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

[Dan Shelton <dan.f.shelton@gmail.com>]

On 18 July 2012 12:59, Thomas Schraitle <tom_schr@web.de> wrote:
> Hi Dan,
>
> On Wed, 18 Jul 2012 12:05:38 +0200
> Dan Shelton <dan.f.shelton@gmail.com> wrote:
>
>> I need help with the Docbook syntax for manual pages.
>> I'm trying to create a Docbook man page segment for this kind of
>> --help output but fail miserably:
>> -------cut-------
>>   -m, --mode=mode Set the mode of created directories to mode. mode is
>> symbolic or octal mode as in chmod(1). Relative modes assume an
>> initial mode of a=rwx.
>> -------cut-------
>> Can anyone help me and express this in Docbook/XML, please? I'm stuck
>> after 10 hours of trial&error. HELP!
>
> I guess, this is one of many options you describe?

Yes, the full list is this:

Usage: mkdir [ options ] directory ...
OPTIONS
  -m, --mode=mode Set the mode of created directories to mode. mode is
symbolic or octal mode as in chmod(1). Relative modes assume an
initial mode of a=rwx.
  -p, --parents   Create any missing intermediate pathname components.
For each dir operand that does not name an existing directory, effects
equivalent to those caused by the following command shall occur: mkdir
-p -m $(umask -S),u+wx $(dirname dir) && mkdir [-m mode] dir where the
-m mode option represents that option supplied to the original
invocation of mkdir, if any. Each dir operand that names an existing
directory shall be ignored without error.
  -v, --verbose   Print a message on the standard error for each
created directory.

> In that case you
> could use variablelist:
>
>   <variablelist>
>     <varlistentry>
>       <term><option>-m</option></term>
>       <term><option>--mode</option>=<replaceable>mode</replaceable></term>
>       <listitem>
>         <para>Set the mode of created directories to mode. mode is
>             symbolic or octal mode as in <citerefentry>
>               <refentrytitle>chmod</refentrytitle>
>               <manvolnum>1</manvolnum>
>             </citerefentry>. Relative modes assume an initial mode of
>             <literal>a=rwx</literal>.
>         </para>
>       </listitem>
>     </varlistentry>
>     <!-- Add more varlistentrys with the same structure -->
>   </variablelist>
>
> Hope that helps.

Thank you! :)

Next question:
How do describe an option in Docbook which optionally takes an
argument, e.g. like this one:

  -D, --all-repeated[=delimit]
                  Output all duplicate lines as a group with an empty
line delimiter specified by delimit:
                    "none"  Do not delimit duplicate groups.
                    "prepend"
                          Prepend an empty line before each group.
                    "separate"
                          Separate each group with an empty line.
                  The option value may be omitted. The default value is "none".