Re: [docbook-apps] Docbook man page: Both short and long option alternative example?

[Thomas Schraitle <tom_schr@web.de>]

Hi Dan,

Am Mittwoch, 18. Juli 2012, 14:06:44 schrieb Dan Shelton:
> [...] 
> > I guess, this is one of many options you describe?
> 
> Yes, the full list is this:
> 
> Usage: mkdir [ options ] directory ...
> OPTIONS
> [...]
> > In that case you could use variablelist:
> [...]
> Thank you! :)

Not a problem. :)

By the way, you *could* extend your variablelist with a title like this:

 <variablelist>
   <title>Available Options for <command>mkdir</command> Command</title>
   <varlistentry>
   <!-- rest omitted -->

But you are not forced to do this. Sometimes it's nice to have a title before 
the list starts.


> Next question:
> How do describe an option in Docbook which optionally takes an
> argument, e.g. like this one:
> 
>   -D, --all-repeated[=delimit]

Well, guess! ;-) 
Yes, you are right: there is an optional element in DocBook.

 <varlistentry>
  <term><option>--all-repeated</option><optional>=delimit</optional></term>
  <listitem>
    <para>Output all duplicate lines as a group with an empty
         line delimiter specified by delimit: [...]</para>
  </listitem>
 </varlistentry>

You could also move the optional element /inside/ the option element. Depends 
on which notation you prefer.

If you transform the above structure with the DocBook stylesheets into 
(X)HTML, you will end up with =delimiter in brackets. So no need to add 
additional brackets.

If you need more information on variablelist and other list elements, look 
here: http://doccookbook.sf.net/html/en/dbc.markup.lists.html


-- 
Gruß/Regards
  Thomas Schraitle