docs/1.6/tables.xml

   1 <?xml version='1.0' encoding='UTF-8'?>\r
   2 <chapter xmlns="http://docbook.org/ns/docbook"\r
   3 xmlns:xi="http://www.w3.org/2001/XInclude"\r
   4 xmlns:xl="http://www.w3.org/1999/xlink"\r
   5 version="5.0"\r
   6 xml:id="tables">\r
   7   <title>Tables</title>\r
   8   <section>\r
   9     <title>Types of Tables</title>\r
  10     <para>There are two types of tables in DocBook:</para>\r
  11     <itemizedlist>\r
  12       <listitem>\r
  13         <para>Informal tables</para>\r
  14       </listitem>\r
  15       <listitem>\r
  16         <para>Tables</para>\r
  17       </listitem>\r
  18     </itemizedlist>\r
  19     <para>An informal table is simply a table that does not have a title. Tables\r
  20 must have a title element and are listed in a list of tables if it is\r
  21 generated.</para>\r
  22   </section>\r
  23   <section>\r
  24     <title>Specifying a Table</title>\r
  25     <para>Both informal tables and tables use the same markup elements to define\r
  26 their structure. The differences are as follows:</para>\r
  27     <itemizedlist>\r
  28       <listitem>\r
  29         <para>Informal tables are specified using the <tag class="element">informaltable</tag> element and tables are specified using\r
  30 the <tag class="element">table</tag> element.</para>\r
  31       </listitem>\r
  32       <listitem>\r
  33         <para>Informal tables cannot contain a <tag class="element">title</tag> element and tables require a <tag class="element">title</tag> element.</para>\r
  34       </listitem>\r
  35     </itemizedlist>\r
  36     <para>Creating a table involves the following steps:</para>\r
  37     <procedure>\r
  38       <step>\r
  39         <para>Specify the proper root element.</para>\r
  40       </step>\r
  41       <step>\r
  42         <para>If you are creating a table, add a <tag class="element">title</tag> element.</para>\r
  43       </step>\r
  44       <step>\r
  45         <para>Add a <tag class="element">tgroup</tag> element to wrap the\r
  46 contents of the table.</para>\r
  47       </step>\r
  48       <step>\r
  49         <para>If needed, add <tag class="element">colspec</tag> elements to\r
  50 specify properties for specific columns.</para>\r
  51       </step>\r
  52       <step>\r
  53         <para>If needed, add <tag class="element">spanspec</tag> elements to\r
  54 define reusable column spans.</para>\r
  55       </step>\r
  56       <step>\r
  57         <para>If desired, add a <tag>thead</tag> element to specify a header\r
  58 row.</para>\r
  59         <substeps>\r
  60           <step>\r
  61             <para>Add a <tag class="element">row</tag> element.</para>\r
  62           </step>\r
  63           <step>\r
  64             <para>Add an <tag class="element">entry</tag> element for each column\r
  65 heading.</para>\r
  66           </step>\r
  67         </substeps>\r
  68       </step>\r
  69       <step>\r
  70         <para>Add a <tag class="element">tbody</tag> element to contain the\r
  71 body of the table.</para>\r
  72         <substeps>\r
  73           <step>\r
  74             <para>Add one <tag class="element">row</tag> element for each row in\r
  75 the table.</para>\r
  76           </step>\r
  77           <step>\r
  78             <para>In the <tag class="element">row</tag> elements, add an <tag class="element">entry</tag> element for each value that appear in the\r
  79 row.</para>\r
  80           </step>\r
  81         </substeps>\r
  82       </step>\r
  83     </procedure>\r
  84     <section>\r
  85       <title>Table Root Elements</title>\r
  86       <para>Depending on the type of table you are using you will use either the\r
  87 <tag class="element">informaltable</tag> element or the <tag class="element">table</tag> element as the root element of your table.\r
  88 Both elements use the attributes listed in <xref linkend="rootattrs"/>.</para>\r
  89       <table frame="all" xml:id="rootattrs" pgwide="1">\r
  90         <title>Attributes for <tag class="element">table</tag> Element and <tag class="element">informaltable</tag> Element</title>\r
  91         <tgroup cols="3" colsep="1" rowsep="1">\r
  92           <colspec colwidth="1.5in"/>\r
  93           <thead>\r
  94             <row>\r
  95               <entry align="center">Attribute</entry>\r
  96               <entry align="center">Description</entry>\r
  97               <entry align="center">Values</entry>\r
  98             </row>\r
  99           </thead>\r
 100           <tbody>\r
 101             <row>\r
 102               <entry>\r
 103                 <indexterm><primary>table</primary><secondary>pgwide</secondary></indexterm>\r
 104                 <tag class="attribute">pgwide</tag>\r
 105               </entry>\r
 106               <entry>Specifies whether the table will be span the whole page in PDF output.</entry>\r
 107               <entry><tag class="attvalue">0</tag> (default), <tag class="attvalue">1</tag></entry>\r
 108             </row>\r
 109             <row>\r
 110               <entry>\r
 111                 <tag class="attribute">colsep</tag>\r
 112               </entry>\r
 113               <entry>Specifies whether a rule will be drawn between the columns in the table.</entry>\r
 114               <entry><tag class="attvalue">0</tag>, <tag class="attvalue">1</tag> (default)</entry>\r
 115             </row>\r
 116             <row>\r
 117               <entry>\r
 118                 <tag class="attribute">frame</tag>\r
 119               </entry>\r
 120               <entry>Specifies how the table will be framed.</entry>\r
 121               <entry><tag class="attvalue">all</tag>, <tag class="attvalue">bottom</tag>, <tag class="attvalue">none</tag>, <tag class="attvalue">sides</tag>, <tag class="attvalue">top</tag>, <tag class="attvalue">topbot</tag></entry>\r
 122             </row>\r
 123             <row>\r
 124               <entry>\r
 125                 <tag class="attribute">orient</tag>\r
 126               </entry>\r
 127               <entry>Specifies how the table will be oriented in relationship to the rest of the text.</entry>\r
 128               <entry><tag class="attvalue">land</tag>, <tag class="attvalue">port</tag> (default)</entry>\r
 129             </row>\r
 130             <row>\r
 131               <entry>\r
 132                 <tag class="attribute">rowsep</tag>\r
 133               </entry>\r
 134               <entry>Specifies whether a rule will be drawn between the rows in the table.</entry>\r
 135               <entry><tag class="attvalue">0</tag>, <tag class="attvalue">1</tag> (default)</entry>\r
 136             </row>\r
 137             <row>\r
 138               <entry>\r
 139                 <tag class="attribute">xml:id</tag>\r
 140               </entry>\r
 141               <entry>Specifies a unique identifier used to reference the table.</entry>\r
 142               <entry>a unique string</entry>\r
 143             </row>\r
 144             <row>\r
 145               <entry>\r
 146                 <tag class="attribute">xreflabel</tag>\r
 147               </entry>\r
 148               <entry>\r
 149                 <para>Specifies a label to be used when cross referencing the table.</para>\r
 150               </entry>\r
 151               <entry>a string</entry>\r
 152             </row>\r
 153           </tbody>\r
 154         </tgroup>\r
 155       </table>\r
 156       <note>\r
 157         <para>Attributes not listed in <xref linkend="rootattrs"/> are not used in Evergreen' documentation.</para>\r
 158       </note>\r
 159     </section>\r
 160     <section>\r
 161       <title>The tgroup Element</title>\r
 162       <indexterm><primary>tgroup</primary></indexterm>\r
 163       <para>The <tag class="element">tgroup</tag> element groups together the logical components of a table. It specifies the number of columns in a table and contains the column and span specifications used by the table. All of the rows, including the header, are defined inside of the <tag class="element">tgroup</tag> element.</para>\r
 164       <para>While most tables contain a single <tag class="element">tgroup</tag> element, it is possible for a complex table to have multiple tgroup elements. In such a case, each <tag class="element">tgroup</tag> element would define a unique portion of table where the columns and spans had different specifications.</para>\r
 165       <simplesect>\r
 166         <title>Attributes</title>\r
 167         <para><xref linkend="tgroupattrs"/> shows the attributes for the <tag class="element">tgroup</tag> element. Attributes in the <tag class="element">tgroup</tag> element override the corresponding attributes\r
 168 from the table&apos;s root element.</para>\r
 169         <table xml:id="tgroupattrs" pgwide="1">\r
 170           <title>Attributes for the <tag class="element">tgroup</tag> Element</title>\r
 171           <tgroup cols="3">\r
 172             <colspec colwidth="1.5in"/>\r
 173             <thead>\r
 174               <row>\r
 175                 <entry align="center">Attribute</entry>\r
 176                 <entry align="center">Description</entry>\r
 177                 <entry align="center">Values</entry>\r
 178               </row>\r
 179             </thead>\r
 180             <tbody>\r
 181               <row>\r
 182                 <entry>\r
 183                   <tag class="attribute">colsep</tag>\r
 184                 </entry>\r
 185                 <entry>Specifies whether a rule will be drawn between the columns of the group.</entry>\r
 186                 <entry><tag class="attvalue">0</tag>, <tag class="attvalue">1</tag> (default)</entry>\r
 187               </row>\r
 188               <row>\r
 189                 <entry>\r
 190                   <tag class="attribute">rowsep</tag>\r
 191                 </entry>\r
 192                 <entry>Specifies whether a rule will be drawn between the rows of the group.</entry>\r
 193                 <entry><tag class="attvalue">0</tag>, <tag class="attvalue">1</tag> (default)</entry>\r
 194               </row>\r
 195               <row>\r
 196                 <entry>\r
 197                   <tag>align</tag>\r
 198                 </entry>\r
 199                 <entry>Specifies the horizontal alignment of the entries in the group.</entry>\r
 200                 <entry><tag class="attvalue">center</tag>, <tag class="attvalue">justify</tag>, <tag class="attvalue">right</tag>, <tag class="attvalue">left</tag> (default)</entry>\r
 201               </row>\r
 202               <row>\r
 203                 <entry>\r
 204                   <tag>cols</tag>\r
 205                 </entry>\r
 206                 <entry>A required attribute that specifies the number of columns in the group.</entry>\r
 207                 <entry>&gt;=1</entry>\r
 208               </row>\r
 209             </tbody>\r
 210           </tgroup>\r
 211         </table>\r
 212         <note>\r
 213           <para>Attributes not listed in <xref linkend="tgroupattrs"/> are not used in Evergreen' documentation.</para>\r
 214         </note>\r
 215       </simplesect>\r
 216       <simplesect>\r
 217         <title>Example</title>\r
 218         <para><xref linkend="groupexample"/> shows the markup for a <tag class="element">tgroup</tag> element that defines a 3 column table.</para>\r
 219         <informalexample xml:id="groupexample" xreflabel="The following">\r
 220           <programlisting>&lt;informaltable ...&gt;\r
 221   &lt;tgroup cols=&quot;3&quot; colsep=&quot;1&quot; rowsep=&quot;1&quot; &gt;\r
 222     ...\r
 223   &lt;/tgroup&gt;\r
 224 &lt;/table&gt;</programlisting>\r
 225         </informalexample>\r
 226       </simplesect>\r
 227     </section>\r
 228     <section xml:id="ColProps">\r
 229       <title>Specifying Column Properties</title>\r
 230       <para>If you desire, you can specify a number of the display properties for\r
 231 the column in a table by adding <tag class="element">colspec</tag>\r
 232 elements to a <tag class="element">tgroup</tag> element. A <tag class="element">colspec</tag> element defines properties for all of the\r
 233 entries in one column in a group. You can set different properties for each\r
 234 column in a group.</para>\r
 235       <simplesect>\r
 236         <title>Attributes</title>\r
 237         <para><xref linkend="colattrs"/> shows the attributes for the <tag class="element">colspec</tag> element. Attributes in the <tag class="element">colspec</tag> element override corresponding attributes in\r
 238 the parent <tag class="element">tgroup</tag> element and the table&apos;s\r
 239 root element.</para>\r
 240         <table xml:id="colattrs" pgwide="1">\r
 241           <title>Attributes for the <tag class="element">colspec</tag> Element</title>\r
 242           <tgroup cols="3">\r
 243             <colspec colwidth="1.5in"/>\r
 244             <thead>\r
 245               <row>\r
 246                 <entry align="center">Attribute</entry>\r
 247                 <entry align="center">Description</entry>\r
 248                 <entry align="center">Values</entry>\r
 249               </row>\r
 250             </thead>\r
 251             <tbody>\r
 252               <row>\r
 253                 <entry>\r
 254                   <tag class="attribute">colsep</tag>\r
 255                 </entry>\r
 256                 <entry>Specifies whether a rule will be drawn to the right of entries in the column.</entry>\r
 257                 <entry><tag class="attvalue">0</tag>, <tag class="attvalue">1</tag> (default)</entry>\r
 258               </row>\r
 259               <row>\r
 260                 <entry>\r
 261                   <tag class="attribute">rowsep</tag>\r
 262                 </entry>\r
 263                 <entry>Specifies whether a rule will be drawn between the rows in the column.</entry>\r
 264                 <entry><tag class="attvalue">0</tag>, <tag class="attvalue">1</tag> (default)</entry>\r
 265               </row>\r
 266               <row>\r
 267                 <entry>\r
 268                   <tag>align</tag>\r
 269                 </entry>\r
 270                 <entry>Specifies the horizontal alignment of the entries in the column.</entry>\r
 271                 <entry><tag class="attvalue">center</tag>, <tag class="attvalue">justify</tag>, <tag class="attvalue">right</tag>, <tag class="attvalue">left</tag> (default)</entry>\r
 272               </row>\r
 273               <row>\r
 274                 <entry>\r
 275                   <tag>colnum</tag>\r
 276                 </entry>\r
 277                 <entry>Specifies the number of the column being specified.</entry>\r
 278                 <entry>1&lt;=<replaceable>X</replaceable>&lt;=number of columns</entry>\r
 279               </row>\r
 280               <row>\r
 281                 <entry>\r
 282                   <tag class="attribute">colname</tag>\r
 283                 </entry>\r
 284                 <entry>Specifies a unique identifier by which the column can be referenced by other elements in the group.</entry>\r
 285                 <entry>a unique string</entry>\r
 286               </row>\r
 287               <row>\r
 288                 <entry>\r
 289                   <tag class="attribute">colwidth</tag>\r
 290                 </entry>\r
 291                 <entry>Specifies the width of the column.</entry>\r
 292                 <entry>Can be either a fixed measure using either points (pts), inches (in), or centimeters (cm).</entry>\r
 293               </row>\r
 294             </tbody>\r
 295           </tgroup>\r
 296         </table>\r
 297         <note>\r
 298           <para>Attributes not listed in <xref linkend="colattrs"/> are not used in  Evergreen' documentation.</para>\r
 299         </note>\r
 300       </simplesect>\r
 301       <simplesect>\r
 302         <title>Example</title>\r
 303         <para><xref linkend="colspecexample"/> shows the markup for specifying a\r
 304 column that is two inches wide and whose content is justified.</para>\r
 305         <example xml:id="colspecexample">\r
 306           <?dbfo pgwide="1"?>\r
 307           <title>Setting Column Properties</title>\r
 308           <programlisting>&lt;table ...&gt;\r
 309   &lt;title&gt;...&lt;/title&gt;\r
 310   &lt;tgroup ... &gt;\r
 311     &lt;colspec align=&quot;justify&quot; colwidth=&quot;2in&quot; colname=&quot;2incol&quot; /&gt;\r
 312     ...\r
 313   &lt;/tgroup&gt;\r
 314 &lt;/table&gt;</programlisting>\r
 315         </example>\r
 316       </simplesect>\r
 317     </section>\r
 318     <section xml:id="SpanProps">\r
 319       <title>Defining Spans</title>\r
 320       <para>DocBook allows you to define properties for cells that span columns and\r
 321 name them for use by the cells in the group. To define a span you use the\r
 322 <tag class="element">spanspec</tag> element.</para>\r
 323       <simplesect>\r
 324         <title>Required Attributes</title>\r
 325         <para>The <tag class="element">spanspec</tag> element has three\r
 326 required attributes as described in <xref linkend="spanreqattrs"/>.</para>\r
 327         <table xml:id="spanreqattrs" pgwide="1">\r
 328           <title>Required Attributes for the <tag class="element">spanspec</tag> Element</title>\r
 329           <tgroup cols="2">\r
 330             <colspec colwidth="1.5in"/>\r
 331             <thead>\r
 332               <row>\r
 333                 <entry align="center">Attribute</entry>\r
 334                 <entry align="center">Description</entry>\r
 335               </row>\r
 336             </thead>\r
 337             <tbody>\r
 338               <row>\r
 339                 <entry>\r
 340                   <tag class="attribute">spanname</tag>\r
 341                 </entry>\r
 342                 <entry>Specifies the name by which cells will refer to the span.</entry>\r
 343               </row>\r
 344               <row>\r
 345                 <entry>\r
 346                   <tag class="attribute">namest</tag>\r
 347                 </entry>\r
 348                 <entry>Specifies the name, as declared in a <tag class="element">colspec</tag> element&apos;s <tag class="attribute">colname</tag> attribute, of the starting column for the span.</entry>\r
 349               </row>\r
 350               <row>\r
 351                 <entry>\r
 352                   <tag>nameend</tag>\r
 353                 </entry>\r
 354                 <entry>Specifies the name, as declared in a <tag class="element">colspec</tag> element&apos;s <tag class="attribute">colname</tag> attribute, of the ending column for the span.</entry>\r
 355               </row>\r
 356             </tbody>\r
 357           </tgroup>\r
 358         </table>\r
 359       </simplesect>\r
 360       <simplesect>\r
 361         <title>Optional Attributes</title>\r
 362         <para>In addition to the required attributes, the <tag class="element">spanspec</tag> element can also have the attributes\r
 363 described in <xref linkend="spanoptattrs"/>. Attributes in the <tag class="element">spanspec</tag> element override corresponding attributes\r
 364 in the parent <tag class="element">tgroup</tag> element and the\r
 365 table&apos;s root element.</para>\r
 366         <table xml:id="spanoptattrs" pgwide="1">\r
 367           <title>Optional Attributes for the <tag class="element">spanspec</tag> Element</title>\r
 368           <tgroup cols="3">\r
 369             <colspec colwidth="1.5in"/>\r
 370             <thead>\r
 371               <row>\r
 372                 <entry align="center">Attribute</entry>\r
 373                 <entry align="center">Description</entry>\r
 374                 <entry align="center">Values</entry>\r
 375               </row>\r
 376             </thead>\r
 377             <tbody>\r
 378               <row>\r
 379                 <entry>\r
 380                   <tag class="attribute">colsep</tag>\r
 381                 </entry>\r
 382                 <entry>Specifies whether a rule will be drawn to the right of entries in the span.</entry>\r
 383                 <entry><tag class="attvalue">0</tag>, <tag class="attvalue">1</tag> (default)</entry>\r
 384               </row>\r
 385               <row>\r
 386                 <entry>\r
 387                   <tag class="attribute">rowsep</tag>\r
 388                 </entry>\r
 389                 <entry>Specifies whether a rule will be drawn below the rows in the span.</entry>\r
 390                 <entry><tag class="attvalue">0</tag>, <tag class="attvalue">1</tag> (default)</entry>\r
 391               </row>\r
 392               <row>\r
 393                 <entry>\r
 394                   <tag>align</tag>\r
 395                 </entry>\r
 396                 <entry>Specifies the horizontal alignment of the entry in the span.</entry>\r
 397                 <entry><tag class="attvalue">center</tag>, <tag class="attvalue">justify</tag>, <tag class="attvalue">right</tag>, <tag class="attvalue">left</tag> (default)</entry>\r
 398               </row>\r
 399             </tbody>\r
 400           </tgroup>\r
 401         </table>\r
 402         <note>\r
 403           <para>Attributes not listed in <xref linkend="spanoptattrs"/> are not used in Evergreen' documentation.</para>\r
 404         </note>\r
 405       </simplesect>\r
 406       <simplesect>\r
 407         <title>Example</title>\r
 408         <para><xref linkend="spanexample"/> shows the markup for a span that crosses\r
 409 the second and third column of a five column table. The contents of the span\r
 410 are centered.</para>\r
 411         <example xml:id="spanexample">\r
 412           <?dbfo pgwide="1"?>\r
 413           <title>Defining a Span</title>\r
 414           <programlisting>&lt;informaltable ...&gt;\r
 415   &lt;tgroup  cols=&quot;5&quot; &gt;\r
 416     &lt;colspec colnum=&quot;2&quot; colname=&quot;c2&quot; /&gt;\r
 417     &lt;colspec colnum=&quot;3&quot; colname=&quot;c3&quot; /&gt;\r
 418     &lt;spanspec spanname=&quot;midspan&quot; namest=&quot;c2&quot; nameend=&quot;c3&quot;\r
 419               align=&quot;center&quot; /&gt;\r
 420     ...\r
 421 &lt;/informaltable&gt;</programlisting>\r
 422         </example>\r
 423       </simplesect>\r
 424     </section>\r
 425     <section xml:id="TableHead">\r
 426       <title>Adding a Heading Row to a Table</title>\r
 427       <para>Tables in Evergreen documentation generally have one heading row. They are specified\r
 428 using a <tag class="element">thead</tag> element. The <tag class="element">thead</tag> element is a child of a\r
 429 <tag>tgroup</tag> element. It must be placed after any <tag class="element">colspec</tag> elements and <tag class="element">spanspec</tag> elements. It should also be placed before\r
 430 any <tag class="element">tbody</tag> elements.</para>\r
 431       <simplesect>\r
 432         <title>Attributes</title>\r
 433         <para><xref linkend="theadattrs"/> lists the attributes of the <tag class="element">thead</tag> element.</para>\r
 434         <table xml:id="theadattrs" pgwide="1">\r
 435           <title>Attributes for the <tag class="element">thead</tag> Element</title>\r
 436           <tgroup cols="3">\r
 437             <colspec colwidth="1.5in"/>\r
 438             <thead>\r
 439               <row>\r
 440                 <entry align="center">Attribute</entry>\r
 441                 <entry align="center">Description</entry>\r
 442                 <entry align="center">Values</entry>\r
 443               </row>\r
 444             </thead>\r
 445             <tbody>\r
 446               <row>\r
 447                 <entry>\r
 448                   <tag>valign</tag>\r
 449                 </entry>\r
 450                 <entry>Specifies the vertical alignment of the entry in the heading.</entry>\r
 451                 <entry><tag class="attvalue">top</tag>, <tag class="attvalue">bottom</tag>, <tag class="attvalue">middle</tag> (default)</entry>\r
 452               </row>\r
 453             </tbody>\r
 454           </tgroup>\r
 455         </table>\r
 456       </simplesect>\r
 457       <simplesect>\r
 458         <title>Adding content</title>\r
 459         <para>The content of the heading row is specified using a single <tag class="element">row</tag> element and one entry <tag class="element">child</tag> element for each column in the table. For more\r
 460 information on the row element and the entry element see <xref linkend="rowsect"/> and <xref linkend="entrysect"/>.</para>\r
 461       </simplesect>\r
 462       <simplesect>\r
 463         <title>Example</title>\r
 464         <para><xref linkend="theadexample"/> shows the markup for tables used in this\r
 465 chapter.</para>\r
 466         <example xml:id="theadexample">\r
 467           <title>Adding a Table Header</title>\r
 468           <programlisting>&lt;table ...&gt;\r
 469   &lt;tgroup  cols=&quot;3&quot; &gt;\r
 470     &lt;colspec ... /&gt;\r
 471     &lt;thead&gt;\r
 472       &lt;row&gt;\r
 473         &lt;entry align=&quot;center&quot;&gt;\r
 474           Attribute\r
 475         &lt;/entry&gt;\r
 476         &lt;entry align=&quot;center&quot;&gt;\r
 477           Description\r
 478         &lt;/entry&gt;\r
 479         &lt;entry align=&quot;center&quot;&gt;\r
 480           Values\r
 481         &lt;/entry&gt;\r
 482       &lt;/row&gt;\r
 483     &lt;/thead&gt;\r
 484     ...\r
 485   &lt;/tgroup&gt;\r
 486 &lt;/informaltable&gt;</programlisting>\r
 487         </example>\r
 488       </simplesect>\r
 489     </section>\r
 490     <section xml:id="TableRows">\r
 491       <title>Adding Rows to a Table</title>\r
 492       <para>The rows that make up the body of a table are defined inside of a\r
 493 <tag class="element">tbody</tag> element. Each row in the table is\r
 494 defined using a <tag class="element">row</tag> element. The contents\r
 495 of each column in the row is defined using an <tag class="element">entry</tag> element.</para>\r
 496       <simplesect>\r
 497         <title>The <tag class="element">tbody</tag> Element</title>\r
 498         <para>The <tag class="element">tbody</tag> element is a wrapper for\r
 499 all of the rows in the body of a group. It is placed after all of the <tag class="element">colspec</tag> elements, all of the <tag class="element">spanspec</tag> elements, and the <tag class="element">thead</tag> element. It has a single attribute, <tag class="attribute">valign</tag>, that is described in <xref linkend="theadattrs"/>.</para>\r
 500       </simplesect>\r
 501       <simplesect xml:id="rowsect">\r
 502         <title>The <tag class="element">row</tag> Element</title>\r
 503         <para>Rows in a table are defined using the <tag>row</tag> element.\r
 504 Each <tag>row</tag> element wraps a number of <tag>entry</tag>\r
 505 children elements that cannot exceed the number columns specified in the\r
 506 <tag>tgroup</tag> element&apos;s <tag>cols</tag> attribute. It is\r
 507 possible to have less <tag>entry</tag> child elements. This can happen\r
 508 when you wish to have empty columns, when one entry spans multiple columns, or\r
 509 if there is an entry from a previous row that vertically spans the row being\r
 510 specified.</para>\r
 511         <important>\r
 512           <para>When spans are being used the number of <tag>entry</tag>\r
 513 elements plus the number of columns being spanned cannot add up to more than\r
 514 the number of columns defined for the group.</para>\r
 515         </important>\r
 516         <para>The <tag class="element">row</tag> element has two attributes as\r
 517 described in <xref linkend="rowattrs"/>. Attributes in the <tag class="element">row</tag> element override corresponding attributes in the\r
 518 parent <tag class="element">tbody</tag> element, the enclosing\r
 519 <tag class="element">tgroup</tag> element, the <tag class="element">colspec</tag> elements in the group, and the table&apos;s root\r
 520 element.</para>\r
 521         <table xml:id="rowattrs" pgwide="1">\r
 522           <title>Attributes for the <tag class="element">row</tag> Element</title>\r
 523           <tgroup cols="3">\r
 524             <colspec colwidth="1.5in"/>\r
 525             <thead>\r
 526               <row>\r
 527                 <entry align="center">Attribute</entry>\r
 528                 <entry align="center">Description</entry>\r
 529                 <entry align="center">Values</entry>\r
 530               </row>\r
 531             </thead>\r
 532             <tbody>\r
 533               <row>\r
 534                 <entry>\r
 535                   <tag class="attribute">rowsep</tag>\r
 536                 </entry>\r
 537                 <entry>Specifies whether a rule will be drawn below all of the entries in the row.</entry>\r
 538                 <entry><tag class="attvalue">0</tag>, <tag class="attvalue">1</tag> (default)</entry>\r
 539               </row>\r
 540               <row>\r
 541                 <entry>\r
 542                   <tag>valign</tag>\r
 543                 </entry>\r
 544                 <entry>Specifies the vertical alignment of the entry in the heading.</entry>\r
 545                 <entry><tag class="attvalue">top</tag>, <tag class="attvalue">bottom</tag>, <tag class="attvalue">middle</tag> (default)</entry>\r
 546               </row>\r
 547             </tbody>\r
 548           </tgroup>\r
 549         </table>\r
 550       </simplesect>\r
 551       <simplesect xml:id="entrysect">\r
 552         <title>The <tag class="element">entry</tag> Element</title>\r
 553         <para>The contents of of a table are specified using <tag>entry</tag>\r
 554 elements. <tag>entry</tag> elements are children of the\r
 555 <tag>row</tag> element and hold the contents for a column in the\r
 556 row.</para>\r
 557         <para>The contents of a table entry can be specified using either text with\r
 558 in-line markup elements or using block-level markup elements such as the\r
 559 <tag class="element">para</tag> element, the <tag class="element">procedure</tag> element, or one of the list types.\r
 560 However, if you intend to use one of the block-level markup elements you must\r
 561 place all of the content inside a block-level element. For example, if you\r
 562 want to use a list in a table entry, along with some text outside the list,\r
 563 you must place all of the content, including the list, inside a <tag class="element">para</tag> element.</para>\r
 564         <para>The <tag class="element">entry</tag> element&apos;s attributes are\r
 565 described in <xref linkend="entryattrs"/>. Attributes in the <tag class="element">entry</tag> element override corresponding attributes in\r
 566 the parent <tag class="element">row</tag> element, the enclosing\r
 567 <tag class="element">tbody</tag> element, the enclosing <tag class="element">tgroup</tag> element, the <tag class="element">colspec</tag> elements in the group, the <tag class="element">spansec</tag> elements in the group, and the table&apos;s root\r
 568 element.</para>\r
 569         <table xml:id="entryattrs" pgwide="1">\r
 570           <title>Attributes for the <tag class="element">entry</tag> Element</title>\r
 571           <tgroup cols="3">\r
 572             <colspec colwidth="1.5in"/>\r
 573             <thead>\r
 574               <row>\r
 575                 <entry align="center">Attribute</entry>\r
 576                 <entry align="center">Description</entry>\r
 577                 <entry align="center">Values</entry>\r
 578               </row>\r
 579             </thead>\r
 580             <tbody>\r
 581               <row>\r
 582                 <entry>\r
 583                   <tag class="attribute">rowsep</tag>\r
 584                 </entry>\r
 585                 <entry>Specifies whether a rule will be drawn below the entry.</entry>\r
 586                 <entry><tag class="attvalue">0</tag>, <tag class="attvalue">1</tag> (default)</entry>\r
 587               </row>\r
 588               <row>\r
 589                 <entry>\r
 590                   <tag>valign</tag>\r
 591                 </entry>\r
 592                 <entry>Specifies the vertical alignment of the entry.</entry>\r
 593                 <entry><tag class="attvalue">top</tag>, <tag class="attvalue">bottom</tag>, <tag class="attvalue">middle</tag> (default)</entry>\r
 594               </row>\r
 595               <row>\r
 596                 <entry>\r
 597                   <tag class="attribute">colsep</tag>\r
 598                 </entry>\r
 599                 <entry>Specifies whether a rule will be drawn to the right of the entry.</entry>\r
 600                 <entry><tag class="attvalue">0</tag>, <tag class="attvalue">1</tag> (default)</entry>\r
 601               </row>\r
 602               <row>\r
 603                 <entry>\r
 604                   <tag class="attribute">namest</tag>\r
 605                 </entry>\r
 606                 <entry>Specifies the name of the left-most column the entry will span.</entry>\r
 607                 <entry>The value of the <tag class="attribute">name</tag> attribute of the <tag class="element">colspec</tag> element defining the left-most column of the span.</entry>\r
 608               </row>\r
 609               <row>\r
 610                 <entry>\r
 611                   <tag class="attribute">nameend</tag>\r
 612                 </entry>\r
 613                 <entry>Specifies the right-most column the entry will span.</entry>\r
 614                 <entry>The value of the <tag class="attribute">name</tag> attribute of the <tag class="element">colspec</tag> element defining the right-most column of the span.</entry>\r
 615               </row>\r
 616               <row>\r
 617                 <entry>\r
 618                   <tag class="attribute">spanname</tag>\r
 619                 </entry>\r
 620                 <entry>Specifies a defined span to use for the entry. This attribute should not be used with <tag class="attribute">namest</tag> and <tag class="attribute">nameend</tag>.</entry>\r
 621                 <entry>The value of the <tag class="attribute">name</tag> attribute of the <tag class="element">spanspec</tag> element defining the span to use for the entry.</entry>\r
 622               </row>\r
 623               <row>\r
 624                 <entry>\r
 625                   <tag class="attribute">align</tag>\r
 626                 </entry>\r
 627                 <entry>Specifies the horizontal alignment of the contents in the entry.</entry>\r
 628                 <entry><tag class="attvalue">center</tag>, <tag class="attvalue">justify</tag>, <tag class="attvalue">right</tag>, <tag class="attvalue">left</tag> (default)</entry>\r
 629               </row>\r
 630               <row>\r
 631                 <entry>\r
 632                   <tag class="attribute">morerows</tag>\r
 633                 </entry>\r
 634                 <entry>Specifies the number of additional rows the entry will span.</entry>\r
 635                 <entry>&gt;1</entry>\r
 636               </row>\r
 637               <row>\r
 638                 <entry>\r
 639                   <tag class="attribute">colname</tag>\r
 640                 </entry>\r
 641                 <entry>\r
 642                   <para>Specifies the column, defined by a <tag class="element">colspec</tag> element, in which the entry belongs.</para>\r
 643                   <para><emphasis role="bold">Note: </emphasis>You must specify entries rom left to right.</para>\r
 644                 </entry>\r
 645                 <entry>The value of the <tag class="attribute">name</tag> attribute of the <tag class="element">colspec</tag> element defining the column of the span.</entry>\r
 646               </row>\r
 647             </tbody>\r
 648           </tgroup>\r
 649         </table>\r
 650         <note>\r
 651           <para>Attributes not listed in <xref linkend="entryattrs"/> are not used in Evergreen' documentation.</para>\r
 652         </note>\r
 653       </simplesect>\r
 654       <simplesect>\r
 655         <title>Example</title>\r
 656         <para><xref linkend="tbodyexample"/> shows the markup for tables used in this\r
 657 chapter.</para>\r
 658         <example xml:id="tbodyexample">\r
 659           <?dbfo pgwide="1"?>\r
 660           <title>Add Rows to a Table</title>\r
 661           <programlisting>&lt;table ...&gt;\r
 662   &lt;tgroup  cols=&quot;3&quot; &gt;\r
 663     &lt;colspec ... /&gt;\r
 664     ...\r
 665     &lt;tbody&gt;\r
 666       &lt;row&gt;\r
 667         &lt;entry&gt;\r
 668            &lt;tag class=&quot;attribute&quot;&gt;colsep&lt;/tag&gt;\r
 669         &lt;/entry&gt;\r
 670         &lt;entry&gt;Specifies whether a rule will be drawn to \r
 671             the right of entries in the span.&lt;/entry&gt;\r
 672         &lt;entry&gt;\r
 673            &lt;tag class=&quot;attvalue&quot;&gt;0&lt;/tag&gt;, \r
 674            &lt;tag class=&quot;attvalue&quot;&gt;1&lt;/tag&gt; \r
 675            (default)&lt;/entry&gt;\r
 676       &lt;/row&gt;\r
 677       &lt;row&gt;\r
 678         &lt;entry&gt;\r
 679            &lt;tag class=&quot;attribute&quot;&gt;rowsep&lt;/tag&gt;\r
 680         &lt;/entry&gt;\r
 681         &lt;entry&gt;Specifies whether a rule will be drawn below \r
 682             the rows in the span.&lt;/entry&gt;\r
 683         &lt;entry&gt;\r
 684            &lt;tag class=&quot;attvalue&quot;&gt;0&lt;/tag&gt;, \r
 685            &lt;tag class=&quot;attvalue&quot;&gt;1&lt;/tag&gt; \r
 686            (default)&lt;/entry&gt;\r
 687       &lt;/row&gt;\r
 688       &lt;row&gt;\r
 689         &lt;entry&gt;&lt;tag&gt;align&lt;/tag&gt;&lt;/entry&gt;\r
 690         &lt;entry&gt;Specifies the horizontal alignment of \r
 691             the entry in the span.&lt;/entry&gt;\r
 692         &lt;entry&gt;\r
 693            &lt;tag class=&quot;attvalue&quot;&gt;center&lt;/tag&gt;, \r
 694            &lt;tag class=&quot;attvalue&quot;&gt;justify&lt;/tag&gt;, \r
 695            &lt;tag class=&quot;attvalue&quot;&gt;right&lt;/tag&gt;, \r
 696            &lt;tag class=&quot;attvalue&quot;&gt;left&lt;/tag&gt; \r
 697            (default)&lt;/entry&gt;\r
 698       &lt;/row&gt;\r
 699     &lt;/tbody&gt;\r
 700   &lt;/tgroup&gt;\r
 701 &lt;/informaltable&gt;</programlisting>\r
 702         </example>\r
 703       </simplesect>\r
 704     </section>\r
 705     <section>\r
 706       <title>Example</title>\r
 707       <para><xref linkend="tableexample"/> shows a table that uses most of the\r
 708 features of a table.</para>\r
 709       <table xml:id="tableexample" pgwide="1">\r
 710         <title>Complicated Table</title>\r
 711         <tgroup cols="6">\r
 712           <colspec colnum="1" colname="c1" align="center"/>\r
 713           <colspec colnum="2" colname="c2" align="justify"/>\r
 714           <colspec colname="c3"/>\r
 715           <colspec colnum="4" colname="c4"/>\r
 716           <colspec colnum="5" colname="c5" align="right"/>\r
 717           <colspec colname="c6" align="left"/>\r
 718           <spanspec namest="c2" nameend="c5" spanname="25" align="center"/>\r
 719           <spanspec namest="c1" nameend="c4" spanname="14" align="left"/>\r
 720           <thead>\r
 721             <row>\r
 722               <entry>c1</entry>\r
 723               <entry>c2</entry>\r
 724               <entry>c3</entry>\r
 725               <entry>c4</entry>\r
 726               <entry>c5</entry>\r
 727               <entry>c6</entry>\r
 728             </row>\r
 729           </thead>\r
 730           <tbody>\r
 731             <row>\r
 732               <entry>Pomegranate</entry>\r
 733               <entry>Pineapple</entry>\r
 734               <entry>Mango</entry>\r
 735               <entry>Carambola</entry>\r
 736               <entry>Banana</entry>\r
 737               <entry>Papaya</entry>\r
 738             </row>\r
 739             <row>\r
 740               <entry>Apples</entry>\r
 741               <entry align="right">Kiwis</entry>\r
 742               <entry namest="c3" nameend="c5" align="center">Passion Fruits</entry>\r
 743               <entry>Watermelon</entry>\r
 744             </row>\r
 745             <row>\r
 746               <entry spanname="14">Strawberries</entry>\r
 747               <entry>Cantaloupe</entry>\r
 748               <entry>Tamarind</entry>\r
 749             </row>\r
 750             <row>\r
 751               <entry>Lichee</entry>\r
 752               <entry spanname="25">Boysenberry</entry>\r
 753               <entry>Guava</entry>\r
 754             </row>\r
 755           </tbody>\r
 756         </tgroup>\r
 757       </table>\r
 758       <para><xref linkend="tablemarkup"/> shows the markup for <xref linkend="tableexample"/>.</para>\r
 759       <example xml:id="tablemarkup">\r
 760         <?dbfo pgwide="1"?>\r
 761         <title>Markup for a Table</title>\r
 762         <programlisting>&lt;table xml:id=&quot;tableexample&quot; pgwide="1"&gt;\r
 763   &lt;title&gt;Complicated Table&lt;/title&gt;\r
 764   &lt;tgroup cols=&quot;6&quot;&gt;\r
 765     &lt;colspec align=&quot;center&quot; colname=&quot;c1&quot; colnum=&quot;1&quot; /&gt;\r
 766     &lt;colspec align=&quot;justify&quot; colname=&quot;c2&quot; colnum=&quot;2&quot; /&gt;\r
 767     &lt;colspec colname=&quot;c3&quot; /&gt;\r
 768     &lt;colspec colname=&quot;c4&quot; colnum=&quot;4&quot; /&gt;\r
 769     &lt;colspec align=&quot;right&quot; colname=&quot;c5&quot; colnum=&quot;5&quot; /&gt;\r
 770     &lt;colspec align=&quot;left&quot; colname=&quot;c6&quot; /&gt;\r
 771     &lt;spanspec align=&quot;center&quot; nameend=&quot;c5&quot; namest=&quot;c2&quot;\r
 772         spanname=&quot;25&quot; /&gt;\r
 773     &lt;spanspec align=&quot;left&quot; nameend=&quot;c4&quot; namest=&quot;c1&quot; \r
 774         spanname=&quot;14&quot; /&gt;\r
 775     &lt;thead&gt;\r
 776       &lt;row&gt;\r
 777         &lt;entry&gt;c1&lt;/entry&gt;\r
 778         &lt;entry&gt;c2&lt;/entry&gt;\r
 779         &lt;entry&gt;c3&lt;/entry&gt;\r
 780         &lt;entry&gt;c4&lt;/entry&gt;\r
 781         &lt;entry&gt;c5&lt;/entry&gt;\r
 782         &lt;entry&gt;c6&lt;/entry&gt;\r
 783       &lt;/row&gt;\r
 784     &lt;/thead&gt;\r
 785     &lt;tbody&gt;\r
 786       &lt;row&gt;\r
 787         &lt;entry&gt;Pomegranate&lt;/entry&gt;\r
 788         &lt;entry&gt;Pineapple&lt;/entry&gt;\r
 789         &lt;entry&gt;Mango&lt;/entry&gt;\r
 790         &lt;entry&gt;Carambola&lt;/entry&gt;\r
 791         &lt;entry&gt;Banana&lt;/entry&gt;\r
 792         &lt;entry&gt;Papaya&lt;/entry&gt;\r
 793       &lt;/row&gt;\r
 794       &lt;row&gt;\r
 795         &lt;entry&gt;Apples&lt;/entry&gt;\r
 796         &lt;entry align=&quot;right&quot;&gt;Kiwis&lt;/entry&gt;\r
 797         &lt;entry align=&quot;center&quot; nameend=&quot;c5&quot; \r
 798             namest=&quot;c3&quot;&gt;Passion\r
 799           Fruits&lt;/entry&gt;\r
 800         &lt;entry&gt;Watermelon&lt;/entry&gt;\r
 801       &lt;/row&gt;\r
 802       &lt;row&gt;\r
 803         &lt;entry spanname=&quot;14&quot;&gt;Strawberries&lt;/entry&gt;\r
 804         &lt;entry&gt;Cantaloupe&lt;/entry&gt;\r
 805         &lt;entry&gt;Tamarind&lt;/entry&gt;\r
 806       &lt;/row&gt;\r
 807       &lt;row&gt;\r
 808         &lt;entry&gt;Lichee&lt;/entry&gt;\r
 809         &lt;entry spanname=&quot;25&quot;&gt;Boysenberry&lt;/entry&gt;\r
 810         &lt;entry&gt;Guava&lt;/entry&gt;\r
 811       &lt;/row&gt;\r
 812     &lt;/tbody&gt;\r
 813   &lt;/tgroup&gt;\r
 814 &lt;/table&gt;</programlisting>\r
 815       </example>\r
 816     </section>\r
 817   </section>\r
 818 </chapter>\r