asciidoctor-rfc 0.9.0 → 0.9.1

Sign up to get free protection for your applications and to get access to all the features.
@@ -0,0 +1,2298 @@
1
+
2
+
3
+
4
+
5
+
6
+
7
+ Internet Architecture Board (IAB) J. Hildebrand, Ed.
8
+ Request for Comments: 7992 P. Hoffman
9
+ Category: Informational December 2016
10
+ ISSN: 2070-1721
11
+
12
+
13
+ HTML Format for RFCs
14
+
15
+ Abstract
16
+
17
+ In order to meet the evolving needs of the Internet community, the
18
+ canonical format for RFCs is changing from a plain-text, ASCII-only
19
+ format to an XML format that will, in turn, be rendered into several
20
+ publication formats. This document defines the HTML format that will
21
+ be rendered for an RFC or Internet-Draft.
22
+
23
+ Status of This Memo
24
+
25
+ This document is not an Internet Standards Track specification; it is
26
+ published for informational purposes.
27
+
28
+ This document is a product of the Internet Architecture Board (IAB)
29
+ and represents information that the IAB has deemed valuable to
30
+ provide for permanent record. It represents the consensus of the
31
+ Internet Architecture Board (IAB). Documents approved for
32
+ publication by the IAB are not a candidate for any level of Internet
33
+ Standard; see Section 2 of RFC 7841.
34
+
35
+ Information about the current status of this document, any errata,
36
+ and how to provide feedback on it may be obtained at
37
+ http://www.rfc-editor.org/info/rfc7992.
38
+
39
+ Copyright Notice
40
+
41
+ Copyright (c) 2016 IETF Trust and the persons identified as the
42
+ document authors. All rights reserved.
43
+
44
+ This document is subject to BCP 78 and the IETF Trust's Legal
45
+ Provisions Relating to IETF Documents
46
+ (http://trustee.ietf.org/license-info) in effect on the date of
47
+ publication of this document. Please review these documents
48
+ carefully, as they describe your rights and restrictions with respect
49
+ to this document.
50
+
51
+
52
+
53
+
54
+
55
+
56
+
57
+
58
+ Hildebrand & Hoffman Informational [Page 1]
59
+
60
+ RFC 7992 HTML for RFCs December 2016
61
+
62
+
63
+ Table of Contents
64
+
65
+ 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4
66
+ 2. Requirements for the HTML Format . . . . . . . . . . . . . . 5
67
+ 2.1. Requirements for Accessibility . . . . . . . . . . . . . 6
68
+ 3. HTML Version . . . . . . . . . . . . . . . . . . . . . . . . 7
69
+ 4. HTML Syntax . . . . . . . . . . . . . . . . . . . . . . . . . 7
70
+ 5. Common Items . . . . . . . . . . . . . . . . . . . . . . . . 8
71
+ 5.1. IDs . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
72
+ 5.2. Pilcrows . . . . . . . . . . . . . . . . . . . . . . . . 8
73
+ 6. Front Matter . . . . . . . . . . . . . . . . . . . . . . . . 9
74
+ 6.1. DOCTYPE . . . . . . . . . . . . . . . . . . . . . . . . . 9
75
+ 6.2. Root Element . . . . . . . . . . . . . . . . . . . . . . 9
76
+ 6.3. <head> Element . . . . . . . . . . . . . . . . . . . . . 9
77
+ 6.3.1. Charset Declaration . . . . . . . . . . . . . . . . . 9
78
+ 6.3.2. Document Title . . . . . . . . . . . . . . . . . . . 10
79
+ 6.3.3. Document Metadata . . . . . . . . . . . . . . . . . . 10
80
+ 6.3.4. Link to XML Source . . . . . . . . . . . . . . . . . 10
81
+ 6.3.5. Link to License . . . . . . . . . . . . . . . . . . . 10
82
+ 6.3.6. Style . . . . . . . . . . . . . . . . . . . . . . . . 11
83
+ 6.3.7. Links . . . . . . . . . . . . . . . . . . . . . . . . 11
84
+ 6.4. Page Headers and Footers . . . . . . . . . . . . . . . . 11
85
+ 6.5. Document Information . . . . . . . . . . . . . . . . . . 12
86
+ 6.6. Table of Contents . . . . . . . . . . . . . . . . . . . . 13
87
+ 7. Main Body . . . . . . . . . . . . . . . . . . . . . . . . . . 14
88
+ 8. Back Matter . . . . . . . . . . . . . . . . . . . . . . . . . 14
89
+ 8.1. Index . . . . . . . . . . . . . . . . . . . . . . . . . . 14
90
+ 8.1.1. Index Contents . . . . . . . . . . . . . . . . . . . 14
91
+ 8.1.2. Index Letters . . . . . . . . . . . . . . . . . . . . 15
92
+ 8.1.3. Index Items . . . . . . . . . . . . . . . . . . . . . 15
93
+ 8.1.4. Index Subitems . . . . . . . . . . . . . . . . . . . 16
94
+ 8.2. Authors' Addresses Section . . . . . . . . . . . . . . . 16
95
+ 8.3. Document Information . . . . . . . . . . . . . . . . . . 17
96
+ 9. Elements . . . . . . . . . . . . . . . . . . . . . . . . . . 17
97
+ 9.1. <abstract> . . . . . . . . . . . . . . . . . . . . . . . 17
98
+ 9.2. <address> . . . . . . . . . . . . . . . . . . . . . . . . 17
99
+ 9.3. <annotation> . . . . . . . . . . . . . . . . . . . . . . 18
100
+ 9.4. <area> . . . . . . . . . . . . . . . . . . . . . . . . . 18
101
+ 9.5. <artwork> . . . . . . . . . . . . . . . . . . . . . . . . 18
102
+ 9.5.1. Text Artwork . . . . . . . . . . . . . . . . . . . . 19
103
+ 9.5.2. SVG Artwork . . . . . . . . . . . . . . . . . . . . . 19
104
+ 9.5.3. Other Artwork . . . . . . . . . . . . . . . . . . . . 20
105
+ 9.6. <aside> . . . . . . . . . . . . . . . . . . . . . . . . . 20
106
+ 9.7. <author> . . . . . . . . . . . . . . . . . . . . . . . . 20
107
+ 9.7.1. Authors in Document Information . . . . . . . . . . . 21
108
+ 9.7.2. Authors of This Document . . . . . . . . . . . . . . 21
109
+ 9.7.3. Authors of References . . . . . . . . . . . . . . . . 23
110
+ 9.8. <back> . . . . . . . . . . . . . . . . . . . . . . . . . 23
111
+
112
+
113
+
114
+ Hildebrand & Hoffman Informational [Page 2]
115
+
116
+ RFC 7992 HTML for RFCs December 2016
117
+
118
+
119
+ 9.9. <bcp14> . . . . . . . . . . . . . . . . . . . . . . . . . 24
120
+ 9.10. <blockquote> . . . . . . . . . . . . . . . . . . . . . . 24
121
+ 9.11. <boilerplate> . . . . . . . . . . . . . . . . . . . . . . 24
122
+ 9.12. <br> . . . . . . . . . . . . . . . . . . . . . . . . . . 25
123
+ 9.13. <city> . . . . . . . . . . . . . . . . . . . . . . . . . 25
124
+ 9.14. <code> . . . . . . . . . . . . . . . . . . . . . . . . . 25
125
+ 9.15. <country> . . . . . . . . . . . . . . . . . . . . . . . . 25
126
+ 9.16. <cref> . . . . . . . . . . . . . . . . . . . . . . . . . 25
127
+ 9.17. <date> . . . . . . . . . . . . . . . . . . . . . . . . . 26
128
+ 9.18. <dd> . . . . . . . . . . . . . . . . . . . . . . . . . . 26
129
+ 9.19. <displayreference> . . . . . . . . . . . . . . . . . . . 26
130
+ 9.20. <dl> . . . . . . . . . . . . . . . . . . . . . . . . . . 26
131
+ 9.21. <dt> . . . . . . . . . . . . . . . . . . . . . . . . . . 26
132
+ 9.22. <em> . . . . . . . . . . . . . . . . . . . . . . . . . . 26
133
+ 9.23. <email> . . . . . . . . . . . . . . . . . . . . . . . . . 26
134
+ 9.24. <eref> . . . . . . . . . . . . . . . . . . . . . . . . . 27
135
+ 9.25. <figure> . . . . . . . . . . . . . . . . . . . . . . . . 27
136
+ 9.26. <front> . . . . . . . . . . . . . . . . . . . . . . . . . 27
137
+ 9.27. <iref> . . . . . . . . . . . . . . . . . . . . . . . . . 27
138
+ 9.28. <keyword> . . . . . . . . . . . . . . . . . . . . . . . . 27
139
+ 9.29. <li> . . . . . . . . . . . . . . . . . . . . . . . . . . 28
140
+ 9.30. <link> . . . . . . . . . . . . . . . . . . . . . . . . . 28
141
+ 9.31. <middle> . . . . . . . . . . . . . . . . . . . . . . . . 28
142
+ 9.32. <name> . . . . . . . . . . . . . . . . . . . . . . . . . 28
143
+ 9.33. <note> . . . . . . . . . . . . . . . . . . . . . . . . . 28
144
+ 9.34. <ol> . . . . . . . . . . . . . . . . . . . . . . . . . . 28
145
+ 9.34.1. Percent Styles . . . . . . . . . . . . . . . . . . . 29
146
+ 9.34.2. Standard Styles . . . . . . . . . . . . . . . . . . 29
147
+ 9.35. <organization> . . . . . . . . . . . . . . . . . . . . . 29
148
+ 9.36. <phone> . . . . . . . . . . . . . . . . . . . . . . . . . 29
149
+ 9.37. <postal> . . . . . . . . . . . . . . . . . . . . . . . . 30
150
+ 9.38. <postalLine> . . . . . . . . . . . . . . . . . . . . . . 30
151
+ 9.39. <refcontent> . . . . . . . . . . . . . . . . . . . . . . 31
152
+ 9.40. <reference> . . . . . . . . . . . . . . . . . . . . . . . 31
153
+ 9.41. <referencegroup> . . . . . . . . . . . . . . . . . . . . 32
154
+ 9.42. <references> . . . . . . . . . . . . . . . . . . . . . . 32
155
+ 9.43. <region> . . . . . . . . . . . . . . . . . . . . . . . . 33
156
+ 9.44. <relref> . . . . . . . . . . . . . . . . . . . . . . . . 33
157
+ 9.44.1. displayFormat='of' . . . . . . . . . . . . . . . . . 33
158
+ 9.44.2. displayFormat='comma' . . . . . . . . . . . . . . . 34
159
+ 9.44.3. displayFormat='parens' . . . . . . . . . . . . . . . 34
160
+ 9.44.4. displayFormat='bare' . . . . . . . . . . . . . . . . 35
161
+ 9.45. <rfc> . . . . . . . . . . . . . . . . . . . . . . . . . . 35
162
+ 9.46. <section> . . . . . . . . . . . . . . . . . . . . . . . . 35
163
+ 9.47. <seriesInfo> . . . . . . . . . . . . . . . . . . . . . . 36
164
+ 9.48. <sourcecode> . . . . . . . . . . . . . . . . . . . . . . 36
165
+ 9.49. <street> . . . . . . . . . . . . . . . . . . . . . . . . 36
166
+ 9.50. <strong> . . . . . . . . . . . . . . . . . . . . . . . . 36
167
+
168
+
169
+
170
+ Hildebrand & Hoffman Informational [Page 3]
171
+
172
+ RFC 7992 HTML for RFCs December 2016
173
+
174
+
175
+ 9.51. <sub> . . . . . . . . . . . . . . . . . . . . . . . . . . 36
176
+ 9.52. <sup> . . . . . . . . . . . . . . . . . . . . . . . . . . 36
177
+ 9.53. <t> . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
178
+ 9.54. <table> . . . . . . . . . . . . . . . . . . . . . . . . . 37
179
+ 9.55. <tbody> . . . . . . . . . . . . . . . . . . . . . . . . . 37
180
+ 9.56. <td> . . . . . . . . . . . . . . . . . . . . . . . . . . 37
181
+ 9.57. <tfoot> . . . . . . . . . . . . . . . . . . . . . . . . . 37
182
+ 9.58. <th> . . . . . . . . . . . . . . . . . . . . . . . . . . 37
183
+ 9.59. <thead> . . . . . . . . . . . . . . . . . . . . . . . . . 37
184
+ 9.60. <title> . . . . . . . . . . . . . . . . . . . . . . . . . 37
185
+ 9.61. <tr> . . . . . . . . . . . . . . . . . . . . . . . . . . 38
186
+ 9.62. <tt> . . . . . . . . . . . . . . . . . . . . . . . . . . 38
187
+ 9.63. <ul> . . . . . . . . . . . . . . . . . . . . . . . . . . 38
188
+ 9.64. <uri> . . . . . . . . . . . . . . . . . . . . . . . . . . 38
189
+ 9.65. <workgroup> . . . . . . . . . . . . . . . . . . . . . . . 38
190
+ 9.66. <xref> . . . . . . . . . . . . . . . . . . . . . . . . . 38
191
+ 9.67. <svg xmlns='http://www.w3.org/2000/svg'> . . . . . . . . 39
192
+ 10. Security Considerations . . . . . . . . . . . . . . . . . . . 39
193
+ 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 39
194
+ 11.1. Normative References . . . . . . . . . . . . . . . . . . 39
195
+ 11.2. Informative References . . . . . . . . . . . . . . . . . 40
196
+ Appendix A. IAB Members at the Time of Approval . . . . . . . . 40
197
+ Appendix B. Acknowledgments . . . . . . . . . . . . . . . . . . 41
198
+ Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 41
199
+
200
+ 1. Introduction
201
+
202
+ As described in [RFC7990], the RFC Series is changing. One of those
203
+ changes includes the RFC Editor publishing a non-canonical HTML
204
+ version of RFCs.
205
+
206
+ This document describes the HTML format that will be used as one of
207
+ the publication formats for the RFC Series. It defines a strict
208
+ subset of HTML appropriate for RFC Series documents. The visual
209
+ layout of the document will be defined through a cascading style
210
+ sheet (CSS) [W3C.REC-CSS2-20110607]. The CSS will be included in the
211
+ HTML file but will be described in [RFC7993].
212
+
213
+ The details (particularly any vocabularies) described in this
214
+ document are expected to change based on experience gained in
215
+ implementing the the new publication toolsets. Revised documents
216
+ will be published capturing those changes as the toolsets are
217
+ completed. Other implementers must not expect those changes to
218
+ remain backwards compatible with the details described in this
219
+ document.
220
+
221
+
222
+
223
+
224
+
225
+
226
+ Hildebrand & Hoffman Informational [Page 4]
227
+
228
+ RFC 7992 HTML for RFCs December 2016
229
+
230
+
231
+ 2. Requirements for the HTML Format
232
+
233
+ This section lists the design requirements used to create the HTML
234
+ format described in this document. These requirements build on those
235
+ found in [RFC6949]. Many of these requirements are naturally
236
+ fulfilled by using the output of the preparation tool [RFC7998].
237
+
238
+ o The HTML has to render correctly on a list of browser versions
239
+ that the RFC Editor will keep up to date outside of this document.
240
+
241
+ o The format will consist of a subset of HTML deemed to be widely
242
+ implemented by common browsers at the time the specification is
243
+ created, likely to continue to be widely implemented, and unlikely
244
+ to cause security issues. This will maximize the chances that
245
+ future HTML renderers (such as new web browsers) will continue to
246
+ produce readable text from the HTML format without the format
247
+ needing to be changed frequently.
248
+
249
+ o These requirements are expected to change in the future to reflect
250
+ the expectation that HTML rendering will be required for current
251
+ versions of browsers and platforms, while ideally continuing to
252
+ render correctly on recent versions of those browsers.
253
+
254
+ o The HTML documents from the RFC Editor or Internet-Drafts
255
+ directory may be re-rendered from the canonical XML format in the
256
+ future to ensure the ongoing readability of the documents. The
257
+ intent is that any re-rendering would be due to exceptional
258
+ circumstances rather than for minor annoyances.
259
+
260
+ o The HTML must display adequately in at least one text-based
261
+ browser. Some consumers of the RFC Series can only access the
262
+ documents on text-based terminals.
263
+
264
+ o The HTML document will be self-contained, without requiring
265
+ external files for images, CSS, JavaScript, or the like. This
266
+ will allow the HTML file to be moved over various non-HTTP
267
+ transports (such as email, FTP, and rsync) without breakage.
268
+
269
+ o JavaScript will be supported on a limited basis. It will not be
270
+ permitted to overwrite or change any text present in the rendered
271
+ HTML. It may, on a limited basis, add additional text that
272
+ provides post-publication metadata or pointers if warranted. All
273
+ such text will be clearly marked as additional.
274
+
275
+ o The HTML document will allow easy local override of the default
276
+ CSS formatting. This will allow users who have a different visual
277
+ style that they prefer to make RFCs display with that style
278
+ without having to alter the contents of the HTML document. This
279
+
280
+
281
+
282
+ Hildebrand & Hoffman Informational [Page 5]
283
+
284
+ RFC 7992 HTML for RFCs December 2016
285
+
286
+
287
+ might also be valuable for allowing people with specific
288
+ accessibility needs to use a customized CSS.
289
+
290
+ o HTML tags in documents will rarely have attributes whose only
291
+ purpose is to affect the rendered styling, and those will only be
292
+ used if it would not be possible to specify that styling in a CSS.
293
+ No such attributes are known at this time.
294
+
295
+ o Both user-defined and auto-generated anchors must be supported and
296
+ linkable, with user-defined anchors appearing in an "id"
297
+ attribute. Auto-generated anchors will be generated for every
298
+ heading, paragraph, and so on, not just those that do not have
299
+ user-defined anchors. User-defined anchors may, and auto-
300
+ generated anchors will, appear next to paragraphs, figures,
301
+ tables, blockquotes, and section titles.
302
+
303
+ o All sections, subsections, figures, and paragraphs should have
304
+ stable numbered link anchors. Additionally, anchors expressed in
305
+ the source XML should be exposed as anchors in the HTML output as
306
+ well.
307
+
308
+ o The HTML must make it easy to separate sections along with all of
309
+ their subsections into separate files. This will make creating
310
+ EPUB documents easier in the future.
311
+
312
+ o The HTML produced for Internet-Drafts will differ from that
313
+ produced by the RFC Editor due to differences in the output from
314
+ the prep tool.
315
+
316
+ o The abstract must be marked up or tagged in a way that popular
317
+ search engines will extract it as a summary.
318
+
319
+ 2.1. Requirements for Accessibility
320
+
321
+ o Normative information must be easily accessible to the following
322
+ consumers:
323
+
324
+ * People with impaired vision, including those that use large
325
+ fonts and those that use screen readers
326
+
327
+ * People with difficulty distinguishing between colors
328
+
329
+ * People who use devices with small screens, such as cell phones
330
+
331
+ o Specific instances where goals for accessibility are important in
332
+ the design choices of the format have been called out in the text.
333
+
334
+
335
+
336
+
337
+
338
+ Hildebrand & Hoffman Informational [Page 6]
339
+
340
+ RFC 7992 HTML for RFCs December 2016
341
+
342
+
343
+ o Note: designing for these consumers does not preclude the use of
344
+ features they cannot use, but it does require that key semantic
345
+ data not be lost when read using the tools and settings that are
346
+ required by a given constituency.
347
+
348
+ 3. HTML Version
349
+
350
+ The RFC Editor will periodically determine which version of the HTML
351
+ specification will be referenced for tools generating the format
352
+ defined in this document. The starting version will be that defined
353
+ in [W3C.REC-html5-20141028], commonly known as "HTML5". Although the
354
+ HTML specification mandates several of the syntax and structure rules
355
+ described in this document, they are called out here for emphasis.
356
+
357
+ 4. HTML Syntax
358
+
359
+ The processor emitting HTML from the XML source will follow these
360
+ rules:
361
+
362
+ o The HTML output is encoded as UTF-8, as specified in [RFC3629].
363
+
364
+ o The document is valid HTML.
365
+
366
+ o Double quotes (U+0022 QUOTATION MARK: ") are used to quote
367
+ attribute values unless the HTML specification forbids quoting a
368
+ particular attribute.
369
+
370
+ o Each logical line is terminated solely with a \n (U+000A: LINE
371
+ FEED), otherwise known as "Unix-style" line endings.
372
+
373
+ o Code points below (U+0020: SPACE) or character entity references
374
+ that generate them (e.g. &#9;), other than (U+000A: LINE FEED) may
375
+ not be used. Note: this rule explicitly forbids \t (U+0009:
376
+ CHARACTER TABULATION), \f (U+000C: FORM FEED), and \r (U+000D:
377
+ CARRIAGE RETURN) from appearing in the HTML output.
378
+
379
+ o Comments in the source XML, if any, will not be copied into the
380
+ HTML.
381
+
382
+ o The HTML output will be pretty-printed, using whatever consistent
383
+ rules are deemed best by the developers of the HTML production
384
+ tools.
385
+
386
+ Note: none of these rules affect the rendered output of the HTML, but
387
+ they are intended to increase the chance that text comparison tools
388
+ (e.g., "diff") that operate on the HTML output are easier to write.
389
+
390
+
391
+
392
+
393
+
394
+ Hildebrand & Hoffman Informational [Page 7]
395
+
396
+ RFC 7992 HTML for RFCs December 2016
397
+
398
+
399
+ 5. Common Items
400
+
401
+ This section lists items that are common across multiple parts of the
402
+ HTML document.
403
+
404
+ 5.1. IDs
405
+
406
+ HTML elements that are generated from XML elements that include an
407
+ "anchor" attribute will use the value of the "anchor" attribute as
408
+ the value of the "id" attribute of the corresponding HTML element.
409
+ The prep tool produces XML with "anchor" attributes in all elements
410
+ that need them. Some HTML constructs (such as <section>) will use
411
+ multiple instances of these identifiers.
412
+
413
+ 5.2. Pilcrows
414
+
415
+ Each paragraph, artwork, or sourcecode segment outside of a <figure>
416
+ or <table> element will be appended with a space and a "pilcrow"
417
+ (U+00B6: PILCROW SIGN), otherwise known as a "paragraph sign". For
418
+ the purposes of clarity in ASCII renderings of this document, in this
419
+ document pilcrows are rendered as "&para;". The pilcrow will be
420
+ linked to the "id" attribute on the XML entity to which it is
421
+ associated using an <a> element of class "pilcrow". For example:
422
+
423
+ <p id="s-1.1-1">
424
+ Some paragraph text. <a class="pilcrow" href="#s-1.1-1">&para;</a>
425
+ </p>
426
+
427
+ The pilcrow will normally be invisible unless the element it is
428
+ attached to is moused over. The pilcrow will be surrounded by a link
429
+ that points to the element it is attached to.
430
+
431
+ Pilcrows are never included inside a <table> or <figure> element,
432
+ since the figure number or table number serves as an adequate link
433
+ target.
434
+
435
+ Elements that might otherwise contain a pilcrow do not get marked
436
+ with a pilcrow if they contain one or more child elements that are
437
+ marked with a pilcrow. For example:
438
+
439
+ <blockquote id="s-1.2-1">
440
+ <p id="s-1.2-2">Four score and seven years ago our fathers brought
441
+ forth on this continent, a new nation, conceived in Liberty, and
442
+ dedicated to the proposition that all men are created equal.
443
+ <a href="#s-1.2-2" class="pilcrow">&para;</a></p>
444
+ <!-- NO pilcrow here -->
445
+ </blockquote>
446
+
447
+
448
+
449
+
450
+ Hildebrand & Hoffman Informational [Page 8]
451
+
452
+ RFC 7992 HTML for RFCs December 2016
453
+
454
+
455
+ 6. Front Matter
456
+
457
+ The front matter of the HTML format contains processing information,
458
+ metadata of various types, and styling information that applies to
459
+ the document as a whole. This section describes HTML that is not
460
+ necessarily a direct transform from the XML format. For more details
461
+ on each of the tags that generate content in this section, see
462
+ Section 9.
463
+
464
+ 6.1. DOCTYPE
465
+
466
+ The DOCTYPE of the document is "html", which declares that the
467
+ document is compliant with HTML5. The document will start with
468
+ exactly this string:
469
+
470
+ <!DOCTYPE html>
471
+
472
+ 6.2. Root Element
473
+
474
+ The root element of the document is <html>. This element includes a
475
+ "lang" attribute, whose value is a language tag, as discussed in
476
+ [RFC5646], that describes the natural language of the document. The
477
+ language tag to be included is "en". The class of the <html> element
478
+ will be copied verbatim from the XML <rfc> element's <front>
479
+ element's <seriesInfo> element's "name" attributes (separated by
480
+ spaces; see Section 2.47.3 of [RFC7991]), allowing CSS to style RFCs
481
+ and Internet-Drafts differently from one another (if needed):
482
+
483
+ <html lang="en" class="RFC">
484
+
485
+ 6.3. <head> Element
486
+
487
+ The root <html> will contain a <head> element that contains the
488
+ following elements, as needed.
489
+
490
+ 6.3.1. Charset Declaration
491
+
492
+ In order to be correctly processed by browsers that load the HTML
493
+ using a mechanism that does not provide a valid content-type or
494
+ charset (such as from a local file system using a "file:" URL), the
495
+ HTML <head> element contains a <meta> element, whose "charset"
496
+ attribute value is "utf-8":
497
+
498
+ <meta charset="utf-8">
499
+
500
+
501
+
502
+
503
+
504
+
505
+
506
+ Hildebrand & Hoffman Informational [Page 9]
507
+
508
+ RFC 7992 HTML for RFCs December 2016
509
+
510
+
511
+ 6.3.2. Document Title
512
+
513
+ The contents of the <title> element from the XML source will be
514
+ placed inside an HTML <title> element in the header.
515
+
516
+ 6.3.3. Document Metadata
517
+
518
+ The following <meta> elements will be included:
519
+
520
+ o author - one each for the each of the "fullname"s and
521
+ "asciiFullname"s of all of the <author>s from the <front> of the
522
+ XML source
523
+
524
+ o description - the <abstract> from the XML source
525
+
526
+ o generator - the name and version number of the software used to
527
+ create the HTML
528
+
529
+ o keywords - comma-separated <keyword>s from the XML source
530
+
531
+ For example:
532
+
533
+ <meta name="author" content="Joe Hildebrand">
534
+ <meta name="author" content="JOE HILDEBRAND">
535
+ <meta name="author" content="Heather Flanagan">
536
+ <meta name="description" content="This document defines...">
537
+ <meta name="generator" content="xmljade v0.2.4">
538
+ <meta name="keywords" content="html,css,rfc">
539
+
540
+ Note: the HTML <meta> tag does not contain a closing slash.
541
+
542
+ 6.3.4. Link to XML Source
543
+
544
+ The <head> element contains a <link> tag, with "rel" attribute of
545
+ "alternate", "type" attribute of "application/rfc+xml", and "href"
546
+ attribute pointing to the prepared XML source that was used to
547
+ generate this document.
548
+
549
+ <link rel="alternate" type="application/rfc+xml" href="source.xml">
550
+
551
+ 6.3.5. Link to License
552
+
553
+ The <head> element contains a <link> tag, with "rel" attribute of
554
+ "license" and "href" attribute pointing to the an appropriate
555
+ copyright license for the document.
556
+
557
+ <link rel="license"
558
+ href="https://trustee.ietf.org/trust-legal-provisions.html">
559
+
560
+
561
+
562
+ Hildebrand & Hoffman Informational [Page 10]
563
+
564
+ RFC 7992 HTML for RFCs December 2016
565
+
566
+
567
+ 6.3.6. Style
568
+
569
+ The <head> element contains an embedded CSS in a <style> element.
570
+ The styles in the style sheet are to be set consistently between
571
+ documents by the RFC Editor, according to the best practices of the
572
+ day.
573
+
574
+ To ensure consistent formatting, individual style attributes should
575
+ not be used in the main portion of the document.
576
+
577
+ Different readers of a specification will desire different formatting
578
+ when reading the HTML versions of RFCs. To facilitate this, the
579
+ <head> element also includes a <link> to a style sheet in the same
580
+ directory as the HTML file, named "rfc-local.css". Any formatting in
581
+ the linked style sheet will override the formatting in the included
582
+ style sheet. For example:
583
+
584
+ <style>
585
+ body {}
586
+ ...
587
+ </style>
588
+ <link rel="stylesheet" type="text/css" href="rfc-local.css">
589
+
590
+ 6.3.7. Links
591
+
592
+ Each <link> element from the XML source is copied into the HTML
593
+ header. Note: the HTML <link> element does not include a closing
594
+ slash.
595
+
596
+ 6.4. Page Headers and Footers
597
+
598
+ In order to simplify printing by HTML renderers that implement
599
+ [W3C.WD-css3-page-20130314], a hidden HTML <table> tag of class
600
+ "ears" is added at the beginning of the HTML <body> tag, containing
601
+ HTML <thead> and <tfoot> tags, each of which contains an HTML <tr>
602
+ tag, which contains three HTML <td> tags with class "left", "center",
603
+ and "right", respectively.
604
+
605
+ The <thead> corresponds to the top of the page, the <tfoot> to the
606
+ bottom. The string "[Page]" can be used as a placeholder for the
607
+ page number. In practice, this must always be in the <tfoot>'s right
608
+ <td>, and no control of the formatting of the page number is implied.
609
+
610
+
611
+
612
+
613
+
614
+
615
+
616
+
617
+
618
+ Hildebrand & Hoffman Informational [Page 11]
619
+
620
+ RFC 7992 HTML for RFCs December 2016
621
+
622
+
623
+ <table class="ears">
624
+ <thead>
625
+ <tr>
626
+ <td class="left">Internet-Draft</td>
627
+ <td class="center">HTML RFC</td>
628
+ <td class="right">March 2016</td>
629
+ </tr>
630
+ </thead>
631
+ <tfoot>
632
+ <tr>
633
+ <td class="left">Hildebrand</td>
634
+ <td class="center">Expires September 2, 2016</td>
635
+ <td class="right">[Page]</td>
636
+ </tr>
637
+ </tfoot>
638
+ </table>
639
+
640
+ 6.5. Document Information
641
+
642
+ Information about the document as a whole will appear as the first
643
+ child of the HTML <body> element, embedded in an HTML <dl> element
644
+ with id="identifiers". The defined terms in the definition list are
645
+ "Workgroup:", "Series:", "Status:", "Published:", and "Author:" or
646
+ "Authors:" (as appropriate). For example:
647
+
648
+
649
+
650
+
651
+
652
+
653
+
654
+
655
+
656
+
657
+
658
+
659
+
660
+
661
+
662
+
663
+
664
+
665
+
666
+
667
+
668
+
669
+
670
+
671
+
672
+
673
+
674
+ Hildebrand & Hoffman Informational [Page 12]
675
+
676
+ RFC 7992 HTML for RFCs December 2016
677
+
678
+
679
+ <dl id="identifiers">
680
+ <dt>Workgroup:</dt>
681
+ <dd class="workgroup">rfc-interest</dd>
682
+ <dt>Series:</dt>
683
+ <dd class="series">Internet-Draft</dd>
684
+ <dt>Status:</dt>
685
+ <dd class="status">Informational</dd>
686
+ <dt>Published:</dt>
687
+ <dd><time datetime="2014-10-25"
688
+ class="published">2014-10-25</time></dd>
689
+ <dt>Authors:</dt>
690
+ <dd class="authors">
691
+ <div class="author">
692
+ <span class="initial">J.</span>
693
+ <span class="surname">Hildebrand</span>
694
+ (<span class="organization">Cisco Systems, Inc.</span>)
695
+ <span class="editor">Ed.</span>
696
+ </div>
697
+ <div class="author">
698
+ <span class="initial">H.</span>
699
+ <span class="surname">Flanagan</span>
700
+ (<span class="organization">RFC Editor</span>)
701
+ </div>
702
+ </dd>
703
+ </dl>
704
+
705
+ 6.6. Table of Contents
706
+
707
+ The table of contents will follow the boilerplate if the XML's <rfc>
708
+ element's "tocInclude" attribute has the value "true". An HTML <h2>
709
+ heading containing the text "Table of Contents" will be followed by a
710
+ <nav> element that contains a <ul> element for each depth of the
711
+ section hierarchy. Each section will be represented by a <li>
712
+ element containing links by the section number (from the "pn"
713
+ attribute) and by the name (from the "slugifiedName" attribute of the
714
+ <name> child element). Each <nav>, <ul>, and <li> element will have
715
+ the class "toc".
716
+
717
+ For example:
718
+
719
+
720
+
721
+
722
+
723
+
724
+
725
+
726
+
727
+
728
+
729
+
730
+ Hildebrand & Hoffman Informational [Page 13]
731
+
732
+ RFC 7992 HTML for RFCs December 2016
733
+
734
+
735
+ <h2 id="toc">Table of Contents</h2>
736
+ <nav class="toc">
737
+ <ul class="toc">
738
+ <li class="toc">
739
+ <a href="s-1">1</a>. <a href="n-introduction">Introduction</a>
740
+ </li>
741
+ <ul class="toc">
742
+ <li class="toc">
743
+ <a href="s-1.1">1.1</a>. <a href="n-sub-intro">Sub Intro</a>
744
+ </li>
745
+ ...
746
+
747
+ 7. Main Body
748
+
749
+ The main body of the HTML document is processed according to the
750
+ rules in Section 9.
751
+
752
+ 8. Back Matter
753
+
754
+ The back matter of the HTML document includes an index (if
755
+ generated), information about the authors, and further information
756
+ about the document itself.
757
+
758
+ 8.1. Index
759
+
760
+ The index will be produced as dictated by the RFC Editor's Style
761
+ Guide [RFC-STYLE] if and only if the XML document's <rfc> element has
762
+ an "indexInclude" attribute with the value "true" and there is one or
763
+ more <iref> elements in the document.
764
+
765
+ 8.1.1. Index Contents
766
+
767
+ The index section will start with an <h2> heading containing the text
768
+ "Index", followed by links to each of the lettered portions of the
769
+ index. Links are not generated for letters that do not occur as the
770
+ first letter of an index item.
771
+
772
+ For example:
773
+
774
+ <h2>Index</h2>
775
+ <div class="index">
776
+ <div class="indexIndex">
777
+ <a href="#rfc.index.C">C</a>
778
+ <a href="#rfc.index.P">P</a>
779
+ </div>
780
+ ...
781
+
782
+
783
+
784
+
785
+
786
+ Hildebrand & Hoffman Informational [Page 14]
787
+
788
+ RFC 7992 HTML for RFCs December 2016
789
+
790
+
791
+ 8.1.2. Index Letters
792
+
793
+ The index letter is followed by a <ul> tag that contains an <li> tag
794
+ for each first letter represented in the index. This <li> tag has
795
+ the class "indexChar" and contains an <a> tag with the id pointed to
796
+ by the index letter as well as an "href" attribute to itself. The
797
+ <li> tag also includes a <ul> tag that will contain the index items.
798
+
799
+ For example:
800
+
801
+ <ul>
802
+ <li class="indexChar">
803
+ <a href="#rfc.index.C" id="rfc.index.C">C</a>
804
+ <ul>
805
+ <!-- items go here -->
806
+ </ul>
807
+ </li>
808
+ ...
809
+
810
+ 8.1.3. Index Items
811
+
812
+ Each index item can have multiple <iref> elements to point to, all
813
+ with the same item attribute. Each index item is represented by an
814
+ <li> tag of class "indexItem" containing a <span> of class "irefItem"
815
+ for the item text and one of class "irefRefs" for the generated
816
+ references (if there is at least one reference to the item not having
817
+ a subitem). Each generated reference contains an <a> tag containing
818
+ the section number where the <iref> is found, with an "href"
819
+ attribute pointing to the "irefid" attribute of the <iref> element
820
+ from the XML document. If the primary attribute of the <iref>
821
+ element has the value "true", the <a> element in the HTML document
822
+ will have the class "indexPrimary". Commas may be used to separate
823
+ the generated references.
824
+
825
+ For example:
826
+
827
+ <li class="indexItem">
828
+ <span class="irefItem">Bullets</span>
829
+ <span class="irefRefs">
830
+ <a class="indexPrimary" href="#s-Bullets-1">2</a>,
831
+ <a href="#s-Bullets-2">2</a>
832
+ </span>
833
+ <!-- subitems go here -->
834
+ </li>
835
+ ...
836
+
837
+
838
+
839
+
840
+
841
+
842
+ Hildebrand & Hoffman Informational [Page 15]
843
+
844
+ RFC 7992 HTML for RFCs December 2016
845
+
846
+
847
+ 8.1.4. Index Subitems
848
+
849
+ If an index item has at least one subitem, the <li> of that item will
850
+ contain a <ul>, with one <li> for each subitem, of class
851
+ "indexSubItem". The format for each subitem is similar to that used
852
+ for items, except the class of the first <span> tag is "irefSubItem".
853
+
854
+ For example:
855
+
856
+ <ul>
857
+ <li class="indexSubItem">
858
+ <span class="irefSubItem">Ordered</span>
859
+ <span class="irefRefs">
860
+ <a href="#s-Bullets-Ordered-1">2</a>
861
+ </span>
862
+ </li>
863
+ </ul>
864
+ ...
865
+
866
+ 8.2. Authors' Addresses Section
867
+
868
+ At the end of the document, author information will be included
869
+ inside an HTML <section> element whose "id" attribute is "author-
870
+ addresses". The class names of the constituent HTML tags have been
871
+ chosen to match the class names in [HCARD].
872
+
873
+ The information for each author will be separated by an HTML <hr>
874
+ element with class "addr".
875
+
876
+ <section id="author-addresses">
877
+ <h2>
878
+ <a class="selfRef" href="#author-addresses">
879
+ Authors' Addresses
880
+ </a>
881
+ </h2>
882
+ <address class="vcard">
883
+ <div class="nameRole"><span class="fn">Joe Hildebrand</span>
884
+ (<span class="role">editor</span>)</div>
885
+ <div class="org">Cisco Systems, Inc.</div>
886
+ </address>
887
+ <hr class="addr">
888
+ <address class="vcard">
889
+ <div class="nameRole"><span class="fn">Heather Flanagan</span>
890
+ (<span class="role">editor</span>)</div>
891
+ <div class="org">RFC Series Editor</div>
892
+ </address>
893
+ </section>
894
+
895
+
896
+
897
+
898
+ Hildebrand & Hoffman Informational [Page 16]
899
+
900
+ RFC 7992 HTML for RFCs December 2016
901
+
902
+
903
+ 8.3. Document Information
904
+
905
+ A few bits of metadata about the document that are less important to
906
+ most readers are included after the author information. These are
907
+ gathered together into a <div> of class "docInfo".
908
+
909
+ The finalized time is copied from the <rfc> element's "prepTime"
910
+ attribute. The rendered time is the time that this HTML was
911
+ generated.
912
+
913
+ For example:
914
+
915
+ <div class="docInfo">
916
+ <span class="finalized">
917
+ Finalized: <time
918
+ datetime="2015-04-29T18:59:08Z">2015-04-29T18:59:08Z</time>
919
+ </span>
920
+ <span class="rendered">
921
+ Rendered: <time
922
+ datetime="2015-04-29T18:59:10Z">2015-04-29T18:59:10Z</time>
923
+ </span>
924
+ </div>
925
+
926
+ 9. Elements
927
+
928
+ This section describes how each of the XML elements from [RFC7991] is
929
+ rendered to HTML. Many of the descriptions have examples to clarify
930
+ how elements will be rendered.
931
+
932
+ 9.1. <abstract>
933
+
934
+ The abstract is rendered in a similar fashion to a <section> with
935
+ anchor="abstract" and <name>Abstract</name>, but without a section
936
+ number.
937
+
938
+ <section id="abstract">
939
+ <h2><a href="#abstract" class="selfRef">Abstract</a></h2>
940
+ <p id="s-abstract-1">This document defines...
941
+ <a href="#s-abstract-1" class="pilcrow">&para;</a>
942
+ </p>
943
+ </section>
944
+
945
+ 9.2. <address>
946
+
947
+ This element is used in the Authors' Addresses section. It is
948
+ rendered as an HTML <address> tag of class "vcard". If none of the
949
+ descendant XML elements has an "ascii" attribute, the <address> HTML
950
+ tag includes the HTML rendering of each of the descendant XML
951
+
952
+
953
+
954
+ Hildebrand & Hoffman Informational [Page 17]
955
+
956
+ RFC 7992 HTML for RFCs December 2016
957
+
958
+
959
+ elements. Otherwise, the <address> HTML tag includes an HTML <div>
960
+ tag of class "ascii" (containing the HTML rendering of the ASCII
961
+ variants of each of the descendant XML elements), an HTML <div> tag
962
+ of class "alternative-contact", (containing the text "Alternate
963
+ contact information:"), and an HTML <div> tag of class "non-ascii"
964
+ (containing the HTML rendering of the non-ASCII variants of each of
965
+ the descendant XML elements).
966
+
967
+ Note: the following example shows some ASCII equivalents that are the
968
+ same as their nominal equivalents for clarity; normally, the ASCII
969
+ equivalents would not be included for these cases.
970
+
971
+ <address class="vcard">
972
+ <div class="ascii">
973
+ <div class="nameRole"><span class="fn">Joe Hildebrand</span>
974
+ (<span class="role">editor</span>)</div>
975
+ <div class="org">Cisco Systems, Inc.</div>
976
+ </div>
977
+ <div class="alternative-contact">
978
+ Alternate contact information:
979
+ </div>
980
+ <div class="non-ascii">
981
+ <div class="nameRole"><span class="fn">Joe Hildebrand</span>
982
+ (<span class="role">editor</span>)</div>
983
+ <div class="org">Cisco Systems, Inc.</div>
984
+ </div>
985
+ </address>
986
+
987
+ 9.3. <annotation>
988
+
989
+ This element is rendered as the text ", " (a comma and a space)
990
+ followed by a <span> of class "annotation" at the end of a
991
+ <reference> element, the <span> containing appropriately transformed
992
+ elements from the children of the <annotation> tag.
993
+
994
+ <span class="annotation">Some <em>thing</em>.</span>
995
+
996
+ 9.4. <area>
997
+
998
+ Not currently rendered to HTML.
999
+
1000
+ 9.5. <artwork>
1001
+
1002
+ Artwork can consist of either inline text or SVG. If the artwork is
1003
+ not inside a <figure> element, a pilcrow (Section 5.2) is included.
1004
+ Inside a <figure> element, the figure title serves the purpose of the
1005
+ pilcrow. If the "align" attribute has the value "right", the CSS
1006
+
1007
+
1008
+
1009
+
1010
+ Hildebrand & Hoffman Informational [Page 18]
1011
+
1012
+ RFC 7992 HTML for RFCs December 2016
1013
+
1014
+
1015
+ class "alignRight" will be added. If the "align" attribute has the
1016
+ value "center", the CSS class "alignCenter" will be added.
1017
+
1018
+ 9.5.1. Text Artwork
1019
+
1020
+ Text artwork is rendered inside an HTML <pre> element, which is
1021
+ contained by a <div> element for consistency with SVG artwork. Note
1022
+ that CDATA blocks are not a part of HTML, so angle brackets and
1023
+ ampersands (i.e., <, >, and &) must be escaped as &lt;, &gt;, and
1024
+ &amp;, respectively.
1025
+
1026
+ The <div> element will have CSS classes of "artwork", "art-text", and
1027
+ "art-" prepended to the value of the <artwork> element's "type"
1028
+ attribute, if it exists.
1029
+
1030
+ <div class="artwork art-text art-ascii-art" id="s-1-2">
1031
+ <pre>
1032
+ ______________
1033
+ &lt; hello, world &gt;
1034
+ --------------
1035
+ \ ^__^
1036
+ \ (oo)\_______
1037
+ (__)\ )\/\
1038
+ ||----w |
1039
+ || ||
1040
+ </pre>
1041
+ <a class="pilcrow" href="#s-1-2">&para;</a>
1042
+ </div>
1043
+
1044
+ 9.5.2. SVG Artwork
1045
+
1046
+ SVG artwork will be included inline. The SVG is wrapped in a <div>
1047
+ element with CSS classes "artwork" and "art-svg".
1048
+
1049
+ If the SVG "artwork" element is a child of <figure> and the artwork
1050
+ is specified as align="right", an empty HTML <span> element is added
1051
+ directly after the <svg> element, in order to get right alignment to
1052
+ work correctly in HTML rendering engines that do not support the
1053
+ flex-box model.
1054
+
1055
+ Note: the "alt" attribute of <artwork> is not currently used for SVG;
1056
+ instead, the <title> and <desc> tags are used in the SVG.
1057
+
1058
+
1059
+
1060
+
1061
+
1062
+
1063
+
1064
+
1065
+
1066
+ Hildebrand & Hoffman Informational [Page 19]
1067
+
1068
+ RFC 7992 HTML for RFCs December 2016
1069
+
1070
+
1071
+ <div class="artwork art-svg" id="s-2-17">
1072
+ <svg width="100" height="100" xmlns="http://www.w3.org/2000/svg">
1073
+ <desc>Alt text here</desc>
1074
+ <circle
1075
+ cx="50" cy="50" r="40"
1076
+ stroke="green" stroke-width="4" fill="yellow" />
1077
+ </svg>
1078
+ <a href="#s-2-17" class="pilcrow">&para;</a>
1079
+ </div>
1080
+
1081
+ 9.5.3. Other Artwork
1082
+
1083
+ Other artwork will have a "src" attribute that uses the "data" URI
1084
+ scheme defined in [RFC2397]. Such artwork is rendered in an HTML
1085
+ <img> element. Note: the HTML <img> element does not have a closing
1086
+ slash.
1087
+
1088
+ Note: such images are not yet allowed in RFCs even though the format
1089
+ supports them. A limited set of "data:" mediatypes for artwork may
1090
+ be allowed in the future.
1091
+
1092
+ <div class="artwork art-logo" id="s-2-58">
1093
+ <img alt="IETF logo"
1094
+ src="data:image/gif;charset=utf-8;base64,...">
1095
+ <a class="pilcrow" href="#s-2-58">&para;</a>
1096
+ </div>
1097
+
1098
+ 9.6. <aside>
1099
+
1100
+ This element is rendered as an HTML <aside> element, with all child
1101
+ content appropriately transformed.
1102
+
1103
+ <aside id="s-2.1-2">
1104
+ <p id="s-2.1-2.1">
1105
+ A little more than kin, and less than kind.
1106
+ <a class="pilcrow" href="#s-2.1-2.1">&para;</a>
1107
+ </p>
1108
+ </aside>
1109
+
1110
+ 9.7. <author>
1111
+
1112
+ The <author> element is used in several places in the output.
1113
+ Different rendering is used for each.
1114
+
1115
+
1116
+
1117
+
1118
+
1119
+
1120
+
1121
+
1122
+ Hildebrand & Hoffman Informational [Page 20]
1123
+
1124
+ RFC 7992 HTML for RFCs December 2016
1125
+
1126
+
1127
+ 9.7.1. Authors in Document Information
1128
+
1129
+ As seen in the Document Information at the beginning of the HTML,
1130
+ each document author is rendered as an HTML <div> tag of class
1131
+ "author".
1132
+
1133
+ Inside the <div class="author"> HTML tag, the author's initials and
1134
+ surname (or the fullname, if it exists and the others do not) will be
1135
+ rendered in an HTML <div> tag of class "author-name". If the
1136
+ <author> contains "asciiInitials" and "asciiSurname" attributes, or
1137
+ contains as "asciiFullname" attribute, the author's name is rendered
1138
+ twice, with the first being the non-ASCII version, wrapped in an HTML
1139
+ <span> tag of class "non-ascii", followed by the ASCII version
1140
+ wrapped in an HTML <span> tag of class "ascii", wrapped in
1141
+ parentheses. If the <author> has a "role" attribute of "editor", the
1142
+ <div class="author-name"> will also contain the text ", " (comma,
1143
+ space), followed by an HTML <span> tag of class "editor", which
1144
+ contains the text "Ed.".
1145
+
1146
+ If the <author> element contains an <organization> element, it is
1147
+ also rendered inside the <div class="author"> HTML tag.
1148
+
1149
+ <div class="author">
1150
+ <div class="author-name">
1151
+ H. Flanagan,
1152
+ <span class="editor">Ed.</span></div>
1153
+ <div class="org">Test Org</div>
1154
+ </div>
1155
+ <div class="author">
1156
+ <div class="author-name">
1157
+ <span class="non-ascii">Hildebrand</span>
1158
+ (<span class="ascii">HILDEBRAND</span>)
1159
+ </div>
1160
+ <div class="org">
1161
+ <span class="non-ascii">Test Org</span>
1162
+ (<span class="ascii">TEST ORG</span>)
1163
+ </div>
1164
+ </div>
1165
+
1166
+ 9.7.2. Authors of This Document
1167
+
1168
+ As seen in the Authors' Addresses section, at the end of the HTML,
1169
+ each document author is rendered into an HTML <address> element with
1170
+ the CSS class "vcard".
1171
+
1172
+ The HTML <address> element will contain an HTML <div> with CSS class
1173
+ "nameRole". That div will contain an HTML <span> element with CSS
1174
+ class "fn" containing the value of the "fullname" attribute of the
1175
+
1176
+
1177
+
1178
+ Hildebrand & Hoffman Informational [Page 21]
1179
+
1180
+ RFC 7992 HTML for RFCs December 2016
1181
+
1182
+
1183
+ <author> XML element and an HTML <span> element with CSS class "role"
1184
+ containing the value of the "role" attribute of the <author> XML
1185
+ element (if there is a role). Parentheses will surround the <span
1186
+ class="role">, if it exists.
1187
+
1188
+ <address class="vcard">
1189
+ <div class="nameRole">
1190
+ <span class="fn">Joe Hildebrand</span>
1191
+ (<span class="role">editor</span>)
1192
+ </div>
1193
+ ...
1194
+
1195
+ After the name, the <organization> and <address> child elements of
1196
+ the author are rendered inside the HTML <address> tag.
1197
+
1198
+ When the <author> element, or any of its descendant elements, has any
1199
+ attribute that starts with "ascii", all of the author information is
1200
+ displayed twice. The first version is wrapped in an HTML <div> tag
1201
+ with class "ascii"; this version prefers the ASCII version of
1202
+ information, such as "asciiFullname", but falls back on the non-ASCII
1203
+ version if the ASCII version doesn't exist. The second version is
1204
+ wrapped in an HTML <div> tag with class "non-ascii"; this version
1205
+ prefers the non-ASCII version of information, such as "fullname", but
1206
+ falls back on the ASCII version if the non-ASCII version does not
1207
+ exist. Between these two HTML <div>s, a third <div> is inserted,
1208
+ with class "alternative-contact", containing the text "Alternate
1209
+ contact information:".
1210
+
1211
+ <address class="vcard">
1212
+ <div class="ascii">
1213
+ <div class="nameRole">
1214
+ <span class="fn">The ASCII name</span>
1215
+ </div>
1216
+ </div>
1217
+ <div class="alternative-contact">
1218
+ Alternate contact information:
1219
+ </div>
1220
+ <div class="non-ascii">
1221
+ <div class="nameRole">
1222
+ <span class="fn">The non-ASCII name</span>
1223
+ (<span class="role">editor</span>)
1224
+ </div>
1225
+ </div>
1226
+ </address>
1227
+
1228
+
1229
+
1230
+
1231
+
1232
+
1233
+
1234
+ Hildebrand & Hoffman Informational [Page 22]
1235
+
1236
+ RFC 7992 HTML for RFCs December 2016
1237
+
1238
+
1239
+ 9.7.3. Authors of References
1240
+
1241
+ In the output generated from a reference element, author tags are
1242
+ rendered inside an HTML <span> element with CSS class "refAuthor".
1243
+ See Section 4.8.6.2 of [RFC7322] for guidance on how author names are
1244
+ to appear.
1245
+
1246
+ <span class="refAuthor">Flanagan, H.</span> and
1247
+ <span class="refAuthor">N. Brownlee</span>
1248
+
1249
+ 9.8. <back>
1250
+
1251
+ If there is exactly one <references> child, render that child in a
1252
+ similar way to a <section>. If there are more than one <references>
1253
+ children, render as a <section> whose name is "References",
1254
+ containing a <section> for each <references> child.
1255
+
1256
+ After any <references> sections, render each <section> child of
1257
+ <back> as an appendix.
1258
+
1259
+ <section id="n-references">
1260
+ <h2 id="s-2">
1261
+ <a class="selfRef" href="#s-2">2.</a>
1262
+ <a class="selfRef" href="#n-references">References</a>
1263
+ </h2>
1264
+ <section id="n-normative">
1265
+ <h3 id="s-2.1">
1266
+ <a class="selfRef" href="#s-2.1">2.1.</a>
1267
+ <a class="selfRef" href="#n-normative">Normative</a>
1268
+ </h3>
1269
+ <dl class="reference"></dl>
1270
+ </section>
1271
+ <section id="n-informational">
1272
+ <h3 id="s-2.2">
1273
+ <a class="selfRef" href="#s-2.2">2.2.</a>
1274
+ <a class="selfRef" href="#n-informational">Informational</a>
1275
+ </h3>
1276
+ <dl class="reference"></dl>
1277
+ </section>
1278
+ </section>
1279
+ <section id="n-unimportant">
1280
+ <h2 id="s-A">
1281
+ <a class="selfRef" href="#s-A">Appendix A.</a>
1282
+ <a class="selfRef" href="#n-unimportant">Unimportant</a>
1283
+ </h2>
1284
+ </section>
1285
+
1286
+
1287
+
1288
+
1289
+
1290
+ Hildebrand & Hoffman Informational [Page 23]
1291
+
1292
+ RFC 7992 HTML for RFCs December 2016
1293
+
1294
+
1295
+ 9.9. <bcp14>
1296
+
1297
+ This element marks up words like MUST and SHOULD [BCP14] with an HTML
1298
+ <span> element with the CSS class "bcp14".
1299
+
1300
+ You <span class="bcp14">MUST</span> be joking.
1301
+
1302
+ 9.10. <blockquote>
1303
+
1304
+ This element renders in a way similar to the HTML <blockquote>
1305
+ element. If there is a "cite" attribute, it is copied to the HTML
1306
+ "cite" attribute. If there is a "quoteFrom" attribute, it is placed
1307
+ inside a <cite> element at the end of the quote, with an <a> element
1308
+ surrounding it (if there is a "cite" attribute), linking to the cited
1309
+ URL.
1310
+
1311
+ If the <blockquote> does not contain another element that gets a
1312
+ pilcrow (Section 5.2), a pilcrow is added.
1313
+
1314
+ Note that the "&mdash;" at the beginning of the <cite> element should
1315
+ be a proper emdash, which is difficult to show in the display of the
1316
+ current format.
1317
+
1318
+ <blockquote id="s-1.2-1"
1319
+ cite="http://...">
1320
+ <p id="s-1.2-2">Four score and seven years ago our fathers
1321
+ brought forth on this continent, a new nation, conceived
1322
+ in Liberty, and dedicated to the proposition that all men
1323
+ are created equal.
1324
+ <a href="#s-1.2-2" class="pilcrow">&para;</a>
1325
+ </p>
1326
+ <cite>&mdash; <a href="http://...">Abraham Lincoln</a></cite>
1327
+ </blockquote>
1328
+
1329
+ 9.11. <boilerplate>
1330
+
1331
+ The Status of This Memo and the Copyright statement, together
1332
+ commonly referred to as the document boilerplate, appear after the
1333
+ Abstract. The children of the input <boilerplate> element are
1334
+ treated in a similar fashion to unnumbered sections.
1335
+
1336
+
1337
+
1338
+
1339
+
1340
+
1341
+
1342
+
1343
+
1344
+
1345
+
1346
+ Hildebrand & Hoffman Informational [Page 24]
1347
+
1348
+ RFC 7992 HTML for RFCs December 2016
1349
+
1350
+
1351
+ <section id="status-of-this-memo">
1352
+ <h2 id="s-boilerplate-1">
1353
+ <a href="#status-of-this-memo" class="selfRef">
1354
+ Status of this Memo</a>
1355
+ </h2>
1356
+ <p id="s-boilerplate-1-1">This Internet-Draft is submitted in full
1357
+ conformance with the provisions of BCP 78 and BCP 79.
1358
+ <a href="#s-boilerplate-1-1" class="pilcrow">&para;</a>
1359
+ </p>
1360
+ ...
1361
+
1362
+ 9.12. <br>
1363
+
1364
+ This element is directly rendered as its HTML counterpart. Note: in
1365
+ HTML, <br> does not have a closing slash.
1366
+
1367
+ 9.13. <city>
1368
+
1369
+ This element is rendered as a <span> element with CSS class
1370
+ "locality".
1371
+
1372
+ <span class="locality">Guilford</span>
1373
+
1374
+ 9.14. <code>
1375
+
1376
+ This element is rendered as a <span> element with CSS class "postal-
1377
+ code".
1378
+
1379
+ <span class="postal-code">GU16 7HF<span>
1380
+
1381
+ 9.15. <country>
1382
+
1383
+ This element is rendered as a <div> element with CSS class "country-
1384
+ name".
1385
+
1386
+ <div class="country-name">England</div>
1387
+
1388
+ 9.16. <cref>
1389
+
1390
+ This element is rendered as a <span> element with CSS class "cref".
1391
+ Any anchor is copied to the "id" attribute. If there is a source
1392
+ given, it is contained inside the "cref" <span> element with another
1393
+ <span> element of class "crefSource".
1394
+
1395
+ <span class="cref" id="crefAnchor">Just a brief comment
1396
+ about something that we need to remember later.
1397
+ <span class="crefSource">--life</span></span>
1398
+
1399
+
1400
+
1401
+
1402
+ Hildebrand & Hoffman Informational [Page 25]
1403
+
1404
+ RFC 7992 HTML for RFCs December 2016
1405
+
1406
+
1407
+ 9.17. <date>
1408
+
1409
+ This element is rendered as the HTML <time> element. If the "year",
1410
+ "month", or "day" attribute is included on the XML element, an
1411
+ appropriate "datetime" element will be generated in HTML.
1412
+
1413
+ If this date is a child of the document's <front> element, it gets
1414
+ the CSS class "published".
1415
+
1416
+ If this date is inside a <reference> element, it gets the CSS class
1417
+ "refDate".
1418
+
1419
+ <time datetime="2014-10" class="published">October 2014</time>
1420
+
1421
+ 9.18. <dd>
1422
+
1423
+ This element is directly rendered as its HTML counterpart.
1424
+
1425
+ 9.19. <displayreference>
1426
+
1427
+ This element does not affect the HTML output, but it is used in the
1428
+ generation of the <reference>, <referencegroup>, <relref>, and <xref>
1429
+ elements.
1430
+
1431
+ 9.20. <dl>
1432
+
1433
+ This element is directly rendered as its HTML counterpart.
1434
+
1435
+ If the hanging attribute is "false", add the "dlParallel" class, else
1436
+ add the "dlHanging" class.
1437
+
1438
+ If the spacing attribute is "compact", add the "dlCompact" class.
1439
+
1440
+ 9.21. <dt>
1441
+
1442
+ This element is directly rendered as its HTML counterpart.
1443
+
1444
+ 9.22. <em>
1445
+
1446
+ This element is directly rendered as its HTML counterpart.
1447
+
1448
+ 9.23. <email>
1449
+
1450
+ This element is rendered as an HTML <div> containing the string
1451
+ "Email:" and an HTML <a> element with the "href" attribute set to the
1452
+ equivalent "mailto:" URI, a CSS class of "email", and the contents
1453
+ set to the email address. If this is the version of the address with
1454
+ ASCII, the "ascii" attribute is preferred to the element text.
1455
+
1456
+
1457
+
1458
+ Hildebrand & Hoffman Informational [Page 26]
1459
+
1460
+ RFC 7992 HTML for RFCs December 2016
1461
+
1462
+
1463
+ <div>
1464
+ <span>Email:</span>
1465
+ <a class="email" href="mailto:joe@example.com">joe@example.com</a>
1466
+ </div>
1467
+
1468
+ 9.24. <eref>
1469
+
1470
+ This element is rendered as an HTML <a> element, with the "href"
1471
+ attribute set to the value of the "target" attribute and the CSS
1472
+ class of "eref".
1473
+
1474
+ <a href="https://..." class="eref">the text</a>
1475
+
1476
+ 9.25. <figure>
1477
+
1478
+ This element renders as the HTML <figure> element, containing the
1479
+ artwork or sourcecode indicated and an HTML <figcaption> element.
1480
+ The <figcaption> element will contain an <a> element around the
1481
+ figure number. It will also contain another <a> element with CSS
1482
+ class "selfRef" around the figure name, if a name was given.
1483
+
1484
+ <figure id="f-1">
1485
+ ...
1486
+ <figcaption>
1487
+ <a href="#f-1">Figure 1.</a>
1488
+ <a href="#n-it-figures" id="n-it-figures" class="selfRef">
1489
+ It figures
1490
+ </a>
1491
+ </figcaption>
1492
+ </figure>
1493
+
1494
+ 9.26. <front>
1495
+
1496
+ See "Document Information" (Section 6.5) for information on this
1497
+ element.
1498
+
1499
+ 9.27. <iref>
1500
+
1501
+ This element is rendered as an empty <> tag of class "iref", with an
1502
+ "id" attribute consisting of the <iref> element's "irefid" attribute:
1503
+
1504
+ <span class="iref" id="s-Paragraphs-first-1"/>
1505
+
1506
+ 9.28. <keyword>
1507
+
1508
+ Each <keyword> element renders its text into the <meta> keywords in
1509
+ the document's header, separated by commas.
1510
+
1511
+
1512
+
1513
+
1514
+ Hildebrand & Hoffman Informational [Page 27]
1515
+
1516
+ RFC 7992 HTML for RFCs December 2016
1517
+
1518
+
1519
+ <meta name="keywords" content="html,css,rfc">
1520
+
1521
+ 9.29. <li>
1522
+
1523
+ This element is rendered as its HTML counterpart. However, if there
1524
+ is no contained element that has a pilcrow (Section 5.2) attached, a
1525
+ pilcrow is added.
1526
+
1527
+ <li id="s-2-7">Item <a href="#s-2-7" class="pilcrow">&para;</a></li>
1528
+
1529
+ 9.30. <link>
1530
+
1531
+ This element is rendered as its HTML counterpart, in the HTML header.
1532
+
1533
+ 9.31. <middle>
1534
+
1535
+ This element does not add any direct output to HTML.
1536
+
1537
+ 9.32. <name>
1538
+
1539
+ This element is never rendered directly; it is only rendered when
1540
+ considering a parent element, such as <figure>, <references>,
1541
+ <section>, or <table>.
1542
+
1543
+ 9.33. <note>
1544
+
1545
+ This element is rendered like a <section> element, but without a
1546
+ section number and with the CSS class of "note". If the
1547
+ "removeInRFC" attribute is set to "yes", the generated <div> element
1548
+ will also include the CSS class "rfcEditorRemove".
1549
+
1550
+ <section id="s-note-1" class="note rfcEditorRemove">
1551
+ <h2>
1552
+ <a href="#n-editorial-note" class="selfRef">Editorial Note</a>
1553
+ </h2>
1554
+ <p id="s-note-1-1">
1555
+ Discussion of this draft takes place...
1556
+ <a href="#s-note-1-1" class="pilcrow">&para;</a>
1557
+ </p>
1558
+ </section>
1559
+
1560
+ 9.34. <ol>
1561
+
1562
+ The output created from an <ol> element depends upon the "style"
1563
+ attribute.
1564
+
1565
+ If the "spacing" attribute has the value "compact", a CSS class of
1566
+ "olCompact" will be added.
1567
+
1568
+
1569
+
1570
+ Hildebrand & Hoffman Informational [Page 28]
1571
+
1572
+ RFC 7992 HTML for RFCs December 2016
1573
+
1574
+
1575
+ The group attribute is not copied; the input XML should have start
1576
+ values added by a prep tool for all grouped <ol> elements.
1577
+
1578
+ 9.34.1. Percent Styles
1579
+
1580
+ If the style attribute includes the character "%", the output is a
1581
+ <dl> tag with the class "olPercent". Each contained <li> element is
1582
+ emitted as a <dt>/<dd> pair, with the generated label in the <dt> and
1583
+ the contents of the <li> in the <dd>.
1584
+
1585
+ <dl class="olPercent">
1586
+ <dt>Requirement xviii:</dt>
1587
+ <dd>Wheels on a big rig</dd>
1588
+ </dl>
1589
+
1590
+ 9.34.2. Standard Styles
1591
+
1592
+ For all other styles, an <ol> tag is emitted, with any "style"
1593
+ attribute turned into the equivalent HTML attribute.
1594
+
1595
+ <ol class="compact" type="I" start="18">
1596
+ <li>Wheels on a big rig</li>
1597
+ </ol>
1598
+
1599
+ 9.35. <organization>
1600
+
1601
+ This element is rendered as an HTML <div> tag with CSS class "org".
1602
+
1603
+ If the element contains the "ascii" attribute, the organization name
1604
+ is rendered twice: once with the non-ASCII version wrapped in an HTML
1605
+ <span> tag of class "non-ascii" and then as the ASCII version wrapped
1606
+ in an HTML <span> tag of class "ascii" wrapped in parentheses.
1607
+
1608
+ <div class="org">
1609
+ <span class="non-ascii">Test Org</span>
1610
+ (<span class="ascii">TEST ORG</span>)
1611
+ </div>
1612
+
1613
+ 9.36. <phone>
1614
+
1615
+ This element is rendered as an HTML <div> tag containing the string
1616
+ "Phone:" (wrapped in a span), an HTML <a> tag with CSS class "tel"
1617
+ containing the phone number (and an href with a corresponding "tel:"
1618
+ URI), and an HTML <span> with CSS class "type" containing the string
1619
+ "VOICE".
1620
+
1621
+
1622
+
1623
+
1624
+
1625
+
1626
+ Hildebrand & Hoffman Informational [Page 29]
1627
+
1628
+ RFC 7992 HTML for RFCs December 2016
1629
+
1630
+
1631
+ <div>
1632
+ <span>Phone:</span>
1633
+ <a class="tel" href="tel:+1-720-555-1212">+1-720-555-1212</a>
1634
+ <span class="type">VOICE</span>
1635
+ </div>
1636
+
1637
+ 9.37. <postal>
1638
+
1639
+ This element renders as an HTML <div> with CSS class "adr", unless it
1640
+ contains one or more <postalLine> child elements; in which case, it
1641
+ renders as an HTML <pre> element with CSS class "label".
1642
+
1643
+ When there is no <postalLine> child, the following child elements are
1644
+ rendered into the HTML:
1645
+
1646
+ o Each <street> is rendered
1647
+
1648
+ o A <div> that includes:
1649
+
1650
+ * The rendering of all <city> elements
1651
+
1652
+ * A comma and a space: ", "
1653
+
1654
+ * The rendering of all <region> elements
1655
+
1656
+ * Whitespace
1657
+
1658
+ * The rendering of all <code> elements
1659
+
1660
+ o The rendering of all <country> elements
1661
+
1662
+ <div class="adr">
1663
+ <div class="street-address">1 Main Street</div>
1664
+ <div class="street-address">Suite 1</div>
1665
+ <div>
1666
+ <span class="city">Denver</span>,
1667
+ <span class="region">CO</span>
1668
+ <span class="postal-code">80212</span>
1669
+ </div>
1670
+ <div class="country-name">United States of America</div>
1671
+ </div>
1672
+
1673
+ 9.38. <postalLine>
1674
+
1675
+ This element renders as the text contained by the element, followed
1676
+ by a newline. However, the last <postalLine> in a given <postal>
1677
+ element should not be followed by a newline. For example:
1678
+
1679
+
1680
+
1681
+
1682
+ Hildebrand & Hoffman Informational [Page 30]
1683
+
1684
+ RFC 7992 HTML for RFCs December 2016
1685
+
1686
+
1687
+ <postal>
1688
+ <postalLine>In care of:</postalLine>
1689
+ <postalLine>Computer Sciences Division</postalLine>
1690
+ </postal>
1691
+
1692
+ Would be rendered as:
1693
+
1694
+ <pre class="label">In care of:
1695
+ Computer Sciences Division</pre>
1696
+
1697
+ 9.39. <refcontent>
1698
+
1699
+ This element renders as an HTML <span> with CSS class "refContent".
1700
+
1701
+ <span class="refContent">Self-published pamphlet</span>
1702
+
1703
+ 9.40. <reference>
1704
+
1705
+ If the parent of this element is not a <referencegroup>, this element
1706
+ will render as a <dt> <dd> pair with the defined term being the
1707
+ reference "anchor" attribute surrounded by square brackets and the
1708
+ definition including the correct set of bibliographic information as
1709
+ specified by [RFC7322]. The <dt> element will have an "id" attribute
1710
+ of the reference anchor.
1711
+
1712
+ <dl class="reference">
1713
+ <dt id="RFC5646">[RFC5646]</dt>
1714
+ <dd>
1715
+ <span class="refAuthor">Phillips, A.</span>
1716
+ <span>and</span>
1717
+ <span class="refAuthor">M. Davis</span>
1718
+ <span class="refTitle">"Tags for Identifying Languages"</span>,
1719
+ ...
1720
+ </dd>
1721
+ </dl>
1722
+
1723
+ If the child of a <referencegroup>, this element renders as a <div>
1724
+ of class "refInstance" whose "id" attribute is the value of the
1725
+ <source> element's "anchor" attribute.
1726
+
1727
+ <div class="refInstance" id="RFC5730">
1728
+ ...
1729
+ </div>
1730
+
1731
+
1732
+
1733
+
1734
+
1735
+
1736
+
1737
+
1738
+ Hildebrand & Hoffman Informational [Page 31]
1739
+
1740
+ RFC 7992 HTML for RFCs December 2016
1741
+
1742
+
1743
+ 9.41. <referencegroup>
1744
+
1745
+ A <referencegroup> is translated into a <dt> <dd> pair, with the
1746
+ defined term being the referencegroup "anchor" attribute surrounded
1747
+ by square brackets, and the definition containing the translated
1748
+ output of all of the child <reference> elements.
1749
+
1750
+ <dt id="STD69">[STD69]</dt>
1751
+ <dd>
1752
+ <div class="refInstance" id="RFC5730">
1753
+ <span class="refAuthor">Hollenbeck, S.</span>
1754
+ ...
1755
+ </div>
1756
+ <div class="refInstance" id="RFC5731">
1757
+ <span class="refAuthor">Hollenbeck, S.</span>
1758
+ ...
1759
+ </div>
1760
+ ...
1761
+ </dd>
1762
+
1763
+ 9.42. <references>
1764
+
1765
+ If there is at exactly one <references> element, a section is added
1766
+ to the document, continuing with the next section number after the
1767
+ last top-level <section> in <middle>. The <name> element of the
1768
+ <references> element is used as the section name.
1769
+
1770
+ <section id="n-my-references">
1771
+ <h2 id="s-3">
1772
+ <a href="#s-3" class="selfRef">3.</a>
1773
+ <a href="#n-my-references class="selfRef">My References</a>
1774
+ </h2>
1775
+ ...
1776
+ </section>
1777
+
1778
+ If there is more than one <references> element, an HTML <section>
1779
+ element is created to contain a subsection for each of the
1780
+ <references>. The section number will be the next section number
1781
+ after the last top-level <section> in <middle>. The name of this
1782
+ section will be "References", and its "id" attribute will be
1783
+ "n-references".
1784
+
1785
+
1786
+
1787
+
1788
+
1789
+
1790
+
1791
+
1792
+
1793
+
1794
+ Hildebrand & Hoffman Informational [Page 32]
1795
+
1796
+ RFC 7992 HTML for RFCs December 2016
1797
+
1798
+
1799
+ <section id="n-references">
1800
+ <h2 id="s-3">
1801
+ <a href="#s-3" class="selfRef">3.</a>
1802
+ <a href="#n-references" class="selfRef">References</a>
1803
+ </h2>
1804
+ <section id="n-informative-references">
1805
+ <h3 id="s-3.1">
1806
+ <a href="#s-3.1" class="selfRef">3.1.</a>
1807
+ <a href="#n-informative-references" class="selfRef">
1808
+ Informative References</a></h3>
1809
+ <dl class="reference">...
1810
+ </dl>
1811
+ </section>
1812
+ ...
1813
+ </section>
1814
+
1815
+ 9.43. <region>
1816
+
1817
+ This element is rendered as a <span> tag with CSS class "region".
1818
+
1819
+ <span class="region">Colorado</span>
1820
+
1821
+ 9.44. <relref>
1822
+
1823
+ This element is rendered as an HTML <a> tag with CSS class "relref"
1824
+ and "href" attribute of the "derivedLink" attribute of the element.
1825
+ Different values of the "displayFormat" attribute cause the text
1826
+ inside that HTML <a> tag to change and cause extra text to be
1827
+ generated. Some values of the "displayFormat" attribute also cause
1828
+ another HTML <a> tag to be rendered with CSS class "xref" and an
1829
+ "href" of "#" and the "target" attribute (modified by any applicable
1830
+ <displayreference> XML element) and text inside of the "target"
1831
+ attribute (modified by any applicable <displayreference> XML
1832
+ element). When used, this <a class='xref'> HTML tag is always
1833
+ surrounded by square brackets, for example, "[<a class='xref'
1834
+ href='#foo'>foo</a>]".
1835
+
1836
+ 9.44.1. displayFormat='of'
1837
+
1838
+ The output is an <a class='relref'> HTML tag, with contents of
1839
+ "Section " and the value of the "section" attribute. This is
1840
+ followed by the word "of" (surrounded by whitespace). This is
1841
+ followed by the <a class='xref'> HTML tag (surrounded by square
1842
+ brackets).
1843
+
1844
+ For example, with an input of:
1845
+
1846
+
1847
+
1848
+
1849
+
1850
+ Hildebrand & Hoffman Informational [Page 33]
1851
+
1852
+ RFC 7992 HTML for RFCs December 2016
1853
+
1854
+
1855
+ See <relref section="2.3" target="RFC9999" displayFormat="of"
1856
+ derivedLink="http://www.rfc-editor.org/info/rfc9999#s-2.3"/>
1857
+ for an overview.
1858
+
1859
+ The HTML generated will be:
1860
+
1861
+ See <a class="relref"
1862
+ href="http://www.rfc-editor.org/info/rfc9999#s-2.3">Section
1863
+ 2.3</a> of [<a class="xref" href="#RFC9999">RFC9999</a>]
1864
+ for an overview.
1865
+
1866
+ 9.44.2. displayFormat='comma'
1867
+
1868
+ The output is an <a class='xref'> HTML tag (wrapped by square
1869
+ brackets), followed by a comma (","), followed by whitespace,
1870
+ followed by an <a class='relref'> HTML tag, with contents of
1871
+ "Section " and the value of the "section" attribute.
1872
+
1873
+ For example, with an input of:
1874
+
1875
+ See <relref section="2.3" target="RFC9999" displayFormat="comma"
1876
+ derivedLink="http://www.rfc-editor.org/info/rfc9999#s-2.3"/>,
1877
+ for an overview.
1878
+
1879
+ The HTML generated will be:
1880
+
1881
+ See [<a class="xref" href="#RFC9999">RFC9999</a>], <a class="relref"
1882
+ href="http://www.rfc-editor.org/info/rfc9999#s-2.3">Section 2.3</a>,
1883
+ for an overview.
1884
+
1885
+ 9.44.3. displayFormat='parens'
1886
+
1887
+ The output is an <a> element with "href" attribute whose value is the
1888
+ value of the "target" attribute prepended by "#", and whose content
1889
+ is the value of the "target" attribute; the entire element is wrapped
1890
+ in square brackets. This is followed by whitespace. This is
1891
+ followed by an <a> element whose "href" attribute is the value of the
1892
+ "derivedLink" attribute and whose content is the value of the
1893
+ "derivedRemoteContent" attribute; the entire element is wrapped in
1894
+ parentheses.
1895
+
1896
+ For example, if Section 2.3 of RFC 9999 has the title "Protocol
1897
+ Overview", for an input of:
1898
+
1899
+ See <relref section="2.3" target="RFC9999" displayFormat="parens"
1900
+ derivedLink="http://www.rfc-editor.org/info/rfc9999#s-2.3"
1901
+ derivedRemoteContent="Section 2.3"/> for an overview.
1902
+
1903
+
1904
+
1905
+
1906
+ Hildebrand & Hoffman Informational [Page 34]
1907
+
1908
+ RFC 7992 HTML for RFCs December 2016
1909
+
1910
+
1911
+ The HTML generated will be:
1912
+
1913
+ See [<a class="relref" href="#RFC9999">RFC9999</a>]
1914
+ (<a class="relref"
1915
+ href="http://www.rfc-editor.org/info/rfc9999#s-2.3">Section
1916
+ 2.3</a>) for an overview.
1917
+
1918
+ 9.44.4. displayFormat='bare'
1919
+
1920
+ The output is an <a> element whose "href" attribute is the value of
1921
+ the "derivedLink" attribute and whose content is the value of the
1922
+ "derivedRemoteContent" attribute.
1923
+
1924
+ For this input:
1925
+
1926
+ See <relref section="2.3" target="RFC9999" displayFormat="bare"
1927
+ derivedLink="http://www.rfc-editor.org/info/rfc9999#s-2.3"
1928
+ derivedRemoteContent="Section 2.3"/> and ...
1929
+
1930
+ The HTML generated will be:
1931
+
1932
+ See <a class="relref"
1933
+ href="http://www.rfc-editor.org/info/rfc9999#s-2.3">Section
1934
+ 2.3</a> and ...
1935
+
1936
+ 9.45. <rfc>
1937
+
1938
+ Various attributes of this element are represented in different parts
1939
+ of the HTML document.
1940
+
1941
+ 9.46. <section>
1942
+
1943
+ This element is rendered as an HTML <section> element, containing an
1944
+ appropriate level HTML heading element (<h2>-<h6>). That heading
1945
+ element contains an <a> element around the part number (pn), if
1946
+ applicable (for instance, <abstract> does not get a section number).
1947
+ Another <a> element is included with the section's name.
1948
+
1949
+ <section id="intro">
1950
+ <h2 id="s-1">
1951
+ <a href="#s-1" class="selfRef">1.</a>
1952
+ <a href="#intro" class="selfRef">Introduction</a>
1953
+ </h2>
1954
+ <p id="s-1-1">Paragraph <a href="#s-1-1" class="pilcrow">&para;</a>
1955
+ </p>
1956
+ </section>
1957
+
1958
+
1959
+
1960
+
1961
+
1962
+ Hildebrand & Hoffman Informational [Page 35]
1963
+
1964
+ RFC 7992 HTML for RFCs December 2016
1965
+
1966
+
1967
+ 9.47. <seriesInfo>
1968
+
1969
+ This element is rendered in an HTML <span> element with CSS name
1970
+ "seriesInfo".
1971
+
1972
+ <span class="seriesInfo">RFC 5646</span>
1973
+
1974
+ 9.48. <sourcecode>
1975
+
1976
+ This element is rendered in an HTML <pre> element with a CSS class of
1977
+ "sourcecode". Note that CDATA blocks do not work consistently in
1978
+ HTML, so all <, >, and & must be escaped as &lt;, &gt;, and &amp;,
1979
+ respectively. If the input XML has a "type" attribute, another CSS
1980
+ class of "lang-" and the type is added.
1981
+
1982
+ If the sourcecode is not inside a <figure> element, a pilcrow
1983
+ (Section 5.2) is included. Inside a <figure> element, the figure
1984
+ title serves the purpose of the pilcrow.
1985
+
1986
+ <pre class="sourcecode lang-c">
1987
+ #include &lt;stdio.h&gt;
1988
+ int main(void)
1989
+ {
1990
+ printf(&quot;hello, world\n&quot;);
1991
+ return 0;
1992
+ }
1993
+ </pre>
1994
+
1995
+ 9.49. <street>
1996
+
1997
+ This element renders as an HTML <div> element with CSS class "street-
1998
+ address".
1999
+
2000
+ <div class="street-address">1899 Wynkoop St, Suite 600</div>
2001
+
2002
+ 9.50. <strong>
2003
+
2004
+ This element is directly rendered as its HTML counterpart.
2005
+
2006
+ 9.51. <sub>
2007
+
2008
+ This element is directly rendered as its HTML counterpart.
2009
+
2010
+ 9.52. <sup>
2011
+
2012
+ This element is directly rendered as its HTML counterpart.
2013
+
2014
+
2015
+
2016
+
2017
+
2018
+ Hildebrand & Hoffman Informational [Page 36]
2019
+
2020
+ RFC 7992 HTML for RFCs December 2016
2021
+
2022
+
2023
+ 9.53. <t>
2024
+
2025
+ This element is rendered as an HTML <p> element. A pilcrow
2026
+ (Section 5.2) is included.
2027
+
2028
+ <p id="s-1-1">A paragraph.
2029
+ <a href="#s-1-1" class="pilcrow">&para;</a></p>
2030
+
2031
+ 9.54. <table>
2032
+
2033
+ This element is directly rendered as its HTML counterpart.
2034
+
2035
+ 9.55. <tbody>
2036
+
2037
+ This element is directly rendered as its HTML counterpart.
2038
+
2039
+ 9.56. <td>
2040
+
2041
+ This element is directly rendered as its HTML counterpart.
2042
+
2043
+ 9.57. <tfoot>
2044
+
2045
+ This element is directly rendered as its HTML counterpart.
2046
+
2047
+ 9.58. <th>
2048
+
2049
+ This element is directly rendered as its HTML counterpart.
2050
+
2051
+ 9.59. <thead>
2052
+
2053
+ This element is directly rendered as its HTML counterpart.
2054
+
2055
+ 9.60. <title>
2056
+
2057
+ The title of the document appears in a <title> element in the <head>
2058
+ element, as described in Section 6.3.2.
2059
+
2060
+ The title also appears in an <h1> element and follows directly after
2061
+ the Document Information. The <h1> element has an "id" attribute
2062
+ with value "title".
2063
+
2064
+ <h1 id="title">HyperText Markup Language Request For
2065
+ Comments Format</h1>
2066
+
2067
+ Inside a reference, the title is rendered as an HTML <span> tag with
2068
+ CSS class "refTitle". The text is surrounded by quotes inside the
2069
+ <span>.
2070
+
2071
+
2072
+
2073
+
2074
+ Hildebrand & Hoffman Informational [Page 37]
2075
+
2076
+ RFC 7992 HTML for RFCs December 2016
2077
+
2078
+
2079
+ <span class="refTitle">"Tags for Identifying Languages"</span>
2080
+
2081
+ 9.61. <tr>
2082
+
2083
+ This element is directly rendered as its HTML counterpart.
2084
+
2085
+ 9.62. <tt>
2086
+
2087
+ This element is rendered as an HTML <code> element.
2088
+
2089
+ 9.63. <ul>
2090
+
2091
+ This element is directly rendered as its HTML counterpart. If the
2092
+ "spacing" attribute has the value "compact", a CSS class of
2093
+ "ulCompact" will be added. If the "empty" attribute has the value
2094
+ "true", a CSS class of "ulEmpty" will be added.
2095
+
2096
+ 9.64. <uri>
2097
+
2098
+ This element is rendered as an HTML <div> containing the string
2099
+ "URI:" and an HTML <a> element with the "href" attribute set to the
2100
+ linked URI, CSS class of "url" (note that the value is "url", not
2101
+ "uri" as one might expect), and the contents set to the linked URI.
2102
+
2103
+ <div>URI:
2104
+ <a href="http://www.example.com"
2105
+ class="url">http://www.example.com</a>
2106
+ </div>
2107
+
2108
+ 9.65. <workgroup>
2109
+
2110
+ This element does not add any direct output to HTML.
2111
+
2112
+ 9.66. <xref>
2113
+
2114
+ This element is rendered as an HTML <a> element containing an
2115
+ appropriate local link as the "href" attribute. The value of the
2116
+ "href" attribute is taken from the "target" attribute, prepended by
2117
+ "#". The <a> element generated will have class "xref". The contents
2118
+ of the <a> element are the value of the "derivedContent" attribute.
2119
+ If the "format" attribute has the value "default", and the "target"
2120
+ attribute points to a <reference> or <referencegroup> element, then
2121
+ the generated <a> element is surrounded by square brackets in the
2122
+ output.
2123
+
2124
+ <a class="xref" href="#target">Table 2</a>
2125
+
2126
+ or
2127
+
2128
+
2129
+
2130
+ Hildebrand & Hoffman Informational [Page 38]
2131
+
2132
+ RFC 7992 HTML for RFCs December 2016
2133
+
2134
+
2135
+ [<a class="xref" href="#RFC1234">RFC1234</a>]
2136
+
2137
+ 9.67. <svg xmlns='http://www.w3.org/2000/svg'>
2138
+
2139
+ This element is rendered as part of the <artwork> element. The
2140
+ "xmlns='http://www.w3.org/2000/svg'" namespace declaration should be
2141
+ included, and the SVG should be serialized as well-formed XML, even
2142
+ for tags that would otherwise not need closing in HTML5.
2143
+
2144
+ 10. Security Considerations
2145
+
2146
+ Since RFCs are sometimes exchanged outside the normal Web sandboxing
2147
+ mechanism (such as using the "rsync" program to a mirror site) then
2148
+ loaded from a local file, more care must be taken with the HTML than
2149
+ is ordinary on the web.
2150
+
2151
+ 11. References
2152
+
2153
+ 11.1. Normative References
2154
+
2155
+ [BCP14] Bradner, S., "Key words for use in RFCs to Indicate
2156
+ Requirement Levels", BCP 14, RFC 2119, March 1997,
2157
+ <https://www.rfc-editor.org/info/bcp14>.
2158
+
2159
+ [RFC2397] Masinter, L., "The "data" URL scheme", RFC 2397,
2160
+ DOI 10.17487/RFC2397, August 1998,
2161
+ <https://www.rfc-editor.org/info/rfc2397>.
2162
+
2163
+ [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO
2164
+ 10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November
2165
+ 2003, <https://www.rfc-editor.org/info/rfc3629>.
2166
+
2167
+ [RFC5646] Phillips, A., Ed. and M. Davis, Ed., "Tags for Identifying
2168
+ Languages", BCP 47, RFC 5646, DOI 10.17487/RFC5646,
2169
+ September 2009, <https://www.rfc-editor.org/info/rfc5646>.
2170
+
2171
+ [RFC7322] Flanagan, H. and S. Ginoza, "RFC Style Guide", RFC 7322,
2172
+ DOI 10.17487/RFC7322, September 2014,
2173
+ <https://www.rfc-editor.org/info/rfc7322>.
2174
+
2175
+ [RFC7991] Hoffman, P., "The "xml2rfc" Version 3 Vocabulary",
2176
+ RFC 7991, DOI 10.17487/RFC7991, December 2016,
2177
+ <https://www.rfc-editor.org/info/rfc7991>.
2178
+
2179
+ [RFC7993] Flanagan, H., "Cascading Style Sheets (CSS) Requirements
2180
+ for RFCs", RFC 7993, DOI 10.17487/RFC7993, December 2016,
2181
+ <https://www.rfc-editor.org/info/rfc7993>.
2182
+
2183
+
2184
+
2185
+
2186
+ Hildebrand & Hoffman Informational [Page 39]
2187
+
2188
+ RFC 7992 HTML for RFCs December 2016
2189
+
2190
+
2191
+ [W3C.REC-CSS2-20110607]
2192
+ Bos, B., Celik, T., Hickson, I., and H. Lie, "Cascading
2193
+ Style Sheets Level 2 Revision 1 (CSS 2.1) Specification",
2194
+ World Wide Web Consortium Recommendation REC-
2195
+ CSS2-20110607, June 2011,
2196
+ <http://www.w3.org/TR/2011/REC-CSS2-20110607>.
2197
+
2198
+ [W3C.REC-html5-20141028]
2199
+ Hickson, I., Berjon, R., Faulkner, S., Leithead, T.,
2200
+ Navara, E., O'Connor, T., and S. Pfeiffer, "HTML5", World
2201
+ Wide Web Consortium Recommendation REC-html5-20141028,
2202
+ October 2014,
2203
+ <http://www.w3.org/TR/2014/REC-html5-20141028>.
2204
+
2205
+ 11.2. Informative References
2206
+
2207
+ [HCARD] Celik, T., "hCard 1.0", 2015,
2208
+ <http://microformats.org/wiki/hcard>.
2209
+
2210
+ [RFC-STYLE]
2211
+ RFC Editor, "Style Guide",
2212
+ <https://www.rfc-editor.org/styleguide/>.
2213
+
2214
+ [RFC6949] Flanagan, H. and N. Brownlee, "RFC Series Format
2215
+ Requirements and Future Development", RFC 6949, May 2013.
2216
+
2217
+ This is a primary reference work.
2218
+
2219
+ [RFC7990] Flanagan, H., "RFC Format Framework", RFC 7990,
2220
+ DOI 10.17487/RFC7990, December 2016,
2221
+ <https://www.rfc-editor.org/info/rfc7990>.
2222
+
2223
+ [RFC7998] Hoffman, P. and J. Hildebrand, ""xml2rfc" Version 3
2224
+ Preparation Tool Description", RFC 7998,
2225
+ DOI 10.17487/RFC7998, December 2016,
2226
+ <https://www.rfc-editor.org/info/rfc7998>.
2227
+
2228
+ [W3C.WD-css3-page-20130314]
2229
+ Grant, M., Etemad, E., Lie, H., and S. Sapin, "CSS Paged
2230
+ Media Module Level 3", World Wide Web Consortium WD WD-
2231
+ css3-page-20130314, March 2013,
2232
+ <http://www.w3.org/TR/2013/WD-css3-page-20130314>.
2233
+
2234
+ Appendix A. IAB Members at the Time of Approval
2235
+
2236
+ The IAB members at the time this memo was approved were (in
2237
+ alphabetical order):
2238
+
2239
+
2240
+
2241
+
2242
+ Hildebrand & Hoffman Informational [Page 40]
2243
+
2244
+ RFC 7992 HTML for RFCs December 2016
2245
+
2246
+
2247
+ o Jari Arkko
2248
+
2249
+ o Ralph Droms
2250
+
2251
+ o Ted Hardie
2252
+
2253
+ o Joe Hildebrand
2254
+
2255
+ o Russ Housley
2256
+
2257
+ o Lee Howard
2258
+
2259
+ o Erik Nordmark
2260
+
2261
+ o Robert Sparks
2262
+
2263
+ o Andrew Sullivan
2264
+
2265
+ o Dave Thaler
2266
+
2267
+ o Martin Thomson
2268
+
2269
+ o Brian Trammell
2270
+
2271
+ o Suzanne Woolf
2272
+
2273
+ Appendix B. Acknowledgments
2274
+
2275
+ Heather Flanangan was an early coauthor of this document and helped
2276
+ its formation. The authors gratefully acknowledge the contributions
2277
+ of: Patrick Linskey and the members of the RFC Format Design Team
2278
+ (Nevil Brownlee (ISE), Tony Hansen, Ted Lemon, Julian Reschke, Adam
2279
+ Roach, Alice Russo, Robert Sparks (Tools Team liaison), and Dave
2280
+ Thaler).
2281
+
2282
+ Authors' Addresses
2283
+
2284
+ Joe Hildebrand (editor)
2285
+ Mozilla
2286
+
2287
+ Email: joe-ietf@cursive.net
2288
+
2289
+
2290
+ Paul Hoffman
2291
+ ICANN
2292
+
2293
+ Email: paul.hoffman@icann.org
2294
+
2295
+
2296
+
2297
+
2298
+ Hildebrand & Hoffman Informational [Page 41]