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
|
<page xmlns="http://projectmallard.org/1.0/"
type="topic"
id="mal_block_terms">
<info>
<revision version="0.1" date="2009-05-28" 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 terms and associated descriptions.</desc>
</info>
<title>Definition Lists</title>
<synopsis><code mime="application/relax-ng-compact-syntax">
mal_block_terms = element terms {
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_title">mal_block_title</link> +,
<link xref="mal_block">mal_block</link> +
} +
}
</code></synopsis>
<p>The <code>terms</code> element creates a list of terms and associated
definitions or descriptions. This type of list is often called a definition
list or a variable list.</p>
<!-- BEGIN notes -->
<section id="notes">
<title>Notes</title>
<list>
<item><p>The <code>terms</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 one or more <code xref="mal_block_title">title</code> elements
followed by a mixture of text and any
<link xref="mal_inline">general inline elements</link>.</p></item>
<item><p>The <code>terms</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>terms</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 definition list with a title:</p>
<example>
<code><![CDATA[
<terms>
<title>Selected Basic Block Elements</title>
<item>
<title><code>code</code></title>
<p>Mark up a block of code or the contents of a file.</p>
</item>
<item>
<title><code>example</code></title>
<p>Mark up a group of block elements as being part of a single example.</p>
</item>
<item>
<title><code>screen</code></title>
<p>Mark up a textual user interface or an interactive shell session.</p>
</item>
</terms>]]></code>
<terms>
<title>Selected Basic Block Elements</title>
<item>
<title><code>code</code></title>
<p>Mark up a block of code or the contents of a file.</p>
</item>
<item>
<title><code>example</code></title>
<p>Mark up a group of block elements as being part of a single example.</p>
</item>
<item>
<title><code>screen</code></title>
<p>Mark up a textual user interface or an interactive shell session.</p>
</item>
</terms>
</example>
<p>Create a definition list with multiple terms per entry:</p>
<example>
<code><![CDATA[
<terms>
<item>
<title><code>comment</code></title>
<title><code>quote</code></title>
<p>Formal elements which allow a <code>cite</code> element.</p>
</item>
<item>
<title><code>figure</code></title>
<title><code>listing</code></title>
<title><code>synopsis</code></title>
<p>Formal elements which allow a <code>desc</code> element.</p>
</item>
<item>
<title><code>note</code></title>
<p>Formal elements which only allow a <code>title</code> element.</p>
</item>
</terms>]]></code>
<terms>
<item>
<title><code>comment</code></title>
<title><code>quote</code></title>
<p>Formal elements which allow a <code>cite</code> element.</p>
</item>
<item>
<title><code>figure</code></title>
<title><code>listing</code></title>
<title><code>synopsis</code></title>
<p>Formal elements which allow a <code>desc</code> element.</p>
</item>
<item>
<title><code>note</code></title>
<p>Formal elements which only allow a <code>title</code> element.</p>
</item>
</terms>
</example>
</section>
<!-- END examples -->
<!-- BEGIN processing -->
<section id="processing">
<title>Processing Expectations</title>
<p>Definition lists are displayed as block elements, with each child
<code>item</code> displayed as some number of list items. When present, the
title should be displayed in a way that makes it clear that it is the title
of the list. Each <code>title</code> element of each list item is treated
as a term, and is displayed as a block element. The remaining block content
is then treated as the description and displayed as normal. The description
blocks should be indented from the terms.</p>
</section>
<!-- END processing -->
<!-- BEGIN comparison -->
<section id="comparison">
<title>Comparison to Other Formats</title>
<p>The <code>terms</code> element is similar to
<code href="http://www.docbook.org/tdg/en/html/variablelist.html">variablelist</code>
element in DocBook. Like DocBook (and unlike HTML), Mallard groups terms with their
corresponding entries. In DocBook, the entry must be wrapped with a
<code href="http://www.docbook.org/tdg/en/html/listitem.html">listitem</code>
element inside the
<code href="http://www.docbook.org/tdg/en/html/varlistentry.html">varlistentry</code>
element. In Mallard, the entry is simply all of the block content except the
<code xref="mal_block_title">title</code> elements.</p>
</section>
<!-- END comparison -->
</page>
|
