Chapter 7. Tables

You can create formal and informal tables. Formal tables have a caption while informal tables do not.

 Table Types

You can create formal and informal tables. Formal tables have a caption, while informal tables do not.

 Formal Tables

A formal table requires a caption and looks like this:

Table 7.1. Formal table
Header Description
Term Description
Term Description

A caption describes the table.

The advantage of formal tables is that you can cross-reference them from other sections in your book or from other books.

Additionally, if you configure tables to be listed in a list of tables in the front matter of your book, captions for formal tables are listed in the list of tables.

A formal table is tagged with <table> tag. The following markup shows how to tag a formal table and include a caption:

 

Example 7.1. Markup for a formal table

<?xml version="1.0" encoding="UTF-8"?>
<table rules="all" width="30%">
    <caption>Formal table</caption>
    <col width="50%"/>
    <col width="50%"/>
    <thead>
        <tr>
            <th>Header</th>
            <th>Description</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td>Term</td>
            <td>Description</td>
        </tr>
        <tr>
            <td>Term</td>
            <td>Description</td>
        </tr>
    </tbody>
</table>

If you include the following markup in your pom.xml file:

book   toc,title,figure,table,example,equation

The caption for the table appears in the list of tables in the front matter of the book.

 Informal Tables

An informal table does not contain a caption and is not listed in the list of tables.

An informal table looks like this:

Header Description
Term Description
Term Description

Though you can cross-reference informal tables, you must supply link text because no text is auto-generated.

An informal table is tagged with <informaltable> tag. The following markup shows how to tag an informal table:

 

Example 7.2. Markup for an informal table

<?xml version="1.0" encoding="UTF-8"?>
<informaltable rules="all" width="30%">
    <col width="50%"/>
    <col width="50%"/>
    <thead>
        <tr>
            <th>Header</th>
            <th>Description</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td>Term</td>
            <td>Description</td>
        </tr>
        <tr>
            <td>Term</td>
            <td>Description</td>
        </tr>
    </tbody>
</informaltable>

 Guidelines for Tables

  • Capitalize only the first word of table captions and table headings.

  • Attribute tables:

    • Write the first sentence of a description with an implied subject.

      For example, if the attribute is name, the description might be Server name, which becomes the initial host name of the server.

    • For attributes, include the valid values and default value at the end of the description. Use the format Valid values are: and Default is X.

  • Use parallel structure.

  • If the table descriptions or construction is complex, consider using a variable list or itemized list instead of a table.

  • Avoid putting a variable list in a table.

  • Lead-in sentences for tables:

    • Use a lead-in sentence for tables.

    • Use complete sentences for lead-in sentences, and use a colon as ending punctuation.

    • Use the style: The following table (describes/shows/lists) X:

    • Put the lead-in sentence in a separate paragraph directly before the object of the lead-in.

 Create Tables

The easiest way to create a table is in Author mode in oXygen.

Alternatively, you can cut and paste the markup from an existing table in Text mode.

 

To create a table

  1. In Author mode, click Rackbook > Table > Insert Table.

    The Insert Table dialog box appears.

  2. Make the following selections:

    • Model

      Select HTML.

      DocBook tables are written using either CALS or HTML table elements. CALS is an SGML standard developed by the US military. DocBook added HTML table elements, starting with version 4.3 of the DocBook DTD.

      When you create tables, choose the HTML format. Not all elements of CALS tables are supported, so they might not format correctly. To convert existing CALS tables to HTML format, see the section called “CALS Tables Do Not Work”.

    • Title

      For a formal table, enter a table title. Capitalize only the first word of the table title.

      For an informal table, clear the Title selection.

    • Table Size

      Select or enter the number of rows and columns in the table.

    • Generate table header

      Accept the default to generate a table header row.

      Clear this selection to omit a table header row.

    • Generate table footer

      Accept the default to omit a table footer.

      We do not use table footers.

    • Column widths

      Select proportional, dynamic, or fixed.

    • Frame

      Select void. You will manually change this after your table is created.

  3. Switch to Text mode.

    Locate the table markup line. For an informal table, it looks like this:

    <informaltable frame="void">

    For a formal table, it looks like this:

    <table frame="void">

    Update the table markup to change frame="void" to rules="all", as follows:

    <informaltable rules="all">
  4. Use the Rackbook > Table menu commands to add and delete rows and columns, or to join or split cells.

    You can also use the table toolbar.

 Format Tables

For information about how to define other table properties, see DocBook XSL: The Complete Guide - Chapter 30: Tables. However, RackBook does not support all the features described in that chapter.

 Table and Column Widths

To control the overall width of a table, use the width attribute on the table tag.

To control the width of columns, use the width attribute on the col tag.

[Note]Note

The width attribute is not supported in CALS tables. For how to control table and column widths in CALS tables, see Table width.

The following markup shows how to control table and column widths:

<table rules="all" width="75%">
      <caption>Table Using Percentage Widths</caption>
      <col width="16%"/>
      <col width="14%"/>
      <col width="42%"/>
      <col width="28%"/>
      <thead>
...
      </thead>
      <tbody>
...
      </tbody>
    </table>

The column widths are a percentage of the total table width. In this example, the first column takes up 16% of the total table width of 75%.

When you create a table, check its appearance in all outputs. Column widths that appear correctly in HTML output might be incorrect in PDF output.

To describe a table differently for each type of output, see Troubleshooting badly formatted tables.

 Table Alignment

Tables that are less that the full page width are generally left-aligned. If you want a different alignment for tables in HTML output, then you can use CSS. See Table alignment.

 Cell Alignment

To control the horizontal and vertical positioning of content in a cell, use the align and valign attributes, respectively.

Add either or both the valign and align attributes to any of the following table tags:

  • thead

  • th

  • tbody

  • tr

  • td

The scope of these attributes depends on the table element in which you define the attributes. For example, if you add the valign attribute to the tbody tag, it applies to all child tr and td tags in that tbody block unless it is overridden by another valign attribute in a child tr or td tag in the tbody block.

 

To define cell alignments and spanning

  1. Set the vertical alignment

    Add the valign attribute a table tag.

    Valid values for the valign attribute are:

    • baseline. All cells in the same row as a cell whose valign attribute has this value should have their textual data positioned so that the first text line occurs on a baseline common to all cells in the row. This constraint does not apply to subsequent text lines in these cells.

    • top. Aligns to top of cell. Flushes cell data with the top of the cell.

    • middle. Aligns to center of cell or row. Centers cell data horizontally in the cell. Default value.

    • bottom. Aligns to bottom of cell or row. Flushes cell data with the bottom of the cell.

  2. Set the horizontal alignment

    Add the align attribute to a table tag.

    Valid values for the align attribute are:

    • center. Center text and center-justifies text. Default for table headers.

    • char. Aligns text around a specific character.

    • justify. Double-justifies text.

    • left. Left-justifies text. Default value for table data.

    • right. Right-flushes data and right-justifies text.

 Cell Spanning

Cell spanning means joining cells together to make a larger cell. You can join cells horizontally, vertically, or both.

To join columns, add the colspan attribute to the th tag or td tag in a table.

To join rows, add the rowspan attribute to the th tag or td tag in a table.

Set the colspan and rowspan attributes to a numeric value to define how many columns or rows to join.

 

To define cell spanning

  1. Join columns

    Select the cells to join. Then, use the join toolbar to join the columns across rows.

    Alternatively, add the colspan attribute to a cell and specify the number of cells to join horizontally.

    For example, for the following table:

    Table 7.2. Test table
    Header column A Header column B
    Row 1 column A Row 1 column B
    Row 2 column A Row 2 column B
    Row 3 column A Row 3 column B

    Use the following markup to join columns A and B in row 1:

    <?xml version="1.0" encoding="UTF-8"?>
    <table rules="all" width="50%">
        <caption>Test table</caption>
        <col width="50%"/>
        <col width="50%"/>
        <thead>
            <tr>
                <th>Header column A</th>
                <th>Header column B</th>
            </tr>
        </t(1)head>
        <tbody>
            <tr>
                <td colspan="2">Row 1 column ARow 1 column B</td>
            </tr>
            <tr>
                <td>Row 2 column A</td>
                <td>Row 2 column B</td>
            </tr>
            <tr>
                <td>Row 3 column A</td>
                <td>Row 3 column B</td>
            </tr>
        </tbody>
    </table>
    

    1

    Add the colspan attribute to the td tag.

    The table appears as follows:

    Table 7.3. Test table
    Header column A Header column B
    Row 1 column ARow 1 column B
    Row 2 column A Row 2 column B
    Row 3 column A Row 3 column B
  2. Join rows

    Select the cells to join. Then, use the join toolbar to join the rows across columns.

    Alternatively, add the rowspan attribute to a cell and specify the number of cells to join vertically.

    For example, for the following table:

    Use the following markup to join rows 2 and 3 in column B:

     <table rules="all">
                    <caption>Test table</caption>
                    <thead>
                        <tr>
                            <th>Header column A</th>
                            <th>Header column B</th>
                        </tr>
    
                    </thead>
                    <tbody>
                        <tr>
                            <td>Row 1 column A</td>
                            <td>Row 1 column B</td>
                        </tr>
                        <tr>
                            <td>Row 2 column A</td>
                            <td rowspan="2">Row 2 column BRow 3 column
                                B</td>
                        </tr>
                        <tr>
                            <td>Row 3 column A</td>
                        </tr>
                    </tbody>
                </table>

    The table appears as follows:

  3. Split columns or rows

    Put your cursor in the cell that you want to split. Then, use the correct tool icon on the split toolbar to split the cell into rows or columns.

    Alternatively, remove the colspan or rowspan attribute, if they exist, from the cell markup.

 Borders

By default, when you create a table in Author mode, the table tag includes the frame="void" attribute, which suppresses interior and frame borders from the table.

 

To define borders

  • In Text mode, remove the frame="void" attribute from the table tag and add the rules="all" tag, as shown in the following markup:

    <table rules="all">
    ...
    </table>

 Troubleshoot Tables

 CALS Tables Do Not Work

Problem

CALS tables no longer work. You might find one in an existing document, as follows:

<?xml version="1.0" encoding="UTF-8"?>
<table frame="all">
    <?dbhtml table-width="85%" ?>
    <?dbfo table-width="100%" ?>
    <title>Request Methods</title>
    <?dbfo keep-together="always"?>
    <tgroup cols="2">
        <colspec colname="c1" colnum="1" colwidth="1.0*"/>
        <colspec colname="c2" colnum="2" colwidth="1.48*"/>
        <thead>
            <row>
                <entry>Request Method</entry>
                <entry>Description</entry>
            </row>
        </thead>
        <tbody>
            <row>
                <entry>Complex MIME Type with Vendor
                    Specification</entry>
                <entry>
                   <para> Vendor specifications do not modify ... </para>
                </entry>
            </row>
        </tbody>
    </tgroup>
</table>
Solution

Rebuild the CALS table to match the following markup:

<?xml version="1.0" encoding="UTF-8"?>
<table border="1" frame="box">
    <caption>Request Methods</caption>
    <thead>
        <tr>
            <td>Request Method</td>
            <td>Description</td>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td>Complex MIME Type with Vendor Specification</td>
            <td>
                <para> Vendor specifications do not modify how ... </para>
            </td>
        </tr>
   </tbody>
</table>

 Tables Have No Borders

Problem

Tables have no borders.

Solution

In an HTML table, define the table as follows:

<table rules="all" frame="border">

 Long URLs Do Not Wrap Inside a Table Cell

Problem

DocBook can generate line breaks at a space or a slash but not at a period, such as in verylongdescriptivenameofaresource.com.

In HTML output, the table cell widens to the size of the string.

In PDF output, that does not happen, which causes long URLs in a table in a PDF to be wider than the table cell that contains them, which causes them to overstrike the contents of an adjacent cell or to disappear off the edge of the page, as shown in the following figure:

Solution

First, manually update the table so that the rows become columns, and the columns become rows, as shown in the following figure:

Then, specify column widths that add up to greater than 100% of the space reserved for the table, as shown in the following markup:

<?xml version="1.0" encoding="UTF-8"?>
<table rules="all">
    <caption>Recommended Authentication Endpoints</caption>
    <col width="13%"/>
    <col width="32%"/>
    <col width="32%"/>
    <col width="32%"/>
    <thead>
        <tr>
            <th>Resource</th>
            <th>v1</th>
            <th>v1.1</th>
            <th>v2.0</th>
        </tr>
    </thead>
    <tbody>
...
    </tbody>
</table>
Questions? Discuss on ask.openstack.org
Found an error? Report a bug against this page