The Crash Course to DocBook

10.3. Command Line Elements

The following tags are used to label elements of a command:

type - Classification of a value
literal - Literal string, used in-line, that is part of data in a computer
userinput - Data entered by the user
symbol - Name that is replaced by a value before processing
replaceable - Content that may be replaced in a synopsis or command line
filename - Name of a file, possibly including pathname
prompt - Character indicating the start of an input field in a computer display.
paramdef - Data type information and the name of the parameter this information applies to
parameter - Part of an instruction to a computer
option - Option for a computer program command
envar - Environmental variable
command - Executable program, or the entry a user makes to execute a command
cmdsynopsis - Synopsis for a command
arg - Argument in a cmdsynopsis
computeroutput - Data presented to the user by a computer
funcsynopsis - Syntax summary for a function definition
funcsynopsisinfo - General information on how to use the function
funcprototype - Prototype of the function
funcdef - Name and return value of the function
function - Name of the function
paramdef - Name and type of a function parameter
parameter - Name of a function parameter

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 10-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. 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. 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 10-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:

foo [-a | -x] [-c cheese(1)cheesetype] {-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.