Metanorma: Aequitate Verum

Block syntax

Information that forms a logical segment, such as a paragraph or a list, is called a block.

Most blocks start and end with a delimiter which is a matching sequence of characters. The delimiters tell the compiler that the text they contain belongs together.

Example 1. Examples for different blocks
I’m a paragraph and I don’t need a block delimiter. (1)

. I’m a list item and also do not need a delimiter
. I’m the second list item
. I'm list item number three

//// (2)
I’m a comment.
////

[source, python] (3)
----
print("Hello World!")
----
  1. Paragraphs and lists are types of blocks that do not need any delimiters. They are separated by a blank line in between blocks.

  2. Comments use four slashes as a delimiter ////. No other block uses slashes to begin and end a block.

  3. All other types of blocks rely on delimiters. Source code blocks use four dashes ----, example blocks use four equal signs ====. This particular block contains a source code snippet written in python.

There are many types of blocks in AsciiDoc, such as:

  • Paragraphs

  • Lists

  • Tables

  • Images

  • Admonitions (Note, Caution, Warning, etc.)

  • Examples

  • Code samples

  • Mathematic formulas

  • Term definitions

  • Comments

  • Literal (ASCII art)

  • Blockquotes

  • Reviewer Notes

Let’s look at the most common blocks.

Lists

General

Metanorma AsciiDoc supports three types of lists:

  • Unordered lists

  • Ordered lists

  • Definition lists

Unordered lists

Unordered lists are bulleted and can be nested by adding asterisks.

They look like this:

The main changes compared to the previous edition are:

* updated normative references;
* deletions:
** deletion of 4.3. [nested list item]
** deletion of 4.4. [nested list item]

Ordered lists

Ordered lists are invoked by beginning the line with a dot ..

List items are numbered automatically.

Note
The exact style of
. First Step
. Second Step
. Third Step

Definition lists

Definition lists (also called description lists) pair a term and a description together.

Occasionally they are used in a "Definitions" section to define units or terms. Definition lists can appear in other sections as well, except for the Terms section, which provides a special syntax for defining terms.

Definition lists follow the syntax of:

{term}:: {definition}
Example of definitions for units
stem:[w]:: is the mass fraction of grains with a particular defect in the test sample;
stem:[m_D]:: is the mass, in grams, of grains with that defect;
stem:[m_S]:: is the mass, in grams, of the test sample.
Note
stem:[] is used for mathematical formatting, and results in italics. So stem:[w] is an italic w, w; stem:[m_D] is an italic m with a D subscript: mD.

Tables

Tables are a useful tool to collect and display measured data. As AsciiDoc is all text input, it uses specific symbols to determine where new table rows and columns begin. A simple table looks like this:

[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. Attribute that specifies the table. cols=”x,x” tells the compiler that there are two columns. [cols="1,1"] The numbers specify the amount of spacing. For example, [cols="4,2,4"] would define three columns. The first and last column’s width would be four times the relative width and the middle column would be half as broad. This attribute is optional.

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

  3. Starting delimiter |===

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

  5. When you use 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 delimiter |===

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

Table cells under OGC always have a vertical alignment of middle [added in https://github.com/metanorma/metanorma-ogc/releases/tag/v1.4.1].

Any markup instructions to set cell alignment to a different vertical alignment are ignored.

Images

A block image is displayed as a discrete element, i.e., on its own line, in a document. A block image is designated by image macro name and followed by two colons (image::PATH[]). It’s preceded by a blank line, entered on a line by itself, and then followed by a blank line.

In standard documents images are informative and you might want to reference an image in the text. As with all references, you need to define an anchor. You can also explain a graphic by adding a key. The entries of the key follow the syntax of a definition list (key::Explanation).

[[figureC-1]] (1)
.Typical gelatinization curve (2)
image::images/rice_image2.png[Image of the gelatinization curve] (3)

[%key] (4)
stem:[t_90]:: time required to gelatinize 90 % of the kernels (5)
P:: point of the curve corresponding to a cooking time of stem:[t_90]
  1. Anchor for references

  2. Image title

  3. Image macro image::path/file.jpg[alt text]. If you don’t want to write alt text, you still need to append empty square brackets at the end of the macro.

  4. [%key] indicates that the image has a key.

  5. Key entries

Admonitions

Admonitions are signal words used to catch the reader’s attention, such as “TIP”, “NOTE”, or “WARNING”. There are two ways to declare an admonition: in a single paragraph and as a block.

Single-paragraph admonitions

Start a new line with the signal word in all caps and a colon and write your admonition.

Example for an inline note
NOTE: Advice on when to use which signal word is specified in ANSI Z535.6.

Block admonitions

  1. Start with the signal word in all caps enclosed in square brackets.

  2. Insert the block delimiter.

  3. Insert any AsciiDoc markup that you need.

  4. End the block with a block delimiter.

Example for a note block.
[NOTE] (1)
==== (2)
This is an example of an admonition block. (3)

Unlike an admonition paragraph, it may contain any AsciiDoc content.
The style can be any one of the admonition labels:

* NOTE
* TIP
* WARNING
* CAUTION
* IMPORTANT
==== (4)

Metanorma adds two more signal words: "Safety precautions" and "Danger". Since they are not standard AsciiDoc functionality, you’ll need to mark them with a type attribute like this:

DANGER: Do perform maintenance tasks while the machine is still operating.

Source code

Metanorma supports adding source code using the [source] attribute before a new block. If you specify the coding language, the sample will be highlighted correctly in HTML output.

Within the source code block, line breaks and space indentations are preserved. Have a look at the example:

.Sample Code (1)
[source,ruby] (2)
---- (3)
puts "Hello, world." (4)
%w{a b c}.each do |x|
  puts x
end
---- (5)
  1. Title for your code sample (optional)

  2. [source] specifies that the block contains code. ruby is the language used by the code block. The block will highlight keywords depending on the language.

  3. Starting delimiter

  4. Sample code

  5. Ending delimiter

Block quotes

Metanorma supports block quotes, which are specified in AsciiDoc with a __ delimiter, and the [quote] attribute beforehand. An author and citation can be added beforehand as attributes after `quote; the citation is processed as if it is contained in <<…​>>, using a bibliographic anchor defined in a bibliography.

[quote,ISO,"ISO7301,section=1"]
____
This is a block quotation.
____

This is rendered as:

This is a block quotation.

 — ISO, ISO:7301:2011, Section 1.

with "ISO7301,section=1" processed as if it is <‌<ISO7301,section=1>>.

ASCII Art

Metanorma supports ASCII Art, corresponding to HTML preformatted text (<pre>), which is specified in AsciiDoc with a ..&#x200c.. delimiter:

....
/-\       ***
| |  ==>  * *
\-/       ***
....

AsciiDoc with initial spaces, as a block indent, is processed as ASCII Art, and not as source code or a blockquote. If you require either, you will need to use the explicit required AsciiDoc markup.

Removing auto-numbering from blocks

In Metanorma for OGC, all block elements are auto-numbered in order to facilitate unique referencing.

Each block label is unique and typically composed of the block type with a sequence number. For instance, “Table 3” or “Figure 5”.

In some cases, the author may want to remove the unique label and the numbering applied to a block, for example, when inserting short source code blocks within text that have no need of being uniquely referenced.

All auto-numbered blocks can be marked to not be labelled via the unnumbered attribute option.

These block types include:

  • Figure

  • Example

  • Equation

  • Source code

  • Table

The unnumbered attribute can be used in the following ways, in equal effect.

For blocks without the explicit block type defined, prepend with the [%unnumbered] attribute right before the block definition.

Unnumbered figure using "[%unnumbered]"
[%unnumbered]
image::images/fig1.png[]

For blocks with their types defined explicitly that do not have the options attribute list, insert "%unnumbered" right after the block type, before the block type separator, e.g.: [example%unnumbered], [stem%unnumbered], etc.

Unnumbered example by appending "%unnumbered" to block type
[example%unnumbered]
Example content