Re: [docbook] man page: long and short opts

["John L. Clark" <jlc6@po.cwru.edu>]

On Thu, Jun 17, 2004 at 12:37:23PM +0200, Tobias Reif wrote:
> In a man page I have:
> 
> <refentry>
>   <!-- ... -->
>   <refsect1>
>     <title>Options</title>
>     <variablelist>
>       <!-- ... -->
>       <varlistentry>
>         <term><option>--prompt</option> <replaceable>string</replaceable></term>
>         <listitem>
>           <simpara>Use <replaceable>string</replaceable> as prompt in
>           command mode.</simpara>
>         </listitem>
>       </varlistentry>
> 
> --prompt can also be supplied as -p; how would I best mark this up?
> 
> Any other suggestions?

Conveniently, the varlistentry element has a content model which allows
for an arbitrary number of terms; I have used this for essentially the
same purpose - in describing both long and short options:

    <varlistentry>
      <term><option>-t</option> <replaceable>name</replaceable></term>
      <term><option>--top=</option><replaceable>name</replaceable></term>
      <listitem>
        <para>Specify the name of the root fragment to use to tangle the source; the default is "top".</para>
      </listitem>
    </varlistentry>

I think the point here is that a varlistentry maps any number of
equivalent, abstract "terms" to their common description, which fits the
use here precisely.

Take care,

    John L. Clark

PGP signature