Writing Internet-Drafts And RFCs In AsciiDoc (AsciiRFC)RiboseSuite 1111, 1 Pedder StreetCentralHong KongHong Kongronald.tse@ribose.comhttps://www.ribose.comRiboseAustralianick.nicholas@ribose.comhttps://www.ribose.comRiboseSuite 1111, 1 Pedder StreetCentralHong KongHong Kongjeffrey.lau@ribose.comhttps://www.ribose.comRiboseItalypaolo.brasolin@ribose.comhttps://www.ribose.com
Internet
Network Working GroupThis document describes the AsciiDoc syntax extension called AsciiRFC
designed for authoring IETF Internet-Drafts and RFCs.AsciiDoc is a human readable document markup language which affords more
granular control over markup than comparable schemes such as Markdown.The AsciiRFC syntax is designed to allow the author to entirely focus
on text, providing the full power of the resulting XML RFC through the AsciiDoc
language, while abstracting away the need to manually edit XML, including
references.This document itself was written and generated into XML RFC v2 (RFC7749) and
XML RFC v3 (RFC7991) directly through asciidoctor-rfc, an AsciiRFC generator.As specified in , the IETF intends for the canonical format of RFCs
to transition from plain-text ASCII to RFC XML v3 . While plain-text
will continue to be accepted from authors by the IETF, at least in the short-
to medium-term, XML will be preferred for submission, and any plain-text
submissions will need to be converted to RFC XML v3.The transition to RFC XML v3 places added onus on authors to generate compliant
XML. This need is already met for RFC XML v2 by tools such as
MMark and
Kramdown, both based on the popular
Markdown markup language.Asciidoctor is an alternative markup language to
Markdown, with features that make it attractive as a markup language for RFC
with XML output.Compared to Markdown,Asciidoctor was designed from the beginning as a publishing language: it was
initially intended as a plain-text alternative to the DocBook XML schema. For
that reason, Asciidoctor natively supports the full range of formatting
required by RFC XML (including notes, tables, bibliographies, source-code
blocks, and definition lists), without resorting to embedded HTML or Markdown
"flavours".Asciidoctor is extensible, with a well-defined API.Asciidoctor allows granular control of rendering, including user-specified
attribute of text blocks.Asciidoctor allows document inclusion, for managing large-scale documentation
projects.Asciidoctor allows granular control of permutations of block nesting, such as
source code within lists or definition lists within unordered lists.As a more formal counterpart to Markdown, Asciidoctor is well-suited to
generating XML that needs to conform to a specified schema.Section 1.2 of famously states that "there is no such thing as "invalid"
Markdown, there is no standard demanding adherence to the Markdown syntax, and
there is no governing body that guides or impedes its development." While there
are contexts where that lack of rigour is helpful, the authoring of RFCs does
have a standard and a governing body, and there is such a thing as invalid RFC
XML. A more rigorous counterpart to Markdown, which still preserves its basic
approach to formatting, is useful in generating RFC XML that encompasses a
fuller subset of the specification, and preempting malformed RFC XML output.As with Markdown, there is a wide range of tools that can render Asciidoctor;
so Asciidoctor drafts of RFC documents can be previewed and accessed without
depending on the RFC tools ecosystem. Our porting of RFC XML to Asciidoctor has
aimed to ensure that, as much as possible, the Asciidoctor being used for RFC
is generic Asciidoctor, which can be processed by Asciidoctor tools in general.
(The only exception to this as an add-on is the optional bibliography module,
which allows bibliographies to be assembled on the fly based on citations in a
document.)The key words "MUST", "MUST NOT", "REQUIRED", "SHALL",
"SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED",
"MAY", and "OPTIONAL" in this document are to be interpreted
as described in .TODO.The syntax of Asciidoctor is presented in the
Asciidoctor user manual.Asciidoctor consists of:A document header, containing a title, a list of authors, and document
attributes in lines prefixed with ":"An optional document preamble, separated from document header by a blank lineA number of sections, set off by a section title (a line prefixed with two or
more "=". A section may contain:Other sections, whose level of nesting is indicated by the number of "=" in
their headerBlocks of text. Blocks can have metadata (including a title, an anchor for
cross-references, and attributes.) Blocks can be:Paragraphs, which are terminated by blank lines.Lists. List items are by default paragraphs, but can span over multiple
paragraphs.Delimited blocks (with a line delimiter on either side of them); these
include tables, notes, sidebars, source code, block quotes, examples, and
unprocessed content (e.g. raw XML). Delimited blocks contain by default one or
more paragraphs.List items can contain other blocks, including both nested lists and
delimited blocks.Some delimited blocks can contain other delimited blocks; for example,
examples can contain source code as well as discussion in paragraphs.Blocks of text consist of inline text, which themselves can contain markup.Inline markup includes:Text formatting: bold, italic, superscript, subscript, monospaceCustom markup macrosURLs, including display textInline anchorsCross-references to anchors (IDs of blocks or spans of text), including
display textImages, audio, and visual filesIndex termsEquations (native support for
AsciiMathML and
TeX/LaTeX, via the
MathJax toolFootnotesThe Asciidoctor document structure aligns with the RFC XML v2 and v3 structure.
In the following, v3 equivalences are given:Header: <rfc> attributes, most front elementsPreamble: front/abstract and front/noteSections: middle/section elementsSections with bibliography style attributes: back/references elements.Sections with appendix style attributes: back/section elements.Paragraphs: t elementsLists: ul, ol, dl elementsDelimited blocks: artwork, aside, blockquote, figure, note,
sourcecode, tableInline markup: bcp14, br, cref, em, eref, iref, relref,
strong, sub, sup, tt, xrefFull details of the mapping of Asciidoctor elements to RFC XML v2 and v3
elements, and of how to convert Asciidoctor documents to RFC XML, are given in
. The
following gives an overview of how to create an RFC XML document in
Asciidoctor, with some pitfalls to be aware of. Illustrations are in RFC XML
v3, although the converter deals with both versions of RFC XML.The header gives the document title, followed by an optional author
attribution, and a series of document attributes, with no carriage return
breaks.For example:The document attributes are used to populate rfc attributes, front
elements, and document-level processing instructions.:doctype: determines whether the document will be considered rfc or
internet-draft, and interprets other attributes accordingly.Certain attributes (workgroup, area, keyword) are comma delimited, and result in repeated RFC XML elements.A few attributes are specific to the operation of the RFC XML document converter::no-rfc-bold-bcp14: false overrides the conversion of boldface uppercase
BCP14 words with the bcp14 element.:smart-quotes false: overrides Asciidoctor’s conversion of straight quotes and apostrophes to smart quotes and apostrophes.:inline-definition-lists: true overrides the RFC XML v2 idnits requirement that a blank line be inserted between a definition list term and its definition.The foregoing Asciidoc renders into RFC XML v3 as:Details of a second, third etc. author, including their organization and
contact details, are provided by suffixing the author attribute with _2, _3
etc.:The initial author attribution in Asciidoctor, e.g. John Doe Horton<john.doe@email.com>; Billy Bob Thornton <billy.thornton@email.com>
in the example above, expects a strict format of First Name, zero or
more Middle Names, Last name, and cannot process honorifics like "Dr"
or suffixes like "Jr". Name attributes with any degree of complexity
should be overriden by using the :fullname: and :lastname:
attributes. The :forename_initials: replaces the built-in
:initials: attribute (which includes the surname initial), and is not
automatically populated from the name attribution.The preamble in Asciidoctor is the text between the end of the document header
(which terminates with a blank line) and the first section of text. Any
paragraphs of text in the preamble are treated as an abstract, and may
optionally be tagged with the abstract style attribute. Any notes in the
preamble are treated as a note element. For example:Section headers are given with a sequence of =, the number of = giving the
header level. Section numbering is toggled with the in-document attribute
:sectnums: (on), :sectnums!: (off)AsciiDoc Examples (corresponding to RFC XML figures), source code listings, and
literals (preformatted text) are all delimited blocks. Listings and literals
can occur nested within examples. If an Asciidoctor listing or literal occurs
outside of an example, the RFC XML converter will supply the surrounding figure
element:Asciidoctor supports ordered, unordered, and definition lists. Indentation of
ordered and unordered lists is indicated by repeating the list item prefix (*
and . respectively.) List attributes specify the type of symbol used for
ordered lists:A list item by default spans a single paragraph. A following paragraph or other block element can be appended to the current list item by prefixing it with + in a separate line (Asciidoc list continuation.)Multiple paragraphs are not permitted within a list item in RFC XML v2. The RFC XML converter deals with this by converting paragraph breaks into line breaks within a list item.List continuations can also be embed to populate a list item with a sequence of blocks as a unit (in an Asciidoc open block):Asciidoctor considers paragraphs to be the basic level of blocks, and does not permit lists to be nested within them: text after a list is considered to be a new paragraph. So markup like the following cannot be generated via Asciidoctor:Asciidoctor supports blockquotes and quotations of verse; its block quotations
permit arbitrary levels of quote nesting. RFC XML v3 only supports one level of
blockquotes. RFC XML v3 does not support line breaks outside of tables, so
verse quotations are converted to prose.Asciidoctor supports a range of "admonitions", including notes, warnings, and
tips. They are indicated by a paragraph prefix (e.g. WARNING:), or as a block
with an admonition style attribute. All admonitions are converted to note elements in the document preamble, and cref documents in the main document.
RFC XML v3 also supports asides (Asciidoctor sidebars):Note that no inline formatting is permitted in RFC XML v2, and it is stripped
for v2 by the converter.Because paragraphs in Asciidoctor cannot contain any other blocks, a comment at
the end of a paragraph is treated as a new block. In the document converter,
any such comments are moved inside the preceding RFC XML paragraph; if the
comment is at the start of a section, as in the example above, it is wrapped
inside a paragraph.While Asciidoctor has comments proper, notated with initial //, they are
ignore by the document converter, so they will not appear as XML comments in
the converter output.Asciidoctor tables, like RFC XML v3, support distinct table heads, bodies and
feet, cells spanning multiple rows and columns, and horizontal alignment. The
larger range of formatting options available in RFC XML v2 is also supported.Neither version of RFC XML is as expressive in its table structure as
Asciidoctor; RFC XML for example does not permit blocks within table
cells.Like RFC XML v3, Asciidoctor supports italics, boldface, monospace, subscripts
and superscripts:RFC XML v3 also supports tagging of BCP14 keywords ; this is done in
Asciidoctor either by tagging them with a custom formatting span (bcp14#mustnot#), or by converting by default BCP14 boldface all-caps words:Any spans of BCP14 text delimited by inline formatting delimiters needs to be
contained within a single line of text; the Asciidoctor API breaks up
formatting spans across line breaks.Formatting delimiters like * can be escaped with backslash; double formatting
delimiters, like <spanx style="strong"> and __, need to be escaped with double backslash(\\</spanx>). Escaping delimiters is not always reliable, and for double delimiters
it is preferable to use HTML entities (**), or attribute references:Common URL formats are recognised automatically as hyperlinks, and are rendered
as such; any hyperlinked text is appended after the hyperlink in square
brackets:To prevent hyperlinking of a URL, prefix it with a backslash.Anchors for crossreferences are notated as [[…]] or [#…]. Anchors can
be inserted on their own line in front of most blocks. Asciidoctor supports
anchors in a much wider range of contexts than is supported than RFC XML v3
(let alone v2); anchors that are not supported for that version of RFC XML are
simply ignored by the converter. Note that anchors in RFC XML are constrained
to the format [A-Za-z_:][[A-Za-z0-9_:.-]*.Cross-references to anchors are notated as <…>; cross-references
with custom text as <reference,text>. Asciidoctor does not
otherwise support attributes on cross-references, but the converter extracts
format information from templated text within cross-references: format=x:text populates the xref@format attribute, while a section number followed by
one of the words of, parens, bare, text is treated as a relref reference to
an external document.The Asciidoctor "include" directive
is used to include external files in a master Asciidoctor document. The
directive is capable of sophisticated document merging, including adjusting the
heading levels of the included text, selecting text within specified tags or
line numbers to be included, and adjusting the indentation of code snippets in
merged text:XML accepted the full range of characters in the world’s languages through
UTF-8 character encoding, and one of the motivations for the move from plain
text to RFC XML has been to allow non-ASCII characters to be included in RFCs.
However, current RFC XML v2 tools still do not support UTF-8, and other tool
support for UTF-8 also remains patchy. Out of an abundance of caution, the RFC
XML converter uses US-ASCII for its character encoding, and renders any
non-ASCII characters as entities.The converter accepts HTML entities in Asciidoctor, even though they are not
part of the XML specification; HTML entities such as feature in
examples of RFC XML provided by the IETF. In order to prevent dependence of the
XML output from extraneous entity definitions, any such entities are rendered
in the XML as decimal character entities.Asciidoctor has a simple encoding of bibliographies, but it is not adequate for
the complexity of bibliographic markup supported in RFC XML. RFC documents
overwhelmingly cite other RFC documents, and canonical RFC XML bibliographic
entries are available at ; so it
would be inefficient to encode those entries in Asciidoctor, only to have them
converted back to RFC XML.The converter provides two means of incorporating bibliographies into RFC
documents authored in Asciidoctor:using raw RFC XML; andassembling bibliographies in preprocessing.In either case, the RFC XML needs to be well-formed; missing closing tags can
lead to erratic behaviour in the converter.In the first, bibliographic citations are handled like all other
cross-references. The bibliographic entries for normative and informative
references are given in the Asciidoctor as passthrough blocks, which contain
the raw RFC XML for all references; document conversion leaves the raw RFC XML
in place. This approach requires authors to maintain the normative and
informative bibliographies within the document, to update them as citations are
added and removed, and to sort them manually.The alternative method is to use a preprocessing tool,
asciidoc-bibliography,
to import citations into the Asciidoctor document from an external file of
references.The references file consists of RFC XML reference entries, and still needs to
be managed manually; however the bibliographies are assembled from that file,
sorted, and inserted into the normative and informative references in
preprocessing. Citations in the document itself are given as macros to be
interpreted by the preprocessor; this allows them to be split into normative
and informative references. (The MMark tool likewise splits reference citations
into normative and informative.)Integration with the asciidoc-bibliography gem proceeds as follows:Create an RFC XML references file, consisting of a <references> element
with individual <reference> elements inserted, as would be done for the
informative and normative references normally. The references file will contain
all possible references to be used in the file; the bibliography gem will
select which references have actually been cited in the document.Rather than hand crafting RFC XML references for RFC documents, you should
download them from an authoritative source; e.g.
Unlike the case for RFC XML documents created manually, the references file
does not recognise XML entities and will not attempt to download them during
processing. Any references to will
need to be downloaded and inserted into the references file.The RFC XML in the references file will need to be appropriate to the
version of RFC XML used in the main document, as usual. Note that RFC XML v2
references are forward compatible with v3; v3 contains a couple of additional
elements.Add to the main document header attributes referencing the references file
(:bibliography-database:), and the bibliography style (:bibliography-style:rfc-v3).References to a normative reference are inserted with the macro
cite:norm[id] instead of <id>, where id is the anchor of the
reference.References to an infomrative reference are inserted with the macro
cite:info[id] instead of <id>, where id is the anchor of the
reference.Normative and Informative References are inserted in the document through a
macro, which occurs where the RFC XML references would be inserted:The following features of RFC XML are not supported by the Asciidoctor
converter, and would need to be adjusted manually:RFC XML elementRFC XML v3RFC XML v2front/boilerplateNot added by the converterN/Airef@primaryNNreference (and all children)As Raw XMLAs Raw XMLtable/preambleDeprecatedNtable/postambleDeprecatedNartwork@widthOnly on imagesOnly on imagesartwork@heightOnly on imagesOnly on imagesTo author an Asciidoctor RFC document, you should familiarise yourself with the
Asciidoctor specification. The
converter Ruby gem source code distribution also has
samples of individual RFC XML features, in v2 and v3, and
examples of self-standing Asciidoctor RFC XML documents,
along with their RFC XML renderings. (This includes round-tripped RFC XML
documents.)In addition, you can clone the sample rfc-in-asciidoc-template repository as
a template, and populate it for your AsciiDoc RFCs and Internet-Drafts:Converting your AsciiDoc to RFC XML is a simple as installing asciidoctor (see
) and the asciidoctor-rfc gem in Ruby, then
running the asciidoctor executable on the document, specifying the
asciidoctor-rfc gem as a library:As you author Asciidoctor content, you should iterate through running the
Asciidoctor conversion frequently, to ensure that you are still generating
valid XML through your markup. The converter makes an effort to ensure that its
XML output is valid, and it issues warnings about likely issues; it also
validates its own XML output against the Asciidoctor schema, and reports errors
in the XML output in the following format:Note that validation against the RELAXNG RFC XML schema includes confirming the
referential integrity of all cross-references in the document.It may be necessary to intervene in the XML output generated by the converter,
either because the block model of Asciidoctor does not conform with the
intended RFC XML (e.g. lists embedded in paragraphs), or because RFC XML
features are required that are not supported within Asciidoctor.Ensure your AsciiRFC generator comes from a geniune and trustworthy source.
This protects your own machine and also prevents injection of malicious content
in your document.An AsciiRFC generator may cause errors in textual rendering or link generation
that may lead to security issues.Creating cross-references (and also bibliographic references) to external
documents may pose risks since the external document’s location may become
controlled by a malicious party.This document does not require any action by IANA.TODO.Key words for use in RFCs to Indicate Requirement LevelsIn many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements.The "xml2rfc" Version 2 VocabularyThis document defines the "xml2rfc" version 2 vocabulary: an XML-based language used for writing RFCs and Internet-Drafts.Version 2 represents the state of the vocabulary (as implemented by several tools and as used by the RFC Editor) around 2014.This document obsoletes RFC 2629.The "xml2rfc" Version 3 VocabularyThis document defines the "xml2rfc" version 3 vocabulary: an XML-based language used for writing RFCs and Internet-Drafts. It is heavily derived from the version 2 vocabulary that is also under discussion. This document obsoletes the v2 grammar described in RFC 7749.Version 2.0 Microsoft Word Template for Creating Internet Drafts and RFCsThis document describes the properties and use of a revised Microsoft Word template (.dot) for writing Internet Drafts and RFCs. It replaces the initial template described in RFC 3285 to more fully support Word's outline modes and to be easier to use. This template can be direct-printed and direct-viewed, where either is line-for-line identical with RFC Editor-compliant ASCII output. This version obsoletes RFC 3285.The most recent version of this template and post-processing scripts are available at http://www.isi.edu/touch/tools. This document is not an Internet Standards Track specification; it is published for informational purposes.Writing I-Ds and RFCs Using Pandoc and a Bit of XMLThis document presents a technique for using a Markdown syntax variant, called Pandoc, and a bit of XML (as defined in RFC 2629) as a source format for documents that are Internet-Drafts (I-Ds) or RFCs.The goal of this technique (which is called Pandoc2rfc) is to let an author of an I-D focus on the main body of text without being distracted too much by XML tags; however, it does not alleviate the need to typeset some files in XML.The text/markdown Media TypeThis document registers the text/markdown media type for use with Markdown, a family of plain-text formatting syntaxes that optionally can be converted to formal markup languages such as HTML.Guidance on Markdown: Design Philosophies, Stability Strategies, and Select RegistrationsThis document elaborates upon the text/markdown media type for use with Markdown, a family of plain-text formatting syntaxes that optionally can be converted to formal markup languages such as HTML. Background information, local storage strategies, and additional syntax registrations are supplied.RFC Format FrameworkIn order to improve the readability of RFCs while supporting their archivability, the canonical format of the RFC Series will be transitioning from plain-text ASCII to XML using the xml2rfc version 3 vocabulary; different publication formats will be rendered from that base document. With these changes comes an increase in complexity for authors, consumers, and the publisher of RFCs. This document serves as the framework that provides the problem statement, lays out a road map of the documents that capture the specific requirements, and describes the transition plan.The authors would like to thank the following persons for their valuable advice
and input.TODO.