Impedance Mismatch LLC

marc@petit-huguenin.org

General This document specifies a mapping between XML2RFC v3 and AsciiDoc. The goal of this mapping and its associated tooling is to make writing an Internet-Draft as simple as possible, by converting any AsciiDoc formatted document into a valid Internet-Draft, ready to be submitted to the IETF. This is still work in progress and for the time being this mapping only ensures that any valid XML2RFC element can be generated from AsciiDoc.

Introduction This document specifies a mapping between XML2RFC v3, as defined in the successor of , and . The goal of this mapping and its associated tooling is to make writing an Internet-Draft as simple as possible, by converting any AsciiDoc formatted document into a valid Internet-Draft, ready to be submitted to the IETF. This is still work in progress and for the time being this mapping only ensures that any valid XML2RFC element can be generated from AsciiDoc. Installation and usage of the tool is described in .

Overview AsciiDoc is an extensible documentation format whose syntax can be split in two parts:

• The standard syntax as defined in
• Extensions that extend the standard syntax. A popular example of extension is asciidoctor-diagrams, which permits the insertion of diagrams in a document.

The mapping described in this document splits these parts further. The standard syntax is split in two subparts:

• The primitive standard syntax contains all the AsciiDoc elements that have a direct translation back and forth with XML2RFC v3.
• The compound standard syntax contains all the other standard elements.

Elements in the compound standard syntax are converted into XML2RFC v3 by using multiple elements. That means that the conversion back to AsciiDoc will always be to elements in the primitive standard syntax, not the original elements. For instance an AsciiDoc unordered list is a primitive element that is converted to an <ol> element in XML2RFC. On the other hand the AsciiDoc checklist is a compound element that is converted into a combination of <ol> and <t> elements in XML2RFC, but the conversion back will not result in an AsciiDoc checklist. Similarly some AsciiDoc extensions have been developed to support XML2RFC elements and attributes that do not have a standard AsciiDoc equivalent. The XML2RFC elements and attributes will be converted back into these AsciiDoc extensions, but any other AsciiDoc extensions will be converted back into a combination of primitive AsciiDoc elements. When choosing the mapping between an XML2RFC elements and an AsciiDoc element, reusing as much as possible of the standard AsciiDoc syntax was a priority. An extension is added only if a standard element with the correct semantics cannot be found. AsciiDoc is not really meant to support highly structured XML2RFC elements like <front>, <reference>, <referencegroup>, <author>, and <contact>. Thus these element are used directly in AsciiDoc by inserting an XML2RFC fragment inside a passthrough block. Passthrough blocks serve also as an escape hatch for new elements added to the XML2RFC syntax until a new revision of this document is published.

Deprecated and Unsupported Elements In any case AsciiDoc, both standard and extensions, never generate deprecated XML2RFC elements or attributes. This mapping is specifically designed to write Internet-Drafts so there is no support, in any direction, for XML2RFC elements and attributes that are specific to RFCs. The list of xml2rc v3 elements that are specific to the generation of RFCs, and so cannot be generated from an AsciiDoc document are:

• the <boilerplate> element
• the <link> element
• the "iprExtract", "number", "prepTime", and "seriesNo" attributes in the <rfc> element
• the <toc> element
• all the attributes added by the preptool.

Docinfo Processing If a docinfo file is used, it completely replaces the generation of the <front> element. To reduce redundancy, some of the attributes declared in the document header can be referenced in the docinfo file:

subtitle:

This attribute contains the subtitle to be inserted in the "abbrev" attribute of the <title> element. This is an extension to the standard AsciiDoc.

author:

This attribute contains the full name to be inserted in the "fullname" attribute of the <author> element.

email:

This attribute contains the email to be inserted in the <email> element.

revday:

This attribute contains the day to be inserted in the "day" attribute of the <date> element. This is an extension to the standard AsciiDoc.

revmonth:

This attribute contains the month to be inserted in the "month" attribute of the <date> element. This is an extension to the standard AsciiDoc.

revyear:

This attribute contains the year to be inserted in the "year" attribute of the <date> element. This is an extension to the standard AsciiDoc.

abstract:

This attribute contains the abstract to be inserted in the <abstract> element. This is an extension to the standard AsciiDoc.

revremark:

This attribute contains the note to be inserted in a <note> element.

Include Citation References can be automatically extracted from local Internet-Drafts written in AsciiDoc, and inserted into a reference section by including the document with the fragment identifier "#citation", as in the following example:

Mappings

Mapping between AsciiDoc and XML2RFC v3 This section describes the mapping between the AsciiDoc direct syntax and IETF extensions to non-deprecated XML2RFC v3 elements and attributes.

<abstract> The <abstract> element inside a <front> element is either generated from an abstract section or copied from a docinfo file. The <abstract> element can also be used inside a <reference> element in a passthrough block in the bibliography.

"anchor" Attribute The <abstract> "anchor" attribute can be copied from a docinfo file. It cannot be generated from an abstract section.

<address> The <address> element inside a <front> element is copied from a docinfo file. The <address> element can also be used inside a <reference> element in a passthrough block in the bibliography. The <address> element can also be used inside an <author> element in a passthrough block in a section.

<annotation> The <annotation> element can be used inside a <reference> element in a passthrough block in the bibliography.

<area> The <area> element inside a <front> element is copied from a docinfo file. The <area> element can be used inside a <reference> element in a passthrough block in the bibliography.

<artset> The <artset> element is generated from an example block using the style "alt". This block can only contain images or literal blocks. The alt style on an example block is an extension to standard AsciiDoc. The following example

is converted to

• ]]>

"anchor" Attribute The <artset> "anchor" attribute is generated from the "alt" block ID, if present. The following example

is converted to

• ]]>

<artwork> The <artwork> element is generated from a literal or image block. The following example

is converted to

• ]]>

The following example

is converted to

• ]]>

"align" Attribute The <artwork> "align" attribute is generated from the align attribute, if present. The following example

is converted to

• ]]>

The following example

is converted to

• ]]>

"alt" Attribute The <artwork> "alt" attribute is generated from the alt attribute, if present. The alt attribute on a literal block is an extension to standard AsciiDoc. The following example

is converted to

• ]]>

The following example

is converted to

• ]]>

"anchor" Attribute The <artwork> "anchor" attribute is generated from the image or literal block ID, if present. The following example

is converted to

• ]]>

The following example

is converted to

• ]]>

"name" Attribute The <artwork> "name" attribute is generated from the name attribute, if present. The name attribute on a literal block is an extension to standard AsciiDoc. The following example

is converted to

• ]]>

"src" Attribute The <artwork> "src" attribute is generated from the target of an image block. The src attribute on an image block is an extension to standard AsciiDoc. The following example

is converted to

• ]]>

"type" Attribute The <artwork> "type" attribute is generated from the format attribute, if present. The format attribute on an literal block is an extension to standard AsciiDoc. The following example

is converted to

• ]]>

<aside> The <aside> element is generated from a sidebar block. The following example

is converted to

• Some text ]]>

"anchor" Attribute The <aside> "anchor" attribute is generated from the aside block ID, if present. The following example

is converted to

• Some text ]]>

<author> The <author> element inside a <front> element is either generated from the author information in the document header or copied from a docinfo file. The <author> element can also be used inside a <reference> element in a passthrough block in the bibliography.

<back> The <back> element is implicitly generated when a bibliography or a appendices are added to a document.

<bcp14> The <bcp14> element is generated from the text span style bcp14. The text span style bcp14 is an extension to standard AsciiDoc. The following example

is converted to

• Implementers MUST implement all MUST. ]]>

<blockquote> The <blockquote> element is generated from a quote block. The following example

is converted to

• Some text ]]>

"anchor" Attribute The <blockquote> "anchor" attribute is generated from the quote block ID, if present. The following example

is converted to

• Some text ]]>

"cite" Attribute The <blockquote> "cite" attribute is generated from the quote block cite attribute, if present. The cite attribute on an literal block is an extension to standard AsciiDoc. The following example

is converted to

• Some text ]]>

"quotedFrom" Attribute The <blockquote> "quotedFrom" attribute is generated from the quote block positional attribute, if present. The following example

is converted to

• Some text ]]>

<boilerplate> The <boilerplate> element is used only for RFCs and so is not generated.

<br> The <br> element is generated from the " +" string at the end of a line in a paragraph. The following example

is converted to

• This is
  two lines ]]>

<contact> The <contact> element and its attributes are provided in a section as a passthrough block containing that element, or in a paragraph as an inline passthrough containing that element.

<country> The <country> element and its attribute inside a <front> element is copied from a docinfo file. The <country> element can be used inside a <reference> element in a passthrough block in the bibliography.

<cref> The <cref> element is generated from the comment inline macro. The comment inline macro and its attributes are extensions to standard AsciiDoc. The following example

is converted to

• The Replace native native mode can be used. ]]>

"anchor" Attribute The <cref> "anchor" attribute is generated from the comment inline macro ID, if present. The following example

is converted to

• The Replace native native mode can be used. ]]>

"display" Attribute The <cref> "display" attribute is generated from the comment inline macro display attribute, if present. The following example

is converted to

• The Replace native native mode can be used. ]]>

"source" Attribute The <cref> "source" attribute is generated from the comment inline macro source attribute, if present. The following example

is converted to

• The Replace native native mode can be used. ]]>

<date> The <date> element and its attributes inside a <front> element are either generated from an revdate document header or copied from a docinfo file. The <date> element can also be used inside a <reference> element in a passthrough block in the bibliography.

<dd> The <dd> element is generated from the definition part of a description list. The following example

is converted to

• text
  data
  ]]>

"anchor" Attribute The <dd> anchor attribute cannot be generated.

<displayreference> The <displayreference> element is generated from a bibliography entry bibref that differs from the ID of the entry itself. The following example

• ++++]]>

is converted to

• References ]]>

"target" Attribute The <displayreference> target attribute cannot be generated.

"to" Attribute The displayreference "to" attribute cannot be generated.

<dl> The <dl> element is generated from a description list. The following example

is converted to

• text
  data
  ]]>

"anchor" Attribute The <dl> "anchor" attribute is generated from the ID of a description list, if present. The following example

is converted to

• text
  data
  ]]>

"indent" Attribute The <dl> "indent" attribute is generated from the indent attribute of a description list, if present. The description list indent attribute is an extension to standard AsciiDoc. The following example

is converted to

• text
  data
  ]]>

"newline" Attribute The <dl> "newline" attribute is generated from the indent attribute of a description list, if present. The description list newline attribute is an extension to standard AsciiDoc. The following example

is converted to

• text
  data
  ]]>

"spacing" Attribute The <dl> "spacing" attribute is generated from the spacing attribute of a description list, if present. The description list spacing attribute is an extension to standard AsciiDoc. The following example

is converted to

• text
  data
  ]]>

<dt> The <dt> element is generated from the term part of a definition list. The following example

is converted to

• text
  data
  ]]>

"anchor" Attribute The <dt> anchor attribute cannot be generated.

<em> The <em> element is generated from an italic text formatting. The following example

is converted to

• Text with emphasis. ]]>

<email> The <email> element inside a <front> element is either generated from the email document header or copied from a docinfo file. The <email> element can also be used inside a <reference> element in a passthrough block in the bibliography. The <email> element can also be used inside an <author> element in a passthrough block in a section.

<eref> The <eref> element is generated from a link macro. The following example

is converted to

• As cited in . ]]>

"bracket" Attribute The <eref> "bracket" attribute is generated from the bracket attribute in the link macro, if present. The link macro bracket attribute is an extension to standard AsciiDoc. The following example

is converted to

• As cited in . ]]>

"target" Attribute The <eref> "target" attribute is generated from the target in the link macro. The following example

is converted to

• As cited in . ]]>

<figure> The <figure> element is generated from an example block with the style "figure". The figure style on an example block is an extension to standard AsciiDoc. The following example

is converted to

• ]]>

"anchor" Attribute The <figure> "anchor" attribute is generated from the ID of a figure block, if present.

is converted to

• ]]>

<front> The <front> element is either generated from the author information in the document header or copied from a docinfo file. The <front> element can also be used inside a <reference> element in a passthrough block in the bibliography.

<iref> The <iref> element is generated either from an indexterm inline macro or from an indexterm block macro extension. The indexterm block macro is an extension to standard AsciiDoc. The following example

is converted to

• Text with an index. ]]>

The following example

is converted to

• ]]>

"item" Attribute The <iref> "item" attribute is generated from the positional attribute of the index term. The following example

is converted to

• Text with an index. ]]>

"primary" Attribute The <iref> "primary" attribute is generated from the primary attribute of the index term. The primary indexterm block macro attribute is an extension to standard AsciiDoc. The following example

is converted to

• Text with an index. ]]>

The following example

is converted to

• ]]>

"subitem" Attribute The <iref> "subitem" attribute is generated from the secondary attribute of the index term. The secondary indexterm block macro attribute is an extension to standard AsciiDoc. The following example

is converted to

• Text with an index. ]]>

The following example

is converted to

• ]]>

<keyword> The <keyword> element inside a <front> element is copied from a docinfo file. The <keyword> element can also be used inside a <reference> element in a passthrough block in the bibliography.

<li> The <li> element is generated from a line in either an unordered or an ordered list. The following example

is converted to

• One line
]]>

The following example

is converted to

• One line

]]>

"anchor" Attribute The <li> "anchor" attribute is generated from the ID of a list item, if present. The following example

is converted to

• test
]]>

The following example

is converted to

• test

]]>

<link> The <link> element is provided in the docinfo file.

<middle> The <middle> element is implicitly generated.

<name> The <name> element is generated from the title in either a section, an example block with figure style, or a table block. The possibility of using formatted text in an example block with figure style title or in a table title is an extension to standard AsciiDoc. The following example

is converted to

• section

]]> The following example

is converted to

• title ]]>

The following example

is converted to

• title Test ]]>

<note> The <note> element inside a <front> element is either generated from the revremark document header or copied from a docinfo file. The <note> element can also be used inside a <reference> element in a passthrough block in the bibliography.

<ol> The <ol> element is generated from an ordered list. The following example

is converted to

• One line
]]>

"anchor" Attribute The <ol> "anchor" attribute is generated from the ID of a ordered list, if present. The following example

is converted to

• test
]]>

"group" Attribute The <ol> "group" attribute is generated from the group attribute of a ordered list, if present. The group attribute on an ordered list is an extension to standard AsciiDoc. The following example

is converted to

• test
]]>

"indent" Attribute The <ol> "indent" attribute is generated from the indent attribute of an ordered list, if present. The indent attribute on an ordered list is an extension to standard AsciiDoc. The following example

is converted to

• test
]]>

"spacing" Attribute The <ol> "spacing" attribute is generated from the spacing attribute of an ordered list, if present. The spacing attribute on an ordered list is an extension to standard AsciiDoc. The following example

is converted to

• test
]]>

"start" Attribute The <ol> "start" attribute is generated from the start attribute of an ordered list, if present. The following example

is converted to

• test
]]>

"type" Attribute The <ol> "type" attribute is generated from the style of an ordered list, if present. The prefix and suffix types are used to generate a "type" attribute that uses the "percent-letter" format. The prefix and suffix attributes on an ordered list are extensions to standard AsciiDoc. The following example

is converted to

• test
]]>

The following example

is converted to

• test
]]>

<organization> The <organization> element inside a <front> element is copied from a docinfo file. The <organization> element can also be used inside a <reference> element in a passthrough block in the bibliography. The <organization> element can also be used inside an <author> element in a passthrough block in a section.

<phone> The <phone> element inside a <front> element is copied from a docinfo file. The <phone> element can also be used inside a <reference> element in a passthrough block in the bibliography. The <phone> element can also be used inside an <author> element in a passthrough block in a section.

<postal> The <postal> element inside a <front> element is copied from a docinfo file. The <postal> element can also be used inside a <reference> element in a passthrough block in the bibliography. The <postal> element can also be used inside an <author> element in a passthrough block in a section.

<postalLine> The <postalLine> element inside a <front> element is copied from a docinfo file. The <postalLine> element can also be used inside a <reference> element in a passthrough block in the bibliography. The <postalLine> element can also be used inside an <author> element in a passthrough block in a section.

<refcontent> The <refcontent> element can be used inside a <reference> element in a passthrough block in the bibliography.

<reference> The <reference> element is provided in a passthrough block in the bibliography.

<referencegroup> The <referencegroup> element is provided in a passthrough block in the bibliography.

<references> The <references> element is generated from an unordered list in a bibliography section. The following example

• ++++]]>

is converted to

• References ]]>

"anchor" Attribute The <references> "anchor" attribute is generated from the ID of an unordered list in a bibliographic section, if present. The following example

is converted to

• ]]>

<rfc> The <rfc> element is generated by a top level section: The following example

is converted to

• ]]>

"category" Attribute The <rfc> "category" attribute is generated from the category document header attribute. The category attribute on a document header is an extension to standard AsciiDoc. The following example

is converted to

• ]]>

"consensus" Attribute The <rfc> "consensus" attribute is generated from the consensus document header attribute. The consensus attribute on a document header is an extension to standard AsciiDoc. The following example

is converted to

• ]]>

"docName" Attribute The <rfc> "docName" attribute is generated from the doc-name document header attribute. The doc-name attribute on a document header is an extension to standard AsciiDoc. The following example

is converted to

• ]]>

"indexInclude" Attribute The <rfc> "indexInclude" attribute is generated from the "index-include" document header attribute if present. The following example

is converted to

• ]]>

"ipr" Attribute The <rfc> "ipr" attribute is generated from the "ipr" document header attribute if present, or with the "trust200902" content if not present. The following example

is converted to

• ]]>

"iprExtract" Attribute Specific to RFC, so not implemented.

"number" Attribute Specific to RFC, so not implemented.

"obsoletes" Attribute The <rfc> "obsoletes" attribute is generated from the "obsoletes" document header attribute if present. The following example

is converted to

• ]]>

"prepTime" Attribute Specific to RFC, so not implemented.

"seriesNo" Attribute Specific to RFC, so not implemented.

"sortRefs" Attribute The <rfc> "sortRefs" attribute is generated from the "sort-refs" document header attribute if present. The following example

is converted to

• ]]>

"submissionType" Attribute The <rfc> "submissionType" attribute is generated from the "submission-type" document header attribute if present. The following example

is converted to

• ]]>

"symRefs" Attribute The <rfc> "symRefs" attribute is generated from the "sym-refs" document header attribute if present. The following example

is converted to

• ]]>

"tocDepth" Attribute The <rfc> "tocDepth" attribute is generated from the "toclevels" document header attribute if present. The following example

is converted to

• ]]>

"tocInclude" Attribute The <rfc> "tocInclude" attribute with a value of "false" is generated from the "toc" document header attribute if not present, or a value of "true" if present. The following example

is converted to

• ]]>

"updates" Attribute The <rfc> "updates" attribute is generated from the "updates" document header attribute if present. The following example

is converted to

• ]]>

"version" Attribute The <rfc> "version" attribute is implicitly generated. The following example

is converted to

• ]]>

<section> The <section> attribute is generated from a document section. The following example

is converted to

• Section 1

]]>

"anchor" Attribute The <section> "anchor" attribute is generated from section ID, if present. The following example

is converted to

• Section 1

]]>

"numbered" Attribute The <section> "numbered" attribute is generated from the current value of the sectnums attribute. Note that AsciiDoc standards sections are unnumbered by default, but xml2rfc sections are numbered by default, so a ":sectnums:" attribute should be added to the document header. Each AsciiDoc special sections with style "appendix" that needs to be unnumbered needs to be preceded with the attribute ":sectnums!". The following example

is converted to

• Section 1

]]>

"removeInRfc" Attribute The <section> "removeInRfc" attribute is generated from the remove-in-rfc section attribute. The remove-in-rfc attribute on a section is an extension to standard AsciiDoc. The following example

is converted to

• Section 1

]]>

"toc" Attribute The <section> "toc" attribute is generated from the section attribute "toc". The toc attribute on a section is an extension to standard AsciiDoc. The following example

is converted to

• Section 1

]]>

<seriesInfo> The <seriesInfo> element inside a <front> element is copied from a docinfo file. The <seriesInfo> element can also be used inside a <reference> element in a passthrough block in the bibliography.

<sourcecode> The <sourcecode> element is generated from a listing block with the source style. The following example

is converted to

• ]]>

"anchor" Attribute The <sourcecode> "anchor" attribute is generated from the ID of a listing block with source style, if present. The following example

is converted to

• ]]>

"markers" Attribute The <sourcecode> "markers" attribute is generated from the markers attribute of a listing block with source style, if present. The markers attribute on a listing block with source style is an extension to standard AsciiDoc. The following example

is converted to

• ]]>

"name" Attribute The <sourcecode> "name" attribute is generated from the name attribute of a listing block with source style, if present. The name attribute on a listing block with source style is an extension to standard AsciiDoc. The following example

is converted to

• ]]>

"src" Attribute The <sourcecode> "src" attribute is generated from the src attribute of a listing block with source style, if present. The src attribute on a listing block with source style is an extension to standard AsciiDoc. The following example

is converted to

• ]]>

"type" Attribute The <sourcecode> "type" attribute is generated from the positional attribute of a listing block with source style, if present. The following example

is converted to

• ]]>

<stream> The <stream> element inside a <front> element is copied from a docinfo file. The <stream> element can also be used inside a <reference> element in a passthrough block in the bibliography.

<strong> The <strong> element is generated from a bold text formatting. The following example

is converted to

• Strong text. ]]>

<sub> The <sub> element is generated from a subscript text formatting. The following example

is converted to

• Base₁₆. ]]>

<sup> The <sup> element is generated from a superscript text formatting. The following example

is converted to

• E = mc² ]]>

<t> The <t> element is generated from a paragraph. The following example

is converted to

• Some text. ]]>

"anchor" Attribute The <t> "anchor" attribute is generated from the ID of a paragraph, if present. The following example

is converted to

• Some text. ]]>

"indent" Attribute The <t> "indent" attribute is generated from the indent attribute of a paragraph, if present. The indent attribute on a paragraph is an extension to standard AsciiDoc. The following example

is converted to

• Some text. ]]>

"keepWithNext" Attribute The <t> "keepWithNext" attribute is generated from the keep-with-next attribute of a paragraph, if present. The keep-with-next attribute on a paragraph is an extension to standard AsciiDoc. The following example

is converted to

• Some text. ]]>

"keepWithPrevious" Attribute The <t> "keepWithPrevious" attribute is generated from the keep-with-previous attribute of a paragraph, if present. The keep-with-previous attribute on a paragraph is an extension to standard AsciiDoc. The following example

is converted to

• Some text. ]]>

<table> The <table> element is generated from a table. The following example

is converted to

• Cell ]]>

"align" Attribute The <table> "align" attribute is generated from the ID of a table, if present. The following example

is converted to

• Cell ]]>

"anchor" Attribute The <table> "anchor" attribute is generated from the ID of a table, if present. The following example

is converted to

• Cell ]]>

<tbody> The <tbody> element is generated from a table with rows. The following example

is converted to

• Cell ]]>

"anchor" Attribute The <tbody> anchor attribute cannot be generated.

<td> The <td> element is generated from a table with at least one cell. The following example

is converted to

• Cell ]]>

"align" Attribute The <td> "align" attribute is generated from the horizontal alignment operator of a cell in a table, if present. The following example

• Cell |===]]>

is converted to

• > Cell ]]>

"anchor" Attribute The <td> anchor attribute cannot be generated.

"colspan" Attribute The <td> "colspan" attribute is generated from the horizontal alignment operator of a cell in a table, if present. The following example

is converted to

• Cell ]]>

"rowspan" Attribute The <td> "rowspan" attribute is generated from the horizontal alignment operator of a cell in a table, if present. The following example

is converted to

• Cell ]]>

<tfoot> The <tfoot> element is generated from a table with footer. The following example

is converted to

• Cell Footer ]]>

"anchor" Attribute The <tfoot> anchor attribute cannot be generated.

<th> The <th> element is generated from a table with at least one cell. The following example

is converted to

• Cell ]]>

"align" Attribute The <th> "align" attribute is generated from the horizontal alignment operator of a cell in a table, if present. The following example

• Cell |===]]>

is converted to

• > Cell ]]>

"anchor" Attribute The <th> anchor attribute cannot be generated.

"colspan" Attribute The <th> "colspan" attribute is generated from the horizontal alignment operator of a cell in a table, if present. The following example

is converted to

• Cell ]]>

"rowspan" Attribute The <th> "rowspan" attribute is generated from the horizontal alignment operator of a cell in a table, if present. The following example

is converted to

• Cell ]]>

<thead> The <thead> element is generated from a table with header. The following example

is converted to

• Header Cell ]]>

"anchor" Attribute The <tfoot> anchor attribute cannot be generated.

<title> The <title> element and its attributes are provided in the docinfo file or in a passthrough block containing a top <reference> element.

<toc> The <toc> element is provided in the docinfo file.

<tr> The <tr> element is generated from a table with rows. The following example

is converted to

• Cell ]]>

"anchor" Attribute The <tr> anchor attribute cannot be generated.

<tt> The <tt> element is generated from a monospace text formatting. The following example

is converted to

• The function main() ]]>

<u> The <u> element is generated from an u inline macro. The inline macro is an extension to standard AsciiDoc. The following example

is converted to

• This is test ]]>

"anchor" Attribute The <u> "anchor" attribute is generated from the ID of a u inline macro, if present. The following example

is converted to

• This is test ]]>

"ascii" Attribute The <u> "ascii" attribute is generated from the ascii attribute of a u inline macro, if present. The following example

is converted to

• This is test ]]>

"format" Attribute The <u> "format" attribute is generated from the format attribute of a u inline macro, if present. The following example

is converted to

• This is test ]]>

<ul> The <ul> element is generated from an unordered list. The following example

is converted to

• One line

]]>

"anchor" Attribute The <ul> "anchor" attribute is generated from the ID of an unordered list, if present. The following example

is converted to

• test

]]>

"bare" Attribute The <ul> "bare" attribute is generated from the unstyled style on an unordered list, if present. The following example

is converted to

• test

]]>

"empty" Attribute The <ul> "empty" attribute is generated from the no-bullet style on an unordered list, if present. The following example

is converted to

• test

]]>

"indent" Attribute The <ul> "indent" attribute is generated from the indent attribute on an unordered list, if present. The indent attribute on am unordered is an extension to standard AsciiDoc. The following example

is converted to

• test

]]>

"spacing" Attribute The <ul> "spacing" attribute is generated from the spacing attribute on an unordered list, if present. The spacing attribute on an unordered list is an extension to standard AsciiDoc. The following example

is converted to

• test

]]>

<uri> The <uri> element inside a <front> element is copied from a docinfo file. The <uri> element can also be used inside a <reference> element in a passthrough block in the bibliography. The <uri> element can also be used inside an <author> element in a passthrough block in a section.

<workgroup> The <workgroup> element inside a <front> element is copied from a docinfo file. The <workgroup> element can also be used inside a <reference> element in a passthrough block in the bibliography. The <workgroup> element can also be used inside an <author> element in a passthrough block in a section.

<xref> The <xref> element is generated from a cross-reference. The following example

• >.]]>

is converted to

• As described in . ]]>

"format" Attribute The <xref> "format" attribute is generated from the format attribute in a cross reference, if present. The format attribute on a cross reference is an extension to standard AsciiDoc. The following example

• >.]]>

is converted to

• As described in . ]]>

"relative" Attribute The <xref> "relative" attribute is generated from the relative attribute in a cross reference, if present. The relative attribute on a cross reference is an extension to standard AsciiDoc. The following example

• >.]]>

is converted to

• As described in . ]]>

"section" Attribute The <xref> "section" attribute is generated from the section attribute in a cross reference, if present. The section attribute on a cross reference is an extension to standard AsciiDoc. The following example

• >.]]>

is converted to

• As described in . ]]>

"sectionFormat" Attribute The <xref> "sectionFormat" attribute is generated from the section-format attribute in a cross reference, if present. The section-format attribute on a cross reference is an extension to standard AsciiDoc. The following example

• >.]]>

is converted to

• As described in . ]]>

"target" Attribute The <xref> "target" attribute is generated from the target in a cross reference. The following example

• >.]]>

is converted to

• As described in . ]]>

Informative References

marc@petit-huguenin.org

AsciiDoc is a human-readable document format, semantically equivalent to DocBook XML, but using plain-text mark-up conventions. AsciiDoc documents can be created using any text editor and read “as-is”, or rendered to HTML or any other format supported by a DocBook tool-chain, i.e. PDF, TeX, Unix manpages, e-books, slide presentations, etc. Common file extensions for AsciiDoc files are txt(as encouraged by AsciiDoc's creator) and adoc. Accessed 23 April 2021 This document defines the "xml2rfc" version 3 vocabulary: an XML-based language used for writing RFCs and Internet-Drafts. It is heavily derived from the version 2 vocabulary that is also under discussion. This document obsoletes the v2 grammar described in RFC 7749. Accessed 1 January 2023 Corporation for Digital Scholarship Accessed 20 January 2023 Accessed 29 January 2023 This document describes the fundamental and unique style conventions and editorial policies currently in use for the RFC Series. It captures the RFC Editor's basic requirements and offers guidance regarding the style and structure of an RFC. Additional guidance is captured on a website that reflects the experimental nature of that guidance and prepares it for future inclusion in the RFC Style Guide. This document obsoletes RFC 2223, "Instructions to RFC Authors". Accessed 29 January 2023 This document describes the "xml2rfc" version 3 vocabulary as implemented in xml2rfc tools at the time of publication. Editorial Note This note is to be removed before publishing as an RFC. Discussion of this draft takes place on the rswg@rfc-editor.org mailing list, which has its home pags at \textlesshttps://www.ietf.org/mailman/listinfo/rswg\textgreater. Source code and issues list for this draft can be found at \textlesshttps://github.com/jrlevine/draft-rswg-xml2rfcv3-implemented\textgreater. Example References This memo describes a generic application protocol kernel for connection-oriented, asynchronous interactions called the BEEP (Blocks Extensible Exchange Protocol) core. [STANDARDS-TRACK] This document specifies an update to the round-trip time (RTT) estimation algorithm used for TFRC (TCP-Friendly Rate Control) congestion control by the Datagram Congestion Control Protocol (DCCP). It updates specifications for the CCID-3 and CCID-4 Congestion Control IDs of DCCP. The update addresses parameter-estimation problems occurring with TFRC-based DCCP congestion control. It uses a recommendation made in the original TFRC specification to avoid the inherent problems of receiver-based RTT sampling, by utilising higher-accuracy RTT samples already available at the sender. It is integrated into the feature set of DCCP as an end-to-end negotiable extension. [STANDARDS-TRACK] This document clarifies the Zero Window Probes (ZWPs) described in RFC 1122 ("Requirements for Internet Hosts -- Communication Layers"). In particular, it clarifies the actions that can be taken on connections that are experiencing the ZWP condition. Rather than making a change to the standard, this document clarifies what has been until now a misinterpretation of the standard as specified in RFC 1122. This document is not an Internet Standards Track specification; it is published for informational purposes. This document describes the fundamental and unique style conventions and editorial policies currently in use for the RFC Series. It captures the RFC Editor's basic requirements and offers guidance regarding the style and structure of an RFC. Additional guidance is captured on a website that reflects the experimental nature of that guidance and prepares it for future inclusion in the RFC Style Guide. This document obsoletes RFC 7322, "RFC Style Guide". This RFC is the revised basic definition of The Domain Name System. It obsoletes RFC-882. This memo describes the domain style names and their used for host address look up and electronic mail forwarding. It discusses the clients and servers in the domain name system and the protocol used between them. This RFC is the revised specification of the protocol and format used in the implementation of the Domain Name System. It obsoletes RFC-883. This memo documents the details of the domain name client - server communication. This memo splits message submission from message relay, allowing each service to operate according to its own rules (for security, policy, etc.), and specifies what actions are to be taken by a submission server. Message relay is unaffected, and continues to use SMTP over port 25. When conforming to this document, message submission uses the protocol specified here, normally over port 587. This separation of function offers a number of benefits, including the ability to apply specific security or policy requirements. [STANDARDS-TRACK]

Command Line Tool The "asciidoctor-xml" Ruby gem is distributed as a git repository that can be installed as follow:

Then an AsciiDoc file can be converted into an XML2RFC v3 file like this: Note that, if present, the value of the "doc-name" document header attribute will be used as the name of the output file. This permits to keep the same file name but generate different versions by just changing the doc-name header. The command will write the name of the generated file on the standard output, so it can be used to generate the final document: The "-P" option generates the text file without pagination, which permits to do a local diff between different versions of a draft (e.g., with the ":vert diffs <previous-file>" command in VIM).

Build a Bibliography with Zotero The simplest way to build a bibliography is to use and the AsciiBib exporter provided in the git repository. The Better BibTex for Zotero add-on is needed to manage the citation keys for the bibliographic items exported. First the "AsciiBib.js" file must be copied, or better symbolically linked, in the "data/translators" directory under the Zotero configuration directory (most likely "~/.zotero"). To build a bibliography for an Internet-Draft, first create a new collection in Zotero and add bibliographic items in it. E.g., a collection named "mapping-xml2rfc-asciidoc" contains a sub-collection named "informative", which itself contains all the references for this document. Bibliographic items can be created from scratch, scrapped from the Internet using web translators, or imported from an existing bibliography. The git repository distributed with contains a Zotero importer that can create the full collection of RFCs items in Zotero from the "rfc-index.xml" file. A Zotero collection can then be converted into a AsciiBib file by right-clicking on it, choosing "Export Collection...", select the "AsciiBib" format, then finally the target directory. This will create an AsciiDoc file that can be imported in a bibliography section:

The Zotero exporter tries to export bibliographic items in a form that is as close as possible to the RFC Style guides . The bibliography in this document shows examples of bibliographic items converted from Zotero:

RFC with one author or editor:

RFC with two authors or editors:

RFC with three or more authors or editors:

STD or BCP that contains one RFC:

STD or BCP that contains two or more RFCs:

Internet-Draft:

Acknowledgments No technology that cannot explain its own results (LLM, AI/ML) have been involved in the creation of this document or its associated tooling.

Changelog

draft-petithuguenin-xml2rfc-asciidoc-03:

• Document:
  • Upadte?
• Tooling:
  • ?update

draft-petithuguenin-xml2rfc-asciidoc-02:

• Document:
  • Update RFC 7991 successor reference.
• Tooling:
  • Process text in definition list items with attached blocks.

draft-petithuguenin-xml2rfc-asciidoc-01:

• Document:
  • Add explanations for citation inclusion.
  • Add new appendix that explains how to use Zotero to generate a bibliography.
• Tooling:
  • Implemented citation extraction.
  • The name of the generated file is written on the standard output.
  • AsciiBib Zotero exporter.