1
<page xmlns="http://projectmallard.org/1.0/"
6
<link type="seealso" xref="mal_block_code"/>
8
<revision version="0.1" date="2009-04-16" status="review"/>
10
<credit type="author">
11
<name>Shaun McCance</name>
12
<email>shaunm@gnome.org</email>
16
<name>Shaun McCance</name>
19
<include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude" />
21
<desc>Mark up a textual user interface or an interactive shell session.</desc>
24
<title>Screens</title>
26
<synopsis><code mime="application/relax-ng-compact-syntax">
27
mal_block_screen = element screen {
28
attribute style { xsd:NMTOKENS } ?,
29
attribute mime { text } ?,
30
attribute * - (mal:* | local:*) { text } *,
32
<link xref="mal_inline">mal_inline</link>
36
<p>Use the <code>screen</code> element to mark up a textual screen for
37
a textual user interface or an interactive shell. The contents of a
38
<code>screen</code> element are displayed verbatim. While all inline
39
content is allowed, <code xref="mal_inline_input">input</code> and
40
<code xref="mal_inline_output">output</code> will frequently be used
41
to provide richer markup when showing a shell session.</p>
43
<p>The <code>screen</code> element may also be used to mark up a single
44
command in a block context.</p>
46
<p>Use the <code xref="mal_inline_var">var</code> element inside a
47
<code>screen</code> element to indicate text that should be replaced
55
<item><p>The <code>screen</code> element can contain a mixture of text and
56
any <link xref="mal_inline">general inline elements</link>. Whitespace
57
is interpreted literally.</p></item>
59
<item><p>The <code>screen</code> element can occur in any
60
general block context, including inside
61
<link xref="mal_page">pages</link>, <link xref="mal_section">sections</link>,
62
and certain <link xref="mal_block">block elements</link>.</p></item>
64
<item><p>The <code>style</code> attribute takes a space-separated list of
65
style hints. Processing tools should adjust their behavior according to
66
those style hints they understand.</p></item>
68
<item><p>The <code>mime</code> attribute takes a valid MIME type. Processing
69
tools may adjust their behavior for particular MIME types. A MIME type is
70
assumed to apply to the user input only; thus, processing tools may ignore
71
the MIME type if the <code>screen</code> element is not composed of
72
<code>input</code> and <code>output</code> elements.</p></item>
75
<p>Typical values for the <code>mime</code> attribute include:</p>
76
<table rules="rows"><tr>
77
<td><p><code>application/x-sh</code></p></td>
78
<td>Command to execute with the Bourne shell</td>
80
<td><p><code>application/x-csh</code></p></td>
81
<td>Command to execute with the C shell</td>
85
<item><p>The <code>screen</code> element can have attributes from external
86
namespaces. See <link xref="mal_external"/> for more information
87
on external-namespace attributes on block elements.</p></item>
93
<!-- BEGIN examples -->
94
<section id="examples">
95
<title>Examples</title>
97
<p>Use <code>screen</code> to mark up the screen of an interactive
98
text-based interface:</p>
101
<code><![CDATA[<screen>
102
+==== Beanstalk =====================================+
103
| Type the letter of the command you want: |
106
| T - Track bean inventory |
107
+====================================================+
110
+==== Beanstalk =====================================+
111
| Type the letter of the command you want: |
114
| T - Track bean inventory |
115
+====================================================+
119
<p>Use <code>screen</code> to mark up a long command:</p>
124
xsltproc -o mal_block_screen.html \
125
--stringparam mal.cache.file `pwd`/mallard.cache \
126
`pkg-config --variable mal2html gnome-doc-utils` mal_block_screen.html
130
xsltproc -o mal_block_screen.html \
131
--stringparam mal.cache.file `pwd`/mallard.cache \
132
`pkg-config --variable mal2html gnome-doc-utils` mal_block_screen.html
136
<p>Use <code xref="mal_inline_input">input</code> and <code xref="mal_inline_output">output</code>
137
inside <code>screen</code> for richer text:</p>
142
<output style="prompt">[rupert@gnome] </output><input>ls foo bar</input>
143
<output style="error">foo: cannot access file: No such file or directory</output>
144
<output>bar</output></screen>
147
<output style="prompt">[rupert@gnome] </output><input>ls foo bar</input>
148
<output style="error">foo: cannot access file: No such file or directory</output>
149
<output>bar</output></screen>
152
<!-- END examples -->
155
<!-- BEGIN processing -->
156
<section id="processing">
157
<title>Processing Expectations</title>
159
<p>Screens should be displayed verbatim, with all whitespace and line breaks
160
reproduced in the rendered output. The only exception is a single leading
161
line break, which should be stripped by display tools if present. Display
162
tools should only strip a leading line break in an initial text node. They
163
are not expected to strip line breaks from child elements.</p>
165
<p>Screens should be displayed in a fixed-width font. Inline markup may cause
166
style variations, but they should not cause a change to a variable-width font.</p>
168
<!-- END processing -->
171
<!-- BEGIN comparison -->
172
<section id="comparison">
173
<title>Comparison to Other Formats</title>
175
<p>The <code>screen</code> element is similar to the
176
<code href="http://www.docbook.org/tdg/en/html/screen.html">screen</code>
177
element in DocBook.</p>
179
<p>The <code>screen</code> element is similar to the
180
<code href="http://docs.oasis-open.org/dita/v1.1/CS01/langspec/langref/screen.html">screen</code>
183
<!-- END comparison -->