Borders

In DocBook tables, the box around a table and the grid lines separating table cells are controlled by different attributes. For the table frame, you can indicate which sides are to have rule lines. For cell separators, you can indicate which columns and rows are to have separators, or you can set it for the whole table. For HTML output, controlling individual cell borders requires turning on the table.borders.with.css stylesheet parameter.

Table border

The border around a given table is turned on by adding a frame attribute to the table element. You must select one of the following values, which indicate which sides of the table are to have a border.

all
bottom
none
sides
top
topbot

If you want a box around your table, then set frame="all". If you just want horizontal lines at the top and bottom of the table, set frame="topbot".

If you want all your tables to have the same frame style without adding frame attributes to them all, then set the stylesheet parameter default.table.frame to one of the above values. You can still override the parameter setting by using a frame attribute on a given table. This parameter was added in version 1.73 of the stylesheets, and works with both print and HTML output.

In printed output, when a long table breaks across a page boundary, the bottom table border is not normally displayed at the break, nor is the top border after the page break. To some readers, this feature indicates that the table is continuing to the next page. To others, it looks odd. If you want the bottom and top table borders to display at the page breaks, then add this to your customization layer:

<xsl:attribute-set name="table.table.properties">
  <xsl:attribute name="border-after-width.conditionality">retain</xsl:attribute>
  <xsl:attribute name="border-before-width.conditionality">retain</xsl:attribute>
</xsl:attribute-set>

You might think you can turn borders on and off with the table.table.properties attribute-set, but that does not work. That's because a template named table.frame is called to apply borders after the attribute-set is applied. Any border properties set by the template override the same property in the attribute-set.

To customize table borders in print output, perhaps responding to a tabstyle attribute on a table, you need to customize the table.frame template in fo/table.xsl. That template outputs border attributes for the various frame attribute values.

To customize table borders in HTML output, you need to set the stylesheet parameter table.borders.with.css to 1 and customize the template named border in html/table.xsl.

Row borders

Horizontal grid lines drawn below rows are turned on by setting the attribute rowsep="1". You can turn it off by setting rowsep="0". This attribute can be set on any of the following elements so it applies to the scope of that element.

table
tgroup
colspec
spanspec
row
entry

So you can turn it on for all rows by setting the value to 1 in table, and then turn it off for specific rows by setting it to 0 in those rows. In colspec or spanspec, it applies on to the cells in that column or span. When cells are spanned vertically, no lines are drawn within the range of the span, only at the bottom of the span. Any rowsep value for the last row is ignored, because the table's frame attribute controls the bottom border.

Column borders

Vertical grid lines drawn to the right of each table cell are turned on by setting the attribute colsep="1". You can turn it off by setting colsep="0". This attribute can be set on any of the following elements so it applies to the scope of that element.

table
tgroup
colspec
spanspec
entry

So you can turn it on for all columns by setting the value to 1 in table, and then turn it off for specific columns by setting it to 0 in those colspec elements. When cells are spanned horizontally, no lines are drawn within the range of the span, only at the end of the span. Any colsep value for the last column is ignored, because the table's frame attribute controls the right border. The following example turns grid lines on and off.

<table frame="topbot" colsep="1" rowsep="1">
<title>Table borders</title>
<tgroup cols="4">
<colspec colnum="1" colname="col1" colwidth="1*"/>
<colspec colnum="2" colname="col2" colwidth="1*" colsep="0"/>
<colspec colnum="3" colname="col3" colwidth="1*"/>
<colspec colnum="4" colname="col4" colwidth="1*"/>
<thead>
<row>
<entry>Column 1 heading</entry>
<entry>Column 2 heading</entry>
<entry>Column 3 heading</entry>
<entry>Column 4 heading</entry>
</row>
</thead>
<tbody>
<row>
<entry>Entry 1.1</entry>
<entry>Entry 2.1</entry>
<entry>Entry 3.1</entry>
<entry>Entry 4.1</entry>
</row>
<row rowsep="0">
<entry>Entry 1.2</entry>
<entry rowsep="1" colsep="1">Entry 2.2</entry>
<entry>Entry 3.2</entry>
<entry>Entry 4.2</entry>
</row>
<row>
<entry>Entry 1.3</entry>
<entry>Entry 2.3</entry>
<entry>Entry 3.3</entry>
<entry rowsep="0">Entry 4.3</entry>
</row>
</tbody>
</tgroup>
</table> 

Example 30.3. Table borders

Column 1 headingColumn 2 headingColumn 3 headingColumn 4 heading
Entry 1.1Entry 2.1Entry 3.1Entry 4.1
Entry 1.2Entry 2.2Entry 3.2Entry 4.2
Entry 1.3Entry 2.3Entry 3.3Entry 4.3

Note these features of this example:

  • The table frame attribute creates borders at the top and bottom of the table.

  • The table attributes also turn on row and column lines for the whole table.

  • The colspec for column 2 turns off the vertical line to the right of column 2.

  • The row element for the second row turns off the horizontal line below that row.

  • Entry 2.2 turns on the vertical line to the right of and the horizontal line below that cell, overriding the removed lines.

  • The rowsep="0" in Entry 4.3 has no effect because the bottom rule comes from the table frame attribute.

Border styles

The DocBook stylesheets provide parameters for controlling table border styles. You can control the color, thickness, and style of borders, and control them separately for table frame and cell borders. You can set these parameters on the command line or in a stylesheet customization layer. Because these are stylesheet parameters, they apply to all tables in a document.

Example 30.4. Table border properties

PropertyParametersPossible Values
Border color

table.frame.border.color
table.cell.border.color

Color keywords: aqua, black, blue, fuchsia, gray, green, lime, maroon, navy, olive, purple, red, silver, teal, white, yellow.
RGB color: #2D33FF, #001A3D, etc.
Border thickness

table.frame.border.thickness
table.cell.border.thickness

Thickness keyword: thin, medium, thick.
Thickness length: 0.5pt, 3px, 2mm, etc.
Border style

table.frame.border.style
table.cell.border.style

Style keywords: none, dotted, dashed, solid, double, groove, ridge, inset, outset

Some of these properties may not be completely supported in all output formats or by all HTML browsers.