Screens

This specification has been replaced by Mallard 1.1.

Use the screen element to mark up a text-based user interface or an interactive shell. The contents of a screen element are displayed verbatim. While all inline content is allowed, input and output elements will frequently be used to provide richer markup when showing a shell session.

The screen element may also be used to mark up a single command in a block context.

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

Notes

The screen element can contain a mixture of text and any general inline elements. Whitespace is interpreted literally.
The screen element can occur in any general block context, including inside pages, sections, and certain block elements.
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. A MIME type is assumed to apply to the user input only; thus, processing tools may ignore the MIME type if the screen element is not composed of input and output elements.
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 screen element can have attributes from external namespaces. See External Namespaces for more information on external-namespace attributes on block elements.

Examples

Use screen to mark up the screen of an interactive text-based interface:

<screen>
+==== Beanstalk =====================================+
| Type the letter of the command you want:           |
| O - Order beans                                    |
| P - Plant beans                                    |
| T - Track bean inventory                           |
+====================================================+
</screen>

+==== Beanstalk =====================================+
| Type the letter of the command you want:           |
| O - Order beans                                    |
| P - Plant beans                                    |
| T - Track bean inventory                           |
+====================================================+

Use screen to mark up a long command:

<screen>
xsltproc -o mal_block_screen.html \
  --stringparam mal.cache.file `pwd`/mallard.cache \
  `pkg-config --variable mal2html yelp-xsl` mal_block_screen.page
</screen>

xsltproc -o mal_block_screen.html \
  --stringparam mal.cache.file `pwd`/mallard.cache \
  `pkg-config --variable mal2html yelp-xsl` mal_block_screen.page

Use input and output inside screen for richer text:

<screen>
<output style="prompt">[rupert@gnome] </output><input>ls foo bar</input>
<output style="error">foo: cannot access file: No such file or directory</output>
<output>bar</output></screen>

[rupert@gnome] ls foo bar
foo: cannot access file: No such file or directory
bar

Processing Expectations

Screens are displayed verbatim, with all whitespace and line breaks reproduced in the rendered output. The only exception is a single leading line break, which is stripped by display tools if present. Display tools only strip a leading line break in an initial text node. They are not expected to strip line breaks from child elements.

Screens should be displayed in a fixed-width font. Inline markup may cause style variations, but they do not cause a change to a variable-width font.

Comparison to Other Formats

The screen element is similar to the screen element in DocBook.

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

mal_block_screen = element screen {
  mal_block_screen_attr,
  mal_block_screen_inline
}
mal_block_screen_attr = (
  attribute style { xsd:NMTOKENS } ?,
  attribute mime { text } ?,
  mal_block_attr,
  mal_attr_external *
)
mal_block_screen_inline = mal_inline