Chapter 28. Tables

Chapter 28. Tables
	Part IV. Special DocBook features

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 can't mix them in one table, however. Also, the content of each table cell has to be valid DocBook, so you can't 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.

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 28.1. Comparison of CALS and HTML tables

Purpose	HTML Element	CALS Element	Comments
Container for table elements.	`table`, `informaltable`	`table`, `informaltable`	The CALS `table` element requires a `title`, an HTML `table` element requires a `caption`. An `informaltable` accepts neither.
Table title	`caption`	`title`	Use `informaltable` for an HTML table without a caption.
Wrapper for column specs and content.	Not available	`tgroup`	HTML tables don't support subsections of a table with different column specifications. CALS requires at least one `tgroup`.
Column specifications	`col`, `colgroup`	`colspec`, `spanspec`	The CALS `spanspec` element specifies horizontal spanning (joining) of cells.
Wrapper for header rows	`thead`	`thead`
Wrapper for body rows	`tbody`	`tbody`
Wrapper for footer rows	`tfoot`	`tfoot`	In both HTML and CALS, `tfoot` must appear before `tbody`.
Row	`tr`	`row`	All open `tr` tags must have a closing tag.
Cell	`td`, `th`	`entry`	All open `td` tags must have a closing tag.
Nested table	`informaltable` inside a `td`	`entrytbl` inside a `row`	Nested 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 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 two processing instructions. These processing instructions will override the default width if one is specified. Here is an example.

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

For FO output, the stylesheet has an internal default value as well. This is used if neither the parameter nor the processing instruction 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 and PassiveTeX have not implemented automatic table layout. So if fop.extensions or passivetex.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.

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.


Chunking Q and A		Column widths