Command synopsis markup

[<techno_plume-mailbox@yahoo.com>]

X-No-Archive: yes

Hi. I'm trying to figure out 'right'/'canonical' way to mark up a
synopsis for long or complex commands or scripts. I couldn't find
anything relevant in the list archives.

The TDG terminology seems to recommend the element 'arg'(uments) to
mark up, say, "-a" on the Unix ls command. Or, if just referring to the
"-a" in prose within a paragraph, then 'option' is used instead. On the
other hand, the KDE project's DocBook-guide uses 'option' inside
'cmdsynopsis', for _almost_ all the (as TDG refers to them)
'arg'(uments). 

The terminology section in Unix IEEE docs on opengroup.org says
"commands" are followed by "options" (historically termed "flags"),
that those "options" may be followed by an "option_argument" (value for
the option presumably), then an "operand". It seems to use the
collective pronoun "arguments" to refer to all of the possible
parameters following "command". Yet more sources commonly refer to
everything following the "command" (and preceded by a symbol like /,-
,--) as "options" and the final parameter (such as a filename) as the
arguments.

I can use one or both of 'option'/'arg' indeterminately. There are
exceptions as 'arg' has attributes to indicate it is optional, whereas
'option' allows the 'optional' child element instead. But then I can
use the 'literal' element everywhere and put 'programlisting' contents
inside cdata containers too :) For option arguments, aka flag values,
aka parameters, etc., it seems I can use 'replaceable' amongst others.
I'd like to follow best practices (if there are any) for all this.

I've tried things like example below (example markup may not be valid).
TDG also describes splitting up longer synopses using synopfragments,
which is another option. For notes like the format for a date option
value I suppose the 'co' element in the main synopsis followed by a
calloutlist with the callout arearefs/id might work?

Can anybody offer tips/advice for what works well when marking up
things like this?

Thanks,

- Richard.

Example command involved:
Usage: userbantool.pl [opts]
--add  --what=? --value=? [--status=? --bandate=datetime {
--banuntil=datetime | --banlength=duration } --note=?]
--list      { --banid=? | or one of: 
            [--what=? --status=? --bandate=datetime --banuntil=datetime
--value=? --note=?] }
* datetime in format 'YYYY-MM-DD HH:MM:SS', duration in format
'N[dhms]' e.g. '5d' or '3h'.
examples:
userbantool.pl --add --what=email --value=demo@example.com
--banuntil='2007-12-12 00:01:00' --note='test'

<cmdsynopsis>
  <command>userbantool.pl</command>
  <arg choice="plain">--list</arg>
    <arg>--banid=<replaceable>id</replaceable>
    <group choice="opt">
        <option>--what=<replaceable>parameter</replaceable></option>
        <option>--status=<replaceable>value</replaceable></option>
        <option>--bandate=<replaceable>datetime</replaceable></option>
        <option>--banuntil=<replaceable>datetime</replaceable></option>
        <option>--value=<replaceable>value</replaceable></option>
       
<option>--note=<optional><replaceable>string</replaceable></optional></option>
    </group>
    </arg>
<sbr/>
  <arg choice="plain">--add</arg>
        <arg
choice="req">--what=<replaceable>parameter</replaceable></arg>
        <arg
choice="req">--value=<replaceable>value</replaceable></arg>
    <group choice="opt">
        <option>--status=<replaceable>value</replaceable></option>
        <option>--bandate=<replaceable>datetime</replaceable></option>
            <arg choice="req">
           
<option>--banuntil=<replaceable>datetime</replaceable></option>
           
<option>--banlength=<replaceable>duration</replaceable></option>
            </arg>
       
<option>--note=<optional><replaceable>string</replaceable></optional></option>
    </group>
<sbr/> ...
    </arg>
</cmdsynopsis>

<informalexample>
    <cmdsynopsis>
        <filename>userbantool.pl</filename> <arg>--list
<option>--what=ip</option>
--value=<replaceable>127.0.0.1</replaceable></option></arg>
    <sbr/>
        <filename>userbantool.pl</filename> <arg>--add
<option>--what=email
--value=<replaceable>demo@example.com</replaceable>
--banuntil=<replaceable>&apos;2007-12-12 00:01:00&apos;</replaceable>
--note=<replaceable>&apos;test&apos;</replaceable><option></arg>
    <sbr/>
        <filename>userbantool.pl</filename> <arg>--add
<option>--what=uniq --value=jd45abcdef1js1jjd --banlength=3d
--note=&apos;3 day ban&apos;</option></arg>
    </cmdsynopsis>
</informalexample>

--