Skip to main content

Writing Internet-Drafts And RFCs In AsciiDoc (AsciiRFC)
draft-ribose-asciirfc-01

The information below is for an old version of the document.
Document Type
This is an older version of an Internet-Draft whose latest revision state is "Expired".
Authors Ronald Henry Tse , Nick Nicholas , Jeffrey Lau
Last updated 2017-11-25
RFC stream (None)
Formats
IETF conflict review conflict-review-ribose-asciirfc, conflict-review-ribose-asciirfc, conflict-review-ribose-asciirfc, conflict-review-ribose-asciirfc, conflict-review-ribose-asciirfc, conflict-review-ribose-asciirfc
Additional resources
Stream Stream state (No stream defined)
Consensus boilerplate Unknown
RFC Editor Note (None)
IESG IESG state I-D Exists
Telechat date (None)
Responsible AD (None)
Send notices to (None)
draft-ribose-asciirfc-01
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

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 May 29, 2018.

Tse, et al.               Expires May 29, 2018                  [Page 1]
Internet-Draft           AsciiRFC Specifications           November 2017

Copyright Notice

   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.

Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   3
   2.  Conventions Used in This Document . . . . . . . . . . . . . .   5
     2.1.  Definitions . . . . . . . . . . . . . . . . . . . . . . .   5
   3.  Document Structure And AsciiDoctor Syntax . . . . . . . . . .   5
     3.1.  Simple illustration . . . . . . . . . . . . . . . . . . .   7
   4.  Header And Document Attributes  . . . . . . . . . . . . . . .  15
   5.  Preamble  . . . . . . . . . . . . . . . . . . . . . . . . . .  22
   6.  Sections and Paragraphs . . . . . . . . . . . . . . . . . . .  24
   7.  Figures . . . . . . . . . . . . . . . . . . . . . . . . . . .  25
   8.  Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . .  28
   9.  Blockquotes . . . . . . . . . . . . . . . . . . . . . . . . .  30
   10. Notes And Asides  . . . . . . . . . . . . . . . . . . . . . .  31
   11. Tables  . . . . . . . . . . . . . . . . . . . . . . . . . . .  32
   12. Inline Formatting . . . . . . . . . . . . . . . . . . . . . .  35
   13. Links . . . . . . . . . . . . . . . . . . . . . . . . . . . .  36
   14. Crossreferences . . . . . . . . . . . . . . . . . . . . . . .  36
   15. Inclusions  . . . . . . . . . . . . . . . . . . . . . . . . .  38
   16. Encoding and Entities . . . . . . . . . . . . . . . . . . . .  39
   17. Bibliography  . . . . . . . . . . . . . . . . . . . . . . . .  39
     17.1.  Using Raw RFC XML  . . . . . . . . . . . . . . . . . . .  40
     17.2.  Using preprocessing  . . . . . . . . . . . . . . . . . .  41
   18. RFC XML features not supported in Asciidoctor . . . . . . . .  43
   19. Authoring . . . . . . . . . . . . . . . . . . . . . . . . . .  43
   20. Security Considerations . . . . . . . . . . . . . . . . . . .  44
   21. IANA Considerations . . . . . . . . . . . . . . . . . . . . .  45
   22. Examples  . . . . . . . . . . . . . . . . . . . . . . . . . .  45
     22.1.  Example 1  . . . . . . . . . . . . . . . . . . . . . . .  45
   23. References  . . . . . . . . . . . . . . . . . . . . . . . . .  45
     23.1.  Normative References . . . . . . . . . . . . . . . . . .  45
     23.2.  Informative References . . . . . . . . . . . . . . . . .  45
     23.3.  URIs . . . . . . . . . . . . . . . . . . . . . . . . . .  47

Tse, et al.               Expires May 29, 2018                  [Page 2]
Internet-Draft           AsciiRFC Specifications           November 2017

   Appendix A.  Acknowledgements . . . . . . . . . . . . . . . . . .  47
   Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . .  47

1.  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

Tse, et al.               Expires May 29, 2018                  [Page 3]
Internet-Draft           AsciiRFC Specifications           November 2017

   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.

   Compared to Markdown [1],

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

Tse, et al.               Expires May 29, 2018                  [Page 4]
Internet-Draft           AsciiRFC Specifications           November 2017

2.  Conventions Used in This 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 [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
   [2].  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.

Tse, et al.               Expires May 29, 2018                  [Page 5]
Internet-Draft           AsciiRFC Specifications           November 2017

         +  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:

   o  Text formatting: bold, italic, superscript, subscript, monospace.

   o  Custom markup macros.  (AsciiRFC uses one: "bcp14".)

   o  URLs, including display text.

   o  Inline anchors.

   o  Cross-references to anchors (IDs of blocks or spans of text),
      including display text.

   o  Images, audio, and visual files.  (AsciiRFC only supports images.)

   o  Index terms.

   o  Equations (native support for AsciiMathML [3] and TeX/LaTeX [4],
      via the MathJax [5] tool).  (Not supported in AsciiRFC, since
      there is no RFC XML equivalent.)

   o  Footnotes.  (Not supported in AsciiRFC.)

   The Asciidoctor document structure aligns with the RFC XML v2 and v3
   structure.  In the following, v3 equivalences are given:

   o  Header: "<rfc>" attributes, most "front" elements.

   o  Preamble: "front/abstract" and "front/note".

   o  Sections: "middle/section" elements.

Tse, et al.               Expires May 29, 2018                  [Page 6]
Internet-Draft           AsciiRFC Specifications           November 2017

   o  Sections with "bibliography" style attributes: "back/references"
      elements.

   o  Sections with "appendix" style attributes: "back/section"
      elements.

   o  Paragraphs: "t" elements.

   o  Lists: "ul", "ol", "dl" elements.

   o  Delimited blocks: "artwork", "aside", "blockquote", "figure",
      "note", "sourcecode", "table".

   o  Inline markup: "bcp14", "br", "cref", "em", "eref", "iref",
      "relref", "strong", "sub", "sup", "tt", "xref".

   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.

3.1.  Simple illustration

   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

Tse, et al.               Expires May 29, 2018                  [Page 7]
Internet-Draft           AsciiRFC Specifications           November 2017

: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]

Tse, et al.               Expires May 29, 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
   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

Tse, et al.               Expires May 29, 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"
    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>

Tse, et al.               Expires May 29, 2018                 [Page 10]
Internet-Draft           AsciiRFC Specifications           November 2017

      </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>

Tse, et al.               Expires May 29, 2018                 [Page 11]
Internet-Draft           AsciiRFC Specifications           November 2017

      </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:

<rfc ipr="trust200902" obsoletes="10, 120" updates="2010, 2120"
  category="info" submissionType="IETF"

Tse, et al.               Expires May 29, 2018                 [Page 12]
Internet-Draft           AsciiRFC Specifications           November 2017

  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>

Tse, et al.               Expires May 29, 2018                 [Page 13]
Internet-Draft           AsciiRFC Specifications           November 2017

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

Tse, et al.               Expires May 29, 2018                 [Page 14]
Internet-Draft           AsciiRFC Specifications           November 2017

        <seriesInfo name="RFC" value="7253" />
      </reference>
    </references>
    <section anchor="_addendum" title="Addendum">
      <t>But you try and tell the young people today that&#8230;&#8203;
        and they won't believe ya'.</t>
    </section>
  </back>
</rfc>

4.  Header And Document Attributes

   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.

   o  ":doctype:" determines whether the document will be considered
      "rfc" or "internet-draft", and interprets other attributes
      accordingly.

   o  Certain attributes ("workgroup", "area", "keyword") are comma
      delimited, and result in repeated RFC XML elements.

   The foregoing AsciiRFC renders into RFC XML v3 as:

Tse, et al.               Expires May 29, 2018                 [Page 15]
Internet-Draft           AsciiRFC Specifications           November 2017

  <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

Tse, et al.               Expires May 29, 2018                 [Page 16]
Internet-Draft           AsciiRFC Specifications           November 2017

  <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.:

Tse, et al.               Expires May 29, 2018                 [Page 17]
Internet-Draft           AsciiRFC Specifications           November 2017

   = 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

Tse, et al.               Expires May 29, 2018                 [Page 18]
Internet-Draft           AsciiRFC Specifications           November 2017

   <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:

Tse, et al.               Expires May 29, 2018                 [Page 19]
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
   :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:

   :no-rfc-bold-bcp14: false

      overrides the wrapping by default of boldface uppercase BCP14
      [RFC2119] words (e.g. "*MUST NOT*") 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.

Tse, et al.               Expires May 29, 2018                 [Page 20]
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

   == 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&#8217;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_.

Tse, et al.               Expires May 29, 2018                 [Page 21]
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 May 29, 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 May 29, 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 May 29, 2018                 [Page 24]
Internet-Draft           AsciiRFC Specifications           November 2017

   :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>

7.  Figures

   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:

Tse, et al.               Expires May 29, 2018                 [Page 25]
Internet-Draft           AsciiRFC Specifications           November 2017

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

Tse, et al.               Expires May 29, 2018                 [Page 26]
Internet-Draft           AsciiRFC Specifications           November 2017

   <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 &lt;&lt; "&lt;figure&gt;"
         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>

Tse, et al.               Expires May 29, 2018                 [Page 27]
Internet-Draft           AsciiRFC Specifications           November 2017

8.  Lists

   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 [6].)

   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>

Tse, et al.               Expires May 29, 2018                 [Page 28]
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 May 29, 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 May 29, 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 May 29, 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 May 29, 2018                 [Page 32]
Internet-Draft           AsciiRFC Specifications           November 2017

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

Tse, et al.               Expires May 29, 2018                 [Page 33]
Internet-Draft           AsciiRFC Specifications           November 2017

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

Tse, et al.               Expires May 29, 2018                 [Page 34]
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 <http://asciidoctor.org/docs/user-
   manual/#applying-substitutions>

Tse, et al.               Expires May 29, 2018                 [Page 35]
Internet-Draft           AsciiRFC Specifications           November 2017

13.  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.  Crossreferences

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

Tse, et al.               Expires May 29, 2018                 [Page 36]
Internet-Draft           AsciiRFC Specifications           November 2017

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

Tse, et al.               Expires May 29, 2018                 [Page 37]
Internet-Draft           AsciiRFC Specifications           November 2017

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

15.  Inclusions

   The Asciidoctor "include" directive [7] 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:

Tse, et al.               Expires May 29, 2018                 [Page 38]
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
   <http://xml.resource.org/public/rfc/bibxml/> ; so it would be

Tse, et al.               Expires May 29, 2018                 [Page 39]
Internet-Draft           AsciiRFC Specifications           November 2017

   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 May 29, 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, asciidoc-
   bibliography [8], 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

Tse, et al.               Expires May 29, 2018                 [Page 41]
Internet-Draft           AsciiRFC Specifications           November 2017

           source; e.g.  <http://xml.resource.org/public/rfc/bibxml/
           reference.RFC.2119.xml>

       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 <http://xml.resource.org/public/rfc/bibxml/> 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'/>"]"

Tse, et al.               Expires May 29, 2018                 [Page 42]
Internet-Draft           AsciiRFC Specifications           November 2017

   6.  Normative and Informative References are inserted in the document
       through a macro, which occurs where the RFC XML references would
       be inserted:

   [bibliography]
   == Normative References

   ++++
   bibliography::norm[]
   ++++

   [bibliography]
   == Informative References

   ++++
   bibliography::info[]
   ++++

18.  RFC XML features not supported in Asciidoctor

   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   | Not added by the    |
   |                        | converter          | converter           |
   | "iref@primary"         | N                  | N                   |
   | "reference" (and all   | As Raw XML         | As Raw XML          |
   | children)              |                    |                     |
   | "table/preamble"       | Deprecated         | N                   |
   | "table/postamble"      | Deprecated         | N                   |
   | "artwork@width"        | Only on images     | Only on images      |
   | "artwork@height"       | Only on images     | Only on images      |
   +------------------------+--------------------+---------------------+

19.  Authoring

   To author an AsciiRFC document, you should familiarise yourself with
   the Asciidoctor specification [9].  The converter Ruby gem source
   code distribution also has samples of individual RFC XML features
   [10], in v2 and v3, and examples of self-standing AsciiRFC documents
   [11], along with their RFC XML renderings.  (This includes round-
   tripped RFC XML documents.)

Tse, et al.               Expires May 29, 2018                 [Page 43]
Internet-Draft           AsciiRFC Specifications           November 2017

   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.

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 document.

Tse, et al.               Expires May 29, 2018                 [Page 44]
Internet-Draft           AsciiRFC Specifications           November 2017

   o  An AsciiRFC generator may cause errors in textual rendering or
      link generation that may lead to security issues.

   o  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.

21.  IANA Considerations

   This document does not require any action by IANA.

22.  Examples

22.1.  Example 1

   TODO.

23.  References

23.1.  Normative References

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119,
              DOI 10.17487/RFC2119, March 1997,
              <https://www.rfc-editor.org/info/rfc2119>.

   [RFC7991]  Hoffman, P., "The "xml2rfc" Version 3 Vocabulary",
              RFC 7991, DOI 10.17487/RFC7991, December 2016,
              <https://www.rfc-editor.org/info/rfc7991>.

23.2.  Informative References

   [AsciiDoc]
              Rackham, S., "AsciiDoc: Text based document generation",
              November 2013, <http://www.methods.co.nz/asciidoc/>.

   [Asciidoctor]
              Allen, D., Waldron, R., and S. White, "Asciidoctor: A fast
              text processor & publishing toolchain for converting
              AsciiDoc to HTML5, DocBook & more.", November 2017,
              <http://asciidoctor.org>.

   [draftr]   Barnes, R., "draftr: an HTML front-end to pandoc2rfc", Nov
              2017, <https://ipv.sx/draftr/>.

Tse, et al.               Expires May 29, 2018                 [Page 45]
Internet-Draft           AsciiRFC Specifications           November 2017

   [kramdown-rfc2629]
              Bormann, C., "kramdown-rfc2629: An RFC2629 (XML2RFC)
              backend for Thomas Leitner's kramdown markdown parser",
              Nov 2017, <https://github.com/cabo/kramdown-rfc2629>.

   [lyx2rfc]  Williams, N., "LyX to I-D/RFC export by way of Lyx export
              to XHTML and XSLT conversion to xml2rfc schema", 2014,
              <https://github.com/nicowilliams/lyx2rfc>.

   [mmark]    Gieben, R., "Using mmark to create I-Ds and RFCs", June
              2015, <https://github.com/miekg/mmark>.

   [NroffEdit]
              Santesson, S., "WYSIWYG Internet-Draft Nroff Editor", May
              2011, <http://aaa-sec.com/nroffedit/>.

   [pandoc2rfc]
              Gieben, R., "pandoc2rfc: Use pandoc to create XML suitable
              for xml2rfc", 2012, <https://github.com/miekg/pandoc2rfc>.

   [RFC5385]  Touch, J., "Version 2.0 Microsoft Word Template for
              Creating Internet Drafts and RFCs", RFC 5385,
              DOI 10.17487/RFC5385, February 2010,
              <https://www.rfc-editor.org/info/rfc5385>.

   [RFC7328]  Gieben, R., "Writing I-Ds and RFCs Using Pandoc and a Bit
              of XML", RFC 7328, DOI 10.17487/RFC7328, August 2014,
              <https://www.rfc-editor.org/info/rfc7328>.

   [RFC7749]  Reschke, J., "The "xml2rfc" Version 2 Vocabulary",
              RFC 7749, DOI 10.17487/RFC7749, February 2016,
              <https://www.rfc-editor.org/info/rfc7749>.

   [RFC7763]  Leonard, S., "The text/markdown Media Type", RFC 7763,
              DOI 10.17487/RFC7763, March 2016,
              <https://www.rfc-editor.org/info/rfc7763>.

   [RFC7764]  Leonard, S., "Guidance on Markdown: Design Philosophies,
              Stability Strategies, and Select Registrations", RFC 7764,
              DOI 10.17487/RFC7764, March 2016,
              <https://www.rfc-editor.org/info/rfc7764>.

   [RFC7990]  Flanagan, H., "RFC Format Framework", RFC 7990,
              DOI 10.17487/RFC7990, December 2016,
              <https://www.rfc-editor.org/info/rfc7990>.

Tse, et al.               Expires May 29, 2018                 [Page 46]
Internet-Draft           AsciiRFC Specifications           November 2017

23.3.  URIs

   [1] http://asciidoctor.org/docs/user-manual/#compared-to-markdown

   [2] http://asciidoctor.org/docs/user-manual/#compared-to-markdown

   [3] http://docs.mathjax.org/en/latest/asciimath.html

   [4] http://docs.mathjax.org/en/latest/tex.html

   [5] https://www.mathjax.org

   [6] http://asciidoctor.org/docs/user-manual/#complex-list-content

   [7] http://asciidoctor.org/docs/user-manual/#include-directive

   [8] https://github.com/riboseinc/asciidoctor-bibliography

   [9] http://asciidoctor.org/docs/user-manual

   [10] https://github.com/riboseinc/asciidoctor-
        rfc/tree/master/spec/asciidoctor/rfc

   [11] https://github.com/riboseinc/asciidoctor-rfc/tree/master/spec/
        examples

Appendix A.  Acknowledgements

   The authors would like to thank the following persons for their
   valuable advice and input.

   o  TODO.

Authors' Addresses

   Ronald Henry Tse
   Ribose
   Suite 1111, 1 Pedder Street
   Central, Hong Kong
   Hong Kong

   Email: ronald.tse@ribose.com
   URI:   https://www.ribose.com

Tse, et al.               Expires May 29, 2018                 [Page 47]
Internet-Draft           AsciiRFC Specifications           November 2017

   Nick Nicholas
   Ribose
   Australia

   Email: nick.nicholas@ribose.com
   URI:   https://www.ribose.com

   Jeffrey Lau
   Ribose
   Suite 1111, 1 Pedder Street
   Central, Hong Kong
   Hong Kong

   Email: jeffrey.lau@ribose.com
   URI:   https://www.ribose.com

   Paolo Brasolin
   Ribose
   Italy

   Email: paolo.brasolin@ribose.com
   URI:   https://www.ribose.com

Tse, et al.               Expires May 29, 2018                 [Page 48]