DocBook: The Definitive Guide By Norman Walsh & Leonard Muellner 1st Edition October 1999 1-56592-580-7, Order Number: 5807 652 pages, $36.95 , Includes CD-ROM

DocBook: The Definitive Guide
Prev		Next

---

CmdSynopsis

Name

CmdSynopsis -- A syntax summary for a software command

Synopsis

Content Model

CmdSynopsis ::=
((Command|Arg|Group|SBR)+,
 SynopFragment*)

Attributes

Common attributes

Name	Type	Default
Label	CDATA	None
CmdLength	CDATA	None
Sepchar	CDATA	" "

Tag Minimization

Both the start- and end-tags are required for this element.

Parameter Entities

%admon.mix;	%bookcomponent.content;	%component.mix;
%divcomponent.mix;	%example.mix;	%figure.mix;
%footnote.mix;	%glossdef.mix;	%indexdivcomponent.mix;
%para.char.mix;	%programlisting.content;	%qandaset.mix;
%refcomponent.mix;	%screen.content;	%sidebar.mix;
%synop.class;	%tbl.entry.mdl;

Description

A CmdSynopsis summarizes the options and parameters of a command started from a text prompt. This is usually a program started from the DOS, Windows, or UNIX shell prompt.

CmdSynopsis operates under the following general model: commands have arguments, that may be grouped; arguments and groups may be required or optional and may be repeated.

Processing expectations

The processing expectations of CmdSynopsis are fairly complex.

• Arguments are generally identified with a prefix character.

  In the UNIX world, this character is almost universally the dash or hyphen although plus signs and double dashes have become more common in recent years.

  In the DOS/Windows world, forward slashes are somewhat more common than dashes.

  The DocBook processing expectations on this point are intentionally vague. In some environments it may be most convenient to generate these characters automatically, in other environments it may be more convenient to insert them literally in the content.

  Whichever processing model you choose, note that this will be an interchange issue if you share documents with other users (see Appendix F).

• Brackets are used to distinguish between optional, required, or plain arguments. Usually square brackets are placed around optional arguments, [-g], and curly brackets are placed around required arguments, {-g}. Plain arguments are required, but are not decorated with brackets.

• Repeatable arguments are followed by an ellipsis.

• Multiple arguments within a group are considered exclusive and are separated by vertical bars.

• Groups, like arguments, may be optional, required, or plain and may or may not repeat. The same brackets and ellipses that are used to indicate these characteristics on arguments are used on groups.

• Arguments and groups may nest more-or-less arbitrarily.

• Formatted as a displayed block. The processing system is free to introduce line breaks where required, but the SBR element may be introduced by the author to provide an explicit break location.

Parents

These elements contain CmdSynopsis: Answer, Appendix, Application, Article, Attribution, BiblioDiv, Bibliography, BiblioMisc, BlockQuote, Callout, Caution, Chapter, Citation, CiteTitle, Comment, Emphasis, entry, Example, Figure, Footnote, ForeignPhrase, Glossary, GlossDef, GlossDiv, GlossSee, GlossSeeAlso, GlossTerm, Important, Index, IndexDiv, InformalExample, InformalFigure, LineAnnotation, Link, ListItem, LiteralLayout, LoTentry, Member, MsgAud, MsgExplan, MsgText, Note, OLink, Para, PartIntro, Phrase, Preface, Procedure, ProductName, ProgramListing, QandADiv, QandASet, Question, Quote, RefEntryTitle, RefSect1, RefSect2, RefSect3, RefSynopsisDiv, Screen, ScreenInfo, Sect1, Sect2, Sect3, Sect4, Sect5, Section, Seg, SetIndex, Sidebar, SimPara, SimpleSect, Step, Synopsis, Term, Tip, ToCback, ToCentry, ToCfront, ULink, Warning.

Children

The following elements occur in CmdSynopsis: Arg, Command, Group, SBR, SynopFragment.

In some contexts, the following elements are allowed anywhere: BeginPage, IndexTerm.

Attributes

CmdLength

CmdLength indicates displayed length of the command; this information may be used to intelligently indent command synopses which extend beyond one line.

Label

Label specifies an identifying number or string that may be used in presentation.

Sepchar

SepChar specifies the character (a space by default) that should separate the Command and its top-level arguments.

See Also

Arg, FuncSynopsis, Group, RefSynopsisDiv, SBR, SynopFragment, SynopFragmentRef, Synopsis

Examples

<!DOCTYPE cmdsynopsis PUBLIC "-//OASIS//DTD DocBook V3.1//EN">
<cmdsynopsis>
  <command>cd</command>
  <arg choice=req><replaceable>directory</replaceable></arg>
</cmdsynopsis>

cd {directory}

<!DOCTYPE cmdsynopsis PUBLIC "-//OASIS//DTD DocBook V3.1//EN">
<cmdsynopsis>
  <command>cal</command>
  <arg>-j</arg>
  <arg>-y</arg>
  <arg>month <arg>year</arg></arg>
</cmdsynopsis>

cal [-j] [-y] [month [year]]

<!DOCTYPE cmdsynopsis PUBLIC "-//OASIS//DTD DocBook V3.1//EN">
<cmdsynopsis>
  <command>chgrp</command>
  <arg>-R 
    <group>
      <arg>-H</arg>
      <arg>-L</arg>
      <arg>-P</arg>
    </group>
  </arg>
  <arg>-f</arg>
  <arg choice=plain><replaceable>group</replaceable></arg>
  <arg rep=repeat choice=plain><replaceable>file</replaceable></arg>
</cmdsynopsis>

chgrp [-R [-H | -L | -P] ] [-f] group file...

<!DOCTYPE cmdsynopsis PUBLIC "-//OASIS//DTD DocBook V3.1//EN">
<cmdsynopsis>
  <command>emacs</command>
  <arg>-t <replaceable>file</replaceable></arg>
  <arg>-q</arg>
  <arg>-u <replaceable>user</replaceable></arg>
  <arg>+<replaceable>number</replaceable></arg>
  <arg rep=repeat>-f <replaceable>function</replaceable></arg>
  <sbr>
  <arg rep=repeat>-l <replaceable>file</replaceable></arg>
  <arg rep=repeat choice=plain><replaceable>file</replaceable></arg>
</cmdsynopsis>

emacs [-t file] [-q] [-u user] [+number] [-f function...]
[-l file...] file...

Note the use of SBR in this example to force line breaks at reasonable places in the synopsis.

For additional examples, see also SynopFragment.

---

Prev	Home	Next
ClassName	Up	CO

Back to: DocBook: The Definitive Guide