Writing documentation with DocBook-XML 4.3 |  |
Writing documentation with DocBook-XML 4.3 | |
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
| Player | FTA | FTM | Pct. |
|---|---|---|---|
| Rick Barry | 4,243 | 3,818 | .900 |
| Calvin Murphy | 3,864 | 3,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 table element encloses the entire
table. The attribute frame="topbot"
specifies that ruled lines be placed over the top and
bottom of the table as a while. The attribute pgwide="0" tells DocBook to place the table
within the current paragraph width.
If a page break falls in the middle of a table, the heading will be repeated on the new page.
Every table must be titled, so the next thing after the
table opening tag must be a title element.
The tgroup element encloses the entire
rest of the table. Its cols attribute
specifies the number of columns for the table as a
whole.
Specify the presentation of each column in the table
with a colspec element.
The colwidth attribute specifies the
width of the column. In this example, we want the
first column to be three times as wide as the other
columns, so we use a value of colwidth="3*" for the first column and colwidth="*" for the rest.
The align attribute specifies whether
the contents of each column are to be positioned to the
left or right side.
The thead element encloses the heading
section of the table. The heading consists of a row element, containing one entry element for each heading.
Note that the row element has an attribute
rowsep="1" that places a ruled line
after that row. The rows in the table body do not have
that attribute and are not separated by rules.
The tbody element comes after the last
colspec element, and encloses the actual
body of the table.
Each row of the table is enclosed in a row element.
Each cell in the table is enclosed within an entry element.
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.
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:
Attributes of the table element
specify values for the table as a whole.
Attributes of colspec specify values
for all entries in a column, and may override values
set in the table element.
Attributes of the row element can
override higher-level values.
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:
| Value | Meaning |
|---|---|
all | Rules 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.