Metanorma AsciiDoc markup (AsciiRFC v3)

Abstract

Any paragraphs following the document header are treated as the abstract (front/abstract), whether they are notated as an AsciiDoc preamble or as an AsciiDoc abstract; if both are present, the abstract takes priority. The abstract is terminated by either the first section header (which ends the document preamble), or a note.

Any notes immediately following the abstract are treated as RFC notes (front/note).

[[abstract-id]] <1>
Abstract text without an explicit title and abstract style. <2>

[[abstract-id]] <1>
[abstract]
== Abstract
This is an abstract <2>
NOTE: This is a note <3>
[NOTE,remove-in-rfc=true] <4>
.Note 2 Title <5>
===
This is another note <3>
===

Sections and Subsections

[[id]] <1>
[removeInRFC=true,toc=include|exclude|default,numbered=true] <2>
== Section title <3>
First paragraph of section <4>
Second paragraph of section <4>
=== Subsection title <5>
First paragraph of subsection <6>
==== Subsubsection title <7>
Content content content <8>

Appendices

[[id]] <1>
[appendix,removeInRFC=true,toc=include|exclude|default,numbered=true] <2>
== Appendix 1 <3>
Content <4>

Examples

RFC XML does not recognize examples as a distinct element. The example label and example contents are rendered without a containing element; the example label appears on a paragraph of its own.

The example label (if any) is prefixed with the standard Metanorma prefix, “EXAMPLE: ”, or “EXAMPLE nnn: ” if there are more than one examples in the clause.

Figures

Figures are rendered as RFC XML figure, and are treated as wrappers for ASCII art, source code and images. Any text in an example block that precedes or follows sourcecode, an image, or preformatted text is moved outside the figure.

Requirements, Recommendations, Permissions

RFC XML does not recognize recommendations as a distinct element. The recommendation label and example contents are rendered without a containing element; the recommendation label appears on a paragraph of its own. Recommendation components that are not meant to be human readable (those set to exclude attribute) are left out of RFC XML.

Source code listings

In RFC XML v2, sourcecode elements only occur within a figure wrapper. This is not the case for RFC XML v3, and Metanorma-IETF no longer supplies that wrapper if it is not provided explicitly [added in https://github.com/metanorma/metanorma-ietf/releases/tag/v2.3.0].

Any label supplied for sourcecode will be dropped, since sourcecode in RFC XML has no caption.

Metanorma pseudocode is marked up in RFC as sourcecode; any formatting is removed from the pseudocode body.

.Without Figure Wrapper

begin() {
  source code listing <4>
}

1. sourcecode/@anchor
2. Ignored
3. sourcecode/@type, sourcecode/@src, sourcecode/@markers, sourcecode/@name. If src is present, the listing is not expected to have any content: content is taken from the hyperlink in the attribute.
4. sourcecode

.With Figure Wrapper

begin() {
  source code listing <6>
}

1. t/@anchor
2. t
3. sourcecode/@anchor
4. sourcecode/@name
5. sourcecode/@type, sourcecode/@src, sourcecode/@markers, sourcecode/@name. If src is present, the listing is not expected to have any content: content is taken from the hyperlink in the attribute.
6. sourcecode

ASCII Art and Images

All ASCII art is assigned the type ascii-art. Only SVG images are supported in xml2rfc; metanorma will issue a warning for any other image type.

Metanorma supports inline images; RFC XML does not. Any instances of inline images in a paragraph are replaced by a placeholder counter (“[IMAGE nnn]”); the images are moved after the paragraph.

.ASCII-Art Without Figure Wrapper

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

1. figure/artwork/@anchor
2. figure/name
3. figure/artwork/@align, figure/artwork/@alt
4. figure/artwork

.Image Without Figure Wrapper

1. figure/artwork/@anchor
2. figure/name
3. figure/artwork/@align, figure/artwork/@alt
4. figure/artwork/@src, figure/artwork/@alt

.With Figure Wrapper

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

1. figure/@anchor
2. figure/name
3. figure/artwork/@anchor
4. figure/artwork/@align, figure/artwork/@alt
5. figure/artwork
6. figure/artwork/@name
7. figure/artwork/@align, figure/artwork/@alt (type populated as either svg or binary-art depending on file suffix)
8. figure/artwork/@src, figure/artwork/@alt

Formulae

Formulae are rendered consistent with the rest of Metanorma, as paragraphs of mathematical expressions followed by a counter in parentheses; the counter is separated from the expression by four spaces.

Mathematical expressions

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

Unlike previous versions of this gem, mathematical expressions, whether in formulae or inline, are rendered as AsciiMath delimited by $$</code>; if a sequence of <code>$ already occurs in the text, that delimiter has more $ added to it until it is unique.

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

Lists

[[id]] <1>
[nobullet=true,spacing=normal|compact,indent=5,bare=true] <2>
* Unordered list 1 <3>
* Unordered list 2 <3>
** Nested list <4>
[[id]] <5>
[spacing=compact,start=n,group=n,format=List #%d,arabic|loweralpha|upperralpha|lowerroman|upperroman,indent=5] <6>
. A <7>
. B <7>

Definition Lists

[[id]] <1>
[newline=true,spacing=compact,indent=5] <2>
A:: B <3>

Metanorma-IETF permits anchors on definition list terms and definition list definitions, whereas other flavours treat them as bookmarks (which are otherwise ignored in Metanorma-IETF):

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

Metanorma-IETF automatically inserts a colon after the definition term, if one is not already provided [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v3.5.3]

Note

[[id]] <1>
NOTE
====
Sidebar <2>
====
[[id]] <1>
NOTE: Sidebar <2>

Notes are prefixed with the standard Metanorma prefix, “NOTE: ”.

Exceptionally, notes after abstracts are encoded in RFC XML v3 as note (abstract).

Admonitions

Admonitions are rendered like notes as RFC XML aside, with the admonition label and title as an initial paragraph:

[[id]] <1>
[CAUTION] <2>
.Here be dragons </2>
====
Sidebar <3>
====
[[id]] <1>
NOTE: Sidebar <2>

Tables

The converter respects the colspan and rowspan attributes of cells, as set in AsciiDoc (3|, .3|).

[[id]] <1>
.Table Title <2>
|===
|[[id]] head | head <3>
h|header cell | body cell <4>
| | [[id]] body cell <5>
|foot | foot <6>
|===

Paragraphs

[[id]] <1>
[keep-with-next=true,keep-with-previous=true,indent=5] <2>
Paragraph text <3>

Quotes

[[id]] <1>
[quote, attribution, citation info] <2>
Quotation <3>

Comments

Unlike previous versions of this gem working with RFC XML v3, this version of the gem does not currently provide a means of populating XML comments in RFC XML.

[[id]] <1>
[reviewer="Nick Nicholas",display=true] <2>
.Note Title <3>
****
Profile?!
****

This is a paragraph containing{blank}cref:[id] an editorial comment.
[[id]] <1>
[reviewer="Nick Nicholas",display=true] <2>
.Note Title <3>
****
Profile?!
****

Inline markup

Indexing

This ((indexterm)) <1>
is visible in the text,
this one is not (((indexterm, index-subterm))). <2>
This is a ((primary:primary index term)) <3>
and so is (((primary:indexterm, index-subterm))) <4>

Inline formatting

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

*WOULD
PROBABLY*

Cross-references

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

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.

If cross-reference text is not supplied, it is populated with the Metanorma default, naming and numbering the referenced object.

Citations

<<crossreference>> <1>
<<crossreference,(of|comma|parens|bare),section=4.3>> <2>
<<crossreference,(of|comma|parens|bare),section-4.3: text>> <3>
<<crossreference#fragment,section_number (of|comma|parens|bare)>> <4>
<<crossreference#fragment,section_number (of|comma|parens|bare): text>> <5>

Localities other than clause and section are ignored in the generated RFC XML v3.

Metanorma has switched to xref in its RFC XML output from the deprecated relref [added in https://github.com/metanorma/metanorma-ietf/releases/tag/v3.3.1].

Footnotes

Footnotes in text are rendered as a separate “Endnotes” appendix, with each endnote rendered as a paragraph prefixed by an incrementing numeric counter in brackets. The footnote reference in the main text is replaced by the same counter in brackets.

Footnotes in tables and figures, similar to the rest of Metanorma, are rendered as aside elements, with an incrementing alphabetic counter in brackets.