1 <?xml version='1.0' encoding='UTF-8'?>
\r
2 <chapter xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude"
\r
3 xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:id="lists">
\r
7 <para>DocBook has several list structures to choose from. It has the standard numbered lists
\r
8 and bulleted lists. In addition it provides specialized types of lists for glossaries and
\r
9 other occasions. All of these lists may be used in Evergreen documentation. </para>
\r
13 <title>Simple Lists</title>
\r
15 <title>Overview</title>
\r
16 <para>Simple lists are like a grocery list. They are a simple list of words or phrases without
\r
17 any delimiter. Their elements can only consist of simple, in-line tags, and therefore cannot
\r
18 contain sublists, examples, code listings or multiple paragraphs. Simple lists are rarely
\r
19 used in Evergreen' documentation.</para>
\r
22 <title>Specifying a simple list</title>
\r
23 <para>A simple list is specified by a <tag class="element">simplelist</tag> element. <tag
\r
24 class="element">simplelist</tag> has two optional attributes:</para>
\r
26 <title>Attributes of the <tag class="element">simplelist</tag> Element</title>
\r
30 <entry>Attribute</entry>
\r
31 <entry>Values</entry>
\r
32 <entry>Description</entry>
\r
38 <tag class="attribute">type</tag>
\r
40 <entry><tag class="attvalue">inline</tag>, <tag class="attvalue">horiz</tag>, <tag
\r
41 class="attvalue">vert</tag> (default)</entry>
\r
42 <entry>Specifies how the items in the list are to be listed.</entry>
\r
46 <tag class="attribute">columns</tag>
\r
48 <entry>>=1</entry>
\r
49 <entry>Specifies the number of columns to use when <tag class="attribute">type</tag>
\r
50 is set to <tag class="attvalue">horiz</tag> or <tag class="attvalue"
\r
51 >vert</tag>.</entry>
\r
56 <para>The elements of a simple list are specified using a <tag class="element">member</tag>
\r
57 element. The contents of each <tag class="element">member</tag> element can only contain
\r
58 character data and in-line elements.</para>
\r
61 <title>Example</title>
\r
62 <para><xref linkend="simpmarkup"/> shows the markup for a simple list.</para>
\r
63 <example xml:id="simpmarkup" xreflabel="Example 1">
\r
64 <title>Simple List Markup</title>
\r
65 <programlisting><simplelist>
\r
66 <member>Swedish Fish</member>
\r
67 <member>Mike & Ike</member>
\r
68 <member>Sour Patch Kids</member>
\r
69 <member>Gummy Bears</member>
\r
70 </simplelist></programlisting>
\r
75 <title>Itemized Lists</title>
\r
77 <title>Overview</title>
\r
78 <para>An itemized list is used for lists where the order of the items in the list does not
\r
79 matter. They are like bulleted lists or the lists that are created by the <tag
\r
80 class="element">ul</tag> tag in HTML.</para>
\r
83 <title>Specifying an itemized list</title>
\r
84 <para>An itemized list is specified by an <tag class="element">itemizedlist</tag> element. You
\r
85 can specify an <tag class="attribute">xml:id</tag> attribute for itemized lists. If the list
\r
86 is going to referenced by an <tag class="element">xref</tag> element, you should also
\r
87 specify a value for the <tag class="attribute">xreflabel</tag> attribute.</para>
\r
88 <para>Each item in an itemized list is specified by a <tag class="element">listitem</tag>
\r
89 element. The <tag class="element">listitem</tag> element is a wrapper element and can
\r
90 contain any container elements such as a <tag class="element">para</tag> element. All
\r
91 content within a <tag class="element">listitem</tag> element will be indented to the same
\r
92 level. You can also specify sub-lists within a <tag class="element">listitem</tag>
\r
96 <title>Example</title>
\r
97 <para><xref linkend="itemmarkup"/> shows the markup for an itemized list.</para>
\r
98 <example xml:id="itemmarkup" xreflabel="Example 2">
\r
99 <title>Itemized List Markup</title>
\r
100 <programlisting><itemizedlist>
\r
102 <para>This is the first item in my list</para>
\r
105 <para>This is the second item in my list.</para>
\r
106 <para>It has two paragraphs.</para>
\r
109 <para>This item has a sublist.</para>
\r
110 <itemizedlist>
\r
111 <listitem><para>first</para></listitem>
\r
112 <listitem><para>second</para></listitem>
\r
113 </itemizedlist>
\r
115 </itemizedlist></programlisting>
\r
120 <title>Ordered List</title>
\r
122 <title>Overview</title>
\r
123 <para>An ordered list is a list where the order of the elements is important and made
\r
124 explicit. They are like numbered lists and lists that are created using the <tag
\r
125 class="element">ol</tag> tag in HTML.</para>
\r
128 <title>Specifying an ordered list</title>
\r
129 <para>Ordered lists are specified by an <tag class="element">orderedlist</tag> element. In
\r
130 addition to the <tag class="attribute">xml:id</tag> attribute and <tag class="attribute"
\r
131 >xreflabel</tag> attribute, <tag class="element">orderedlist</tag> elements have three
\r
132 optional elements.</para>
\r
134 <title>Attributes of the <tag class="element">orderedlist</tag> Element</title>
\r
138 <entry>Attribute</entry>
\r
139 <entry>Values</entry>
\r
140 <entry>Description</entry>
\r
146 <tag class="attribute">continuation</tag>
\r
148 <entry><tag class="attvalue">continues</tag>, <tag class="attvalue">restarts</tag>
\r
150 <entry>Specifies whether the item numbering should restart at one or continue from the
\r
151 previous ordered list.</entry>
\r
155 <tag class="attribute">inheritnum</tag>
\r
157 <entry><tag class="attvalue">inherit</tag>, <tag class="attvalue">ignore</tag>
\r
159 <entry>Valid only for nested lists. Specifies whether the items in the nested list
\r
160 contain a reference to the item of the parent list.</entry>
\r
164 <tag class="attribute">numeration</tag>
\r
166 <entry><tag class="attvalue">arabic</tag>, <tag class="attvalue">loweralpha</tag>,
\r
167 <tag class="attvalue">lowerroman</tag>, <tag class="attvalue">upperalpha</tag>,
\r
168 <tag class="attvalue">upperroman</tag></entry>
\r
169 <entry>Specifies the numbering style to use for the list.</entry>
\r
174 <para>Items in an ordered list are specified using a <tag class="element">listitem</tag>
\r
175 element. The <tag class="element">listitem</tag> element is a wrapper element and can
\r
176 contain any container elements such as a <tag class="element">para</tag> element. All
\r
177 content within a <tag class="element">listitem</tag> element will be indented to the same
\r
178 level. You can also specify sub-lists within a <tag class="element">listitem</tag>
\r
182 <section xml:id="VariableLists">
\r
183 <title>Variable Lists</title>
\r
185 <title>Overview</title>
\r
186 <para>A variable list looks similar to a glossary. It consists of a word, or phrase, and some
\r
187 text describing the word, or phrase. <xref linkend="varexample"
\r
188 xrefstyle="select: title nopage"/> shows a variable list.</para>
\r
189 <variablelist xml:id="varexample">
\r
190 <title>List of Rooms</title>
\r
192 <term>Kitchen</term>
\r
194 <para>The room where food is stored and prepared.</para>
\r
198 <term>Garage</term>
\r
200 <para>Where the cars are parked.</para>
\r
202 <para>Bikes are also here.</para>
\r
207 <term>Living room</term>
\r
208 <term>Family room</term>
\r
210 <para>This is where we watch TV.</para>
\r
216 <title>Specifying the list</title>
\r
217 <para>Variable lists are specified by a <tag class="element">variablelist</tag> element. The
\r
218 <tag class="element">variablelist</tag> element can have the optional <tag
\r
219 class="attribute">xml:id</tag> attribute and <tag class="attribute">xreflabel</tag>
\r
220 attribute specified. You can also supply a title for a variable list by adding a <tag
\r
221 class="element">title</tag> element as the <tag class="element">variablelist</tag>
\r
222 element's first child.</para>
\r
223 <para>The items in a variable list are specified using a <tag class="element"
\r
224 >varlistentry</tag> element. The <tag class="element">varlistentry</tag> element has two
\r
225 children elements that specify the contents of the item:</para>
\r
228 <para><tag class="element">term</tag></para>
\r
231 <para><tag class="element">listitem</tag></para>
\r
236 <title>Specifying terms</title>
\r
237 <para>You can specify one or more <tag class="element">term</tag> elements in a <tag
\r
238 class="element">varlistentry</tag> element. Each <tag class="element">term</tag> element
\r
239 can contain text and in-line markup elements. Each <tag class="element">term</tag> element
\r
240 should contain a single term or phrase that the list item describes.</para>
\r
243 <title>Describing a term</title>
\r
244 <para>You describe the term, or terms, defined by the <tag class="element">term</tag> elements
\r
245 using a single <tag class="element">listitem</tag> element. The <tag class="element"
\r
246 >listitem</tag> element is a wrapper element and can contain any container elements such
\r
247 as a <tag class="element">para</tag> element. All content within a <tag class="element"
\r
248 >listitem</tag> element will be indented to the same level. You can also specify sub-lists
\r
249 within a <tag class="element">listitem</tag> element.</para>
\r
252 <title>Example</title>
\r
253 <para><xref linkend="varmarkup"/> shows the markup representing <xref linkend="varexample"
\r
255 <example xml:id="varmarkup">
\r
256 <title>Variable List Markup</title>
\r
257 <programlisting><variablelist xml:id="varexample">
\r
258 <title>List of Rooms</title>
\r
259 <varlistentry>
\r
260 <term>Kitchen</term>
\r
262 <para>The room where food is stored and prepared.</para>
\r
264 </varlistentry>
\r
265 <varlistentry>
\r
266 <term>Garage</term>
\r
268 <para>Where the cars are parked.</para>
\r
270 <para>Bikes are also here.</para>
\r
273 </varlistentry>
\r
274 <varlistentry>
\r
275 <term>Living room</term>
\r
276 <term>Family room</term>
\r
278 <para>This is where we watch TV.</para>
\r
280 </varlistentry>
\r
281 </variablelist></programlisting>
\r
285 <section xml:id="GlossList">
\r
286 <title>Glossary Lists</title>
\r
288 <title>Overview</title>
\r
289 <para>A glossary list is a special case of a variable list. It is used specifically for lists
\r
290 that define terms and where you may want to refer the reader back to the definition of a
\r
291 specific term. <xref linkend="glossexample" xrefstyle="select: nopage label"/> shows a use
\r
292 of a glossary list.</para>
\r
293 <glosslist xml:id="glossexample" xreflabel="List of Terms">
\r
294 <title>List of Terms</title>
\r
295 <glossentry xml:id="consumerdef">
\r
296 <glossterm>consumer</glossterm>
\r
298 <para>The end user of a service, also called a client for that service.</para>
\r
299 </glossdef></glossentry>
\r
300 <glossentry xml:id="endptdef">
\r
301 <glossterm>endpoint</glossterm>
\r
303 <para>The point of contact that a <glossterm linkend="servicedef">service</glossterm>
\r
304 provides for its <glossterm linkend="consumerdef">consumers</glossterm>.</para>
\r
305 </glossdef></glossentry>
\r
306 <glossentry xml:id="servicedef">
\r
307 <glossterm>service</glossterm>
\r
309 <para>A collection of operations that perform a useful set of functions in a network,
\r
310 access to which is implemented as an <glossterm linkend="endptdef"
\r
311 >endpoint</glossterm>. In a service-oriented network, services are defined by a
\r
312 service contract.</para>
\r
313 </glossdef></glossentry>
\r
315 <glossterm>service consumer</glossterm>
\r
316 <glosssee otherterm="consumerdef"/></glossentry>
\r
320 <title>Specifying the list</title>
\r
321 <para>A glossary list is specified using the <tag class="element">glosslist</tag> element. If
\r
322 you want to refer back to a glossary list, you can provide values for the <tag
\r
323 class="attribute">xml:id</tag> attribute and the <tag class="attribute">xreflabel</tag>
\r
324 attribute. Like variable lists, glossary lists can have titles.</para>
\r
325 <para>The entries in a glossary list are specified using a <tag class="element"
\r
326 >glossentry</tag> element. The <tag class="element">glossentry</tag> element typically has
\r
327 two children: <tag class="element">glossterm</tag> and <tag class="element">glossdef</tag>.
\r
328 You can also use the <tag class="element">glosssee</tag> element to xref with other
\r
329 definitions.</para>
\r
332 <title>Specifying a term</title>
\r
333 <para>A <tag class="element">glossentry</tag> element can have only one <tag class="element"
\r
334 >glossterm</tag> element. This element specifies the term being defined by this entry. If
\r
335 you are going to refer back to this term, you can supply a value for the parent <tag
\r
336 class="element">glossentry</tag> element's <tag class="attribute">xml:id</tag>
\r
339 <para>The <tag class="element">glossterm</tag> element can also be used in text entries to
\r
340 refer to terms defined in a glossary entry. When used in this manner, you supply a value
\r
341 for the <tag class="attribute">linkend</tag> attribute.</para>
\r
345 <title>Defining a term</title>
\r
346 <para>You define a term using either one or more <tag class="element">glossdef</tag> elements
\r
347 or a <tag class="element">glosssee</tag> element. The <tag class="element">glossdef</tag>
\r
348 element is a content element that contains markup specifying a definition. If you use more
\r
349 than one <tag class="element">glossdef</tag> element, they are treated as separate
\r
350 definitions for the same term.</para>
\r
351 <para>The <tag class="element">glosssee</tag> element redirects the reader to a term with the
\r
352 same meaning. It acts like a "See" entry in a dictionary. It has one attribute,
\r
353 <tag class="attribute">otherterm</tag>, whose value is the id of the term to which the
\r
354 reader is redirected.</para>
\r
357 <title>Example</title>
\r
358 <para><xref linkend="glossmarkup"/> shows the markup for <xref linkend="glossexample"
\r
359 xrefstyle="select: nopage label"/>.</para>
\r
360 <example xml:id="glossmarkup" xreflabel="Example 4" pgwide="1">
\r
361 <?dbfo pgwide="1"?>
\r
362 <title>Glossary List Markup</title>
\r
363 <programlisting><glosslist xml:id="glossexample" xreflabel="List of terms";>
\r
364 <glossentry xml:id="consumerdef">
\r
365 <glossterm>consumer</glossterm>
\r
367 <para>The end user of a service, also called a
\r
368 client for that service.</para>
\r
370 </glossentry>
\r
371 <glossentry xml:id="endptdef">
\r
372 <glossterm>endpoint</glossterm>
\r
374 <para>The point of contact that a
\r
375 <glossterm linkend="servicedef">service</glossterm>
\r
377 <glossterm linkend="consumerdef">consumers</glossterm>.
\r
380 </glossentry>
\r
381 <glossentry xml:id="servicedef">
\r
382 <glossterm>service</glossterm>
\r
384 <para>A collection of operations that perform a
\r
385 useful set of functions in a network, access to
\r
386 which is implemented as an
\r
387 <glossterm linkend="endptdef">endpoint</glossterm>.
\r
388 In a service-oriented network, services are defined
\r
389 by a service contract.</para>
\r
391 </glossentry>
\r
393 <glossterm>service consumer</glossterm>
\r
394 <glosssee otherterm="consumerdef" />
\r
395 </glossentry>
\r
396 </glosslist></programlisting>
\r