7.3. Command Line Elements

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

<prompt>bash$</prompt> <command>twiddle <replaceable>myfile</replaceable>
twiddling myfile.....done!

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

   <!-- 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
   <arg rep="repeat">-c <replaceable>cheese</replaceable></arg>
   <synopfragmentref linkend="cheesetype">cheesetype</synopfragmentref>
   <group choice="req">
   <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>

Which looks like this:

foo [-a | -x] [-c cheese(1)] {-i | -j | -k} {-f filename}

(1) [-t milk | -k mold...]

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.