Chapter 30. Tables

Table of Contents

Table width
Table alignment
Full-width tables
Column widths
Cell spacing and cell padding
Row height
Cell alignment
Horizontal alignment
Vertical alignment
Cell rotation
Cell spanning
Horizontal spans
Vertical spans
Table border
Row borders
Column borders
Border styles
Background color
Cell background color
Row background color
Long tables
Table styles in print output attribute-set attribute-set attribute-set
tabstyle template template template template
Table page breaking
Landscape tables
Table title formatting
Table titles without number labels
Table styles in HTML output
Table summary text
HTML table elements
Table template customization for printed output
Table "continued" label

DocBook tables are written using either CALS table elements or HTML table elements. CALS is an SGML standard developed by the U.S. military, and their set of table tags was one of the first to be developed that included complex features for tables. DocBook adopted the CALS table model because it was already developed.

Later, because of widespread familiarity with HTML tables, DocBook added HTML table elements, starting with version 4.3 of the DocBook DTD. Now you can use tr and td instead of row and entry in a table. You cannot mix them in one table, however. Also, the content of each table cell has to be valid DocBook, so you cannot usually just cut and paste an HTML table into your DocBook document. But the DTD does permit a document to contain both CALS tables and HTML tables. The tgroup element is the distinguishing characteristic between them. A CALS table requires a tgroup, and an HTML table does not permit one.

There are many similarities between DocBook (CALS) tables and HTML tables, as the following table shows. But you cannot cut and paste between them.

Table 30.1. Comparison of CALS and HTML tables

PurposeHTML ElementCALS ElementComments
Container for table elements.table, informal­tabletable, informal­tableThe CALS table element requires a title, an HTML table element requires a caption. An informaltable accepts neither.
Table titlecaptiontitleUse informaltable for an HTML table without a caption.
Wrapper for table sectionNot availabletgroupHTML tables do not support subsections of a table with different column specifications. CALS requires at least one tgroup.
Column specificationscol, colgroupcolspec, spanspecThe CALS spanspec element specifies horizontal spanning (joining) of cells.
Wrapper for header rowstheadthead 
Wrapper for body rowstbodytbody 
Wrapper for footer rowstfoottfootIn both HTML and CALS, tfoot must appear before tbody.
RowtrrowAll open tr tags must have a closing tag.
Celltd, thentryAll open td tags must have a closing tag.
Nested tableinformaltable inside a tdentrytbl inside a rowNested HTML tables permitted since version 4.4 of the DTD.

To learn how to write table elements, you should consult the reference page for table in DocBook: The Definitive Guide. It has an example table that uses most of the table elements and features.

Formatting of tables is controlled through a combination of elements, attributes, and processing instructions for the stylesheet. The following sections provide detailed information for CALS table formatting. Because DocBook tables created with HTML table elements use different elements and attributes, there is a separate section for DocBook HTML tables. See the section “ HTML table elements” for more information.

Table width

The overall table width can be controlled in two ways: a parameter or a processing instruction. It can be set globally for all tables in the document by setting the default.table.width stylesheet parameter to a width measurement or a percentage. A percentage is taken to be of the available width. This parameter has no default value and so has no effect unless you set it to some value.

The width of a single table using HTML markup can be set using the width attribute. However, that attribute is not supported on tables using CALS table elements. The width of a single CALS table can be specified with a processing instruction. The processing instruction is named dbhtml for HTML output, or dbfo for FO output. If you want to control the width for both outputs, you will need to provide both processing instructions. These processing instructions will override the default global width if one is specified. The following is an example.

<table><title>My table</title>
<?dbhtml table-width="75%" ?>
<?dbfo table-width="75%" ?>

For FO output, the stylesheet has an internal default value as well. This is used if neither the parameter nor the processing instruction or attribute establish a table width. For most processors the internal default value for table width is auto, which triggers automatic table layout. But some XSL-FO processors, such as FOP, have not implemented automatic table layout. So if fop.extensions or fop1.extensions parameter is set to 1, the internal default value is 100%. Either of these values can be overridden for all tables by setting the default.table.width parameter, or for an individual table with the PI or attribute.

The automatic table layout algorithm in XSL-FO is borrowed from the CSS2 specification. It combines any column width specs with the measured width of the text in the table cells to arrive at a total table width. Each cell has a minimum and maximum width. The minimum assumes line breaks between all words. The maximum assumes no line breaks except those that are explicit in the data. The processor then computes a width for each column and lays out the table for the best fit.