Computer Output

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

Use the output element to mark up text that is output by a computer program. Typically, this is text output in a command-line environment, although you may use the output element for computer-generated text in a text box or similar control in a graphical application. For messages and other labels in a graphical application, use the gui element.

You can use the style attribute to indicate what type of text is being marked up. Inside a screen element, this may be used to format normal text, error text, and prompts differently.

Notes

The output element can contain a mixture of text and any general inline elements.
The output element can occur in any general inline context, including inside most inline elements, some basic block elements, and certain informational elements.
The output 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.
Typical values for the style attribute include:

output

Standard output from a running program

error

Standard error from a running program

prompt

The command prompt for an interactive shell
The output element can have attributes from external namespaces. See External Namespaces for more information on external-namespace attributes.
The output element, together with the input element, may be used to mark up the contents of a screen element, allowing processing tools to treat them differently.

Examples

Use output to mark up text generated by a program:

The output of <cmd>echo $SHELL</cmd> is <output>/bin/bash</output>
if you use the Bourne-again shell.

The output of echo $SHELL is /bin/bash if you use the Bourne-again shell.

Use output and input inside a screen element:

<screen>
<output style="prompt">$ </output><input>ls mal_inline_output.xml</input>
<output>mal_inline_output.xml</output>
</screen>

$ ls mal_inline_output.xml
mal_inline_output.xml

Use output for error text:

<screen>
<output style="prompt">$ </output><input>ls mal.xml</input>
<output style="error">ls: mal.xml: No such file or directory</output>
</screen>

$ ls mal_inline_computeroutput.xml
ls: mal_inline_computeroutput.xml: No such file or directory

Processing Expectations

Computer output is displayed in a fixed-width or wide font. Fixed-width fonts tend to have more distinction between visually similar characters. A border or background color may be used to make the beginning and end of the output clear.

Comparison to Other Formats

The output element is similar to the computeroutput element in DocBook. When necessary, the output element may be used with the style attribute "prompt" in place of the prompt element in DocBook. In some cases, it may be appropriate to use the output element with the style attribute "error" in place of the errorname and errortext elements in DocBook.

The output element is similar to the systemoutput 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 output element. The namespace declarations for this definition are on the page Pages.

mal_inline_output = element output {
  mal_inline_output_attr,
  mal_inline_output_inline
}
mal_inline_output_attr = (
  mal_attr_link *,
  attribute style { xsd:NMTOKENS } ?,
  mal_inline_attr,
  mal_attr_external *
)
mal_inline_output_inline = mal_inline