Screens

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

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

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 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 type { xsd:NMTOKENS } ?,
  attribute mime { text } ?,
  mal_block_attr,
  mal_attr_external *
)
mal_block_screen_inline = mal_inline