|Syntax and mark-up / Phrases|
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].
The syntax mark-up should be contained as a whole within a syntax phrase (synph) or syntax block (synblk) element.
<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.