Next / Previous / Contents / Shipman's homepage

12. Tables

DocBook has extensive features that help you present data in a tabular form. Here is an example of a small table:

Table 1. All-time NBA free throw percentages

PlayerFTAFTMPct.
Rick Barry4,2433,818.900
Calvin Murphy3,8643,445.892

Here is how the XML source for the table looks:

    <table frame='topbot' pgwide='0'>
      <title>All-time NBA free throw percentages</title>
      <tgroup cols='4'>
        <colspec colwidth='3*' align='left' colnum='1' colname='player'/>
        <colspec colwidth='*'  align='right' colnum='2' colname='fta'/>
        <colspec colwidth='*'  align='right' colnum='3' colname='ftm'/>
        <colspec colwidth='*'  align='right' colnum='4' colname='pct'/>
        <thead>
          <row rowsep='1'>
            <entry>Player</entry>
            <entry>FTA</entry>
            <entry>FTM</entry>
            <entry>Pct.</entry>
          </row>
        </thead>
        <tbody>
          <row>
            <entry>Rick Barry</entry>
            <entry>4,243</entry>
            <entry>3,818</entry>
            <entry>.900</entry>
          </row>
          <row>
            <entry>Calvin Murphy</entry>
            <entry>3,864</entry>
            <entry>3,445</entry>
            <entry>.892</entry>
          </row>
        </tbody>
      </tgroup>
    </table>

Let's look at these tags and their attributes in detail.

The sections below discuss a number of ways you can control the appearance of your table, but not all details of table construction are covered. For the full gory details, see the CALS table model Document Type Definition.

12.1. Ruled lines in tables

The default table appearance is to have rules (ruled lines) around the outside of the table and between all rows and columns.

You can control where rules appear by adding attributes to the various elements of your table. There is a hierarchy of elements:

  1. Attributes of the table element specify values for the table as a whole.

  2. Attributes of colspec specify values for all entries in a column, and may override values set in the table element.

  3. Attributes of the row element can override higher-level values.

  4. Attributes of the entry element can in turn override all higher-level values.

The example table above shows this process. The frame='topbot' attribute of the table element specifies that rules appear only above and below the table as a whole. But the rowsep='1' attribute of the first row element overrides that specification, forcing a rule to appear below the first row.

Here are the elements and attributes that affect ruled lines:

  • In the table element, the frame attribute can have any of these values:

    ValueMeaning
    allRules are placed above and below the table, on the left and right sides, between columns, and between rows.
    none No rules are used in the table.
    sides Rules are placed only at the left and right sides of the table.
    top A rule is placed only above the table.
    bottom A rule is placed only below the table.
    topbot Rules are placed above and below the table.

  • Any of the elements table, tgroup, colspec, and entry can have a colsep attribute.

    Use colsep=0 to suppress rules to the right of a column, or colsep='1' to place rules to the right of a column.

    The attribute for the table element sets the default for the table as a whole; the attribute for tgroup overrides the value for table; and so forth, with the value for deeper elements overriding the values of all shallower elements.

  • Any of the elements table, tgroup, row, and entry can have a rowsep attribute.

    Use rowsep=0 to suppress the rule below the row (or cell, for the entry element). Use rowsep='1' to place a rule below the row (or cell).

    As with the colsep attribute, values of this attribute for deeper elements override values in shallower elements.