| Writing Documentation Using DocBook: A Crash Course | ||
|---|---|---|
| Prev | Chapter 10. Describing the Application's Interface | Next |
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>
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 <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>
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.