DocBook Table Layouts

CALS Table Model Layout

The CALS table model allows for more flexibility and table customization than other models. When choosing a CALS table model from the Insert Table dialog box, you have access to more configurable properties. The layout of a CALS table includes a colspecs section that allows you to easily configure some properties without opening the Table Properties dialog box. For example, you can change the value of column widths (@colwidth attribute) or the text alignment (@align attribute). Although they appear as part of the Author mode, the colspecs link and its controls will not appear in your output. They are just there to make it easier to adjust how the columns of your table are formatted.

Figure 1. CALS Table in DocBook

Tip: A sample plugin is available that can be used as inspiration to add support for CALS tables in any XML document: Sample Plugin: Add CALS Support for any XML Document.

HTML Table Model Layout

Choosing an HTML table model from the Insert Table dialog box in a DocBook document inserts a formal (captioned) HTML table. The layout of an HTML table includes a section above the table that allows you to easily configure some properties without opening the Table Properties dialog box. For example, you can change the value of column widths (@width attribute) or the text alignment (@align attribute). Although these properties appear as part of the Author mode, they will not appear in your output. They are just there to make it easier to adjust how the columns of your table are formatted.

Figure 2. HTML Table in DocBook

Pasting Tables in DocBook

Tables that are pasted into a DocBook file are automatically converted to the CALS model. If you want to overwrite this behavior and instruct Oxygen XML Author Eclipse plugin to convert them to HTML tables, set the docbook.html.table parameter to 1. You can find this parameter in the following stylesheet:

[OXYGEN_INSTALL_DIR]/frameworks/docbook/resources/xhtml2db5Driver.xsl for DocBook 5
[OXYGEN_INSTALL_DIR]/frameworks/docbook/resources/xhtml2db4Driver.xsl for DocBook 4

Table Validation in DocBook

Oxygen XML Author Eclipse plugin reports table layout problems that are detected in manual or automatic validations. The types of errors that may be reported for DocBook table layout problems include:

CALS Tables

A row has fewer cells than the number of columns detected from the table @cols attribute.
A row has more cells than the number of columns detected from the table @cols attribute.
A cell has a vertical span greater than the available rows count.
The number of <colspecs> is different than the number of columns detected from the table @cols attribute.
The number of columns detected from the table @cols attribute is different than the number of columns detected in the table structure.
The value of the @cols, @rowsep, or @colsep attributes are not numeric.
The @namest, @nameend, or @colname attributes point to an incorrect column name.

HTML Tables

A row has fewer cells than the number of table columns.
The value of the @colspan, @rowspan, or @span attributes are not numeric.
A cell has a vertical span greater than the available rows count.