    | DocBook: The Definitive Guide 0.0.12 for DocBook V5.0b1 (Alpha) |
| | DocBook: The Definitive Guide 0.0.12 for DocBook V5.0b1 (Alpha) |
cmdsynopsis — A syntax summary for a software command
Common attributes and common linking attributes.
Additional attributes:
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.
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 E, Interchanging DocBook Documents).
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.
These elements contain cmdsynopsis: annotation, answer, appendix, article, bibliodiv, bibliography, bibliolist, blockquote, callout, calloutlist, caption (db.caption), caution, chapter, colophon, constraintdef, dedication, entry, example, figure, footnote, glossary, glossdef, glossdiv, glosslist, html:fieldset, html:form, important, index, indexdiv, informalexample, informalfigure, itemizedlist, legalnotice, listitem, msgexplan, msgtext, note, orderedlist, para, partintro, preface, procedure, qandadiv, qandaset, question, refsect1, refsect2, refsect3, refsection, refsynopsisdiv, revdescription, sect1, sect2, sect3, sect4, sect5, section, setindex, sidebar, simplesect, step, taskprerequisites, taskrelated, tasksummary, td, textobject, th, tip, toc, tocdiv, variablelist, warning.
<article xmlns='http://docbook.org/ns/docbook'> <title>Example cmdsynopsis</title> <cmdsynopsis> <command>cd</command> <arg choice='req'><replaceable>directory</replaceable></arg> </cmdsynopsis> </article>
cd {directory}
<article xmlns='http://docbook.org/ns/docbook'> <title>Example cmdsynopsis</title> <cmdsynopsis> <command>cal</command> <arg>-j</arg> <arg>-y</arg> <arg>month <arg>year</arg></arg> </cmdsynopsis> </article>
cal [-j] [-y] [month [year]]
<article xmlns='http://docbook.org/ns/docbook'> <title>Example cmdsynopsis</title> <cmdsynopsis> <command>cal</command> <arg>-j</arg> <arg>-y</arg> <arg>month <arg>year</arg></arg> </cmdsynopsis> </article>
chgrp [-R
[[-H] | [-L] | [-P]]
] [-f] group file...
<article xmlns='http://docbook.org/ns/docbook'> <title>Example cmdsynopsis</title> <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> </article>
emacs [-t file] [-q] [-u user] [+number] [-f function...]
[-l file...] file...
| | | |
| classsynopsisinfo | | co |