Writing documentation with DocBook-XML 4.2 |  |
Writing documentation with DocBook-XML 4.2 | |
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 should be a <title>...</title> element.
The <tgroup> element encloses the entire rest of the table. Its cols= attribute gives the number of columns for the table as a whole.
There is a <colspec> element for each column of the table that specifies how the column is to be presented. 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 "3*" for the first column and "*" 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> tag 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 http://www.oasis-open.org/cover/tr9502.html.
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 start tags in your table. There is a hierarchy of tags: attributes of the <table> tag set values for the table as a whole. Attributes of <colspec/> set values for all entries in a column, and may override values set in the <table> tag. Attributes of the <row> and <entry> tag can in turn override those values.
The example table above shows this process. The frame="topbot" attribute of the <table> tag specifies that rules appear only above and below the table as a whole. But the rowsep="1" attribute of the row tag for the first row overrides that specification, forcing a rule to appear below the first row.
Here are the tags and attributes that affect ruled lines:
In the <table> tag, 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 tags <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 <table> 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 tags <table>, <tgroup>, <row>, and <entry> can have a rowsep="..." attribute.
Use rowsep=0 to suppress the rule below the row (or cell, for <entry>). 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.
Normally, your table will be fit into the page width remaining after the current indentation level is subtracted from the total page width. However, if you need more width, use a pgwide="1" attribute in your <table> tag. This will give you the whole width of the page to work with.
Your other job is to distribute this width among the columns of the table. You can do this in two ways:
You can assign a specific width to each column of the table. However, this can make life more difficult for people reading the Web version of your document if their window is too narrow for your table.
A better way is to specify the relative width of the columns. The advantage of this method is that in Web form your table can be resized to conform to the width of the browser window.
Regardless of which method you use, the width of each column is specified in the <colspec colwidth="..."/> attribute, which can take these values:
A number followed by a unit of measure. Units include: pt (printer's points, about 1/72 inch), pi (picas, about 1/6 inch), mm (millimeters), cm (centimeters), or in (inches). For example, colwidth="5.5cm" would specify a width of 5.5 centimeters.
A number followed by an asterisk. This allows you to specify relative column widths. With this method, all the numbers are added up, and the space is divided according to the coefficients. The numbers can be integers or fixed-point constants such as 5.25.
For example, suppose your table has four columns and the values of the colwidth attribute are "3*", "*", "2*", and "2*". The sum of these coefficients (the second value is the same as "1*") is 8. The resulting table would allocate 3/8 of the width to the first column, 1/8 of the width to the second column, and 1/4 of the width to each of the third and fourth columns.
By alignment, we mean the positioning of elements within the cells of a table. Since most cells will not be filled exactly, we need ways of controlling where the content is placed within the cell, both horizontally and vertically.
Horizontal alignment is controlled by the align="..." attribute. This attribute can be used:
in a <tgroup> tag to set the default alignment for the table as a whole;
in a <colspec/> tag to set the default alignment for one column; or
in an <entry> tag to set the alignment for a specific cell.
Attribute values for deeper elements override those for shallower elements.
The value of the align attribute can be any of the following:
| Value | Meaning |
|---|---|
| left | Content is aligned to the left side of each cell. |
| right | Content is aligned to the right side. |
| center | Content is centered. |
| justify | Text is shown as a justified paragraph, stretched to the full width of the cell. |
Vertical alignment is controlled by the valign="..." attribute. This attribute can be used:
in a <row> tag to set the default alignment for that row; or
in an <entry> tag to change the alignment of a single cell.
The value of the valign attribute can be any of these:
| Value | Meaning |
|---|---|
| top | Content is aligned to the top side of each cell. |
| middle | Content is centered vertically in the cell. |
| bottom | Content is aligned to the bottom of the cell. |
So far we have talked only about tables with a cell at the intersection of each row and column. In the real world, though, we often need to span cells, that is, to combine two or more cells into a larger area that holds a single item.
Here is a small table that demonstrates spanning. Note that the last two column headings are each centered over two columns:
Table 2. Rising and setting of Venus, 1994
| 20 degrees N. Lat. | 30 degrees; N. Lat. | ||||
|---|---|---|---|---|---|
| Rise | Set | Rise | Set | ||
| Jan. | 1 | 6:21 | 17:14 | 6:43 | 16:52 |
| 11 | 6:35 | 17:31 | 6:56 | 17:10 | |
Here's the source for the first part of this table:
<table>
<title>Rising and setting of Venus, 1994</title>
<tgroup cols="6" align="right">
<colspec align="left" colname="month"/>
<colspec colname="day"/>
<colspec colname="rise-20"/>
<colspec colname="set-20"/>
<colspec colname="rise-30"/>
<colspec colname="set-30"/>
<thead>
<row>
<entry namest="month" nameend="day"> </entry>
<entry namest="rise-20" nameend="set-20" align="center"
>20 degrees N. Lat.</entry>
<entry namest="rise-30" nameend="set-30" align="center"
>30 degrees; N. Lat.</entry>
</row> |
Note the additional colname attributes within the <colspec/> tags. These attributes give names to the columns of the table. The spanned elements refer to these names in order to specify where the spanning starts and ends. The <entry> tags for a spanned element have attributes namest="A" and nameend="B", where A is the column name where the span starts and B is the column name where the span ends.