9 Tables

This section contains editorial rules on how to create tables:

Section 9.1, “Use tables to represent sets of related pieces of information (ASM-44)”
Section 9.2, “Add tables in a defined sequence (ASM-45)”
Section 9.3, “Highlight table headers (ASM-55)”
Section 9.4, “Uniform cell border thicknesses (ASM-93)”
Section 9.5, “Start text in the table header with a capital letter (ASM-50)”
Section 9.6, “Add a description for each table (ASM-135)”

9.1 Use tables to represent sets of related pieces of information (ASM-44)

Use tables if you have to present a huge amount of similar data in a very compressed form.

Exceptions

If you have only one column in your table, turn the table into a list.

Example

Code

[#tab-de746de4-8483-4a29-87e1-31cf59244108]
.This is the caption of the table
[%header]
|===
|cell 1_1 | cell 1_2 | cell 1_3
|cell 2_1 | cell 2_2 | cell 2_3
|cell 3_1 | cell 3_2 | cell 3_3
|===

Result

Table 42. This is the caption of the table
cell 1_1	cell 1_2	cell 1_3
cell 2_1	cell 2_2	cell 2_3
cell 3_1	cell 3_2	cell 3_3

Source

Microsoft Style Guide: docs.microsoft.com/en-us/style-guide/scannable-content/tables

9.2 Add tables in a defined sequence (ASM-45)

Elements for tables shall be added in the following sequence:

An anchor (see rule ASM-78)
A caption to express the essence of the table
An attribute list for the table
A starting delimiter |===
A table (see docs.asciidoctor.org/asciidoc/latest/tables/build-a-basic-table/)
- Indent AsciiDoc cell content in columns under the table header if the lines are short enough.
- If the lines are too long, write one cell per line.
An ending delimiter |===
A blank line
An optional description (see rule ASM-135)

Exceptions

In case of a nested table, the inner table shall not have an additional caption.

Example

Code

[#tab-69612353-0fb1-496b-81d6-e42bc07940da]
.This is the caption of the table with short lines
[%header]
|===
|Head 1   |Head 2   |Head 3
|cell 1_1 |cell 1_2 |cell 1_3
|cell 2_1 |cell 2_2 |cell 2_3
|cell 3_1 |cell 3_2 |cell 3_3
|===

<<tab-69612353-0fb1-496b-81d6-e42bc07940da>> shows something that shall be explained in more detail.

[#tab-4c824f78-b3ce-4d16-a19b-c3732d066917]
.This is the caption of the table with long lines
[%header]
|===
|Head 1 |Head 2 |Head 3
|cell 1_1 with a very long line in the content
|cell 1_2
|cell 1_3

|cell 2_1
|cell 2_2 with a very long line in the content
|cell 2_3

|cell 3_1
|cell 3_2
|cell 3_3 with a very long line in the content
|===

<<tab-4c824f78-b3ce-4d16-a19b-c3732d066917>> shows something that shall be explained in more detail.

Result

Table 43. This is the caption of the table with short lines
Head 1	Head 2	Head 3
cell 1_1	cell 1_2	cell 1_3
cell 2_1	cell 2_2	cell 2_3
cell 3_1	cell 3_2	cell 3_3

Table 43 shows something that shall be explained in more detail.

Table 44. This is the caption of the table with long lines
Head 1	Head 2	Head 3
cell 1_1 with a very long line in the content	cell 1_2	cell 1_3
cell 2_1	cell 2_2 with a very long line in the content	cell 2_3
cell 3_1	cell 3_2	cell 3_3 with a very long line in the content

Table 44 shows something that shall be explained in more detail.

Source

ASAM specific rule.

9.3 Highlight table headers (ASM-55)

Highlight table headers in gray color. The following color codes shall be used:

HEX code: #DFDAD7
RGB code: 233,218,215

Exceptions

There are no exceptions.

Example

Table 45. Highlighted table header
Gray header first column	Gray header second column
…	…

Source

ASAM specific rule.

9.4 Uniform cell border thicknesses (ASM-93)

All lines in tables, for example, inner cells, outer frames, and headers shall have the same cell border thicknesses.

Exceptions

There are no exceptions.

Example

There is no example.

Source

ASAM specific rule.

9.5 Start text in the table header with a capital letter (ASM-50)

In a cell in the header row of a table, only the first word begins with an uppercase letter (sentence-style capitalization).

Exceptions

Acronyms and proper names are spelled as is.

Example

Table 46. Use of uppercase in the table header
No	Yes
Wrong Formatting of a Heading	Correct formatting of a heading
Asam rules to follow	ASAM rules to follow
Scope of OpenScenario	Scope of ASAM OpenSCENARIO

Source

Microsoft Style Guide: docs.microsoft.com/en-us/style-guide/scannable-content/tables

9.6 Add a description for each table (ASM-135)

The description should be below the table.
The description shall start with the text [Reference to table] shows.
The description shall not have an initial article.
The description shall not contain references to the placement of the table, for example, before or below.
A reference to a table shall be realized by a table anchor. Table references are displayed as a link.

Exceptions

There are no exceptions.

Example

Code

<<tab-7558b905-679d-4fb9-affa-3b3b72025a18>> shows all available commands and the corresponding parameters for both communication directions.

Result

Table 58 shows all available commands and the corresponding parameters for both communication directions.

Source

ASAM specific rule.