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
128
129
130
131
132
133
134
|
<page xmlns="http://www.gnome.org/~shaunm/mallard"
type="topic"
id="mal_block_example">
<info>
<revision version="0.1" date="2009-05-06" 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>Mark a group of block elements as being part of a single example.</desc>
</info>
<title>Examples</title>
<synopsis><code mime="application/relax-ng-compact-syntax">
mal_block_example = element example {
attribute style { xsd:NMTOKENS } ?,
attribute * - (mal:* | local:*) { text } *,
<link xref="mal_block">mal_block</link> +
}
</code></synopsis>
<p>Use the <code>example</code> element to place block elements into a
logical group, indicating that they are part of a single example. This
may be used to group example input with its result, to show different
steps with different types of block elements, or simply to group some
paragraphs together.</p>
<!-- BEGIN notes -->
<section id="notes">
<title>Notes</title>
<list>
<item><p>The <code>example</code> element can contain any
<link xref="mal_block">general block content</link>.</p></item>
<item><p>The <code>example</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>example</code> element can have attributes from external
namespaces. See <link xref="mal_external"/> for more information
on external-namespace attributes.</p></item>
</list>
</section>
<!-- END notes -->
<!-- BEGIN examples -->
<section id="examples">
<title>Examples</title>
<p>Use <code>example</code> to show how to use the <code>screen</code>
element, grouping the input and formatted result:</p>
<example>
<code><![CDATA[
<example>
<code><![CDATA[
<screen>
xsltproc -o mal_block_screen.html \
--stringparam mal.cache.file `pwd`/mallard.cache \
`pkg-config --variable mal2html gnome-doc-utils` \
mal_block_screen.html
</screen>
]]>]<![CDATA[]></code>
<screen>
xsltproc -o mal_block_screen.html \
--stringparam mal.cache.file `pwd`/mallard.cache \
`pkg-config --variable mal2html gnome-doc-utils` \
mal_block_screen.html
</screen>
</example>
]]></code>
<example>
<code><![CDATA[
<screen>
xsltproc -o mal_block_screen.html \
--stringparam mal.cache.file `pwd`/mallard.cache \
`pkg-config --variable mal2html gnome-doc-utils` \
mal_block_screen.html
</screen>
]]></code>
<screen>
xsltproc -o mal_block_screen.html \
--stringparam mal.cache.file `pwd`/mallard.cache \
`pkg-config --variable mal2html gnome-doc-utils` \
mal_block_screen.html
</screen></example>
</example>
</section>
<!-- END examples -->
<!-- BEGIN processing -->
<section id="processing">
<title>Processing Expectations</title>
<p>The contents of an <code>example</code> element should each be rendered
as block elements as normal. Example should use margins, borders, or other
stylistic effects to provide a clear visual indication of the grouping.</p>
</section>
<!-- END processing -->
<!-- BEGIN comparison -->
<section id="comparison">
<title>Comparison to Other Formats</title>
<p>The <code>example</code> element is similar to the
<code href="http://www.docbook.org/tdg/en/html/example.html">example</code>
element in DocBook. In DocBook, the <code>example</code> element is a
formal element. In Mallard, <code>example</code> is a simple container
element, and does not allow a <code xref="mal_block_title">title</code>
element.</p>
</section>
<!-- END comparison -->
</page>
|
