Add man pages for nitsi
authorJonatan Schlag <jonatan.schlag@ipfire.org>
Fri, 11 May 2018 12:25:01 +0000 (14:25 +0200)
committerJonatan Schlag <jonatan.schlag@ipfire.org>
Fri, 11 May 2018 12:27:00 +0000 (14:27 +0200)
Fixes: #11722

Signed-off-by: Jonatan Schlag <jonatan.schlag@ipfire.org>
Makefile.am
man/custom-html.xsl [new file with mode: 0644]
man/nitsi.recipe.xml [new file with mode: 0644]
man/nitsi.settings.xml [new file with mode: 0644]
man/nitsi.xml [new file with mode: 0644]

index 689b61e..8562842 100644 (file)
@@ -48,7 +48,9 @@ man: $(MANPAGES) $(MANPAGES_HTML)
 
 if ENABLE_MANPAGES
 MANPAGES = \
-       man/nitsi.1
+       man/nitsi.1 \
+       man/nitsi.settings.1 \
+       man/nitsi.recipe.1
 
 MANPAGES_XML  = $(patsubst %.1,%.xml,$(patsubst %.5,%.xml,$(MANPAGES)))
 MANPAGES_HTML = $(patsubst %.xml,%.html,$(MANPAGES_XML))
diff --git a/man/custom-html.xsl b/man/custom-html.xsl
new file mode 100644 (file)
index 0000000..fe2b54e
--- /dev/null
@@ -0,0 +1,31 @@
+<?xml version='1.0'?>
+
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
+
+<xsl:import href="http://docbook.sourceforge.net/release/xsl/current/html/docbook.xsl"/>
+
+<!-- translate man page references to links to html pages -->
+<xsl:template match="citerefentry">
+  <a>
+    <xsl:attribute name="href">
+      <xsl:value-of select="refentrytitle"/><xsl:text>.html</xsl:text>
+    </xsl:attribute>
+    <xsl:call-template name="inline.charseq"/>
+  </a>
+</xsl:template>
+
+<!-- add Index link at top of page -->
+<xsl:template name="user.header.content">
+  <a>
+    <xsl:attribute name="href">
+      <xsl:text>index.html</xsl:text>
+    </xsl:attribute>
+    <xsl:text>Index</xsl:text>
+  </a>
+  <hr/>
+</xsl:template>
+
+<!-- Switch things to UTF-8, ISO-8859-1 is soo yesteryear -->
+<xsl:output method="html" encoding="UTF-8" indent="no"/>
+
+</xsl:stylesheet>
diff --git a/man/nitsi.recipe.xml b/man/nitsi.recipe.xml
new file mode 100644 (file)
index 0000000..91925d4
--- /dev/null
@@ -0,0 +1,164 @@
+<?xml version="1.0"?>
+<!DOCTYPE refentry PUBLIC "-//OASIS/DTD DocBook XML V4.2//EN"
+       "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<refentry id="nitsi.recipe">
+       <refentryinfo>
+               <title>nitsi.recipe</title>
+               <productname>nitsi</productname>
+
+               <authorgroup>
+                       <author>
+                               <contrib>Developer</contrib>
+                               <firstname>Jonatan</firstname>
+                               <surname>Schlag</surname>
+                               <email>jonatan.schlag@ipfire.org</email>
+                       </author>
+               </authorgroup>
+       </refentryinfo>
+
+       <refmeta>
+               <refentrytitle>nitsi.recipe</refentrytitle>
+               <manvolnum>1</manvolnum>
+       </refmeta>
+
+       <refnamediv>
+               <refname>nitsi.recipe</refname>
+               <refpurpose>Recipe file for a nitsi test</refpurpose>
+       </refnamediv>
+
+
+       <refsect1>
+               <title>Description</title>
+
+               <para>
+                       The <filename>recipe</filename> file contains the actions for a test.
+                       So it consist of lines which state which command should executed on which machine.
+               </para>
+       </refsect1>
+
+       <refsect1>
+               <title>Basic Syntax</title>
+
+               <para>
+                       All lines follows the following syntax:
+               </para>
+
+               <variablelist>
+                       <varlistentry>
+                               <term>
+                                       <option>machine: command</option>
+                               </term>
+
+                               <listitem>
+                                       <para>
+                                               The machine name is the first part of the line followed by an ':'.
+                                               After the ':' follows the command which should be executed.
+                                       </para>
+
+                               </listitem>
+                       </varlistentry>
+               </variablelist>
+       </refsect1>
+
+       <refsect1>
+               <title>Extended Syntax</title>
+
+               <para>
+                       The following syntax examples shows how you could solve common problems.
+               </para>
+
+               <variablelist>
+                       <varlistentry>
+                               <term>
+                                       <option>machine !: command</option>
+                               </term>
+
+                               <listitem>
+                                       <para>
+                                               The '!' is similar to the 'not' in python. So this line will fail if the command succeds
+                                               and succeds if the command fails. Between the machine name and the '!' must be a space.
+                                       </para>
+
+                               </listitem>
+                       </varlistentry>
+
+                       <varlistentry>
+                               <term>
+                                       <option>all: command</option>
+                               </term>
+
+                               <listitem>
+                                       <para>
+                                               This command is executed on all machines of this test.
+                                       </para>
+
+                               </listitem>
+                       </varlistentry>
+                       <varlistentry>
+                               <term>
+                                       <option>machine1,machine2: command</option>
+                               </term>
+
+                               <listitem>
+                                       <para>
+                                               This command is on all machines of the comma seperated list. So on machine1 and on machine2.
+                                       </para>
+
+                               </listitem>
+                       </varlistentry>
+
+                                               <varlistentry>
+                               <term>
+                                       <option>include: ../test2</option>
+                               </term>
+
+                               <listitem>
+                                       <para>
+                                               This will include the recipe of test2.
+                                               The path is relativ to the directory of the recipe file which contain the include statement.
+                                       </para>
+
+                               </listitem>
+                       </varlistentry>
+
+               </variablelist>
+       </refsect1>
+
+       <refsect1>
+               <title>Example</title>
+
+               <example>
+
+                       <simplelist>
+                               <member>alice: echo "Hello World"</member>
+                               <member>bob !: eecho "Hello World"</member>
+                               <member>alice: ls -l</member>
+                               <member>all: blkid</member>
+                               <member>alice,bob: echo "This is a comma seperated list"</member>
+                               <member>include: ../test2</member>
+                       </simplelist>
+               </example>
+
+       </refsect1>
+
+       <refsect1>
+               <title>Bugs</title>
+
+               <para>
+                       Please report all bugs to the official bugtracker at
+                       http://bugzilla.ipfire.org/.
+               </para>
+       </refsect1>
+
+       <refsect1>
+               <title>See Also</title>
+
+               <para>
+                       <citerefentry>
+                               <refentrytitle>nitsi</refentrytitle>
+                               <manvolnum>1</manvolnum>
+                       </citerefentry>
+               </para>
+       </refsect1>
+</refentry>
diff --git a/man/nitsi.settings.xml b/man/nitsi.settings.xml
new file mode 100644 (file)
index 0000000..680a5c0
--- /dev/null
@@ -0,0 +1,190 @@
+<?xml version="1.0"?>
+<!DOCTYPE refentry PUBLIC "-//OASIS/DTD DocBook XML V4.2//EN"
+       "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<refentry id="nitsi.setting">
+       <refentryinfo>
+               <title>nitsi.settings</title>
+               <productname>nitsi.settings</productname>
+
+               <authorgroup>
+                       <author>
+                               <contrib>Developer</contrib>
+                               <firstname>Jonatan</firstname>
+                               <surname>Schlag</surname>
+                               <email>jonatan.schlag@ipfire.org</email>
+                       </author>
+               </authorgroup>
+       </refentryinfo>
+
+       <refmeta>
+               <refentrytitle>nitsi.settings</refentrytitle>
+               <manvolnum>1</manvolnum>
+       </refmeta>
+
+       <refnamediv>
+               <refname>nitsi.settings</refname>
+               <refpurpose>Settings file for a nitsi test</refpurpose>
+       </refnamediv>
+
+
+       <refsect1>
+               <title>Description</title>
+
+               <para>
+                       The <filename>settings</filename> file is the main configuration file of the
+                       <command>nitsi</command> test.
+                       This file specifies runtime configuration parameters for the test
+                       and set the virtual environment to use.
+               </para>
+
+               <para>
+                       The syntax of the configuration file is based on the INI configuration
+                       file format. Lines starting with hash (#) or semi-colon (;)
+                       are ignored.
+               </para>
+       </refsect1>
+
+       <refsect1>
+               <title>DEFAULT configuration</title>
+
+               <para>
+                       The following options can be configured in the [DEFAULT] section:
+               </para>
+
+               <variablelist>
+                       <varlistentry>
+                               <term>
+                                       <option>Name = ""</option>
+                               </term>
+
+                               <listitem>
+                                       <para>
+                                               This option will configure the name of the test
+                                               and can be something more human readbale then the name of the test directory.
+                                       </para>
+
+                               </listitem>
+                       </varlistentry>
+
+                       <varlistentry>
+                               <term>
+                                       <option>Description = ""</option>
+                               </term>
+
+                               <listitem>
+                                       <para>
+                                               This can be a short description of the test to explain
+                                               what we are trying to test and what results we expect when
+                                               we are running the recipe. So when do the test succeed and when do the test fails.
+                                       </para>
+
+                               </listitem>
+                       </varlistentry>
+
+                       <varlistentry>
+                               <term>
+                                       <option>Copy_from = ""</option>
+                               </term>
+
+                               <listitem>
+                                       <para>
+                                               The files or directories which should be copied into all virtual machines.
+                                               The paths are relativ to the path of the test directory.
+                                       </para>
+
+                               </listitem>
+                       </varlistentry>
+
+                       <varlistentry>
+                               <term>
+                                       <option>Copy_to = ""</option>
+                               </term>
+
+                               <listitem>
+                                       <para>
+                                               The path to which the files should be copied. For example /root/
+                                       </para>
+
+                               </listitem>
+                       </varlistentry>
+
+               </variablelist>
+       </refsect1>
+
+       <refsect1>
+               <title>VIRTUAL_ENVIRONMENT Configuration</title>
+
+               <para>
+                       The following options can be configured in the [VIRTUAL_ENVIRONMENT] section:
+               </para>
+
+               <variablelist>
+                       <varlistentry>
+                               <term>
+                                       <option>Name = ""</option>
+                               </term>
+
+                               <listitem>
+                                       <para>
+                                               The Name of the virtual environment to use.
+                                       </para>
+
+                               </listitem>
+                       </varlistentry>
+
+                                       <varlistentry>
+                               <term>
+                                       <option>path = ""</option>
+                               </term>
+
+                               <listitem>
+                                       <para>
+                                               The path of the virtual environment relativ to the path of the test.
+                                       </para>
+
+                               </listitem>
+                       </varlistentry>
+               </variablelist>
+       </refsect1>
+
+       <refsect1>
+               <title>Example</title>
+
+               <example>
+
+                       <simplelist>
+                               <member>[DEFAULT]</member>
+                               <member>Name = Hello World</member>
+                               <member>Description = This is a
+                               short description.</member>
+                               <member>Copy_from =</member>
+                               <member>Copy_to = /root/</member>
+                               <member>[VIRTUAL_ENVIRONMENT]</member>
+                               <member>Name = basic</member>
+                               <member>path = ../virtual-environment/basic</member>
+                       </simplelist>
+               </example>
+
+       </refsect1>
+
+       <refsect1>
+               <title>Bugs</title>
+
+               <para>
+                       Please report all bugs to the official bugtracker at
+                       http://bugzilla.ipfire.org/.
+               </para>
+       </refsect1>
+
+       <refsect1>
+               <title>See Also</title>
+
+               <para>
+                       <citerefentry>
+                               <refentrytitle>nitsi</refentrytitle>
+                               <manvolnum>1</manvolnum>
+                       </citerefentry>
+               </para>
+       </refsect1>
+</refentry>
diff --git a/man/nitsi.xml b/man/nitsi.xml
new file mode 100644 (file)
index 0000000..5310de6
--- /dev/null
@@ -0,0 +1,124 @@
+<?xml version="1.0"?>
+<!DOCTYPE refentry PUBLIC "-//OASIS/DTD DocBook XML V4.2//EN"
+       "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<refentry id="nitsi">
+       <refentryinfo>
+               <title>nitsi</title>
+               <productname>nitsi</productname>
+
+               <authorgroup>
+                       <author>
+                               <contrib>Developer</contrib>
+                               <firstname>Jonatan</firstname>
+                               <surname>Schlag</surname>
+                               <email>jonatan.schlag@ipfire.org</email>
+                       </author>
+               </authorgroup>
+       </refentryinfo>
+
+       <refmeta>
+               <refentrytitle>nitsi</refentrytitle>
+               <manvolnum>1</manvolnum>
+       </refmeta>
+
+       <refnamediv>
+               <refname>nitsi</refname>
+               <refpurpose>Networking Integration Test Suite for IPFire</refpurpose>
+       </refnamediv>
+
+       <refsynopsisdiv>
+               <cmdsynopsis>
+                       <command>nitsi</command>
+                       <arg choice="opt" rep="repeat">OPTIONS</arg>
+                       <arg choice="plain">COMMAND</arg>
+               </cmdsynopsis>
+       </refsynopsisdiv>
+
+       <refsect1>
+               <title>Description</title>
+
+               <para>
+                       <command>nitsi</command> is a simple, extensible, Integration Test Suite
+                               for the Network code of IPfire written in Python.
+               </para>
+       </refsect1>
+
+       <refsect1>
+               <title>Options</title>
+
+               <para>
+                       The following options are understood:
+               </para>
+
+               <variablelist>
+                       <varlistentry>
+                               <term>
+                                       <option>-d DIRECTORY</option>
+                               </term>
+                               <term>
+                                       <option>--directory DIRECTORY</option>
+                               </term>
+
+                               <listitem>
+                                       <para>
+                                               Is the directory where all files of a test are located.
+                                               So this dir should contain at least a setting file and a recipe file
+                                       </para>
+
+                                       <para>
+                                               For further details of the setting file layout and the recipe file layout, please consult the
+                                               <citerefentry>
+                                                       <refentrytitle>nitsi.setting</refentrytitle>
+                                                       <manvolnum>5</manvolnum>
+                                               </citerefentry>
+                                               <citerefentry>
+                                                       <refentrytitle>nitsi.recipe</refentrytitle>
+                                                       <manvolnum>5</manvolnum>
+                                               </citerefentry>
+                                               manual page.
+                                       </para>
+                               </listitem>
+                       </varlistentry>
+
+                       <varlistentry>
+                               <term>
+                                       <option>-h</option>
+                               </term>
+                               <term>
+                                       <option>--help</option>
+                               </term>
+
+                               <listitem>
+                                       <para>
+                                               Shows the help message provided by the program and exit.
+                                       </para>
+                               </listitem>
+                       </varlistentry>
+               </variablelist>
+       </refsect1>
+
+       <refsect1>
+               <title>Bugs</title>
+
+               <para>
+                       Please report all bugs to the official bugtracker at
+                       http://bugzilla.ipfire.org/.
+               </para>
+       </refsect1>
+
+       <refsect1>
+               <title>See Also</title>
+
+               <para>
+                       <citerefentry>
+                               <refentrytitle>nitsi.setting</refentrytitle>
+                               <manvolnum>5</manvolnum>
+                       </citerefentry>
+                       <citerefentry>
+                               <refentrytitle>nitsi.recipe</refentrytitle>
+                               <manvolnum>5</manvolnum>
+                       </citerefentry>
+               </para>
+       </refsect1>
+</refentry>