metanorma-ietf 1.0.0

Sign up to get free protection for your applications and to get access to all the features.
Files changed (54) hide show
  1. checksums.yaml +7 -0
  2. data/.gitignore +18 -0
  3. data/.hound.yml +3 -0
  4. data/.oss-guides.rubocop.yml +1077 -0
  5. data/.rspec +2 -0
  6. data/.rubocop.ribose.yml +65 -0
  7. data/.rubocop.tb.yml +650 -0
  8. data/.rubocop.yml +15 -0
  9. data/.travis.yml +23 -0
  10. data/CODE_OF_CONDUCT.md +74 -0
  11. data/Gemfile +4 -0
  12. data/Guardfile +22 -0
  13. data/LICENSE +25 -0
  14. data/README.adoc +1660 -0
  15. data/Rakefile +6 -0
  16. data/bin/asciidoctor-rfc2 +14 -0
  17. data/bin/asciidoctor-rfc3 +14 -0
  18. data/bin/console +14 -0
  19. data/bin/rspec +17 -0
  20. data/bin/setup +8 -0
  21. data/docs/installation.md +21 -0
  22. data/docs/navigation.md +10 -0
  23. data/docs/overview.md +5 -0
  24. data/lib/asciidoctor/rfc.rb +8 -0
  25. data/lib/asciidoctor/rfc/common/base.rb +531 -0
  26. data/lib/asciidoctor/rfc/common/front.rb +120 -0
  27. data/lib/asciidoctor/rfc/v2/base.rb +379 -0
  28. data/lib/asciidoctor/rfc/v2/blocks.rb +261 -0
  29. data/lib/asciidoctor/rfc/v2/converter.rb +60 -0
  30. data/lib/asciidoctor/rfc/v2/front.rb +69 -0
  31. data/lib/asciidoctor/rfc/v2/inline_anchor.rb +111 -0
  32. data/lib/asciidoctor/rfc/v2/lists.rb +135 -0
  33. data/lib/asciidoctor/rfc/v2/table.rb +114 -0
  34. data/lib/asciidoctor/rfc/v2/validate.rb +32 -0
  35. data/lib/asciidoctor/rfc/v2/validate2.rng +716 -0
  36. data/lib/asciidoctor/rfc/v3/base.rb +329 -0
  37. data/lib/asciidoctor/rfc/v3/blocks.rb +246 -0
  38. data/lib/asciidoctor/rfc/v3/converter.rb +62 -0
  39. data/lib/asciidoctor/rfc/v3/front.rb +122 -0
  40. data/lib/asciidoctor/rfc/v3/inline_anchor.rb +89 -0
  41. data/lib/asciidoctor/rfc/v3/lists.rb +176 -0
  42. data/lib/asciidoctor/rfc/v3/svg.rng +9081 -0
  43. data/lib/asciidoctor/rfc/v3/table.rb +65 -0
  44. data/lib/asciidoctor/rfc/v3/validate.rb +34 -0
  45. data/lib/asciidoctor/rfc/v3/validate.rng +2143 -0
  46. data/lib/metanorma-ietf.rb +7 -0
  47. data/lib/metanorma/ietf.rb +8 -0
  48. data/lib/metanorma/ietf/processor.rb +89 -0
  49. data/lib/metanorma/ietf/version.rb +5 -0
  50. data/metanorma-ietf.gemspec +51 -0
  51. data/rfc2629-other.ent +61 -0
  52. data/rfc2629-xhtml.ent +165 -0
  53. data/rfc2629.dtd +312 -0
  54. metadata +289 -0
data/.rubocop.yml ADDED
@@ -0,0 +1,15 @@
1
+ # This project follows the Ribose OSS style guide.
2
+ # https://github.com/riboseinc/oss-guides
3
+ # All project-specific additions and overrides should be specified in this file.
4
+
5
+ inherit_from:
6
+ # Thoughtbot's style guide from: https://github.com/thoughtbot/guides
7
+ - ".rubocop.tb.yml"
8
+ # Overrides from Ribose
9
+ - ".rubocop.ribose.yml"
10
+ AllCops:
11
+ DisplayCopNames: false
12
+ StyleGuideCopsOnly: false
13
+ TargetRubyVersion: 2.3
14
+ Rails:
15
+ Enabled: true
data/.travis.yml ADDED
@@ -0,0 +1,23 @@
1
+ dist: trusty
2
+ sudo: true
3
+ language: ruby
4
+ python:
5
+ - 2.7
6
+ rvm:
7
+ - 2.5
8
+ - 2.4
9
+ - 2.3
10
+ - ruby-head
11
+ addons:
12
+ apt:
13
+ packages:
14
+ - python-lxml
15
+ - python-pip
16
+
17
+ before_install:
18
+ - gem install bundler -v 1.16.1
19
+ - unset _JAVA_OPTIONS
20
+ - pip install --user xml2rfc
21
+ matrix:
22
+ allow_failures:
23
+ - rvm: ruby-head
@@ -0,0 +1,74 @@
1
+ # Contributor Covenant Code of Conduct
2
+
3
+ ## Our Pledge
4
+
5
+ In the interest of fostering an open and welcoming environment, we as
6
+ contributors and maintainers pledge to making participation in our project and
7
+ our community a harassment-free experience for everyone, regardless of age, body
8
+ size, disability, ethnicity, gender identity and expression, level of experience,
9
+ nationality, personal appearance, race, religion, or sexual identity and
10
+ orientation.
11
+
12
+ ## Our Standards
13
+
14
+ Examples of behavior that contributes to creating a positive environment
15
+ include:
16
+
17
+ * Using welcoming and inclusive language
18
+ * Being respectful of differing viewpoints and experiences
19
+ * Gracefully accepting constructive criticism
20
+ * Focusing on what is best for the community
21
+ * Showing empathy towards other community members
22
+
23
+ Examples of unacceptable behavior by participants include:
24
+
25
+ * The use of sexualized language or imagery and unwelcome sexual attention or
26
+ advances
27
+ * Trolling, insulting/derogatory comments, and personal or political attacks
28
+ * Public or private harassment
29
+ * Publishing others' private information, such as a physical or electronic
30
+ address, without explicit permission
31
+ * Other conduct which could reasonably be considered inappropriate in a
32
+ professional setting
33
+
34
+ ## Our Responsibilities
35
+
36
+ Project maintainers are responsible for clarifying the standards of acceptable
37
+ behavior and are expected to take appropriate and fair corrective action in
38
+ response to any instances of unacceptable behavior.
39
+
40
+ Project maintainers have the right and responsibility to remove, edit, or
41
+ reject comments, commits, code, wiki edits, issues, and other contributions
42
+ that are not aligned to this Code of Conduct, or to ban temporarily or
43
+ permanently any contributor for other behaviors that they deem inappropriate,
44
+ threatening, offensive, or harmful.
45
+
46
+ ## Scope
47
+
48
+ This Code of Conduct applies both within project spaces and in public spaces
49
+ when an individual is representing the project or its community. Examples of
50
+ representing a project or community include using an official project e-mail
51
+ address, posting via an official social media account, or acting as an appointed
52
+ representative at an online or offline event. Representation of a project may be
53
+ further defined and clarified by project maintainers.
54
+
55
+ ## Enforcement
56
+
57
+ Instances of abusive, harassing, or otherwise unacceptable behavior may be
58
+ reported by contacting the project team at ronald.tse@ribose.com. All
59
+ complaints will be reviewed and investigated and will result in a response that
60
+ is deemed necessary and appropriate to the circumstances. The project team is
61
+ obligated to maintain confidentiality with regard to the reporter of an incident.
62
+ Further details of specific enforcement policies may be posted separately.
63
+
64
+ Project maintainers who do not follow or enforce the Code of Conduct in good
65
+ faith may face temporary or permanent repercussions as determined by other
66
+ members of the project's leadership.
67
+
68
+ ## Attribution
69
+
70
+ This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
71
+ available at [http://contributor-covenant.org/version/1/4][version]
72
+
73
+ [homepage]: http://contributor-covenant.org
74
+ [version]: http://contributor-covenant.org/version/1/4/
data/Gemfile ADDED
@@ -0,0 +1,4 @@
1
+ source "https://rubygems.org"
2
+
3
+ # Specify your gem's dependencies in metanorma-ietf.gemspec
4
+ gemspec
data/Guardfile ADDED
@@ -0,0 +1,22 @@
1
+ directories(%w(. lib spec)).
2
+ select { |d| Dir.exists?(d) ? d : UI.warning("Directory #{d} does not exist") }
3
+
4
+ guard :rspec, cmd: "bundle exec rspec" do
5
+ require "guard/rspec/dsl"
6
+ dsl = Guard::RSpec::Dsl.new(self)
7
+
8
+ # Feel free to open issues for suggestions and improvements
9
+
10
+ # RSpec files
11
+ rspec = dsl.rspec
12
+ watch(rspec.spec_helper) { rspec.spec_dir }
13
+ watch(rspec.spec_support) { rspec.spec_dir }
14
+ watch(rspec.spec_files)
15
+
16
+ # Ruby files
17
+ ruby = dsl.ruby
18
+ dsl.watch_spec_files_for(ruby.lib_files)
19
+
20
+ # Run all specs if any lib file changes.
21
+ watch(ruby.lib_files) { rspec.spec_dir }
22
+ end
data/LICENSE ADDED
@@ -0,0 +1,25 @@
1
+ BSD 2-Clause License
2
+
3
+ Copyright (c) 2018, Ribose
4
+ All rights reserved.
5
+
6
+ Redistribution and use in source and binary forms, with or without
7
+ modification, are permitted provided that the following conditions are met:
8
+
9
+ * Redistributions of source code must retain the above copyright notice, this
10
+ list of conditions and the following disclaimer.
11
+
12
+ * Redistributions in binary form must reproduce the above copyright notice,
13
+ this list of conditions and the following disclaimer in the documentation
14
+ and/or other materials provided with the distribution.
15
+
16
+ THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
17
+ AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18
+ IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
19
+ DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
20
+ FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
21
+ DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
22
+ SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
23
+ CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
24
+ OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
25
+ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
data/README.adoc ADDED
@@ -0,0 +1,1660 @@
1
+ = AsciiRFC: Writing Internet-Drafts and RFCs in AsciiDoc
2
+ :source-highlighter: coderay
3
+ :icons: font
4
+
5
+ `metanorma-ietf` lets you write Internet-Drafts and RFCs in AsciiDoc, the
6
+ "`http://asciidoctor.org/[asciidoctor]-way`".
7
+
8
+ image:https://img.shields.io/gem/v/metanorma-ietf.svg["Gem Version", link="https://rubygems.org/gems/metanorma-ietf"]
9
+ image:https://img.shields.io/travis/riboseinc/metanorma-ietf/master.svg["Build Status", link="https://travis-ci.org/riboseinc/metanorma-ietf"]
10
+ image:https://codeclimate.com/github/riboseinc/metanorma-ietf/badges/gpa.svg["Code Climate", link="https://codeclimate.com/github/riboseinc/metanorma-ietf"]
11
+
12
+ _Formerly known as_ `asciidoctor-rfc`.
13
+
14
+
15
+ == Functionality
16
+
17
+ This gem processes http://asciidoctor.org/[Asciidoctor] documents following
18
+ a template for generating IETF International Standards.
19
+
20
+ This AsciiDoc syntax for writing IETF standards is called "`AsciiRFC`".
21
+
22
+ The gem currently inherits from the https://github.com/riboseinc/metanorma-standoc
23
+ gem, and aligns closely to it.
24
+
25
+ The following outputs are generated:
26
+
27
+ * RFC XML v2
28
+ ** Metanorma `doctype`: `rfc2`
29
+ ** Metanorma file extension: `xmlrfc` (not `xml`!)
30
+
31
+ * RFC XML v3
32
+ ** Metanorma `doctype`: `rfc3`
33
+ ** Metanorma file extension: `xmlrfc` (not `xml`!)
34
+
35
+ The "`xml2rfc`" Vocabulary (hereinafter "`RFC XML`") is an XML-based language
36
+ used for writing
37
+ https://www.ietf.org/id-info/guidelines.html[Internet-Drafts]
38
+ and https://tools.ietf.org/html/rfc7322[RFCs (RFC7322)].
39
+
40
+ This gem allows you to author these types of documents in AsciiDoc, and outputs
41
+ RFC XML output in both v3 and v2 formats:
42
+
43
+ * v3 RFC XML (https://tools.ietf.org/html/rfc7991[RFC 7991])
44
+ * v2 RFC XML (https://tools.ietf.org/html/rfc7749[RFC 7749])
45
+
46
+ Its syntax is designed to be "`native-asciidoctor`" as much as possible, with
47
+ some templated use of attributes to convey added information for RFC XML
48
+ output.
49
+
50
+ This README documents the AsciiRFC markup in full detail. For further
51
+ information about AsciiRFC, please refer to the
52
+ https://datatracker.ietf.org/doc/draft-ribose-asciirfc/[AsciiRFC IETF Internet-Draft].
53
+
54
+
55
+
56
+ == Usage
57
+
58
+ The preferred way to invoke this gem is via the `metanorma` command:
59
+
60
+ [source,console]
61
+ ----
62
+ $ metanorma --type rfc3 a.adoc # output RFC XML v3
63
+ $ metanorma --type rfc3 --extensions xmlrfc a.adoc # output RFC XML v3
64
+ ----
65
+
66
+ The gem translates the document into IETF XML RFC format.
67
+
68
+ Text and HTML versions should be generated using the `xml2rfc` tool.
69
+
70
+
71
+ == Installation
72
+
73
+ === Metanorma
74
+
75
+ Please visit https://www.metanorma.com for installation instructions
76
+ for all platforms.
77
+
78
+
79
+ === Gem usage
80
+
81
+ Add this line to your application's Gemfile:
82
+
83
+ [source,ruby]
84
+ ----
85
+ gem "metanorma-ietf"
86
+ ----
87
+
88
+ And then execute:
89
+
90
+ [source,console]
91
+ ----
92
+ $ bundle
93
+ ----
94
+
95
+
96
+
97
+ == Quick Start / Template
98
+
99
+ Clone the
100
+ https://github.com/riboseinc/rfc-in-asciidoc-template[`rfc-in-asciidoc-template`]
101
+ repository as a template, and populate it for your Asciidoc RFCs and
102
+ Internet-Drafts:
103
+
104
+ [source,console]
105
+ ----
106
+ $ git clone https://github.com/riboseinc/rfc-in-asciidoc-template
107
+ ----
108
+
109
+ See the https://github.com/riboseinc/rfc-in-asciidoc-template[README] of that document for
110
+ more information.
111
+
112
+
113
+ == Quick Example
114
+
115
+ Illustrating with v2 RFC XML, and Internet Draft rather than RFC
116
+
117
+ [source,asciidoc]
118
+ ----
119
+ = A Standard for the Transmission of IP Datagrams on Avian Carriers
120
+ David Waitzman <dwaitzman@BBN.COM>
121
+ :doctype: internet-draft
122
+ :abbrev: IP Datagrams on Avian Carriers
123
+ :obsoletes: 10, 120
124
+ :updates: 2010, 2120
125
+ :status: informational
126
+ :name: internet-draft-avian-transmission-00
127
+ :ipr: trust200902
128
+ :area: Internet
129
+ :workgroup: Network Working Group
130
+ :keyword: avians, datagrams
131
+ :revdate: 1990-04-01T00:00:00Z
132
+ :organization: BBN STC
133
+ :phone: (617) 873-4323
134
+ :uri: http://bbn.com
135
+ :street: 10 Moulton Street
136
+ :city: Cambridge
137
+ :code: MA 02238
138
+
139
+ [abstract]
140
+ Avian carriers can provide high delay, low throughput, and low
141
+ altitude service. The connection topology is limited to a single
142
+ point-to-point path for each carrier, used with standard carriers,
143
+ but many carriers can be used without significant interference with
144
+ each other, outside of early spring. This is because of the 3D ether
145
+ space available to the carriers, in contrast to the 1D ether used by
146
+ IEEE802.3. The carriers have an intrinsic collision avoidance
147
+ system, which increases availability. Unlike some network
148
+ technologies, such as packet radio, communication is not limited to
149
+ line-of-sight distance. Connection oriented service is available in
150
+ some cities, usually based upon a central hub topology.
151
+
152
+ NOTE: Yes, this is an April Fool's RFC.
153
+
154
+ [[frame]]
155
+ == Frame Format
156
+
157
+ The IP _datagram_ is *printed*, on a small scroll of paper, in
158
+ hexadecimal, with each octet separated by whitestuff and blackstuff.
159
+ The scroll of paper is wrapped around one leg of the avian carrier.
160
+ A band of duct tape is used to secure the datagram's edges. The
161
+ bandwidth is limited to the leg length. The MTU is variable, and
162
+ paradoxically, generally increases with increased carrier age. A
163
+ typical MTU is 256 milligrams. Some datagram padding may be needed.<<RFC7253>>
164
+
165
+ [bibliography]
166
+ == Normative References
167
+ ++++
168
+ <reference anchor="RFC2119" target="https://www.rfc-editor.org/info/rfc2119">
169
+ <front>
170
+ <title>Key words for use in RFCs to Indicate Requirement Levels</title>
171
+ <author initials="S." surname="Bradner" fullname="S. Bradner">
172
+ <organization/>
173
+ </author>
174
+ <date year="1997" month="March"/>
175
+ <abstract>
176
+ <t>In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements.</t>
177
+ </abstract>
178
+ </front>
179
+ <seriesInfo name="BCP" value="14"/>
180
+ <seriesInfo name="RFC" value="2119"/>
181
+ <seriesInfo name="DOI" value="10.17487/RFC2119"/>
182
+ </reference>
183
+ ++++
184
+
185
+ [bibliography]
186
+ == Informative References
187
+ ++++
188
+ <reference anchor='RFC7253' target='https://tools.ietf.org/html/rfc7253'>
189
+ <front>
190
+ <title>Guidelines for Writing an IANA Considerations Section in RFCs</title>
191
+ <author initials="T." surname="Krovetz">
192
+ <organization>Sacramento State</organization>
193
+ </author>
194
+ <author initials="P." surname="Rogaway">
195
+ <organization>UC Davis</organization>
196
+ </author>
197
+ <date month='May' year='2014'/>
198
+ </front>
199
+ <seriesInfo name="RFC" value="7253"/>
200
+ </reference>
201
+ ++++
202
+ ----
203
+
204
+
205
+ == Usage
206
+
207
+ Converting your AsciiDoc to RFC XML is a simple as running the appropriate
208
+ `metanorma` command.
209
+
210
+ Once processing completes, you should see the RFC XML file `draft-example-00.xml` in the
211
+ same directory.
212
+
213
+
214
+ == Syntax
215
+
216
+ The converter follows native AsciiDoc/asciidoctor syntax as much as possible,
217
+ including built-in attributes and styles.
218
+
219
+ Extension commands are provided to fully support writing an Internet-Draft/RFC
220
+ in AsciiDoc/asciidoctor syntax.
221
+
222
+ [NOTE]
223
+ ====
224
+ The document model of Asciidoctor and RFC XML are different. In particular,
225
+
226
+ * Asciidoctor and RFC XML differ in where they allow anchors to be placed:
227
+ Asciidoctor does not allow anchors within tables and lists, and RFC XML v3 does
228
+ not permit anchors for the `note` or `abstract` elements, while RFC XML v2
229
+ uses anchors for much fewer block elements (e.g. `artwork`, `list`.)
230
+ * Asciidoctor has a more restrctive block model: it regards elements such as
231
+ admonitions, lists, and tables as blocks, and does not allow them to be nested
232
+ within paragraphs.
233
+
234
+ As a result, it may be necessary to postedit the RFC XML output, if the block
235
+ model produced does not reflect the intended structure accurately.
236
+ ====
237
+
238
+ NOTE: The gem validates all RFC XML generated through the RELAXNG schema definitions
239
+ of RFC XML. While the gem attempts to generate valid RFC XML, some Asciidoctor
240
+ text may not align with the RFC XML document model, and any highlighted syntax
241
+ errors will also need to be rectified in postediting, before processing the
242
+ generated XML further.
243
+
244
+ NOTE: A summary guide to authoring RFC XML in Asciidoctor is available at
245
+ https://datatracker.ietf.org/doc/draft-ribose-asciirfc/ (with source at
246
+ https://github.com/riboseinc/rfc-asciidoc-rfc ).
247
+
248
+
249
+
250
+ == Document Attributes
251
+
252
+
253
+ === Document Type: `rfc` or `internet-draft` (Mandatory)
254
+
255
+ Set the `doctype` attribute to set status of this document:
256
+
257
+ `:doctype: internet-draft` sets the document as an Internet-Draft (default value):
258
+
259
+ * `rfc/front/seriesInfo@name` attribute will be set to `Internet-Draft` (in v3)
260
+ * `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)
261
+ * `rfc@docName` will be set to the `:name:` attribute (in v2)
262
+
263
+ `:doctype: rfc` sets the document as an RFC:
264
+
265
+ * `rfc/front/seriesInfo@name` attribute will be set to `RFC` (in v3)
266
+ * `rfc/front/seriesInfo@value` will be set to the `:name:` attribute, stripping the initial `rfc-` prefix and any file suffixes (in v3)
267
+ * `rfc@number` will be set to the `:name:` attribute (in v2)
268
+
269
+
270
+ === Global Options
271
+
272
+ [cols="2", options="header"]
273
+ |===
274
+
275
+ | Attribute
276
+ | Purpose
277
+
278
+ |`:no-rfc-bold-bcp14:`
279
+ | Optional. Default value `true`. Allowed values: `true`, `false`.
280
+ Override default assumption that boldface uppercase BCP14 word is to be rendered with `bcp14` tag.
281
+
282
+ |`:smart-quotes:`
283
+ |Optional. Default value `true`. Allowed values: `true`, `false`.
284
+ Permit smart quotes, when they are specified explicitly in Asciidoc (as `"`...`"`, `'`...`'`.)
285
+ When disabled, smart quotes are rendered as straight quotes, and Asciidoc's default conversion
286
+ of straight apostrophes to smart is undone.
287
+
288
+ |`:inline-definition-lists:`
289
+ |Optional. Default value `false`. Allowed values: `true`, `false`.
290
+ Only applies to v2. By default, `<vspace blankLines="1">` is inserted after
291
+ the definition in a v2 definition list, to satisfy the requirement from `idnits` validation
292
+ that definition terms be separated by a carriage return from the definition. That is, by
293
+ default inline definition lists are rendered as paragraphing definition lists. If the option is
294
+ on, the additional `vspace` element is not added, and inline definition lists are left as is.
295
+
296
+ |`:flush-caches:`
297
+ |Optional. Default value `false`. Allowed values: `true`, `false`.
298
+ Delete and reload the caches of references to be included externally, and of workgroups,
299
+ during processing of this document.
300
+ The caches are stored in `~/.asciidoc-rfc-biblio-cache.json` and `~/.asciidoc-rfc-workgroup-cache.json`.
301
+
302
+ |`:biblio-dir:`
303
+ |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.
304
+
305
+ |`:normative:`
306
+ |Optional. Comma-delimited list of reference anchors. Used in conjunction with `:biblio-dir:`, which uses a single directory for all references: this attribute
307
+ lists those references which are to be considered normative, and listed under the _Normative References_ heading.
308
+
309
+ |===
310
+
311
+ ////
312
+ Any of these global options can also be included in the command line call, for either
313
+ the asciidoctor executable or the local bin-stubs, through the command line option `-a`;
314
+ e.g.
315
+
316
+ [source,console]
317
+ ----
318
+ $ asciidoctor -a flush-biblio=true -b rfc3 -r 'asciidoctor-rfc' a.adoc
319
+ $ ./bin/asciidoctor-rfc2 -a smart-quotes=false draft-example-00.adoc
320
+ ----
321
+ ////
322
+
323
+ [[caches]]
324
+ ==== Caches
325
+
326
+ The cache of externally addressable bibliographic information is built from screenscraping the contents of:
327
+
328
+ * https://xml2rfc.tools.ietf.org/public/rfc/bibxml/
329
+ * https://xml2rfc.tools.ietf.org/public/rfc/bibxml2/
330
+ * https://xml2rfc.tools.ietf.org/public/rfc/bibxml3/
331
+ * https://xml2rfc.tools.ietf.org/public/rfc/bibxml4/
332
+ * https://xml2rfc.tools.ietf.org/public/rfc/bibxml5/
333
+
334
+ The cache of current IETF and IRTF workgroups is built from screenscraping the contents of:
335
+
336
+ * https://tools.ietf.org/wg/
337
+ * https://irtf.org/groups
338
+
339
+ The caches are not rebuilt daily, as the bibliographic cache is with `xml2rfc`.
340
+ If you want to refresh the caches,
341
+
342
+ * delete
343
+ your `~/.asciidoc-rfc-biblio-cache.json` and `~/.asciidoc-rfc-workgroup-cache.json` files;
344
+ * insert the document attribute `:flush-caches: true` into
345
+ the header of the document being processed; or
346
+ * run the asciidoctor executable with option `-a flush-caches=true`
347
+ (which has the same effect).
348
+
349
+
350
+ === Basic Document Attributes
351
+
352
+ `metanorma-ietf` allows setting the RFC XML document header using the following
353
+ document attributes. Complying with AsciiDoc syntax, no blank lines are
354
+ permitted between the title, listing of authors, and the document attributes.
355
+ Also following AsciiDoc syntax, character entities will be ignored in the document
356
+ header: `&nbsp;` in the header for example will be rendered as `&amp;nbsp;`.
357
+
358
+ Shared RFC XML v3/v2 syntax:
359
+
360
+ [cols="3", options="header"]
361
+ |===
362
+
363
+ | Attribute
364
+ | Purpose
365
+ | RFC XML v2/v3 element
366
+
367
+ | `= Document Title`
368
+ | Mandatory. Title of document.
369
+ | `rfc/front/title`
370
+
371
+ | `:abbrev:`
372
+ | Mandatory. Abbreviation of document title. Usually the document name without
373
+ the keyword `draft-`.
374
+ | `rfc/front/title@abbrev`
375
+
376
+ | `:ipr:`
377
+ | Mandatory. IP status of document. See
378
+ https://tools.ietf.org/html/rfc7991#section-2.45.5[here]. Defaults to
379
+ `trust200902`.
380
+ | `rfc@ipr`
381
+
382
+ | `:ipr-extract:`
383
+ | Optional. Identifies a section that can be extracted from text. See
384
+ https://tools.ietf.org/html/rfc7991#section-2.45.6[here].
385
+ | `rfc@iprExtract`
386
+
387
+ | `:obsoletes:`
388
+ | Optional. A comma-separated list of RFC numbers or Internet-Draft names that
389
+ this document obsoletes. Delimited by `comma + space`.
390
+ | `rfc@obsoletes`
391
+
392
+ | `:updates:`
393
+ | Optional. A comma-separated list of RFC numbers or Internet-Draft names that
394
+ this document updates. Delimited by `comma + space`.
395
+ | `rfc@updates`
396
+
397
+ | `:submission-type:`
398
+ | Optional. Document stream of document described in
399
+ https://tools.ietf.org/html/rfc7841[RFC7841]. Allowed values: `IETF` (default),
400
+ `independent`, `IAB`, and `IRTF`.
401
+ | `rfc@submissionType`
402
+
403
+ | `:revdate:`
404
+ | Optional. Latest revision date of document. Default value is current time.
405
+ Accepts ISO 8601 date. Also accepts YYYY year, and YYYY[-]MM year/month.
406
+ For consistency with AsciiDoc, `:revdate:` is given as
407
+ an ISO 8601 date; the converter breaks it down into day, month name and year
408
+ | `front/date@day`, `front/date@month`, `front/date@year`
409
+
410
+ | `:area:`
411
+ | Optional. Comma delimited text on which IETF area this document relates to. Value should
412
+ "be either the full name or the abbreviation of one of the IETF areas as
413
+ listed on <http://www.ietf.org/iesg/area.html>". See
414
+ https://tools.ietf.org/html/rfc7991#section-2.4[here].
415
+ | `front/area`
416
+
417
+ | `:workgroup:`
418
+ | Optional. Comma delimited text on which IETF or IRTF workgroup or research group this
419
+ document originates from. See https://tools.ietf.org/html/rfc7991#section-2.65[here].
420
+ | `front/workgroup`
421
+
422
+ | `:keyword:`
423
+ | Optional. Comma delimited text for singular keywords used for RFC index and
424
+ metadata.
425
+ | `front/keyword`
426
+
427
+ |===
428
+
429
+ === Processing Instructions
430
+ The `xml2rfc` tool accepts processing instructions of the form `<?rfc keyword='value'?>`:
431
+ see https://xml2rfc.tools.ietf.org/authoring/README.html#processing.instructions .
432
+ (Of these, `sort-refs`, `sym-refs` and `toc-include` are also present in the
433
+ v3 RFC XML specifcation, as attributes of the
434
+ root `rfc` element: <<v3documentattributes,v3-specific document attributes>>.)
435
+ Those processing instructions which apply to the entire document can also be
436
+ specified for this gem as document options.
437
+
438
+ |===
439
+ |keyword |meaning
440
+
441
+ |artworkdelimiter | when producing txt or nroff files, use this string to delimit artwork
442
+ |artworklines | when producing txt or nroff files, add this many blank lines around artwork
443
+ |authorship | render author information
444
+ |autobreaks | automatically force page breaks to avoid widows and orphans (not perfect)
445
+ |background | when producing a html file, use this image
446
+ |colonspace | put two spaces instead of one after each colon (":") in txt or nroff files
447
+ |comments | render <cref> information
448
+ |compact | when producing a txt/nroff file, try to conserve vertical whitespace (the default value is the current value of the rfcedstyle PI)
449
+ |docmapping | use hierarchical tags (e.g., <h1>, <h2>, etc.) for (sub)section titles
450
+ |editing | insert editing marks for ease of discussing draft versions
451
+ |emoticonic | automatically replaces input sequences such as \|*text\| by, e.g., <strong>text</strong> in html output
452
+ |footer | override the center footer string
453
+ |header | override the leftmost header string
454
+ |inline | if comments is "yes", then render comments inline; otherwise render them in an "Editorial Comments" section
455
+ |iprnotified | include boilerplate from Section 10.4(d) of http://tools.ietf.org/html/rfc2026
456
+ |linkmailto | generate mailto: URL, as appropriate
457
+ |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)
458
+ |notedraftinprogress | generates "(work in progress)", as appropriate
459
+ |private | produce a private memo rather than an RFC or Internet-Draft
460
+ |refparent | title of the top-level section containing all references
461
+ |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 <references> sections.
462
+ |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
463
+ |slides | when producing a html file, produce multiple files for a slide show
464
+ |sort-refs | (`sortrefs`) sort references
465
+ |strict | try to enforce the ID-nits conventions and DTD validity
466
+ |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)
467
+ |sym-refs | (`symrefs`) use anchors rather than numbers for references
468
+ |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.
469
+ |toc-include | (`toc`) generate a table-of-contents
470
+ |tocappendix | control whether the word "Appendix" appears in the table-of-content
471
+ |toc-depth | if toc is "yes", then this determines the depth of the table-of-contents
472
+ |tocindent | if toc is "yes", then setting this to "yes" will indent subsections in the table-of-contents
473
+ |tocnarrow | affects horizontal spacing in the table-of-content
474
+ |tocompact | if toc is "yes", then setting this to "no" will make it a little less compact
475
+ |topblock | put the famous header block on the first page
476
+ |useobject | when producing a html file, use the <object> html element with inner replacement content instead of the <img> html element, when a source xml element includes an src attribute
477
+ |===
478
+
479
+ Exceptionally, `compact`, `toc-include`, `sym-refs`, `sort-refs` and `strict` are is set by default to `yes`, `subcompact` to `no`, and `toc-depth` to 4.
480
+
481
+ The additional document option `rfc2629xslt` (default value: true) injects into the document header the processing
482
+ instruction `<?xml-stylesheet type="text/xsl" href="rfc2629.xslt" ?>`, which impacts on the output of xml2rfc.
483
+
484
+ === Document Name / Number (Mandatory)
485
+
486
+ The `name` attribute sets the document's name. This should be a number if
487
+ the document is an RFC, and a name (in the form of `draft-ietf-somewg-someprotocol-07`)
488
+ if it is an Internet-Draft.
489
+
490
+ When `doctype` is set to:
491
+
492
+ * `internet-draft`: the value should be in the form `draft-ietf-somewg-someprotocol-07`.
493
+ ** v3: the `front/seriesInfo@value` will be set to this value.
494
+ ** v2: the `rfc@docName` will be set to this value.
495
+
496
+ * `rfc`: the value should be a number like `7991` as described
497
+ https://tools.ietf.org/html/rfc7991#section-2.47.6[here]
498
+ ** v3: the `front/seriesInfo@value` will be set to this value.
499
+ ** v2: the `rfc@number` will be set to this value.
500
+
501
+
502
+ === Document Status
503
+
504
+ Set the `status` attribute to set the current status of this document.
505
+
506
+ The following values are allowed: `standard`, `informational`, `experimental`, `bcp`, `fyi`,
507
+ `full-standard` (v3 only), `historic` (v2 only).
508
+
509
+ * In v3, this sets the first `front/seriesInfo` element with `@status` as one
510
+ of: `standard`, `informational`, `experimental`, `bcp`, `fyi`, `full-standard`.
511
+ * In v2, this sets the `rfc@category` value as one of `std`, `info`, `exp`, `bcp`, `historic`.
512
+
513
+
514
+ === Intended Series
515
+
516
+ Set the `intended-series` attribute to set the intended series of this
517
+ document.
518
+
519
+ The following values are allowed: `standard`, `informational`, `experimental`, `bcp`, `fyi`, `full-standard`.
520
+
521
+ When `doctype` is set to:
522
+
523
+ * `internet-draft`: this value can be one of `standard`, `full-standard`, `bcp`, `fyi`, `informational`,
524
+ `experimental`, or `historic` to indicate the intended series once the document is published as an RFC.
525
+
526
+ ** In v3, this sets a second `front/seriesInfo` element with `@status` as one of those values, and an empty `@name`, to indicate this.
527
+ ** In v2, this sets the `front@category` value to one of `std`, `bcp`, `info`, `exp`, `historic`.
528
+
529
+ * `rfc`: this value can be either:
530
+ ** 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`.
531
+ ** `exp`, `info`, or `historic`. (`experimental` and `informational` will be accepted by the gem as synonyms.)
532
+
533
+ ** In v3, this sets a second `front/seriesInfo` element with `@status` as one of those values, and an empty `@name`, to indicate this.
534
+ ** 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.)
535
+
536
+ === Document Submission Type / Stream
537
+
538
+ Set document submission type via the `submission-type` document attribute.
539
+
540
+ The following values are allowed: `IETF` (default), `independent`, `IAB`, and `IRTF`.
541
+
542
+ * In v3, the `rfc@submissionType` and `rfc/front/seriesInfo@stream` attributes are set to this value.
543
+ * In v2, the `rfc@submissionType` is set to this value
544
+
545
+ === Document Consensus
546
+
547
+ Set document consensus type via the `consensus` document attribute.
548
+
549
+ These values are accepted: `false`, `true`.
550
+
551
+ * In v3, this is the value set for the `rfc@consensus` attribute.
552
+ * In v2, this is the value set for the `rfc@consensus` attribute, but `false` is converted to `no` and `true` is converted to `yes`.
553
+
554
+ === Document Language
555
+
556
+ Set the document language using the `xml-lang` document attribute.
557
+
558
+ By default this is `en`.
559
+
560
+ * In v3 and v2, this is the value set for the `rfc@xml:lang` attribute.
561
+
562
+ While v3 supports marking specific elements with their own `xml:lang` attribute, this is not yet supported by our gem.
563
+
564
+
565
+ === Document Attributes for v2 only
566
+
567
+ These attributes are only supported for the v2 converter.
568
+
569
+ [cols="3", options="header"]
570
+ |===
571
+
572
+ | Attribute
573
+ | Purpose
574
+ | RFC XML v3 element
575
+
576
+ |`:series-no:`
577
+ | Optional. The document series is defined by the "category" attribute;
578
+ "seriesNo" is only applicable to the values "info" ("FYI" series),
579
+ "std" ("STD" series), and "bcp" ("BCP" series).
580
+ | `rfc@seriesNo`
581
+ |===
582
+
583
+ [#v3documentattributes]
584
+ === Document Attributes for v3 only
585
+
586
+ These attributes are only supported for the v3 converter.
587
+
588
+ [cols="3", options="header"]
589
+ |===
590
+
591
+ | Attribute
592
+ | Purpose
593
+ | RFC XML v3 element
594
+
595
+ |`:index-include:`
596
+ | Optional. Defaults to `true`. Values: `true` or `false`. Specifies whether
597
+ formatter should include an index in generated files. If the source file has no
598
+ `<iref>` elements, an index is never generated.
599
+ | `rfc@indexInclude`
600
+
601
+ |`:sort-refs:`
602
+ | Optional. Defaults to `false`. Values: `true` or `false`. Specifies whether
603
+ the prep tool should sort references. Supported in v2 as a processing instruction.
604
+ | `rfc@sortRefs`
605
+
606
+ |`:sym-refs:`
607
+ | Optional. Defaults to `true`. Values: `true` or `false`. Specifies whether
608
+ formatter should use symbolic references (such as "`[RFC2119]`") or not
609
+ (such as "`[3]`"). Supported in v2 as a processing instruction.
610
+ | `rfc@symRefs`
611
+
612
+ |`:toc-include:`
613
+ | Optional. Defaults to `true`. Values: `true` or `false`. Specifies whether
614
+ formatter should contain a table of contents. Supported in v2 as a processing instruction.
615
+ | `rfc@tocInclude`
616
+
617
+ | `:link: _URL_, _URL_ _REL_`
618
+ a| Optional. Comma-delimited links to an external document related to this document.
619
+
620
+ There are 4 types of values:
621
+
622
+ . (RFC only) ISSN for this RFC document (`rel` set to `item`, `link` value in
623
+ form of `urn:issn:`);
624
+ . (RFC only) DOI for this RFC document (`rel` set to `describedBy`, `link`
625
+ value in form specified by https://tools.ietf.org/html/rfc7669[RFC7669]);
626
+ . (Final Draft) Internet-Draft submitted to become published RFC (`rel` set to
627
+ `convertedFrom`, `link` value set to "IETF-controlled web site that retains
628
+ copies of Internet-Drafts");
629
+ . (Any status) ISSN (`rel` set to `alternate`, `link` value as any author run web site).
630
+ | `front/link@href = _URL_`, `front/link@rel = _REL_` (if supplied)
631
+
632
+ |===
633
+
634
+
635
+ === Author Attributes
636
+
637
+ In an Internet-Draft/RFC, detailed information of an author is necessary, which
638
+ is not supported by the normal AsciiDoc syntax.
639
+
640
+ You will need to provide the following information.
641
+
642
+
643
+ ==== Multiple Author Names
644
+
645
+ Just like a normal AsciiDoc, you can provide author information in the author
646
+ header (sample of 3 authors):
647
+
648
+ [source,asciidoc]
649
+ ----
650
+ firstname middlename(s) lastname <email>; firstname middlename(s) lastname <email>; firstname middlename(s) lastname <email>
651
+ ----
652
+
653
+ These will be mapped as follows:
654
+
655
+ [cols="3", options="header"]
656
+ |===
657
+
658
+ | Syntax
659
+ | Purpose
660
+ | RFC XML v3/v2 element
661
+
662
+ | `firstname middlename(s) lastname`
663
+ | Mandatory (at least one). Author's full name. (Middle names are optional.)
664
+ | `front/author@fullname`
665
+
666
+ | `lastname`
667
+ | Author's last name.
668
+ | `front/author@surname`
669
+
670
+ | `email`
671
+ | Author's email address.
672
+ | `front/author/address/email`
673
+
674
+ |===
675
+
676
+ If any author names deviate from that pattern, e.g. with an honorific like Dr.,
677
+ they will not be recognised correctly by the Asciidoc API; use the `fullname`
678
+ document attribute instead.
679
+
680
+ ==== Author Attributes
681
+
682
+ In `metanorma-ietf`, detailed author attributes are given as document
683
+ attributes.
684
+
685
+ As multiple authors can be specified, the document attribute to specify the
686
+ first author uses a unsuffixed attribute name `:role`, and the second author's
687
+ attributes onwards use a numeric suffix to identify the author: `:role_2`, `:role_3`, etc.
688
+
689
+ Shared RFC XML v3/v2 syntax:
690
+
691
+ [cols="3", options="header"]
692
+ |===
693
+
694
+ | Attribute
695
+ | Purpose
696
+ | RFC XML v3/v2 element
697
+
698
+ | `:fullname{_i}:`
699
+ | Optional. Author's full name. Can set here instead of document header's "`Author`" line.
700
+ | `front/author@fullname`
701
+
702
+ | `:forename_initials{_i}:`
703
+ | Optional. Author's initials excluding surname. Defaults to dynamically
704
+ calculated initials. Distinct from the AsciiDoc `:initials:` attribute, which
705
+ includes surname.
706
+ | `front/author@initials`
707
+
708
+ | `:lastname{_i}:`
709
+ | Optional. Author's last name. Can set here instead of document header's "`Author`" line.
710
+ | `front/author@surname`
711
+
712
+ | `:role{_i}:`
713
+ | Optional. Defaults to `author`. Possible values: `author`, `editor`. If `author` is supplied,
714
+ the attribute is not populated.
715
+ | `front/author@role`
716
+
717
+ | `:organization{_i}:`
718
+ | Optional. Defaults to `""`. Author's organization affiliation.
719
+ | `front/author/organization`
720
+
721
+ | `:organization_abbrev{_i}:`
722
+ | Optional. Defaults to `""`. Author's organization's abbreviation shown .
723
+ | `front/author/organization@abbrev`
724
+
725
+ |===
726
+
727
+ NOTE: You can provide organization information without providing name information
728
+ for an author.
729
+
730
+ ===== Author Address
731
+
732
+ [cols="3", options="header"]
733
+ |===
734
+ | Attribute
735
+ | Purpose
736
+ | RFC XML v2/v3 element
737
+
738
+ | `:email{_i}:`
739
+ | Email of author.
740
+ | `front/author/address/email`
741
+
742
+ | `:fax{_i}:`
743
+ | Fax number of author. Deprecated in v3.
744
+ | `front/author/address/facsimile`
745
+
746
+ | `:uri{_i}:`
747
+ | URI of author.
748
+ | `front/author/address/uri`
749
+
750
+ | `:phone{_i}:`
751
+ | Author's phone number. Scheme-specific part of a `tel` URI (does not include
752
+ the prefix `tel:`).
753
+ See https://tools.ietf.org/html/rfc3966#section-3[RFC3966 `global-number-digits`].
754
+ | `front/author/address/phone`
755
+
756
+ | `:street{_i}:`
757
+ | Address of author, non-city/region/code/country portion.
758
+ Multiple lines concatenated with `"\ "` will be split into separate `<street>`
759
+ elements.
760
+ | `front/author/address/postal/street`
761
+
762
+ | `:city{_i}:`
763
+ | City portion of author's address
764
+ | `front/author/address/postal/city`
765
+
766
+ | `:region{_i}:`
767
+ | Region, state or province portion of author's address. For US/CA the 2-letter state code.
768
+ | `front/author/address/postal/region`
769
+
770
+ | `:country{_i}:`
771
+ | Country of author's address
772
+ | `front/author/address/postal/country`
773
+
774
+ | `:code{_i}:`
775
+ | Postal code of author's address
776
+ | `front/author/address/postal/code`
777
+ |===
778
+
779
+
780
+ Only available for RFC XML v3:
781
+
782
+ |===
783
+ | Attribute | Purpose | RFC XML v3 element
784
+ | `:postal-line{_i}:`
785
+ | For those who want to directly format their postal addresses without regard
786
+ to the prior types. Ignored in v2. Multiple lines are concatenated with `"\ "`.
787
+ The `postal-line` attribute is mutually exclusive with the presence of `street`,
788
+ `city`, `region`, `country` and `code` attributes.
789
+ | `front/author/address/postal/postalLine`
790
+ |===
791
+
792
+
793
+ Example. This source:
794
+
795
+ [source,asciidoc]
796
+ ----
797
+ :street: 57 Mt Pleasant St\ Technology Park
798
+ :city: Dullsville
799
+ :region: NSW
800
+ :country: Australia
801
+ :code: 3333
802
+ ----
803
+
804
+ Produces:
805
+
806
+ [source,xml]
807
+ ----
808
+ <address>
809
+ <postal>
810
+ <street>57 Mt Pleasant St</street>
811
+ <street>Technology Park</street>
812
+ <city>Dullsville</city>
813
+ <region>NSW</region>
814
+ <code>3333</code>
815
+ <country>Australia</country>
816
+ </postal>
817
+ </address>
818
+ ----
819
+
820
+
821
+ === Abstract
822
+
823
+ Any paragraphs following the document header are treated as the abstract
824
+ (`front/abstract`), whether or not they are in abstract style. The abstract is
825
+ terminated by either the first section header (which ends the document
826
+ preamble), or an admonition (e.g. `note`).
827
+
828
+ Any admonitions before the first section header are treated as notes (`front/note`).
829
+
830
+ [source,asciidoc]
831
+ ----
832
+ [[abstract-id]] <1>
833
+ [abstract]
834
+ This is an abstract <2>
835
+
836
+ NOTE: This is a note <3>
837
+
838
+ [NOTE,remove-in-rfc=true] <4>
839
+ .Note 2 Title <5>
840
+ ===
841
+ This is another note <3>
842
+ ===
843
+ ----
844
+ <1> v3 only: `front/abstract@anchor` (attribute only available in v3)
845
+ <2> `front/abstract`
846
+ <3> `front/note`
847
+ <4> v3 only: `front/note@removeInRFC` (attribute only available in v3)
848
+ <5> v3: `front/note/name`; v2: `front/note@title` (mandatory attribute; if not provided, `NOTE` is supplied)
849
+
850
+
851
+ === Sections and Subsections
852
+
853
+ [source,asciidoc]
854
+ ----
855
+ :sectnums: <1>
856
+ [[id]] <2>
857
+ [remove-in-rfc=true,toc=include|exclude|default] <3>
858
+ == Section title <4>
859
+ First paragraph of section <5>
860
+
861
+ Second paragraph of section <5>
862
+
863
+ :sectnums!: <6>
864
+ === Subsection title <7>
865
+ First paragraph of subsection <8>
866
+
867
+ ==== Subsubsection title <9>
868
+ Content content content <10>
869
+ ----
870
+ <1> `middle/section@numbered=true` (attribute only available in v3)
871
+ <2> `middle/section@anchor`
872
+ <3> v3 only: `middle/section@removeInRFC`, `middle/section@toc` (attributes only available in v3)
873
+ <4> v3: `middle/section/name`; v2: `middle/section@title`
874
+ <5> `middle/section/t`
875
+ <6> `middle/section@numbered=false` (attribute only available in v3) (toggle)
876
+ <7> v3: `middle/section/section/name`; v2: `middle/section/section@title`
877
+ <8> `middle/section/section/t`
878
+ <9> v3: `middle/section/section/section/name`; v2: `middle/section/section/section@title`
879
+ <10> `middle/section/section/section/t`
880
+
881
+
882
+ === Cross-References
883
+
884
+ [source,asciidoc]
885
+ ----
886
+ Content content content
887
+ <<crossreference>> <1>
888
+ <<crossreference,text>> <2>
889
+ <<crossreference,format=(counter|title|none|default): text>> <3>
890
+ http://example.com/[linktext] <4>
891
+ The following represent the v3 relref element
892
+ <<crossreference,section_number (of|comma|parens|bare)>> <5>
893
+ <<crossreference,section_number (of|comma|parens|bare): text>> <6>
894
+ <<crossreference#fragment,section_number (of|comma|parens|bare)>> <7>
895
+ <<crossreference#fragment,section_number (of|comma|parens|bare): text>> <8>
896
+ ----
897
+ <1> `<xref target="crossreference"/>`
898
+ <2> `<xref target="crossreference">text</xref>`
899
+ <3> `<xref format="counter|title|none|default" target="crossreference">text</xref>`
900
+ <4> `<eref href="http://example.com/">linktext</eref>`
901
+ <5> v3 only: `<relref displayFormat="of|comma|parens|bare" section="section_number" target="crossreference"/>` (element only available in v3)
902
+ <6> v3 only: `<relref displayFormat="of|comma|parens|bare" section="section_number" target="crossreference">text</relref>` (element only available in v3)
903
+ <7> v3 only: `<relref relative="fragment" displayFormat="of|comma|parens|bare" section="section_number" target="crossreference"/>` (element only available in v3)
904
+ <8> v3 only: `<relref relative="fragment" displayFormat="of|comma|parens|bare" section="section_number" target="crossreference">text</relref>` (element only available in v3)
905
+
906
+ In v2, the relref style crossreferences are rendered as equivalent `xref` crossreferences,
907
+ inserting section numbers as appropriate.
908
+
909
+ Note that fragments (e.g. `crossreference#fragment`) are not supported on the `xref@target` attribute,
910
+ in either v2 or v3: the RFC XML specification requires that the `xref@target` attribute equals
911
+ the value of an anchor attribute elsewhere in the document.
912
+
913
+ Internal crossreferences and bibliographic references are marked up in the same way; but
914
+ bibliographic references are marked up separately from the main flow of Asciidoctor, and are
915
+ processed later.
916
+
917
+ NOTE: Normally, Asciidoctor attempts to match a crossreference to a section title, if it does not find
918
+ a matching anchor ID. This behaviour has become optional as of Asciidoctor 1.5.7, and is suppressed in
919
+ this gem. If you have a citation of a bibliographic item which is identical to a section title (e.g. you have a
920
+ bibliographic citation with the anchor "WHIRLPOOL", and a section with the title "WHIRLPOOL"),
921
+ this gem will correctly pick the former as the target of the reference, so long as that section
922
+ has a different anchor ID:
923
+
924
+ [source,asciidoc]
925
+ ----
926
+ [[hash_whirlpool]]
927
+ === WHIRLPOOL
928
+
929
+ The WHIRLPOOL hash function is defined in <<WHIRLPOOL>>.
930
+
931
+ This section should actually be referenced as <<hash_whirlpool>>.
932
+ ...
933
+
934
+ [bibliography]
935
+ == Informative References
936
+ ++++
937
+ <reference anchor='WHIRLPOOL' target='http://www.larc.usp.br/~pbarreto/WhirlpoolPage.html'>
938
+ ...
939
+ ++++
940
+ ----
941
+
942
+ === Indexing
943
+
944
+ [source,asciidoc]
945
+ --
946
+ This ((<indexterm>)) <1>
947
+ is visible in the text,
948
+ this one is not (((indexterm, index-subterm))). <2>
949
+ --
950
+ <1> `<iref item="indexterm">indexterm</iref>`
951
+ <2> `<iref item="indexterm" subitem="index-subterm"/>`
952
+
953
+
954
+ === Inline formatting
955
+
956
+ [source,asciidoc]
957
+ --
958
+ Linebreak: + <1>
959
+ _Italic_ <2>
960
+ *Bold* <3>
961
+ `Monospace` <4>
962
+ ~subscript~ <5>
963
+ ^superscript^ <6>
964
+ [bcp14]#MUST NOT# <7>
965
+ *MUST NOT* <8>
966
+ stem:[sqrt(4) = 2]
967
+ --
968
+ <1> That is, "+ " at the end of a line. v3: `<br/>`; v2: `<vspace/>`.
969
+ <2> v3: `<em>Italic</em>`; v2: `<spanx style="emph">Italic</spanx>`
970
+ <3> v3: `<strong>Bold</strong>`; v2: `<spanx style="strong">Bold</spanx>`
971
+ <4> v3: `<tt>Monospace</tt>`; v2: `<spanx style="verb">Monospace</spanx>`
972
+ <5> v3 only: `<sub>subscript</sub>`. Not supported in v2; rendered as `\_subscript_`
973
+ <6> v3 only: `<sup>superscript</sup>`. Not supported in v2; rendered as `\^superscript^`
974
+ <7> v3 only: `<bcp14>MUST NOT</bcp14>`. Not supported in v2; rendered as `<spanx style="strong">MUST NOT</spanx>`.
975
+ <8> v3: if document flag `:no-rfc-bold-bcp14:` is present, then `<strong>MUST NOT</strong>`, else (by default) any BCP14/RFC2119 phrase in boldface and capitals is assumed to be intended to be tagged in `<bcp14>`. v2: `<spanx style="strong">MUST NOT</spanx>`.
976
+ <9> Stem expressions are treated identically to monospace expressions; they are not currently rendered as MathML or any other notation.
977
+
978
+ NOTE: The delimiters must occur within the one line; the following is invalid in Asciidoctor:
979
+ [source,asciidoc]
980
+ --
981
+ *WOULD
982
+ PROBABLY*
983
+ --
984
+
985
+ Any formatting XML spans within `spanx` elements are stripped in postprocessing.
986
+
987
+ === Paragraphs
988
+
989
+ [source,asciidoc]
990
+ --
991
+ [[id]] <1>
992
+ [keep-with-next=true,keep-with-previous=true] <2>
993
+ Paragraph text <3>
994
+ --
995
+ <1> `t@anchor`
996
+ <2> v3 only: `t@keepWithNext`, `t@keepWithPrevious` (attributes only available in v3)
997
+ <3> `<t>Paragraph text</t>`
998
+
999
+ === Quotes (v3 only)
1000
+
1001
+ [source,asciidoc]
1002
+ --
1003
+ [[id]] <1>
1004
+ [quote, attribution, citation info] <2>
1005
+ Quotation <3>
1006
+ --
1007
+ <1> `blockquote@anchor`
1008
+ <2> `blockquote@quotedFrom`, `blockquote@cite`. In v3, `citation info` is limited to a URL.
1009
+ <3> `<blockquote>Quotation</blockquote>`
1010
+
1011
+
1012
+ === Comments
1013
+
1014
+ ==== Asciidoctor comments
1015
+
1016
+ Asciidoctor implements both inline comments (prefixed with `\\`)
1017
+ and block comments (prefixed with `\\\\`). Both are ignored by
1018
+ the Asciidoctor processor, and are not rendered in any output,
1019
+ including RFC XML.
1020
+
1021
+ Asciidoctor also permits paragraphs and open blocks (which can contain
1022
+ multiple paragraphs) to be treated as Asciidoctor comments, if
1023
+ they have the style attribute `[comment]`:
1024
+
1025
+ [source,asciidoc]
1026
+ ----
1027
+
1028
+ // This is an inline Asciidoctor comment, which will not be output to XML.
1029
+
1030
+ [comment]
1031
+ This is a single paragraph Asciidoctor comment,
1032
+ which will not be output to XML.
1033
+
1034
+ ////
1035
+ This is a block Asciidoctor comment,
1036
+
1037
+ which will not be output to XML.
1038
+ ////
1039
+
1040
+ [comment]
1041
+ --
1042
+ This is a
1043
+
1044
+ multiple paragraph
1045
+
1046
+ Asciidoctor comment, which will not be output to XML.
1047
+ --
1048
+ ----
1049
+
1050
+ ==== XML comments
1051
+
1052
+ XML inline comments may be introduced into XML through the `[comment]`
1053
+ formatting macro: any such comments may not span more than one line.
1054
+
1055
+ [source,asciidoc]
1056
+ --
1057
+ Text [comment]#This is a comment# Text
1058
+ --
1059
+
1060
+ The foregoing will be rendered in RFC XML as:
1061
+
1062
+ [source,xml]
1063
+ --
1064
+ <t>Text <!-- This is a comment --> Text</t>
1065
+ --
1066
+
1067
+ XML block comments are introduced through the role attribute
1068
+ `[.comment]`, which can be prefied to a paragraph or an open
1069
+ block (which can contain multiple paragraphs):
1070
+
1071
+ [source,asciidoc]
1072
+ ----
1073
+ [.comment]
1074
+ This is a single paragraph XML comment.
1075
+
1076
+ [.comment]
1077
+ --
1078
+ This is a
1079
+
1080
+ multiple paragraph
1081
+
1082
+ XML comment.
1083
+ --
1084
+ ----
1085
+
1086
+ ==== Text Comments
1087
+
1088
+ RFC XML provides for editorial comments which may optionally appear
1089
+ in the published text (subject to either the v3 `cref@display`
1090
+ attribute, or the `comments` processing instruction).
1091
+
1092
+ In v2 RFC XML, comment text is stripped of all formatting.
1093
+
1094
+ [source,asciidoc]
1095
+ --
1096
+ NOTE: Any admonition inside the body of the text is a comment. <1>
1097
+ // Note that actual AsciiDoc comments are ignored by the converter.
1098
+
1099
+ [[id]] <2>
1100
+ [NOTE,display=true|false,source=name] <3>
1101
+ .Note Title <4>
1102
+ ====
1103
+ Any admonition inside the body of the text is a comment.
1104
+ ====
1105
+ --
1106
+ <1> `<cref>Any admonition inside the body of the text is a comment.</cref>`
1107
+ <2> `cref@anchor`
1108
+ <3> v3 only: `cref@display` (not supported in v2); v2: `cref@source`
1109
+ <4> v3 only: `cref/name` (not suppported in v2)
1110
+
1111
+
1112
+ === Source Code Listings
1113
+
1114
+ In RFC XML, `sourcecode` (v3) and `artwork` (v2) elements only occur within a
1115
+ `figure` wrapper; this gem supplies that wrapper if it is not provided
1116
+ explicitly.
1117
+
1118
+ [source,asciidoc]
1119
+ .Without Figure Wrapper
1120
+ --
1121
+ [[id]] <1>
1122
+ .Source code listing title <2>
1123
+ [source,type,src=uri,align,alt] <3>
1124
+ ----
1125
+ begin() {
1126
+ source code listing <4>
1127
+ }
1128
+ ----
1129
+ --
1130
+ <1> v3: `figure/sourcecode@anchor`; v2: `figure@anchor` (moved into supplied wrapper: anchors not supported on `artwork`)
1131
+ <2> v3: `figure/sourcecode@name`; v2: `figure/artwork@name`
1132
+ <3> v3: `figure/sourcecode@type`; `figure/sourcecode@src` (`align` and `alt` not supported). If `src` is present, the listing is not expected to have any content: content is taken from the hyperlink in the attribute. v2: `figure/artwork@type`, `figure/artwork@src`, `figure/artwork@align`, `figure/artwork@alt`.
1133
+ <4> v3: `figure/sourcecode`; v2: `figure/artwork`
1134
+
1135
+ [source,asciidoc]
1136
+ .With Figure Wrapper
1137
+ --
1138
+ [[id]] <1>
1139
+ [align,alt,suppress-title] <2>
1140
+ .Figure 1 <3>
1141
+ ====
1142
+ Preamble text <4>
1143
+
1144
+ [[id1]] <5>
1145
+ .Source code listing title <6>
1146
+ [source,type,src=uri,align,alt] <7>
1147
+ ----
1148
+ begin() {
1149
+ source code listing <8>
1150
+ }
1151
+ ----
1152
+
1153
+ Postamble text <9>
1154
+ ====
1155
+ --
1156
+ <1> `figure@anchor`
1157
+ <2> v2 only: `figure/artwork@align`, `figure/artwork@alt`, `figure@suppress-title` (attributes only available in v2)
1158
+ <3> `figure/name`
1159
+ <4> v2 only: `figure/preamble` (only available in v2)
1160
+ <5> v3: `figure/sourcecode@anchor`; v2: Not supported: use `figure@anchor`
1161
+ <6> v3: `figure/sourcecode@name`; v2: `figure/artwork@name`
1162
+ <7> v3: `figure/sourcecode@type`; `figure/sourcecode@src` (`align` and `alt` not supported). If `src` is present, the listing is not expected to have any content: content is taken from the hyperlink in the attribute. v2: `figure/artwork@type`, `figure/artwork@src`, `figure/artwork@align`, `figure/artwork@alt`.
1163
+ <8> v3: `figure/sourcecode`; v2: `figure/artwork`
1164
+ <9> v2 only: `figure/postamble` (only available in v2)
1165
+
1166
+
1167
+ === ASCII Art and Images
1168
+
1169
+ In RFC XML, `artwork` elements only occur within a
1170
+ `figure` wrapper; this gem supplies that wrapper if it is not provided
1171
+ explicitly.
1172
+
1173
+
1174
+ [source,asciidoc]
1175
+ .Ascii-Art Without Figure Wrapper
1176
+ --
1177
+ [[id]] <1>
1178
+ .Figure2.jpg <2>
1179
+ [align=left|center|right,alt=Ascii Art,type=text/plain] <3>
1180
+ ....
1181
+ ------------------------
1182
+ | Ascii Art |
1183
+ ------------------------ <4>
1184
+ ....
1185
+ --
1186
+ <1> v3 only: `figure/artwork@anchor`; v2: `figure@anchor` (moved into supplied wrapper: anchors not supported on `artwork`)
1187
+ <2> `figure/artwork@name`
1188
+ <3> `figure/artwork@align`, `figure/artwork@alt`; `figure@type` (attribute only available in v2)
1189
+ <4> `figure/artwork`
1190
+
1191
+ [source,asciidoc]
1192
+ .Image Without Figure Wrapper
1193
+ --
1194
+ [[id]] <1>
1195
+ .Figure2.jpg <2>
1196
+ [align=left|center|right,alt=alt_text,type=img/jpeg] <3>
1197
+ image::filename.jpg[alt_text,700,200] <4>
1198
+ --
1199
+ <1> v3 only: `figure/artwork@anchor`; v2: `figure@anchor` (moved into supplied wrapper: anchors not supported on `artwork`)
1200
+ <2> `figure/artwork@name`
1201
+ <3> `figure/artwork@align`, `figure/artwork@alt`; `figure/artwork@type` (only available in v2, intended to be a MIME type; v3: populated as either `svg` or `binary-art` depending on file suffix)
1202
+ <4> `figure/artwork@src`, `figure/artwork@alt`, `figure/artwork@width` (deprecated in v3), `figure/artwork@height` (deprecated in v3)
1203
+
1204
+
1205
+ [source,asciidoc]
1206
+ .With Figure Wrapper
1207
+ --
1208
+ [[id]] <1>
1209
+ [align,alt,suppress-title] <2>
1210
+ .Figure 1 <3>
1211
+ ====
1212
+ Preamble text <4>
1213
+
1214
+ [[id]] <5>
1215
+ .Figure2.jpg <8>
1216
+ [align=left|center|right,alt=alt_text,type=text/plain] <6>
1217
+ ....
1218
+ Figures are
1219
+ only permitted to contain listings (sourcecode),
1220
+ images (artwork),
1221
+ or literal (artwork) <7>
1222
+ ....
1223
+ [[id]] <5>
1224
+ .Figure2.jpg <8>
1225
+ [align=left|center|right,alt=alt_text,type=img/jpeg] <9>
1226
+ image::filename.jpg[alt_text,700,200] <10>
1227
+
1228
+ Postamble text <11>
1229
+ ====
1230
+ --
1231
+ <1> `figure@anchor`
1232
+ <2> v2 only: `figure/artwork@align`, `figure/artwork@alt`, `figure@suppress-title` (attributes only available in v2)
1233
+ <3> `figure/name`
1234
+ <4> v2 only: `figure/preamble` (only available in v2)
1235
+ <5> v3: `figure/artwork@anchor`; v2: Not supported: use `figure@anchor`
1236
+ <6> `figure/artwork@align`, `figure/artwork@alt`; `figure@type` (attribute only available in v2)
1237
+ <7> `figure/artwork`
1238
+ <8> `figure/artwork@name`
1239
+ <9> `figure/artwork@align`, `figure/artwork@alt`; `figure/artwork@type` (only available in v2, intended to be a MIME type; v3: populated as either `svg` or `binary-art` depending on file suffix)
1240
+ <10> `figure/artwork@src`, `figure/artwork@alt`, `figure/artwork@width` (deprecated in v3), `figure/artwork@height` (deprecated in v3)
1241
+ <11> v2 only: `figure/postamble` (only available in v2)
1242
+
1243
+ === Mathematical examples
1244
+
1245
+ In order for mathematical formatting to be recognised in Asciidoc, the document attribute `:stem:` needs to be set.
1246
+
1247
+ [source,asciidoc]
1248
+ --
1249
+ :stem:
1250
+
1251
+ [stem]
1252
+ ++++
1253
+ sqrt(4) = 2
1254
+ ++++
1255
+ --
1256
+
1257
+ Mathematical examples are treated identically to literals, and are rendered as `artwork` in both v2 and v3;
1258
+ however their default alignment is set as `center`. As with inline stem expressions, they are treated identically
1259
+ to monospace expressions in the RFC XML output; they are not currently rendered as MathML or any other notation.
1260
+
1261
+ === Unordered and Ordered Lists
1262
+
1263
+ [source,asciidoc]
1264
+ --
1265
+ [[id]] <1>
1266
+ [empty=true,spacing=normal|compact,hang-indent=n] <2>
1267
+ * Unordered list 1 <3>
1268
+ * Unordered list 2 <3>
1269
+ ** Nested list <4>
1270
+
1271
+ [[id]] <5>
1272
+ [spacing=compact,empty=true,start=n,group=n,counter=token,hang-indent=n,format=List #%d,arabic|loweralpha|upperralpha|lowerroman|upperroman] <6>
1273
+ . A <7>
1274
+ . B <7>
1275
+ --
1276
+ <1> v3: `ul@anchor`; attribute only available in v3
1277
+ <2> v3: `ul@empty`, `ul@spacing` (`hangIndent` not available); v2: `ul@style = empty`, `ul@hangIndent` (`spacing` not available)
1278
+ <3> v2: `list[@style="symbols"]/t`; v3: ul/li
1279
+ <4> v2: `list[@style="symbols"]/t/list[@style="symbols"]/t`; v3: `ul/li/ul/li`
1280
+ <5> v3: `ol@anchor`; attribute only available in v3
1281
+ <6> v2: `list/counter`, `list@hangIndent`, `list@style = format List #%d`, `list@style` (for arabic|loweralpha|upperralpha|lowerroman|upperroman) (`spacing`, `start`, `empty` and `group` not available) v3: `ol@spacing`, `ol@empty`, `ol@start`, `ol@group`, `ol@type = "#%d", `ol@type` (for arabic|loweralpha|upperralpha|lowerroman|upperroman) (`counter`, `hangIndent` not available)
1282
+ <7> v2: `list/t`; v3: `ol/li`
1283
+
1284
+ NOTE: Asciidoctor does not permit anchors on list items: the anchors in the following are ignored.
1285
+
1286
+ [source,asciidoc]
1287
+ --
1288
+ * [[id1]] A
1289
+
1290
+ . [[id2]] A
1291
+ --
1292
+
1293
+ NOTE: RFC XML v2 does not support multiparagraph list items. Following the specification recommendation,
1294
+ paragraphs within v2 list items are replaced with `vspace` tages.
1295
+
1296
+ === Definition Lists
1297
+
1298
+ [source,asciidoc]
1299
+ --
1300
+ [[id]] <1>
1301
+ [horizontal,compact,hang-indent=n] <2>
1302
+ A:: B <3>
1303
+ --
1304
+ <1> v3 only: `dl@anchor` (attribute only available in v3)
1305
+ <2> v3 only: `dl@hanging`, `dl@spacing` (attributes only available in v3); v2 only: `list@hangIndent` (attribute only available in v2). Note that the `compact` and `horizontal` attributes are mutually exclusive in AsciiDoc.
1306
+ <3> v3: `dl/dt`, `dl/dd`; v2: `list[@style="hanging"]/t@hangText`, `list[@style="hanging"]/t`
1307
+
1308
+ NOTE: Asciidoctor does not permit anchors on either definition list terms,
1309
+ or definition list definitions: the anchors in the following are ignored.
1310
+
1311
+ NOTE: In RFC XML v2, `idnits` considers inline definition lists invalid; the gem
1312
+ renders them as paragraphed definition lists. The gem option `:inline-definition-lists`
1313
+ disables this behaviour.
1314
+
1315
+ [source,asciidoc]
1316
+ --
1317
+ [[id1]] A:: [[id2]]B
1318
+ --
1319
+
1320
+ NOTE: RFC XML v2 does not support multiparagraph list items. Following the specification recommendation,
1321
+ paragraphs within v2 list items are replaced with `vspace` tages.
1322
+
1323
+ === Tables
1324
+
1325
+ The converter respects the AsciiDoc (horizontal) align attributes of cells (v2,
1326
+ v3), column widths (v2), and `colspan`, `rowspan` attributes (v3).
1327
+
1328
+ (Exceptionally,
1329
+ column widths specified for v2 as `"1,1,1,1,1,1...."` will be ignored, since Asciidoctor
1330
+ internally treats them identically to unspecified column widths on a table.)
1331
+
1332
+ [source,asciidoc]
1333
+ --
1334
+ [[id]] <1>
1335
+ [suppress-title=true|false,align=left|center|right,grid=all|cols|none|rows] <2>
1336
+ .Table Title <3>
1337
+ |===
1338
+ |[[id]] head | head <4>
1339
+
1340
+ h|header cell | body cell <5>
1341
+ | | [[id]] body cell <6>
1342
+
1343
+ |foot | foot <7>
1344
+ |===
1345
+ --
1346
+ <1> v3: `table@anchor`; v2: `texttable@anchor`
1347
+ <2> v2: `texttable@suppress-title`, `texttable@align`, `texttable@style` (attributes only available in v2). Mapping of Asciidoc grid attribute to RFC XML style attribute is: `all` > `all`, `cols` > `full`, `none` > `none`, `rows` > `headers` (although the two are not strictly equivalent).
1348
+ <3> v3: `table/name`; v2: `texttable@title`
1349
+ <4> v3: `table/thead/tr/td`; v2: `texttable/ttcol@id` (attribute only available in v2), `texttable/ttcol`
1350
+ <5> v3: `table/tbody/tr/th`, `table/tbody/tr/td`; v2: `texttable/c`, `texttable/c`
1351
+ <6> v3: `table/tbody/tr/td@anchor` (attribute only available in v3)
1352
+ <7> v3: `table/tfoot/tr/td`; v2: `texttable/c`
1353
+
1354
+ NOTE: v3 permits table cells to contain block elements, such as paragraphs and lists. (This is done in Asciidoc by prefixing
1355
+ the table cell with `a|`.) However v2 only permits inline tagging, and any block tags are ignored.
1356
+
1357
+ === Sidebar (v3 only)
1358
+
1359
+ [source,asciidoc]
1360
+ --
1361
+ [[id]] <1>
1362
+ ****
1363
+ Sidebar <2>
1364
+ ****
1365
+ --
1366
+ <1> `aside@anchor`
1367
+ <2> `<aside>Sidebar</aside>`
1368
+
1369
+
1370
+ === References: Embedded in Document
1371
+
1372
+ References are expected to be provided in raw RFC XML v2 format. For v3, a list of crossreferences may
1373
+ precede the block of references, with alternative text. This will not be rendered, but it will be used
1374
+ to populate `displayreference` elements, mapping the reference anchors to display text. For example,
1375
+ a list entry `[[[ref1,alt1]]]` means that any instances of the anchor `ref1` should be displayed as `alt1`,
1376
+ and is rendered as `<displayreference target="ref1" to="alt1"/>`.
1377
+
1378
+ RFC requires two separate bibliographies, one for normative and one for informative references;
1379
+ either can be omitted. All bibliography sections in the must be styled with the prefix `[bibliography]`,
1380
+ and must appear in sequence, before any appendices.
1381
+
1382
+ By default, the references cited must be included as raw RFC XML, and separated
1383
+ into the normative and informative sections.
1384
+
1385
+ [source,asciidoc]
1386
+ --
1387
+ [[id]] <1>
1388
+ [bibliography]
1389
+ == Normative References
1390
+ * [[[ref1,alt1]]] <2>
1391
+ ++++
1392
+ (raw XML) <3>
1393
+ ++++
1394
+
1395
+ [[id]] <1>
1396
+ [bibliography]
1397
+ == Informative References
1398
+ ++++
1399
+ (raw XML) <2>
1400
+ ++++
1401
+ --
1402
+ <1> `back/references@anchor` (only in v3)
1403
+ <2> `back/displayreference@target`, `back/displayreference@to` (only in v3)
1404
+ <3> `back/references/reference`
1405
+
1406
+ In postprocessing, bibliographic entries available from http://xml.resource.org/public/rfc are replaced
1407
+ with external references to that entry, using XML entities in RFC XML v2, and XML includes
1408
+ in RFC XML v3. Do not insert your own entities or XML includes into the references; the gem will have difficulty
1409
+ processing them.
1410
+
1411
+ [[external-directory-refs]]
1412
+ === References: External Directory
1413
+
1414
+ As an alternative, the document attribute `:biblio-dir:` can nominate a directory in which separate XML files can be placed, one for each reference to be included. (RFC XML v3 referencegroup elements will also be recognised as files.) The gem will read in from that directory only the files that have actually been cited, and insert them into the appropriate bibliography, without the references needing to be given under the bibliographies as above. (In fact, any XML already provided will be deleted.) By default, references will be considered informative; the document attribute `:normative:` can be used to specify a comma-delimited list of normative references.
1415
+
1416
+ The gem will issue a warning if any cited reference is not included in the directory. However, external references do not have to be included in the directory: they will be recognised by comparing their anchors against the external bibliography cache, and referenced as entities or includes. However, particular drafts of Internet-Draft documents do still need to be included as separate documents (see <<external-ref-lookup>>.)
1417
+
1418
+ For example:
1419
+
1420
+ [source,asciidoc]
1421
+ --
1422
+ = The Holy Hand Grenade of Antioch
1423
+ Arthur Pendragon
1424
+ :doctype: internet-draft
1425
+ :workgroup: silly
1426
+ :biblio-dir: refs <1>
1427
+ :normative: RFC2119, AsciiDoc <1>
1428
+
1429
+ [[xyz]]
1430
+ == Hello
1431
+ Hello
1432
+
1433
+ * a <<RFC2119,2.3 of: See internet draft subsection>> <3>
1434
+ * b <<I-D.abarth-cake>>
1435
+ * b2 <<I-D.abarth-cake,what>>
1436
+ * b1 <<I-D.abarth-cake,2.3 of: See internet draft subsection>> <3>
1437
+ * c <<xyz,format=counter: xyzzy>> <4>
1438
+ * d <<biblio>> <4>
1439
+ * e <<AsciiDoc,AsciiDoctor>>
1440
+ * f <<mathrefs>>
1441
+
1442
+
1443
+ [[biblio]]
1444
+ === Biblio
1445
+ See biblio
1446
+
1447
+ [bibliography]
1448
+ == Normative References <5>
1449
+
1450
+ [bibliography]
1451
+ == Informative References <6>
1452
+ --
1453
+ <1> The RFC XML references are included in the directory `./refs`, with one file per reference. For example, we would expect it to contain a file corresponding to the reference `mathrefs`. A file corresponding to `RFC2119` is optional, and in fact will be ignored, since the anchor is recognised as an external reference. A file corresponding to `I-D.abarth-cake` will not be ignored, if that file contains a `seriesInfo` element nominating a specific draft version.
1454
+ <2> The references in the `./refs` directory are by default considered informative; this attribute indicates that `RFC2119` and `AsciiDoc` are to be considered normative.
1455
+ <3> References are recognised in `relref` as well as `xref` elements.
1456
+ <4> The gem differentiates between bibliographic references and crossreferences to other anchors within the document.
1457
+ <5> The bibliographic headers need to be provided as above, and its titles are expected to be "Normative References" and "Informative References"; the gem will look for those titles specifically in order to insert the references it identifies from the file. However, no XML content is expected to be provided under each heading, and any XML content that is provided will be ignored.
1458
+
1459
+
1460
+ === Appendices
1461
+
1462
+ [source,asciidoc]
1463
+ --
1464
+ [[id]] <1>
1465
+ [appendix]
1466
+ == Appendix 1 <2>
1467
+ Content <3>
1468
+ --
1469
+ <1> `back/section@anchor`
1470
+ <2> v3: `back/section/name`; v2: `back/section@title`
1471
+ <3> `back/section/t`
1472
+
1473
+
1474
+
1475
+
1476
+ === Unsupported RFC XML Elements
1477
+
1478
+ The following **RFC XML v3/v2** elements are not (yet) supported through
1479
+ asciidoctor commands:
1480
+
1481
+ |===
1482
+ | RFC XML element | RFC XML v3 | RFC XML v2
1483
+
1484
+ | `front/boilerplate` | Not added | N/A
1485
+ | `iref@primary` | N | N
1486
+ | `reference` (and all children) 2+| Supported only as pass-through or through asciidoc-bibliography gem
1487
+ | `table/preamble` | Deprecated | N
1488
+ | `table/postamble` | Deprecated | N
1489
+ | `artwork@width` | Only on images | Only on images
1490
+ | `artwork@height` | Only on images | Only on images
1491
+ |===
1492
+
1493
+ === Unsupported Asciidoctor Features
1494
+
1495
+ These asciidoctor features are not supported in output of these formats:
1496
+
1497
+ |===
1498
+ | asciidoctor feature | RFC XML v2 | RFC XML v3
1499
+
1500
+ | http://asciidoctor.org/docs/user-manual/#quote[Quote] | Rendered as normal paragraph | Supported
1501
+ | http://asciidoctor.org/docs/user-manual/#quote[Quote]: Non-URL Citations 2+| Ignored
1502
+ | http://asciidoctor.org/docs/user-manual/#verse[Verse] | Rendered as normal paragraph | Rendered as Quote
1503
+ | http://asciidoctor.org/docs/user-manual/#sidebar[Sidebar] | Rendered as normal paragraph | Supported
1504
+ | http://asciidoctor.org/docs/user-manual/#index-terms[Index Term]: Tertiary 2+| Ignored
1505
+ | List: http://asciidoctor.org/docs/user-manual/#numbering-styles[Ordered List numbering] `decimal`, `lowergreek` 2+| Treated as `arabic`
1506
+ | http://asciidoctor.org/docs/user-manual/#callouts[Callouts] 2+| Ignored
1507
+ | http://asciidoctor.org/docs/user-manual/#admonition[Adminitions: formatting] | Ignored | Supported
1508
+ | Formatting: http://asciidoctor.org/docs/user-manual/#discrete-headings[Floating Title] 2+| Rendered as strong paragraph
1509
+ | Formatting: http://asciidoctor.org/docs/user-manual/#page-break[Page Break] 2+| Ignored
1510
+ | Formatting: http://asciidoctor.org/docs/user-manual/#horizontal-rules[Horizontal Rule] 2+| Ignored
1511
+ | Formatting: http://asciidoctor.org/docs/user-manual/#line-breaks[Line breaks] | Supported | Only supported within table cells
1512
+ | Media: http://asciidoctor.org/docs/user-manual/#audio[Audio] 2+| Ignored
1513
+ | Media: http://asciidoctor.org/docs/user-manual/#video[Video] 2+| Ignored
1514
+ | Media: http://asciidoctor.org/docs/user-manual/#images[Inline images] 2+| Ignored
1515
+ | Macro: http://asciidoctor.org/docs/user-manual/#keyboard-shortcuts[Keyboard shortcuts] 2+| Ignored
1516
+ | Macro: http://asciidoctor.org/docs/user-manual/#menu-selections[Menu selections] 2+| Ignored
1517
+ | Macro: http://asciidoctor.org/docs/user-manual/#ui-buttons[UI buttons] 2+| Ignored
1518
+ | Table: http://asciidoctor.org/docs/user-manual/#footer-row[Distinction between table body and table footer] | No | Supported
1519
+ | Table: http://asciidoctor.org/docs/user-manual/#header-row[Multiple table header rows] | No | Supported
1520
+ | Table: http://asciidoctor.org/docs/user-manual/#table-borders[Table borders: grid = rows] | Rendered as `headers` | Ignored
1521
+ | Table: http://asciidoctor.org/docs/user-manual/#table-borders[Table borders: grid = cols\|none] | Supported | Ignored
1522
+ | Table: http://asciidoctor.org/docs/user-manual/#table-borders[Table borders: frame] 2+| Ignored
1523
+ | Table: http://asciidoctor.org/docs/user-manual/#cell[Table cells: rowspan] | Ignored | Supported
1524
+ | Table: http://asciidoctor.org/docs/user-manual/#cell[Table cells: colspan] | Ignored | Supported
1525
+ | Table: http://asciidoctor.org/docs/user-manual/#cell[Table cells: Asciidoctor formatting (blocks within cells)] | Ignored | Supported
1526
+ | Table: http://asciidoctor.org/docs/user-manual/#cols-format[Table columns: width] | Supported | Ignored
1527
+ |===
1528
+
1529
+ [[external-ref-lookup]]
1530
+ == Lookup of external references
1531
+
1532
+ In order to speed the lookup of references on the http://xml.resource.org/public/rfc website for external
1533
+ references, a cache of references is built the first time the gem is run, in the user's home directory:
1534
+ `~/.asciidoc-rfc-biblio-cache.json`. This maps all the canonical anchors for external references as defined
1535
+ by the IETF, such as `RFC2119` or `CCITT.E163.1988`, to the URLs that their RFC reference is stored on.
1536
+ References are detected for replacement in the Asciidoc document by matching the `references@anchor`
1537
+ attribute to one of those canonical anchors; the content of the local RFC XML reference is not checked.
1538
+
1539
+ (For rebuilding the cache, see <<caches>>.)
1540
+
1541
+ Rather than hand crafting RFC XML references for RFC documents, or other references hosted at `http://xml.resource.org/public/rfc/`,
1542
+ you need only create a dummy `<reference>` element containing the IETF-defined anchor for that citation. In postprocessing, any
1543
+ references that are hosted at xml.resource.org will be identified by their anchor, and replaced by entities or XML includes,
1544
+ for RFC XML v2 and v3 respectively. (The complete list of authoritative
1545
+ RFC XML bibliographies is available from https://xml2rfc.tools.ietf.org , online and in zipped form.)
1546
+
1547
+ Because the content of any externally defined `<reference>` element is overwritten with an entity or include,
1548
+ you do not need to provide a full reference. You can supply a minimal reference like `<reference anchor="RFC2119"/>`,
1549
+ but note that such a reference is invalid in the RFC XML schema, and the gem will report a missing element during processing.
1550
+ (The document will still be processed successfully.) To prevent any validation error reports, the minimal syntactically valid reference is:
1551
+
1552
+ [source,xml]
1553
+ --
1554
+ <reference anchor="RFC2119">
1555
+ <front>
1556
+ <title/>
1557
+ <author/>
1558
+ <date/>
1559
+ </front>
1560
+ </reference>
1561
+ --
1562
+
1563
+ If you wish to cite a specific version of an Internet-Draft, you will need to include the `seriesInfo` element
1564
+ in the reference that identifies the specific version; the anchor is the same for all internet drafts. For example:
1565
+
1566
+ [source,xml]
1567
+ --
1568
+ <reference anchor="I-D.abarth-cake">
1569
+ <front>
1570
+ <title/>
1571
+ <author/>
1572
+ <date/>
1573
+ </front>
1574
+ <seriesInfo name="Internet-Draft" value="draft-abarth-cake-00"/>
1575
+ </reference>
1576
+ --
1577
+
1578
+ As discussed under <<external-directory-refs>>, 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.)
1579
+
1580
+
1581
+ == Examples
1582
+
1583
+ === RFC XML v3 Example
1584
+
1585
+ ifdef::env-github[]
1586
+ include::spec/examples/example-v3.adoc[]
1587
+ endif::[]
1588
+ ifndef::env-github[]
1589
+ [source,asciidoc]
1590
+ ----
1591
+ include::spec/examples/example-v3.adoc[]
1592
+ ----
1593
+ endif::[]
1594
+
1595
+ === RFC XML v2 Example
1596
+
1597
+ ifdef::env-github[]
1598
+ include::spec/examples/example-v2.adoc[]
1599
+ endif::[]
1600
+ ifndef::env-github[]
1601
+ [source,asciidoc]
1602
+ ----
1603
+ include::spec/examples/example-v2.adoc[]
1604
+ ----
1605
+ endif::[]
1606
+
1607
+
1608
+ == Development
1609
+
1610
+ We follow Sandi Metz's Rules for this gem, you can read the
1611
+ http://robots.thoughtbot.com/post/50655960596/sandi-metz-rules-for-developers[description of the rules here].
1612
+
1613
+ All new code should follow these
1614
+ rules. If you make changes in a pre-existing file that violates these rules you
1615
+ should fix the violations as part of your contribution.
1616
+
1617
+ === Setup
1618
+
1619
+ Clone the repository.
1620
+
1621
+ [source,sh]
1622
+ ----
1623
+ git clone https://github.com/riboseinc/metanorma-ietf
1624
+ ----
1625
+
1626
+ Setup your environment.
1627
+
1628
+ [source,sh]
1629
+ ----
1630
+ bin/setup
1631
+ ----
1632
+
1633
+ Run the test suite
1634
+
1635
+ [source,sh]
1636
+ ----
1637
+ bin/rspec
1638
+ ----
1639
+
1640
+ == Contributing
1641
+
1642
+ First, thank you for contributing! We love pull requests from everyone. By
1643
+ participating in this project, you hereby grant https://www.ribose.com[Ribose Inc.] the
1644
+ right to grant or transfer an unlimited number of non exclusive licenses or
1645
+ sub-licenses to third parties, under the copyright covering the contribution
1646
+ to use the contribution by all means.
1647
+
1648
+ Here are a few technical guidelines to follow:
1649
+
1650
+ . Open an https://github.com/riboseinc/metanorma-ietf/issues[issue] to discuss a new feature.
1651
+ . Write tests to support your new feature.
1652
+ . Make sure the entire test suite passes locally and on CI.
1653
+ . Open a Pull Request.
1654
+ . https://github.com/thoughtbot/guides/tree/master/protocol/git#write-a-feature[Squash your commits] after receiving feedback.
1655
+ . Party!
1656
+
1657
+
1658
+ == Credits
1659
+
1660
+ This gem is developed, maintained and funded by https://www.ribose.com[Ribose Inc.]