Column widths

Table column widths in CALS tables can be controlled by setting a colwidth attribute in a colspec element for each column inside the tgroup element. You also assign each column a number (colnum attribute) and an optional name (colname attribute). The name can be used in other specifications in the table, such as spans. It is recommended that you provide colspec elements for each column to make it easier for the processor to format the table.

The DocBook XSL stylesheets provide XSL extension functions to assist in the adjustment of table columns. These extension functions are only available for the Saxon and Xalan processors. They are enabled by setting both the use.extensions parameter and the tablecolumns.extension parameter to 1. If you turn on these parameters for other processors, then you will get an error message about No adjustColumnWidths function available at the first table.

For HTML output, the extension functions are required if you want to manually set column widths with the colwidth attribute. That is because CALS tables permit widths to be specified in ways that cannot be translated by XSLT to HTML table values. The result of this requirement is if the two parameters are not set, then any colwidth attributes are ignored. In general, the table columns extension is more important for HTML output than FO output, since the major XSL-FO processors handle table column widths without it. If you use these extensions, do not forget to include the extensions jar file in your Java CLASSPATH.

The following is an example for a four column table:

<table><title>My table</title>
<tgroup cols="4" >
<colspec colnum="1" colname="col1" colwidth="1*"/>
<colspec colnum="2" colname="col2" colwidth="2*"/>
<colspec colnum="3" colname="col3" colwidth="1.5*"/>
<colspec colnum="4" colname="col4" colwidth="1*"/>

Here is how you specify column width values:


colwidth specifies the desired width of the relevant column. It can be either a fixed measure using one of the CALS units (36pt, 10pc, etc.) or a proportional measure. Proportional measures have the form “number*”, meaning this column should be number times wider than a column with the measure “1*” (or just “*”). These two forms can be mixed, as in “3*+1pc”.

 --DocBook: The Definitive Guide

In this example, the first and fourth columns have the same proportion, the second column is twice as wide, and third is 1.5 times as wide. The widths could also have been specified with measurement units, but then they do not adjust to the overall table width.