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
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
|
<page xmlns="http://www.gnome.org/~shaunm/mallard"
type="topic"
id="mal_block_note">
<info>
<version number="0.1" date="2009-05-18" 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>Include notes, tips, warnings, and other parenthetical information.</desc>
</info>
<title>Notes</title>
<synopsis><code mime="application/relax-ng-compact-syntax">
mal_block_note = element note {
attribute style { xsd:NMTOKENS } ?,
attribute * - (mal:* | local:*) { text } *,
<link xref="mal_block_title">mal_block_title</link> ?,
<link xref="mal_block">mal_block</link> +
}
</code></synopsis>
<p>The <code>note</code> element allows you to insert parenthetical block-level
content into your document. Notes are visually distinct blocks, allowing readers
to skip them or focus on them, depending on their needs. You can use notes to
give tips, warn readers of potentially dangerous operations, point out known bugs,
or otherwise provide additional information without interfering with the main text
of your document.</p>
<!-- BEGIN notes -->
<section id="notes">
<title>Notes</title>
<ulist>
<item><p>The <code>note</code> element contains an optional
<link xref="mal_block_title">title</link> element and any
<link xref="mal_block">general block content</link>.</p></item>
<item><p>The <code>note</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 following style hints are recommended:</p>
<table rules="rows">
<tr>
<td><p><code>"advanced"</code></p></td>
<td><p>information that advanced users may find useful</p></td>
</tr>
<tr>
<td><p><code>"bug"</code></p></td>
<td><p>a note about a known bug in the software</p></td>
</tr>
<tr>
<td><p><code>"important"</code></p></td>
<td><p>important information highlighted in a note</p></td>
</tr>
<tr>
<td><p><code>"tip"</code></p></td>
<td><p>a general tip that may help the reader perform an operation better</p></td>
</tr>
<tr>
<td><p><code>"warning"</code></p></td>
<td><p>a warning to the reader about a potentially dangerous operation</p></td>
</tr>
</table>
</item>
<item><p>The <code>note</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>Insert a basic note into your document:</p>
<example>
<code><![CDATA[
<note>
<p>Information in this section is non-normative.</p>
</note>
]]></code>
<note>
<p>Information in this section is non-normative.</p>
</note>
</example>
<p>Include a note with extra information for advanced readers:</p>
<example>
<code><![CDATA[
<note style="advanced">
<p>The Mallard schema is maintained in RELAX-NG Compact Syntax in
code blocks embedded within the specification.</p>
</note>
]]></code>
<note style="advanced">
<p>The Mallard schema is maintained in RELAX-NG Compact Syntax in
code blocks embedded within the specification.</p>
</note>
</example>
<p>Mention a known bug the reader is likely to encounter:</p>
<example>
<code><![CDATA[
<note style="bug">
<title>Cannot Save Files</title>
<p>Due to <link href="http://bugs.example.com/1234">bug #1234</link> you
cannot actually save files. If you try to save your files, the application
will crash. We recommend memorizing all your data on a regular basis.</p>
</note>
]]></code>
<note style="bug">
<title>Cannot Save Files</title>
<p>Due to <link href="http://bugs.example.com/1234">bug #1234</link> you
cannot actually save files. If you try to save your files, the application
will crash. We recommend memorizing all your data on a regular basis.</p>
</note>
</example>
<p>Highlight a vital piece of information to ensure readers see it even
when skimming a document:</p>
<example>
<code><![CDATA[
<note style="important">
<title>Supply Your Name and Email Address</title>
<p>Before making any commits to a git repository, make sure to
supply your name and email address so that your commits are
correctly attributed.</p>
<code>
git config --global user.name <var>full_name</var>
git config --global user.email <var>email_address</var></code>
</note>
]]></code>
<note style="important">
<title>Supply Your Name and Email Address</title>
<p>Before making any commits to a git repository, make sure to
supply your name and email address so that your commits are
correctly attributed.</p>
<code>
git config --global user.name <var>full_name</var>
git config --global user.email <var>email_address</var></code>
</note>
</example>
<p>Provide a helpful but non-essential tip:</p>
<example>
<code><![CDATA[
<note style="tip">
<p>Press <keyseq><key>Ctrl</key><key>J</key></keyseq> to jump to
the currently playing track.</p>
</note>
]]></code>
<note style="tip">
<p>Press <keyseq><key>Ctrl</key><key>J</key></keyseq> to jump to
the currently playing track.</p>
</note>
</example>
<p>Warn the reader about dangerous operations:</p>
<example>
<code><![CDATA[
<note style="warning">
<p>There is no way to recover files deleted with the
<cmd>shred</cmd> command.</p>
</note>
]]></code>
<note style="warning">
<p>There is no way to recover files deleted with the <cmd>shred</cmd> command.</p>
</note>
</example>
</section>
<!-- END examples -->
<!-- BEGIN processing -->
<section id="processing">
<title>Processing Expectations</title>
<p>Notes are displayed as block elements, with each of their child elements
being interpreted as block elements. When present, the title should be
displayed in a way that makes it clear that it is the title of the block.
Notes should have a border, background color, or other styling effect to
distinguish them from the surrounding block content. Notes often use an
icon to identify what type of note is being displayed.</p>
</section>
<!-- END processing -->
<!-- BEGIN comparison -->
<section id="comparison">
<title>Comparison to Other Formats</title>
<p>The <code>note</code> element is similar to the
<code href="http://www.docbook.org/tdg/en/html/caution.html">caution</code>,
<code href="http://www.docbook.org/tdg/en/html/important.html">important</code>,
<code href="http://www.docbook.org/tdg/en/html/note.html">note</code>,
<code href="http://www.docbook.org/tdg/en/html/tip.html">tip</code>, and
<code href="http://www.docbook.org/tdg/en/html/warning.html">warning</code>
elements in DocBook. Rather than use separate elements, Mallard uses single
<code>note</code> element which can be specialized and extended through style
hints. This document recommends the style hints <code>advanced</code> and
<code>bug</code>, which have no counterpart in DocBook. This document does
not recommend separate <code>caution</code> and <code>warning</code> types,
as there is rarely a useful distinction in practice.</p>
</section>
<!-- END comparison -->
</page>
|
