Network Working Group R. Tse
Internet-Draft N. Nicholas
Intended status: Informational J. Lau
Expires: June 1, 2018 P. Brasolin
Ribose
November 28, 2017
AsciiRFC: Authoring Internet-Drafts And RFCs Using AsciiDocdraft-ribose-asciirfc-02
Abstract
This 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.
Status of This Memo
This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
This Internet-Draft will expire on June 1, 2018.
Tse, et al. Expires June 1, 2018 [Page 1]

Internet-Draft AsciiRFC Specifications November 2017
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 471. Introduction
Internet-Drafts and RFCs intended for publication submission to the
IETF can be written in a multitude of formats today, including:
o XML: RFC XML v2 [RFC7749] and v3 [RFC7991]
o nroff: through "NroffEdit" [NroffEdit]
o Microsoft Word: through usage of [RFC5385]
o Lyx: through [lyx2rfc]
o Pandoc: [RFC7328], through [pandoc2rfc] or [draftr]
o Kramdown: through [kramdown-rfc2629]
o mmark: through [mmark]
Interestingly, the last three are Markdown [RFC7763] variants.
As specified in [RFC7990], the IETF intends for the canonical format
of RFCs to transition from plain-text ASCII to RFC XML v3 [RFC7991].
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.
While this need is already met for RFC XML v2 [RFC7749] by the tools
specified above, the transition to RFC XML v3 [RFC7991] places added
onus on authors to generate compliant XML.
[AsciiDoc] is an alternative markup language to Markdown, with
features that make it attractive as a markup language for RFC with
XML output. This document describes the use of [Asciidoctor], a
Ruby-based enhancement of the original AsciiDoc markup language, for
RFC XML markup, with a Ruby gem written by the authors used to render
Asciidoctor documents as RFC XML. The markup language used
specifically for the purpose of generating RFC XML document is called
"AsciiRFC".
Section 1.2 of [RFC7764] 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
Tse, et al. Expires June 1, 2018 [Page 3]

Internet-Draft AsciiRFC Specifications November 2017
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.
Compared to Markdown [Asciidoctor-Manual],
o AsciiDoc 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".
o AsciiDoc in its Ruby-based Asciidoctor implementation is
extensible, with a well-defined API. (Extensions have been
harnessed to deal with bibliographic preprocessing for AsciiRFC.)
o AsciiRFC allows granular control of rendering, including user-
specified attributes of text blocks.
o The Asciidoctor implementation allows document inclusion, for
managing large-scale documentation projects.
o AsciiRFC allows granular control of permutations of block nesting,
such as source code within lists or definition lists within
unordered lists.
o As a more formal counterpart to Markdown, AsciiDoc is well-suited
to generating XML that needs to conform to a specified schema.
As with Markdown, there is a wide range of tools that can render
AsciiDoc; so AsciiRFC drafts of RFC documents can be previewed and
accessed without depending on the RFC tools ecosystem. Our
realisation of RFC XML in AsciiRFC has aimed to ensure that, as much
as possible, the markup language can be can be processed by generic
Asciidoctor tools. (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: see
Section 17.2.)
2. Conventions Used in This Document
The key words "*MUST*", "*MUST NOT*", "*REQUIRED*", "*SHALL*",
"*SHALL NOT*", "*SHOULD*", "*SHOULD NOT*", "*RECOMMENDED*", "*MAY*",
Tse, et al. Expires June 1, 2018 [Page 4]

Internet-Draft AsciiRFC Specifications November 2017
and "*OPTIONAL*" in this document are to be interpreted as described
in [RFC2119].
2.1. Definitions
In this document, _AsciiDoc_ refers to the markup language
generically. _Asciidoctor_ refers specifically to the Ruby-based
implementation of the markup language, which has enhanced the
original markup language. The RFC XML document converter contributed
by the authors uses a subset of _Asciidoctor_, with some minor
additions (a few document attributes specific to RFC XML, some macros
specific to citation processing, and some templated use of
_Asciidoctor_ crossreferences). This variant of _Asciidoctor_ markup
is referred to as _AsciiRFC_.
3. Document Structure And AsciiDoctor Syntax
The syntax of Asciidoctor is presented in the Asciidoctor user manual
[Asciidoctor-Manual]. AsciiRFC is a subset of Asciidoctor syntax,
with the addition of bibliographic macros (Section 17.2).
Asciidoctor consists of:
o A document header, containing a title, a list of authors, and
document attributes in lines prefixed with ":".
o An optional document preamble, separated from document header by a
blank line.
o A 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 header.
* Blocks 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
Tse, et al. Expires June 1, 2018 [Page 5]

Internet-Draft AsciiRFC Specifications November 2017
:email_3: gc@example.com
:email_4: mf@bcc.co.uk
:smart-quotes: false
:link: https://en.wikipedia.org/wiki/Four_Yorkshiremen_sketch
[abstract]
The sketch is a parody of nostalgic conversations about humble
beginnings or difficult childhoods, featuring four men from Yorkshire
who reminisce about their upbringing. As the conversation progresses
they try to outdo one another, and their accounts of deprived
childhoods become increasingly absurd. <<michaelpalin>> <<ericidle>>
NOTE: See also Wikipedia summary
[#michaelpalin]
== Claim: Michael Palin
You were lucky. We lived for three months in a brown paper bag in a
septic tank. We used to have to get up at six o'clock in the morning,
clean the bag, eat a crust of stale bread, go to work down mill for
fourteen hours a day week in-week out. When we got home, our Dad would
thrash us to sleep with his belt! <<RFC7253>>
=== Response: Graham Chapman
Luxury. We used to have to get out of the lake at three o'clock in
the morning, clean the lake, eat a handful of hot gravel, go to work
at the mill every day for tuppence a month, come home, and Dad would
beat us around the head and neck with a broken bottle, if we were
*lucky*!
=== Response: Terry Gilliam
Well we had it tough. We used to have to get up out of the shoebox at
twelve o'clock at night, and *lick* the road clean with our tongues. We
had half a handful of freezing cold gravel, worked twenty-four hours
a day at the mill for fourpence every six years, and when we got home,
our Dad would slice us in two with a bread knife.
[#ericidle]
=== Response: Eric Idle
Right.
I had to get up in the morning at ten o'clock at night, half
an hour before I went to bed, (_pause for laughter_), eat a lump
of cold poison, work twenty-nine hours a day down mill, and pay mill
owner for permission to come to work, and when we got home,
our Dad would kill us, and dance about on our graves
singing "Hallelujah."
[bibliography]
Tse, et al. Expires June 1, 2018 [Page 8]

Internet-Draft AsciiRFC Specifications November 2017
== Normative References
++++
<reference anchor='RFC7253'
target='https://tools.ietf.org/html/rfc7253'>
<front>
<title>Guidelines for Writing an IANA Considerations
Section in RFCs</title>
<author initials="T." surname="Krovetz">
<organization>Sacramento State</organization>
</author>
<author initials="P." surname="Rogaway">
<organization>UC Davis</organization>
</author>
<date month='May' year='2014'/>
</front>
<seriesInfo name="RFC" value="7253"/>
</reference>
++++
[appendix]
== Addendum
But you try and tell the young people today that...
and they won't believe ya.
The first block of text, from "= Four Yorkshiremen Sketch" through to
":link: https://en.wikipedia.org/wiki/Four_Yorkshiremen_sketch", is
the document header. It contains a title in the first line, an
author attribution, and then a set of document attributes, conveying
information about the document as well as information about its
authors. This information ends up either as attributes of the root
"rfc" tag, elements of the "front" tag, or processing instructions.
The following blocks of text, up until the first section header ("==
Claim: Michael Palin"), are the document preamble. They are treated
by the document converter as containing the document abstract
("abstract"), followed by any notes ("note", identified above by the
"NOTE:" heading).
The first section header ("== Claim: Michael Palin") is preceded by
an anchor for that section ("[#michaelpalin]"). There is a cross-
reference to that anchor already in place in the abstract
("<<michaelpalin>>"). The document converter treats the first
section of the document as the start of the "middle" section of the
document.
The first section header is followed by a paragraph, and other
sections and paragraphs. The number of "=" signs are one higher than
the initial section header, which indicates that they are subsections
Tse, et al. Expires June 1, 2018 [Page 9]

Internet-Draft AsciiRFC Specifications November 2017
of that section. The paragraphs contains some inline formatting
(italics: "_pause for laughter_"; boldface: "*lick*"). The first
paragraph also contains a citation of a reference, which in this
version of AsciiRFC is treated identically to a cross-reference
("<<RFC7253>>"). (If the bibliography preprocessor were used, it
would be encoded differently.)
The second last section is tagged with the style attribute
"[bibliography]", which identifies it as a references container; the
document converter accordingly inserts this into the "back" element
of the document. The contents of the references section are in this
instance raw XML, delimited as a passthrough block (with "++++"),
which the converter does not alter. The final section is tagged with
the style attribute "[appendix]", and is treated as such.
The RFC XML v3 document generated from this AsciiRFC document is:
<?xml version="1.0" encoding="US-ASCII"?>
<!DOCTYPE rfc SYSTEM "rfc2629.dtd">
<rfc ipr="trust200902" obsoletes="10, 120" updates="2010, 2120"
submissionType="IETF" prepTime="2017-11-25T09:54:54Z" version="3">
<link href="https://en.wikipedia.org/wiki/Four_Yorkshiremen_sketch"/>
<front>
<title abbrev="4 Yorkshiremen">Four Yorkshiremen Sketch</title>
<seriesInfo name="Internet-Draft" status="informational"
stream="IETF" value="draft-four-yorkshiremen-00" />
<author fullname="Tim Brooke-Taylor" surname="Brooke-Taylor">
<organization>BBC</organization>
<address>
<postal>
<street>10 Moulton Street</street>
<city>Cambridge</city>
<code>MA 02238</code>
</postal>
<phone>(555) 555-5555</phone>
<email>tbt@example.com</email>
<uri>http://example.com</uri>
</address>
</author>
<author fullname="John Cleese" surname="Cleese">
<address>
<email>jc@example.com</email>
</address>
</author>
<author fullname="Graham Chapman" surname="Chapman">
<address>
<email>gc@example.com</email>
</address>
Tse, et al. Expires June 1, 2018 [Page 10]

Internet-Draft AsciiRFC Specifications November 2017
</author>
<author fullname="Marty Feldman" surname="Feldman">
<address>
<email>mf@bcc.co.uk<email>
</address>
</author>
<date day="1" month="April" year="1990" />
<area>Internet<area>
<workgroup>Network Working Group</workgroup>
<keyword>yorkshire<keyword>
<keyword>memory<keyword>
<abstract>
<t>The sketch is a parody of nostalgic conversations about humble
beginnings or difficult childhoods, featuring four men from
Yorkshire who reminisce about their upbringing. As the
conversation progresses they try to outdo one another, and their
accounts of deprived childhoods become increasingly absurd.
<xref target="michaelpalin" />
<xref target="ericidle" /></t>
</abstract>
<note>
<t>See also Wikipedia summary<t>
</note>
</front>
<middle>
<section anchor="michaelpalin" numbered="false">
<name>Claim: Michael Palin<name>
<t>You were lucky. We lived for three months in a brown paper bag
in a septic tank. We used to have to get up at six o'clock in
the morning, clean the bag, eat a crust of stale bread, go to
work down mill for fourteen hours a day week in-week out. When
we got home, our Dad would thrash us to sleep with his belt!
<xref target="RFC7253" /></t>
<section anchor="_response_graham_chapman" numbered="false">
<name>Response: Graham Chapman<name>
<t>Luxury. We used to have to get out of the lake at three
o'clock in the morning, clean the lake, eat a handful of hot
gravel, go to work at the mill every day for tuppence a month,
come home, and Dad would beat us around the head and neck with
a broken bottle, if we were <strong>lucky</strong>!</t>
</section>
<section anchor="_response_terry_gilliam" numbered="false">
<name>Response: Terry Gilliam<name>
<t>Well we had it tough. We used to have to get up out of the
shoebox at twelve o'clock at night, and <strong>lick<strong>
the road clean with our tongues. We had half a handful of
freezing cold gravel, worked twenty-four hours a day at the
mill for fourpence every six years, and when we got home,
Tse, et al. Expires June 1, 2018 [Page 11]

Internet-Draft AsciiRFC Specifications November 2017
our Dad would slice us in two with a bread knife.</t>
</section>
<section anchor="ericidle" numbered="false">
<name>Response: Eric Idle<name>
<t>Right.<t>
<t>I had to get up in the morning at ten o'clock at night, half
an hour before I went to bed, (<em>pause for laughter</em>),
eat a lump of cold poison, work twenty-nine hours a day down
mill, and pay mill owner for permission to come to work, and
when we got home, our Dad would kill us, and dance about on
our graves singing "Hallelujah."</t>
</section>
</section>
</middle>
<back>
<references anchor="_normative_references">
<name>Normative References<name>
<reference anchor="RFC7253"
target="https://tools.ietf.org/html/rfc7253">
<front>
<title>Guidelines for Writing an IANA Considerations
Section in RFCs<title>
<author initials="T." surname="Krovetz">
<organization>Sacramento State<organization>
</author>
<author initials="P." surname="Rogaway">
<organization>UC Davis<organization>
</author>
<date month="May" year="2014" />
</front>
<seriesInfo name="RFC" value="7253" />
</reference>
</references>
<section anchor="_addendum" numbered="false">
<name>Addendum<name>
<t>But you try and tell the young people today that&#8230;&#8203;
and they won't believe ya'.<t>
</section>
</back>
</rfc>
Some default processing instructions have already been prefixed to
the XML.
Although we do not describe it extensively in this document, our
AsciiRFC converter also generates RFC XML v2 from the same source
AsciiRFC. For illustration, the foregoing AsciiRFC document
generates the following RFC XML v2 output:
Tse, et al. Expires June 1, 2018 [Page 12]

Internet-Draft AsciiRFC Specifications November 2017
<t>See also Wikipedia summary</t>
</note>
</front>
<middle>
<section anchor="michaelpalin" title="Claim: Michael Palin">
<t>You were lucky. We lived for three months in a brown paper bag
in a septic tank. We used to have to get up at six o'clock in
the morning, clean the bag, eat a crust of stale bread, go to
work down mill for fourteen hours a day week in-week out. When
we got home, our Dad would thrash us to sleep with his belt!
<xref target="RFC7253" /></t>
<section anchor="_response_graham_chapman"
title="Response: Graham Chapman">
<t>Luxury. We used to have to get out of the lake at three
o'clock in the morning, clean the lake, eat a handful of hot
gravel, go to work at the mill every day for tuppence a month,
come home, and Dad would beat us around the head and neck with
a broken bottle, if we were
<spanx style="strong">lucky</spanx>!</t>
</section>
<section anchor="_response_terry_gilliam"
title="Response: Terry Gilliam">
<t>Well we had it tough. We used to have to get up out of the
shoebox at twelve o'clock at night, and
<spanx style="strong">lick<spanx>
the road clean with our tongues. We had half a handful of
freezing cold gravel, worked twenty-four hours a day at the
mill for fourpence every six years, and when we got home,
our Dad would slice us in two with a bread knife.</t>
</section>
<section anchor="ericidle" title="Response: Eric Idle">
<t>Right.</t>
<t>I had to get up in the morning at ten o'clock at night, half
an hour before I went to bed, (<spanx style="emph">pause
for laughter</spanx>),
eat a lump of cold poison, work twenty-nine hours a day down
mill, and pay mill owner for permission to come to work, and
when we got home, our Dad would kill us, and dance about on
our graves singing "Hallelujah."</t>
</section>
</section>
</middle>
<back>
<references title="Normative References">
<reference anchor="RFC7253"
target="https://tools.ietf.org/html/rfc7253">
<front>
<title>Guidelines for Writing an IANA Considerations
Tse, et al. Expires June 1, 2018 [Page 14]

Internet-Draft AsciiRFC Specifications November 2017
<rfc submissionType="IETF" prepTime="2017-11-25T10:23:39Z" version="3">
<front>
<title>Four Yorkshiremen Sketch</title>
<seriesInfo name="Internet-Draft" status="informational"
stream="IETF" value="draft-four-yorkshiremen-00" />
<author fullname="Tim Brooke-Taylor" surname="Brooke-Taylor">
<address>
<email>tbt@example.com</email>
</address>
</author>
<date day="25" month="November" year="2017" />
</front>
<middle>
<section anchor="_section_1" numbered="false">
<name>Section 1</name>
<t>The specification <strong>MUST NOT</strong>
use the word <em> doesn't</em>.</t>
</section>
</middle>
</rfc>
5. Preamble
The preamble in AsciiRFC 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:
Tse, et al. Expires June 1, 2018 [Page 22]

Internet-Draft AsciiRFC Specifications November 2017
= Four Yorkshiremen Sketch
Tim Brooke-Taylor <tbt@example.com>
:doctype: internet-draft
:status: informational
:name: draft-four-yorkshiremen-00
The "Four Yorkshiremen" sketch is a comedy sketch written by
Tim Brooke-Taylor, John Cleese, Graham Chapman and Marty Feldman and
originally performed on their TV series _At Last the 1948 Show_ in 1967.
It later became associated with the comedy group Monty Python
(which included Cleese and Chapman), who performed it in their live
shows, including _Monty Python Live at the Hollywood Bowl_.
The sketch is a parody of nostalgic conversations about humble
beginnings or difficult childhoods, featuring four men from Yorkshire
who reminisce about their upbringing. As the conversation progresses
they try to outdo one another, and their accounts of deprived
childhoods become increasingly absurd.
NOTE: Barry Cryer is the wine waiter in the original performance
and may have contributed to the writing.
[NOTE]
.Original Recording
====
The original performance of the sketch by the four creators is one of
the surviving sketches from the programme and can be seen on the
_At Last the 1948 Show_ DVD.
====
Tse, et al. Expires June 1, 2018 [Page 23]

Internet-Draft AsciiRFC Specifications November 2017
<rfc submissionType="IETF" prepTime="2017-11-25T10:32:27Z" version="3">
<front>
<title>Four Yorkshiremen Sketch</title>
<seriesInfo name="Internet-Draft" status="informational"
stream="IETF" value="draft-four-yorkshiremen-00" />
<author fullname="Tim Brooke-Taylor" surname="Brooke-Taylor">
<address>
<email>tbt@example.com</email>
</address>
</author>
<date day="25" month="November" year="2017" />
<abstract>
<t>The "Four Yorkshiremen" sketch is a comedy sketch written by
Tim Brooke-Taylor, John Cleese, Graham Chapman and Marty Feldman
and originally performed on their TV series <em>At Last the 1948
Show</em> in 1967. It later became associated with the comedy
group Monty Python (which included Cleese and Chapman), who
performed it in their live shows, including <em>Monty Python
Live at the Hollywood Bowl</em>.</t>
<t>The sketch is a parody of nostalgic conversations about humble
beginnings or difficult childhoods, featuring four men from
Yorkshire who reminisce about their upbringing. As the
conversation progresses they try to outdo one another, and their
accounts of deprived childhoods become increasingly absurd.</t>
</abstract>
<note>
<t>Barry Cryer is the wine waiter in the original performance and
may have contributed to the writing.</t>
</note>
<note>
<name>Original Recording</name>
<t>The original performance of the sketch by the four
creators is one of the surviving sketches from the programme
and can be seen on the <em>At Last the 1948 Show</em> DVD.</t>
</note>
</front>
6. Sections and Paragraphs
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). The "toc"
attribute can also be set on sections, indicating whether the section
can be included in the document's table of contents.
Tse, et al. Expires June 1, 2018 [Page 24]

Internet-Draft AsciiRFC Specifications November 2017
(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 Asciidoctor open block):
* List Entry 1
* List Entry 2
+
--
Note 2.
....
Literal
....
Note 3.
--
<ul>
<li>List Entry 1</li>
<li>
<t>List Entry 2</t>
<t>Note 2.</t>
<figure>
<artwork type="ascii-art">
Literal
</artwork>
</figure>
<t>Note 3.</t>
</li>
</ul>
AsciiDoc, and thus AsciiRFC, 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 AsciiRFC:
Tse, et al. Expires June 1, 2018 [Page 29]

Internet-Draft AsciiRFC Specifications November 2017
<t>
This is the start of a paragraph.
<ul>
<li>List Entry 1</li>
<li>
<t>List Entry 2</t>
<t>Note 2.</t>
</li>
</ul>
And this is the continuation of the paragraph.
</t>
9. Blockquotes
Asciidoctor supports blockquotes and quotations of verse; its block
quotations permit arbitrary levels of quote nesting. RFC XML v3, and
thus AsciiRFC, only supports one level of blockquotes. Unlike RFC
XML v2, RFC XML v3 does not support line breaks outside of tables; so
verse quotations are converted to prose in the v3 converter.
[quote,attribution="Monty Python",citetitle="http://example.com"]
____
Dennis: Come and see the violence inherent in the system.
Help! Help! I'm being repressed!
King Arthur: Bloody peasant!
Dennis: Oh, what a giveaway!
* Did you hear that?
* Did you hear that, eh?
* That's what I'm on about!
** Did you see him repressing me?
** You saw him, Didn't you?
____
Tse, et al. Expires June 1, 2018 [Page 30]

Internet-Draft AsciiRFC Specifications November 2017
<blockquote quotedfrom="Monty Python" cite="http://example.com">
<t>Dennis: Come and see the violence inherent in the system.
Help! Help! I&#8217;m being repressed!</t>
<t>King Arthur: Bloody peasant!</t>
<t>Dennis: Oh, what a giveaway!</t>
<ul>
<li>Did you hear that?</li>
<li>Did you hear that, eh?</li>
<li>
<t>That&#8217;s what I&#8217;m on about!</t>
<ul>
<li>Did you see him repressing me?</li>
<li>You saw him, Didn&#8217;t you?</li>
</ul>
</li>
</ul>
</blockquote>
10. Notes And Asides
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 conflated in AsciiRFC, being converted to "note"
elements in the document preamble, and "cref" documents in the main
document.
== Section 1
[NOTE,source=GBS]
.Note Title
====
Any admonition inside the body of the text is a comment.
====
<section anchor="_section_1" numbered="false">
<name>Section 1</name>
<t>
<cref display="true" source="GBS">
Any admonition inside the body of the text is a comment.
</cref>
</t>
</section>
Note that no inline formatting is permitted in RFC XML v2 "cref"
elements, and it is stripped for v2 by the converter.
Because paragraphs in AsciiRFC cannot contain any other blocks, a
comment at the end of a paragraph is treated as a new block. In the
Tse, et al. Expires June 1, 2018 [Page 31]

Internet-Draft AsciiRFC Specifications November 2017
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.
The RFC XML v3 converter also supports asides (Asciidoctor sidebars):
== Section 1
****
Sidebar
Another sidebar
* This is a list
....
And this is ascii-art
....
****
<section anchor="_section_1" numbered="false">
<name>Section 1</name>
<aside>
<t>Sidebar</t>
<t>Another sidebar</t>
<ul>
<li>This is a list</li>
</ul>
<figure>
<artwork type="ascii-art">
And this is ascii-art
</artwork>
</figure>
</aside>
</section>
While AsciiDoc has comments proper, notated with initial "//", they
are ignored by the Asciidoctor document converter; so they will not
appear as XML comments in the converter output.
11. Tables
AsciiRFC 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 table formatting options
available in RFC XML v2 is also supported.
Tse, et al. Expires June 1, 2018 [Page 32]

Internet-Draft AsciiRFC Specifications November 2017
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.
12. Inline Formatting
Like RFC XML v3, AsciiRFC supports italics, boldface, monospace,
subscripts and superscripts:
_Text_ *Text* `Text` ^Superscript^ ~Subscript~
<t><em>Text</em> <strong>Text</strong> <tt>Text</tt>
<sup>Superscript</sup> <sub>Subscript</sub></t>
RFC XML v3 also supports tagging of BCP14 keywords [RFC2119]; this is
done in AsciiRFC either by tagging them with a custom formatting span
("bcp14#must not#"), or by converting BCP14 boldface all-caps words
(unless the ":no-rfc-bold-bcp14: false" document attribute is set):
This [bcp14]#must not# stand
This *MUST NOT* stand
<t>This <bcp14>MUST NOT</bcp14> stand</t>
<t>This <bcp14>MUST NOT</bcp14> stand</t>
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 "**" and "__", need to be escaped
with double backslash ("\\**"). Escaping delimiters is not always
reliable, and for double delimiters it is preferable to use HTML
entities ("&#42;&#42;"), or attribute references (references to the
value of attributes set in the document header):
:dblast: **
`{dblast}`
In extreme circumstances (such as quoting AsciiDoc syntax), you may
need to resort to altering the substitutions behaviour within a given
block of of AsciiDoc; see the "Applying Substitutions" section of
[Asciidoctor-Manual].
Tse, et al. Expires June 1, 2018 [Page 35]

Internet-Draft AsciiRFC Specifications November 201713. Links
Common URL formats are recognised automatically as hyperlinks, and
are rendered as such; any hyperlinked text is appended after the
hyperlink in square brackets:
http://example.com/[linktext]
<t><eref target="http://example.com/">linktext</eref></t>
To prevent hyperlinking of a URL, prefix it with a backslash.
\http://example.com/[linktext]
<t>http://example.com/[linktext]</t>
14. Cross-references
Anchors for cross-references 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>>".
[[crossreference]]
== Section 1
== Section 2
See <<crossreference>>.
== Section 3
See <<crossreference,text>>
Tse, et al. Expires June 1, 2018 [Page 36]

Internet-Draft AsciiRFC Specifications November 2017
include::path[
leveloffset=_offset_,
lines=_ranges_,
tag(s)=_name(s)_,
indent=_depth_
]
If a file is included in an AsciiRFC document, ensure it ends with a
blank line. An inclusion that results in its final block not being
delimited with a blank line from what follows can lead to
unpredictable results.
16. Encoding and Entities
XML accepts 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 AsciiRFC, even though they are
not part of the XML specification; HTML entities such as "&nbsp;"
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.
&#1069;&#1090;&#1086;
&#1056;&#1091;&#1089;&#1089;&#1082;&#1080;&#1081;
&#1071;&#1079;&#1099;&#1082;.
&mdash; This is not George&apos;s.&#x2020;
<t>&#1069;&#1090;&#1086;
&#1056;&#1091;&#1089;&#1089;&#1082;&#1080;&#1081;
&#1071;&#1079;&#1099;&#1082;. &#8212;
This is not George's.&#8224;</t>
17. Bibliography
Asciidoctor natively has a simple encoding of bibliographies, which
is not adequate for the complexity of bibliographic markup required
by RFC XML.
RFC documents overwhelmingly cite other RFC documents, and canonical
RFC XML bibliographic entries are available at [IETF-BibXML]; so it
Tse, et al. Expires June 1, 2018 [Page 39]

Internet-Draft AsciiRFC Specifications November 2017
would be inefficient to encode those entries in AsciiRFC, only to
have them converted back to RFC XML.
The converter provides two means of incorporating bibliographies into
RFC documents authored in AsciiRFC:
o using raw RFC XML; and
o assembling 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.
17.1. Using Raw RFC XML
In the first method, bibliographic citations are handled like all
other AsciiRFC cross-references. The bibliographic entries for
normative and informative references are given in the AsciiRFC 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. For example:
Some datagram padding may be needed.<<RFC7253>>
[bibliography]
== Normative References
++++
<reference anchor='RFC7253'
target='https://tools.ietf.org/html/rfc7253'>
<front>
<title>Guidelines for Writing an IANA Considerations
Section in RFCs</title>
<author initials="T." surname="Krovetz">
<organization>Sacramento State</organization>
</author>
<author initials="P." surname="Rogaway">
<organization>UC Davis</organization>
</author>
<date month='May' year='2014'/>
</front>
<seriesInfo name="RFC" value="7253"/>
</reference>
++++
Tse, et al. Expires June 1, 2018 [Page 40]

Internet-Draft AsciiRFC Specifications November 2017
<t>Some datagram padding may be needed <xref target="RFC7253"/></t>
</middle><back>
<references anchor="_references">
<name>Normative References</name>
<reference anchor='RFC7253'
target='https://tools.ietf.org/html/rfc7253'>
<front>
<title>Guidelines for Writing an IANA Considerations
Section in RFCs</title> <author initials="T." surname="Krovetz">
<organization>Sacramento State</organization>
</author>
<author initials="P." surname="Rogaway">
<organization>UC Davis</organization>
</author>
<date month='May' year='2014'/>
</front>
<seriesInfo name="RFC" value="7253"/>
</reference>
</references>
17.2. Using Preprocessing
The alternative method is to use a preprocessing tool,
[asciidoctor-bibliography], to import citations into the AsciiRFC
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:
1. 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.
A. Rather than hand crafting RFC XML references for RFC
documents, you should download them from an authoritative
source; e.g. ""
Tse, et al. Expires June 1, 2018 [Page 41]

Internet-Draft AsciiRFC Specifications November 2017
B. 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.
C. 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.
2. Add to the main document header attributes referencing the
references file (":bibliography-database:"), and the bibliography
style (":bibliography-style:rfc-v3").
3. References to a normative reference are inserted with the macro
"cite:norm[id]" instead of "<<id>>", where "id" is the anchor of
the reference.
4. References to an infomrative reference are inserted with the
macro "cite:info[id]" instead of "<<id>>", where "id" is the
anchor of the reference.
5. Formatted crossreferences and "relref" crossreferences are
entered by inserting the expected raw XML in the "text"
attribute. Do not use the "{cite}" interpolation of the
citation. For example:
* "<<id,words>>" = "cite:norm[id, text="<xref
target='id'>words</xref>"]"
* "<<id,format=counter: words>>" (processed as a formatted
crossreference) = "cite:norm[id, text="<xref format='counter'
target='id'>words</xref>"]"
* "<<id,2.4 comma: words>>" (processed as relref) =
"cite:norm[id, text="<relref displayFormat='comma'
section='2.4' target='id'}/>"]"
* "<<id#section2_4,2.4 comma: words>>" (processed as relref with
a cross-document internal reference) = "cite:norm[id,
text="<relref relative='section2_4' displayFormat='comma'
section='2.4' target='id'/>"]"
6. Normative and Informative References are inserted in the document
through a macro, which occurs where the RFC XML references would
be inserted:
Tse, et al. Expires June 1, 2018 [Page 42]

Internet-Draft AsciiRFC Specifications November 2017
$ git clone https://github.com/riboseinc/rfc-in-asciidoc-template
Converting your AsciiRFC to RFC XML is a simple as installing
Asciidoctor (see "Installation" at [Asciidoctor]) and the
"asciidoctor-rfc" gem in Ruby, then running the asciidoctor
executable on the document, specifying the asciidoctor-rfc gem as a
library:
$ git clone https://github.com/riboseinc/asciidoctor-rfc
$ cd asciidoctor-rfc
$ bundle install
$ gem build asciidoctor-rfc.gemspec
$ gem install asciidoctor-rfc
$ asciidoctor -b rfc3 -r 'asciidoctor-rfc' a.adoc # RFC XML v3 output
$ asciidoctor -b rfc2 -r 'asciidoctor-rfc' a.adoc # RFC XML v2 output
As you author AsciiRFC 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:
V3 RELAXNG Validation: 12:0: ERROR: Invalid attribute
sortRefs for element rfc
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 AsciiRFC 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 AsciiRFC.
20. Security Considerations
o 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 resulting
document.
o An AsciiRFC generator may cause errors in textual rendering or
link generation that may lead to security issues.
Tse, et al. Expires June 1, 2018 [Page 44]