Draft

1.2 (2019-02-09)

Tables

This is a draft specification. It is likely that changes will still be made before the final specification.

Use the table element to arrange data into rows and columns for easier reading. Mallard tables are designed to make it easy to handle common formatting needs.

Notes

The table element contains the following content:
- An optional info element.
- An optional title element.
- An optional desc element.
- Optionally either one or more col elements or one or more colgroup elements.
- Either one or more tr elements or the following:
  
  An optional thead element.
  
  One or more tbody elements.
  
  An optional tfoot element.
The table element can occur in any general block context, including inside pages, sections, and certain block elements.
The style attribute takes a space-separated list of style hints. Processing tools should adjust their behavior according to those style hints they understand.
The frame attribute controls the frame around the entire table. Valid values are "all", "none", or a space-separated list of the values "top", "bottom", "left", and "right".
The rules attribute controls lines between rows and columns. Valid values are "all", "groups", "none", or a space-separated list of "rows", "rowgroups", "cols", and "colgroups".
The shade attribute controls shading of alternating rows and columns. Valid values are "all", "groups", "none", or a space-separated list of "rows", "rowgroups", "cols", and "colgroups".
The table element can have attributes from external namespaces. See External Namespaces for more information on external-namespace attributes.

Examples

Basic Table Examples

Create a basic table:

<table>
  <tr>
    <td><p>Mallard</p></td>  <td><p>Anas platyrhynchos</p></td>
    <td><p>56-65 cm</p></td> <td><p>900-1200 g</p></td>
  </tr>
  <tr>
    <td><p>Eurasian Wigeon</p></td> <td><p>Anas penelope</p></td>
    <td><p>45-50 cm</p></td>        <td><p>680 g</p></td>
  </tr>
  <tr>
    <td><p>Common Teal</p></td> <td><p>Anas crecca</p></td>
    <td><p>34-43 cm</p></td>    <td><p>360 g</p></td>
  </tr>
  <tr>
    <td><p>Northern Pintail</p></td> <td><p>Anas acuta</p></td>
    <td><p>59-76 cm</p></td>         <td><p>450-1360 g</p></td>
  </tr>
</table>

Mallard	Anas platyrhynchos	56-65 cm	900-1200 g
Eurasian Wigeon	Anas penelope	45-50 cm	680 g
Common Teal	Anas crecca	34-43 cm	360 g
Northern Pintail	Anas acuta	59-76 cm	450-1360 g

The frame Attribute

Place a frame on the top and bottom of the table:

<table frame="top bottom">
  <tr>
    <td><p>Mallard</p></td>  <td><p>Anas platyrhynchos</p></td>
    <td><p>56-65 cm</p></td> <td><p>900-1200 g</p></td>
  </tr>
  <tr>
    <td><p>Eurasian Wigeon</p></td> <td><p>Anas penelope</p></td>
    <td><p>45-50 cm</p></td>        <td><p>680 g</p></td>
  </tr>
  <tr>
    <td><p>Common Teal</p></td> <td><p>Anas crecca</p></td>
    <td><p>34-43 cm</p></td>    <td><p>360 g</p></td>
  </tr>
  <tr>
    <td><p>Northern Pintail</p></td> <td><p>Anas acuta</p></td>
    <td><p>59-76 cm</p></td>         <td><p>450-1360 g</p></td>
  </tr>
</table>

Mallard	Anas platyrhynchos	56-65 cm	900-1200 g
Eurasian Wigeon	Anas penelope	45-50 cm	680 g
Common Teal	Anas crecca	34-43 cm	360 g
Northern Pintail	Anas acuta	59-76 cm	450-1360 g

Place a frame on all sides of the table:

<table frame="all">
  <tr>
    <td><p>Mallard</p></td>  <td><p>Anas platyrhynchos</p></td>
    <td><p>56-65 cm</p></td> <td><p>900-1200 g</p></td>
  </tr>
  <tr>
    <td><p>Eurasian Wigeon</p></td> <td><p>Anas penelope</p></td>
    <td><p>45-50 cm</p></td>        <td><p>680 g</p></td>
  </tr>
  <tr>
    <td><p>Common Teal</p></td> <td><p>Anas crecca</p></td>
    <td><p>34-43 cm</p></td>    <td><p>360 g</p></td>
  </tr>
  <tr>
    <td><p>Northern Pintail</p></td> <td><p>Anas acuta</p></td>
    <td><p>59-76 cm</p></td>         <td><p>450-1360 g</p></td>
  </tr>
</table>

Mallard	Anas platyrhynchos	56-65 cm	900-1200 g
Eurasian Wigeon	Anas penelope	45-50 cm	680 g
Common Teal	Anas crecca	34-43 cm	360 g
Northern Pintail	Anas acuta	59-76 cm	450-1360 g

The rules Attribute

Place rules between each row:

<table frame="all" rules="rows">
  <tr>
    <td><p>Mallard</p></td>  <td><p>Anas platyrhynchos</p></td>
    <td><p>56-65 cm</p></td> <td><p>900-1200 g</p></td>
  </tr>
  <tr>
    <td><p>Eurasian Wigeon</p></td> <td><p>Anas penelope</p></td>
    <td><p>45-50 cm</p></td>        <td><p>680 g</p></td>
  </tr>
  <tr>
    <td><p>Common Teal</p></td> <td><p>Anas crecca</p></td>
    <td><p>34-43 cm</p></td>    <td><p>360 g</p></td>
  </tr>
  <tr>
    <td><p>Northern Pintail</p></td> <td><p>Anas acuta</p></td>
    <td><p>59-76 cm</p></td>         <td><p>450-1360 g</p></td>
  </tr>
</table>

Mallard	Anas platyrhynchos	56-65 cm	900-1200 g
Eurasian Wigeon	Anas penelope	45-50 cm	680 g
Common Teal	Anas crecca	34-43 cm	360 g
Northern Pintail	Anas acuta	59-76 cm	450-1360 g

Place rules between each column:

<table frame="all" rules="cols">
  <tr>
    <td><p>Mallard</p></td>  <td><p>Anas platyrhynchos</p></td>
    <td><p>56-65 cm</p></td> <td><p>900-1200 g</p></td>
  </tr>
  <tr>
    <td><p>Eurasian Wigeon</p></td> <td><p>Anas penelope</p></td>
    <td><p>45-50 cm</p></td>        <td><p>680 g</p></td>
  </tr>
  <tr>
    <td><p>Common Teal</p></td> <td><p>Anas crecca</p></td>
    <td><p>34-43 cm</p></td>    <td><p>360 g</p></td>
  </tr>
  <tr>
    <td><p>Northern Pintail</p></td> <td><p>Anas acuta</p></td>
    <td><p>59-76 cm</p></td>         <td><p>450-1360 g</p></td>
  </tr>
</table>

Mallard	Anas platyrhynchos	56-65 cm	900-1200 g
Eurasian Wigeon	Anas penelope	45-50 cm	680 g
Common Teal	Anas crecca	34-43 cm	360 g
Northern Pintail	Anas acuta	59-76 cm	450-1360 g

Place rules between each row group:

<table frame="all" rules="rowgroups cols">
  <tbody>
    <tr>
      <td><p>Mallard</p></td>  <td><p>Anas platyrhynchos</p></td>
      <td><p>56-65 cm</p></td> <td><p>900-1200 g</p></td>
    </tr>
    <tr>
      <td><p>Eurasian Wigeon</p></td> <td><p>Anas penelope</p></td>
      <td><p>45-50 cm</p></td>        <td><p>680 g</p></td>
    </tr>
  </tbody>
  <tbody>
    <tr>
      <td><p>Common Teal</p></td> <td><p>Anas crecca</p></td>
      <td><p>34-43 cm</p></td>    <td><p>360 g</p></td>
    </tr>
    <tr>
      <td><p>Northern Pintail</p></td> <td><p>Anas acuta</p></td>
      <td><p>59-76 cm</p></td>         <td><p>450-1360 g</p></td>
    </tr>
  </tbody>
</table>

Mallard	Anas platyrhynchos	56-65 cm	900-1200 g
Eurasian Wigeon	Anas penelope	45-50 cm	680 g
Common Teal	Anas crecca	34-43 cm	360 g
Northern Pintail	Anas acuta	59-76 cm	450-1360 g

Place rules between each column group:

<table frame="all" rules="rows colgroups">
  <colgroup><col/><col/></colgroup>
  <colgroup><col/><col/></colgroup>
  <tr>
    <td><p>Mallard</p></td>  <td><p>Anas platyrhynchos</p></td>
    <td><p>56-65 cm</p></td> <td><p>900-1200 g</p></td>
  </tr>
  <tr>
    <td><p>Eurasian Wigeon</p></td> <td><p>Anas penelope</p></td>
    <td><p>45-50 cm</p></td>        <td><p>680 g</p></td>
  </tr>
  <tr>
    <td><p>Common Teal</p></td> <td><p>Anas crecca</p></td>
    <td><p>34-43 cm</p></td>    <td><p>360 g</p></td>
  </tr>
  <tr>
    <td><p>Northern Pintail</p></td> <td><p>Anas acuta</p></td>
    <td><p>59-76 cm</p></td>         <td><p>450-1360 g</p></td>
  </tr>
</table>

Mallard	Anas platyrhynchos	56-65 cm	900-1200 g
Eurasian Wigeon	Anas penelope	45-50 cm	680 g
Common Teal	Anas crecca	34-43 cm	360 g
Northern Pintail	Anas acuta	59-76 cm	450-1360 g

The shade Attribute

Shade alternating rows:

<table frame="all" shade="rows">
  <tr>
    <td><p>Mallard</p></td>  <td><p>Anas platyrhynchos</p></td>
    <td><p>56-65 cm</p></td> <td><p>900-1200 g</p></td>
  </tr>
  <tr>
    <td><p>Eurasian Wigeon</p></td> <td><p>Anas penelope</p></td>
    <td><p>45-50 cm</p></td>        <td><p>680 g</p></td>
  </tr>
  <tr>
    <td><p>Common Teal</p></td>     <td><p>Anas crecca</p></td>
    <td><p>34-43 cm</p></td>        <td><p>360 g</p></td>
  </tr>
  <tr>
    <td><p>Northern Pintail</p></td> <td><p>Anas acuta</p></td>
    <td><p>59-76 cm</p></td>         <td><p>450-1360 g</p></td>
  </tr>
</table>

Mallard	Anas platyrhynchos	56-65 cm	900-1200 g
Eurasian Wigeon	Anas penelope	45-50 cm	680 g
Common Teal	Anas crecca	34-43 cm	360 g
Northern Pintail	Anas acuta	59-76 cm	450-1360 g

Shade alternating columns:

<table frame="all" shade="cols">
  <tr>
    <td><p>Mallard</p></td>  <td><p>Anas platyrhynchos</p></td>
    <td><p>56-65 cm</p></td> <td><p>900-1200 g</p></td>
  </tr>
  <tr>
    <td><p>Eurasian Wigeon</p></td> <td><p>Anas penelope</p></td>
    <td><p>45-50 cm</p></td>        <td><p>680 g</p></td>
  </tr>
  <tr>
    <td><p>Common Teal</p></td>     <td><p>Anas crecca</p></td>
    <td><p>34-43 cm</p></td>        <td><p>360 g</p></td>
  </tr>
  <tr>
    <td><p>Northern Pintail</p></td> <td><p>Anas acuta</p></td>
    <td><p>59-76 cm</p></td>         <td><p>450-1360 g</p></td>
  </tr>
</table>

Mallard	Anas platyrhynchos	56-65 cm	900-1200 g
Eurasian Wigeon	Anas penelope	45-50 cm	680 g
Common Teal	Anas crecca	34-43 cm	360 g
Northern Pintail	Anas acuta	59-76 cm	450-1360 g

Shade alternating row groups:

<table frame="all" shade="rowgroups cols">
  <tbody>
    <tr>
      <td><p>Mallard</p></td>  <td><p>Anas platyrhynchos</p></td>
      <td><p>56-65 cm</p></td> <td><p>900-1200 g</p></td>
    </tr>
    <tr>
      <td><p>Eurasian Wigeon</p></td> <td><p>Anas penelope</p></td>
      <td><p>45-50 cm</p></td>        <td><p>680 g</p></td>
    </tr>
  </tbody>
  <tbody>
    <tr>
      <td><p>Common Teal</p></td>     <td><p>Anas crecca</p></td>
      <td><p>34-43 cm</p></td>        <td><p>360 g</p></td>
    </tr>
    <tr>
      <td><p>Northern Pintail</p></td> <td><p>Anas acuta</p></td>
      <td><p>59-76 cm</p></td>         <td><p>450-1360 g</p></td>
    </tr>
  </tbody>
</table>

Mallard	Anas platyrhynchos	56-65 cm	900-1200 g
Eurasian Wigeon	Anas penelope	45-50 cm	680 g
Common Teal	Anas crecca	34-43 cm	360 g
Northern Pintail	Anas acuta	59-76 cm	450-1360 g

Shade alternating column groups:

<table frame="all" shade="rows colgroups">
  <colgroup><col/><col/></colgroup>
  <colgroup><col/><col/></colgroup>
  <tr>
    <td><p>Mallard</p></td>  <td><p>Anas platyrhynchos</p></td>
    <td><p>56-65 cm</p></td> <td><p>900-1200 g</p></td>
  </tr>
  <tr>
    <td><p>Eurasian Wigeon</p></td> <td><p>Anas penelope</p></td>
    <td><p>45-50 cm</p></td>        <td><p>680 g</p></td>
  </tr>
  <tr>
    <td><p>Common Teal</p></td>     <td><p>Anas crecca</p></td>
    <td><p>34-43 cm</p></td>        <td><p>360 g</p></td>
  </tr>
  <tr>
    <td><p>Northern Pintail</p></td> <td><p>Anas acuta</p></td>
    <td><p>59-76 cm</p></td>         <td><p>450-1360 g</p></td>
  </tr>
</tbody>
</table>

Mallard	Anas platyrhynchos	56-65 cm	900-1200 g
Eurasian Wigeon	Anas penelope	45-50 cm	680 g
Common Teal	Anas crecca	34-43 cm	360 g
Northern Pintail	Anas acuta	59-76 cm	450-1360 g

Spanning Rows and Columns

Span multiple rows:

<table frame="all" rules="all">
  <tr>
    <td><p>Mallard</p></td>  <td><p>Anas platyrhynchos</p></td>
    <td><p>America, Europe, Asia, New Zealand</p></td>
  </tr>
  <tr>
    <td><p>Eurasian Wigeon</p></td> <td><p>Anas penelope</p></td>
    <td rowspan="2"><p>Eurasia</p></td>
  </tr>
  <tr>
    <td><p>Common Teal</p></td>     <td><p>Anas crecca</p></td>
  </tr>
  <tr>
    <td><p>Northern Pintail</p></td> <td><p>Anas acuta</p></td>
    <td><p>Europe, Asia, North America</p></td>
  </tr>
</table>

Mallard	Anas platyrhynchos	America, Europe, Asia, New Zealand
Eurasian Wigeon	Anas penelope	Eurasia
Common Teal	Anas crecca	Eurasia
Northern Pintail	Anas acuta	Europe, Asia, North America

Header Cells

Use th elements for column headers:

<table>
  <tr>
    <td></td>                <th><p>Scientific name</p></th>
    <th><p>Length</p></th>   <th><p>Mass</p></th>
  </tr>
  <tr>
    <td><p>Mallard</p></td>  <td><p>Anas platyrhynchos</p></td>
    <td><p>56-65 cm</p></td> <td><p>900-1200 g</p></td>
  </tr>
  <tr>
    <td><p>Eurasian Wigeon</p></td> <td><p>Anas penelope</p></td>
    <td><p>45-50 cm</p></td>        <td><p>680 g</p></td>
  </tr>
  <tr>
    <td><p>Common Teal</p></td> <td><p>Anas crecca</p></td>
    <td><p>34-43 cm</p></td>    <td><p>360 g</p></td>
  </tr>
  <tr>
    <td><p>Northern Pintail</p></td> <td><p>Anas acuta</p></td>
    <td><p>59-76 cm</p></td>         <td><p>450-1360 g</p></td>
  </tr>
</table>

	Scientific name	Length	Mass
Mallard	Anas platyrhynchos	56-65 cm	900-1200 g
Eurasian Wigeon	Anas penelope	45-50 cm	680 g
Common Teal	Anas crecca	34-43 cm	360 g
Northern Pintail	Anas acuta	59-76 cm	450-1360 g

Use th elements for column and row headers:

<table>
  <tr>
    <td></td>                <th><p>Scientific name</p></th>
    <th><p>Length</p></th>   <th><p>Mass</p></th>
  </tr>
  <tr>
    <th><p>Mallard</p></th>  <td><p>Anas platyrhynchos</p></td>
    <td><p>56-65 cm</p></td> <td><p>900-1200 g</p></td>
  </tr>
  <tr>
    <th><p>Eurasian Wigeon</p></th> <td><p>Anas penelope</p></td>
    <td><p>45-50 cm</p></td>        <td><p>680 g</p></td>
  </tr>
  <tr>
    <th><p>Common Teal</p></th> <td><p>Anas crecca</p></td>
    <td><p>34-43 cm</p></td>    <td><p>360 g</p></td>
  </tr>
  <tr>
    <th><p>Northern Pintail</p></th> <td><p>Anas acuta</p></td>
    <td><p>59-76 cm</p></td>         <td><p>450-1360 g</p></td>
  </tr>
</table>

	Scientific name	Length	Mass
Mallard	Anas platyrhynchos	56-65 cm	900-1200 g
Eurasian Wigeon	Anas penelope	45-50 cm	680 g
Common Teal	Anas crecca	34-43 cm	360 g
Northern Pintail	Anas acuta	59-76 cm	450-1360 g

Add a th element for a column group:

<table rules="colgroups">
  <colgroup><col/></colgroup>
  <colgroup><col/></colgroup>
  <colgroup><col/><col/></colgroup>
  <tr>
    <td></td> <td></td>
    <th colspan="2" scope="colgroup"><p>Size information</p></th>
  </tr>
  <tr>
    <td></td>                <th><p>Scientific name</p></th>
    <th><p>Length</p></th>   <th><p>Mass</p></th>
  </tr>
  <tr>
    <th><p>Mallard</p></th>  <td><p>Anas platyrhynchos</p></td>
    <td><p>56-65 cm</p></td> <td><p>900-1200 g</p></td>
  </tr>
  <tr>
    <th><p>Eurasian Wigeon</p></th> <td><p>Anas penelope</p></td>
    <td><p>45-50 cm</p></td>        <td><p>680 g</p></td>
  </tr>
  <tr>
    <th><p>Common Teal</p></th> <td><p>Anas crecca</p></td>
    <td><p>34-43 cm</p></td>    <td><p>360 g</p></td>
  </tr>
  <tr>
    <th><p>Northern Pintail</p></th> <td><p>Anas acuta</p></td>
    <td><p>59-76 cm</p></td>         <td><p>450-1360 g</p></td>
  </tr>
</table>

		Size information
	Scientific name	Length	Mass
Mallard	Anas platyrhynchos	56-65 cm	900-1200 g
Eurasian Wigeon	Anas penelope	45-50 cm	680 g
Common Teal	Anas crecca	34-43 cm	360 g
Northern Pintail	Anas acuta	59-76 cm	450-1360 g

Add th elements for row groups:

<table rules="rowgroups" shade="rows">
  <thead>
    <tr>
      <td></td>                <th><p>Scientific name</p></th>
      <th><p>Length</p></th>   <th><p>Mass</p></th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <th colspan="4" scope="rowgroup">
        <p>America, Europe, Asia, New Zealand</p>
      </th>
    </tr>
    <tr>
      <th><p>Mallard</p></th>  <td><p>Anas platyrhynchos</p></td>
      <td><p>56-65 cm</p></td> <td><p>900-1200 g</p></td>
    </tr>
  </tbody>
  <tbody>
    <tr>
      <th colspan="4" scope="rowgroup">
        <p>Eurasia</p>
      </th>
    </tr>
    <tr>
      <th><p>Eurasian Wigeon</p></th> <td><p>Anas penelope</p></td>
      <td><p>45-50 cm</p></td>        <td><p>680 g</p></td>
    </tr>
    <tr>
      <th><p>Common Teal</p></th> <td><p>Anas crecca</p></td>
      <td><p>34-43 cm</p></td>    <td><p>360 g</p></td>
    </tr>
  </tbody>
  <tbody>
    <tr>
      <th colspan="4" scope="rowgroup">
        <p>Europe, Asia, North America</p>
      </th>
    </tr>
    <tr>
      <th><p>Northern Pintail</p></th> <td><p>Anas acuta</p></td>
      <td><p>59-76 cm</p></td>         <td><p>450-1360 g</p></td>
    </tr>
  </tbody>
</table>

America, Europe, Asia, New Zealand
	Scientific name	Length	Mass
Mallard	Anas platyrhynchos	56-65 cm	900-1200 g
Eurasia
Eurasian Wigeon	Anas penelope	45-50 cm	680 g
Common Teal	Anas crecca	34-43 cm	360 g
Europe, Asia, North America
Northern Pintail	Anas acuta	59-76 cm	450-1360 g

Processing Expectations

The basic layout of tables, rows, columns, and cells follows the layout model for the similarly named elements in HTML, including row and column spanning. Mallard does not provide a means to control spacing, colors, or other stylistic effects you can control in HTML, nor does it make any guarantee about how processing tools will choose these effects.

Unlike HTML, Mallard does not consider each table cell to have its own border. Instead, there is a frame around the entire table, and rules between rows and columns. This is similar to setting the border-collapse CSS property on HTML tables.

A frame is drawn on the top, bottom, left, or right sides of the table if the corresponding value appears in the space-separated list in the frame attribute. If the frame attribute is simply "all", a frame is drawn on all sides of the table.

If the space-separated rules attribute contains the value rows or if it is set to "all", then a rule is drawn between each successive row. If the rules attribute contains the value rowgroups or if it is set to "groups", then a rule is drawn between successive rows if they do not belong to the same thead, tbody, or tfoot element.

If the space-separated rules attribute contains the value cols or if it is set to "all", then a rule is drawn between each successive column. If the rules attribute contains the value colgroups or if it is set to "groups", then a rule is drawn between successive columns if their corresponding col elements do not belong to the same colgroup element.

Mallard tables can shade alternating rows, columns, row groups, or column groups. A cell in a shaded row or column is drawn with a slightly darker background color, or a lighter color in a light-on-dark rendering. If a cell is in both a shaded row and a shaded column, it is drawn with an even darker background color, or an even lighter color in a light-on-dark rendering.

If the space-separated shade attribute contains the value rows or if it is set to "all", then every other row is shaded. If the shade attribute contains the value rowgroups or if it is set to "groups", then rows in every other thead, tbody, and tfoot element are shaded.

If the space-separated shade attribute contains the value cols or if it is set to "all", then every other column is shaded. If the shade attribute contains the value colgroups or if it is set to "groups", then columns in every other group are shaded, where two columns are in the same group if their corresponding col elements are in the same colgroup element.

When cells span multiple rows or columns, they are considered to be in their starting row and column for the purpose of shading.

The optional info element can provide metadata for the table, such as attributions, licensing information, and additional titles for extensions. It is not displayed directly.

Comparison to Other Formats

The table element is similar to the table element in DocBook. DocBook allows either CALS or HTML tables to be used in the table element. Mallard tables follow the HTML model. Like Mallard, DocBook treats frames, row separators, and column separators as belonging to the table, rather than to individual cells. Mallard provides more flexibility in controlling these.

The table element serves the same purpose as the table element in DITA, although DITA uses the CALS table model exclusively. Like Mallard, DITA treats the frames, row separators, and column separators as belonging to the table, rather than to individual cells. Mallard provides more flexibility in controlling these.

Schema

The formal definition of the Mallard language is maintained in RELAX NG Compact Syntax in code blocks within this specification. This is the formal definition for the table element. The namespace declarations for this definition are on the page Pages.

mal_table = element table {
  mal_table_attr,

  mal_info ?,
  mal_block_title ?,
  mal_block_desc ?,

  ( mal_table_col + |
    mal_table_colgroup +
  ) ?,

  ( mal_table_tr + |
    ( mal_table_thead ?,
      mal_table_tbody +,
      mal_table_tfoot ?
    )
  )
}
mal_table_attr = (
  attribute style { xsd:NMTOKENS } ?,
  attribute frame {
    "all" | "none" |
    list { ("top" | "bottom" | "left" | "right") * }
  } ?,
  attribute rules {
    "all" | "groups" | "none" |
    list { ("rows" | "rowgroups" | "cols" | "colgroups") * }
  } ?,
  attribute shade {
    "all" | "groups" | "none" |
    list { ("rows" | "rowgroups" | "cols" | "colgroups") * }
  } ?,
  mal_block_attr,
  mal_attr_external *
)