Creating Tables
Prev | Chapter 3. Using dblatex | Next

## Creating 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:

- Columns without specified widths (`colspec` without `colwidth` attribute) have the same size.

- A table width is always equal to the page width, if at least one column doesn't contain a fixed width attribute (e.g. colwidth=“12cm”).

- Fixed column widths are supported (e.g. colwidth=“10cm”). The unit can be whatever is understood by latex (e.g. cm, em, in, pt).

- Proportional column widths are supported (e.g. colwidth= “5*”). Combination of fixed and proportional width is supported too (e.g. colwidth=“5*+10cm”).

- The `morerows` attribute of a table entry (`entry` element) is supported.

- The `namest` and `nameend` attributes of a table entry (`entry` element) are supported. It is possible to have a cell spanned on several columns.

- The `orient` table attribute is supported (portrait and landscape).

- It is possible to have missing cell entries in a table.

### 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.

### 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

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

It is possible to change this sizing policy by playing with the `newtbl.autowidth` parameter. It 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.

### 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>

Prev | Up | Next
Figure Inclusion | Home | Writing Mathematics