Tables

General

Tables are useful for displaying data of the same structure.

Metanorma AsciiDoc tables are required to handle the full range of complexity of standardization documents, and is therefore significantly more powerful than typical AsciiDoc tables.

Note

Typical AsciiDoc already handles tables very well for a non-XML markup language.

Basics

Metanorma AsciiDoc supports all basic table syntaxes of AsciiDoc, including:

cells spanning multiple rows and columns;
horizontal alignment;
vertical alignment metanorma-standoc ≥ v1.5.3.

Given AsciiDoc is a plain-text format, it uses specific symbols to determine where new table rows and columns begin.

Example of a simple AsciiDoc tableadoc

[cols="1,1"] <1>
.A table with a title <2>
|=== <3>
|Cell in column 1, header row |Cell in column 2, header row <4>
|Cell in column 1, row 2
|Cell in column 2, row 2 <5>
|=== <6>

Tip

For table formatting options, such as joining cells or setting text alignment, please refer to AsciiDoc table documentation.

Table width

The table width can be set with the width attribute metanorma-standoc ≥ v1.3.21.

width

Width of table. Valid values listed below.

{percentage}%: a percentage (e.g. 70%)
{pixels}px: a pixel count (e.g. 500px)
full-page-width: PDF-specific. Specifies that the table spans the whole page width regardless of the number of columns on the page. metanorma-standoc ≥ v2.8.6
Note
This feature is not supported in typical AsciiDoc.
text-width: PDF-specific. Specified that the table will be as wide as the text column that contains it. metanorma-standoc ≥ v2.8.6
Note
This feature is not supported in typical AsciiDoc.

Note

The non-PDF width attribute values align with HTML CSS and HTML 4 behavior.

Table width spanning 70% of the rendered output medium

[width=70%]
|===
| Vehicle | Passenger
| Mazda 3 | Bob
| Tesla Model Y | Alice
|===

Table width spanning full page width in PDF regardless of number of columns

[width=full-page-width]
|===
|A |B
|C |D
|===

Column width

Table columns can also have their widths set metanorma-standoc ≥ v1.5.3.

Table column widths must be enumerated explicitly per column to generate column widths.

.Example of table with equal width columns

Example

The following syntax will be processed as generating equal width columns.

[cols="1,1,1"]

Note

In typical AsciiDoc, [cols="3"] is considered a shorthand to [cols="1,1,1"], but this is not supported in Metanorma AsciiDoc.

For long tables that need to continue onto the next page in the DOC or PDF rendering of a document, Metanorma, by default, will automatically repeat the header after every page break.

To suppress this behavior, you can apply the noheader value to the options attribute using its formal (options=noheader) or shorthand (%noheader) syntax. There is a caveat that this option will also deactivate the implicit assignment of the header to the first row of the table (see Implicitly assign header to the first row). Therefore, you will need to apply the header tag (h|) to every cell of the first row to define it as the header.

Supplementary components

A table allows the following supplementary components:

Key
Text
Notes
Footnotes

The order of rendering of these components are in the following order:

Key > Text > Note > Footnote

Note

This order aligns with ISO's editorial practice.

Key

Key can be followed by a definition list for the variables used in the table, just like formulae.

This definition list is marked up with [%key] metanorma-standoc ≥ v1.6.3.

The syntax is as follows:

|===
|Location |Distance
|Over there | 6
|===
[%key] <1>
{some-id}:: {some-description} <2>

.Table containing a key / legend

Example

|===
|Location       | Distance
|Over here      | s
|Over there     | m
|Way over there | l
|===
[%key]
stem:[s]:: Short distance
stem:[m]:: Medium distance
stem:[l]:: Far away

A key can also be a paragraph preceding, following, or instead of the definition list; the following syntax is also allowed metanorma-standoc ≥ v3.3.0

[%key]
Paragraph used instead of definition list

[%key]
--
Open block allowing multiple paragraphs and definition lists to be combined into a single key
a::b
c::d
Text may also follow after the definition list in a key
--

Note

The key definition list can also be preceded by a paragraph consisting of \Key, though that is not recommended.

Notes and footnotes

Metanorma AsciiDoc tables behave differently from typical AsciiDoc with notes and footnotes due to the requirements of standardization documents.

Specifically:

table cell footnotes (footnote:[...]) are rendered inside the table;
notes (NOTE: ...) following the table are rendered inside the table footer.

Note

Typical AsciiDoc renders table cell footnotes inside the cell, and notes trailing the table outside the table.

Tip

Table 1 in the Metanorma ISO Rice example document illustrates a large range of table formatting options.

Statement concerning units

A statement concerning units used can be added to a table, indicating the units of measurement used in the table.

Note

This currently applies to the ISO, IEC and BSI flavors, and flavors that inherit from them.

The units statement is encoded as a NOTE of type units ([NOTE,type=units]).

The statement is rendered in the top-right corner of the table metanorma-iso ≥ v2.3.6.

Table with a statement concerning units

|===
|Location |Distance
|Over there | 6
|===
[NOTE,type=units]
Distance in kilometres

Statement concerning requirements

A statement concerning requirements used can be added to a table.

Note

This currently applies to the ISO, IEC and BSI flavors, and flavors that inherit from them.

The requirements statement is encoded as a NOTE of type requirement ([NOTE,type=requirement]).

The statement is rendered with the other table notes in the table footer metanorma-iso ≥ v3.0.5. Unlike other table notes, it is not numbered or labelled as a note.

Table with a statement concerning units

|===
|Location |Distance
|Over there | 6
|===
[NOTE,type=requirement]
The distance shall be verified independently
[NOTE]
"Over there" is to be understood as not over here

Multiple header rows

Metanorma AsciiDoc supports the option of multiple header rows via attribute headerrows to deal with the complexity of standardization documents' tables requiring labels, variables, and units to lining up in the header.

[headerrows=2]
|===
.2+|Sample 3+^| Value
| Test A | Test B | Test C
| Component 1 | Pass | Fail | Pass
|===

This renders as:

Sample 3+^h	Value
Test A h	Test B h
Test C	Component 1
Pass	Fail
Pass

Note

This feature is not supported in typical AsciiDoc.

Table styling

General

Metanorma supports customized styling of tables to create visually distinctive tables for highlighting important information in standards documents.

Styling is achieved through a limited subset of CSS properties applied to rows and cells.

Whole table

Styling is applied to the full table through table attributes:

css-style

The attribute css-style applies CSS styles to an entire table metanorma-standoc ≥ v3.1.1

Example

== Fossil analysis test
[#table1]
[cols="<,^,^,^,^",options="header,footer",headerrows=2,css-style="border: none; color: purple; background-color: #eeeeee"]
.Maximum permissible mass fraction of defects in dinosaur fossil specimens
|===
.2+^|Defect 4+^| Maximum permissible mass fraction of defects in fossil specimens +
stem:[w_max] +
%
| in raw excavated fossils td-style:[color: green] td-style:[background-color: blue] | in prepared fossil specimens | in consolidated fossils | in reconstructed specimens tr-style:[background-color: red]
| Sediment contamination: organic footnote:[Organic contamination includes plant matter, modern bone fragments, wood particles, etc.] | 5,0 | 2,0 | 3,0 | 1,0
// not rendered list here
| Sediment contamination: inorganic footnote:[Inorganic contamination includes sand, clay, mineral deposits, etc.] | 3,0 | 1,5 | 2,0 | 1,0
| Modern bone contamination td-style:[background-color: blue]| 1,0 td-style:[border: 1px dashed #FF0000; color: yellow]| 0,5 | 0,8 tr-style:[background-color: green] | 0,3
| Unprepared fossil material | Not applicable | 2,0 | 1,5 | 1,0
| Prepared fossil material | 2,0 | Not applicable | 1,5 | 1,0
| Consolidated fossil material | 1,5 | 1,0 | Not applicable | 0,8
| Reconstructed fossil material | 1,0 | 0,8 | 0,5 | Not applicable
| Fragment loss | 0,2 | 0,1 | 0,1 | 0,1
| Surface weathering | 8,0 footnote:fossilmass[The maximum permissible mass fraction of defects shall be determined with respect to the total specimen mass after preparation.] | 5,0 | 6,0 footnote:fossilmass[] | 3,0
| Chemical damage | 6,0 | 4,0 | 5,0 | 3,0
| Mechanical damage | 10,0 | 6,0 | 8,0 | 4,0
| Incomplete preservation | 15,0 footnote:fossilmass[] | 12,0 | Not applicable | Not applicable
| Mineral replacement | 20,0 | 18,0 | 15,0 footnote:fossilmass[] | 12,0
| Partial pyritization | Not applicable | Not applicable | 8,0 footnote:fossilmass[] | 6,0
| Tool marks | Not applicable | Not applicable | 2,0 | 1,0
| Matrix residue | 3,0 footnote:fossilmass[] | 2,0 | 1,5 footnote:fossilmass[] | 1,0
5+a| Live organisms shall not be present. Dead organisms shall be included in organic contamination.
|===

Custom classes

A custom CSS class can be attached to a table using the class attribute metanorma-standoc ≥ v3.4.8. This allows CSS or JavaScript to target specific tables in HTML output -- for example, to make a particular table sortable.

[class="sortable"]
|===
|A |B
|===

The custom class is appended to the table's built-in class rather than replacing it, so the flavour's default table styling is preserved and the custom class is added alongside it. Multiple space-separated classes are passed through verbatim:

[class="sortable fixed"]
|===
|A |B
|===

Note

The class attribute affects HTML output only. It is not applied to Word output, whose CSS handling is more restrictive; a custom-class table still renders normally in Word, but without the custom class.

Note

The class attribute does not affect a table's borders or shading. Those are controlled independently by [%plain] (see below): a table with a custom class still receives the flavour's default table styling unless [%plain] is also given.

Row and cell styling

Metanorma provides two primary commands for applying CSS styles to table elements:

tr-style:[...]: Applies CSS styles to an entire table row metanorma-standoc ≥ v3.0.4
td-style:[...]: Applies CSS styles to a specific table cell metanorma-standoc ≥ v3.0.4

Metanorma also supports the attribute css-style which applies to tables themselves metanorma-standoc ≥ v3.1.1

Flavours of Metanorma often apply border or shading to tables by default, as prescribed by the SDO. In order to overrule these defaults, and reset a table not to have any styling, give it the attribute [%plain] metanorma-standoc ≥ v3.1.2

When a table is not [%plain], the default ISO-style border treatment applied by most flavours consists of:

a 1px table border with no cell spacing;
a heavy top border on the first row, with bold header cells;
light separators between body rows, and a heavy border on the last row.

Giving a table [%plain] removes all of this, so its appearance must be built from scratch using css-style, tr-style:, td-style:, or a custom class.

Supported CSS properties

The CSS properties supported in Metanorma for table rows and cells are as follows. Properties that are not listed here are not supported.

background-color: Sets the background color of a cell or row.
color: Sets the text color of a cell or row.
border: Sets all border properties in one declaration metanorma-standoc ≥ v3.0.7
border-* attributes: Including border-width, border-style, border-color, and directional variants such as border-top-style metanorma-standoc ≥ v3.0.7
Note
The border-* properties follow standard CSS conventions, allowing you to target specific sides of a cell or row.

.Property value examples

Example

CSS properties accept standard CSS values:

background-color: red, #ff0000, rgb(255,0,0)
color: blue, #0000ff, rgb(0,0,255)
border: 1px solid black
border-width: 1px, 2px, thin
border-style: solid, dashed, dotted
border-color: black, #000000

Application methods

Styles can be applied in three ways:

Row-level styling: Apply to an entire row using tr-style:[...] at the end of the last cell in that row
Cell-level styling: Apply to a specific cell using td-style:[...] immediately after the cell's content, before the next cell
Combined styling: Apply multiple styles to the same element by using multiple style macros in sequence

Simple example with row-level styling

[css-style="background-color: yellow"]
|===
|A |B |C tr-style:[background-color: red]
h|1 td-style:[background-color: green] td-style:[color: blue]
|2 tr-style:[background-color: green]
|3
|4 |5 td-style:[background-color: green] | 6
|===

Here:

background-color: red is applied to the first row
background-color: green is applied to the second row
background-color: green and color: blue (as a combination of styles) are applied to the first (header) cell of the second row
background-color: yellow, inherited from the table style, is applied to the third row
background-color: green, overriding the table style (as do all the foregoing background-color instances), is applied to the second cell of the third row

.Table with color-coded cells indicating results

Example

|===
|Test ID |Test Method |Result |Conformity tr-style:[background-color: #eeeeee]
|TC-001 |Method A |Pass td-style:[color: green] |Conforms
|TC-002 |Method B |Fail td-style:[color: red] |Does not conform
|TC-003 |Method A |Not tested td-style:[color: gray] |Incomplete
|===

Here:

background-color: #eeeeee is applied to the header row
color: green is applied to the first cell of the second row
color: red is applied to the second cell of the third row
color: gray is applied to the first cell of the third row

.Table with border styling

Example

|===
|Standard |Edition |Publication Date tr-style:[border-bottom: 2px solid black]
|ISO 8601 td-style:[border-right: 1px solid gray] |Third edition |2019-02
|ISO 19005-1 td-style:[border-right: 1px solid gray] |First edition |2005-10
|ISO/IEC 10646 td-style:[border-right: 1px solid gray] |Sixth edition |2020-05
|===

Here:

border-bottom: 2px solid black is applied to the header row
border-right: 1px solid gray is applied to the first cell of the second row
border-right: 1px solid gray is applied to the second cell of the second row
border-right: 1px solid gray is applied to the first cell of the third row

Accessibility metadata

Metanorma AsciiDoc supports assigning accessibility metadata for tables, including alt text and summary text, via table attributes.

alt: alternate text that describes the table;
summary: summary text that describes a summary of the content provided by the table.

Both are rendered as a summary of the table for accessibility.

Note

Alternate text is shown when the table can not be displayed (HTML only).

Example of assigning alt text and summary text

[alt=Table of tested components,summary=Table of components being tested in Tests A to C]
.2+|Sample 3+^| Value
| Test A | Test B | Test C
| Component 1 | Pass | Fail | Pass
|===

Note

This feature is not supported in typical AsciiDoc.

Complex table examples

Example table 1

Example of a more complex tableadoc

[headerrows=2,alt=Table of maximum mass fraction of defects in husked rice,summary=Table enumerating the permissible mass fraction of defects in husked and various classes of milled rice,width=70%]
|===
.2+|Defect 4+^| Maximum permissible mass fraction of defects in husked rice +
stem:[w_max]
| in husked rice | in milled rice (non-glutinous) | in husked parboiled rice | in milled parboiled rice
| Extraneous matter: organic footnote:[Organic extraneous matter includes foreign seeds, husks, bran, parts of straw, etc.] | 1,0 | 0,5 | 1,0 | 0,5
|===

which renders:

Illustration of a table in Metanorma (DOC output). Configuration: 70% of width — two header rows

Example table 2

Table 1 in the Metanorma ISO Rice example document illustrates a large range of table formatting options. Search for #table1.

Table sources

A table can incorporate an indication of its source.

The source is expected to be a bibliographical reference metanorma-standoc ≥ v2.4.2.

Multiple sources can be given with separate [.source] blocks.

Any such sources need to appear after the table, and before any notes which will also be included in the table.

Table with a single source and a note

|===
| Head | Head
| Row  | Row
|===
[.source]
<<iso1212>>
NOTE: Note 1

Table with multiple sources and notes

|===
| Head | Head
| Row  | Row
|===
[.source]
<<iso1212>>, reformatted
[.source]
<<iso1213>>,
NOTE: Note 1
NOTE: Note 2

The first source will indicate it is "reformatted" as the text after the comma is treated as the modification, while the second source will indicate it is "modified" since there is a trailing comma but no description of modification.

Note

The mechanism for indicating source is identical for terminology sources and figure sources.

Edit this page on GitHub →