Metanorma: Aequitate Verum

Metanorma for IETF

Metanorma AsciiDoc markup (AsciiRFC v3)

This document documents the version of Metanorma AsciiDoc aligned with RFC XML v3 [added in https://github.com/metanorma/metanorma-ietf/releases/tag/v2.0.0]. This version of AsciiDoc is much closer aligned to the rest of Metanorma than the version used in previous versions; this has the added benefit that the same AsciiDoc source can be used to generate output for both IETF and other standards bodies, which was not previously possible.

The version of AsciiDoc that supported RFC XML v2 in previous versions is documented separately. A comparison of the two markups is also provided, and can be used to convert documents marked up for RFC XML v2 to documents for RFC XML v3.

Sections

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)

  1. front/abstract/@anchor

  2. front/abstract

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

  1. front/abstract/@anchor

  2. front/abstract

  3. front/note

  4. front/note/@removeInRFC

  5. front/note/name

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)

  1. middle/section/@anchor

  2. middle/section/@removeInRFC, middle/section/@toc, middle/section/@numbered

  3. middle/section/name

  4. middle/section/t

  5. middle/section/section/name

  6. middle/section/section/t

  7. middle/section/section/section/name

  8. middle/section/section/section/t

Appendices

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

  1. back/section/@anchor

  2. back/section/@removeInRFC, back/section/@toc, back/section/@numbered

  3. back/section/name

  4. back/section/t

Blocks

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
[[id]] (1)
.Source code listing title (2)
[source,type,src=uri,markers=true,filename=a.rb] (3)
----
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
[[id]] (1)
.Figure 1 (2)
====
[[id1]] (3)
.Source code listing title (4)
[source,type,src=uri,markers=true] (5)
----
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
[[id]] (1)
.Figure2.jpg (2)
[align=left|center|right,alt=ASCII Art] (3)
....
------------------------
|        ASCII Art     |
------------------------ (4)
....

  1. figure/artwork/@anchor

  2. figure/name

  3. figure/artwork/@align, figure/artwork/@alt

  4. figure/artwork

Image Without Figure Wrapper
[[id]] (1)
.Figure2.jpg (2)
[align=left|center|right,alt=alt_text] (3)
image::filename.jpg[alt_text] (4)

  1. figure/artwork/@anchor

  2. figure/name

  3. figure/artwork/@align, figure/artwork/@alt

  4. figure/artwork/@src, figure/artwork/@alt

With Figure Wrapper
[[id]] (1)
.Figure 1 (2)
====

[[subid1]] (3)
[align=left|center|right,alt=alt_text,type=text/plain] (4)
....
Figures are
      only permitted to contain listings (sourcecode),
           images (artwork),
or literal (artwork) (5)
....

[[subid2]] (3)
.Figure3.jpg (6)
[align=left|center|right,alt=alt_text] (7)
image::filename.jpg[alt_text] (8)

====

  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 $$; if a sequence of $ 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)

  1. ul/@anchor

  2. ul/@empty, ul/@spacing, [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.4.2] ul/@indent, ul/@bare

  3. ul/li/t

  4. ul/li/t/ul/li/t

  5. ol/@anchor

  6. ol/@spacing, ol/@start, ol/@group, ol/@type = "#%d", `ol/@type (for arabic|loweralpha|upperralpha|lowerroman|upperroman), [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.4.2] ol/@indent

  7. ol/li/t

Definition Lists

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

  1. dl/@anchor

  2. dl/@newline, dl/@spacing, dl/@indent

  3. dl/dt, dl/dd/t

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

Note

[[id]] (1)
NOTE
====
Sidebar (2)
====

[[id]] (1)
NOTE: Sidebar (2)

  1. aside/@anchor

  2. <aside>Sidebar</aside>

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)

  1. aside/@anchor

  2. `aside/t

  3. <aside>Sidebar</aside>

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

  1. table/@anchor

  2. table/name

  3. table/thead/tr/td

  4. table/tbody/tr/th, table/tbody/tr/td

  5. table/tbody/tr/td/@anchor

  6. table/tfoot/tr/td

Note
 RFC XML v3 permits table cells to contain block elements, such as paragraphs and lists. This is done in AsciiDoc by prefixing the table cell with a|.

Paragraphs

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

  1. t/@anchor

  2. t/@keepWithNext, t/@keepWithPrevious, [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.4.2] t/@indent

  3. <t>Paragraph text</t>

Quotes

[[id]] (1)
[quote, attribution, citation info] (2)
Quotation (3)

  1. blockquote/@anchor

  2. blockquote/@quotedFrom, blockquote/@cite. In RFC XML v3, citation info is limited to a URL, and is not otherwise populated.

  3. <blockquote>Quotation</blockquote>

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.

Editorial Notes

RFC XML provides for editorial comments as blocks, which may optionally appear in the published text (subject to either the cref/@display attribute, or the comments processing instruction).

As with the rest of Metanorma, such editorial comments will only be included in the Metanorma XML output, let alone the RFC XML output, if the AsciiDoc :draft: document attribute is present.

Note
 Unlike in RFC XML v2, editorial notes are marked up as AsciiDoc sidebars. 
[[id]] (1)
[reviewer="Nick Nicholas",display=true] (2)
.Note Title (3)
****
Profile?!
****

  1. cref/@anchor

  2. cref/@source, cref/@display

  3. cref/name

Inline comments

To generate an editorial comment inline in RFC XML, notate an editorial comment as a block, and then indicate the insertion point for the editorial comment inline with the command cref:[id] [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.4.2], where id is the identifier of the editorial comment.

Example 1. Example of inserting inline comments
This is a paragraph containing{blank}cref:[id] an editorial comment.

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

  1. cref/@anchor

  2. cref/@source, cref/@display

  3. cref/name

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)

  1. <iref item="indexterm">indexterm</iref>

  2. <iref item="indexterm" subitem="index-subterm"/>

  3. primary index term<iref item="indexterm" primary="true"/> [added in https://github.com/metanorma/metanorma-ietf/releases/tag/v2.2.9]

  4. <iref item="indexterm" subitem="index-subterm"/> [added in https://github.com/metanorma/metanorma-ietf/releases/tag/v2.2.9]

Inline formatting

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

  1. Ignored, as documented in Levkowetz' implementation notes

  2. <em>Italic</em>

  3. <strong>Bold</strong>

  4. <tt>Monospace</tt>

  5. <sub>subscript</sub>

  6. <sup>superscript</sup>

  7. <bcp14>MUST NOT</bcp14>

  8. if document flag :no-rfc-bold-bcp14: is present, then <strong>MUST NOT</strong>, else (by default) any BCP 14 / RFC 2119 phrase in boldface and capitals is assumed to be intended to be tagged in <bcp14>.

Note

The delimiters must occur within the one line; the following is invalid in Metanorma AsciiDoc.

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

  1. <xref target="crossreference"/>

  2. <xref target="crossreference">text</xref>

  3. <xref format="counter|title|none|default" target="crossreference">text</xref>

  4. <eref href="http://example.com/"/>

  5. <eref href="http://example.com/">linktext</eref>

  6. <eref href="http://example.com/" brackets="angle"/> [added in https://github.com/metanorma/metanorma-ietf/releases/tag/v3.3.1]

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)

  1. <xref target="crossreference"/>

  2. <xref sectionFormat="of|comma|parens|bare" section="section_number" target="crossreference"/>

  3. <xref sectionFormat="of|comma|parens|bare" section="section_number" target="crossreference">text</relref>

  4. <xref relative="fragment" sectionFormat="of|comma|parens|bare" section="section_number" target="crossreference"/>

  5. <xref relative="fragment" sectionFormat="of|comma|parens|bare" section="section_number" target="crossreference">text</relref>

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.