= AsciiRFC: Writing Internet-Drafts and RFCs in AsciiDoc :source-highlighter: coderay :icons: font

WARNING: This gem has been subsumed into the https://www.metanorma.com[Metanorma] publishing framework. Development of AsciiRFC is continued at the https://github.com/metanorma/metanorma-ietf[metanorma-ietf] gem. Please see the new repo for details on usage instructions. Thank you for your support.

WARNING: While the RFC XML v2 output of this gem is still valid, the RFC XML v3 output of the gem will not work with the updated xml2rfc tool, as this gem' does not include the modifications to RFC XML v3 subsequent to RFC 7991. Use metanorma-ietf to generate valid RFC XML v3 output.

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/metanorma/asciidoctor-rfc/master.svg["Build Status", link="https://travis-ci.org/metanorma/asciidoctor-rfc"] image:https://codeclimate.com/github/metanorma/asciidoctor-rfc/badges/gpa.svg["Code Climate", link="https://codeclimate.com/github/metanorma/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" as much as possible, with some templated use of attributes to convey added information for RFC XML output.

We refer to the version of Asciidoc markup processed by this gem as AsciiRFC.

This README documents the AsciiRFC markup in full detail. For further information about AsciiRFC, please refer to the https://datatracker.ietf.org/doc/draft-ribose-asciirfc/[AsciiRFC IETF Internet-Draft].

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

Clone the https://github.com/metanorma/rfc-asciirfc-minimal[rfc-asciirfc-minimal] repository as a template, and populate it for your Asciidoc RFCs and Internet-Drafts:

[source,console]

$ git clone https://github.com/metanorma/rfc-asciirfc-minimal

See the https://github.com/metanorma/rfc-asciirfc-minimal[README] of that document for more information.

== Quick Example

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 [email protected] :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

[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] == Normative References ++++ Key words for use in RFCs to Indicate Requirement Levels In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. <seriesInfo name="BCP" value="14"/> <seriesInfo name="RFC" value="2119"/> <seriesInfo name="DOI" value="10.17487/RFC2119"/> ++++

[bibliography] == Informative References ++++ Guidelines for Writing an IANA Considerations Section in RFCs Sacramento State UC Davis <seriesInfo name="RFC" value="7253"/> ++++

== Usage

Converting your AsciiDoc to RFC XML is a simple as running the appropriate ./bin/asciidoctor-rfc script using Ruby, and passing your AsciiDoc document file as the first argument.

Usually you would 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

or through the included bin-stub:

[source,console]

$ ./bin/asciidoctor-rfc3 draft-example-00.adoc # RFC XML v3 output $ ./bin/asciidoctor-rfc2 draft-example-00.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.

NOTE: A summary guide to authoring RFC XML in Asciidoctor is also available at https://tools.ietf.org/html/draft-ribose-asciirfc-02 (with source at https://github.com/metanorma/rfc-asciidoc-rfc ).

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

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

|:inline-definition-lists: |Optional. Default value false. Allowed values: true, false. Only applies to v2. By default, <vspace blankLines="1"> is inserted after the definition in a v2 definition list, to satisfy the requirement from idnits validation that definition terms be separated by a carriage return from the definition. That is, by default inline definition lists are rendered as paragraphing definition lists. If the option is on, the additional vspace element is not added, and inline definition lists are left as is.

|:flush-caches: |Optional. Default value false. Allowed values: true, false. Delete and reload the caches of references to be included externally, and of workgroups, during processing of this document. The caches are stored in ~/.asciidoc-rfc-biblio-cache.json and ~/.asciidoc-rfc-workgroup-cache.json.

|:biblio-dir: |Optional. Name of directory. If present, gives the name of a directory from which RFC XML references are to be read into the document, rather than assuming the references are already present in the document.

|:normative: |Optional. Comma-delimited list of reference anchors. Used in conjunction with :biblio-dir:, which uses a single directory for all references: this attribute lists those references which are to be considered normative, and listed under the Normative References heading.

|===

Any of these global options can also be included in the command line call, for either the asciidoctor executable or the local bin-stubs, through the command line option -a; e.g.

[source,console]

$ asciidoctor -a flush-biblio=true -b rfc3 -r 'asciidoctor-rfc' a.adoc $ ./bin/asciidoctor-rfc2 -a smart-quotes=false draft-example-00.adoc

[[caches]] ==== Caches

The cache of externally addressable bibliographic information is built from screenscraping the contents of:

https://xml2rfc.tools.ietf.org/public/rfc/bibxml/
https://xml2rfc.tools.ietf.org/public/rfc/bibxml2/
https://xml2rfc.tools.ietf.org/public/rfc/bibxml3/
https://xml2rfc.tools.ietf.org/public/rfc/bibxml4/
https://xml2rfc.tools.ietf.org/public/rfc/bibxml5/

The cache of current IETF and IRTF workgroups is built from screenscraping the contents of:

https://tools.ietf.org/wg/
https://irtf.org/groups

The caches are not rebuilt daily, as the bibliographic cache is with xml2rfc. If you want to refresh the caches,

delete your ~/.asciidoc-rfc-biblio-cache.json and ~/.asciidoc-rfc-workgroup-cache.json files;
insert the document attribute :flush-caches: true into the header of the document being processed; or
run the asciidoctor executable with option -a flush-caches=true (which has the same effect).

=== 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:   in the header for example will be rendered as &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 or IRTF 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

|===

=== Processing Instructions The xml2rfc tool accepts processing instructions of the form <?rfc keyword='value'?>: see https://xml2rfc.tools.ietf.org/authoring/README.html#processing.instructions . (Of these, sort-refs, sym-refs and toc-include are also present in the v3 RFC XML specifcation, as attributes of the root rfc element: <<v3documentattributes,v3-specific document attributes>>.) Those processing instructions which apply to the entire document can also be specified for this gem as document options.

|=== |keyword |meaning

,

, etc.) for (sub)section titles |editing | insert editing marks for ease of discussing draft versions |emoticonic | automatically replaces input sequences such as |text| by, e.g., text in html output |footer | override the center footer string |header | override the leftmost header string |inline | if comments is "yes", then render comments inline; otherwise render them in an "Editorial Comments" section |iprnotified | include boilerplate from Section 10.4(d) of http://tools.ietf.org/html/rfc2026 |linkmailto | generate mailto: URL, as appropriate |linefile | a string like "35:file.xml" or just "35" (file name then defaults to the containing file's real name or to the latest linefile specification that changed it) that will be used to override xml2rfc's reckoning of the current input position (right after this PI) for warning and error reporting purposes (line numbers are 1-based) |notedraftinprogress | generates "(work in progress)", as appropriate |private | produce a private memo rather than an RFC or Internet-Draft |refparent | title of the top-level section containing all references |rfcedstyle | attempt to closely follow finer details from the latest observable RFC-Editor style so as to minimize the probability of being sent back corrections after submission; this directive is a kludge whose exact behavior is likely to change on a regular basis to match the current flavor of the month; presently, it will capitalize the adjective "This" in automatically generated headings, use the variant "acknowledgement" spelling instead of Merriam Webster's main "acknowledgment" dictionary entry, use the "eMail" spelling instead of Knuth's more modern "email" spelling, only put one blank line instead of two before top sections, omit "Intellectual Property and Copyright Statements" and "Author's Address" from the table of content, and not limit the indentation to a maximum tag length in sections. |rfcprocack | if there already is an automatically generated Acknowledg(e)ment section, pluralize its title and add a short sentence acknowledging that xml2rfc was used in the document's production to process an input XML source file in RFC-2629 format |slides | when producing a html file, produce multiple files for a slide show |sort-refs | (`sortrefs`) sort references |strict | try to enforce the ID-nits conventions and DTD validity |subcompact | if compact is "yes", then you can make things a little less compact by setting this to "no" (the default value is the current value of the compact PI) |sym-refs | (`symrefs`) use anchors rather than numbers for references |text-list-symbols | modify the list of symbols used (when generated text) for list type="symbols". For example, specifying "abcde" will cause "a" to be used for 1st level, "b" for the 2nd level, etc, cycling back to the first character "a" at the 6th level. Specifying "o" will cause the characters "o" and "*" to be alternated for each successive level. |toc-include | (`toc`) generate a table-of-contents |tocappendix | control whether the word "Appendix" appears in the table-of-content |toc-depth | if toc is "yes", then this determines the depth of the table-of-contents |tocindent | if toc is "yes", then setting this to "yes" will indent subsections in the table-of-contents |tocnarrow | affects horizontal spacing in the table-of-content |tocompact | if toc is "yes", then setting this to "no" will make it a little less compact |topblock | put the famous header block on the first page |useobject | when producing a html file, use the

Exceptionally, compact, toc-include, sym-refs, sort-refs and strict are is set by default to yes, subcompact to no, and toc-depth to 4.

The additional document option rfc2629xslt (default value: true) injects into the document header the processing instruction <?xml-stylesheet type="text/xsl" href="rfc2629.xslt" ?>, which impacts on the output of xml2rfc.

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

The following values are allowed: standard, informational, experimental, bcp, fyi, full-standard (v3 only), historic (v2 only).

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.

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

[#v3documentattributes] === 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. Supported in v2 as a processing instruction. | 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]"). Supported in v2 as a processing instruction. | rfc@symRefs

|:toc-include: | Optional. Defaults to true. Values: true or false. Specifies whether formatter should contain a table of contents. Supported in v2 as a processing instruction. | rfc@tocInclude

| :link: _URL_, _URL_ _REL_ a| Optional. Comma-delimited links 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 ; firstname middlename(s) lastname ; firstname middlename(s) lastname

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

|===

If any author names deviate from that pattern, e.g. with an honorific like Dr., they will not be recognised correctly by the Asciidoc API; use the fullname document attribute instead.

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

57 Mt Pleasant St Technology Park Dullsville NSW 3333 Australia

----

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

Note that fragments (e.g. crossreference#fragment) are not supported on the xref@target attribute, in either v2 or v3: the RFC XML specification requires that the xref@target attribute equals the value of an anchor attribute elsewhere in the document.

Internal crossreferences and bibliographic references are marked up in the same way; but bibliographic references are marked up separately from the main flow of Asciidoctor, and are processed later.

NOTE: Normally, Asciidoctor attempts to match a crossreference to a section title, if it does not find a matching anchor ID. This behaviour has become optional as of Asciidoctor 1.5.7, and is suppressed in this gem. If you have a citation of a bibliographic item which is identical to a section title (e.g. you have a bibliographic citation with the anchor "WHIRLPOOL", and a section with the title "WHIRLPOOL"), this gem will correctly pick the former as the target of the reference, so long as that section has a different anchor ID:

[source,asciidoc]

[[hash_whirlpool]] === WHIRLPOOL

The WHIRLPOOL hash function is defined in <<WHIRLPOOL>>.

This section should actually be referenced as <<hash_whirlpool>>. ...

[bibliography] == Informative References ++++ ... ++++

=== Indexing

[source,asciidoc]

This (()) <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> stem:[sqrt(4) = 2]

<1> That is, "+ " at the end of a line. v3:  ; v2: <vspace/>. <2> v3: Italic; v2: <spanx style="emph">Italic</spanx> <3> v3: Bold; v2: <spanx style="strong">Bold</spanx> <4> v3: <tt>Monospace</tt>; v2: <spanx style="verb">Monospace</spanx> <5> v3 only: subscript. Not supported in v2; rendered as \_subscript_ <6> v3 only: superscript. 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 MUST NOT, 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>. <9> Stem expressions are treated identically to monospace expressions; they are not currently rendered as MathML or any other notation.

NOTE: The delimiters must occur within the one line; the following is invalid in Asciidoctor: [source,asciidoc]

WOULD PROBABLY

Any formatting XML spans within spanx elements are stripped in postprocessing.

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

==== Asciidoctor comments

Asciidoctor implements both inline comments (prefixed with //) and block comments (prefixed with ////). Both are ignored by the Asciidoctor processor, and are not rendered in any output, including RFC XML.

Asciidoctor also permits paragraphs and open blocks (which can contain multiple paragraphs) to be treated as Asciidoctor comments, if they have the style attribute [comment]:

[source,asciidoc]

// This is an inline Asciidoctor comment, which will not be output to XML.

[comment] This is a single paragraph Asciidoctor comment, which will not be output to XML.

//// This is a block Asciidoctor comment,

which will not be output to XML. ////

[comment]

This is a

multiple paragraph

Asciidoctor comment, which will not be output to XML.

==== XML comments

XML inline comments may be introduced into XML through the [comment] formatting macro: any such comments may not span more than one line.

[source,asciidoc]

Text [comment]#This is a comment# Text

The foregoing will be rendered in RFC XML as:

[source,xml]

Text Text

XML block comments are introduced through the role attribute [.comment], which can be prefied to a paragraph or an open block (which can contain multiple paragraphs):

[source,asciidoc]

[.comment] This is a single paragraph XML comment.

[.comment]

This is a

multiple paragraph

XML comment.

==== Text Comments

RFC XML provides for editorial comments which may optionally appear in the published text (subject to either the v3 cref@display attribute, or the comments processing instruction).

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

In RFC XML, sourcecode (v3) and artwork (v2) elements only occur within a figure wrapper; this gem supplies that wrapper if it is not provided explicitly.

[source,asciidoc] .Without Figure Wrapper

[[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@anchor (moved into supplied wrapper: anchors not supported on artwork) <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

[source,asciidoc] .With Figure Wrapper

[[id]] <1> [align,alt,suppress-title] <2> .Figure 1 <3>

Preamble text <4>

[[id1]] <5> .Source code listing title <6> [source,type,src=uri,align,alt] <7>

begin() { source code listing <8> }

Postamble text <9>

-- <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> v3: figure/sourcecode@anchor; v2: Not supported: use figure@anchor <6> v3: figure/sourcecode@name; v2: figure/artwork@name <7> 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. <8> v3: figure/sourcecode; v2: figure/artwork <9> v2 only: figure/postamble (only available in v2)

=== ASCII Art and Images

In RFC XML, artwork elements only occur within a figure wrapper; this gem supplies that wrapper if it is not provided explicitly.

[source,asciidoc] .Ascii-Art Without Figure Wrapper

[[id]] <1> .Figure2.jpg <2> [align=left|center|right,alt=Ascii Art,type=text/plain] <3> ....

| Ascii Art | ------------------------ <4> ....

[source,asciidoc] .Image Without Figure Wrapper

[[id]] <1> .Figure2.jpg <2> [align=left|center|right,alt=alt_text,type=img/jpeg] <3> image::filename.jpg[alt_text,700,200] <4>

<1> v3 only: figure/artwork@anchor; v2: figure@anchor (moved into supplied wrapper: anchors not supported on artwork) <2> figure/artwork@name <3> 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) <4> figure/artwork@src, figure/artwork@alt, figure/artwork@width (deprecated in v3), figure/artwork@height (deprecated in v3)

[source,asciidoc] .With Figure Wrapper

[[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=text/plain] <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=img/jpeg] <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> v3: figure/artwork@anchor; v2: Not supported: use figure@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)

=== Mathematical examples

In order for mathematical formatting to be recognised in Asciidoc, the document attribute :stem: needs to be set.

[source,asciidoc]

:stem:

[stem] ++++ sqrt(4) = 2 ++++

Mathematical examples are treated identically to literals, and are rendered as artwork in both v2 and v3; however their default alignment is set as center. As with inline stem expressions, they are treated identically to monospace expressions in the RFC XML output; they are not currently rendered as MathML or any other notation.

=== 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,empty=true,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) (spacing, start, empty and group not available) v3: ol@spacing, ol@empty, ol@start, ol@group, ol@type = "#%d", ol@type (for arabic|loweralpha|upperralpha|lowerroman|upperroman) (counter, hangIndentnot 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.

NOTE: In RFC XML v2, idnits considers inline definition lists invalid; the gem renders them as paragraphed definition lists. The gem option :inline-definition-lists disables this behaviour.

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

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, rows > headers (although the two are not strictly equivalent). <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: Embedded in Document

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

RFC requires two separate bibliographies, one for normative and one for informative references; either can be omitted. All bibliography sections in the must be styled with the prefix [bibliography], and must appear in sequence, before any appendices.

By default, the references cited must be included as raw RFC XML, and separated into the normative and informative sections.

[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 (only in v3) <2> back/displayreference@target, back/displayreference@to (only in v3) <3> back/references/reference

In postprocessing, bibliographic entries available from http://xml.resource.org/public/rfc are replaced with external references to that entry, using XML entities in RFC XML v2, and XML includes in RFC XML v3. Do not insert your own entities or XML includes into the references; the gem will have difficulty processing them.

[[external-directory-refs]] === References: External Directory

As an alternative, the document attribute :biblio-dir: can nominate a directory in which separate XML files can be placed, one for each reference to be included. (RFC XML v3 referencegroup elements will also be recognised as files.) The gem will read in from that directory only the files that have actually been cited, and insert them into the appropriate bibliography, without the references needing to be given under the bibliographies as above. (In fact, any XML already provided will be deleted.) By default, references will be considered informative; the document attribute :normative: can be used to specify a comma-delimited list of normative references.

The gem will issue a warning if any cited reference is not included in the directory. However, external references do not have to be included in the directory: they will be recognised by comparing their anchors against the external bibliography cache, and referenced as entities or includes. However, particular drafts of Internet-Draft documents do still need to be included as separate documents (see <>.)

For example:

[source,asciidoc]

= The Holy Hand Grenade of Antioch Arthur Pendragon :doctype: internet-draft :workgroup: silly :biblio-dir: refs <1> :normative: RFC2119, AsciiDoc <1>

[[xyz]] == Hello Hello

a <<RFC2119,2.3 of: See internet draft subsection>> <3>
b <<I-D.abarth-cake>>
b2 <<I-D.abarth-cake,what>>
b1 <<I-D.abarth-cake,2.3 of: See internet draft subsection>> <3>
c <<xyz,format=counter: xyzzy>> <4>
d <> <4>
e <<AsciiDoc,AsciiDoctor>>
f <>

[[biblio]] === Biblio See biblio

[bibliography] == Normative References <5>

[bibliography] == Informative References <6>

<1> The RFC XML references are included in the directory ./refs, with one file per reference. For example, we would expect it to contain a file corresponding to the reference mathrefs. A file corresponding to RFC2119 is optional, and in fact will be ignored, since the anchor is recognised as an external reference. A file corresponding to I-D.abarth-cake will not be ignored, if that file contains a seriesInfo element nominating a specific draft version. <2> The references in the ./refs directory are by default considered informative; this attribute indicates that RFC2119 and AsciiDoc are to be considered normative. <3> References are recognised in relref as well as xref elements. <4> The gem differentiates between bibliographic references and crossreferences to other anchors within the document. <5> The bibliographic headers need to be provided as above, and its titles are expected to be "Normative References" and "Informative References"; the gem will look for those titles specifically in order to insert the references it identifies from the file. However, no XML content is expected to be provided under each heading, and any XML content that is provided will be ignored.

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

=== Unsupported Asciidoctor Features

These asciidoctor features are not supported in output of these formats:

|=== | asciidoctor feature | RFC XML v2 | RFC XML v3

[[external-ref-lookup]] == Lookup of external references

In order to speed the lookup of references on the http://xml.resource.org/public/rfc website for external references, a cache of references is built the first time the gem is run, in the user's home directory: ~/.asciidoc-rfc-biblio-cache.json. This maps all the canonical anchors for external references as defined by the IETF, such as RFC2119 or CCITT.E163.1988, to the URLs that their RFC reference is stored on. References are detected for replacement in the Asciidoc document by matching the references@anchor attribute to one of those canonical anchors; the content of the local RFC XML reference is not checked.

(For rebuilding the cache, see <>.)

Rather than hand crafting RFC XML references for RFC documents, or other references hosted at http://xml.resource.org/public/rfc/, you need only create a dummy <reference> element containing the IETF-defined anchor for that citation. In postprocessing, any references that are hosted at xml.resource.org will be identified by their anchor, and replaced by entities or XML includes, for RFC XML v2 and v3 respectively. (The complete list of authoritative RFC XML bibliographies is available from https://xml2rfc.tools.ietf.org , online and in zipped form.)

Because the content of any externally defined <reference> element is overwritten with an entity or include, you do not need to provide a full reference. You can supply a minimal reference like <reference anchor="RFC2119"/>, but note that such a reference is invalid in the RFC XML schema, and the gem will report a missing element during processing. (The document will still be processed successfully.) To prevent any validation error reports, the minimal syntactically valid reference is:

[source,xml]

If you wish to cite a specific version of an Internet-Draft, you will need to include the seriesInfo element in the reference that identifies the specific version; the anchor is the same for all internet drafts. For example:

[source,xml]

As discussed under <>, any citations of specific versions of an Internet-Draft need to be included as explicit files in an external directory of RFC XML references, since the seriesInfo draft information cannot be recovered by the anchor. However, any other external references do not require a corresponding directory file (although normative references do still need to be named in the :normative: document attribute.)

== asciidoc-bibliography integration

[TODO]

//// The https://github.com/riboseinc/asciidoctor-bibliography[asciidoc-bibliography] gem allows citations to be imported into asciidoc from BibTex or RFC XML files. The gem natively requires the user to provide the correct, presorted RFC XML references within asciidoc separately for normative and for informative references. Using the asciidoc-bibliography gem, the user can instead have a single file of RFC XML references, and indicate in place whether each reference is intended to be normative or informative, as is the case for MMark; the gem will then extract the correct RFC XML references from the references file, and insert them in order into the normative and informative references respectively.

Integration with the asciidoc-bibliography gem proceeds as follows:

. 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. .. The caveats for <<external-ref-lookup,externally available references>> also apply to the references file. 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; postprocessing means you do not need to create your own XML entities anyway. .. 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. . Add the following header attributes to the main document: +

`:bibliography-database:` :: The name of the references file; this is expected to be in the same directory as the main document. `:bibliography-passthrough:` :: `citations`. This instructs the asciidoctor-bibliography gem to wrap the citations in an Asciidoctor passthrough block. If `true` is used, the references introduced through `cite` macros will also be treated as inline Asciidoctor passthrough text. `:bibliography-prepend-empty:` :: `true|false`. No current effect on file `:bibliography-hyperlinks:` :: `true|false` (default `true`): inserts bibliographic link around reference. Use `false`. `:bibliography-style:` :: The style of reference used in the references file; the recognised styles are `rfc-v2` and `rfc-v3`, for RFC XML v2 and RFC XML v3 respectively.

. References to a normative reference are inserted with the macro `cite:norm[id]` instead of `<<id>>`, where `id` is the anchor of the reference. . References to an informative reference are inserted with the macro `cite:info[id]` instead of `<<id>>`, where `id` is the anchor of the reference. .. Text may be prefixed or suffixed to the crossreference with the `prefix` and `suffix` attributes. .. Arbitrary text associated with a crossreference is inserted with a `text` attribute (with the citation itself in curly brackets), and fragment references are inserted with a `locator` attribute. .. 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. Using `cite:norm`, the following equivalence obtain between normal Asciidoc treatment of crossreferences and asciidoc-bibliography macros: * `<<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'/>"]` . Normative and Informative References are inserted in the document through a macro, which occurs where the RFC XML references would be inserted + [source,asciidoc]

[bibliography] == Normative References

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

[bibliography] == Informative References

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

. In order to preprocess the macros, the asciidoctor-bibliography gem is passed as an -r argument to the asciidoctor-rfc invocation: ** asciidoctor -b rfc2 -r 'asciidoctor-bibliography' -r 'asciidoctor-rfc' spec/examples/refs-v2.adoc ** asciidoctor -b rfc3 -r 'asciidoctor-bibliography' -r 'asciidoctor-rfc' spec/examples/refs-v3.adoc . referencegroup citations are not currently supported by the asciidoctor-bibliography gem. ////

== 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/metanorma/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/metanorma/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.]

asciidoctor-rfc asciidoctor-rfc copied to clipboard

Metadata

[source,ruby]

gem "asciidoctor-rfc"

[source,console]

$ bundle

[source,console]

$ gem install asciidoctor-rfc

[source,console]

$ git clone https://github.com/metanorma/rfc-asciirfc-minimal

[source,asciidoc]

[bibliography] == Informative References ++++ Guidelines for Writing an IANA Considerations Section in RFCs Sacramento State UC Davis <seriesInfo name="RFC" value="7253"/> ++++

[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

[source,console]

$ ./bin/asciidoctor-rfc3 draft-example-00.adoc # RFC XML v3 output $ ./bin/asciidoctor-rfc2 draft-example-00.adoc # RFC XML v2 output

[NOTE]

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.

[source,console]

$ asciidoctor -a flush-biblio=true -b rfc3 -r 'asciidoctor-rfc' a.adoc $ ./bin/asciidoctor-rfc2 -a smart-quotes=false draft-example-00.adoc

,

[source,asciidoc]

firstname middlename(s) lastname ; firstname middlename(s) lastname ; firstname middlename(s) lastname

[source,asciidoc]

:street: 57 Mt Pleasant St\ Technology Park :city: Dullsville :region: NSW :country: Australia :code: 3333

[source,xml]

[source,asciidoc]

[NOTE,remove-in-rfc=true] <4> .Note 2 Title <5>

This is another note <3>

[source,asciidoc]

==== Subsubsection title <9> Content content content <10>

[source,asciidoc]

[source,asciidoc]

[bibliography] == Informative References ++++ ... ++++

[source,asciidoc]

This (()) <1> is visible in the text, this one is not (((indexterm, index-subterm))). <2>

[source,asciidoc]

Linebreak: + <1> Italic <2> Bold <3> Monospace <4> ~subscript~ <5> ^superscript^ <6> [bcp14]#MUST NOT# <7> MUST NOT <8> stem:[sqrt(4) = 2]

NOTE: The delimiters must occur within the one line; the following is invalid in Asciidoctor: [source,asciidoc]

WOULD PROBABLY

[source,asciidoc]

[[id]] <1> [keep-with-next=true,keep-with-previous=true] <2> Paragraph text <3>

[source,asciidoc]

[[id]] <1> [quote, attribution, citation info] <2> Quotation <3>

[source,asciidoc]

[comment]

Asciidoctor comment, which will not be output to XML.

[source,asciidoc]

Text [comment]#This is a comment# Text

[source,xml]

Text Text

[source,asciidoc]

[.comment]

XML comment.

[source,asciidoc]

[[id]] <2> [NOTE,display=true|false,source=name] <3> .Note Title <4>

Any admonition inside the body of the text is a comment.

[source,asciidoc] .Without Figure Wrapper

[[id]] <1> .Source code listing title <2> [source,type,src=uri,align,alt] <3>

begin() { source code listing <4> }

[source,asciidoc] .With Figure Wrapper

[[id]] <1> [align,alt,suppress-title] <2> .Figure 1 <3>

[[id1]] <5> .Source code listing title <6> [source,type,src=uri,align,alt] <7>

begin() { source code listing <8> }

Postamble text <9>

[source,asciidoc] .Ascii-Art Without Figure Wrapper

[[id]] <1> .Figure2.jpg <2> [align=left|center|right,alt=Ascii Art,type=text/plain] <3> ....

| Ascii Art | ------------------------ <4> ....

[source,asciidoc] .Image Without Figure Wrapper

[[id]] <1> .Figure2.jpg <2> [align=left|center|right,alt=alt_text,type=img/jpeg] <3> image::filename.jpg[alt_text,700,200] <4>

[source,asciidoc] .With Figure Wrapper

[[id]] <1> [align,alt,suppress-title] <2> .Figure 1 <3>

Postamble text <11>

[source,asciidoc]

[stem] ++++ sqrt(4) = 2 ++++

[source,asciidoc]

[[id]] <5> [spacing=compact,empty=true,start=n,group=n,counter=token,hang-indent=n,format=List #%d,arabic|loweralpha|upperralpha|lowerroman|upperroman] <6> . A <7> . B <7>

[source,asciidoc]

. [[id2]] A

[source,asciidoc]

asciidoctor-rfc
asciidoctor-rfc copied to clipboard

Linebreak: + <1> Italic <2> Bold <3> `Monospace` <4> ~subscript~ <5> ^superscript^ <6> [bcp14]#MUST NOT# <7> MUST NOT <8> stem:[sqrt(4) = 2]