Whole document tree
CmdSynopsis
Description
Synopsis for a Command. A CmdSynopsis contains any number of Args and Groups, in any order, followed by a single required Command, another set of any number of Args and Groups, in any order, and ending with any number of optional SynopFragments. CmdSynopsis has common, Label, and Sepchar attributes.
An argument at the command level (Arg) is a parameter passed to a command to specify or modify the command's behavior; it often consists of a variable value (Replaceable) such as a filename field, or an option (Option) and its own nested argument (Arg). If the contents of an argument are not marked up further, they are assumed to be something the user must type as shown (probably an Option, but this is implicit). The Choice attribute on the two argument elements indicates whether the argument must be present ("Req", the default), whether it is optional ("Opt"), or whether no indication of presence is given ("Plain", the default).
A group (Group) as a peer or child of an argument is a collection of arguments, options, or other constructs that must appear in some relation to each other. For example, three options that are exclusive of each other and are optional would be in a group with a choice of "Opt" (the default). The "Optmult" choice allows zero or more of the children of the group to be supplied, and the "Reqmult" choice requires one or more of the children of the group to be supplied.
An option (Option) is a literal string or name of a parameter-keyword controlling the behavior of the command; a variable value (Replaceable) is a mnemonic name for a value that the user must supply, such as an input file name. The Option and Replaceable elements are available in text as well as in synopses. Stacks of options (for example, "-aefstuv") should be put into a single Option element for simplicity.
Depressingly complex constructs may appear anywhere within a synopsis. A SynopFragment reference (SynopFragmentRef) is a special kind of variable value assigned in place of this construct, which is then broken out into its own synopsis subset (SynopFragment) for clarity. A SynopFragment must have an ID, and any SynopFragmentRefs supplied must point to some SynopFragment.
Plain text within a CmdSynopsis is allowed only inside Cmd, Arg, Option, Replaceable, and SynopFragmentRef. The top-level separator character attribute value (" " by default) should be used to separate arguments and groups from their repeat indicators ("…") and to separate Commands and their arguments and groups at the top level.
The CmdSynopsis structure does not meet the needs of DCL and other VMS-related command languages that have command parameters such as /[NO]WRITE, positional versus nonpositional parameters, and so on. Probably additional low-level elements would have to be added to the mix and the top-level structure enhanced slightly to account for these. However, CmdSynopsis appears to meet most UNIX-related needs.
Processing Expectations
The "Opt" settings on arguments and groups (and probably "Optmult" as well for now) should produce square brackets. The "Req" settings (and probably "Reqmult" as well for now) should produce curly braces. The children of Group (if there is more than one child) should be either separated by vertical bars or formatted as a stacked list. Spacing at the Command and Group levels is controlled by formatter defaults and/or the sepchar setting.
Parents
These elements contain CmdSynopsis: Appendix, Application, Article, Attribution, BiblioDiv, BiblioMisc, Bibliography, BlockQuote, Callout, Caution, Chapter, Citation, CiteTitle, Comment, Emphasis, Example, Figure, Footnote, ForeignPhrase, GlossDef, GlossDiv, GlossSee, GlossSeeAlso, GlossTerm, Glossary, Important, Index, IndexDiv, InformalExample, LineAnnotation, Link, ListItem, LiteralLayout, LoTentry, Member, MsgAud, MsgExplan, MsgText, Note, OLink, Para, PartIntro, Phrase, Preface, Procedure, ProductName, ProgramListing, Quote, RefEntryTitle, RefSect1, RefSect2, RefSect3, RefSynopsisDiv, Screen, ScreenInfo, Sect1, Sect2, Sect3, Sect4, Sect5, Seg, SetIndex, Sidebar, SimPara, SimpleSect, Step, Synopsis, Term, Tip, ToCback, ToCentry, ToCfront, ULink, Warning, entry.
Children
CmdSynopsis contains these elements: Arg, Command, Group, SBR, SynopFragment.
In some contexts, additional elements may be allowed by inclusions in parent elements. Similarly, in some contexts, some of these elements may be invalid due to exclusions in parent elements.
Attributes
- Label
Label holds an identifying number or string to be output in some manner when the element it is applied to is rendered.
- Sepchar
Sepchar is the character that should separate command and all top-level arguments in a CmdSynopsis. The default is a space.
Examples
<CMDSYNOPSIS> <COMMAND>adepted.exe</COMMAND> <ARG>-c '<REPLACEABLE>commandlist</REPLACEABLE>'</ARG> <ARG>-C '<REPLACEABLE>commandlist</REPLACEABLE>'</ARG> <ARG>-cc</ARG> <ARG>-fosi <REPLACEABLE>name</REPLACEABLE></ARG> <ARG>-h</ARG><ARG>-n'<REPLACEABLE>type</REPLACEABLE>'</ARG> <ARG>-nocmd</ARG> <ARG>-nocc</ARG> <ARG>-q</ARG> <ARG>-r</ARG> <ARG>-sample</ARG> <ARG>-subtype '<REPLACEABLE>typename</REPLACEABLE>'</ARG> <ARG>-u</ARG> <arg choice="plain"><REPLACEABLE>docname</REPLACEABLE></ARG> </CMDSYNOPSIS>