Metanorma
On this page

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.

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 unitsadoc
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 w is an italic w, w; \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>
Note
In typical AsciiDoc, [cols="3"] is considered a shorthand to [cols="1,1,1"], but this is not supported in Metanorma AsciiDoc.

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]

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 noteadoc
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.adoc
[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:

[type=danger]
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>

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 <&#x200c;<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

ModSpec requirements

For guidance on how to specify ModSpec requirements in Metanorma, see ModSpec recommendations, requirements, and permissions.