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".
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.
= A Standard for the Transmission of IP Datagrams on Avian Carriers
David Waitzman dwaitzman@BBN.COM
:doctype: internet-draft
:abbrev: IP Datagrams on Avian Carriers
:obsoletes: 10, 120
:updates: 2010, 2120
:status: 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.<>
[bibliography]
== Normative References
++++
Key words for use in RFCs to Indicate Requirement LevelsIn 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.
++++
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:
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.
NOTE: The gem validates all RFC XML generated through the RELAXNG schema definitions
of RFC XML. While the gem attempts to generate valid RFC XML, some Asciidoctor
text may not align with the RFC XML document model, and any highlighted syntax
errors will also need to be rectified in postediting, before processing the
generated XML further.
=== Document Type: rfc or internet-draft (Mandatory)
Set the doctype attribute to set status of this document:
:doctype: internet-draft sets the document as an Internet-Draft (default value):
rfc/front/seriesInfo@name attribute will be set to Internet-Draft (in v3)
rfc/front/seriesInfo@value will be set to the :name: attribute, stripping any file suffixes, but including any draft number; e.g. draft-ietf-somewg-someprotocol-07 (in v3)
rfc@docName will be set to the :name: attribute (in v2)
:doctype: rfc sets the document as an RFC:
rfc/front/seriesInfo@name attribute will be set to RFC (in v3)
rfc/front/seriesInfo@value will be set to the :name: attribute, stripping the initial rfc- prefix and any file suffixes (in v3)
rfc@number will be set to the :name: attribute (in v2)
=== 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.
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
| :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
| :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
|artworkdelimiter | when producing txt or nroff files, use this string to delimit artwork
|artworklines | when producing txt or nroff files, add this many blank lines around artwork
|authorship | render author information
|autobreaks | automatically force page breaks to avoid widows and orphans (not perfect)
|background | when producing a html file, use this image
|colonspace | put two spaces instead of one after each colon (":") in txt or nroff files
|comments | render information
|compact | when producing a txt/nroff file, try to conserve vertical whitespace (the default value is the current value of the rfcedstyle PI)
|docmapping | use hierarchical tags (e.g.,
,
, 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
