The following tags are used to label elements of a command:
There are two situations in which you want to describe a command: showing an example of a command typed on the command line and a detailed description of all of the arguments and options to a command like you would see in a man page.
DocBook supports both of these contexts with the <command> and <cmdsynopsis> tags.
Example 7.6. A command and its output
<screen> <prompt>bash$</prompt> <command>twiddle <replaceable>myfile</replaceable> </command> twiddling myfile.....done! </screen>
Would appear as:
bash$ twiddle -c 1 myfile twiddling myfile.....done!
The command tag can also be used within a paragraph to mark the name of a command. For example:
The <command>twiddle</command> command is used to twiddle files files. Twiddled files will be marked with the .twid extension, so if I <command>twiddle</command> <replaceable>myfile</replaceable> then it will become <replaceable>myfile.twid</replaceable>. Errors are written to the file <filename>twiddle.err</filename>.
The twiddle command is used to twiddle files files. Twiddled files will be marked with the .twid extension, so if I twiddle myfile then it will become myfile.twid. Errors are written to the file twiddle.err.
The <prompt> tag is simply used to label the prompt in a command line. Replaceable labels text that should be replaced by the user. In the example, myfile is just an arbitrary name for a file since we don't know and don't care what the name of the file is, we just want to show how the command is used. If a filename in a command is known, use the <filename> tag instead.
Marking up a cmdsynopsis is a bit more difficult. Here is an example from the DocBook Reference:
Example 7.7. A commandsynopsis
<cmdsynopsis> <!-- This is a synopsis for the command foo. The options -a and -x are optional and exclusive The option -c takes a cheese and is optional and repeatable The options -t and -k are referred to in another fragment The options -i, -j, and -k are required and exclusive The option -f takes a filename and is required The -t and -k options specify the kind of milk and mold in an optional and repeatable group --> <command>foo</command> <group> <arg>-a</arg> <arg>-x</arg> </group> <group> <arg rep="repeat">-c <replaceable>cheese</replaceable></arg> <synopfragmentref linkend="cheesetype">cheesetype</synopfragmentref> </group> <group choice="req"> <arg>-i</arg> <arg>-j</arg> <arg>-k</arg> </group> <arg choice="req">-f <replaceable>filename</replaceable></arg> <synopfragment id="cheesetype"> <group rep="repeat"> <arg>-t <replaceable>milk</replaceable></arg> <arg>-k <replaceable>mold</replaceable></arg> </group> </synopfragment> </cmdsynopsis>
Which looks like this:
A cmdsynopsis contains one command, groups of related args, independent args, and synopfragments. The <arg> labels arguments to the command. arg has two attributes: choice and rep. choice is used to indicate whether the tag is optional (the default), required (req), or to be displayed without any decoration (plain). The <group> tag is used to group together related args. synopfragment is the most complicated of the cmdsynopsis tags. It is used to provide a more detailed description of options for an argument. A synopfragment consists of two parts: the synopfragment, which contains the additional Args, and the synopfragmentref which points to the detailed description.