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.
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.
. First Step
. Second Step
. Third StepDefinition 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}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.\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>[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.
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.
[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 <‌<ISO7301,section=1>>.
ASCII Art
Metanorma supports ASCII Art, corresponding to HTML preformatted text (<pre>), which is specified in AsciiDoc with a ..‌.. 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.