[Docs] [txt|pdf|xml|html] [Tracker] [Email] [Nits]

Versions: 00 01 02 03 04 05 06 07 08 Draft is active
In: Author-wait
Network Working Group                                             R. Tse
Internet-Draft                                               N. Nicholas
Intended status: Informational                                    J. Lau
Expires: May 24, 2018                                        P. Brasolin
                                                                  Ribose
                                                       November 20, 2017


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

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 24, 2018.






Tse, et al.               Expires May 24, 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 . . . . . . . . . . . . . .   4
     2.1.  Definitions . . . . . . . . . . . . . . . . . . . . . . .   4
   3.  Document Structure And AsciiDoctor Syntax . . . . . . . . . .   4
   4.  Header And Document Attributes  . . . . . . . . . . . . . . .   6
   5.  Preamble  . . . . . . . . . . . . . . . . . . . . . . . . . .   9
   6.  Sections and Paragraphs . . . . . . . . . . . . . . . . . . .  11
   7.  Figures . . . . . . . . . . . . . . . . . . . . . . . . . . .  11
   8.  Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . .  12
   9.  Blockquotes . . . . . . . . . . . . . . . . . . . . . . . . .  15
   10. Notes And Asides  . . . . . . . . . . . . . . . . . . . . . .  16
   11. Tables  . . . . . . . . . . . . . . . . . . . . . . . . . . .  17
   12. Inline Formatting . . . . . . . . . . . . . . . . . . . . . .  20
   13. Links . . . . . . . . . . . . . . . . . . . . . . . . . . . .  20
   14. Crossreferences . . . . . . . . . . . . . . . . . . . . . . .  21
   15. Inclusions  . . . . . . . . . . . . . . . . . . . . . . . . .  23
   16. Encoding and Entities . . . . . . . . . . . . . . . . . . . .  23
   17. Bibliography  . . . . . . . . . . . . . . . . . . . . . . . .  23
     17.1.  Using Raw RFC XML  . . . . . . . . . . . . . . . . . . .  24
     17.2.  Using preprocessing  . . . . . . . . . . . . . . . . . .  25
   18. RFC XML features not supported in Asciidoctor . . . . . . . .  27
   19. Authoring . . . . . . . . . . . . . . . . . . . . . . . . . .  27
   20. Security Considerations . . . . . . . . . . . . . . . . . . .  28
   21. IANA Considerations . . . . . . . . . . . . . . . . . . . . .  28
   22. Examples  . . . . . . . . . . . . . . . . . . . . . . . . . .  29
     22.1.  Example 1  . . . . . . . . . . . . . . . . . . . . . . .  29
   23. References  . . . . . . . . . . . . . . . . . . . . . . . . .  29
     23.1.  Normative References . . . . . . . . . . . . . . . . . .  29
     23.2.  Informative References . . . . . . . . . . . . . . . . .  29
     23.3.  URIs . . . . . . . . . . . . . . . . . . . . . . . . . .  30
   Appendix A.  Acknowledgements . . . . . . . . . . . . . . . . . .  30



Tse, et al.               Expires May 24, 2018                  [Page 2]


Internet-Draft           AsciiRFC Specifications           November 2017


   Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . .  30

1.  Introduction

   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.

   The transition to RFC XML v3 places added onus on authors to generate
   compliant XML.  This need is already met for RFC XML v2 [RFC7749] by
   tools such as MMark [1] and Kramdown [2], both based on the popular
   Markdown markup language [3] [RFC7763] [RFC7764].

   Asciidoctor [4] is an alternative markup language to Markdown, with
   features that make it attractive as a markup language for RFC with
   XML output.

   Compared to Markdown [5],

   o  Asciidoctor was designed from the beginning as a publishing
      language: it was initially intended as a plain-text alternative to
      the DocBook XML schema.  For that reason, Asciidoctor natively
      supports the full range of formatting required by RFC XML
      (including notes, tables, bibliographies, source-code blocks, and
      definition lists), without resorting to embedded HTML or Markdown
      "flavours".

   o  Asciidoctor is extensible, with a well-defined API.

   o  Asciidoctor allows granular control of rendering, including user-
      specified attribute of text blocks.

   o  Asciidoctor allows document inclusion, for managing large-scale
      documentation projects.

   o  Asciidoctor 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, Asciidoctor is well-
      suited to generating XML that needs to conform to a specified
      schema.

   Section 1.2 of [RFC7764] famously states that "there is no such thing
   as "invalid" Markdown, there is no standard demanding adherence to



Tse, et al.               Expires May 24, 2018                  [Page 3]


Internet-Draft           AsciiRFC Specifications           November 2017


   the Markdown syntax, and there is no governing body that guides or
   impedes its development."  While there are contexts where that lack
   of rigour is helpful, the authoring of RFCs does have a standard and
   a governing body, and there is such a thing as invalid RFC XML.  A
   more rigorous counterpart to Markdown, which still preserves its
   basic approach to formatting, is useful in generating RFC XML that
   encompasses a fuller subset of the specification, and preempting
   malformed RFC XML output.

   As with Markdown, there is a wide range of tools that can render
   Asciidoctor; so Asciidoctor drafts of RFC documents can be previewed
   and accessed without depending on the RFC tools ecosystem.  Our
   porting of RFC XML to Asciidoctor has aimed to ensure that, as much
   as possible, the Asciidoctor being used for RFC is generic
   Asciidoctor, which can be processed by Asciidoctor tools in general.
   (The only exception to this as an add-on is the optional bibliography
   module, which allows bibliographies to be assembled on the fly based
   on citations in a document.)

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

   TODO.

3.  Document Structure And AsciiDoctor Syntax

   The syntax of Asciidoctor is presented in the Asciidoctor user manual
   [6].

   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



Tse, et al.               Expires May 24, 2018                  [Page 4]


Internet-Draft           AsciiRFC Specifications           November 2017


      *  Blocks of text.  Blocks can have metadata (including a title,
         an anchor for cross-references, and attributes.)  Blocks can
         be:

         +  Paragraphs, which are terminated by blank lines.

         +  Lists.  List items are by default paragraphs, but can span
            over multiple paragraphs.

         +  Delimited blocks (with a line delimiter on either side of
            them); these include tables, notes, sidebars, source code,
            block quotes, examples, and unprocessed content (e.g. raw
            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

   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

   o  Index terms

   o  Equations (native support for AsciiMathML [7] and TeX/LaTeX [8],
      via the MathJax [9] tool

   o  Footnotes





Tse, et al.               Expires May 24, 2018                  [Page 5]


Internet-Draft           AsciiRFC Specifications           November 2017


   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

   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 Asciidoctor elements to RFC XML v2 and
   v3 elements, and of how to convert Asciidoctor 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 Asciidoctor, with some pitfalls to
   be aware of.  Illustrations are in RFC XML v3, although the converter
   deals with both versions of RFC XML.

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:











Tse, et al.               Expires May 24, 2018                  [Page 6]


Internet-Draft           AsciiRFC Specifications           November 2017


   = Transmission of IP Datagrams on Avian Carriers
   David Waitzman <dwaitzman@BBN.COM>
   :doctype: internet-draft
   :abbrev: IP Datagrams on Avian Carriers
   :obsoletes: 10, 120
   :updates: 2010, 2120
   :status: informational
   :name: internet-draft-avian-transmission-00
   :ipr: trust200902
   :area: Internet
   :workgroup: Network Working Group
   :keyword: avians, datagrams
   :revdate: 1990-04-01T00:00:00Z
   :organization: BBN STC
   :phone: (617) 873-4323
   :uri: http://bbn.com
   :street: 10 Moulton Street
   :city: Cambridge
   :code: MA 02238
   :rfcedstyle: yes
   :text-list-symbols: yes
   :rfc2629xslt: true

   The document attributes are used to populate "rfc" attributes,
   "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.

   o  A few attributes are specific to the operation of the RFC XML
      document converter:

      *  ":no-rfc-bold-bcp14: false" overrides the conversion of
         boldface uppercase BCP14 [RFC2119] words with the "bcp14"
         element.

      *  ":smart-quotes false:" overrides Asciidoctor's conversion of
         straight quotes and apostrophes to smart quotes and
         apostrophes.

      *  ":inline-definition-lists: true" overrides the RFC XML v2
         "idnits" requirement that a blank line be inserted between a
         definition list term and its definition.




Tse, et al.               Expires May 24, 2018                  [Page 7]


Internet-Draft           AsciiRFC Specifications           November 2017


   The foregoing Asciidoc renders into RFC XML v3 as:

 <?xml version="1.0" encoding="US-ASCII"?>
 <?xml-stylesheet type="text/xsl" href="rfc2629.xslt"?>
 <!DOCTYPE rfc SYSTEM "rfc2629.dtd">
 <?rfc rfcedstyle="yes"?>
 <?rfc text-list-symbols="yes"?>
 <?rfc strict="yes"?>
 <?rfc compact="yes"?>
 <?rfc subcompact="no"?>
 <?rfc toc="yes"?>
 <?rfc tocdepth="4"?>
 <?rfc symrefs="yes"?>
 <?rfc sortrefs="yes"?>
 <rfc ipr="trust200902" obsoletes="10, 120" updates="2010, 2120"
   submissiontype="IETF" preptime="2017-11-18T01:52:35Z" version="3">
     <front>
         <title abbrev="IP Datagrams on Avian Carriers">
             A Standard for the Transmission of IP
             Datagrams on Avian Carriers
         </title>
         <seriesinfo name="Internet-Draft" status="informational"
           stream="IETF" value="internet-draft-avian-transmission-00" />
         <author fullname="David Waitzman" surname="Waitzman">
             <organization>BBN STC</organization>
             <address>
                 <postal>
                     <street>10 Moulton Street</street>
                     <city>Cambridge</city>
                     <code>MA 02238</code>
                 </postal>
                 <phone>(617) 873-4323</phone>
                 <email>dwaitzman@BBN.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>avians</keyword>
         <keyword>datagrams</keyword>

   Details of a second, third etc. author, including their organization
   and contact details, are provided by suffixing the author attribute
   with "_2", "_3" etc.:






Tse, et al.               Expires May 24, 2018                  [Page 8]


Internet-Draft           AsciiRFC Specifications           November 2017


   John Doe Horton <john.doe@email.com>;
     Billy Bob Thornton <billy.thornton@email.com>
   :fullname: John Doe Horton
   :lastname: Horton
   :forename_initials: J. D.
   :role: editor
   :organization: Ribose
   :fax: 555 5555
   :email: john.doe@email.com
   :uri: http://example.com
   :phone: 555 5655
   :street: 57 Mt Pleasant St
   :city: Dullsville
   :region: NSW
   :country: Australia
   :code: 3333
   :fullname_2: Billy Bob Thornton
   :lastname_2: Thornton
   :forename_initials_2: B. B.
   :role_2: editor
   :organization_2: IBM
   :fax_2: 555 6666
   :email_2: billy.thornton@email.com
   :uri_2: http://ibm.com
   :phone_2: 555 6655
   :street_2: 67 Mt Pleasant St
   :city_2: Dulltown
   :region_2: VIC
   :country_2: UK
   :code_2: 44444

   The initial author attribution in Asciidoctor, e.g.  "John Doe
   Horton<john.doe@email.com>; Billy Bob Thornton
   <billy.thornton@email.com>" in the example above, expects a strict
   format of First Name, zero or more Middle Names, Last name, and
   cannot process honorifics like "Dr" or suffixes like "Jr".  Name
   attributes with any degree of complexity should be overriden by using
   the ":fullname:" and ":lastname:" attributes.  The
   ":forename_initials:" replaces the built-in ":initials:" attribute
   (which includes the surname initial), and is not automatically
   populated from the name attribution.

5.  Preamble

   The preamble in Asciidoctor is the text between the end of the
   document header (which terminates with a blank line) and the first
   section of text.  Any paragraphs of text in the preamble are treated
   as an abstract, and may optionally be tagged with the "abstract"



Tse, et al.               Expires May 24, 2018                  [Page 9]


Internet-Draft           AsciiRFC Specifications           November 2017


   style attribute.  Any notes in the preamble are treated as a "note"
   element.  For example:

   = A Standard for the Transmission of IP Datagrams on Avian Carriers
   David Waitzman <dwaitzman@BBN.COM>
   :doctype: internet-draft
   :abbrev: IP Datagrams on Avian Carriers
   :status: informational
   :name: internet-draft-avian-transmission-00

   Preamble content.

   More Preamble content.

   NOTE: This is a note.

   [NOTE]
   .Title of Note
   ====
   This is another note.
   ====

<rfc submissionType="IETF" prepTime="2017-11-18T02:55:47Z" version="3">
<front>
  <title abbrev="IP Datagrams on Avian Carriers">
    A Standard for the Transmission of IP Datagrams on Avian Carriers
  </title>
  <seriesInfo name="Internet-Draft" status="informational" stream="IETF"
  value="internet-draft-avian-transmission-00"/>
  <author fullname="David Waitzman" surname="Waitzman">
    <address>
      <email>dwaitzman@BBN.COM</email>
    </address>
  </author>
  <date day="18" month="November" year="2017"/>

  <abstract><t>Preamble content.</t>
    <t>More Preamble content.</t>
  </abstract>
  <note>
    <t>This is a note.</t>
  </note>
  <note>
    <name>Title of Note</name>
    <t>This is another note.</t>
  </note>
</front>




Tse, et al.               Expires May 24, 2018                 [Page 10]


Internet-Draft           AsciiRFC Specifications           November 2017


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)

   :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

   AsciiDoc Examples (corresponding to RFC XML figures), source code
   listings, and literals (preformatted text) are all delimited blocks.
   Listings and literals can occur nested within examples.  If an
   Asciidoctor listing or literal occurs outside of an example, the RFC
   XML converter will supply the surrounding figure element:




Tse, et al.               Expires May 24, 2018                 [Page 11]


Internet-Draft           AsciiRFC Specifications           November 2017


   .Figure 1
   ====
   .figure1.txt
   ....
   Figures are only permitted to contain listings
   (sourcecode), images (artwork), or literal (artwork)
   ....

   [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)
     </artwork>
     <sourcecode type="ruby">
       def listing(node)
         result = []
         if node.parent.context != :example
           result &lt;&lt; "&lt;figure&gt;"
         end
       end
     </sourcecode>
   </figure>

8.  Lists

   Asciidoctor supports ordered, unordered, and definition lists.
   Indentation of ordered and unordered lists is indicated by repeating
   the list item prefix ("*" and "." respectively.)  List attributes
   specify the type of symbol used for ordered lists:










Tse, et al.               Expires May 24, 2018                 [Page 12]


Internet-Draft           AsciiRFC Specifications           November 2017


   [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 (Asciidoc list
   continuation [10].)

   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>

   List continuations can also be embed to populate a list item with a
   sequence of blocks as a unit (in an Asciidoc open block):







Tse, et al.               Expires May 24, 2018                 [Page 13]


Internet-Draft           AsciiRFC Specifications           November 2017


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

   Asciidoctor considers paragraphs to be the basic level of blocks, and
   does not permit lists to be nested within them: text after a list is
   considered to be a new paragraph.  So markup like the following
   cannot be generated via Asciidoctor:














Tse, et al.               Expires May 24, 2018                 [Page 14]


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>
               <figure>
                   <artwork type="ascii-art">
                       Literal
                   </artwork>
               </figure>
               <t>Note 3.</t>
           </li>
       </ul>

9.  Blockquotes

   Asciidoctor supports blockquotes and quotations of verse; its block
   quotations permit arbitrary levels of quote nesting.  RFC XML v3 only
   supports one level of blockquotes.  RFC XML v3 does not support line
   breaks outside of tables, so verse quotations are converted to prose.

   [quote,attribution="Monty Python",citetitle="http://foo.bar"]
   ____
   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 24, 2018                 [Page 15]


Internet-Draft           AsciiRFC Specifications           November 2017


   <blockquote quotedfrom="Monty Python" cite="http://foo.bar">
     <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 converted to "note" elements in the document
   preamble, and "cref" documents in the main document.  RFC XML v3 also
   supports asides (Asciidoctor sidebars):

   == Section 1
   [NOTE,source=GBS]
   .Note Title
   ====
   Any admonition inside the body of the text is a comment.
   ====

   ****
   Sidebar

   Another sidebar

   * This is a list

   ....
   And this is ascii-art
   ....
   ****






Tse, et al.               Expires May 24, 2018                 [Page 16]


Internet-Draft           AsciiRFC Specifications           November 2017


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

   Note that no inline formatting is permitted in RFC XML v2, and it is
   stripped for v2 by the converter.

   Because paragraphs in Asciidoctor cannot contain any other blocks, a
   comment at the end of a paragraph is treated as a new block.  In the
   document converter, any such comments are moved inside the preceding
   RFC XML paragraph; if the comment is at the start of a section, as in
   the example above, it is wrapped inside a paragraph.

   While Asciidoctor has comments proper, notated with initial "//",
   they are ignore by the document converter, so they will not appear as
   XML comments in the converter output.

11.  Tables

   Asciidoctor tables, like RFC XML v3, support distinct table heads,
   bodies and feet, cells spanning multiple rows and columns, and
   horizontal alignment.  The larger range of formatting options
   available in RFC XML v2 is also supported.












Tse, et al.               Expires May 24, 2018                 [Page 17]


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 24, 2018                 [Page 18]


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 24, 2018                 [Page 19]


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, Asciidoctor 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 Asciidoctor either by tagging them with a custom formatting
   span ("bcp14#mustnot#"), or by converting by default BCP14 boldface
   all-caps words:

   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 "<spanx style="strong">" and "__", need
   to be escaped with double backslash("\\</spanx>").  Escaping
   delimiters is not always reliable, and for double delimiters it is
   preferable to use HTML entities ("&#42;&#42;"), or attribute
   references:

   :dblast: **

   `{dblast}`

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:




Tse, et al.               Expires May 24, 2018                 [Page 20]


Internet-Draft           AsciiRFC Specifications           November 2017


   http://example.com/[linktext]

   <t><eref target="http://example.com/">linktext</eref></t>

   To prevent hyperlinking of a URL, prefix it with a backslash.

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"">".  Asciidoctor
   does not otherwise support attributes on cross-references, but the
   converter extracts format information from templated text within
   cross-references: "format=x:text" populates the "xref@format"
   attribute, while a section number followed by one of the words "of,
   parens, bare, text" is treated as a "relref" reference to an external
   document.

   [[crossreference]]
   == Section 1

   == Section 2
   See <<crossreference>>.

   == Section 3
   See <<crossreference,text>>

   == 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="crossreference" numbered="false">
     <name>Section 1</name>
   </section>



Tse, et al.               Expires May 24, 2018                 [Page 21]


Internet-Draft           AsciiRFC Specifications           November 2017


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



Tse, et al.               Expires May 24, 2018                 [Page 22]


Internet-Draft           AsciiRFC Specifications           November 2017


     </t>
   </section>

15.  Inclusions

   The Asciidoctor "include" directive [11] is used to include external
   files in a master Asciidoctor document.  The directive is capable of
   sophisticated document merging, including adjusting the heading
   levels of the included text, selecting text within specified tags or
   line numbers to be included, and adjusting the indentation of code
   snippets in merged text:

   \include::path[
     leveloffset=_offset_,
     lines=_ranges_,
     tag(s)=_name(s)_,
     indent=_depth_
   ]

16.  Encoding and Entities

   XML accepted the full range of characters in the world's languages
   through UTF-8 character encoding, and one of the motivations for the
   move from plain text to RFC XML has been to allow non-ASCII
   characters to be included in RFCs.  However, current RFC XML v2 tools
   still do not support UTF-8, and other tool support for UTF-8 also
   remains patchy.  Out of an abundance of caution, the RFC XML
   converter uses US-ASCII for its character encoding, and renders any
   non-ASCII characters as entities.

   The converter accepts HTML entities in Asciidoctor, even though they
   are not part of the XML specification; HTML entities such as "&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.

17.  Bibliography

   Asciidoctor has a simple encoding of bibliographies, but it is not
   adequate for the complexity of bibliographic markup supported in RFC
   XML.  RFC documents overwhelmingly cite other RFC documents, and
   canonical RFC XML bibliographic entries are available at
   <http://xml.resource.org/public/rfc/bibxml/> ; so it would be
   inefficient to encode those entries in Asciidoctor, only to have them
   converted back to RFC XML.





Tse, et al.               Expires May 24, 2018                 [Page 23]


Internet-Draft           AsciiRFC Specifications           November 2017


   The converter provides two means of incorporating bibliographies into
   RFC documents authored in Asciidoctor:

   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, bibliographic citations are handled like all other
   cross-references.  The bibliographic entries for normative and
   informative references are given in the Asciidoctor as passthrough
   blocks, which contain the raw RFC XML for all references; document
   conversion leaves the raw RFC XML in place.  This approach requires
   authors to maintain the normative and informative bibliographies
   within the document, to update them as citations are added and
   removed, and to sort them manually.

   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 24, 2018                 [Page 24]


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 [12], to import citations into the Asciidoctor document
   from an external file of references.

   The references file consists of RFC XML reference entries, and still
   needs to be managed manually; however the bibliographies are
   assembled from that file, sorted, and inserted into the normative and
   informative references in preprocessing.  Citations in the document
   itself are given as macros to be interpreted by the preprocessor;
   this allows them to be split into normative and informative
   references.  (The MMark tool likewise splits reference citations into
   normative and informative.)

   Integration with the asciidoc-bibliography gem proceeds as follows:

   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 24, 2018                 [Page 25]


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.  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[]
   ++++







Tse, et al.               Expires May 24, 2018                 [Page 26]


Internet-Draft           AsciiRFC Specifications           November 2017


18.  RFC XML features not supported in Asciidoctor

   The following features of RFC XML are not supported by the
   Asciidoctor converter, and would need to be adjusted manually:

   +----------------------------+-----------------------+--------------+
   | RFC XML element            | RFC XML v3            | RFC XML v2   |
   +----------------------------+-----------------------+--------------+
   | "front/boilerplate"        | Not added by the      | N/A          |
   |                            | 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 Asciidoctor RFC document, you should familiarise
   yourself with the Asciidoctor specification [13].  The converter Ruby
   gem source code distribution also has samples of individual RFC XML
   features [14], in v2 and v3, and examples of self-standing
   Asciidoctor RFC XML documents [15], along with their RFC XML
   renderings.  (This includes round-tripped RFC XML documents.)

   In addition, you can clone the sample "rfc-in-asciidoc-template"
   repository as a template, and populate it for your AsciiDoc RFCs and
   Internet-Drafts:

   $ git clone https://github.com/riboseinc/rfc-in-asciidoc-template

   Converting your AsciiDoc 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:










Tse, et al.               Expires May 24, 2018                 [Page 27]


Internet-Draft           AsciiRFC Specifications           November 2017


  $ git clone https://github.com/riboseinc/asciidoctor-rfc.git
  $ 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 Asciidoctor content, you should iterate through running
   the Asciidoctor conversion frequently, to ensure that you are still
   generating valid XML through your markup.  The converter makes an
   effort to ensure that its XML output is valid, and it issues warnings
   about likely issues; it also validates its own XML output against the
   Asciidoctor schema, and reports errors in the XML output in the
   following format:

   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 Asciidoctor does not
   conform with the intended RFC XML (e.g. lists embedded in
   paragraphs), or because RFC XML features are required that are not
   supported within Asciidoctor.

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.

   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.






Tse, et al.               Expires May 24, 2018                 [Page 28]


Internet-Draft           AsciiRFC Specifications           November 2017


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

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

   [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

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

   [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 24, 2018                 [Page 29]


Internet-Draft           AsciiRFC Specifications           November 2017


23.3.  URIs

   [1] https://github.com/miekg/mmark

   [2] https://github.com/cabo/kramdown-rfc2629

   [3] https://daringfireball.net/projects/markdown/

   [4] http://asciidoctor.org

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

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

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

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

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

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

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

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

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

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

   [15] 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









Tse, et al.               Expires May 24, 2018                 [Page 30]


Internet-Draft           AsciiRFC Specifications           November 2017


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

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


   Nick Nicholas
   Ribose
   Australia

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


   Paolo Brasolin
   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 24, 2018                 [Page 31]


Html markup produced by rfcmarkup 1.129b, available from https://tools.ietf.org/tools/rfcmarkup/