<RefEntry ID="dbre.elem.CmdSynopsis">
<!-- Created by DTDParseRefentry version 0.94 -->
<!-- Consult http://www.ora.com/homepages/dtdparse/ -->
<!-- for more information. -->

<![ %dbre.ms.refmeta [
<RefMeta>
<IndexTerm><Primary>CmdSynopsis Element</Primary></IndexTerm>
<RefEntryTitle>CmdSynopsis</RefEntryTitle>
<RefMiscInfo>Element</RefMiscInfo>
</RefMeta>
]]>

<RefNameDiv>
<RefName>CmdSynopsis</RefName>
<RefPurpose>
Synopsis for a Command
</RefPurpose>
</RefNameDiv>

<![ %dbre.ms.refsynopsisdiv [
<RefSynopsisDiv><Title>Content Model</Title>
<Synopsis>
  (<Link LinkEnd="dbre.elem.Command">Command</Link> | <Link LinkEnd="dbre.elem.Arg">Arg</Link> | <Link LinkEnd="dbre.elem.Group">Group</Link> | <Link LinkEnd="dbre.elem.SBR">SBR</Link>)+,
  <Link LinkEnd="dbre.elem.SynopFragment">SynopFragment</Link>*
</Synopsis>

<![ %dbre.ms.refsynopsisdiv.attr [
<RefSect2><Title>Attributes</Title>
<Para>
This element has <link linkend="dbre.x.common">common</link> and <link linkend="dbre.x.role"><sgmltag class=attribute>Role</></link> attributes.
</Para>
<INFORMALTABLE>
<TGROUP COLS=4>
<COLSPEC COLNUM=2 COLNAME=C2>
<COLSPEC COLNUM=4 COLNAME=C4>
<SPANSPEC SPANNAME=C2C4 NAMEST=C2 NAMEEND=C4>
<THEAD>
<ROW>
  <ENTRY>Name</ENTRY>
  <ENTRY>Value(s)</ENTRY>
  <ENTRY>Type</ENTRY>
  <ENTRY>Default Value</ENTRY>
</ROW>
</THEAD>
<TBODY>
<ROW>
  <ENTRY>Label</ENTRY>
  <ENTRY>CDATA</ENTRY>
  <ENTRY>#IMPLIED</ENTRY>
  <ENTRY>&nbsp;</ENTRY>
</ROW>
<ROW>
  <ENTRY>Sepchar</ENTRY>
  <ENTRY>CDATA</ENTRY>
  <ENTRY>&nbsp;</ENTRY>
  <ENTRY>" "</ENTRY>
</ROW>
</TBODY>

</TGROUP>

</INFORMALTABLE>

</RefSect2>
]]>

<![ %dbre.ms.refsynopsisdiv.tagmin [
<RefSect2><Title>Tag Minimization</Title>
<Para>
Both the start- and end-tags are required for this element.
</Para>
</RefSect2>
]]>

</RefSynopsisDiv>
]]>

<![ %dbre.ms.description [
<RefSect1><Title>Description</Title>
<para>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.  
</para>
<para>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). 
</para>
<para>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.
</para>
<para>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.
</para>
<para>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. 
</para>
<para>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 ("&hellip;") and
to separate Commands and their arguments and groups at the top level.
</para>
<para>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.
</para>
<refsect2 id="dbreproc"><title>Processing Expectations</title>
<para>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. 
</para>
</refsect2> 


<![ %dbre.ms.description.parents [
<RefSect2><Title>Parents</Title>
<Para>
These elements contain CmdSynopsis:
<SimpleList Type=Inline>
<Member><Link LinkEnd="dbre.elem.Appendix">Appendix</Link></Member>
<Member><Link LinkEnd="dbre.elem.Application">Application</Link></Member>
<Member><Link LinkEnd="dbre.elem.Article">Article</Link></Member>
<Member><Link LinkEnd="dbre.elem.Attribution">Attribution</Link></Member>
<Member><Link LinkEnd="dbre.elem.BiblioDiv">BiblioDiv</Link></Member>
<Member><Link LinkEnd="dbre.elem.BiblioMisc">BiblioMisc</Link></Member>
<Member><Link LinkEnd="dbre.elem.Bibliography">Bibliography</Link></Member>
<Member><Link LinkEnd="dbre.elem.BlockQuote">BlockQuote</Link></Member>
<Member><Link LinkEnd="dbre.elem.Callout">Callout</Link></Member>
<Member><Link LinkEnd="dbre.elem.Caution">Caution</Link></Member>
<Member><Link LinkEnd="dbre.elem.Chapter">Chapter</Link></Member>
<Member><Link LinkEnd="dbre.elem.Citation">Citation</Link></Member>
<Member><Link LinkEnd="dbre.elem.CiteTitle">CiteTitle</Link></Member>
<Member><Link LinkEnd="dbre.elem.Comment">Comment</Link></Member>
<Member><Link LinkEnd="dbre.elem.Emphasis">Emphasis</Link></Member>
<Member><Link LinkEnd="dbre.elem.Example">Example</Link></Member>
<Member><Link LinkEnd="dbre.elem.Figure">Figure</Link></Member>
<Member><Link LinkEnd="dbre.elem.Footnote">Footnote</Link></Member>
<Member><Link LinkEnd="dbre.elem.ForeignPhrase">ForeignPhrase</Link></Member>
<Member><Link LinkEnd="dbre.elem.GlossDef">GlossDef</Link></Member>
<Member><Link LinkEnd="dbre.elem.GlossDiv">GlossDiv</Link></Member>
<Member><Link LinkEnd="dbre.elem.GlossSee">GlossSee</Link></Member>
<Member><Link LinkEnd="dbre.elem.GlossSeeAlso">GlossSeeAlso</Link></Member>
<Member><Link LinkEnd="dbre.elem.GlossTerm">GlossTerm</Link></Member>
<Member><Link LinkEnd="dbre.elem.Glossary">Glossary</Link></Member>
<Member><Link LinkEnd="dbre.elem.Important">Important</Link></Member>
<Member><Link LinkEnd="dbre.elem.Index">Index</Link></Member>
<Member><Link LinkEnd="dbre.elem.IndexDiv">IndexDiv</Link></Member>
<Member><Link LinkEnd="dbre.elem.InformalExample">InformalExample</Link></Member>
<Member><Link LinkEnd="dbre.elem.LineAnnotation">LineAnnotation</Link></Member>
<Member><Link LinkEnd="dbre.elem.Link">Link</Link></Member>
<Member><Link LinkEnd="dbre.elem.ListItem">ListItem</Link></Member>
<Member><Link LinkEnd="dbre.elem.LiteralLayout">LiteralLayout</Link></Member>
<Member><Link LinkEnd="dbre.elem.LoTentry">LoTentry</Link></Member>
<Member><Link LinkEnd="dbre.elem.Member">Member</Link></Member>
<Member><Link LinkEnd="dbre.elem.MsgAud">MsgAud</Link></Member>
<Member><Link LinkEnd="dbre.elem.MsgExplan">MsgExplan</Link></Member>
<Member><Link LinkEnd="dbre.elem.MsgText">MsgText</Link></Member>
<Member><Link LinkEnd="dbre.elem.Note">Note</Link></Member>
<Member><Link LinkEnd="dbre.elem.OLink">OLink</Link></Member>
<Member><Link LinkEnd="dbre.elem.Para">Para</Link></Member>
<Member><Link LinkEnd="dbre.elem.PartIntro">PartIntro</Link></Member>
<Member><Link LinkEnd="dbre.elem.Phrase">Phrase</Link></Member>
<Member><Link LinkEnd="dbre.elem.Preface">Preface</Link></Member>
<Member><Link LinkEnd="dbre.elem.Procedure">Procedure</Link></Member>
<Member><Link LinkEnd="dbre.elem.ProductName">ProductName</Link></Member>
<Member><Link LinkEnd="dbre.elem.ProgramListing">ProgramListing</Link></Member>
<Member><Link LinkEnd="dbre.elem.Quote">Quote</Link></Member>
<Member><Link LinkEnd="dbre.elem.RefEntryTitle">RefEntryTitle</Link></Member>
<Member><Link LinkEnd="dbre.elem.RefSect1">RefSect1</Link></Member>
<Member><Link LinkEnd="dbre.elem.RefSect2">RefSect2</Link></Member>
<Member><Link LinkEnd="dbre.elem.RefSect3">RefSect3</Link></Member>
<Member><Link LinkEnd="dbre.elem.RefSynopsisDiv">RefSynopsisDiv</Link></Member>
<Member><Link LinkEnd="dbre.elem.Screen">Screen</Link></Member>
<Member><Link LinkEnd="dbre.elem.ScreenInfo">ScreenInfo</Link></Member>
<Member><Link LinkEnd="dbre.elem.Sect1">Sect1</Link></Member>
<Member><Link LinkEnd="dbre.elem.Sect2">Sect2</Link></Member>
<Member><Link LinkEnd="dbre.elem.Sect3">Sect3</Link></Member>
<Member><Link LinkEnd="dbre.elem.Sect4">Sect4</Link></Member>
<Member><Link LinkEnd="dbre.elem.Sect5">Sect5</Link></Member>
<Member><Link LinkEnd="dbre.elem.Seg">Seg</Link></Member>
<Member><Link LinkEnd="dbre.elem.SetIndex">SetIndex</Link></Member>
<Member><Link LinkEnd="dbre.elem.Sidebar">Sidebar</Link></Member>
<Member><Link LinkEnd="dbre.elem.SimPara">SimPara</Link></Member>
<Member><Link LinkEnd="dbre.elem.SimpleSect">SimpleSect</Link></Member>
<Member><Link LinkEnd="dbre.elem.Step">Step</Link></Member>
<Member><Link LinkEnd="dbre.elem.Synopsis">Synopsis</Link></Member>
<Member><Link LinkEnd="dbre.elem.Term">Term</Link></Member>
<Member><Link LinkEnd="dbre.elem.Tip">Tip</Link></Member>
<Member><Link LinkEnd="dbre.elem.ToCback">ToCback</Link></Member>
<Member><Link LinkEnd="dbre.elem.ToCentry">ToCentry</Link></Member>
<Member><Link LinkEnd="dbre.elem.ToCfront">ToCfront</Link></Member>
<Member><Link LinkEnd="dbre.elem.ULink">ULink</Link></Member>
<Member><Link LinkEnd="dbre.elem.Warning">Warning</Link></Member>
<Member><Link LinkEnd="dbre.elem.entry">entry</Link></Member>
</SimpleList>.
</Para>

</RefSect2>
]]>

<![ %dbre.ms.description.children [
<RefSect2><Title>Children</Title>
<Para>
CmdSynopsis contains these elements:
<SimpleList Type=Inline>
<Member><Link LinkEnd="dbre.elem.Arg">Arg</Link></Member>
<Member><Link LinkEnd="dbre.elem.Command">Command</Link></Member>
<Member><Link LinkEnd="dbre.elem.Group">Group</Link></Member>
<Member><Link LinkEnd="dbre.elem.SBR">SBR</Link></Member>
<Member><Link LinkEnd="dbre.elem.SynopFragment">SynopFragment</Link></Member>
</SimpleList>.
</Para>

<Para>
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.
</Para>
</RefSect2>
]]>


</RefSect1>
]]>

<![ %dbre.ms.attrdesc [
<RefSect1><Title>Attributes</Title>

<variablelist>
<varlistentry><term>Label</term>
<listitem>
<para>
Label holds an identifying number 
or string to be output in some manner
when the element it is applied to is rendered.

</para>
</listitem>
</varlistentry>
<varlistentry><term>Sepchar</term>
<listitem>
<para>
Sepchar is the character that should separate command and
all top-level arguments in a CmdSynopsis.  The default is a space.

</para>
</listitem>
</varlistentry>
</variablelist>
</RefSect1>
]]>

<![ %dbre.ms.examples [
<RefSect1><Title>Examples</Title>
<programlisting>
<![ CDATA [
<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>
]]>
</programlisting>

</RefSect1>
]]>

</RefEntry>