{"id":13311764,"url":"https://github.com/metanorma/asciidoctor-rfc","last_synced_at":"2025-03-10T17:30:45.618Z","repository":{"id":62553596,"uuid":"95404862","full_name":"metanorma/asciidoctor-rfc","owner":"metanorma","description":"AsciiRFC: an AsciiDoc/asciidoctor backend to produce RFC XML v3 (RFC 7991) and v2 (RFC 7749)","archived":true,"fork":false,"pushed_at":"2019-12-23T14:48:36.000Z","size":1220,"stargazers_count":15,"open_issues_count":1,"forks_count":7,"subscribers_count":14,"default_branch":"master","last_synced_at":"2024-04-29T22:36:38.428Z","etag":null,"topics":["asciidoc","asciidoctor","ietf","ietf-rfcs","internet-draft","rfc","rfc-process","ribose-open"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-2-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/metanorma.png","metadata":{"files":{"readme":"README.adoc","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-06-26T03:26:22.000Z","updated_at":"2023-03-20T21:32:21.000Z","dependencies_parsed_at":"2022-11-03T04:45:26.369Z","dependency_job_id":null,"html_url":"https://github.com/metanorma/asciidoctor-rfc","commit_stats":null,"previous_names":["riboseinc/asciidoctor-rfc"],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/metanorma%2Fasciidoctor-rfc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/metanorma%2Fasciidoctor-rfc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/metanorma%2Fasciidoctor-rfc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/metanorma%2Fasciidoctor-rfc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/metanorma","download_url":"https://codeload.github.com/metanorma/asciidoctor-rfc/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":242892578,"owners_count":20202560,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["asciidoc","asciidoctor","ietf","ietf-rfcs","internet-draft","rfc","rfc-process","ribose-open"],"created_at":"2024-07-29T18:02:29.493Z","updated_at":"2025-03-10T17:30:45.196Z","avatar_url":"https://github.com/metanorma.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"= AsciiRFC: Writing Internet-Drafts and RFCs in AsciiDoc\n:source-highlighter: coderay\n:icons: font\n\nWARNING: This gem has been subsumed into the https://www.metanorma.com[Metanorma]\npublishing framework. Development of AsciiRFC is continued at the\nhttps://github.com/metanorma/metanorma-ietf[metanorma-ietf] gem. Please see\nthe new repo for details on usage instructions. Thank you for your support.\n\nWARNING: While the RFC XML v2 output of this gem is still valid, the RFC XML v3\noutput of the gem will not work with the updated `xml2rfc` tool, as this gem'\ndoes not include the modifications to RFC XML v3 subsequent to RFC 7991.\nUse metanorma-ietf to generate valid RFC XML v3 output.\n\nasciidoctor-rfc lets you write Internet-Drafts and RFCs in AsciiDoc, the\n\"`http://asciidoctor.org/[asciidoctor]-way`\".\n\nimage:https://img.shields.io/gem/v/asciidoctor-rfc.svg[\"Gem Version\", link=\"https://rubygems.org/gems/asciidoctor-rfc\"]\nimage:https://img.shields.io/travis/metanorma/asciidoctor-rfc/master.svg[\"Build Status\", link=\"https://travis-ci.org/metanorma/asciidoctor-rfc\"]\nimage:https://codeclimate.com/github/metanorma/asciidoctor-rfc/badges/gpa.svg[\"Code Climate\", link=\"https://codeclimate.com/github/metanorma/asciidoctor-rfc\"]\n\n\n== Introduction\n\nThe \"`xml2rfc`\" Vocabulary (hereinafter \"`RFC XML`\") is an XML-based language\nused for writing\nhttps://www.ietf.org/id-info/guidelines.html[Internet-Drafts]\nand https://tools.ietf.org/html/rfc7322[RFCs (RFC7322)].\n\nThis gem allows you to author these types of documents in AsciiDoc, and outputs\nRFC XML output in both v3 and v2 formats:\n\n* v3 RFC XML (https://tools.ietf.org/html/rfc7991[RFC 7991])\n* v2 RFC XML (https://tools.ietf.org/html/rfc7749[RFC 7749])\n\nIts syntax is designed to be \"`native-asciidoctor`\" as much as possible, with\nsome templated use of attributes to convey added information for RFC XML\noutput.\n\nWe refer to the version of Asciidoc markup processed by this gem as AsciiRFC.\n\nThis README documents the AsciiRFC markup in full detail. For further\ninformation about AsciiRFC, please refer to the\nhttps://datatracker.ietf.org/doc/draft-ribose-asciirfc/[AsciiRFC IETF Internet-Draft].\n\n\n== Installation\n\nAdd this line to your application's Gemfile:\n\n[source,ruby]\n----\ngem \"asciidoctor-rfc\"\n----\n\nAnd then execute:\n\n[source,console]\n----\n$ bundle\n----\n\nOr install it yourself as:\n\n[source,console]\n----\n$ gem install asciidoctor-rfc\n----\n\n\n== Quick Start / Template\n\nClone the\nhttps://github.com/metanorma/rfc-asciirfc-minimal[`rfc-asciirfc-minimal`]\nrepository as a template, and populate it for your Asciidoc RFCs and\nInternet-Drafts:\n\n[source,console]\n----\n$ git clone https://github.com/metanorma/rfc-asciirfc-minimal\n----\n\nSee the https://github.com/metanorma/rfc-asciirfc-minimal[README] of that document for\nmore information.\n\n== Quick Example\n\nIllustrating with v2 RFC XML, and Internet Draft rather than RFC\n\n[source,asciidoc]\n----\n= A Standard for the Transmission of IP Datagrams on Avian Carriers\nDavid Waitzman \u003cdwaitzman@BBN.COM\u003e\n:doctype: internet-draft\n:abbrev: IP Datagrams on Avian Carriers\n:obsoletes: 10, 120\n:updates: 2010, 2120\n:status: informational\n:name: internet-draft-avian-transmission-00\n:ipr: trust200902\n:area: Internet\n:workgroup: Network Working Group\n:keyword: avians, datagrams\n:revdate: 1990-04-01T00:00:00Z\n:organization: BBN STC\n:phone: (617) 873-4323\n:uri: http://bbn.com\n:street: 10 Moulton Street\n:city: Cambridge\n:code: MA 02238\n\n[abstract]\nAvian carriers can provide high delay, low throughput, and low\naltitude service.  The connection topology is limited to a single\npoint-to-point path for each carrier, used with standard carriers,\nbut many carriers can be used without significant interference with\neach other, outside of early spring.  This is because of the 3D ether\nspace available to the carriers, in contrast to the 1D ether used by\nIEEE802.3.  The carriers have an intrinsic collision avoidance\nsystem, which increases availability.  Unlike some network\ntechnologies, such as packet radio, communication is not limited to\nline-of-sight distance.  Connection oriented service is available in\nsome cities, usually based upon a central hub topology.\n\nNOTE: Yes, this is an April Fool's RFC.\n\n[[frame]]\n== Frame Format\n\nThe IP _datagram_ is *printed*, on a small scroll of paper, in\nhexadecimal, with each octet separated by whitestuff and blackstuff.\nThe scroll of paper is wrapped around one leg of the avian carrier.\nA band of duct tape is used to secure the datagram's edges.  The\nbandwidth is limited to the leg length.  The MTU is variable, and\nparadoxically, generally increases with increased carrier age.  A\ntypical MTU is 256 milligrams.  Some datagram padding may be needed.\u003c\u003cRFC7253\u003e\u003e\n\n[bibliography]\n== Normative References\n++++\n\u003creference anchor=\"RFC2119\" target=\"https://www.rfc-editor.org/info/rfc2119\"\u003e\n  \u003cfront\u003e\n    \u003ctitle\u003eKey words for use in RFCs to Indicate Requirement Levels\u003c/title\u003e\n    \u003cauthor initials=\"S.\" surname=\"Bradner\" fullname=\"S. Bradner\"\u003e\n      \u003corganization/\u003e\n    \u003c/author\u003e\n    \u003cdate year=\"1997\" month=\"March\"/\u003e\n    \u003cabstract\u003e\n      \u003ct\u003eIn 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.\u003c/t\u003e\n    \u003c/abstract\u003e\n  \u003c/front\u003e\n  \u003cseriesInfo name=\"BCP\" value=\"14\"/\u003e\n  \u003cseriesInfo name=\"RFC\" value=\"2119\"/\u003e\n  \u003cseriesInfo name=\"DOI\" value=\"10.17487/RFC2119\"/\u003e\n\u003c/reference\u003e\n++++\n\n[bibliography]\n== Informative References\n++++\n\u003creference anchor='RFC7253' target='https://tools.ietf.org/html/rfc7253'\u003e\n  \u003cfront\u003e\n    \u003ctitle\u003eGuidelines for Writing an IANA Considerations Section in RFCs\u003c/title\u003e\n    \u003cauthor initials=\"T.\" surname=\"Krovetz\"\u003e\n      \u003corganization\u003eSacramento State\u003c/organization\u003e\n    \u003c/author\u003e\n    \u003cauthor initials=\"P.\" surname=\"Rogaway\"\u003e\n      \u003corganization\u003eUC Davis\u003c/organization\u003e\n    \u003c/author\u003e\n    \u003cdate month='May' year='2014'/\u003e\n  \u003c/front\u003e\n  \u003cseriesInfo name=\"RFC\" value=\"7253\"/\u003e\n\u003c/reference\u003e\n++++\n----\n\n\n== Usage\n\nConverting your AsciiDoc to RFC XML is a simple as running the appropriate\n`./bin/asciidoctor-rfc` script using Ruby, and passing your\nAsciiDoc document file as the first argument.\n\nUsually you would use the `asciidoctor` executable, specifying this gem as a\nlibrary:\n\n[source,console]\n----\n$ asciidoctor -b rfc3 -r 'asciidoctor-rfc' a.adoc  # RFC XML v3 output\n$ asciidoctor -b rfc2 -r 'asciidoctor-rfc' a.adoc  # RFC XML v2 output\n----\n\nor through the included bin-stub:\n\n[source,console]\n----\n$ ./bin/asciidoctor-rfc3 draft-example-00.adoc  # RFC XML v3 output\n$ ./bin/asciidoctor-rfc2 draft-example-00.adoc  # RFC XML v2 output\n----\n\nWhen the script completes, you should see the RFC XML file `draft-example-00.xml` in the\nsame directory.\n\n\n== Syntax\n\nThe converter follows native AsciiDoc/asciidoctor syntax as much as possible,\nincluding built-in attributes and styles.\n\nExtension commands are provided to fully support writing an Internet-Draft/RFC\nin AsciiDoc/asciidoctor syntax.\n\n[NOTE]\n====\nThe document model of Asciidoctor and RFC XML are different. In particular,\n\n* Asciidoctor and RFC XML differ in where they allow anchors to be placed:\nAsciidoctor does not allow anchors within tables and lists, and RFC XML v3 does\nnot permit anchors for the `note` or `abstract` elements, while RFC XML v2\nuses anchors for much fewer block elements (e.g. `artwork`, `list`.)\n* Asciidoctor has a more restrctive block model: it regards elements such as\nadmonitions, lists, and tables as blocks, and does not allow them to be nested\nwithin paragraphs.\n\nAs a result, it may be necessary to postedit the RFC XML output, if the block\nmodel produced does not reflect the intended structure accurately.\n====\n\nNOTE: The gem validates all RFC XML generated through the RELAXNG schema definitions\nof RFC XML. While the gem attempts to generate valid RFC XML, some Asciidoctor\ntext may not align with the RFC XML document model, and any highlighted syntax\nerrors will also need to be rectified in postediting, before processing the\ngenerated XML further.\n\nNOTE: A summary guide to authoring RFC XML in Asciidoctor is also available at\nhttps://tools.ietf.org/html/draft-ribose-asciirfc-02 (with source at\nhttps://github.com/metanorma/rfc-asciidoc-rfc ).\n\n\n=== Document Type: `rfc` or `internet-draft` (Mandatory)\n\nSet the `doctype` attribute to set status of this document:\n\n`:doctype: internet-draft` sets the document as an Internet-Draft (default value):\n\n* `rfc/front/seriesInfo@name` attribute will be set to `Internet-Draft` (in v3)\n* `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)\n* `rfc@docName` will be set to the `:name:` attribute (in v2)\n\n`:doctype: rfc` sets the document as an RFC:\n\n* `rfc/front/seriesInfo@name` attribute will be set to `RFC` (in v3)\n* `rfc/front/seriesInfo@value` will be set to the `:name:` attribute, stripping the initial `rfc-` prefix and any file suffixes (in v3)\n* `rfc@number` will be set to the `:name:` attribute (in v2)\n\n\n=== Global Options\n\n[cols=\"2\", options=\"header\"]\n|===\n\n| Attribute\n| Purpose\n\n|`:no-rfc-bold-bcp14:`\n| Optional. Default value `true`. Allowed values: `true`, `false`.\nOverride default assumption that boldface uppercase BCP14 word is to be rendered with `bcp14` tag.\n\n|`:smart-quotes:`\n|Optional. Default value `true`. Allowed values: `true`, `false`.\nPermit smart quotes, when they are specified explicitly in Asciidoc (as `\"`...`\"`, `'`...`'`.)\nWhen disabled, smart quotes are rendered as straight quotes, and Asciidoc's default conversion\nof straight apostrophes to smart is undone.\n\n|`:inline-definition-lists:`\n|Optional. Default value `false`. Allowed values: `true`, `false`.\nOnly applies to v2. By default, `\u003cvspace blankLines=\"1\"\u003e` is inserted after\nthe definition in a v2 definition list, to satisfy the requirement from `idnits` validation\nthat definition terms be separated by a carriage return from the definition. That is, by\ndefault inline definition lists are rendered as paragraphing definition lists. If the option is\non, the additional `vspace` element is not added, and inline definition lists are left as is.\n\n|`:flush-caches:`\n|Optional. Default value `false`. Allowed values: `true`, `false`.\nDelete and reload the caches of references to be included externally, and of workgroups,\nduring processing of this document.\nThe caches are stored in `~/.asciidoc-rfc-biblio-cache.json` and `~/.asciidoc-rfc-workgroup-cache.json`.\n\n|`:biblio-dir:`\n|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.\n\n|`:normative:`\n|Optional. Comma-delimited list of reference anchors. Used in conjunction with `:biblio-dir:`, which uses a single directory for all references: this attribute\nlists those references which are to be considered normative, and listed under the _Normative References_ heading.\n\n|===\n\nAny of these global options can also be included in the command line call, for either\nthe asciidoctor executable or the local bin-stubs, through the command line option `-a`;\ne.g.\n\n[source,console]\n----\n$ asciidoctor -a flush-biblio=true -b rfc3 -r 'asciidoctor-rfc' a.adoc\n$ ./bin/asciidoctor-rfc2 -a smart-quotes=false draft-example-00.adoc\n----\n\n[[caches]]\n==== Caches\n\nThe cache of externally addressable bibliographic information is built from screenscraping the contents of:\n\n* https://xml2rfc.tools.ietf.org/public/rfc/bibxml/\n* https://xml2rfc.tools.ietf.org/public/rfc/bibxml2/\n* https://xml2rfc.tools.ietf.org/public/rfc/bibxml3/\n* https://xml2rfc.tools.ietf.org/public/rfc/bibxml4/\n* https://xml2rfc.tools.ietf.org/public/rfc/bibxml5/\n\nThe cache of current IETF and IRTF workgroups is built from screenscraping the contents of:\n\n* https://tools.ietf.org/wg/\n* https://irtf.org/groups\n\nThe caches are not rebuilt daily, as the bibliographic cache is with xml2rfc.\nIf you want to refresh the caches,\n\n* delete\nyour `~/.asciidoc-rfc-biblio-cache.json` and `~/.asciidoc-rfc-workgroup-cache.json` files;\n* insert the document attribute `:flush-caches: true` into\nthe header of the document being processed; or\n* run the asciidoctor executable with option `-a flush-caches=true`\n(which has the same effect).\n\n=== Basic Document Attributes\n\n`asciidoctor-rfc` allows setting the RFC XML document header using the following\ndocument attributes. Complying with AsciiDoc syntax, no blank lines are\npermitted between the title, listing of authors, and the document attributes.\nAlso following AsciiDoc syntax, character entities will be ignored in the document\nheader: `\u0026nbsp;` in the header for example will be rendered as `\u0026amp;nbsp;`.\n\nShared RFC XML v3/v2 syntax:\n\n[cols=\"3\", options=\"header\"]\n|===\n\n| Attribute\n| Purpose\n| RFC XML v2/v3 element\n\n| `= Document Title`\n| Mandatory. Title of document.\n| `rfc/front/title`\n\n| `:abbrev:`\n| Mandatory. Abbreviation of document title. Usually the document name without\nthe keyword `draft-`.\n| `rfc/front/title@abbrev`\n\n| `:ipr:`\n| Mandatory. IP status of document. See\nhttps://tools.ietf.org/html/rfc7991#section-2.45.5[here]. Defaults to\n`trust200902`.\n| `rfc@ipr`\n\n| `:ipr-extract:`\n| Optional. Identifies a section that can be extracted from text. See\nhttps://tools.ietf.org/html/rfc7991#section-2.45.6[here].\n| `rfc@iprExtract`\n\n| `:obsoletes:`\n| Optional. A comma-separated list of RFC numbers or Internet-Draft names that\nthis document obsoletes. Delimited by `comma + space`.\n| `rfc@obsoletes`\n\n| `:updates:`\n| Optional. A comma-separated list of RFC numbers or Internet-Draft names that\nthis document updates. Delimited by `comma + space`.\n| `rfc@updates`\n\n| `:submission-type:`\n| Optional. Document stream of document described in\nhttps://tools.ietf.org/html/rfc7841[RFC7841]. Allowed values: `IETF` (default),\n`independent`, `IAB`, and `IRTF`.\n| `rfc@submissionType`\n\n| `:revdate:`\n| Optional. Latest revision date of document. Default value is current time.\nAccepts ISO 8601 date. Also accepts YYYY year, and YYYY[-]MM year/month.\nFor consistency with AsciiDoc, `:revdate:` is given as\nan ISO 8601 date; the converter breaks it down into day, month name and year\n| `front/date@day`, `front/date@month`, `front/date@year`\n\n| `:area:`\n| Optional. Comma delimited text on which IETF area this document relates to. Value should\n\"be either the full name or the abbreviation of one of the IETF areas as\nlisted on \u003chttp://www.ietf.org/iesg/area.html\u003e\". See\nhttps://tools.ietf.org/html/rfc7991#section-2.4[here].\n| `front/area`\n\n| `:workgroup:`\n| Optional. Comma delimited text on which IETF or IRTF workgroup or research group this\ndocument originates from. See https://tools.ietf.org/html/rfc7991#section-2.65[here].\n| `front/workgroup`\n\n| `:keyword:`\n| Optional. Comma delimited text for singular keywords used for RFC index and\nmetadata.\n| `front/keyword`\n\n|===\n\n=== Processing Instructions\nThe `xml2rfc` tool accepts processing instructions of the form `\u003c?rfc keyword='value'?\u003e`:\nsee https://xml2rfc.tools.ietf.org/authoring/README.html#processing.instructions .\n(Of these, `sort-refs`, `sym-refs` and `toc-include`  are also present in the\nv3 RFC XML specifcation, as attributes of the\nroot `rfc` element: \u003c\u003cv3documentattributes,v3-specific document attributes\u003e\u003e.)\nThose processing instructions which apply to the entire document can also be\nspecified for this gem as document options.\n\n|===\n|keyword |meaning\n\n|artworkdelimiter |\twhen producing txt or nroff files, use this string to delimit artwork\n|artworklines |\twhen producing txt or nroff files, add this many blank lines around artwork\n|authorship |\trender author information\n|autobreaks |\tautomatically force page breaks to avoid widows and orphans (not perfect)\n|background |\twhen producing a html file, use this image\n|colonspace |\tput two spaces instead of one after each colon (\":\") in txt or nroff files\n|comments |\trender \u003ccref\u003e information\n|compact |\twhen producing a txt/nroff file, try to conserve vertical whitespace (the default value is the current value of the rfcedstyle PI)\n|docmapping |\tuse hierarchical tags (e.g., \u003ch1\u003e, \u003ch2\u003e, etc.) for (sub)section titles\n|editing |\tinsert editing marks for ease of discussing draft versions\n|emoticonic |\tautomatically replaces input sequences such as \\|*text\\| by, e.g., \u003cstrong\u003etext\u003c/strong\u003e in html output\n|footer |\toverride the center footer string\n|header |\toverride the leftmost header string\n|inline |\tif comments is \"yes\", then render comments inline; otherwise render them in an \"Editorial Comments\" section\n|iprnotified |\tinclude boilerplate from Section 10.4(d) of http://tools.ietf.org/html/rfc2026\n|linkmailto |\tgenerate mailto: URL, as appropriate\n|linefile |\ta 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)\n|notedraftinprogress |\tgenerates \"(work in progress)\", as appropriate\n|private |\tproduce a private memo rather than an RFC or Internet-Draft\n|refparent |\ttitle of the top-level section containing all references\n|rfcedstyle |\tattempt 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 \u003creferences\u003e sections.\n|rfcprocack |\tif 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\n|slides |\twhen producing a html file, produce multiple files for a slide show\n|sort-refs |\t(`sortrefs`) sort references\n|strict |\ttry to enforce the ID-nits conventions and DTD validity\n|subcompact |\tif 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)\n|sym-refs |\t(`symrefs`) use anchors rather than numbers for references\n|text-list-symbols |\tmodify 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.\n|toc-include |\t(`toc`) generate a table-of-contents\n|tocappendix |\tcontrol whether the word \"Appendix\" appears in the table-of-content\n|toc-depth |\tif toc is \"yes\", then this determines the depth of the table-of-contents\n|tocindent |\tif toc is \"yes\", then setting this to \"yes\" will indent subsections in the table-of-contents\n|tocnarrow |\taffects horizontal spacing in the table-of-content\n|tocompact |\tif toc is \"yes\", then setting this to \"no\" will make it a little less compact\n|topblock |\tput the famous header block on the first page\n|useobject |\twhen producing a html file, use the \u003cobject\u003e html element with inner replacement content instead of the \u003cimg\u003e html element, when a source xml element includes an src attribute\n|===\n\nExceptionally, `compact`, `toc-include`, `sym-refs`, `sort-refs` and `strict` are is set by default to `yes`, `subcompact` to `no`, and `toc-depth` to 4.\n\nThe additional document option `rfc2629xslt` (default value: true) injects into the document header the processing\ninstruction `\u003c?xml-stylesheet type=\"text/xsl\" href=\"rfc2629.xslt\" ?\u003e`, which impacts on the output of xml2rfc.\n\n=== Document Name / Number (Mandatory)\n\nThe `name` attribute sets the document's name. This should be a number if\nthe document is an RFC, and a name (in the form of `draft-ietf-somewg-someprotocol-07`)\nif it is an Internet-Draft.\n\nWhen `doctype` is set to:\n\n* `internet-draft`: the value should be in the form `draft-ietf-somewg-someprotocol-07`.\n** v3: the `front/seriesInfo@value` will be set to this value.\n** v2: the `rfc@docName` will be set to this value.\n\n* `rfc`: the value should be a number like `7991` as described\n  https://tools.ietf.org/html/rfc7991#section-2.47.6[here]\n** v3: the `front/seriesInfo@value` will be set to this value.\n** v2: the `rfc@number` will be set to this value.\n\n\n=== Document Status\n\nSet the `status` attribute to set the current status of this document.\n\nThe following values are allowed: `standard`, `informational`, `experimental`, `bcp`, `fyi`,\n`full-standard` (v3 only), `historic` (v2 only).\n\n* In v3, this sets the first `front/seriesInfo` element with `@status` as one\n  of: `standard`, `informational`, `experimental`, `bcp`, `fyi`, `full-standard`.\n* In v2, this sets the `rfc@category` value as one of `std`, `info`, `exp`, `bcp`, `historic`.\n\n\n=== Intended Series\n\nSet the `intended-series` attribute to set the intended series of this\ndocument.\n\nThe following values are allowed: `standard`, `informational`, `experimental`, `bcp`, `fyi`, `full-standard`.\n\nWhen `doctype` is set to:\n\n* `internet-draft`: this value can be one of `standard`, `full-standard`, `bcp`, `fyi`, `informational`,\n  `experimental`, or `historic` to indicate the intended series once the document is published as an RFC.\n\n** In v3, this sets a second `front/seriesInfo` element with `@status` as one of those values, and an empty `@name`, to indicate this.\n** In v2, this sets the `front@category` value to one of `std`, `bcp`, `info`, `exp`, `historic`.\n\n* `rfc`: this value can be either:\n** 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`.\n** `exp`, `info`, or `historic`. (`experimental` and `informational` will be accepted by the gem as synonyms.)\n\n** In v3, this sets a second `front/seriesInfo` element with `@status` as one of those values, and an empty `@name`, to indicate this.\n** 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.)\n\n=== Document Submission Type / Stream\n\nSet document submission type via the `submission-type` document attribute.\n\nThe following values are allowed: `IETF` (default), `independent`, `IAB`, and `IRTF`.\n\n* In v3, the `rfc@submissionType` and `rfc/front/seriesInfo@stream` attributes are set to this value.\n* In v2, the `rfc@submissionType` is set to this value\n\n=== Document Consensus\n\nSet document consensus type via the `consensus` document attribute.\n\nThese values are accepted: `false`, `true`.\n\n* In v3, this is the value set for the `rfc@consensus` attribute.\n* In v2, this is the value set for the `rfc@consensus` attribute, but `false` is converted to  `no` and `true` is converted to `yes`.\n\n=== Document Language\n\nSet the document language using the `xml-lang` document attribute.\n\nBy default this is `en`.\n\n* In v3 and v2, this is the value set for the `rfc@xml:lang` attribute.\n\nWhile v3 supports marking specific elements with their own `xml:lang` attribute, this is not yet supported by our gem.\n\n\n=== Document Attributes for v2 only\n\nThese attributes are only supported for the v2 converter.\n\n[cols=\"3\", options=\"header\"]\n|===\n\n| Attribute\n| Purpose\n| RFC XML v3 element\n\n|`:series-no:`\n| Optional. The document series is defined by the \"category\" attribute;\n   \"seriesNo\" is only applicable to the values \"info\" (\"FYI\" series),\n   \"std\" (\"STD\" series), and \"bcp\" (\"BCP\" series).\n| `rfc@seriesNo`\n|===\n\n[#v3documentattributes]\n=== Document Attributes for v3 only\n\nThese attributes are only supported for the v3 converter.\n\n[cols=\"3\", options=\"header\"]\n|===\n\n| Attribute\n| Purpose\n| RFC XML v3 element\n\n|`:index-include:`\n| Optional. Defaults to `true`. Values: `true` or `false`. Specifies whether\nformatter should include an index in generated files. If the source file has no\n`\u003ciref\u003e` elements, an index is never generated.\n| `rfc@indexInclude`\n\n|`:sort-refs:`\n| Optional. Defaults to `false`. Values: `true` or `false`. Specifies whether\nthe prep tool should sort references. Supported in v2 as a processing instruction.\n| `rfc@sortRefs`\n\n|`:sym-refs:`\n| Optional. Defaults to `true`. Values: `true` or `false`. Specifies whether\nformatter should use symbolic references (such as \"`[RFC2119]`\") or not\n(such as \"`[3]`\"). Supported in v2 as a processing instruction.\n| `rfc@symRefs`\n\n|`:toc-include:`\n| Optional. Defaults to `true`. Values: `true` or `false`. Specifies whether\nformatter should contain a table of contents. Supported in v2 as a processing instruction.\n| `rfc@tocInclude`\n\n| `:link: _URL_, _URL_ _REL_`\na| Optional. Comma-delimited links to an external document related to this document.\n\nThere are 4 types of values:\n\n. (RFC only) ISSN for this RFC document (`rel` set to `item`, `link` value in\n  form of `urn:issn:`);\n. (RFC only) DOI for this RFC document (`rel` set to `describedBy`, `link`\n  value in form specified by https://tools.ietf.org/html/rfc7669[RFC7669]);\n. (Final Draft) Internet-Draft submitted to become published RFC (`rel` set to\n  `convertedFrom`, `link` value set to \"IETF-controlled web site that retains\n  copies of Internet-Drafts\");\n. (Any status) ISSN (`rel` set to `alternate`, `link` value as any author run web site).\n| `front/link@href = _URL_`, `front/link@rel = _REL_` (if supplied)\n\n|===\n\n\n=== Author Attributes\n\nIn an Internet-Draft/RFC, detailed information of an author is necessary, which\nis not supported by the normal AsciiDoc syntax.\n\nYou will need to provide the following information.\n\n\n==== Multiple Author Names\n\nJust like a normal AsciiDoc, you can provide author information in the author\nheader (sample of 3 authors):\n\n[source,asciidoc]\n----\nfirstname middlename(s) lastname \u003cemail\u003e; firstname middlename(s) lastname \u003cemail\u003e; firstname middlename(s) lastname \u003cemail\u003e\n----\n\nThese will be mapped as follows:\n\n[cols=\"3\", options=\"header\"]\n|===\n\n| Syntax\n| Purpose\n| RFC XML v3/v2 element\n\n| `firstname middlename(s) lastname`\n| Mandatory (at least one). Author's full name. (Middle names are optional.)\n| `front/author@fullname`\n\n| `lastname`\n| Author's last name.\n| `front/author@surname`\n\n| `email`\n| Author's email address.\n| `front/author/address/email`\n\n|===\n\nIf any author names deviate from that pattern, e.g. with an honorific like Dr.,\nthey will not be recognised correctly by the Asciidoc API; use the `fullname`\ndocument attribute instead.\n\n==== Author Attributes\n\nIn `asciidoctor-rfc`, detailed author attributes are given as document\nattributes.\n\nAs multiple authors can be specified, the document attribute to specify the\nfirst author uses a unsuffixed attribute name `:role`, and the second author's\nattributes onwards use a numeric suffix to identify the author: `:role_2`, `:role_3`, etc.\n\nShared RFC XML v3/v2 syntax:\n\n[cols=\"3\", options=\"header\"]\n|===\n\n| Attribute\n| Purpose\n| RFC XML v3/v2 element\n\n| `:fullname{_i}:`\n| Optional. Author's full name. Can set here instead of document header's \"`Author`\" line.\n| `front/author@fullname`\n\n| `:forename_initials{_i}:`\n| Optional. Author's initials excluding surname. Defaults to dynamically\ncalculated initials. Distinct from the AsciiDoc `:initials:` attribute, which\nincludes surname.\n| `front/author@initials`\n\n| `:lastname{_i}:`\n| Optional. Author's last name. Can set here instead of document header's \"`Author`\" line.\n| `front/author@surname`\n\n| `:role{_i}:`\n| Optional. Defaults to `author`. Possible values: `author`, `editor`. If `author` is supplied,\nthe attribute is not populated.\n| `front/author@role`\n\n| `:organization{_i}:`\n| Optional. Defaults to `\"\"`. Author's organization affiliation.\n| `front/author/organization`\n\n| `:organization_abbrev{_i}:`\n| Optional. Defaults to `\"\"`. Author's organization's abbreviation shown .\n| `front/author/organization@abbrev`\n\n|===\n\nNOTE: You can provide organization information without providing name information\nfor an author.\n\n===== Author Address\n\n[cols=\"3\", options=\"header\"]\n|===\n| Attribute\n| Purpose\n| RFC XML v2/v3 element\n\n| `:email{_i}:`\n| Email of author.\n| `front/author/address/email`\n\n| `:fax{_i}:`\n| Fax number of author. Deprecated in v3.\n| `front/author/address/facsimile`\n\n| `:uri{_i}:`\n| URI of author.\n| `front/author/address/uri`\n\n| `:phone{_i}:`\n| Author's phone number. Scheme-specific part of a `tel` URI (does not include\nthe prefix `tel:`).\nSee https://tools.ietf.org/html/rfc3966#section-3[RFC3966 `global-number-digits`].\n| `front/author/address/phone`\n\n| `:street{_i}:`\n| Address of author, non-city/region/code/country portion.\nMultiple lines concatenated with `\"\\ \"` will be split into separate `\u003cstreet\u003e`\nelements.\n| `front/author/address/postal/street`\n\n| `:city{_i}:`\n| City portion of author's address\n| `front/author/address/postal/city`\n\n| `:region{_i}:`\n| Region, state or province portion of author's address. For US/CA the 2-letter state code.\n| `front/author/address/postal/region`\n\n| `:country{_i}:`\n| Country of author's address\n| `front/author/address/postal/country`\n\n| `:code{_i}:`\n| Postal code of author's address\n| `front/author/address/postal/code`\n|===\n\n\nOnly available for RFC XML v3:\n\n|===\n| Attribute | Purpose | RFC XML v3 element\n| `:postal-line{_i}:`\n| For those who want to directly format their postal addresses without regard\nto the prior types. Ignored in v2. Multiple lines are concatenated with `\"\\ \"`.\nThe `postal-line` attribute is mutually exclusive with the presence of `street`,\n`city`, `region`, `country` and `code` attributes.\n| `front/author/address/postal/postalLine`\n|===\n\n\nExample. This source:\n\n[source,asciidoc]\n----\n:street: 57 Mt Pleasant St\\ Technology Park\n:city: Dullsville\n:region: NSW\n:country: Australia\n:code: 3333\n----\n\nProduces:\n\n[source,xml]\n----\n\u003caddress\u003e\n  \u003cpostal\u003e\n    \u003cstreet\u003e57 Mt Pleasant St\u003c/street\u003e\n    \u003cstreet\u003eTechnology Park\u003c/street\u003e\n    \u003ccity\u003eDullsville\u003c/city\u003e\n    \u003cregion\u003eNSW\u003c/region\u003e\n    \u003ccode\u003e3333\u003c/code\u003e\n    \u003ccountry\u003eAustralia\u003c/country\u003e\n  \u003c/postal\u003e\n\u003c/address\u003e\n----\n\n\n=== Abstract\n\nAny paragraphs following the document header are treated as the abstract\n(`front/abstract`), whether or not they are in abstract style. The abstract is\nterminated by either the first section header (which ends the document\npreamble), or an admonition (e.g. `note`).\n\nAny admonitions before the first section header are treated as notes (`front/note`).\n\n[source,asciidoc]\n----\n[[abstract-id]] \u003c1\u003e\n[abstract]\nThis is an abstract \u003c2\u003e\n\nNOTE: This is a note \u003c3\u003e\n\n[NOTE,remove-in-rfc=true] \u003c4\u003e\n.Note 2 Title \u003c5\u003e\n===\nThis is another note \u003c3\u003e\n===\n----\n\u003c1\u003e v3 only: `front/abstract@anchor` (attribute only available in v3)\n\u003c2\u003e `front/abstract`\n\u003c3\u003e `front/note`\n\u003c4\u003e v3 only: `front/note@removeInRFC` (attribute only available in v3)\n\u003c5\u003e v3: `front/note/name`; v2: `front/note@title` (mandatory attribute; if not provided, `NOTE` is supplied)\n\n\n=== Sections and Subsections\n\n[source,asciidoc]\n----\n:sectnums: \u003c1\u003e\n[[id]] \u003c2\u003e\n[remove-in-rfc=true,toc=include|exclude|default] \u003c3\u003e\n== Section title \u003c4\u003e\nFirst paragraph of section \u003c5\u003e\n\nSecond paragraph of section \u003c5\u003e\n\n:sectnums!: \u003c6\u003e\n=== Subsection title \u003c7\u003e\nFirst paragraph of subsection \u003c8\u003e\n\n==== Subsubsection title \u003c9\u003e\nContent content content \u003c10\u003e\n----\n\u003c1\u003e `middle/section@numbered=true` (attribute only available in v3)\n\u003c2\u003e `middle/section@anchor`\n\u003c3\u003e v3 only: `middle/section@removeInRFC`, `middle/section@toc` (attributes only available in v3)\n\u003c4\u003e v3: `middle/section/name`; v2: `middle/section@title`\n\u003c5\u003e `middle/section/t`\n\u003c6\u003e `middle/section@numbered=false` (attribute only available in v3) (toggle)\n\u003c7\u003e v3: `middle/section/section/name`; v2: `middle/section/section@title`\n\u003c8\u003e `middle/section/section/t`\n\u003c9\u003e v3: `middle/section/section/section/name`; v2: `middle/section/section/section@title`\n\u003c10\u003e `middle/section/section/section/t`\n\n\n=== Cross-References\n\n[source,asciidoc]\n----\nContent content content\n\u003c\u003ccrossreference\u003e\u003e \u003c1\u003e\n\u003c\u003ccrossreference,text\u003e\u003e \u003c2\u003e\n\u003c\u003ccrossreference,format=(counter|title|none|default): text\u003e\u003e \u003c3\u003e\nhttp://example.com/[linktext] \u003c4\u003e\nThe following represent the v3 relref element\n\u003c\u003ccrossreference,section_number (of|comma|parens|bare)\u003e\u003e \u003c5\u003e\n\u003c\u003ccrossreference,section_number (of|comma|parens|bare): text\u003e\u003e \u003c6\u003e\n\u003c\u003ccrossreference#fragment,section_number (of|comma|parens|bare)\u003e\u003e \u003c7\u003e\n\u003c\u003ccrossreference#fragment,section_number (of|comma|parens|bare): text\u003e\u003e \u003c8\u003e\n----\n\u003c1\u003e `\u003cxref target=\"crossreference\"/\u003e`\n\u003c2\u003e `\u003cxref target=\"crossreference\"\u003etext\u003c/xref\u003e`\n\u003c3\u003e `\u003cxref format=\"counter|title|none|default\" target=\"crossreference\"\u003etext\u003c/xref\u003e`\n\u003c4\u003e `\u003ceref href=\"http://example.com/\"\u003elinktext\u003c/eref\u003e`\n\u003c5\u003e v3 only: `\u003crelref displayFormat=\"of|comma|parens|bare\" section=\"section_number\" target=\"crossreference\"/\u003e` (element only available in v3)\n\u003c6\u003e v3 only: `\u003crelref displayFormat=\"of|comma|parens|bare\" section=\"section_number\" target=\"crossreference\"\u003etext\u003c/relref\u003e` (element only available in v3)\n\u003c7\u003e v3 only: `\u003crelref relative=\"fragment\" displayFormat=\"of|comma|parens|bare\" section=\"section_number\" target=\"crossreference\"/\u003e` (element only available in v3)\n\u003c8\u003e v3 only: `\u003crelref relative=\"fragment\" displayFormat=\"of|comma|parens|bare\" section=\"section_number\" target=\"crossreference\"\u003etext\u003c/relref\u003e` (element only available in v3)\n\nIn v2, the relref style crossreferences are rendered as equivalent `xref` crossreferences,\ninserting section numbers as appropriate.\n\nNote that fragments (e.g. `crossreference#fragment`) are not supported on the `xref@target` attribute,\nin either v2 or v3: the RFC XML specification requires that the `xref@target` attribute equals\nthe value of an anchor attribute elsewhere in the document.\n\nInternal crossreferences and bibliographic references are marked up in the same way; but\nbibliographic references are marked up separately from the main flow of Asciidoctor, and are\nprocessed later.\n\nNOTE: Normally, Asciidoctor attempts to match a crossreference to a section title, if it does not find\na matching anchor ID. This behaviour has become optional as of Asciidoctor 1.5.7, and is suppressed in\nthis gem. If you have a citation of a bibliographic item which is identical to a section title (e.g. you have a\nbibliographic citation with the anchor \"WHIRLPOOL\", and a section with the title \"WHIRLPOOL\"),\nthis gem will correctly pick the former as the target of the reference, so long as that section\nhas a different anchor ID:\n\n[source,asciidoc]\n----\n[[hash_whirlpool]]\n=== WHIRLPOOL\n\nThe WHIRLPOOL hash function is defined in \u003c\u003cWHIRLPOOL\u003e\u003e.\n\nThis section should actually be referenced as \u003c\u003chash_whirlpool\u003e\u003e.\n...\n\n[bibliography]\n== Informative References\n++++\n\u003creference anchor='WHIRLPOOL' target='http://www.larc.usp.br/~pbarreto/WhirlpoolPage.html'\u003e\n...\n++++\n----\n\n=== Indexing\n\n[source,asciidoc]\n--\nThis ((\u003cindexterm\u003e)) \u003c1\u003e\nis visible in the text,\nthis one is not (((indexterm, index-subterm))). \u003c2\u003e\n--\n\u003c1\u003e `\u003ciref item=\"indexterm\"\u003eindexterm\u003c/iref\u003e`\n\u003c2\u003e `\u003ciref item=\"indexterm\" subitem=\"index-subterm\"/\u003e`\n\n\n=== Inline formatting\n\n[source,asciidoc]\n--\nLinebreak: + \u003c1\u003e\n_Italic_ \u003c2\u003e\n*Bold* \u003c3\u003e\n`Monospace` \u003c4\u003e\n~subscript~ \u003c5\u003e\n^superscript^ \u003c6\u003e\n[bcp14]#MUST NOT# \u003c7\u003e\n*MUST NOT* \u003c8\u003e\nstem:[sqrt(4) = 2]\n--\n\u003c1\u003e That is, \"+ \" at the end of a line. v3: `\u003cbr/\u003e`; v2: `\u003cvspace/\u003e`.\n\u003c2\u003e v3: `\u003cem\u003eItalic\u003c/em\u003e`; v2: `\u003cspanx style=\"emph\"\u003eItalic\u003c/spanx\u003e`\n\u003c3\u003e v3: `\u003cstrong\u003eBold\u003c/strong\u003e`; v2: `\u003cspanx style=\"strong\"\u003eBold\u003c/spanx\u003e`\n\u003c4\u003e v3: `\u003ctt\u003eMonospace\u003c/tt\u003e`; v2: `\u003cspanx style=\"verb\"\u003eMonospace\u003c/spanx\u003e`\n\u003c5\u003e v3 only: `\u003csub\u003esubscript\u003c/sub\u003e`. Not supported in v2; rendered as `\\_subscript_`\n\u003c6\u003e v3 only: `\u003csup\u003esuperscript\u003c/sup\u003e`. Not supported in v2; rendered as `\\^superscript^`\n\u003c7\u003e v3 only: `\u003cbcp14\u003eMUST NOT\u003c/bcp14\u003e`. Not supported in v2; rendered as `\u003cspanx style=\"strong\"\u003eMUST NOT\u003c/spanx\u003e`.\n\u003c8\u003e v3: if document flag `:no-rfc-bold-bcp14:` is present, then `\u003cstrong\u003eMUST NOT\u003c/strong\u003e`, else (by default) any BCP14/RFC2119 phrase in boldface and capitals is assumed to be intended to be tagged in `\u003cbcp14\u003e`. v2: `\u003cspanx style=\"strong\"\u003eMUST NOT\u003c/spanx\u003e`.\n\u003c9\u003e Stem expressions are treated identically to monospace expressions; they are not currently rendered as MathML or any other notation.\n\nNOTE: The delimiters must occur within the one line; the following is invalid in Asciidoctor:\n[source,asciidoc]\n--\n*WOULD\nPROBABLY*\n--\n\nAny formatting XML spans within `spanx` elements are stripped in postprocessing.\n\n=== Paragraphs\n\n[source,asciidoc]\n--\n[[id]] \u003c1\u003e\n[keep-with-next=true,keep-with-previous=true] \u003c2\u003e\nParagraph text \u003c3\u003e\n--\n\u003c1\u003e `t@anchor`\n\u003c2\u003e v3 only: `t@keepWithNext`, `t@keepWithPrevious` (attributes only available in v3)\n\u003c3\u003e `\u003ct\u003eParagraph text\u003c/t\u003e`\n\n=== Quotes (v3 only)\n\n[source,asciidoc]\n--\n[[id]] \u003c1\u003e\n[quote, attribution, citation info] \u003c2\u003e\nQuotation \u003c3\u003e\n--\n\u003c1\u003e `blockquote@anchor`\n\u003c2\u003e `blockquote@quotedFrom`, `blockquote@cite`. In v3, `citation info` is limited to a URL.\n\u003c3\u003e `\u003cblockquote\u003eQuotation\u003c/blockquote\u003e`\n\n\n=== Comments\n\n==== Asciidoctor comments\n\nAsciidoctor implements both inline comments (prefixed with `//`)\nand block comments (prefixed with `////`). Both are ignored by\nthe Asciidoctor processor, and are not rendered in any output,\nincluding RFC XML.\n\nAsciidoctor also permits paragraphs and open blocks (which can contain\nmultiple paragraphs) to be treated as Asciidoctor comments, if\nthey have the style attribute `[comment]`:\n\n[source,asciidoc]\n----\n\n// This is an inline Asciidoctor comment, which will not be output to XML.\n\n[comment]\nThis is a single paragraph Asciidoctor comment,\nwhich will not be output to XML.\n\n////\nThis is a block Asciidoctor comment,\n\nwhich will not be output to XML.\n////\n\n[comment]\n--\nThis is a\n\nmultiple paragraph\n\nAsciidoctor comment, which will not be output to XML.\n--\n----\n\n==== XML comments\n\nXML inline comments may be introduced into XML through the `[comment]`\nformatting macro: any such comments may not span more than one line.\n\n[source,asciidoc]\n--\nText [comment]#This is a comment# Text\n--\n\nThe foregoing will be rendered in RFC XML as:\n\n[source,xml]\n--\n\u003ct\u003eText \u003c!-- This is a comment --\u003e Text\u003c/t\u003e\n--\n\nXML block comments are introduced through the role attribute\n`[.comment]`, which can be prefied to a paragraph or an open\nblock (which can contain multiple paragraphs):\n\n[source,asciidoc]\n----\n[.comment]\nThis is a single paragraph XML comment.\n\n[.comment]\n--\nThis is a\n\nmultiple paragraph\n\nXML comment.\n--\n----\n\n==== Text Comments\n\nRFC XML provides for editorial comments which may optionally appear\nin the published text (subject to either the v3 `cref@display`\nattribute, or the `comments` processing instruction).\n\nIn v2 RFC XML, comment text is stripped of all formatting.\n\n[source,asciidoc]\n--\nNOTE: Any admonition inside the body of the text is a comment. \u003c1\u003e\n// Note that actual AsciiDoc comments are ignored by the converter.\n\n[[id]] \u003c2\u003e\n[NOTE,display=true|false,source=name] \u003c3\u003e\n.Note Title \u003c4\u003e\n====\nAny admonition inside the body of the text is a comment.\n====\n--\n\u003c1\u003e `\u003ccref\u003eAny admonition inside the body of the text is a comment.\u003c/cref\u003e`\n\u003c2\u003e `cref@anchor`\n\u003c3\u003e v3 only: `cref@display` (not supported in v2); v2: `cref@source`\n\u003c4\u003e v3 only: `cref/name` (not suppported in v2)\n\n\n=== Source Code Listings\n\nIn RFC XML, `sourcecode` (v3) and `artwork` (v2) elements only occur within a\n`figure` wrapper; this gem supplies that wrapper if it is not provided\nexplicitly.\n\n[source,asciidoc]\n.Without Figure Wrapper\n--\n[[id]] \u003c1\u003e\n.Source code listing title \u003c2\u003e\n[source,type,src=uri,align,alt] \u003c3\u003e\n----\nbegin() {\n  source code listing \u003c4\u003e\n}\n----\n--\n\u003c1\u003e v3: `figure/sourcecode@anchor`; v2: `figure@anchor` (moved into supplied wrapper: anchors not supported on `artwork`)\n\u003c2\u003e v3: `figure/sourcecode@name`; v2: `figure/artwork@name`\n\u003c3\u003e 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`.\n\u003c4\u003e v3: `figure/sourcecode`; v2: `figure/artwork`\n\n[source,asciidoc]\n.With Figure Wrapper\n--\n[[id]] \u003c1\u003e\n[align,alt,suppress-title] \u003c2\u003e\n.Figure 1 \u003c3\u003e\n====\nPreamble text \u003c4\u003e\n\n[[id1]] \u003c5\u003e\n.Source code listing title \u003c6\u003e\n[source,type,src=uri,align,alt] \u003c7\u003e\n----\nbegin() {\n  source code listing \u003c8\u003e\n}\n----\n\nPostamble text \u003c9\u003e\n====\n--\n\u003c1\u003e `figure@anchor`\n\u003c2\u003e v2 only: `figure/artwork@align`, `figure/artwork@alt`, `figure@suppress-title` (attributes only available in v2)\n\u003c3\u003e `figure/name`\n\u003c4\u003e v2 only: `figure/preamble` (only available in v2)\n\u003c5\u003e v3: `figure/sourcecode@anchor`; v2: Not supported: use `figure@anchor`\n\u003c6\u003e v3: `figure/sourcecode@name`; v2: `figure/artwork@name`\n\u003c7\u003e 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`.\n\u003c8\u003e v3: `figure/sourcecode`; v2: `figure/artwork`\n\u003c9\u003e v2 only: `figure/postamble` (only available in v2)\n\n\n=== ASCII Art and Images\n\nIn RFC XML, `artwork` elements only occur within a\n`figure` wrapper; this gem supplies that wrapper if it is not provided\nexplicitly.\n\n\n[source,asciidoc]\n.Ascii-Art Without Figure Wrapper\n--\n[[id]] \u003c1\u003e\n.Figure2.jpg \u003c2\u003e\n[align=left|center|right,alt=Ascii Art,type=text/plain] \u003c3\u003e\n....\n------------------------\n|        Ascii Art     |\n------------------------ \u003c4\u003e\n....\n--\n\u003c1\u003e v3 only: `figure/artwork@anchor`; v2: `figure@anchor` (moved into supplied wrapper: anchors not supported on `artwork`)\n\u003c2\u003e `figure/artwork@name`\n\u003c3\u003e `figure/artwork@align`, `figure/artwork@alt`; `figure@type` (attribute only available in v2)\n\u003c4\u003e `figure/artwork`\n\n[source,asciidoc]\n.Image Without Figure Wrapper\n--\n[[id]] \u003c1\u003e\n.Figure2.jpg \u003c2\u003e\n[align=left|center|right,alt=alt_text,type=img/jpeg] \u003c3\u003e\nimage::filename.jpg[alt_text,700,200] \u003c4\u003e\n--\n\u003c1\u003e v3 only: `figure/artwork@anchor`; v2: `figure@anchor` (moved into supplied wrapper: anchors not supported on `artwork`)\n\u003c2\u003e `figure/artwork@name`\n\u003c3\u003e `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)\n\u003c4\u003e `figure/artwork@src`, `figure/artwork@alt`, `figure/artwork@width` (deprecated in v3), `figure/artwork@height` (deprecated in v3)\n\n\n[source,asciidoc]\n.With Figure Wrapper\n--\n[[id]] \u003c1\u003e\n[align,alt,suppress-title] \u003c2\u003e\n.Figure 1 \u003c3\u003e\n====\nPreamble text \u003c4\u003e\n\n[[id]] \u003c5\u003e\n.Figure2.jpg \u003c8\u003e\n[align=left|center|right,alt=alt_text,type=text/plain] \u003c6\u003e\n....\nFigures are\n      only permitted to contain listings (sourcecode),\n           images (artwork),\nor literal (artwork) \u003c7\u003e\n....\n[[id]] \u003c5\u003e\n.Figure2.jpg \u003c8\u003e\n[align=left|center|right,alt=alt_text,type=img/jpeg] \u003c9\u003e\nimage::filename.jpg[alt_text,700,200] \u003c10\u003e\n\nPostamble text \u003c11\u003e\n====\n--\n\u003c1\u003e `figure@anchor`\n\u003c2\u003e v2 only: `figure/artwork@align`, `figure/artwork@alt`, `figure@suppress-title` (attributes only available in v2)\n\u003c3\u003e `figure/name`\n\u003c4\u003e v2 only: `figure/preamble` (only available in v2)\n\u003c5\u003e v3: `figure/artwork@anchor`; v2: Not supported: use `figure@anchor`\n\u003c6\u003e `figure/artwork@align`, `figure/artwork@alt`; `figure@type` (attribute only available in v2)\n\u003c7\u003e `figure/artwork`\n\u003c8\u003e `figure/artwork@name`\n\u003c9\u003e `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)\n\u003c10\u003e `figure/artwork@src`, `figure/artwork@alt`, `figure/artwork@width` (deprecated in v3), `figure/artwork@height` (deprecated in v3)\n\u003c11\u003e v2 only: `figure/postamble` (only available in v2)\n\n=== Mathematical examples\n\nIn order for mathematical formatting to be recognised in Asciidoc, the document attribute `:stem:` needs to be set.\n\n[source,asciidoc]\n--\n:stem:\n\n[stem]\n++++\nsqrt(4) = 2\n++++\n--\n\nMathematical examples are treated identically to literals, and are rendered as `artwork` in both v2 and v3;\nhowever their default alignment is set as `center`. As with inline stem expressions, they are treated identically\nto monospace expressions in the RFC XML output; they are not currently rendered as MathML or any other notation.\n\n=== Unordered and Ordered Lists\n\n[source,asciidoc]\n--\n[[id]] \u003c1\u003e\n[empty=true,spacing=normal|compact,hang-indent=n] \u003c2\u003e\n* Unordered list 1 \u003c3\u003e\n* Unordered list 2 \u003c3\u003e\n** Nested list \u003c4\u003e\n\n[[id]] \u003c5\u003e\n[spacing=compact,empty=true,start=n,group=n,counter=token,hang-indent=n,format=List #%d,arabic|loweralpha|upperralpha|lowerroman|upperroman] \u003c6\u003e\n. A \u003c7\u003e\n. B \u003c7\u003e\n--\n\u003c1\u003e v3: `ul@anchor`; attribute only available in v3\n\u003c2\u003e v3: `ul@empty`, `ul@spacing` (`hangIndent` not available); v2: `ul@style = empty`, `ul@hangIndent` (`spacing` not available)\n\u003c3\u003e v2: `list[@style=\"symbols\"]/t`; v3: ul/li\n\u003c4\u003e v2: `list[@style=\"symbols\"]/t/list[@style=\"symbols\"]/t`; v3: `ul/li/ul/li`\n\u003c5\u003e v3: `ol@anchor`; attribute only available in v3\n\u003c6\u003e 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`, `hangIndent` not available)\n\u003c7\u003e v2: `list/t`; v3: `ol/li`\n\nNOTE: Asciidoctor does not permit anchors on list items: the anchors in the following are ignored.\n\n[source,asciidoc]\n--\n* [[id1]] A\n\n. [[id2]] A\n--\n\nNOTE: RFC XML v2 does not support multiparagraph list items. Following the specification recommendation,\nparagraphs within v2 list items are replaced with `vspace` tages.\n\n=== Definition Lists\n\n[source,asciidoc]\n--\n[[id]] \u003c1\u003e\n[horizontal,compact,hang-indent=n] \u003c2\u003e\nA:: B \u003c3\u003e\n--\n\u003c1\u003e v3 only: `dl@anchor` (attribute only available in v3)\n\u003c2\u003e 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.\n\u003c3\u003e v3: `dl/dt`, `dl/dd`; v2: `list[@style=\"hanging\"]/t@hangText`, `list[@style=\"hanging\"]/t`\n\nNOTE: Asciidoctor does not permit anchors on either definition list terms,\nor definition list definitions: the anchors in the following are ignored.\n\nNOTE: In RFC XML v2, `idnits` considers inline definition lists invalid; the gem\nrenders them as paragraphed definition lists. The gem option `:inline-definition-lists`\ndisables this behaviour.\n\n[source,asciidoc]\n--\n[[id1]] A:: [[id2]]B\n--\n\nNOTE: RFC XML v2 does not support multiparagraph list items. Following the specification recommendation,\nparagraphs within v2 list items are replaced with `vspace` tages.\n\n=== Tables\n\nThe converter respects the AsciiDoc (horizontal) align attributes of cells (v2,\nv3), column widths (v2), and `colspan`, `rowspan` attributes (v3).\n\n(Exceptionally,\ncolumn widths specified for v2 as `\"1,1,1,1,1,1....\"` will be ignored, since Asciidoctor\ninternally treats them identically to unspecified column widths on a table.)\n\n[source,asciidoc]\n--\n[[id]] \u003c1\u003e\n[suppress-title=true|false,align=left|center|right,grid=all|cols|none|rows] \u003c2\u003e\n.Table Title \u003c3\u003e\n|===\n|[[id]] head | head \u003c4\u003e\n\nh|header cell | body cell \u003c5\u003e\n| | [[id]] body cell \u003c6\u003e\n\n|foot | foot \u003c7\u003e\n|===\n--\n\u003c1\u003e v3: `table@anchor`; v2: `texttable@anchor`\n\u003c2\u003e 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` \u003e `all`, `cols` \u003e `full`, `none` \u003e `none`, `rows` \u003e `headers` (although the two are not strictly equivalent).\n\u003c3\u003e v3: `table/name`; v2: `texttable@title`\n\u003c4\u003e v3: `table/thead/tr/td`; v2: `texttable/ttcol@id` (attribute only available in v2), `texttable/ttcol`\n\u003c5\u003e v3: `table/tbody/tr/th`, `table/tbody/tr/td`; v2: `texttable/c`, `texttable/c`\n\u003c6\u003e v3: `table/tbody/tr/td@anchor` (attribute only available in v3)\n\u003c7\u003e v3: `table/tfoot/tr/td`; v2: `texttable/c`\n\nNOTE: v3 permits table cells to contain block elements, such as paragraphs and lists. (This is done in Asciidoc by prefixing\nthe table cell with `a|`.) However v2 only permits inline tagging, and any block tags are ignored.\n\n=== Sidebar (v3 only)\n\n[source,asciidoc]\n--\n[[id]] \u003c1\u003e\n****\nSidebar \u003c2\u003e\n****\n--\n\u003c1\u003e `aside@anchor`\n\u003c2\u003e `\u003caside\u003eSidebar\u003c/aside\u003e`\n\n\n=== References: Embedded in Document\n\nReferences are expected to be provided in raw RFC XML v2 format. For v3, a list of crossreferences may\nprecede the block of references, with alternative text. This will not be rendered, but it will be used\nto populate `displayreference` elements, mapping the reference anchors to display text. For example,\na list entry `[[[ref1,alt1]]]` means that any instances of the anchor `ref1` should be displayed as `alt1`,\nand is rendered as `\u003cdisplayreference target=\"ref1\" to=\"alt1\"/\u003e`.\n\nRFC requires two separate bibliographies, one for normative and one for informative references;\neither can be omitted. All bibliography sections in the must be styled with the prefix `[bibliography]`,\nand must appear in sequence, before any appendices.\n\nBy default, the references cited must be included as raw RFC XML, and separated\ninto the normative and informative sections.\n\n[source,asciidoc]\n--\n[[id]] \u003c1\u003e\n[bibliography]\n== Normative References\n* [[[ref1,alt1]]] \u003c2\u003e\n++++\n(raw XML) \u003c3\u003e\n++++\n\n[[id]] \u003c1\u003e\n[bibliography]\n== Informative References\n++++\n(raw XML) \u003c2\u003e\n++++\n--\n\u003c1\u003e `back/references@anchor` (only in v3)\n\u003c2\u003e `back/displayreference@target`, `back/displayreference@to` (only in v3)\n\u003c3\u003e `back/references/reference`\n\nIn postprocessing, bibliographic entries available from http://xml.resource.org/public/rfc are replaced\nwith external references to that entry, using XML entities in RFC XML v2, and XML includes\nin RFC XML v3. Do not insert your own entities or XML includes into the references; the gem will have difficulty\nprocessing them.\n\n[[external-directory-refs]]\n=== References: External Directory\n\nAs 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.\n\nThe 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 \u003c\u003cexternal-ref-lookup\u003e\u003e.)\n\nFor example:\n\n[source,asciidoc]\n--\n= The Holy Hand Grenade of Antioch\nArthur Pendragon\n:doctype: internet-draft\n:workgroup: silly\n:biblio-dir: refs \u003c1\u003e\n:normative: RFC2119, AsciiDoc \u003c1\u003e\n\n[[xyz]]\n== Hello\nHello\n\n* a \u003c\u003cRFC2119,2.3 of: See internet draft subsection\u003e\u003e \u003c3\u003e\n* b \u003c\u003cI-D.abarth-cake\u003e\u003e\n* b2 \u003c\u003cI-D.abarth-cake,what\u003e\u003e\n* b1 \u003c\u003cI-D.abarth-cake,2.3 of: See internet draft subsection\u003e\u003e \u003c3\u003e\n* c \u003c\u003cxyz,format=counter: xyzzy\u003e\u003e \u003c4\u003e\n* d \u003c\u003cbiblio\u003e\u003e \u003c4\u003e\n* e \u003c\u003cAsciiDoc,AsciiDoctor\u003e\u003e\n* f \u003c\u003cmathrefs\u003e\u003e\n\n\n[[biblio]]\n=== Biblio\nSee biblio\n\n[bibliography]\n== Normative References \u003c5\u003e\n\n[bibliography]\n== Informative References \u003c6\u003e\n--\n\u003c1\u003e 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.\n\u003c2\u003e The references in the `./refs` directory are by default considered informative; this attribute indicates that `RFC2119` and `AsciiDoc` are to be considered normative.\n\u003c3\u003e References are recognised in `relref` as well as `xref` elements.\n\u003c4\u003e The gem differentiates between bibliographic references and crossreferences to other anchors within the document.\n\u003c5\u003e 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.\n\n\n=== Appendices\n\n[source,asciidoc]\n--\n[[id]] \u003c1\u003e\n[appendix]\n== Appendix 1 \u003c2\u003e\nContent \u003c3\u003e\n--\n\u003c1\u003e `back/section@anchor`\n\u003c2\u003e v3: `back/section/name`; v2: `back/section@title`\n\u003c3\u003e `back/section/t`\n\n\n\n\n=== Unsupported RFC XML Elements\n\nThe following **RFC XML v3/v2** elements are not (yet) supported through\nasciidoctor commands:\n\n|===\n| RFC XML element                  | RFC XML v3 | RFC XML v2\n\n| `front/boilerplate`              | Not added  | N/A\n| `iref@primary`                   | N          | N\n| `reference` (and all children) 2+| Supported only as pass-through or through asciidoc-bibliography gem\n| `table/preamble`                 | Deprecated | N\n| `table/postamble`                | Deprecated | N\n| `artwork@width`                  | Only on images | Only on images\n| `artwork@height`                 | Only on images | Only on images\n|===\n\n=== Unsupported Asciidoctor Features\n\nThese asciidoctor features are not supported in output of these formats:\n\n|===\n| asciidoctor feature | RFC XML v2 | RFC XML v3\n\n| http://asciidoctor.org/docs/user-manual/#quote[Quote] | Rendered as normal paragraph | Supported\n| http://asciidoctor.org/docs/user-manual/#quote[Quote]: Non-URL Citations 2+| Ignored\n| http://asciidoctor.org/docs/user-manual/#verse[Verse] | Rendered as normal paragraph | Rendered as Quote\n| http://asciidoctor.org/docs/user-manual/#sidebar[Sidebar] | Rendered as normal paragraph | Supported\n| http://asciidoctor.org/docs/user-manual/#index-terms[Index Term]: Tertiary 2+| Ignored\n| List: http://asciidoctor.org/docs/user-manual/#numbering-styles[Ordered List numbering] `decimal`, `lowergreek` 2+| Treated as `arabic`\n| http://asciidoctor.org/docs/user-manual/#callouts[Callouts] 2+| Ignored\n| http://asciidoctor.org/docs/user-manual/#admonition[Adminitions: formatting] | Ignored | Supported\n| Formatting: http://asciidoctor.org/docs/user-manual/#discrete-headings[Floating Title] 2+| Rendered as strong paragraph\n| Formatting: http://asciidoctor.org/docs/user-manual/#page-break[Page Break] 2+| Ignored\n| Formatting: http://asciidoctor.org/docs/user-manual/#horizontal-rules[Horizontal Rule] 2+| Ignored\n| Formatting: http://asciidoctor.org/docs/user-manual/#line-breaks[Line breaks] | Supported | Only supported within table cells\n| Media: http://asciidoctor.org/docs/user-manual/#audio[Audio] 2+| Ignored\n| Media: http://asciidoctor.org/docs/user-manual/#video[Video] 2+| Ignored\n| Media: http://asciidoctor.org/docs/user-manual/#images[Inline images] 2+| Ignored\n| Macro: http://asciidoctor.org/docs/user-manual/#keyboard-shortcuts[Keyboard shortcuts] 2+| Ignored\n| Macro: http://asciidoctor.org/docs/user-manual/#menu-selections[Menu selections] 2+| Ignored\n| Macro: http://asciidoctor.org/docs/user-manual/#ui-buttons[UI buttons] 2+| Ignored\n| Table: http://asciidoctor.org/docs/user-manual/#footer-row[Distinction between table body and table footer] | No | Supported\n| Table: http://asciidoctor.org/docs/user-manual/#header-row[Multiple table header rows] | No | Supported\n| Table: http://asciidoctor.org/docs/user-manual/#table-borders[Table borders: grid = rows] | Rendered as `headers` | Ignored\n| Table: http://asciidoctor.org/docs/user-manual/#table-borders[Table borders: grid = cols\\|none] | Supported | Ignored\n| Table: http://asciidoctor.org/docs/user-manual/#table-borders[Table borders: frame] 2+| Ignored\n| Table: http://asciidoctor.org/docs/user-manual/#cell[Table cells: rowspan] | Ignored | Supported\n| Table: http://asciidoctor.org/docs/user-manual/#cell[Table cells: colspan] | Ignored | Supported\n| Table: http://asciidoctor.org/docs/user-manual/#cell[Table cells: Asciidoctor formatting (blocks within cells)] | Ignored | Supported\n| Table: http://asciidoctor.org/docs/user-manual/#cols-format[Table columns: width] | Supported | Ignored\n|===\n\n[[external-ref-lookup]]\n== Lookup of external references\n\nIn order to speed the lookup of references on the http://xml.resource.org/public/rfc website for external\nreferences, a cache of references is built the first time the gem is run, in the user's home directory:\n`~/.asciidoc-rfc-biblio-cache.json`. This maps all the canonical anchors for external references as defined\nby the IETF, such as `RFC2119` or `CCITT.E163.1988`, to the URLs that their RFC reference is stored on.\nReferences are detected for replacement in the Asciidoc document by matching the `references@anchor`\nattribute to one of those canonical anchors; the content of the local RFC XML reference is not checked.\n\n(For rebuilding the cache, see \u003c\u003ccaches\u003e\u003e.)\n\nRather than hand crafting RFC XML references for RFC documents, or other references hosted at `http://xml.resource.org/public/rfc/`,\nyou need only create a dummy `\u003creference\u003e` element containing the IETF-defined anchor for that citation. In postprocessing, any\nreferences that are hosted at xml.resource.org will be identified by their anchor, and replaced by entities or XML includes,\nfor RFC XML v2 and v3 respectively. (The complete list of authoritative\nRFC XML bibliographies is available from https://xml2rfc.tools.ietf.org , online and in zipped form.)\n\nBecause the content of any externally defined `\u003creference\u003e` element is overwritten with an entity or include,\nyou do not need to provide a full reference. You can supply a minimal reference like `\u003creference anchor=\"RFC2119\"/\u003e`,\nbut note that such a reference is invalid in the RFC XML schema, and the gem will report a missing element during processing.\n(The document will still be processed successfully.) To prevent any validation error reports, the minimal syntactically valid reference is:\n\n[source,xml]\n--\n\u003creference anchor=\"RFC2119\"\u003e\n  \u003cfront\u003e\n    \u003ctitle/\u003e\n    \u003cauthor/\u003e\n    \u003cdate/\u003e\n  \u003c/front\u003e\n\u003c/reference\u003e\n--\n\nIf you wish to cite a specific version of an Internet-Draft, you will need to include the `seriesInfo` element\nin the reference that identifies the specific version; the anchor is the same for all internet drafts. For example:\n\n[source,xml]\n--\n\u003creference anchor=\"I-D.abarth-cake\"\u003e\n  \u003cfront\u003e\n    \u003ctitle/\u003e\n    \u003cauthor/\u003e\n    \u003cdate/\u003e\n  \u003c/front\u003e\n  \u003cseriesInfo name=\"Internet-Draft\" value=\"draft-abarth-cake-00\"/\u003e\n\u003c/reference\u003e\n--\n\nAs discussed under \u003c\u003cexternal-directory-refs\u003e\u003e, 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.)\n\n== asciidoc-bibliography integration\n\n[TODO]\n\n////\nThe https://github.com/riboseinc/asciidoctor-bibliography[asciidoc-bibliography] gem allows citations to be imported\ninto asciidoc from BibTex or RFC XML files. The gem natively requires the user to provide the correct, presorted\nRFC XML references within asciidoc separately for normative and for informative references. Using the asciidoc-bibliography\ngem, the user can instead have a single file of RFC XML references, and indicate in place whether each reference\nis intended to be normative or informative, as is the case for MMark; the gem will then extract the correct RFC XML\nreferences from the references file, and insert them in order into the normative and informative references respectively.\n\nIntegration with the asciidoc-bibliography gem proceeds as follows:\n\n. Create an RFC XML references file, consisting of a `\u003creferences\u003e` element with individual `\u003creference\u003e` elements inserted,\nas would be done for the informative and normative references normally. The references file will contain all possible\nreferences to be used\nin the file; the bibliography gem will select which references have actually been cited in the document.\n.. The caveats for \u003c\u003cexternal-ref-lookup,externally available references\u003e\u003e also apply to the references file.\nUnlike the case for RFC XML documents created manually, the references file does not recognise XML entities\nand will not attempt to download them during processing; postprocessing means you do not need to create your own\nXML entities anyway.\n.. The RFC XML in the references file will need to be appropriate to the version of RFC XML used in the main document, as\nusual. Note that RFC XML v2 references are forward compatible with v3; v3 contains a couple of additional elements.\n. Add the following header attributes to the main document:\n+\n--\n`:bibliography-database:` :: The name of the references file; this is expected to be in the same directory as\nthe main document.\n`:bibliography-passthrough:` :: `citations`. This instructs the asciidoctor-bibliography gem to wrap the citations\nin an Asciidoctor passthrough block. If `true` is used, the references introduced through `cite` macros will also\nbe treated as inline Asciidoctor passthrough text.\n`:bibliography-prepend-empty:` :: `true|false`. No current effect on file\n`:bibliography-hyperlinks:` :: `true|false` (default `true`): inserts bibliographic link around reference. Use `false`.\n`:bibliography-style:` :: The style of reference used in the references file; the recognised styles are `rfc-v2` and\n`rfc-v3`, for RFC XML v2 and RFC XML v3 respectively.\n--\n\n. References to a normative reference are inserted with the macro `cite:norm[id]` instead of `\u003c\u003cid\u003e\u003e`, where `id` is\nthe anchor of the reference.\n. References to an informative reference are inserted with the macro `cite:info[id]` instead of `\u003c\u003cid\u003e\u003e`, where `id` is\nthe anchor of the reference.\n.. Text may be prefixed or suffixed to the crossreference with the `prefix` and `suffix` attributes.\n.. 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.\n.. 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:\n*** `\u003c\u003cid,words\u003e\u003e` = `cite:norm[id, text=\"\u003cxref target='id'\u003ewords\u003c/xref\u003e\"]`\n*** `\u003c\u003cid,format=counter: words\u003e\u003e` (processed as a formatted crossreference) = `cite:norm[id, text=\"\u003cxref format='counter' target='id'\u003ewords\u003c/xref\u003e\"]`\n*** `\u003c\u003cid,2.4 comma: words\u003e\u003e` (processed as relref) = `cite:norm[id, text=\"\u003crelref displayFormat='comma' section='2.4' target='id'}/\u003e\"]`\n*** `\u003c\u003cid#section2_4,2.4 comma: words\u003e\u003e` (processed as relref with a cross-document internal reference) = `cite:norm[id, text=\"\u003crelref relative='section2_4' displayFormat='comma' section='2.4' target='id'/\u003e\"]`\n. Normative and Informative References are inserted in the document through a macro, which occurs where the RFC XML\nreferences would be inserted\n+\n[source,asciidoc]\n--\n[bibliography]\n== Normative References\n\n++++\nbibliography::norm[]\n++++\n\n[bibliography]\n== Informative References\n\n++++\nbibliography::info[]\n++++\n--\n. In order to preprocess the macros, the asciidoctor-bibliography gem is passed as an `-r` argument to the\nasciidoctor-rfc invocation:\n** `asciidoctor -b rfc2 -r 'asciidoctor-bibliography' -r 'asciidoctor-rfc'  spec/examples/refs-v2.adoc`\n** `asciidoctor -b rfc3 -r 'asciidoctor-bibliography' -r 'asciidoctor-rfc'  spec/examples/refs-v3.adoc`\n. `referencegroup` citations are not currently supported by the asciidoctor-bibliography gem.\n////\n\n== Examples\n\n=== RFC XML v3 Example\n\nifdef::env-github[]\ninclude::spec/examples/example-v3.adoc[]\nendif::[]\nifndef::env-github[]\n[source,asciidoc]\n----\ninclude::spec/examples/example-v3.adoc[]\n----\nendif::[]\n\n=== RFC XML v2 Example\n\nifdef::env-github[]\ninclude::spec/examples/example-v2.adoc[]\nendif::[]\nifndef::env-github[]\n[source,asciidoc]\n----\ninclude::spec/examples/example-v2.adoc[]\n----\nendif::[]\n\n\n== Development\n\nWe follow Sandi Metz's Rules for this gem, you can read the\nhttp://robots.thoughtbot.com/post/50655960596/sandi-metz-rules-for-developers[description of the rules here].\n\nAll new code should follow these\nrules. If you make changes in a pre-existing file that violates these rules you\nshould fix the violations as part of your contribution.\n\n=== Setup\n\nClone the repository.\n\n[source,sh]\n----\ngit clone https://github.com/metanorma/asciidoctor-rfc\n----\n\nSetup your environment.\n\n[source,sh]\n----\nbin/setup\n----\n\nRun the test suite\n\n[source,sh]\n----\nbin/rspec\n----\n\n== Contributing\n\nFirst, thank you for contributing! We love pull requests from everyone. By\nparticipating in this project, you hereby grant https://www.ribose.com[Ribose Inc.] the\nright to grant or transfer an unlimited number of non exclusive licenses or\nsub-licenses to third parties, under the copyright covering the contribution\nto use the contribution by all means.\n\nHere are a few technical guidelines to follow:\n\n. Open an https://github.com/metanorma/asciidoctor-rfc/issues[issue] to discuss a new feature.\n. Write tests to support your new feature.\n. Make sure the entire test suite passes locally and on CI.\n. Open a Pull Request.\n. https://github.com/thoughtbot/guides/tree/master/protocol/git#write-a-feature[Squash your commits] after receiving feedback.\n. Party!\n\n\n== Credits\n\nThis gem is developed, maintained and funded by https://www.ribose.com[Ribose Inc.]\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmetanorma%2Fasciidoctor-rfc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmetanorma%2Fasciidoctor-rfc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmetanorma%2Fasciidoctor-rfc/lists"}