Creating Tables

Limitations
Table Width
Tables without colwidth
Tables with mixed colspec
Tables with proportional and fixed colwidth
Tables with fixed colwidths
Automatic Column Width
Tables with morerows
Landscape tables
Smaller tables
Coloured tables

DocBook tables can be quite complex, but dblatex should be able to drive most of cases thanks to the excellent newtbl implementation by David Hedley completely written in XSL.

Here is what is supported:

Limitations

Currently the following things are known to fail with tables:

  • Program listings and screens cannot be embedded in tables. Some other verbatim environments like litterallayout are allowed.

  • Footnotes in table cells can fail, especially if the footnote contains several paragraphs. Moreover they are lost is a float like a table.

Table Width

A table width is explicit when all the columns have a fixed size. In this case it is the sum of the colum widths. In the other cases (columns with no colwidth or proportional columns widths) the total table width is deduced by dblatex as follow: it looks for the Processing Instruction <?dblatex table-with="width" ?> first, then the @width attribute, the default.table.width parameter, and finally use the page width.

A table width can be expressed as:

Tables without colwidth

When none of the colspec elements contains the colwidth attribute, all the columns have the same size, and the table width is fixed to the maximum available size. Several examples of these tables are given in the PDF version of this manual.

Tables with mixed colspec

A table can have colspec elements containing colwidth attribute mixed with colspec elements without colwidth. Here is an XML source example:

<informaltable>
  <tgroup cols="5" colsep="1" rowsep="1" align="left">
    <colspec colname="c1"/>
    <colspec align="left" colwidth="4cm"/>
    <colspec align="right" colwidth="5cm"/>
    <colspec align="center"/>
    <colspec align="center" colwidth="3cm"/>
    <tbody>
    ...
    </tbody>
  </tgroup>
</informaltable>
   

See the PDF version of this manual to see how it is rendered.

Tables with proportional and fixed colwidth

Proportional column widths are supported. Here is an example:

<informaltable>
  <tgroup cols="5" colsep="1" rowsep="1" align="left"> 
    <colspec colname="c1" colwidth="*"/> 
    <colspec align="left" colwidth="2*"/> 
    <colspec align="right" colwidth="3*"/> 
    <colspec align="center"/>
    <colspec align="center" colwidth="3cm"/>
    <tbody>
    ...
    </tbody>
  </tgroup>
</informaltable>
   

Tables with fixed colwidths

All the columns can have fixed size, like this:

<informaltable>
  <tgroup cols="4" colsep="1" rowsep="1" align="left"> 
    <colspec colname="c1" colwidth="2cm"/> 
    <colspec align="left" colwidth="2.5cm"/> 
    <colspec align="right" colwidth="5cm"/> 
    <colspec align="center" colwidth="3cm"/>
    <tbody>
    ...
    </tbody>
  </tgroup>
</informaltable>
   

Automatic Column Width

Global Setting

In the previous sections the columns widths are computed from a proportional basis, when no colwidth is specified or when the colwidths contain a star ("*"). Of course, a colwidth containing a fixed width incidently sets the column width with this size.

It is possible to change this sizing policy of not-fixed-width columns by playing with the newtbl.autowidth parameter. The parameter can take the following values:

default

The automatic width (that is, latex is in charge to size the column width) is applied only to columns not having a specified colspec colwidth. It includes both undefined colspec, and colspec without the colwidth attribute.

all

the automatic width is applied to any column, whatever a colspec is provided or not.

By default the parameter is unset, and no automatic width is applied. Using automatic width is handy in some situations but there is no more control if the tables fit in the page or not, since in this case the column is as wide as its content, with no more paragraph breaking. The parameter is global for all the tables in the document.

You can also perform the same thing by setting the default.table.width parameter to autowidth.default or autowidth.all instead of using newtbl.autowidth.

Local Setting

If you want to apply an automatic width only to some specific tables you can put the Processing Instruction <?dblatex table-with="autowidth.scope" ?> in the related tables. The PI has precedence over the newtbl.autowidth parameter.

The scope can take the same values and have the same effects than for the newtbl.autowidth parameter: default or all. Here are two examples:

The following table has columns 1 and 2 sized by latex with autowidth.all:

Column 1Column 2Column 3Column 4
cell on 4 lines simple cell cell on 2 lines cell without morerow attribute
cell in column 2 cell on 2 lines
left aligned on 2 lines cell in line 3, column 3
4 cm column width last cell in column 4

It is written as follow:

<informaltable><?dblatex table-width="autowidth.all"?>
  <tgroup cols="4" colsep="1" rowsep="1" align="left">
  <colspec colname="c1"/> <!-- 'default' and 'all' apply on this column -->
  <colspec align="left" colwidth="*"/> <!-- only 'all' applies on this column -->
  <colspec align="right" colwidth="5cm"/>
  <colspec align="center" colwidth="3cm"/>
  ...
</informaltable>

The following table has only columns 1 sized by latex with autowidth.default:

Column 1Column 2Column 3Column 4
cell on 4 lines simple cell cell on 2 lines cell without morerow attribute
cell in column 2 cell on 2 lines
left aligned on 2 lines cell in line 3, column 3
4 cm column width last cell in column 4

The only difference is that the PI attrbute value is autowidth.default:

<informaltable><?dblatex table-width="autowidth.default"?>
  <tgroup cols="4" colsep="1" rowsep="1" align="left">
  <colspec colname="c1"/> <!-- 'default' and 'all' apply on this column -->
  <colspec align="left" colwidth="*"/> <!-- only 'all' applies on this column -->
  <colspec align="right" colwidth="5cm"/>
  <colspec align="center" colwidth="3cm"/>
  ...
</informaltable>

Tables with morerows

A table can contain entries that cover several lines. The following XML source contains an entry covering 4 lines:

<informaltable>
  <tgroup cols="4" colsep="1" rowsep="1" align="left"> 
    <colspec colname="c1" colwidth="*"/>
    ...
    <tbody>
    <entry morerows="3">it covers 4 lines</entry>
    ...
    </tbody>
  </tgroup>
</informaltable>
   

Landscape tables

A table can be displayed in a lanscape format by using the orient attribute. Here is an XML source example:

<informaltable orient="land">
  <tgroup cols="5" colsep="1" rowsep="1" align="left"> 
    <colspec colname="c1" colwidth="*"/>
    ...
    <tbody>
    ...
    </tbody>
  </tgroup>
</informaltable>
   

Smaller tables

For big tables it can be usefull to have smaller text, so that the table is not too large or too long and it can be displayed within a page. It is possible to specify smaller table text by using the role attribute of the elements table or informaltable.

The values and the “role” dedicated to this attribute are specific to dblatex, but it is compliant with the DocBook specification because in general the role attribute purpose is never defined.

The available text size definitions supported by role are directly taken from LaTeX:

  • small,

  • footnotesize,

  • scriptsize,

  • tiny.

Coloured tables

You can color all the table by setting its bgcolor attribute.

You can also color only some cells by using the Processing Instruction <?dblatex bgcolor="color"?>. The PI can apply to columns when put in a colspec, to rows when put at the beginning of a row, or to cells when put in a entry.

The entry colour has precedence over the row colour, that has precedence over the column colour, that has precedence over the table colour.

The color can be expressed in hexadecimal notation like for HTML (e.g. #C0C0C0) or in a syntax understood by the colortbl latex package.

Here is a PDF output example.

This table is coded like this:

<informaltable id="tbl-color" bgcolor="{yellow}">
<tgroup cols="4" colsep="1" rowsep="1" align="left">
  <colspec colname="c1" colwidth="2cm"/>
  <colspec align="left" colwidth="2.5cm"><?dblatex bgcolor="#00FF00"?></colspec>
  <colspec align="right" colwidth="5cm"/>
  <colspec align="center" colwidth="3cm"/>
  <thead>
    <row>
      <entry>Column 1</entry><entry>Column 2</entry>
      <entry>Column 3</entry><entry>Column 4</entry>
    </row>
  </thead>
  <tbody>
  <row>
    <entry>yellow</entry><entry>green column</entry>
    <entry>yellow</entry><entry>yellow</entry>
  </row>
  <row>
  <?dblatex bgcolor="{blue}"?>
    <entry>blue row</entry>
    <entry><?dblatex bgcolor="{red}"?>red cell</entry>
    <entry>blue row</entry><entry>blue row</entry>
  </row>
  <row>
    <entry>yellow</entry><entry>green column</entry>
    <entry>yellow</entry>
    <entry><?dblatex bgcolor="[gray]{0.8}"?>gray</entry>
  </row>
  </tbody>
</tgroup>
</informaltable>