Docbook discussion

ольга крыжановская | 18 Jul 2012 22:56

Docbook-man: command with sub commands?

I hope this is the right place to ask (after seeing some Docbook man
questions coming through):
How can I express sub commands in Docbook man pages, for example I
like to write a myfs(1M) manual page, where command myfs has several
sub commands:

       myfs create [-s] [-b blocksize] [[-o property=value]]... -V size volume

       myfs destroy [-rRf] filesystem|volume|snapshot

How would the syntax for these 2 look alike?

Olga
--

-- 
      ,   _                                    _   ,
     { \/`o;====-    Olga Kryzhanovska   -====;o`\/ }
.----'-/`-/     olga.kryzhanovska <at> gmail.com   \-`\-'----.
 `'-..-| /       http://twitter.com/fleyta     \ |-..-'`
      /\/\     Solaris/BSD//C/C++ programmer   /\/\
      `--`                                      `--`

headers

Robert Fekete | 19 Jul 2012 08:29

Re: Docbook-man: command with sub commands?

Hi,

in such cases I use separate refsection tags for the subcommands. For the 
options of the subcommand I use the variablelists described in the earlier 
thread. The source looks like:

<refsect1 id="pdbtool_dump">
       <title>The dump command</title>
       <cmdsynopsis>
         <command>dump</command>
         <arg>options</arg>
       </cmdsynopsis>
       <para>Display the RADIX tree built from the patterns. This shows how are 
the patterns represented in syslog-ng and it might also help to track down 
pattern-matching problems. The dump utility can dump the tree used for matching 
the PROGRAM or the MSG parts. </para>
       <variablelist>
         <varlistentry>
           <term><command>--pdb</command> or <command>-p</command></term>
           <listitem>
             <para>Name of the pattern database file to
               use.</para>
           </listitem>
         </varlistentry>
         <varlistentry>
           <term><command>--program</command> or <command>-P</command></term>
           <listitem>
             <para>Displays the RADIX tree built from the patterns belonging to 
the <parameter>$PROGRAM</parameter> application.</para>
           </listitem>

(Continue reading)

headers

Bob Stayton | 19 Jul 2012 18:25

Re: Docbook-man: command with sub commands?

In addition, you can add multiple synopsis lines at the start of the refentry like 
this:

<refentry>
    <refnamediv>
        <refname>myfs</refname>
        <refpurpose>general description of myfs</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
      <synopsis>myfs create <optional>-s</optional> <optional>-b blocksize</optional> 
...
      </synopsis>
      <synopsis>myfs destroy <optional>-rRf</optional> filesystem|volume|snapshot
      </synopsis>
    </refsynopsisdiv>
    ...

The <synopsis> element is a verbatim element, which means it preserves white space and 
line breaks.  That's why the command line in this example starts  just after the start 
tag, to avoid introducing an extra line break that adds vertical space in the output.

Or you could replace each <synopsis> with <cmdsynopsis> which is not verbatim and 
takes additional markup elements like <arg>.  See this refentry reference page for an 
example:

http://www.docbook.org/tdg5/en/html/refentry.html

Bob Stayton
Sagehill Enterprises
bobs <at> sagehill.net

(Continue reading)