Shaun McCance
shaunm@gnome.org 2007-2009
Mark up a command to be entered at an interactive shell.

# Comandos

    mal_inline_cmd = element cmd {
      mal_attr_link ?,
      attribute style { xsd:NMTOKENS } ?,
      attribute mime { text } ?,
      attribute * - (mal:* | local:*) { text } *,

      mal_inline
    }

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.

# Notas

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 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 `mime` attribute takes a valid MIME type. Processing tools may adjust their behavior for particular MIME types.

Typical values for the `mime` attribute include:

`application/x-sh` | Command to execute with the Bourne shell
`application/x-csh` | Command to execute with the C shell

The `cmd` element can have attributes from external namespaces. See for more information on external-namespace attributes.

# Ejemplos

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 discernable 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.

# 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.

See for more background.