| Network Working Group | R. Tse |
| Internet-Draft | N. Nicholas |
| Intended status: Informational | J. Lau |
| Expires: May 29, 2018 | P. Brasolin |
| Ribose | |
| November 25, 2017 |
Writing Internet-Drafts And RFCs In AsciiDoc (AsciiRFC)
draft-ribose-asciirfc-01
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.
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 May 29, 2018.
Copyright (c) 2017 IETF Trust and the persons identified as the document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.
Internet-Drafts and RFCs intended for publication submission to the IETF can be written in a multitude of formats today, including:
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 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 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.)
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 [RFC2119].
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.
The syntax of Asciidoctor is presented in the Asciidoctor user manual. AsciiRFC is a subset of Asciidoctor syntax, with the addition of bibliographic macros (Section 17.2).
Asciidoctor consists of:
Inline markup includes:
The Asciidoctor document structure aligns with the RFC XML v2 and v3 structure. In the following, v3 equivalences are given:
Full details of the mapping of AsciiRFC elements to RFC XML v2 and v3 elements, and of how to convert AsciiRFC documents to RFC XML, are given in <https://github.com/riboseinc/asciidoctor-rfc/blob/master/README.adoc>. The following gives an overview of how to create an RFC XML document in AsciiRFC, with some pitfalls to be aware of. Illustrations are in RFC XML v3, although the converter deals with both versions of RFC XML.
The following is an illustration of a simple AsciiRFC document, and its corresponding rendering in RFC XML v3:
= Four Yorkshiremen Sketch
Tim Brooke-Taylor; John Cleese; Graham Chapman; Marty Feldman
:doctype: internet-draft
:abbrev: 4 Yorkshiremen
:obsoletes: 10, 120
:updates: 2010, 2120
:status: informational
:name: draft-four-yorkshiremen-00
:ipr: trust200902
:area: Internet
:workgroup: Network Working Group
:keyword: yorkshire, memory
:revdate: 1990-04-01T00:00:00Z
:organization: BBC
:phone: (555) 555-5555
:uri: http://example.com
:street: 10 Moulton Street
:city: Cambridge
:code: MA 02238
:email: tbt@example.com
:email_2: jc@example.com
:email_3: gc@example.com
:email_4: mf@bcc.co.uk
:smart-quotes: false
:link: https://en.wikipedia.org/wiki/Four_Yorkshiremen_sketch describedby
[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, out 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]
== 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 describedby, 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 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"
rel="describedby" />
<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>
</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, out 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, 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…​
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:
<rfc ipr="trust200902" obsoletes="10, 120" updates="2010, 2120"
category="info" submissionType="IETF"
docName="draft-four-yorkshiremen-00">
<front>
<title abbrev="4 Yorkshiremen">Four Yorkshiremen Sketch<title>
<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>
</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 title="NOTE">
<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, out 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 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" title="Addendum">
<t>But you try and tell the young people today that…​
and they won't believe ya'.</t>
</section>
</back>
</rfc>
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:
= Four Yorkshiremen Sketch Tim Brooke-Taylor <tbt@example.com> :doctype: internet-draft :abbrev: 4 Yorkshiremen :obsoletes: 10, 120 :updates: 2010, 2120 :status: informational :name: draft-four-yorkshiremen-00 :ipr: trust200902 :area: Internet :workgroup: Network Working Group :keyword: yorkshire, memory :revdate: 1990-04-01T00:00:00Z
The document attributes are used to populate attributes of the root rfc element, front elements, and document-level processing instructions.
The foregoing AsciiRFC renders into RFC XML v3 as:
<rfc ipr="trust200902" obsoletes="10, 120" updates="2010, 2120"
submissionType="IETF" prepTime="2017-11-25T10:13:46Z" version="3">
<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">
<address>
<email>tbt@example.com</email>
</address>
</author>
<date day="1" month="April" year="1990" />
<area>Internet</area>
<workgroup>Network Working Group</workgroup>
<keyword>yorkshire</keyword>
<keyword>memory</keyword>
The document header can spell out further information about authors, including contact details:
= Four Yorkshiremen Sketch Tim Brooke-Taylor <tbt@example.com> :doctype: internet-draft :abbrev: 4 Yorkshiremen :obsoletes: 10, 120 :updates: 2010, 2120 :status: informational :name: draft-four-yorkshiremen-00 :ipr: trust200902 :area: Internet :workgroup: Network Working Group :keyword: yorkshire, memory :revdate: 1990-04-01T00:00:00Z :organization: BBC :phone: (555) 555-5555 :uri: http://bbn.com :street: 10 Moulton Street :city: Cambridge :code: MA 02238
<rfc ipr="trust200902" obsoletes="10, 120" updates="2010, 2120"
submissionType="IETF" prepTime="2017-11-25T10:15:02Z" version="3">
<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://bbn.com</uri>
</address>
</author>
<date day="1" month="April" year="1990" />
<area>Internet</area>
<workgroup>Network Working Group</workgroup>
<keyword>yorkshire</keyword>
<keyword>memory</keyword>
Details of a second, third etc. author, including their organization and contact details, are provided by suffixing the relevant author attributes with _2, _3 etc.:
= Four Yorkshiremen Sketch Tim Brooke-Taylor <tbt@example.com>; John Cleese <jc@example.com> :doctype: internet-draft :status: informational :name: draft-four-yorkshiremen-00 :ipr: trust200902 :organization: BBC :phone: (555) 555-5555 :uri: http://example.com :street: 10 Moulton Street :city: Cambridge :code: MA 02238 :forename_initials: T. :lastname: Brooke-Taylor :street: 12 Moulton Street :city: London :country: United Kingdom :forename_initials_2: J. :lastname_2: Cleese :uri_2: https://twitter.com/johncleese
<rfc ipr="trust200902" submissionType="IETF"
prepTime="2017-11-25T10:19:32Z" 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" initials="T.">
<organization>BBC</organization>
<address>
<postal>
<street>12 Moulton Street</street>
<city>London</city>
<code>MA 02238</code>
<country>United Kingdom</country>
</postal>
<phone>(555) 555-5555</phone>
<email>tbt@example.com</email>
<uri>http://example.com</uri>
</address>
</author>
<author fullname="John Cleese" surname="Cleese" initials="J.">
<address>
<email>jc@example.com</email>
<uri>https://twitter.com/johncleese</uri>
</address>
</author>
<date day="25" month="November" year="2017" />
The initial author attribution in AsciiRFC, e.g. Tim Brooke-Taylor <tbt @ example.com>; John Cleese <jc @ example.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 AsciiRFC :forename_initials: attribute replaces the built-in Asciidoctor :initials: attribute (which includes the surname initial), and is not automatically populated from the name attribution.
A document header may also contain attribute headers which are treated as XML processing instructions:
= Four Yorkshiremen Sketch Tim Brooke-Taylor <tbt@example.com> :doctype: internet-draft :status: informational :name: draft-four-yorkshiremen-00 :ipr: trust200902 :revdate: 1990-04-01T00:00:00Z :rfcedstyle: yes :text-list-symbols: yes :rfc2629xslt: true
<rfc ipr="trust200902" submissionType="IETF"
prepTime="2017-11-25T10:21:56Z" 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="1" month="April" year="1990" />
A few document attributes are specific to the operation of the RFC XML document converter:
= Four Yorkshiremen Sketch Tim Brooke-Taylor <tbt@example.com> :doctype: internet-draft :status: informational :name: draft-four-yorkshiremen-00 == Section 1 The specification *MUST NOT* use the word _doesn't_.
<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 <bcp14>MUST NOT</bcp14>
use the word <em> doesn’t</em>.</t>
</section>
</middle>
</rfc>
= Four Yorkshiremen Sketch Tim Brooke-Taylor <tbt@example.com> :doctype: internet-draft :status: informational :name: draft-four-yorkshiremen-00 :no-rfc-bold-bcp14: false :smart-quotes: false == Section 1 The specification *MUST NOT* use the word _doesn't_.
<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>
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:
= 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. ====
<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>
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.
:sectnums: [toc=exclude] == Section 1 Para 1 === Subsection 1.1 Para 1a :sectnums!: [toc=default] === Subsection 1.2 Para 2 ==== Subsection 1.2.1 Para 3
<section anchor="_section_1" toc="exclude" numbered="true">
<name>Section 1</name>
<t>Para 1</t>
<section anchor="_subsection_1_1" numbered="true">
<name>Subsection 1.1</name>
<t>Para 1a</t>
</section>
<section anchor="_subsection_1_2" toc="default" numbered="false">
<name>Subsection 1.2</name>
<t>Para 2</t>
<section anchor="_subsection_1_2_1" numbered="false">
<name>Subsection 1.2.1</name>
<t>Para 3</t>
</section>
</section>
</section>
AsciiRFC 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:
.Figure 1
====
.figure1.txt
....
Figures are only permitted to contain listings
(sourcecode), images (artwork), or literal (artwork)
This is some ASCII Art:
_____ ___ ____ _ _
| ___|_ _/ ___| | ___| |_
| |_ | | | _| |/ _ \ __|
| _| | | |_| | | __/ |_
|_| |___\____|_|\___|\__|
....
[source,ruby]
----
def listing(node)
result = []
if node.parent.context != :example
result << "<figure>"
end
end
----
====
<figure>
<name>Figure 1</name>
<artwork type="ascii-art" name="figure1.txt">
Figures are only permitted to contain listings
(sourcecode), images (artwork), or literal (artwork)
This is some ASCII Art:
_____ ___ ____ _ _
| ___|_ _/ ___| | ___| |_
| |_ | | | _| |/ _ \ __|
| _| | | |_| | | __/ |_
|_| |___\____|_|\___|\__|</artwork>
<sourcecode type="ruby">
def listing(node)
result = []
if node.parent.context != :example
result << "<figure>"
end
end
</sourcecode>
</figure>
If an AsciiRFC Listing or Literal occurs outside of an Example, the RFC XML converter will supply the surrounding Figure element:
.... This is some ASCII Art: _____ ___ ____ _ _ | ___|_ _/ ___| | ___| |_ | |_ | | | _| |/ _ \ __| | _| | | |_| | | __/ |_ |_| |___\____|_|\___|\__| ....
<figure> <artwork type="ascii-art">This is some ASCII Art: _____ ___ ____ _ _ | ___|_ _/ ___| | ___| |_ | |_ | | | _| |/ _ \ __| | _| | | |_| | | __/ |_ |_| |___\____|_|\___|\__|</artwork> </figure>
AsciiRFC 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:
[loweralpha] . First . Second [upperalpha] .. Third .. Fourth . Fifth . Sixth
<ol anchor="id" type="a">
<li>First</li>
<li>
<t>Second</t>
<ol type="A">
<li>Third</li>
<li>Fourth</li>
</ol>
</li>
<li>Fifth</li>
<li>Sixth</li>
</ol>
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 (Asciidoctor list continuation.)
Notes:: Note 1. + Note 2. + Note 3.
<dl>
<dt>Notes</dt>
<dd>
<t>Note 1.</t>
<t>Note 2.</t>
<t>Note 3.</t>
</dd>
</dl>
(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:
<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>
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? ____
<blockquote quotedfrom="Monty Python" cite="http://example.com">
<t>Dennis: Come and see the violence inherent in the system.
Help! Help! I’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’s what I’m on about!</t>
<ul>
<li>Did you see him repressing me?</li>
<li>You saw him, Didn’t you?</li>
</ul>
</li>
</ul>
</blockquote>
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 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.
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.
.Table Title |=== |head | head h|header cell | body cell | | body cell 2+| colspan of 2 .2+|rowspan of 2 | cell |cell ^|centre aligned cell | cell <|left aligned cell | cell >|right aligned cell | cell |foot | foot |===
<table>
<name>Table Title</name>
<thead>
<tr>
<th align="left">head</th>
<th align="left">head</th>
</tr>
</thead>
<tbody>
<tr>
<th align="left">header cell</th>
<td align="left">body cell</td>
</tr>
<tr>
<td align="left"></td>
<td align="left">body cell</td>
</tr>
<tr>
<td colspan="2" align="left">colspan of 2</td>
</tr>
<tr>
<td rowspan="2" align="left">rowspan of 2</td>
<td align="left">cell</td>
</tr>
<tr>
<td align="left">cell</td>
</tr>
<tr>
<td align="center">centre aligned cell</td>
<td align="left">cell</td>
</tr>
<tr>
<td align="left">left aligned cell</td>
<td align="left">cell</td>
</tr>
<tr>
<td align="right">right aligned cell</td>
<td align="left">cell</td>
</tr>
</tbody>
<tfoot>
<tr>
<td align="left">foot</td>
<td align="left">foot</td>
</tr>
</tfoot>
</table>
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, 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 (**), 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 <http://asciidoctor.org/docs/user-manual/#applying-substitutions>
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>
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>>.
[[crossreference]] == Section 1 == Section 2 See <<crossreference>>. == Section 3 See <<crossreference,text>>
<section anchor="crossreference" numbered="false">
<name>Section 1</name>
</section>
<section anchor="_section_2" numbered="false">
<name>Section 2</name>
<t>
See
<xref target="crossreference">
</xref>.
</t>
</section>
<section anchor="_section_3" numbered="false">
<name>Section 3</name>
<t>
See
<xref target="crossreference">
text
</xref>
</t>
</section>
Asciidoctor natively does not otherwise support attributes on cross-references. AsciiRFC works around that by embedding formatting information as 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.
== Section 4 See <<crossreference,format=counter: text>> == Section 5 See <<crossreference,format=title>> See <<crossreference,1.3 of>> <<crossreference,1.4 comma: text>> <<crossreference#fragment1,2.5.3 parens>> <<crossreference#fragment2,6.2a bare: text>>
<section anchor="_section_4" numbered="false">
<name>Section 4</name>
<t>
See
<xref format="counter" target="crossreference">
text
</xref>
</t>
</section>
<section anchor="_section_5" numbered="false">
<name>
Section 5
</name>
<t>
See
<xref format="title" target="crossreference" />
</t>
<t>
See
<relref section="1.3" displayformat="of"
target="crossreference" />
<relref section="1.4" displayformat="comma"
target="crossreference">
text
</relref>
<relref relative="fragment1" section="2.5.3"
displayformat="parens" target="crossreference" />
<relref relative="fragment2" section="6.2a"
displayformat="bare" target="crossreference">
text
</relref>
</t>
</section>
The Asciidoctor "include" directive is used to include external files in a master AsciiRFC 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:
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.
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 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.
Это Русский Язык. — This is not George's.†
<t>Это Русский Язык. — This is not George's.†</t>
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 <http://xml.resource.org/public/rfc/bibxml/> ; so it 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:
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 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>
++++
<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>
The alternative method is to use a preprocessing tool, asciidoc-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:
[bibliography] == Normative References ++++ bibliography::norm[] ++++ [bibliography] == Informative References ++++ bibliography::info[] ++++
The following features of RFC XML are not supported by the AsciiRFC converter, and would need to be adjusted manually after RFC XML is generated:
| RFC XML element | RFC XML v3 | RFC XML v2 |
|---|---|---|
| front/boilerplate | Not added by the converter | Not added by the converter |
| iref@primary | N | N |
| reference (and all children) | As Raw XML | As Raw XML |
| table/preamble | Deprecated | N |
| table/postamble | Deprecated | N |
| artwork@width | Only on images | Only on images |
| artwork@height | Only on images | Only on images |
To author an AsciiRFC 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 AsciiRFC 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 AsciiRFC documents:
$ git clone https://github.com/riboseinc/rfc-in-asciidoc-template
Converting your AsciiRFC to RFC XML is a simple as installing Asciidoctor (see <http://asciidoctor.org/#installation>) 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.
This document does not require any action by IANA.
TODO.
| [RFC2119] | Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997. |
| [RFC7991] | Hoffman, P., "The "xml2rfc" Version 3 Vocabulary", RFC 7991, DOI 10.17487/RFC7991, December 2016. |
The authors would like to thank the following persons for their valuable advice and input.