Commands

This is a draft specification. It is likely that changes will still be made before the final specification.

Use the cmd element to mark up a command or a portion of a command to run in an interactive shell. It is frequently used to mark up the command to run an application. Do not use the cmd element to mark up the human-readable name of an application; use app for this purpose instead.

You may use the cmd element to mark up the entire command, including all arguments. Mallard does not contain elements to mark up the arguments specifically, as there is rarely a need to distinguish them. You may also use the cmd element to mark up parts of a command, such as options and arguments, when these need to be referenced alone.

Use the var element inside a cmd element to indicate text that should be replaced by the user.

Notes

The cmd element can contain a mixture of text and any general inline elements.
The cmd element can occur in any general inline context, including inside most inline elements, some basic block elements, and certain informational elements.
The cmd element can link to other pages or documents. See Ubiquitous Linking for more information.
The style attribute takes a space-separated list of style hints. Processing tools should adjust their behavior according to those style hints they understand.
The type attribute takes a space-separated list of tokens indicating the content type. Processing tools may adjust their behavior based on any of the tokens.
The mime attribute is deprecated and replaced by the type attribute. It takes a valid MIME type. Processing tools may adjust their behavior for particular MIME types.
The cmd element can have attributes from external namespaces. See External Namespaces for more information on external-namespace attributes.

Examples

Use cmd to mark up a simple command to run:

To start <app>Totem Movie Player</app>, enter <cmd>totem</cmd> at
the command line.

To start Totem Movie Player, enter totem at the command line.

Use cmd with var to mark up a command with a placeholder for an argument the user should supply:

To view a file in <app>Totem Movie Player</app>, enter <cmd>totem
<var>file</var></cmd> at the command line, replacing <var>file</var>
with the name of the file.

To view a file in Totem Movie Player, enter totem file at the command line, replacing file with the name of the file.

Use cmd to mark up command names and options:

The <cmd>-mtime</cmd> option for the <cmd>find</cmd> command allows
you to filter files based on their modification times.

The -mtime option for the find command allows you to filter files based on their modification times.

Processing Expectations

Commands are displayed in a fixed-width font. This mimics the look of a typical environment where commands are executed. More importantly, fixed-width fonts tend to have more distinction between visually similar characters. This is particularly important in commands, since letters often appear without the context of a known word that helps make them discernible in normal prose.

Commands in documentation are often provided with options to illustrate how to use them to a particular effect. This can make it difficult to find the end of the command quickly. Surrounding text content, especially punctuation, can sometimes be confused for part of the command. For this reason, it is recommended that commands be displayed with a border or background color.

The type and mime attributes may be used for syntax highlighting or other type-specific formatting. The mime attribute is deprecated in favor of the type attribute. The mime attribute takes a MIME type. The type attribute takes a space-separated list of tokens indicating the content type. Processing tools should select the most specific token that they can work with.

Comparison to Other Formats

The cmd element is similar to the command element in DocBook. In DocBook, writers frequently use the option element inside command. Mallard does not provide an element for this purpose.

In DocBook, the option element is also used outside the command element. In Mallard, simply use the cmd element for options outside of an entire command.

The cmd is similar to the cmdname element in DITA. The option and parmname elements in DITA are sometimes used to mark up options and parameters of commands. In Mallard, simply use the cmd element.

Schema

The formal definition of the Mallard language is maintained in RELAX NG Compact Syntax in code blocks within this specification. This is the formal definition for the cmd element. The namespace declarations for this definition are on the page Pages.

mal_inline_cmd = element cmd {
  mal_inline_cmd_attr,
  mal_inline_cmd_inline
}
mal_inline_cmd_attr = (
  mal_attr_link *,
  attribute style { xsd:NMTOKENS } ?,
  attribute type { xsd:NMTOKENS } ?,
  attribute mime { text } ?,
  mal_inline_attr,
  mal_attr_external *
)
mal_inline_cmd_inline = mal_inline