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 [added in https://github.com/metanorma/metanorma-standoc/releases/tag/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 table

[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)

1. Optional table attributes that specifies the table structure. The numbers specify the relative amount of spacing between the columns. cols="x,x" indicates that there are two columns.

2. The table title can be assigned by beginning a line with a dot .. Make sure that there is no space between the dot and the first word of the heading.

3. Starting table delimiter |===

4. Header row. The line immediately after the starting delimiter is the header row. To add a column, add a vertical bar | before the text that should be in the column.

5. When using the [cols] attribute, columns in the same row can appear on different lines of AsciiDoc text. Otherwise, they need to all be on the same line of text, like in <4>.

6. Closing table delimiter |===

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 [added in https://github.com/metanorma/metanorma-standoc/releases/tag/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. [added in https://github.com/metanorma/metanorma-standoc/releases/tag/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. [added in https://github.com/metanorma/metanorma-standoc/releases/tag/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.

Example 1. Table width spanning 70% of the rendered output medium

[width=70%]
|===
| Vehicle | Passenger

| Mazda 3 | Bob
| Tesla Model Y | Alice

|===

Example 2. 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 [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.5.3].

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

Example 3. Example of table with equal width columns

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] [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.6.3].

The syntax is as follows:

|===
|Location |Distance

|Over there | 6
|===

[%key] (1)
{some-id}:: {some-description} (2)

1. Specification of table key section

2. Key entry: {some-description} is text that describes information about the thing represented by {some-id}

Example 4. Table containing a key / legend

|===
|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

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 [added in https://github.com/metanorma/metanorma-iso/releases/tag/v2.3.6].

Example 5. Table with a statement concerning units

|===
|Location |Distance

|Over there | 6
|===

[NOTE,type=units]
Distance in kilometres

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	Value
	Test A	Test B	Test C
Component 1	Pass	Fail	Pass

Note	This feature is not supported in typical AsciiDoc.

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 6. 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 table

[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:

Figure 1. Illustration of a table in Metanorma (DOC output). Configuration: 70% of width, two header rows, one normal row, one footnote.

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 [added in https://github.com/metanorma/metanorma-standoc/releases/tag/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.

Example 7. Table with a single source and a note

|===
| Head | Head

| Row  | Row
|===

[.source]
<<iso1212>>

NOTE: Note 1

Example 8. 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.