Metanorma AsciiDoc markup (AsciiRFC v2)

Abstract

Any paragraphs following the document header are treated as the abstract (front/abstract), whether or not they are in abstract style. The abstract is terminated by either the first section header (which ends the document preamble), or an admonition (e.g. note).

Any admonitions before the first section header are treated as notes (front/note).

[abstract]
This is an abstract <1>
NOTE: This is a note <2>
[NOTE]
.Note 2 Title <3>
===
This is another note <2>
===

Sections and Subsections

[[id]] <1>
== Section title <2>
First paragraph of section <3>
Second paragraph of section <3>
=== Subsection title <4>
First paragraph of subsection <5>
==== Subsubsection title <6>
Content content content <7>

Appendices

[[id]] <1>
[appendix]
== Appendix 1 <2>
Content <3>

Examples

RFC XML does not recognize examples as a distinct element. Under v2, any Metanorma AsciiDoc example blocks are treated by default as figure; if they do not contain source code, code listing, mathematical formatting or ASCII art, they are treated as a block of text.

Source code listings

In RFC XML, artwork elements only occur within a figure wrapper; Metanorma-IETF supplies that wrapper if it is not provided explicitly.

.Without Figure Wrapper

begin() {
  source code listing <4>
}

1. figure@anchor (moved into supplied wrapper: anchors not supported on artwork)
2. figure/artwork@name
3. figure/artwork@type, figure/artwork@src, figure/artwork@align, figure/artwork@alt.
4. figure/artwork

.With Figure Wrapper

begin() {
  source code listing <7>
}

1. figure@anchor
2. figure/artwork@align, figure/artwork@alt, figure@suppress-title (attributes only available in v2)
3. figure/name
4. figure/preamble
5. figure/artwork@name
6. figure/artwork@type, figure/artwork@src, figure/artwork@align, figure/artwork@alt.
7. figure/artwork
8. figure/postamble

ASCII Art and Images

In RFC XML, artwork elements only occur within a figure wrapper; Metanorma-IETF supplies that wrapper if it is not provided explicitly.

.Ascii-Art Without Figure Wrapper

------------------------
|        ASCII Art     |
------------------------ <4>

1. figure@anchor (moved into supplied wrapper: anchors not supported on artwork)
2. figure/artwork@name
3. figure/artwork@align, figure/artwork@alt; figure@type
4. figure/artwork

.Image Without Figure Wrapper

1. figure@anchor (moved into supplied wrapper: anchors not supported on artwork)
2. figure/artwork@name
3. figure/artwork@align, figure/artwork@alt; figure/artwork@type (intended to be a MIME type)
4. figure/artwork@src, figure/artwork@alt, figure/artwork@width, figure/artwork@height

.With Figure Wrapper

Figures are
      only permitted to contain listings (sourcecode),
           images (artwork),
or literal (artwork) <6>

1. figure@anchor
2. figure/artwork@align, figure/artwork@alt, figure@suppress-title
3. figure/name
4. figure/preamble
5. figure/artwork@align, figure/artwork@alt; figure@type (attribute only available in v2)
6. figure/artwork
7. figure/artwork@name
8. figure/artwork@align, figure/artwork@alt; figure/artwork@type (intended to be a MIME type)
9. figure/artwork@src, figure/artwork@alt, figure/artwork@width, figure/artwork@height
10. figure/postamble

Mathematical examples

In order for mathematical formatting to be recognised in Asciidoc, the document attribute :stem: needs to be set.

:stem:
[stem]
++++
sqrt(4) = 2
++++

Mathematical examples are treated identically to literals, and are rendered as artwork; however their default alignment is set as center. As with inline stem expressions, they are treated identically to monospace expressions in the RFC XML output; they are not currently rendered as MathML or any other notation.

Lists

[empty=true,hang-indent=n] <1>
* Unordered list 1 <2>
* Unordered list 2 <2>
** Nested list <3>
[counter=token,hang-indent=n,format=List #%d,arabic|loweralpha|upperralpha|lowerroman|upperroman] <4>
. A <5>
. B <5>

Unlike Metanorma AsciiDoc, v2 RFC AsciiDoc does not permit anchors on list items: the anchors in the following are ignored.

* [[id1]] A
. [[id2]] A

RFC XML v2 does not support multi-paragraph list items. Following the specification recommendation, paragraphs within v2 list items are replaced with vspace tags.

Definition Lists

[hang-indent=n] <1>
A:: B <2>

In RFC XML v2, idnits considers inline definition lists invalid; Metanorma renders them as paragraphed definition lists. The gem option :inline-definition-lists disables this behaviour.

Metanorma AsciiDoc does not permit anchors on either definition list terms, or definition list definitions: the anchors in the following are ignored.

[[id1]] A:: [[id2]]B

RFC XML v2 does not support multi-paragraph list items. Following the specification recommendation, paragraphs within v2 list items are replaced with vspace tags.

Tables

The converter respects the AsciiDoc (horizontal) align attributes of cells and column widths.

(Exceptionally, column widths specified for v2 as ”1,1,1,1,1,1....“ will be ignored, since AsciiDoc internally treats them identically to unspecified column widths on a table.)

[[id]] <1>
[suppress-title=true|false,align=left|center|right,grid=all|cols|none|rows] <2>
.Table Title <3>
|===
|[[id]] head | head <4>
h|header cell | body cell <5>
| | body cell <5>
|foot | foot <5>
|===

Paragraphs

[[id]] <1>
Paragraph text <2>

Comments

// This is an inline AsciiDoc comment, which will not be output to XML.
[comment]
This is a single paragraph AsciiDoc comment,
which will not be output to XML.
////
This is a block AsciiDoc comment,
which will not be output to XML.
////
[comment]
--
This is a
multiple paragraph
AsciiDoc comment, which will not be output to XML.
--

Text [comment]#This is a comment# Text

<t>Text <!-- This is a comment --> Text</t>

[.comment]
This is a single paragraph XML comment.
[.comment]
--
This is a
multiple paragraph
XML comment.
--

NOTE: Any admonition inside the body of the text is a comment. <1>
// Note that actual AsciiDoc comments are ignored by the converter.
[[id]] <2>
[NOTE,source=name] <3>
====
Any admonition inside the body of the text is a comment.
====

Inline markup

Indexing

This ((<indexterm>)) <1>
is visible in the text,
this one is not (((indexterm, index-subterm))). <2>

Inline formatting

Linebreak: + <1>
_Italic_ <2>
*Bold* <3>
`Monospace` <4>
~subscript~ <5>
^superscript^ <6>
[bcp14]#MUST NOT# <7>
stem:[sqrt(4) = 2] <8>

Any formatting XML spans within spanx elements are stripped in postprocessing.

Cross-References

Content content content
<<crossreference>> <1>
<<crossreference,text>> <2>
<<crossreference,format=(counter|title|none|default): text>> <3>
http://example.com/[linktext] <4>

In v2, relref style cross-references to bibliographic entries are rendered as equivalent xref cross-references, inserting section numbers as appropriate.

Note that fragments (e.g. crossreference#fragment) are not supported on the xref@target attribute: the RFC XML specification requires that the xref@target attribute equals the value of an anchor attribute elsewhere in the document.

Internal cross-references and bibliographic references are marked up in the same way; but bibliographic references are marked up separately from the main flow of Metanorma IETF AsciiDoc, and are processed later.

The WHIRLPOOL hash function is defined in WHIRLPOOL.

This section should actually be referenced as hash_whirlpool. ...