Variable Text

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

Use the var element to mark up placeholder text that should be replaced by the user. This is typically used inside a cmd or code element to indicate a replaceable argument, or within running prose to refer to an indicated argument.

Notes

The var element can contain a mixture of text and any general inline elements.
The var element can occur in any general inline context, including inside most inline elements, some basic block elements, and certain informational elements.
The var 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 var element can have attributes from external namespaces. See External Namespaces for more information on external-namespace attributes.
See Commands and Code Snippets for examples using var.

Examples

Use var with cmd 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.

Processing Expectations

Variable text is typically displayed in an italic or oblique font. When used inside a fixed-width element such as cmd or code, it will inherit the fixed-width font. In running prose, however, the var element does not cause its contents to be displayed in a fixed-width font.

Comparison to Other Formats

The var element is similar to the replaceable element in DocBook.

The var element is similar to the varname element in DITA.

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 var element. The namespace declarations for this definition are on the page Pages.

mal_inline_var = element var {
  mal_inline_var_attr,
  mal_inline_var_inline
}
mal_inline_var_attr = (
  mal_attr_link *,
  attribute style { xsd:NMTOKENS } ?,
  mal_inline_attr,
  mal_attr_external *
)
mal_inline_var_inline = mal_inline