Complex command reference content

When documenting complex software command references, you can use a combination of DITA phrase elements to describe the syntax. The mark-up can be converted to syntax formatting conventions during the publishing process.

In style-based authoring, formatting conventions have been used to identify the parts of command syntax for computer software applications. In this context, a command is a string of text that a user types in order to run an application and pass arguments to the application.

The Microsoft Manual of Style for Technical Publications suggests a syntax of:

For example, a command syntax might be represented as ant [-f filename] [-logfile filename] [-verbose].

In DITA, the following semantic elements are used to identify the components of a command:
kwd
A literal keyword used in a command, utility or batch file
option
an option or switch that modifies a command
oper
An operator (such as *, + or =)
var
The name of a variable or argument
delim
A delimiter character used to identify the beginning or end of one part of the syntax
sep
A separator character such as a bracket that is used within syntax

The syntax mark-up should be contained as a whole within a syntax phrase (synph) or syntax block (synblk) element.

An example of a marked up command line might be:
<synph>
 <kwd>ant</kwd> <option>-f</option> <var>filename</var>
 <option>-logfile</option> <var>filename</var>
 <option>-verbose</option>
</synph>

A typical output of this code is:

ant -f filename -logfile filename -verbose

When the command syntax is being used within an instruction to a user (usually within a task topic), the syntax should instead be contained within a userinput element, without the individual components of the command semantically identified.