1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
|
<page xmlns="http://www.gnome.org/~shaunm/mallard"
type="topic"
id="mal_block_listing">
<info>
<link type="seealso" xref="mal_block_code"/>
<link type="seealso" xref="mal_block_figure"/>
<version number="0.1" date="2009-05-19" status="review"/>
<credit type="author">
<name>Shaun McCance</name>
<email>shaunm@gnome.org</email>
</credit>
<copyright>
<year>2008-2009</year>
<name>Shaun McCance</name>
</copyright>
<include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude" />
<desc>Provide a name and description for a code block or other content.</desc>
</info>
<title>Listings</title>
<synopsis><code mime="application/relax-ng-compact-syntax">
mal_block_listing = element listing {
attribute style { xsd:NMTOKENS } ?,
attribute * - (mal:* | local:*) { text } *,
<link xref="mal_block_title">mal_block_title</link> ?,
<link xref="mal_block_desc">mal_block_desc</link> ?,
<link xref="mal_block">mal_block</link> +
}
</code></synopsis>
<p>Use the <code>listing</code> element to create named listing of file contents
or other content. Listings are usually used with <link xref="mal_block_code">code
blocks</link> to provide a name for the file to enter the content into. They may
also be used to provide a name for an <link xref="mal_block_screen">interactive
shell session</link> or any other type of content. To provide a title for images
or other multimedia objects, use the <link xref="mal_block_figure">figure</link>
element.</p>
<!-- BEGIN notes -->
<section id="notes">
<title>Notes</title>
<ulist>
<item><p>The <code>listing</code> element contains an optional
<link xref="mal_block_title">title</link> element, an optional
<link xref="mal_block_desc">desc</link> element, and any
<link xref="mal_block">general block content</link>.</p></item>
<item><p>The <code>listing</code> element can occur in any
general block context, including inside
<link xref="mal_page">pages</link>, <link xref="mal_section">sections</link>,
and certain <link xref="mal_block">block elements</link>.</p></item>
<item><p>The <code>style</code> attribute takes a space-separated list of
style hints. Processing tools should adjust their behavior according to
those style hints they understand.</p></item>
<item><p>The <code>listing</code> element can have attributes from external
namespaces. See <link xref="mal_external"/> for more information
on external-namespace attributes.</p></item>
</ulist>
</section>
<!-- END notes -->
<!-- BEGIN examples -->
<section id="examples">
<title>Examples</title>
<p>Use <code>listing</code> to provide a file name and description for a
code block:</p>
<example>
<code><![CDATA[
<listing>
<title><file>index.page</file></title>
<desc>A first Mallard page</desc>
<code><![CDATA[
<page xmlns="http://www.gnome.org/~shaunm/mallard"
type="guide"
id="index">
<!-- Content goes here -->
</page>]]]>]><![CDATA[</code>
</listing>]]></code>
<listing>
<title><file>index.page</file></title>
<desc>A first Mallard page</desc>
<code><![CDATA[
<page xmlns="http://www.gnome.org/~shaunm/mallard"
type="guide"
id="index">
<!-- Content goes here -->
</page>]]></code>
</listing>
</example>
</section>
<!-- END examples -->
<!-- BEGIN processing -->
<section id="processing">
<title>Processing Expectations</title>
<p>Listings are displayed as block elements, with each of their child elements
being interpreted as block elements. When present, the title and description
should be displayed in a way that makes their respective roles clear.</p>
</section>
<!-- END processing -->
<!-- BEGIN comparison -->
<!--
No direct analog in DocBook. I'm sure people accomplish the same thing somehow,
but my brain isn't working right now. Also check DITA.
<section id="comparison">
<title>Comparison to Other Formats</title>
</section>
-->
<!-- END comparison -->
</page>
|
