Write man page for stc tool

... and rearrange the man page for stc.conf a bit.

Signed-off-by: David Zeuthen <davidz@redhat.com>

2 files changed, 202 insertions, 21 deletions

diff --git a/doc/stc.conf.xml b/doc/stc.conf.xml
index e224b90..1418e54 100644
--- a/doc/stc.conf.xml
+++ b/doc/stc.conf.xml
@@ -27,19 +27,12 @@
     The <filename>/etc/stc.conf</filename> and
     <filename>/etc/stc.conf.d/*.conf</filename> files contain
     descriptive information about various file systems and
-    devices. These configuration files, collectively, contains a set
-    of <emphasis>storage items</emphasis>. Each storage item describes
+    devices. These configuration files contains a set of
+    <emphasis>storage items</emphasis>. Each storage item describes
     how to mount a filesystem, how to assemble a RAID array, how to
-    unlock a encrypted device, how to activate a LVM Volume Group and so
-    on.
-  </para>
-  <para>
-    An item can either be running or not running. For example, for a
-    filesystem this corresponds to whether it is mounted in the
-    configured location or not. Similarly, for a RAID array it conveys
-    whether the RAID is currently assembled or not. Additionally,
-    items can depend on each other. This allows handling complex
-    inter-subsystem storage trees such as:
+    unlock a encrypted device, how to activate a LVM Volume Group and
+    so on. Additionally, items can depend on each other. This allows
+    handling complex inter-subsystem storage trees such as:
   </para>
 <programlisting>
                    Filesystem
@@ -65,12 +58,17 @@ MyData_LV_PV1     MyData_LV_PV2         MyData_LV_PV3
     <literal>MyData_LV_PV1</literal>, <literal>MyData_LV_PV2</literal>
     and <literal>MyData_LV_PV3</literal> (that each happen to be on
     two disks each). Given this level of information, it is possible
-    to start/stop all involved devices by simply running these two commands
+    to start/stop all involved devices by running a simple command
+    referencing the <literal>MyData</literal> item.
+  </para>
+  <para>
+    The
+    <citerefentry><refentrytitle>stc</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+    command can be used to start/stop/enumerate items as well as
+    inquire about the current item state. The configuration file
+    format is intentionally extensible – item types to support
+    emerging storage subsystems may be added in the future.
   </para>
-<programlisting>
-# stc start --id MyData
-# stc stop --id MyData
-</programlisting>
 </refsect1>
 
 <refsect1>
@@ -101,6 +99,10 @@ FilesystemMountPath=/mnt/somewhere
     mounted at <filename>/mnt/somewhere</filename>.
   </para>
   <para>
+    Identifiers can only contain alphanumeric characters as well as
+    underscores (<literal>[a-zA-Z0-9_]</literal>).
+  </para>
+  <para>
     The order of entries is defined as follows: First, all files are
     sorted and processed in lexical order (in the C locale) and for
     each file, items appear in the order they are declared. If two
@@ -109,6 +111,7 @@ FilesystemMountPath=/mnt/somewhere
   <para>
     Each item supports the following keys:
   </para>
+
   <variablelist>
     <varlistentry>
       <term><literal>Device, Label, UUID, Name</literal></term>
@@ -142,6 +145,7 @@ FilesystemMountPath=/mnt/somewhere
       </listitem>
     </varlistentry>
   </variablelist>
+
   <para>
     Additionally, items can have type-specific keys. See each item
     type for details.
@@ -178,7 +182,7 @@ FilesystemMountPath=/mnt/id1
 UUID=4e057fd9-bae5-4a12-83b5-2f654d42edb1
 FilesystemMountPath=/mnt/id2
 
-# Mount by device (in this case, a persistent device name provided by udev(7))
+# Mount by device (in this case, a persistent device name)
 #
 [Filesystem id3]
 Device=/dev/disk/by-path/pci-0000:00:1f.2-scsi-0:0:0:0-part1
@@ -236,8 +240,10 @@ LuksPassphrase=xyz123
 LuksMappingName=sekrit
 
 # Example of a Filesystem item that depends on the Luks item above.
-# This way the Luks device and the Filesystem will be unlocked/mounted
-# respectively locked/unmounted in tandem when running stc(1).
+#
+# This way the Luks device and the Filesystem will be
+# unlocked/mounted respectively locked/unmounted in
+# tandem when running stc(1).
 #
 [Filesystem sekrit]
 UUID=9639-06F4
diff --git a/doc/stc.xml b/doc/stc.xml
index b9f9a17..471374d 100644
--- a/doc/stc.xml
+++ b/doc/stc.xml
@@ -13,13 +13,188 @@
 <refsynopsisdiv>
   <cmdsynopsis>
     <command>stc</command>
+    <arg choice="plain">start</arg>
+    <arg choice="plain">--id <replaceable>item_identifier</replaceable></arg>
+    <group>
+      <arg choice="plain">--allow-degraded</arg>
+    </group>
+  </cmdsynopsis>
+
+  <cmdsynopsis>
+    <command>stc</command>
+    <arg choice="plain">stop</arg>
+    <arg choice="plain">--id <replaceable>item_identifier</replaceable></arg>
+  </cmdsynopsis>
+
+  <cmdsynopsis>
+    <command>stc</command>
+    <arg choice="plain">list</arg>
+  </cmdsynopsis>
+
+  <cmdsynopsis>
+    <command>stc</command>
+    <arg choice="plain">help</arg>
   </cmdsynopsis>
 </refsynopsisdiv>
 
 <refsect1>
   <title>Description</title>
   <para>
-    <command>stc</command> is TODO.
+    The <command>stc</command> command serves to inspect, start and
+    stop storage items defined in the configuration files mentioned in
+    <citerefentry><refentrytitle>stc.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
+  </para>
+</refsect1>
+
+<refsect1>
+  <title>Verbs</title>
+  <para>
+    <command>stc</command> support the following verbs:
+  </para>
+
+  <variablelist>
+
+    <varlistentry>
+      <term><option>list</option></term>
+      <listitem>
+        <para>
+          Prints out all detected storage items and the state (see
+          <xref linkend="stc-tool-item-states"/>) for each item. Any
+          error or warning that occured during parsing configuration
+          files is also reported.
+        </para>
+      </listitem>
+    </varlistentry>
+
+    <varlistentry>
+      <term>
+        <option>start</option>
+      </term>
+      <listitem>
+        <para>
+          Starts the item with identifier
+          <replaceable>item_identifier</replaceable>. If information
+          is needed to do so (e.g. obtaining passphrases or verifying
+          that it is OK to start an item in degraded mode) and the
+          program is connected to a terminal emulator, then the user
+          is asked for this information. If the
+          <option>--allow-degraded</option> is passed then all
+          questions about whether an item can be started degraded is
+          answered in the affirmative.
+        </para>
+      </listitem>
+    </varlistentry>
+
+    <varlistentry>
+      <term>
+        <option>stop</option>
+      </term>
+      <listitem>
+        <para>
+          Stops the item with identifier
+          <replaceable>item_identifier</replaceable>.
+        </para>
+      </listitem>
+    </varlistentry>
+
+    <varlistentry>
+      <term><option>help</option></term>
+      <listitem><para>
+        Prints help and exit.
+      </para></listitem>
+    </varlistentry>
+
+  </variablelist>
+
+</refsect1>
+
+<refsect1 id="stc-tool-item-states">
+  <title>Item states</title>
+  <para>
+    A storage item can be in one of the following states:
+  </para>
+
+  <variablelist>
+
+    <varlistentry>
+      <term><literal>not-started</literal></term>
+      <listitem>
+        <para>
+          The device the item (or one of its dependencies) is
+          referencing has not been started. Additionally there is no
+          way to currently start it.
+        </para>
+      </listitem>
+    </varlistentry>
+
+    <varlistentry>
+      <term><literal>can-start-degraded</literal></term>
+      <listitem>
+        <para>
+          The device the item (or one of its dependencies) is
+          referencing can be started in a degraded mode.
+        </para>
+      </listitem>
+    </varlistentry>
+
+    <varlistentry>
+      <term><literal>can-start</literal></term>
+      <listitem>
+        <para>
+          The device the item (or one of its dependencies) is
+          referencing can be started.
+        </para>
+      </listitem>
+    </varlistentry>
+
+    <varlistentry>
+      <term><literal>started</literal></term>
+      <listitem>
+        <para>
+          The device the item is referencing has started and is
+          running.
+        </para>
+      </listitem>
+    </varlistentry>
+
+    <varlistentry>
+      <term><literal>defunct</literal></term>
+      <listitem>
+        <para>
+          The device the item is referencing has been started but the
+          device the item (or one of its dependencies) is referencing
+          has disappeared in the meantime.
+        </para>
+        <para>
+        </para>
+      </listitem>
+    </varlistentry>
+
+  </variablelist>
+
+  <para>
+    An example of the <literal>can-start-degraded</literal> is when
+    only half of the mirror for a RAID array is available.  An example
+    of the <literal>defunct</literal> state is when the device backing
+    a filesystem is yanked or if a sufficient number of RAID
+    components for a RAID array has failed.
+  </para>
+
+</refsect1>
+
+<refsect1>
+  <title>Return Codes</title>
+  <para>
+    <command>stc</command> returns zero if the operation succeded and
+    non-zero otherwise.
+  </para>
+</refsect1>
+
+<refsect1>
+  <title>bash Completion</title>
+  <para>
+    <command>stc</command> ships with a bash completion script to
+    complete commands, options and item identifiers.
   </para>
 </refsect1>