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
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
|
<page xmlns="http://projectmallard.org/1.0/"
type="topic"
id="mal_block_steps">
<info>
<revision version="0.1" date="2009-05-23" status="review"/>
<credit type="author">
<name>Shaun McCance</name>
<email>shaunm@gnome.org</email>
<years>2008-2009</years>
</credit>
<include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude" />
<desc>Create a list of steps the reader should perform to accomplish a task.</desc>
</info>
<title>Procedures</title>
<synopsis><code mime="application/relax-ng-compact-syntax">
mal_block_steps = element steps {
attribute style { xsd:NMTOKENS } ?,
attribute * - (mal:* | local:*) { text } *,
<link xref="mal_block_title">mal_block_title</link> ?,
element item {
attribute style { xsd:NMTOKENS } ?,
attribute * - (mal:* | local:*) { text } *,
<link xref="mal_block">mal_block</link> +
} +
}
</code></synopsis>
<p>Use the <code>steps</code> element to create a list of steps the reader
should follow. The <code>steps</code> element is structurally similar to
the <code xref="mal_block_list">list</code> element, but marking the list
as being instructions to the reader allows special display rules to be
applied. If you want a numbered list that is not a procedure, use the
<code xref="mal_block_list">list</code> element with the <code>type</code>
attribute to <code>"numbered"</code> instead.</p>
<!-- BEGIN notes -->
<section id="notes">
<title>Notes</title>
<list>
<item><p>The <code>steps</code> element can contain an optional
<code xref="mal_block_title">title</code> element followed by one or more
<code>item</code> elements. Each child <code>item</code> element can
contain a mixture of text and any
<link xref="mal_inline">general inline elements</link>.</p></item>
<item><p>The <code>steps</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>steps</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>Create a simple procedure of steps for the reader to follow:</p>
<example>
<code><![CDATA[
<steps>
<title>Planting Magic Beans</title>
<item><p>Dig a hole 10cm deep.</p></item>
<item><p>Place magic beans in the hole.</p></item>
<item><p>Fill hole with fertilized soil.</p></item>
<item><p>Water frequently.</p></item>
</steps>
]]></code>
<steps>
<title>Planting Magic Beans</title>
<item><p>Dig a hole 10cm deep.</p></item>
<item><p>Place magic beans in the hole.</p></item>
<item><p>Fill hole with fertilized soil.</p></item>
<item><p>Water frequently.</p></item>
</steps>
</example>
<p>Create a procedure with a nested list and a nested procedure:</p>
<example>
<code><![CDATA[
<steps>
<title>Planting Magic Beans</title>
<item>
<p>Perform one of the following:</p>
<list>
<item><p>Dig a whole 10cm deep.</p></item>
<item><p>Find a whole 10cm deep.</p></item>
</list>
</item>
<item><p>Place magic beans in the hole.</p></item>
<item><p>Fill hole with fertilized soil.</p></item>
<item>
<p>Water frequently with the following steps:</p>
<steps>
<item><p>Fill watering can with water.</p></item>
<item><p>Pour water onto spot where beans were planted.</p></item>
</steps>
</item>
</steps>
]]></code>
<steps>
<title>Planting Magic Beans</title>
<item>
<p>Perform one of the following:</p>
<list>
<item><p>Dig a whole 10cm deep.</p></item>
<item><p>Find a whole 10cm deep.</p></item>
</list>
</item>
<item><p>Place magic beans in the hole.</p></item>
<item><p>Fill hole with fertilized soil.</p></item>
<item>
<p>Water frequently with the following steps:</p>
<steps>
<item><p>Fill watering can with water.</p></item>
<item><p>Pour water onto spot where beans were planted.</p></item>
</steps>
</item>
</steps>
</example>
</section>
<!-- END examples -->
<!-- BEGIN processing -->
<section id="processing">
<title>Processing Expectations</title>
<p>Procedures are displayed as block elements, with each child <code>item</code>
displayed as a numbered list item. When present, the <code>title</code> element
should be displayed in a way that makes it clear that it is the title of the list.
List items are interpreted in the same way as <code>li</code> elements in HTML,
except that the <code>item</code> element only allows block-level child content.</p>
<p>Procedures should have a background color, border, or other styling effect
to clearly differentiate them from basic numbered lists. Special styling allows
readers to skim pages more easily.</p>
</section>
<!-- END processing -->
<!-- BEGIN comparison -->
<section id="comparison">
<title>Comparison to Other Formats</title>
<p>The <code>steps</code> element is similar to the
<code href="http://www.docbook.org/tdg/en/html/procedure.html">procedure</code>
element in DocBook. Note the following differences:</p>
<list>
<item><p>Instead of a separate
<code href="http://www.docbook.org/tdg/en/html/step.html">step</code> element,
Mallard simply uses the common <code>item</code> element for each step.</p></item>
<item><p>DocBook provides an explicit
<code href="http://www.docbook.org/tdg/en/html/substeps.html">substeps</code>
element. Mallard provides no such element; simply nest <code>steps</code>
elements for the same effect.</p></item>
<item><p>Mallard provides no equivalent to the
<code href="http://www.docbook.org/tdg/en/html/stepalternatives.html">stepalternatives</code>
element. Use a <code xref="mal_block_list">basic bulleted list</code> with
introductory text when this is needed.</p></item>
<item><p>DocBook allows leading block-level content in the <code>procedure</code>
element. This is not allowed in Mallard, though an optional <code>title</code>
element is allowed.</p></item>
</list>
</section>
<!-- END comparison -->
</page>
|
