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
|
<page xmlns="http://projectmallard.org/1.0/"
type="topic"
id="mal_block_comment">
<info>
<revision version="0.1" date="2009-05-07" status="review"/>
<credit type="author">
<name>Shaun McCance</name>
<email>shaunm@gnome.org</email>
</credit>
<copyright>
<year>2007-2009</year>
<name>Shaun McCance</name>
</copyright>
<include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude" />
<desc>Include an editorial comment that's hidden from normal readers.</desc>
</info>
<title>Editorial Comments</title>
<synopsis><code mime="application/relax-ng-compact-syntax">
mal_block_comment = element comment {
attribute style { xsd:NMTOKENS } ?,
attribute * - (mal:* | local:*) { text } *,
<link xref="mal_block_title">mal_block_title</link> ?,
<link xref="mal_block_cite">mal_block_cite</link>,
<link xref="mal_block">mal_block</link> +
}
</code></synopsis>
<p>The <code>comment</code> element allows you to insert editorial comments
into your document. These comments are intended to be displayed only when
editing or reviewing the document, and not when the document is viewed by the
end reader. A <code>comment</code> element can contain other <code>comment</code>
elements, allowing you to have a threaded discussion inside editorial comments.</p>
<p>A <code>comment</code> element may optionally contain a
<code xref="mal_block_title">title</code> element to provide a brief description
of the subject of the comment. Titles are encouraged in top-level comments,
although they are usually unnecessary in replies.</p>
<p>The <code xref="mal_block_cite">cite</code> element is a required element
that specifies the person making the comment. Writers are highly encouraged
to provide a <code>date</code> attribute.</p>
<!-- BEGIN notes -->
<section id="notes">
<title>Notes</title>
<list>
<item><p>The <code>comment</code> element contains an optional
<link xref="mal_block_title">title</link> element, a
<link xref="mal_block_cite">cite</link> element, and any
<link xref="mal_block">general block content</link>.</p></item>
<item><p>The <code>comment</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>comment</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>Provide a comment:</p>
<example>
<code><![CDATA[
<comment>
<title>Mallards Are Dabbling Ducks</title>
<cite date="2009-05-07" href="mailto:drake@example.com">Drake</cite>
<p>The information in this section is wrong. Mallards are dabbling
ducks, not diving ducks.</p>
</comment>]]></code>
<comment>
<?mal2html.show_comment?>
<title>Mallards Are Dabbling Ducks</title>
<cite date="2009-05-07" href="mailto:drake@example.com">Drake</cite>
<p>The information in this section is wrong. Mallards are dabbling
ducks, not diving ducks.</p>
</comment>
</example>
<p>Use <code>comment</code> to carry out a threaded discussion:</p>
<example>
<code><![CDATA[
<comment>
<title>Mallards Are Dabbling Ducks</title>
<cite date="2009-05-07" href="mailto:drake@example.com">Drake</cite>
<p>The information in this section is wrong. Mallards are dabbling
ducks, not diving ducks.</p>
<comment>
<cite date="2009-05-08" href="mailto:rupert@example.com">Rupert</cite>
<p>But I saw a mallard dive just the other day.</p>
<comment>
<cite date="2009-05-09" href="mailto:drake@example.com">Drake</cite>
<p>Rupert, please see the
<link href="http://en.wikipedia.org/wiki/Mallard">Wikipedia
entry</link>.</p>
</comment>
</comment>
</comment>]]></code>
<comment>
<?mal2html.show_comment?>
<title>Mallards Are Dabbling Ducks</title>
<cite date="2009-05-07" href="mailto:drake@example.com">Drake</cite>
<p>The information in this section is wrong. Mallards are dabbling
ducks, not diving ducks.</p>
<comment>
<?mal2html.show_comment?>
<cite date="2009-05-08" href="mailto:rupert@example.com">Rupert</cite>
<p>But I saw a mallard dive just the other day.</p>
<comment>
<?mal2html.show_comment?>
<cite date="2009-05-09" href="mailto:drake@example.com">Drake</cite>
<p>Rupert, please see the
<link href="http://en.wikipedia.org/wiki/Mallard">Wikipedia
entry</link>.</p>
</comment>
</comment>
</comment>
</example>
</section>
<!-- END examples -->
<!-- BEGIN processing -->
<section id="processing">
<title>Processing Expectations</title>
<p>In normal processing, <code>comment</code> elements are not displayed.
It may be displayed under various circumstances, such as for writing and
editing purposes.</p>
<p>When shown, a <code>comment</code> element is rendered as a displayed
block, with each of its child elements interpreted as block elements.
A border, background color, or other stylistic effect should be used to
clearly set distinguish comments from the surrounding content.</p>
<p>If a <code>title</code> element is present, it is displayed at the top
of the comment. The <code>cite</code> my require special processing to
dispaly both its inline content and its <code>date</code> attribute.
Automatic text may be used for this.</p>
</section>
<!-- END processing -->
<!-- BEGIN comparison -->
<section id="comparison">
<title>Comparison to Other Formats</title>
<p>The <code>comment</code> element is similar to the
<code href="http://www.docbook.org/tdg/en/html/remark.html">remark</code>
element in DocBook. The DocBook <code>remark</code> element may be used
in either a block or an inline context, whereas the <code>comment</code>
element may only be used as a block element. The DocBook <code>remark</code>
element does not provide a way to supply a title or the name of the person
making the remark.</p>
</section>
<!-- END comparison -->
</page>
|
