[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Command synopsis markup
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>'2007-12-12 00:01:00'</replaceable> --note=<replaceable>'test'</replaceable><option></arg> <sbr/> <filename>userbantool.pl</filename> <arg>--add <option>--what=uniq --value=jd45abcdef1js1jjd --banlength=3d --note='3 day ban'</option></arg> </cmdsynopsis> </informalexample> --
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]