docs/1.6/lists.xml

   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
   4   <title>Lists</title>\r
   5   <info>\r
   6     <abstract>\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
  10     </abstract>\r
  11   </info>\r
  12   <section>\r
  13     <title>Simple Lists</title>\r
  14     <simplesect>\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
  20     </simplesect>\r
  21     <simplesect>\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
  25       <table pgwide="1">\r
  26         <title>Attributes of the <tag class="element">simplelist</tag> Element</title>\r
  27         <tgroup cols="3">\r
  28           <thead>\r
  29             <row>\r
  30               <entry>Attribute</entry>\r
  31               <entry>Values</entry>\r
  32               <entry>Description</entry>\r
  33             </row>\r
  34           </thead>\r
  35           <tbody>\r
  36             <row>\r
  37               <entry>\r
  38                 <tag class="attribute">type</tag>\r
  39               </entry>\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
  43             </row>\r
  44             <row>\r
  45               <entry>\r
  46                 <tag class="attribute">columns</tag>\r
  47               </entry>\r
  48               <entry>&gt;=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
  52             </row>\r
  53           </tbody>\r
  54         </tgroup>\r
  55       </table>\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
  59     </simplesect>\r
  60     <simplesect>\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>&lt;simplelist&gt;\r
  66   &lt;member&gt;Swedish Fish&lt;/member&gt;\r
  67   &lt;member&gt;Mike &amp; Ike&lt;/member&gt;\r
  68   &lt;member&gt;Sour Patch Kids&lt;/member&gt;\r
  69   &lt;member&gt;Gummy Bears&lt;/member&gt;\r
  70 &lt;/simplelist&gt;</programlisting>\r
  71       </example>\r
  72     </simplesect>\r
  73   </section>\r
  74   <section>\r
  75     <title>Itemized Lists</title>\r
  76     <simplesect>\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
  81     </simplesect>\r
  82     <simplesect>\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
  93         element.</para>\r
  94     </simplesect>\r
  95     <simplesect>\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>&lt;itemizedlist&gt;\r
 101   &lt;listitem&gt;\r
 102     &lt;para&gt;This is the first item in my list&lt;/para&gt;\r
 103   &lt;/listitem&gt;\r
 104   &lt;listitem&gt;\r
 105     &lt;para&gt;This is the second item in my list.&lt;/para&gt;\r
 106     &lt;para&gt;It has two paragraphs.&lt;/para&gt;\r
 107   &lt;/listitem&gt;\r
 108   &lt;listitem&gt;\r
 109     &lt;para&gt;This item has a sublist.&lt;/para&gt;\r
 110     &lt;itemizedlist&gt;\r
 111       &lt;listitem&gt;&lt;para&gt;first&lt;/para&gt;&lt;/listitem&gt;\r
 112       &lt;listitem&gt;&lt;para&gt;second&lt;/para&gt;&lt;/listitem&gt;\r
 113     &lt;/itemizedlist&gt;\r
 114   &lt;/listitem&gt;\r
 115 &lt;/itemizedlist&gt;</programlisting>\r
 116       </example>\r
 117     </simplesect>\r
 118   </section>\r
 119   <section>\r
 120     <title>Ordered List</title>\r
 121     <simplesect>\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
 126     </simplesect>\r
 127     <simplesect>\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
 133       <table pgwide="1">\r
 134         <title>Attributes of the <tag class="element">orderedlist</tag> Element</title>\r
 135         <tgroup cols="3">\r
 136           <thead>\r
 137             <row>\r
 138               <entry>Attribute</entry>\r
 139               <entry>Values</entry>\r
 140               <entry>Description</entry>\r
 141             </row>\r
 142           </thead>\r
 143           <tbody>\r
 144             <row>\r
 145               <entry>\r
 146                 <tag class="attribute">continuation</tag>\r
 147               </entry>\r
 148               <entry><tag class="attvalue">continues</tag>, <tag class="attvalue">restarts</tag>\r
 149                 (default)</entry>\r
 150               <entry>Specifies whether the item numbering should restart at one or continue from the\r
 151                 previous ordered list.</entry>\r
 152             </row>\r
 153             <row>\r
 154               <entry>\r
 155                 <tag class="attribute">inheritnum</tag>\r
 156               </entry>\r
 157               <entry><tag class="attvalue">inherit</tag>, <tag class="attvalue">ignore</tag>\r
 158                 (default)</entry>\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
 161             </row>\r
 162             <row>\r
 163               <entry>\r
 164                 <tag class="attribute">numeration</tag>\r
 165               </entry>\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
 170             </row>\r
 171           </tbody>\r
 172         </tgroup>\r
 173       </table>\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
 179         element.</para>\r
 180     </simplesect>\r
 181   </section>\r
 182   <section xml:id="VariableLists">\r
 183     <title>Variable Lists</title>\r
 184     <simplesect>\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
 191         <varlistentry>\r
 192           <term>Kitchen</term>\r
 193           <listitem>\r
 194             <para>The room where food is stored and prepared.</para>\r
 195           </listitem>\r
 196         </varlistentry>\r
 197         <varlistentry>\r
 198           <term>Garage</term>\r
 199           <listitem>\r
 200             <para>Where the cars are parked.</para>\r
 201             <note>\r
 202               <para>Bikes are also here.</para>\r
 203             </note>\r
 204           </listitem>\r
 205         </varlistentry>\r
 206         <varlistentry>\r
 207           <term>Living room</term>\r
 208           <term>Family room</term>\r
 209           <listitem>\r
 210             <para>This is where we watch TV.</para>\r
 211           </listitem>\r
 212         </varlistentry>\r
 213       </variablelist>\r
 214     </simplesect>\r
 215     <simplesect>\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
 226       <itemizedlist>\r
 227         <listitem>\r
 228           <para><tag class="element">term</tag></para>\r
 229         </listitem>\r
 230         <listitem>\r
 231           <para><tag class="element">listitem</tag></para>\r
 232         </listitem>\r
 233       </itemizedlist>\r
 234     </simplesect>\r
 235     <simplesect>\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
 241     </simplesect>\r
 242     <simplesect>\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
 250     </simplesect>\r
 251     <simplesect>\r
 252       <title>Example</title>\r
 253       <para><xref linkend="varmarkup"/> shows the markup representing <xref linkend="varexample"\r
 254         />.</para>\r
 255       <example xml:id="varmarkup">\r
 256         <title>Variable List Markup</title>\r
 257         <programlisting>&lt;variablelist xml:id="varexample"&gt;\r
 258   &lt;title&gt;List of Rooms&lt;/title&gt;\r
 259   &lt;varlistentry&gt;\r
 260     &lt;term&gt;Kitchen&lt;/term&gt;\r
 261     &lt;listitem&gt;\r
 262       &lt;para&gt;The room where food is stored and prepared.&lt;/para&gt;\r
 263     &lt;/listitem&gt;\r
 264   &lt;/varlistentry&gt;\r
 265   &lt;varlistentry&gt;\r
 266     &lt;term&gt;Garage&lt;/term&gt;\r
 267     &lt;listitem&gt;\r
 268       &lt;para&gt;Where the cars are parked.&lt;/para&gt;\r
 269       &lt;note&gt;\r
 270         &lt;para&gt;Bikes are also here.&lt;/para&gt;\r
 271       &lt;/note&gt;\r
 272     &lt;/listitem&gt;\r
 273   &lt;/varlistentry&gt;\r
 274   &lt;varlistentry&gt;\r
 275     &lt;term&gt;Living room&lt;/term&gt;\r
 276     &lt;term&gt;Family room&lt;/term&gt;\r
 277     &lt;listitem&gt;\r
 278       &lt;para&gt;This is where we watch TV.&lt;/para&gt;\r
 279     &lt;/listitem&gt;\r
 280   &lt;/varlistentry&gt;\r
 281 &lt;/variablelist&gt;</programlisting>\r
 282       </example>\r
 283     </simplesect>\r
 284   </section>\r
 285   <section xml:id="GlossList">\r
 286     <title>Glossary Lists</title>\r
 287     <simplesect>\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
 297           <glossdef>\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
 302           <glossdef>\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
 308           <glossdef>\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
 314         <glossentry>\r
 315           <glossterm>service consumer</glossterm>\r
 316           <glosssee otherterm="consumerdef"/></glossentry>\r
 317       </glosslist>\r
 318     </simplesect>\r
 319     <simplesect>\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
 330     </simplesect>\r
 331     <simplesect>\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
 337         attribute.</para>\r
 338       <note>\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
 342       </note>\r
 343     </simplesect>\r
 344     <simplesect>\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 &quot;See&quot; 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
 355     </simplesect>\r
 356     <simplesect>\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>&lt;glosslist xml:id="glossexample" xreflabel="List of terms";&gt;\r
 364   &lt;glossentry xml:id="consumerdef"&gt;\r
 365     &lt;glossterm&gt;consumer&lt;/glossterm&gt;\r
 366     &lt;glossdef&gt;\r
 367       &lt;para&gt;The end user of a service, also called a \r
 368          client for that service.&lt;/para&gt;\r
 369     &lt;/glossdef&gt;\r
 370   &lt;/glossentry&gt;\r
 371   &lt;glossentry xml:id="endptdef"&gt;\r
 372     &lt;glossterm&gt;endpoint&lt;/glossterm&gt;\r
 373     &lt;glossdef&gt;\r
 374       &lt;para&gt;The point of contact that a \r
 375          &lt;glossterm linkend=&quot;servicedef&quot;&gt;service&lt;/glossterm&gt; \r
 376         provides for its \r
 377         &lt;glossterm linkend=&quot;consumerdef&quot;&gt;consumers&lt;/glossterm&gt;.\r
 378     &lt;/para&gt;\r
 379     &lt;/glossdef&gt;\r
 380   &lt;/glossentry&gt;\r
 381   &lt;glossentry xml:id="servicedef"&gt;\r
 382     &lt;glossterm&gt;service&lt;/glossterm&gt;\r
 383     &lt;glossdef&gt;\r
 384       &lt;para&gt;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         &lt;glossterm linkend=&quot;endptdef&quot;&gt;endpoint&lt;/glossterm&gt;.\r
 388         In a service-oriented network, services are defined          \r
 389         by a service contract.&lt;/para&gt;\r
 390     &lt;/glossdef&gt;\r
 391   &lt;/glossentry&gt;\r
 392   &lt;glossentry&gt;\r
 393     &lt;glossterm&gt;service consumer&lt;/glossterm&gt;\r
 394     &lt;glosssee otherterm=&quot;consumerdef&quot; /&gt;\r
 395   &lt;/glossentry&gt;\r
 396 &lt;/glosslist&gt;</programlisting>\r
 397       </example>\r
 398     </simplesect>\r
 399   </section>\r
 400 </chapter>\r