asciidoctor-rfc 0.1.0 → 0.2.0

data/.travis.yml

@@ -1,5 +1,6 @@
 sudo: false
 language: ruby
 rvm:
-  - 2.4.1
-before_install: gem install bundler -v 1.15.1
+  - 2.3
+script:
+  - bundle exec rspec

data/Guardfile

@@ -0,0 +1,22 @@
+directories(%w(. lib spec)).
+  select { |d| Dir.exists?(d) ? d : UI.warning("Directory #{d} does not exist") }
+
+guard :rspec, cmd: "bundle exec rspec" do
+  require "guard/rspec/dsl"
+  dsl = Guard::RSpec::Dsl.new(self)
+
+  # Feel free to open issues for suggestions and improvements
+
+  # RSpec files
+  rspec = dsl.rspec
+  watch(rspec.spec_helper) { rspec.spec_dir }
+  watch(rspec.spec_support) { rspec.spec_dir }
+  watch(rspec.spec_files)
+
+  # Ruby files
+  ruby = dsl.ruby
+  dsl.watch_spec_files_for(ruby.lib_files)
+
+  # Run all specs if any lib file changes.
+  watch(ruby.lib_files) { rspec.spec_dir }
+end

data/README.adoc

@@ -0,0 +1,1151 @@
+= Writing Internet-Drafts and RFCs in AsciiDoc
+:source-highlighter: coderay
+:icons: font
+
+asciidoctor-rfc lets you write Internet-Drafts and RFCs in AsciiDoc, the
+"`http://asciidoctor.org/[asciidoctor]-way`".
+
+image:https://img.shields.io/gem/v/asciidoctor-rfc.svg["Gem Version", link="https://rubygems.org/gems/asciidoctor-rfc"]
+image:https://img.shields.io/travis/riboseinc/asciidoctor-rfc/master.svg["Build Status", link="https://travis-ci.org/riboseinc/asciidoctor-rfc"]
+image:https://codeclimate.com/github/riboseinc/asciidoctor-rfc/badges/gpa.svg["Code Climate", link="https://codeclimate.com/github/riboseinc/asciidoctor-rfc"]
+
+
+== Introduction
+
+The "`xml2rfc`" Vocabulary (hereinafter "`RFC XML`") is an XML-based language
+used for writing
+https://www.ietf.org/id-info/guidelines.html[Internet-Drafts]
+and https://tools.ietf.org/html/rfc7322[RFCs (RFC7322)].
+
+This gem allows you to author these types of documents in AsciiDoc, and outputs
+RFC XML output in both v3 and v2 formats:
+
+* v3 RFC XML (https://tools.ietf.org/html/rfc7991[RFC 7991])
+* v2 RFC XML (https://tools.ietf.org/html/rfc7749[RFC 7749])
+
+Its syntax is designed to be "`native-asciidoctor`":
+
+
+== Installation
+
+Add this line to your application's Gemfile:
+
+[source,ruby]
+----
+gem "asciidoctor-rfc"
+----
+
+And then execute:
+
+[source,console]
+----
+$ bundle
+----
+
+Or install it yourself as:
+
+[source,console]
+----
+$ gem install asciidoctor-rfc
+----
+
+
+== Quick Start
+
+Illustrating with v2 RFC XML, and Internet Draft rather than RFC
+
+[source,asciidoc]
+----
+=  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
+:obsoletes: 10, 120
+:updates: 2010, 2120
+:status: info
+: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
+
+[abstract]
+Avian carriers can provide high delay, low throughput, and low
+altitude service.  The connection topology is limited to a single
+point-to-point path for each carrier, used with standard carriers,
+but many carriers can be used without significant interference with
+each other, outside of early spring.  This is because of the 3D ether
+space available to the carriers, in contrast to the 1D ether used by
+IEEE802.3.  The carriers have an intrinsic collision avoidance
+system, which increases availability.  Unlike some network
+technologies, such as packet radio, communication is not limited to
+line-of-sight distance.  Connection oriented service is available in
+some cities, usually based upon a central hub topology. 
+
+NOTE: Yes, this is an April Fool's RFC.
+
+[[frame]]
+== Frame Format
+
+The IP _datagram_ is *printed*, on a small scroll of paper, in
+hexadecimal, with each octet separated by whitestuff and blackstuff.
+The scroll of paper is wrapped around one leg of the avian carrier.
+A band of duct tape is used to secure the datagram's edges.  The
+bandwidth is limited to the leg length.  The MTU is variable, and
+paradoxically, generally increases with increased carrier age.  A
+typical MTU is 256 milligrams.  Some datagram padding may be needed.<<RFC7253>>
+
+[bibliography]
+== 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>
+++++
+----
+
+== Usage
+
+Converting your AsciiDoc to RFC XML is a simple as running the appropriate
+`./bin/asciidoctor-rfc` script using Ruby, and passing our
+AsciiDoc document file as the first argument.
+
+[source,console]
+----
+$ ruby ./bin/asciidoctor-rfc3 draft-example-00.adoc  # RFC XML v3 output
+$ ruby ./bin/asciidoctor-rfc2 draft-example-00.adoc  # RFC XML v2 output
+## WIP: bundle exec asciidoctor -b asciidoctor-rfc3 draft-example-00.adoc # RFC XML v3 output
+## WIP: bundle exec asciidoctor -b asciidoctor-rfc2 draft-example-00.adoc # RFC XML v2 output
+----
+
+You can also use the asciidoctor executable, specifying this gem as a library:
+
+[source,console]
+----
+$ asciidoctor -b rfc3 -r 'asciidoctor/rfc' a.adoc  # RFC XML v3 output
+$ asciidoctor -b rfc2 -r 'asciidoctor/rfc' a.adoc  # RFC XML v2 output
+----
+
+When the script completes, you should see the RFC XML file `draft-example-00.xml` in the
+same directory.
+
+
+== Syntax
+
+The converter follows native AsciiDoc/asciidoctor syntax as much as possible,
+including built-in attributes and styles.
+
+Extension commands are provided to fully support writing an Internet-Draft/RFC
+in AsciiDoc/asciidoctor syntax.
+
+[NOTE]
+====
+The document model of Asciidoctor and RFC XML are different. In particular,
+
+* Asciidoctor and RFC XML differ in where they allow anchors to be placed:
+Asciidoctor does not allow anchors within tables and lists, and RFC XML v3 does
+not permit anchors for the `note` or `abstract` elements, while RFC XML v2
+uses anchors for much fewer block elements (e.g. `artwork`, `list`.)
+* Asciidoctor has a more restrctive block model: it regards elements such as
+admonitions, lists, and tables as blocks, and does not allow them to be nested
+within paragraphs. 
+
+As a result, it may be necessary to postedit the RFC XML output, if the block
+model produced does not reflect the intended structure accurately.
+====
+
+NOTE: The gem validates all RFC XML generated through the RELAXNG schema definitions
+of RFC XML. While the gem attempts to generate valid RFC XML, some Asciidoctor
+text may not align with the RFC XML document model, and any highlighted syntax 
+errors will also need to be rectified in postediting, before processing the 
+generated XML further.
+
+
+=== Document Type: `rfc` or `internet-draft` (Mandatory)
+
+Set the `doctype` attribute to set status of this document:
+
+`:doctype: internet-draft` sets the document as an Internet-Draft (default value):
+
+* `rfc/front/seriesInfo@name` attribute will be set to `Internet-Draft` (in v3)
+* `rfc/front/seriesInfo@value` will be set to the `:name:` attribute, stripping any file suffixes, but including any draft number; e.g. `draft-ietf-somewg-someprotocol-07` (in v3)
+* `rfc@docName` will be set to the `:name:` attribute (in v2)
+
+`:doctype: rfc` sets the document as an RFC:
+
+* `rfc/front/seriesInfo@name` attribute will be set to `RFC` (in v3)
+* `rfc/front/seriesInfo@value` will be set to the `:name:` attribute, stripping the initial `rfc-` prefix and any file suffixes (in v3)
+* `rfc@number` will be set to the `:name:` attribute (in v2)
+
+
+=== Gem Options
+
+[cols="2", options="header"]
+|===
+
+| Attribute
+| Purpose
+
+|`:no-rfc-bold-bcp14:`
+| Optional. Default value `true`. Allowed values: `true`, `false`.
+Override default assumption that boldface uppercase BCP14 word is to be rendered with `bcp14` tag.
+
+|`:smart-quotes:`
+|Optional. Default value `true`. Allowed values: `true`, `false`.
+Permit smart quotes, when they are specified explicitly in Asciidoc (as `"`...`"`, `'`...`'`.) 
+When disabled, smart quotes are rendered as straight quotes, and Asciidoc's default conversion
+of straight apostrophes to smart is undone.
+
+|===
+
+
+=== Basic Document Attributes
+
+`asciidoctor-rfc` allows setting the RFC XML document header using the following
+document attributes. Complying with AsciiDoc syntax, no blank lines are
+permitted between the title, listing of authors, and the document attributes.
+Also following AsciiDoc syntax, character entities will be ignored in the document
+header: `&nbsp;` in the header for example will be rendered as `&amp;nbsp;`.
+
+Shared RFC XML v3/v2 syntax:
+
+[cols="3", options="header"]
+|===
+
+| Attribute
+| Purpose
+| RFC XML v2/v3 element
+
+| `= Document Title`
+| Mandatory. Title of document.
+| `rfc/front/title`
+
+| `:abbrev:`
+| Mandatory. Abbreviation of document title. Usually the document name without
+the keyword `draft-`.
+| `rfc/front/title@abbrev`
+
+| `:ipr:`
+| Mandatory. IP status of document. See
+https://tools.ietf.org/html/rfc7991#section-2.45.5[here]. Defaults to
+`trust200902`.
+| `rfc@ipr`
+
+| `:ipr-extract:`
+| Optional. Identifies a section that can be extracted from text. See
+https://tools.ietf.org/html/rfc7991#section-2.45.6[here].
+| `rfc@iprExtract`
+
+| `:obsoletes:`
+| Optional. A comma-separated list of RFC numbers or Internet-Draft names that
+this document obsoletes. Delimited by `comma + space`.
+| `rfc@obsoletes`
+
+| `:updates:`
+| Optional. A comma-separated list of RFC numbers or Internet-Draft names that
+this document updates. Delimited by `comma + space`.
+| `rfc@updates`
+
+| `:submission-type:`
+| Optional. Document stream of document described in
+https://tools.ietf.org/html/rfc7841[RFC7841]. Allowed values: `IETF` (default),
+`independent`, `IAB`, and `IRTF`.
+| `rfc@submissionType`
+
+| `:revdate:`
+| Optional. Latest revision date of document. Default value is current time.
+Accepts ISO 8601 date. Also accepts YYYY year, and YYYY[-]MM year/month.
+For consistency with AsciiDoc, `:revdate:` is given as
+an ISO 8601 date; the converter breaks it down into day, month name and year
+| `front/date@day`, `front/date@month`, `front/date@year`
+
+| `:area:`
+| Optional. Comma delimited text on which IETF area this document relates to. Value should
+"be either the full name or the abbreviation of one of the IETF areas as
+listed on <http://www.ietf.org/iesg/area.html>". See
+https://tools.ietf.org/html/rfc7991#section-2.4[here].
+| `front/area`
+
+| `:workgroup:`
+| Optional. Comma delimited text on which IETF workgroup or research group this
+document originates from. See https://tools.ietf.org/html/rfc7991#section-2.65[here].
+| `front/workgroup`
+
+| `:keyword:`
+| Optional. Comma delimited text for singular keywords used for RFC index and
+metadata.
+| `front/keyword`
+
+|===
+
+
+=== Document Name / Number (Mandatory)
+
+The `name` attribute sets the document's name. This should be a number if
+the document is an RFC, and a name (in the form of `draft-ietf-somewg-someprotocol-07`)
+if it is an Internet-Draft.
+
+When `doctype` is set to:
+
+* `internet-draft`: the value should be in the form `draft-ietf-somewg-someprotocol-07`.
+** v3: the `front/seriesInfo@value` will be set to this value.
+** v2: the `rfc@docName` will be set to this value.
+
+* `rfc`: the value should be a number like `7991` as described
+  https://tools.ietf.org/html/rfc7991#section-2.47.6[here]
+** v3: the `front/seriesInfo@value` will be set to this value.
+** v2: the `rfc@number` will be set to this value.
+
+
+=== Document Status
+
+Set the `status` attribute to set the current status of this document.
+
+* In v3, this sets the first `front/seriesInfo` element with `@status` as one
+  of: `standard`, `informational`, `experimental`, `bcp`, `fyi`, `full-standard`.
+* In v2, this sets the `rfc@category` value as one of `std`, `info`, `exp`, `bcp`, `historic`.
+
+
+=== Intended Series
+
+Set the `intended-series` attribute to set the intended series of this
+document.
+
+The following values are allowed: `standard`, `informational`, `experimental`, `bcp`, `fyi`, `full-standard`. 
+
+When `doctype` is set to:
+
+* `internet-draft`: this value can be one of `standard`, `full-standard`, `bcp`, `fyi`, `informational`,
+  `experimental`, or `historic` to indicate the intended series once the document is published as an RFC.
+
+** In v3, this sets a second `front/seriesInfo` element with `@status` as one of those values, and an empty `@name`, to indicate this.
+** In v2, this sets the `front@category` value to one of `std`, `bcp`, `info`, `exp`, `historic`.
+
+* `rfc`: this value can be either:
+** one of `full-standard`, `bcp` or `fyi`, to indicate the current status of this document, followed by the number of the document within the series; e.g. `full-standard 1234`, `bcp 14`.
+** `exp`, `info`, or `historic`. (`experimental` and `informational` will be accepted by the gem as synonyms.)
+
+** In v3, this sets a second `front/seriesInfo` element with `@status` as one of those values, and an empty `@name`, to indicate this.
+** In v2, this sets the `front@category` value to one of `std`, `bcp`, `info`. (While in https://tools.ietf.org/html/rfc7749#appendix-A.1[v2], the values `exp`, `historic` are also possible for a RFC, our gem does not support it.)
+
+=== Document Submission Type / Stream
+
+Set document submission type via the `submission-type` document attribute.
+
+The following values are allowed: `IETF` (default), `independent`, `IAB`, and `IRTF`.
+
+* In v3, the `rfc@submissionType` and `rfc/front/seriesInfo@stream` attributes are set to this value.
+* In v2, the `rfc@submissionType` is set to this value
+
+=== Document Consensus
+
+Set document consensus type via the `consensus` document attribute.
+
+These values are accepted: `false`, `true`.
+
+* In v3, this is the value set for the `rfc@consensus` attribute.
+* In v2, this is the value set for the `rfc@consensus` attribute, but `false` is converted to  `no` and `true` is converted to `yes`.
+
+=== Document Language
+
+Set the document language using the `xml-lang` document attribute.
+
+By default this is `en`.
+
+* In v3 and v2, this is the value set for the `rfc@xml:lang` attribute.
+
+While v3 supports marking specific elements with their own `xml:lang` attribute, this is not yet supported by our gem.
+
+
+=== Document Attributes for v2 only
+
+These attributes are only supported for the v2 converter.
+
+[cols="3", options="header"]
+|===
+
+| Attribute
+| Purpose
+| RFC XML v3 element
+
+|`:series-no:`
+| Optional. The document series is defined by the "category" attribute;
+   "seriesNo" is only applicable to the values "info" ("FYI" series),
+   "std" ("STD" series), and "bcp" ("BCP" series).
+| `rfc@seriesNo`
+|===
+
+=== Document Attributes for v3 only
+
+These attributes are only supported for the v3 converter.
+
+[cols="3", options="header"]
+|===
+
+| Attribute
+| Purpose
+| RFC XML v3 element
+
+|`:index-include:`
+| Optional. Defaults to `true`. Values: `true` or `false`. Specifies whether
+formatter should include an index in generated files. If the source file has no
+`<iref>` elements, an index is never generated.
+| `rfc@indexInclude`
+
+|`:sort-refs:`
+| Optional. Defaults to `false`. Values: `true` or `false`. Specifies whether
+the prep tool should sort references.
+| `rfc@sortRefs`
+
+|`:sym-refs:`
+| Optional. Defaults to `true`. Values: `true` or `false`. Specifies whether
+formatter should use symbolic references (such as "`[RFC2119]`") or not
+(such as "`[3]`").
+| `rfc@symRefs`
+
+|`:toc-include:`
+| Optional. Defaults to `true`. Values: `true` or `false`. Specifies whether
+formatter should contain a table of contents.
+| `rfc@tocInclude`
+
+| `:link{_i_}: _URL_` or `:link{_i_}: _URL_ _REL_`
+a| Optional. A link to an external document related to this document.
+
+There are 4 types of values:
+
+. (RFC only) ISSN for this RFC document (`rel` set to `item`, `link` value in
+  form of `urn:issn:`);
+. (RFC only) DOI for this RFC document (`rel` set to `describedBy`, `link`
+  value in form specified by https://tools.ietf.org/html/rfc7669[RFC7669]);
+. (Final Draft) Internet-Draft submitted to become published RFC (`rel` set to
+  `convertedFrom`, `link` value set to "IETF-controlled web site that retains
+  copies of Internet-Drafts");
+. (Any status) ISSN (`rel` set to `alternate`, `link` value as any author run web site).
+| `front/link@href = _URL_`, `front/link@rel = _REL_` (if supplied)
+
+|===
+
+
+=== Author Attributes
+
+In an Internet-Draft/RFC, detailed information of an author is necessary, which
+is not supported by the normal AsciiDoc syntax.
+
+You will need to provide the following information.
+
+
+==== Multiple Author Names
+
+Just like a normal AsciiDoc, you can provide author information in the author 
+header (sample of 3 authors):
+
+[source,asciidoc]
+----
+firstname middlename(s) lastname <email>; firstname middlename(s) lastname <email>; firstname middlename(s) lastname <email>
+----
+
+These will be mapped as follows:
+
+[cols="3", options="header"]
+|===
+
+| Syntax
+| Purpose
+| RFC XML v3/v2 element
+
+| `firstname middlename(s) lastname`
+| Mandatory (at least one). Author's full name. (Middle names are optional.)
+| `front/author@fullname`
+
+| `lastname`
+| Author's last name.
+| `front/author@surname`
+
+| `email`
+| Author's email address.
+| `front/author/address/email`
+
+|===
+
+
+==== Author Attributes
+
+In `asciidoctor-rfc`, detailed author attributes are given as document
+attributes.
+
+As multiple authors can be specified, the document attribute to specify the
+first author uses a unsuffixed attribute name `:role`, and the second author's
+attributes onwards use a numeric suffix to identify the author: `:role_2`, `:role_3`, etc.
+
+Shared RFC XML v3/v2 syntax:
+
+[cols="3", options="header"]
+|===
+
+| Attribute
+| Purpose
+| RFC XML v3/v2 element
+
+| `:fullname{_i}:`
+| Optional. Author's full name. Can set here instead of document header's "`Author`" line.
+| `front/author@fullname`
+
+| `:forename_initials{_i}:`
+| Optional. Author's initials excluding surname. Defaults to dynamically
+calculated initials. Distinct from the AsciiDoc `:initials:` attribute, which
+includes surname.
+| `front/author@initials`
+
+| `:lastname{_i}:`
+| Optional. Author's last name. Can set here instead of document header's "`Author`" line.
+| `front/author@surname`
+
+| `:role{_i}:`
+| Optional. Defaults to `author`. Possible values: `author`, `editor`. If `author` is supplied,
+the attribute is not populated.
+| `front/author@role`
+
+| `:organization{_i}:`
+| Optional. Defaults to `""`. Author's organization affiliation.
+| `front/author/organization`
+
+| `:organization_abbrev{_i}:`
+| Optional. Defaults to `""`. Author's organization's abbreviation shown .
+| `front/author/organization@abbrev`
+
+|===
+
+NOTE: You can provide organization information without providing name information
+for an author.
+
+===== Author Address
+
+[cols="3", options="header"]
+|===
+| Attribute
+| Purpose
+| RFC XML v2/v3 element
+
+| `:email{_i}:`
+| Email of author.
+| `front/author/address/email`
+
+| `:fax{_i}:`
+| Fax number of author. Deprecated in v3.
+| `front/author/address/facsimile`
+
+| `:uri{_i}:`
+| URI of author.
+| `front/author/address/uri`
+
+| `:phone{_i}:`
+| Author's phone number. Scheme-specific part of a `tel` URI (does not include
+the prefix `tel:`).
+See https://tools.ietf.org/html/rfc3966#section-3[RFC3966 `global-number-digits`].
+| `front/author/address/phone`
+
+| `:street{_i}:`
+| Address of author, non-city/region/code/country portion.
+Multiple lines concatenated with `"\ "` will be split into separate `<street>`
+elements.
+| `front/author/address/postal/street`
+
+| `:city{_i}:`
+| City portion of author's address
+| `front/author/address/postal/city`
+
+| `:region{_i}:`
+| Region, state or province portion of author's address. For US/CA the 2-letter state code.
+| `front/author/address/postal/region`
+
+| `:country{_i}:`
+| Country of author's address
+| `front/author/address/postal/country`
+
+| `:code{_i}:`
+| Postal code of author's address
+| `front/author/address/postal/code`
+|===
+
+
+Only available for RFC XML v3:
+
+|===
+| Attribute | Purpose | RFC XML v3 element
+| `:postal-line{_i}:`
+| For those who want to directly format their postal addresses without regard
+to the prior types. Ignored in v2. Multiple lines are concatenated with `"\ "`.
+The `postal-line` attribute is mutually exclusive with the presence of `street`,
+`city`, `region`, `country` and `code` attributes.
+| `front/author/address/postal/postalLine`
+|===
+
+
+Example. This source:
+
+[source,asciidoc]
+----
+:street: 57 Mt Pleasant St\ Technology Park
+:city: Dullsville
+:region: NSW
+:country: Australia
+:code: 3333
+----
+
+Produces:
+
+[source,xml]
+----
+<address>
+  <postal>
+    <street>57 Mt Pleasant St</street>
+    <street>Technology Park</street>
+    <city>Dullsville</city>
+    <region>NSW</region>
+    <code>3333</code>
+    <country>Australia</country>
+  </postal>
+</address>
+----
+
+
+=== Abstract
+
+Any paragraphs following the document header are treated as the abstract
+(`front/abstract`), whether or not they are in abstract style. The abstract is
+terminated by either the first section header (which ends the document
+preamble), or an admonition (e.g. `note`).
+
+Any admonitions before the first section header are treated as notes (`front/note`).
+
+[source,asciidoc]
+----
+[[abstract-id]] <1>
+[abstract]
+This is an abstract <2>
+
+NOTE: This is a note <3>
+
+[NOTE,remove-in-rfc=true] <4>
+.Note 2 Title <5>
+===
+This is another note <3>
+===
+----
+<1> v3 only: `front/abstract@anchor` (attribute only available in v3)
+<2> `front/abstract`
+<3> `front/note`
+<4> v3 only: `front/note@removeInRFC` (attribute only available in v3)
+<5> v3: `front/note/name`; v2: `front/note@title` (mandatory attribute; if not provided, `NOTE` is supplied)
+
+
+=== Sections and Subsections
+
+[source,asciidoc]
+----
+:sectnums: <1>
+[[id]] <2>
+[remove-in-rfc=true,toc=include|exclude|default] <3>
+== Section title <4>
+First paragraph of section <5>
+
+Second paragraph of section <5>
+
+:sectnums!: <6>
+=== Subsection title <7>
+First paragraph of subsection <8>
+
+==== Subsubsection title <9>
+Content content content <10>
+----
+<1> `middle/section@numbered=true` (attribute only available in v3)
+<2> `middle/section@anchor`
+<3> v3 only: `middle/section@removeInRFC`, `middle/section@toc` (attributes only available in v3)
+<4> v3: `middle/section/name`; v2: `middle/section@title`
+<5> `middle/section/t`
+<6> `middle/section@numbered=false` (attribute only available in v3) (toggle)
+<7> v3: `middle/section/section/name`; v2: `middle/section/section@title`
+<8> `middle/section/section/t`
+<9> v3: `middle/section/section/section/name`; v2: `middle/section/section/section@title`
+<10> `middle/section/section/section/t`
+
+
+=== Cross-References
+
+[source,asciidoc]
+----
+Content content content
+<<crossreference>> <1>
+<<crossreference,text>> <2>
+<<crossreference,format=(counter|title|none|default): text>> <3>
+http://example.com/[linktext] <4>
+The following represent the v3 relref element
+<<crossreference,section_number (of|comma|parens|bare)>> <5>
+<<crossreference,section_number (of|comma|parens|bare): text>> <6>
+<<crossreference#fragment,section_number (of|comma|parens|bare)>> <7>
+<<crossreference#fragment,section_number (of|comma|parens|bare): text>> <8>
+----
+<1> `<xref target="crossreference"/>`
+<2> `<xref target="crossreference">text</xref>`
+<3> `<xref format="counter|title|none|default" target="crossreference">text</xref>`
+<4> `<eref href="http://example.com/">linktext</eref>`
+<5> v3 only: `<relref displayFormat="of|comma|parens|bare" section="section_number" target="crossreference"/>` (element only available in v3)
+<6> v3 only: `<relref displayFormat="of|comma|parens|bare" section="section_number" target="crossreference">text</relref>` (element only available in v3)
+<7> v3 only: `<relref relative="fragment" displayFormat="of|comma|parens|bare" section="section_number" target="crossreference"/>` (element only available in v3)
+<8> v3 only: `<relref relative="fragment" displayFormat="of|comma|parens|bare" section="section_number" target="crossreference">text</relref>` (element only available in v3)
+
+In v2, the relref style crossreferences are rendered as equivalent `xref` crossreferences,
+inserting section numbers as appropriate.
+
+
+=== Indexing
+
+[source,asciidoc]
+--
+This ((<indexterm>)) <1>
+is visible in the text,
+this one is not (((indexterm, index-subterm))). <2>
+--
+<1> `<iref item="indexterm">indexterm</iref>`
+<2> `<iref item="indexterm" subitem="index-subterm"/>`
+
+
+=== Inline formatting
+
+[source,asciidoc]
+--
+Linebreak: + <1>
+_Italic_ <2>
+*Bold* <3>
+`Monospace` <4>
+~subscript~ <5>
+^superscript^ <6>
+[bcp14]#MUST NOT# <7>
+*MUST NOT* <8>
+--
+<1> That is, "+ " at the end of a line. v3: `<br/>`; v2: `<vspace/>`.
+<2> v3: `<em>Italic</em>`; v2: `<spanx style="emph">Italic</spanx>`
+<3> v3: `<strong>Bold</strong>`; v2: `<spanx style="strong">Bold</spanx>`
+<4> v3: `<tt>Monospace</tt>`; v2: `<spanx style="verb">Monospace</spanx>`
+<5> v3 only: `<sub>subscript</sub>`. Not supported in v2; rendered as `\_subscript_`
+<6> v3 only: `<sup>superscript</sup>`. Not supported in v2; rendered as `\^superscript^`
+<7> v3 only: `<bcp14>MUST NOT</bcp14>`. Not supported in v2; rendered as `<spanx style="strong">MUST NOT</spanx>`.
+<8> v3: if document flag `:no-rfc-bold-bcp14:` is present, then `<strong>MUST NOT</strong>`, else (by default) any BCP14/RFC2119 phrase in boldface and capitals is assumed to be intended to be tagged in `<bcp14>`. v2: `<spanx style="strong">MUST NOT</spanx>`.
+
+NOTE: The delimiters must occur within the one line; the following is invalid in Asciidoctor:
+[source,asciidoc]
+--
+*WOULD
+PROBABLY*
+--
+
+=== Paragraphs
+
+[source,asciidoc]
+--
+[[id]] <1>
+[keep-with-next=true,keep-with-previous=true] <2>
+Paragraph text <3>
+--
+<1> `t@anchor`
+<2> v3 only: `t@keepWithNext`, `t@keepWithPrevious` (attributes only available in v3)
+<3> `<t>Paragraph text</t>`
+
+=== Quotes (v3 only)
+
+[source,asciidoc]
+--
+[[id]] <1>
+[quote, attribution, citation info] <2>
+Quotation <3>
+--
+<1> `blockquote@anchor`
+<2> `blockquote@quotedFrom`, `blockquote@cite`. In v3, `citation info` is limited to a URL.
+<3> `<blockquote>Quotation</blockquote>`
+
+
+=== Comments
+
+In v2 RFC XML, comment text is stripped of all formatting.
+
+[source,asciidoc]
+--
+NOTE: Any admonition inside the body of the text is a comment. <1>
+// Note that actual AsciiDoc comments are ignored by the converter.
+
+[[id]] <2>
+[NOTE,display=true|false,source=name] <3>
+.Note Title <4>
+====
+Any admonition inside the body of the text is a comment.
+====
+--
+<1> `<cref>Any admonition inside the body of the text is a comment.</cref>`
+<2> `cref@anchor`
+<3> v3 only: `cref@display` (not supported in v2); v2: `cref@source`
+<4> v3 only: `cref/name` (not suppported in v2)
+
+
+=== Source Code Listings
+
+[source,asciidoc]
+--
+[[id]] <1>
+.Source code listing title <2>
+[source,type,src=uri,align,alt] <3>
+----
+begin() {
+  source code listing <4>
+}
+----
+--
+<1> v3: `figure/sourcecode@anchor`; v2: `figure/artwork@anchor`
+<2> v3: `figure/sourcecode@name`; v2: `figure/artwork@name`
+<3> v3: `figure/sourcecode@type`; `figure/sourcecode@src` (`align` and `alt` not supported). If `src` is present, the listing is not expected to have any content: content is taken from the hyperlink in the attribute. v2: `figure/artwork@type`, `figure/artwork@src`, `figure/artwork@align`, `figure/artwork@alt`.
+<4> v3: `figure/sourcecode`; v2: `figure/artwork`
+
+
+=== ASCII Art and Images
+
+[source,asciidoc]
+--
+[[id]] <1>
+[align,alt,suppress-title] <2>
+.Figure 1 <3>
+====
+Preamble text <4>
+
+[[id]] <5>
+.Figure2.jpg <8>
+[align=left|center|right,alt=alt_text,type] <6>
+....
+Figures are only permitted to contain listings (sourcecode), images (artwork),
+or literal (artwork) <7>
+....
+[[id]] <5>
+.Figure2.jpg <8>
+[align=left|center|right,alt=alt_text,type] <9>
+image::filename.jpg[alt_text,700,200] <10>
+
+Postamble text <11>
+====
+--
+<1> `figure@anchor`
+<2> v2 only: `figure/artwork@align`, `figure/artwork@alt`, `figure@suppress-title` (attributes only available in v2)
+<3> `figure/name`
+<4> v2 only: `figure/preamble` (only available in v2)
+<5> `figure/artwork@anchor`
+<6> `figure/artwork@align`, `figure/artwork@alt`; `figure@type` (attribute only available in v2)
+<7> `figure/artwork`
+<8> `figure/artwork@name`
+<9> `figure/artwork@align`, `figure/artwork@alt`; `figure/artwork@type` (only available in v2, intended to be a MIME type; v3: populated as either `svg` or `binary-art` depending on file suffix)
+<10> `figure/artwork@src`, `figure/artwork@alt`, `figure/artwork@width` (deprecated in v3), `figure/artwork@height` (deprecated in v3)
+<11> v2 only: `figure/postamble` (only available in v2)
+
+
+=== Unordered and Ordered Lists
+
+[source,asciidoc]
+--
+[[id]] <1>
+[empty=true,spacing=normal|compact,hang-indent=n] <2>
+* Unordered list 1 <3>
+* Unordered list 2 <3>
+** Nested list <4>
+
+[[id]] <5>
+[spacing=compact,start=n,group=n,counter=token,hang-indent=n,format=List #%d,arabic|loweralpha|upperralpha|lowerroman|upperroman] <6>
+. A <7>
+. B <7>
+--
+<1> v3: `ul@anchor`; attribute only available in v3
+<2> v3: `ul@empty`, `ul@spacing` (`hangIndent` not available); v2: `ul@style = empty`, `ul@hangIndent` (`spacing` not available)
+<3> v2: `list[@style="symbols"]/t`; v3: ul/li
+<4> v2: `list[@style="symbols"]/t/list[@style="symbols"]/t`; v3: `ul/li/ul/li`
+<5> v3: `ol@anchor`; attribute only available in v3
+<6> v2: `list/counter`,  `list@hangIndent`, `list@style = format List #%d`, `list@style` (for arabic|loweralpha|upperralpha|lowerroman|upperroman) (`start`, `empty` and `group` not available) v3: `ol@empty`, `ol@start`, `ol@group`, `ol@type = "#%d", `ol@type` (for arabic|loweralpha|upperralpha|lowerroman|upperroman) (`counter`, `hangIndent` not available)
+<7> v2: `list/t`; v3: `ol/li`
+
+NOTE: Asciidoctor does not permit anchors on list items: the anchors in the following are ignored.
+
+[source,asciidoc]
+--
+* [[id1]] A
+
+. [[id2]] A
+--
+
+NOTE: RFC XML v2 does not support multiparagraph list items. Following the specification recommendation,
+paragraphs within v2 list items are replaced with `vspace` tages.
+
+=== Definition Lists
+
+[source,asciidoc]
+--
+[[id]] <1>
+[horizontal,compact,hang-indent=n] <2>
+A:: B <3>
+--
+<1> v3 only: `dl@anchor` (attribute only available in v3)
+<2> v3 only: `dl@hanging`, `dl@spacing` (attributes only available in v3); v2 only: `list@hangIndent` (attribute only available in v2). Note that the `compact` and `horizontal` attributes are mutually exclusive in AsciiDoc.
+<3> v3: `dl/dt`, `dl/dd`; v2: `list[@style="hanging"]/t@hangText`, `list[@style="hanging"]/t`
+
+NOTE: Asciidoctor does not permit anchors on either definition list terms,
+or definition list definitions: the anchors in the following are ignored.
+
+[source,asciidoc]
+--
+[[id1]] A:: [[id2]]B
+--
+
+NOTE: RFC XML v2 does not support multiparagraph list items. Following the specification recommendation,
+paragraphs within v2 list items are replaced with `vspace` tages.
+
+=== Tables
+
+The converter respects the AsciiDoc (horizontal) align attributes of cells (v2,
+v3), column widths (v2), and `colspan`, `rowspan` attributes (v3). 
+
+(Exceptionally,
+column widths specified for v2 as `"1,1,1,1,1,1...."` will be ignored, since Asciidoctor
+internally treats them identically to unspecified column widths on a table.)
+
+[source,asciidoc]
+--
+[[id]] <1>
+[suppress-title=true|false,align=left|center|right,grid=all|cols|none] <2>
+.Table Title <3>
+|===
+|[[id]] head | head <4>
+
+h|header cell | body cell <5>
+| | [[id]] body cell <6>
+
+|foot | foot <7>
+|===
+--
+<1> v3: `table@anchor`; v2: `texttable@anchor`
+<2> v2: `texttable@suppress-title`, `texttable@align`, `texttable@style` (attributes only available in v2). Mapping of Asciidoc grid attribute to RFC XML style attribute is: `all` > `all`, `cols` > `full`, `none` > `none`. The RFC XML `headers` attribute is not supported. The Asciidoc attribute `rows` is not supported.
+<3> v3: `table/name`; v2: `texttable@title`
+<4> v3: `table/thead/tr/td`; v2: `texttable/ttcol@id` (attribute only available in v2), `texttable/ttcol`
+<5> v3: `table/tbody/tr/th`, `table/tbody/tr/td`; v2: `texttable/c`, `texttable/c`
+<6> v3: `table/tbody/tr/td@anchor` (attribute only available in v3)
+<7> v3: `table/tfoot/tr/td`; v2: `texttable/c`
+
+NOTE: v3 permits table cells to contain block elements, such as paragraphs and lists. (This is done in Asciidoc by prefixing
+the table cell with `a|`.) However v2 only permits inline tagging, and any block tags are ignored.
+
+=== Sidebar (v3 only)
+
+[source,asciidoc]
+--
+[[id]] <1>
+****
+Sidebar <2>
+****
+--
+<1> `aside@anchor`
+<2> `<aside>Sidebar</aside>`
+
+
+=== References
+
+References are expected to be provided in raw RFC XML v2 format. For v3, a list of crossreferences may
+precede the block of references, with alternative text. This will not be rendered, but it will be used
+to populate `displayreference` elements, mapping the reference anchors to display text. For example,
+a list entry `[[[ref1,alt1]]]` means that any instances of the anchor `ref1` should be displayed as `alt1`,
+and is rendered as `<displayreference target="ref1" to="alt1"/>`.
+
+[source,asciidoc]
+--
+[[id]] <1>
+[bibliography]
+== Normative References
+* [[[ref1,alt1]]] <2>
+++++
+(raw XML) <3>
+++++
+
+[[id]] <1>
+[bibliography]
+== Informative References
+++++
+(raw XML) <2>
+++++
+--
+<1> `back/references@anchor`
+<2> `back/displayreference@target`, `back/displayreference@to` (only in v3)
+<3> `back/references/reference`
+
+
+
+=== Appendices
+
+[source,asciidoc]
+--
+[[id]] <1>
+[appendix]
+== Appendix 1 <2>
+Content <3>
+--
+<1> `back/section@anchor`
+<2> v3: `back/section/name`; v2: `back/section@title`
+<3> `back/section/t`
+
+
+
+
+=== Unsupported RFC XML Elements
+
+The following **RFC XML v3/v2** elements are not (yet) supported through
+asciidoctor commands:
+
+|===
+| RFC XML element                  | RFC XML v3 | RFC XML v2
+| `front/boilerplate`              | Not added  | N/A
+| `iref@primary`                   | N          | N
+| `reference/*` (and all children) | N/A        | N
+| `reference/front`                | N          | N
+| `reference/annotation`           | N          | N
+| `reference@quote-title`          | N          | N/A
+| `reference@target`               | N          | N
+| `table/preamble`                 | Deprecated | N
+| `table/postamble`                | Deprecated | N
+| `table@style = headers`          | N/A        | N
+| `artwork@width`                  | Only on images | Only on images
+| `artwork@height`                 | Only on images | Only on images
+|===
+
+=== Unsupported Asciidoctor Features
+
+These asciidoctor features are not supported in output of these formats:
+
+|===
+| asciidoctor feature | RFC XML v2 | RFC XML v3
+| http://asciidoctor.org/docs/user-manual/#quote[Quote] | Rendered as normal paragraph | Supported
+| http://asciidoctor.org/docs/user-manual/#quote[Quote]: Non-URL Citations 2+| Ignored
+| http://asciidoctor.org/docs/user-manual/#verse[Verse] | Rendered as normal paragraph | Rendered as Quote
+| http://asciidoctor.org/docs/user-manual/#sidebar[Sidebar] | Rendered as normal paragraph | Supported
+| http://asciidoctor.org/docs/user-manual/#index-terms[Index Term]: Tertiary 2+| Ignored
+| List: http://asciidoctor.org/docs/user-manual/#numbering-styles[Ordered List numbering] `decimal`, `lowergreek` 2+| Treated as `arabic`
+| http://asciidoctor.org/docs/user-manual/#callouts[Callouts] 2+| Ignored
+| http://asciidoctor.org/docs/user-manual/#admonition[Adminitions: formatting] | Ignored | Supported
+| Formatting: http://asciidoctor.org/docs/user-manual/#discrete-headings[Floating Title] 2+| Rendered as strong paragraph
+| Formatting: http://asciidoctor.org/docs/user-manual/#page-break[Page Break] 2+| Ignored
+| Formatting: http://asciidoctor.org/docs/user-manual/#horizontal-rules[Horizontal Rule] 2+| Ignored
+| Formatting: http://asciidoctor.org/docs/user-manual/#line-breaks[Line breaks] | Supported | Only supported within table cells
+| Media: http://asciidoctor.org/docs/user-manual/#audio[Audio] 2+| Ignored
+| Media: http://asciidoctor.org/docs/user-manual/#video[Video] 2+| Ignored
+| Media: http://asciidoctor.org/docs/user-manual/#images[Inline images] 2+| Ignored
+| Macro: http://asciidoctor.org/docs/user-manual/#keyboard-shortcuts[Keyboard shortcuts] 2+| Ignored
+| Macro: http://asciidoctor.org/docs/user-manual/#menu-selections[Menu selections] 2+| Ignored
+| Macro: http://asciidoctor.org/docs/user-manual/#ui-buttons[UI buttons] 2+| Ignored
+| Table: http://asciidoctor.org/docs/user-manual/#footer-row[Distinction between table body and table footer] | No | Supported
+| Table: http://asciidoctor.org/docs/user-manual/#header-row[Multiple table header rows] | No | Supported
+| Table: http://asciidoctor.org/docs/user-manual/#table-borders[Table borders: grid = rows] | No | Ignored
+| Table: http://asciidoctor.org/docs/user-manual/#table-borders[Table borders: grid = cols\|none] | Supported | Ignored
+| Table: http://asciidoctor.org/docs/user-manual/#table-borders[Table borders: frame] 2+| Ignored
+| Table: http://asciidoctor.org/docs/user-manual/#cell[Table cells: rowspan] | Ignored | Supported
+| Table: http://asciidoctor.org/docs/user-manual/#cell[Table cells: colspan] | Ignored | Supported
+| Table: http://asciidoctor.org/docs/user-manual/#cell[Table cells: Asciidoctor formatting (blocks within cells)] | Ignored | Supported
+| Table: http://asciidoctor.org/docs/user-manual/#cols-format[Table columns: width] | Supported | Ignored
+|===
+
+
+== Examples
+
+=== RFC XML v3 Example
+
+ifdef::env-github[]
+include::spec/examples/example-v3.adoc[]
+endif::[]
+ifndef::env-github[]
+[source,asciidoc]
+----
+include::spec/examples/example-v3.adoc[]
+----
+endif::[]
+
+=== RFC XML v2 Example
+
+ifdef::env-github[]
+include::spec/examples/example-v2.adoc[]
+endif::[]
+ifndef::env-github[]
+[source,asciidoc]
+----
+include::spec/examples/example-v2.adoc[]
+----
+endif::[]
+
+
+== Development
+
+We follow Sandi Metz's Rules for this gem, you can read the
+http://robots.thoughtbot.com/post/50655960596/sandi-metz-rules-for-developers[description of the rules here].
+
+All new code should follow these
+rules. If you make changes in a pre-existing file that violates these rules you
+should fix the violations as part of your contribution.
+
+=== Setup
+
+Clone the repository.
+
+[source,sh]
+----
+git clone https://github.com/riboseinc/asciidoctor-rfc
+----
+
+Setup your environment.
+
+[source,sh]
+----
+bin/setup
+----
+
+Run the test suite
+
+[source,sh]
+----
+bin/rspec
+----
+
+== Contributing
+
+First, thank you for contributing! We love pull requests from everyone. By
+participating in this project, you hereby grant https://www.ribose.com[Ribose Inc.] the
+right to grant or transfer an unlimited number of non exclusive licenses or
+sub-licenses to third parties, under the copyright covering the contribution
+to use the contribution by all means.
+
+Here are a few technical guidelines to follow:
+
+. Open an https://github.com/riboseinc/asciidoctor-rfc/issues[issue] to discuss a new feature.
+. Write tests to support your new feature.
+. Make sure the entire test suite passes locally and on CI.
+. Open a Pull Request.
+. https://github.com/thoughtbot/guides/tree/master/protocol/git#write-a-feature[Squash your commits] after receiving feedback.
+. Party!
+
+
+== Credits
+
+This gem is developed, maintained and funded by https://www.ribose.com[Ribose Inc.]