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!")
----

Paragraphs and lists are types of blocks that do not need any delimiters. They are separated by a blank line in between blocks.
Comments use four slashes as a delimiter ////. No other block uses slashes to begin and end a block.
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: m_D.

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)

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.
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.
Starting delimiter |===
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.
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>.
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 heads and table subheads are marked up as header cells. They are differentiated by line break:

|===
| Header1 | Header2

h| Table Row Head +
Table Row Subhead | Value

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]

Anchor for references
Image title
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.
[%key] indicates that the image has a key.
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

Start with the signal word in all caps enclosed in square brackets.
Insert the block delimiter.
Insert any AsciiDoc markup that you need.
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:

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

Title for your code sample (optional)
[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.
Starting delimiter
Sample code
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

See Auto-numbering.