Working with tables in structured documents

Structured tables work in much the same way as unstructured tables. The table element definition determines the table’s structure. When you insert the table, at least some row and cell elements are inserted along with it, ready for you to provide the contents.

Elements for structured tables and table parts

A table and its parts (such as title, rows, and cells) are each represented in an element. You can see and work with these elements in the Structure view.

Table and table part elements

When you insert a table element, some of the table parts are inserted automatically. You can use the Element Catalog as a guide for building the rest of the table. If you add more table parts, they can also have an initial structure; for example, a new row element contains cell elements. The content rules for table and table-part elements define an initial structure for that element.

A table can also have cells that are defined to remain empty. No valid elements can be inserted in these cells, and you cannot type in them. An empty cell element’s tag describes the use of the cell—look for names such as BlankHeader or SpacerCell.

How structured tables are formatted

The appearance of a structured table is determined by its table format, various settings in the Table menu, and paragraph formats for text.

Table formats

A table format controls the spacing, indentation, and alignment of a table in a column, the start position on a page, the location of the title, default margins for cells, the direction of autonum­bering in cells, and default ruling and shading. A document stores table formats in a Table Catalog.

The format rules for a table element suggest a particular table format. You can apply a different format to the table at any time and the change is not considered a format rule override. (Changing the table format makes a table invalid, though, if the format adds a title and the table’s content rules don’t allow one.)

Table menu commands

The Table menu has commands for rotating and straddling cells, changing cell height and page breaks, adding rows and columns, and applying custom ruling and shading to cells. These settings take precedence over the table format for particular cells.

You can use any of the Table menu commands in a structured table. The commands are not format rule overrides and, except for Add Rows And Columns, do not affect the structure of the table.

Paragraph formats

Paragraph formats define fonts, line spacing, and other properties for text in the cells and the title. Table-part elements can specify paragraph formats.

DITA support for tables

DITA topics support two types of tables. The <table> element uses the OASIS Exchange Table Model (formerly known as the CALS table model). The OASIS table supports the spanning of multiple rows or columns for special layout or organizational needs, and provides a wide variety of controls over the display properties of the data and even the table structure itself.

The <table> element organizes arbitrarily complex relationships of tabular information. This standard table markup allows column or row spanning and table captions or descriptions. An optional title allowed inside the table element provides a caption to describe the table.

The DITA table is based on the OASIS Exchange Table Model, augmented with DITA attributes that enable it for specialization, conref, and other DITA processing. In addition, the table includes a desc element, which enables table description that is parallel with figure description.

In DITA tables, in place of the expanse attribute used by other DITA elements, the pgwide attribute is used to conform to the OASIS Exchange Table Model. This attribute has a similar semantic (1=page width; 0=resize to galley or column).

note:  The scale attribute represents a stylistic markup property that is maintained (for now) in tables for legacy purposes. External style sheets should enable less dependency on this attribute. You should use the scale attribute judiciously in your topics.

The other table structure in DITA is called <simpletable>. As the name implies, it is structurally less complex than the OASIS table, and can be used as a simple, regular table for which close control of formatting is not as important. The main advantage of simpletable is for describing lists of data with regular headings, such as telephone directory listings, display adapter configuration data, or API properties.