RFC 7992
HTML Format for RFCs
RFC 7992: HTML Format for RFCs 🎀
okay bestie, this is RFC 7992, HTML Format for RFCs 💖 It's an Informational doc from the Internet Architecture Board (IAB) stream, published in December 2016. J. Hildebrand, Ed. (from Mozilla) and P. Hoffman (from ICANN) wrote it, and it's on the ISSN 2070-1721 series. The header doesn't list anything it obsoletes or updates, so it stands on its own 🧚
Abstract ✨
so the big picture is that RFCs needed a glow-up 💅 The canonical format is moving from plain-text, ASCII-only docs to an XML format, and that XML gets rendered into several publication formats. This document defines the HTML format that gets rendered for an RFC or an Internet-Draft 🌸
Status of This Memo 🦋
ngl this part is kind of a formality, but it's important 🙈 This document is not an Internet Standards Track specification. It's published just for informational purposes ✨
It's a product of the Internet Architecture Board (IAB), and it holds information the IAB decided is worth keeping on the permanent record. It reflects the consensus of the IAB. Anything the IAB approves for publication isn't a candidate for any level of Internet Standard, so check Section 2 of RFC 7841 if you want the details 💜
For the current status, any errata, and how to send feedback, go to http://www.rfc-editor.org/info/rfc7992 🌈
Copyright Notice 🎀
Copyright (c) 2016 IETF Trust and the persons named as the document authors. All rights reserved 💖
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) as they're in effect on the publication date. Please actually read those, bestie, because they spell out your rights and restrictions for this document 🫶
Table of Contents 📚
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4
2. Requirements for the HTML Format . . . . . . . . . . . . . . 5
2.1. Requirements for Accessibility . . . . . . . . . . . . . 6
3. HTML Version . . . . . . . . . . . . . . . . . . . . . . . . 7
4. HTML Syntax . . . . . . . . . . . . . . . . . . . . . . . . . 7
5. Common Items . . . . . . . . . . . . . . . . . . . . . . . . 8
5.1. IDs . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
5.2. Pilcrows . . . . . . . . . . . . . . . . . . . . . . . . 8
6. Front Matter . . . . . . . . . . . . . . . . . . . . . . . . 9
6.1. DOCTYPE . . . . . . . . . . . . . . . . . . . . . . . . . 9
6.2. Root Element . . . . . . . . . . . . . . . . . . . . . . 9
6.3. <head> Element . . . . . . . . . . . . . . . . . . . . . 9
6.3.1. Charset Declaration . . . . . . . . . . . . . . . . . 9
6.3.2. Document Title . . . . . . . . . . . . . . . . . . . 10
6.3.3. Document Metadata . . . . . . . . . . . . . . . . . . 10
6.3.4. Link to XML Source . . . . . . . . . . . . . . . . . 10
6.3.5. Link to License . . . . . . . . . . . . . . . . . . . 10
6.3.6. Style . . . . . . . . . . . . . . . . . . . . . . . . 11
6.3.7. Links . . . . . . . . . . . . . . . . . . . . . . . . 11
6.4. Page Headers and Footers . . . . . . . . . . . . . . . . 12
6.5. Document Information . . . . . . . . . . . . . . . . . . 13
6.6. Table of Contents . . . . . . . . . . . . . . . . . . . . 14
7. Main Body . . . . . . . . . . . . . . . . . . . . . . . . . . 14
8. Back Matter . . . . . . . . . . . . . . . . . . . . . . . . . 14
8.1. Index . . . . . . . . . . . . . . . . . . . . . . . . . . 14
8.1.1. Index Contents . . . . . . . . . . . . . . . . . . . 15
8.1.2. Index Letters . . . . . . . . . . . . . . . . . . . . 15
8.1.3. Index Items . . . . . . . . . . . . . . . . . . . . . 16
8.1.4. Index Subitems . . . . . . . . . . . . . . . . . . . 16
8.2. Authors' Addresses Section . . . . . . . . . . . . . . . 17
8.3. Document Information . . . . . . . . . . . . . . . . . . 18
9. Elements . . . . . . . . . . . . . . . . . . . . . . . . . . 18
9.1. <abstract> . . . . . . . . . . . . . . . . . . . . . . . 18
9.2. <address> . . . . . . . . . . . . . . . . . . . . . . . . 19
9.3. <annotation> . . . . . . . . . . . . . . . . . . . . . . 19
9.4. <area> . . . . . . . . . . . . . . . . . . . . . . . . . 19
9.5. <artwork> . . . . . . . . . . . . . . . . . . . . . . . . 20
9.5.1. Text Artwork . . . . . . . . . . . . . . . . . . . . 20
9.5.2. SVG Artwork . . . . . . . . . . . . . . . . . . . . . 20
9.5.3. Other Artwork . . . . . . . . . . . . . . . . . . . . 21
9.6. <aside> . . . . . . . . . . . . . . . . . . . . . . . . . 21
9.7. <author> . . . . . . . . . . . . . . . . . . . . . . . . 21
9.7.1. Authors in Document Information . . . . . . . . . . . 22
9.7.2. Authors of This Document . . . . . . . . . . . . . . 22
9.7.3. Authors of References . . . . . . . . . . . . . . . . 24
9.8. <back> . . . . . . . . . . . . . . . . . . . . . . . . . 24
9.9. <bcp14> . . . . . . . . . . . . . . . . . . . . . . . . . 25
9.10. <blockquote> . . . . . . . . . . . . . . . . . . . . . . 25
9.11. <boilerplate> . . . . . . . . . . . . . . . . . . . . . . 26
9.12. <br> . . . . . . . . . . . . . . . . . . . . . . . . . . 26
9.13. <city> . . . . . . . . . . . . . . . . . . . . . . . . . 26
9.14. <code> . . . . . . . . . . . . . . . . . . . . . . . . . 26
9.15. <country> . . . . . . . . . . . . . . . . . . . . . . . . 26
9.16. <cref> . . . . . . . . . . . . . . . . . . . . . . . . . 27
9.17. <date> . . . . . . . . . . . . . . . . . . . . . . . . . 27
9.18. <dd> . . . . . . . . . . . . . . . . . . . . . . . . . . 27
9.19. <displayreference> . . . . . . . . . . . . . . . . . . . 27
9.20. <dl> . . . . . . . . . . . . . . . . . . . . . . . . . . 27
9.21. <dt> . . . . . . . . . . . . . . . . . . . . . . . . . . 27
9.22. <em> . . . . . . . . . . . . . . . . . . . . . . . . . . 28
9.23. <email> . . . . . . . . . . . . . . . . . . . . . . . . . 28
9.24. <eref> . . . . . . . . . . . . . . . . . . . . . . . . . 28
9.25. <figure> . . . . . . . . . . . . . . . . . . . . . . . . 28
9.26. <front> . . . . . . . . . . . . . . . . . . . . . . . . . 28
9.27. <iref> . . . . . . . . . . . . . . . . . . . . . . . . . 29
9.28. <keyword> . . . . . . . . . . . . . . . . . . . . . . . . 29
9.29. <li> . . . . . . . . . . . . . . . . . . . . . . . . . . 29
9.30. <link> . . . . . . . . . . . . . . . . . . . . . . . . . 29
9.31. <middle> . . . . . . . . . . . . . . . . . . . . . . . . 29
9.32. <name> . . . . . . . . . . . . . . . . . . . . . . . . . 29
9.33. <note> . . . . . . . . . . . . . . . . . . . . . . . . . 30
9.34. <ol> . . . . . . . . . . . . . . . . . . . . . . . . . . 30
9.34.1. Percent Styles . . . . . . . . . . . . . . . . . . . 30
9.34.2. Standard Styles . . . . . . . . . . . . . . . . . . 30
9.35. <organization> . . . . . . . . . . . . . . . . . . . . . 31
9.36. <phone> . . . . . . . . . . . . . . . . . . . . . . . . . 31
9.37. <postal> . . . . . . . . . . . . . . . . . . . . . . . . 31
9.38. <postalLine> . . . . . . . . . . . . . . . . . . . . . . 32
9.39. <refcontent> . . . . . . . . . . . . . . . . . . . . . . 32
9.40. <reference> . . . . . . . . . . . . . . . . . . . . . . . 33
9.41. <referencegroup> . . . . . . . . . . . . . . . . . . . . 33
9.42. <references> . . . . . . . . . . . . . . . . . . . . . . 34
9.43. <region> . . . . . . . . . . . . . . . . . . . . . . . . 34
9.44. <relref> . . . . . . . . . . . . . . . . . . . . . . . . 35
9.44.1. displayFormat='of' . . . . . . . . . . . . . . . . . 35
9.44.2. displayFormat='comma' . . . . . . . . . . . . . . . 35
9.44.3. displayFormat='parens' . . . . . . . . . . . . . . . 36
9.44.4. displayFormat='bare' . . . . . . . . . . . . . . . . 36
9.45. <rfc> . . . . . . . . . . . . . . . . . . . . . . . . . . 37
9.46. <section> . . . . . . . . . . . . . . . . . . . . . . . . 37
9.47. <seriesInfo> . . . . . . . . . . . . . . . . . . . . . . 37
9.48. <sourcecode> . . . . . . . . . . . . . . . . . . . . . . 38
9.49. <street> . . . . . . . . . . . . . . . . . . . . . . . . 38
9.50. <strong> . . . . . . . . . . . . . . . . . . . . . . . . 38
9.51. <sub> . . . . . . . . . . . . . . . . . . . . . . . . . . 38
9.52. <sup> . . . . . . . . . . . . . . . . . . . . . . . . . . 38
9.53. <t> . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
9.54. <table> . . . . . . . . . . . . . . . . . . . . . . . . . 39
9.55. <tbody> . . . . . . . . . . . . . . . . . . . . . . . . . 39
9.56. <td> . . . . . . . . . . . . . . . . . . . . . . . . . . 39
9.57. <tfoot> . . . . . . . . . . . . . . . . . . . . . . . . . 39
9.58. <th> . . . . . . . . . . . . . . . . . . . . . . . . . . 39
9.59. <thead> . . . . . . . . . . . . . . . . . . . . . . . . . 39
9.60. <title> . . . . . . . . . . . . . . . . . . . . . . . . . 39
9.61. <tr> . . . . . . . . . . . . . . . . . . . . . . . . . . 39
9.62. <tt> . . . . . . . . . . . . . . . . . . . . . . . . . . 40
9.63. <ul> . . . . . . . . . . . . . . . . . . . . . . . . . . 40
9.64. <uri> . . . . . . . . . . . . . . . . . . . . . . . . . . 40
9.65. <workgroup> . . . . . . . . . . . . . . . . . . . . . . . 40
9.66. <xref> . . . . . . . . . . . . . . . . . . . . . . . . . 40
9.67. <svg xmlns='http://www.w3.org/2000/svg'> . . . . . . . . 41
10. Security Considerations . . . . . . . . . . . . . . . . . . . 41
11. References . . . . . . . . . . . . . . . . . . . . . . . . . 41
11.1. Normative References . . . . . . . . . . . . . . . . . . 41
11.2. Informative References . . . . . . . . . . . . . . . . . 42
IAB Members at the Time of Approval . . . . . . . . . . . . . . . 43
Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 43
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 431. Introduction 🦋
okay so [RFC7990] is the doc that explains how the RFC Series is changing, and one of the changes is that the RFC Editor will publish a non-canonical HTML version of RFCs 💅
This document describes the HTML format that will be one of the publication formats for the RFC Series. It defines a strict subset of HTML that's made for RFC Series documents ✨ The visual layout is handled by a cascading style sheet (CSS) [W3C.REC-CSS2-20110607]. The CSS gets included in the HTML file, but it's described in [RFC7993] 🎀
the details here (especially the vocabularies) are expected to change as people get experience building the new publishing toolsets 🌸 Revised documents will be published to capture those changes as the toolsets get finished. Other implementers must not expect those changes to stay backwards compatible with what's described in this document 🙈
2. Requirements for the HTML Format ✨
okay bestie, this section is the design wishlist for the HTML format 🧚 It builds on the requirements in [RFC6949], and the prep tool in [RFC7998] already handles a lot of this for you 💅
- The HTML has to render correctly on a list of browser versions that the RFC Editor will keep up to date outside of this document. 🌸
- The format will consist of a subset of HTML deemed to be widely implemented by common browsers at the time the specification is created, likely to continue to be widely implemented, and unlikely to cause security issues. This will maximize the chances that future HTML renderers (such as new web browsers) will continue to produce readable text from the HTML format without the format needing to be changed frequently. 🦋
- These requirements are expected to change in the future to reflect the expectation that HTML rendering will be required for current versions of browsers and platforms, while ideally continuing to render correctly on recent versions of those browsers. ⭐
- The HTML documents from the RFC Editor or Internet-Drafts directory may be re-rendered from the canonical XML format in the future to ensure the ongoing readability of the documents. The intent is that any re-rendering would be due to exceptional circumstances rather than for minor annoyances. 🫶
- The HTML must display adequately in at least one text-based browser. Some consumers of the RFC Series can only access the documents on text-based terminals. 💻
- The HTML document will be self-contained, without requiring external files for images, CSS, JavaScript, or the like. This will allow the HTML file to be moved over various non-HTTP transports (such as email, FTP, and rsync) without breakage. 📬
- JavaScript will be supported on a limited basis. It will not be permitted to overwrite or change any text present in the rendered HTML. It may, on a limited basis, add additional text that provides post-publication metadata or pointers if warranted. All such text will be clearly marked as additional. 🧃
- The HTML document will allow easy local override of the default CSS formatting. This will allow users who have a different visual style that they prefer to make RFCs display with that style without having to alter the contents of the HTML document. This might also be valuable for allowing people with specific accessibility needs to use a customized CSS. 🎀
- HTML tags in documents will rarely have attributes whose only purpose is to affect the rendered styling, and those will only be used if it would not be possible to specify that styling in a CSS. No such attributes are known at this time. 🙈
- Both user-defined and auto-generated anchors must be supported and linkable, with user-defined anchors appearing in an "id" attribute. Auto-generated anchors will be generated for every heading, paragraph, and so on, not just those that do not have user-defined anchors. User-defined anchors may, and auto-generated anchors will, appear next to paragraphs, figures, tables, blockquotes, and section titles. 🔗
- All sections, subsections, figures, and paragraphs should have stable numbered link anchors. Additionally, anchors expressed in the source XML should be exposed as anchors in the HTML output as well. 🧷
- The HTML must make it easy to separate sections along with all of their subsections into separate files. This will make creating EPUB documents easier in the future. 📚
- The HTML produced for Internet-Drafts will differ from that produced by the RFC Editor due to differences in the output from the prep tool. 🍓
- The abstract must be marked up or tagged in a way that popular search engines will extract it as a summary. 🔍
2.1. Requirements for Accessibility
- Normative information must be easily accessible to the following consumers:
- People with impaired vision, including those that use large fonts and those that use screen readers 👀
- People with difficulty distinguishing between colors 🌈
- People who use devices with small screens, such as cell phones 📱
- Specific instances where goals for accessibility are important in the design choices of the format have been called out in the text. 💜
- Note: designing for these consumers does not preclude the use of features they cannot use, but it does require that key semantic data not be lost when read using the tools and settings that are required by a given constituency. 🫶
3. HTML Version
okay so the RFC Editor will periodically decide which version of the HTML specification the tools generating this format reference. The starting version is the one defined in [W3C.REC-html5-20141028], commonly known as "HTML5". 🌟 The HTML specification already mandates several of the syntax and structure rules described in this document, but they're called out here anyway for emphasis 📣
4. HTML Syntax
the processor that emits HTML from the XML source will follow these rules, no cap 💅
- The HTML output is encoded as UTF-8, as specified in [RFC3629]. 🔤
- The document is valid HTML. ✅
- Double quotes (U+0022 QUOTATION MARK: ") are used to quote attribute values unless the HTML specification forbids quoting a particular attribute. 💬
- Each logical line is terminated solely with a
\n(U+000A: LINE FEED), otherwise known as "Unix-style" line endings. 🐧 - Code points below (U+0020: SPACE) or character entity references that generate them (e.g.
	), other than (U+000A: LINE FEED) may not be used. Note: this rule explicitly forbids\t(U+0009: CHARACTER TABULATION),\f(U+000C: FORM FEED), and\r(U+000D: CARRIAGE RETURN) from appearing in the HTML output. 🚫 - Comments in the source XML, if any, will not be copied into the HTML. 🤫
- The HTML output will be pretty-printed, using whatever consistent rules are deemed best by the developers of the HTML production tools. ✨
Note: none of these rules affect the rendered output of the HTML, but they are intended to increase the chance that text comparison tools (e.g., "diff") that operate on the HTML output are easier to write. 🧠
5. Common Items
this section lists the items that show up across multiple parts of the HTML document, so you'll see them everywhere 👑
5.1. IDs
HTML elements that are generated from XML elements that include an "anchor" attribute will use the value of the "anchor" attribute as the value of the "id" attribute of the corresponding HTML element. The prep tool produces XML with "anchor" attributes in all elements that need them. Some HTML constructs (such as <section>) will use multiple instances of these identifiers. 🆔
5.2. Pilcrows
each paragraph, artwork, or sourcecode segment outside of a <figure> or <table> element will be appended with a space and a "pilcrow" (U+00B6: PILCROW SIGN), otherwise known as a "paragraph sign". 🦶 For clarity in ASCII renderings of this document, pilcrows are rendered here as "¶". The pilcrow gets linked to the "id" attribute on the XML entity it belongs to, using an <a> element of class "pilcrow". Here's how it looks:
<p id="s-1.1-1">
Some paragraph text. <a class="pilcrow" href="#s-1.1-1">¶</a>
</p>The pilcrow will normally be invisible unless the element it is attached to is moused over. The pilcrow will be surrounded by a link that points to the element it is attached to. 👻
Pilcrows are never included inside a <table> or <figure> element, since the figure number or table number serves as an adequate link target. 🖼️
Elements that might otherwise contain a pilcrow do not get marked with a pilcrow if they contain one or more child elements that are marked with a pilcrow. For example:
<blockquote id="s-1.2-1">
<p id="s-1.2-2">Four score and seven years ago our fathers brought
forth on this continent, a new nation, conceived in Liberty, and
dedicated to the proposition that all men are created equal.
<a href="#s-1.2-2" class="pilcrow">¶</a></p>
<!-- NO pilcrow here -->
</blockquote>6. Front Matter
the front matter holds the processing info, metadata, and styling that apply to the document as a whole 💖 This section describes HTML that isn't necessarily a direct transform from the XML format. For more details on each of the tags that generate content in this section, see Section 9. 🧁
6.1. DOCTYPE
the DOCTYPE is "html", which declares that the document is compliant with HTML5. The document will start with exactly this string:
<!DOCTYPE html>6.2. Root Element
the root element is <html>. It has a "lang" attribute, whose value is a language tag, as discussed in [RFC5646], that describes the natural language of the document. The language tag used is "en". 🇬🇧 The class of the <html> element gets copied verbatim from the XML <rfc> element's <front> element's <seriesInfo> element's "name" attributes (separated by spaces; see Section 2.47.3 of [RFC7991]). This lets CSS style RFCs and Internet-Drafts differently from one another, if needed 🎨
<html lang="en" class="RFC">6.3. <head> Element
the root <html> will contain a <head> element that holds the following elements, as needed 🧠
6.3.1. Charset Declaration
so browsers that load the HTML through a mechanism that doesn't provide a valid content-type or charset (like a local file system using a "file:" URL) still process it correctly, the HTML <head> element contains a <meta> element whose "charset" attribute value is "utf-8" 🔡
<meta charset="utf-8">6.3.2. Document Title
the contents of the <title> element from the XML source get placed inside an HTML <title> element in the header. 🏷️
6.3.3. Document Metadata
the following <meta> elements will be included 📝
- author - one each for the each of the "fullname"s and "asciiFullname"s of all of the
<author>s from the<front>of the XML source - description - the
<abstract>from the XML source - generator - the name and version number of the software used to create the HTML
- keywords - comma-separated
<keyword>s from the XML source
For example:
<meta name="author" content="Joe Hildebrand">
<meta name="author" content="JOE HILDEBRAND">
<meta name="author" content="Heather Flanagan">
<meta name="description" content="This document defines...">
<meta name="generator" content="xmljade v0.2.4">
<meta name="keywords" content="html,css,rfc">Note: the HTML <meta> tag does not contain a closing slash. 🙅♀️
6.3.4. Link to XML Source
the <head> element contains a <link> tag, with "rel" attribute of "alternate", "type" attribute of "application/rfc+xml", and "href" attribute pointing to the prepared XML source that was used to generate this document. 🔗
<link rel="alternate" type="application/rfc+xml" href="source.xml">6.3.5. Link to License
the <head> element contains a <link> tag, with "rel" attribute of "license" and "href" attribute pointing to the an appropriate copyright license for the document. 📜
<link rel="license"
href="https://trustee.ietf.org/trust-legal-provisions.html">6.3.6. Style ✨
okay so the <head> element has embedded CSS inside a <style> element 🎨 The RFC Editor sets the styles in that sheet so every document looks consistent, following the best practices of the day 💅
bestie, individual style attributes should not be used in the main body of the document. That's how we keep things consistent 🫶
Different readers want different formatting when they read the HTML versions of RFCs, so the <head> also has a <link> to a stylesheet named "rfc-local.css" that lives in the same directory as the HTML file 🦋 Any formatting in that linked sheet overrides the formatting in the embedded one. Like this:
<style>
body {}
...
</style>
<link rel="stylesheet" type="text/css" href="rfc-local.css">6.3.7. Links 🔗
every <link> element from the XML source gets copied into the HTML header 🌸 Also, heads up: the HTML <link> element does not have a closing slash, so don't add one 🙈
6.4. Page Headers and Footers 🖨️
so, to make printing easier for HTML renderers that implement [W3C.WD-css3-page-20130314], a hidden HTML <table> with class "ears" gets added at the very start of the HTML <body> 🧚 It contains a <thead> and a <tfoot>, and each of those holds one <tr>, which holds three <td> tags with the classes "left", "center", and "right", in that order 💜
The <thead> is the top of the page and the <tfoot> is the bottom. The string [Page] works as a placeholder for the page number. In practice it must always sit in the <tfoot>'s right <td>, and no control over how the page number is formatted is implied ✨
<table class="ears">
<thead>
<tr>
<td class="left">Internet-Draft</td>
<td class="center">HTML RFC</td>
<td class="right">March 2016</td>
</tr>
</thead>
<tfoot>
<tr>
<td class="left">Hildebrand</td>
<td class="center">Expires September 2, 2016</td>
<td class="right">[Page]</td>
</tr>
</tfoot>
</table>6.5. Document Information 📇
info about the document as a whole shows up as the very first child of the HTML <body>, wrapped in an HTML <dl> with id="identifiers" 🌈 The defined terms in that definition list are "Workgroup:", "Series:", "Status:", "Published:", and "Author:" or "Authors:" (whichever fits) 🎀 Here's how it looks:
<dl id="identifiers">
<dt>Workgroup:</dt>
<dd class="workgroup">rfc-interest</dd>
<dt>Series:</dt>
<dd class="series">Internet-Draft</dd>
<dt>Status:</dt>
<dd class="status">Informational</dd>
<dt>Published:</dt>
<dd><time datetime="2014-10-25"
class="published">2014-10-25</time></dd>
<dt>Authors:</dt>
<dd class="authors">
<div class="author">
<span class="initial">J.</span>
<span class="surname">Hildebrand</span>
(<span class="organization">Cisco Systems, Inc.</span>)
<span class="editor">Ed.</span>
</div>
<div class="author">
<span class="initial">H.</span>
<span class="surname">Flanagan</span>
(<span class="organization">RFC Editor</span>)
</div>
</dd>
</dl>6.6. Table of Contents 🗂️
the table of contents shows up after the boilerplate, but only if the XML's <rfc> element has a "tocInclude" attribute set to "true" 💖 An HTML <h2> containing the text "Table of Contents" comes first, followed by a <nav> element holding a <ul> for each depth of the section hierarchy. Every section gets a <li> with links that use the section number (from the "pn" attribute) and the name (from the "slugifiedName" attribute of the <name> child element) 🦋 Each <nav>, <ul>, and <li> gets the class "toc". Like, obsessed with how organized this is 😭
For example:
<h2 id="toc">Table of Contents</h2>
<nav class="toc">
<ul class="toc">
<li class="toc">
<a href="s-1">1</a>. <a href="n-introduction">Introduction</a>
</li>
<ul class="toc">
<li class="toc">
<a href="s-1.1">1.1</a>. <a href="n-sub-intro">Sub Intro</a>
</li>
...7. Main Body 🌸
the main body of the HTML document gets processed according to the rules in Section 9 🧚
8. Back Matter 🎀
the back matter of the HTML document includes an index (if one gets generated), info about the authors, and further info about the document itself 💜
8.1. Index 📚
the index gets produced as dictated by the RFC Editor's Style Guide [RFC-STYLE], and only if the XML document's <rfc> element has an "indexInclude" attribute set to "true" AND there is one or more <iref> elements in the document. Both conditions, bestie 🙈
8.1.1. Index Contents 🔤
the index section starts with an <h2> heading containing the text "Index", followed by links to each of the lettered parts of the index 🌈 Links are not generated for letters that don't occur as the first letter of an index item, so no empty letters 💅
For example:
<h2>Index</h2>
<div class="index">
<div class="indexIndex">
<a href="#rfc.index.C">C</a>
<a href="#rfc.index.P">P</a>
</div>
...8.1.2. Index Letters 🔠
each index letter is followed by a <ul> tag holding a <li> for every first letter that shows up in the index 🦋 That <li> has the class "indexChar" and contains an <a> tag whose id is the index letter, plus an "href" attribute that points back to itself. The <li> also includes a <ul> that will hold the index items ✨
For example:
<ul>
<li class="indexChar">
<a href="#rfc.index.C" id="rfc.index.C">C</a>
<ul>
<!-- items go here -->
</ul>
</li>
...8.1.3. Index Items 🎯
each index item can point to multiple <iref> elements, all sharing the same item attribute 💖 Each index item is a <li> tag of class "indexItem" containing a <span> of class "irefItem" for the item text, and a <span> of class "irefRefs" for the generated references (if there's at least one reference to the item that doesn't have a subitem) 🌸 Each generated reference is an <a> tag holding the section number where the <iref> is found, with an "href" attribute pointing to the "irefid" attribute of that <iref> element in the XML document. If the primary attribute of the <iref> element is "true", the <a> in the HTML gets the class "indexPrimary". Commas can separate the generated references 🍓
For example:
<li class="indexItem">
<span class="irefItem">Bullets</span>
<span class="irefRefs">
<a class="indexPrimary" href="#s-Bullets-1">2</a>,
<a href="#s-Bullets-2">2</a>
</span>
<!-- subitems go here -->
</li>
...8.1.4. Index Subitems 🧩
if an index item has at least one subitem, that item's <li> contains a <ul>, with one <li> per subitem of class "indexSubItem" 🧚 The format for each subitem is similar to items, except the first <span> gets the class "irefSubItem" instead 💜
For example:
<ul>
<li class="indexSubItem">
<span class="irefSubItem">Ordered</span>
<span class="irefRefs">
<a href="#s-Bullets-Ordered-1">2</a>
</span>
</li>
</ul>
...8.2. Authors' Addresses Section 💌
at the end of the document, the author info goes inside an HTML <section> element whose "id" attribute is "author-addresses" 🫶 The class names of the tags inside have been chosen to match the class names in [HCARD], which is very much a "work well with others" moment 🌈
The info for each author gets separated by an HTML <hr> element with class "addr" 🦋
<section id="author-addresses">
<h2>
<a class="selfRef" href="#author-addresses">
Authors' Addresses
</a>
</h2>
<address class="vcard">
<div class="nameRole"><span class="fn">Joe Hildebrand</span>
(<span class="role">editor</span>)</div>
<div class="org">Cisco Systems, Inc.</div>
</address>
<hr class="addr">
<address class="vcard">
<div class="nameRole"><span class="fn">Heather Flanagan</span>
(<span class="role">editor</span>)</div>
<div class="org">RFC Series Editor</div>
</address>
</section>8.3. Document Information 🗃️
a few bits of metadata that matter less to most readers come after the author info. They're gathered into a <div> of class "docInfo" 💅
The finalized time gets copied from the <rfc> element's "prepTime" attribute. The rendered time is the time this HTML was generated ⏰
For example:
<div class="docInfo">
<span class="finalized">
Finalized: <time
datetime="2015-04-29T18:59:08Z">2015-04-29T18:59:08Z</time>
</span>
<span class="rendered">
Rendered: <time
datetime="2015-04-29T18:59:10Z">2015-04-29T18:59:10Z</time>
</span>
</div>9. Elements 🧁
this section describes how each of the XML elements from [RFC7991] gets rendered to HTML. Lots of the descriptions come with examples so you can see the rendering in action 👑
9.1. <abstract> 📝
the abstract is rendered in a similar way to a section with anchor="abstract" and <name>Abstract</name>, but without a section number 🌷
<section id="abstract">
<h2><a href="#abstract" class="selfRef">Abstract</a></h2>
<p id="s-abstract-1">This document defines...
<a href="#s-abstract-1" class="pilcrow">¶</a>
</p>
</section>9.2. <address> 🏡
this element is used in the Authors' Addresses section. It's rendered as an HTML <address> tag of class "vcard". If none of the descendant XML elements has an "ascii" attribute, the <address> tag includes the HTML rendering of each descendant XML element 💖
Otherwise, the <address> tag includes three things: an HTML <div> of class "ascii" (holding the HTML rendering of the ASCII variants of each descendant XML element), an HTML <div> of class "alternative-contact" (containing the text "Alternate contact information:"), and an HTML <div> of class "non-ascii" (holding the HTML rendering of the non-ASCII variants of each descendant XML element) 🌈
Note: the following example shows some ASCII equivalents that are the same as their nominal equivalents, just for clarity. Normally, the ASCII equivalents would not be included for these cases. 🙈
<address class="vcard">
<div class="ascii">
<div class="nameRole"><span class="fn">Joe Hildebrand</span>
(<span class="role">editor</span>)</div>
<div class="org">Cisco Systems, Inc.</div>
</div>
<div class="alternative-contact">
Alternate contact information:
</div>
<div class="non-ascii">
<div class="nameRole"><span class="fn">Joe Hildebrand</span>
(<span class="role">editor</span>)</div>
<div class="org">Cisco Systems, Inc.</div>
</div>
</address>9.3. <annotation> 💬
this element gets rendered as the text ", " (a comma and a space), followed by a <span> of class "annotation" at the end of a <reference> element. That <span> contains the appropriately transformed elements from the children of the <annotation> tag 🎀
<span class="annotation">Some <em>thing</em>.</span>9.4. <area> 🌙
not currently rendered to HTML, so nothing to see here, bestie 🫧
9.5. <artwork> ✨
Okay so artwork can be either inline text or SVG 🎨. If the artwork isn't inside a <figure> element, a pilcrow (Section 5.2) gets tacked on. Inside a <figure>, the figure title does the pilcrow's job instead 🫶. If "align" is "right", the CSS class "alignRight" gets added, and if "align" is "center", you get "alignCenter" 🎀.
9.5.1. Text Artwork
Text artwork gets rendered inside an HTML <pre> element, which is wrapped in a <div> so it matches the SVG stuff 💜. Heads up: CDATA blocks aren't a thing in HTML, so angle brackets and ampersands (i.e., <, >, and &) have to be escaped as <, >, and &, respectively 🙈.
The <div> gets the CSS classes "artwork", "art-text", and "art-" with the value of the type attribute tacked onto the end, if that attribute exists 🌸.
<div class="artwork art-text art-ascii-art" id="s-1-2">
<pre>
______________
< hello, world >
--------------
\ ^__^
\ (oo)\_______
(__)\ )\/\
||----w |
|| ||
</pre>
<a class="pilcrow" href="#s-1-2">¶</a>
</div>9.5.2. SVG Artwork
SVG artwork gets included inline 🦋. It's wrapped in a <div> with the CSS classes "artwork" and "art-svg".
If the SVG "artwork" element is a child of <figure> and the artwork is align="right", an empty HTML <span> element gets added directly after the <svg> element. That's so right alignment still works in HTML rendering engines that don't support the flex-box model 💅.
Note: the "alt" attribute of <artwork> isn't currently used for SVG. Instead, the <title> and <desc> tags inside the SVG do the job 🙈.
<div class="artwork art-svg" id="s-2-17">
<svg width="100" height="100" xmlns="http://www.w3.org/2000/svg">
<desc>Alt text here</desc>
<circle
cx="50" cy="50" r="40"
stroke="green" stroke-width="4" fill="yellow" />
</svg>
<a href="#s-2-17" class="pilcrow">¶</a>
</div>9.5.3. Other Artwork
Other artwork gets a "src" attribute that uses the "data" URI scheme defined in [RFC2397] 🌈. This kind of artwork is rendered in an HTML <img> element. Note: the HTML <img> element doesn't have a closing slash.
Note: such images aren't allowed in RFCs yet, even though the format supports them. A limited set of "data:" mediatypes for artwork may be allowed in the future ⭐.
<div class="artwork art-logo" id="s-2-58">
<img alt="IETF logo"
src="data:image/gif;charset=utf-8;base64,...">
<a class="pilcrow" href="#s-2-58">¶</a>
</div>9.6. <aside> 🧚
This element is rendered as an HTML <aside> element, with all of its child content transformed properly 💅.
<aside id="s-2.1-2">
<p id="s-2.1-2.1">
A little more than kin, and less than kind.
<a class="pilcrow" href="#s-2.1-2.1">¶</a>
</p>
</aside>9.7. <author> 👑
The <author> element shows up in several places in the output, and each place gets its own rendering 🍓.
9.7.1. Authors in Document Information
As seen in the Document Information at the beginning of the HTML, each document author is rendered as an HTML <div> tag of class "author" 🌸.
Inside the <div class="author"> tag, the author's initials and surname (or the fullname, if it exists and the others don't) get rendered in an HTML <div> tag of class "author-name". If the <author> contains "asciiInitials" and "asciiSurname" attributes, or an "asciiFullname" attribute, the author's name is rendered twice. The first one is the non-ASCII version, wrapped in an HTML <span> tag of class "non-ascii", followed by the ASCII version wrapped in an HTML <span> tag of class "ascii", all wrapped in parentheses 💖. If the <author> has a "role" attribute of "editor", the <div class="author-name"> also gets the text ", " (comma, space), followed by an HTML <span> tag of class "editor", which contains the text "Ed." 🫶.
If the <author> element contains an <organization> element, that's rendered inside the <div class="author"> HTML tag too ✨.
<div class="author">
<div class="author-name">
H. Flanagan,
<span class="editor">Ed.</span></div>
<div class="org">Test Org</div>
</div>
<div class="author">
<div class="author-name">
<span class="non-ascii">Hildebrand</span>
(<span class="ascii">HILDEBRAND</span>)
</div>
<div class="org">
<span class="non-ascii">Test Org</span>
(<span class="ascii">TEST ORG</span>)
</div>
</div>9.7.2. Authors of This Document
As seen in the Authors' Addresses section, at the end of the HTML, each document author is rendered into an HTML <address> element with the CSS class "vcard" 💜.
The HTML <address> element holds an HTML <div> with the CSS class "nameRole". That div contains an HTML <span> element with the CSS class "fn", which holds the value of the "fullname" attribute of the <author> XML element, and an HTML <span> element with the CSS class "role", which holds the value of the "role" attribute of the <author> XML element (if there is a role). Parentheses surround the <span class="role">, if it exists 🎀.
<address class="vcard">
<div class="nameRole">
<span class="fn">Joe Hildebrand</span>
(<span class="role">editor</span>)
</div>
...After the name, the <organization> and <address> child elements of the author get rendered inside the HTML <address> tag 🌈.
When the <author> element, or any of its descendant elements, has an attribute that starts with "ascii", all of the author information gets displayed twice. The first version is wrapped in an HTML <div> tag with the class "ascii". This version prefers the ASCII version of information, such as "asciiFullname", but falls back on the non-ASCII version if the ASCII version doesn't exist. The second version is wrapped in an HTML <div> tag with the class "non-ascii". This one prefers the non-ASCII version of information, such as "fullname", but falls back on the ASCII version if the non-ASCII version doesn't exist. Between these two HTML <div>s, a third <div> gets inserted, with the class "alternative-contact", containing the text "Alternate contact information:" 🧚.
<address class="vcard">
<div class="ascii">
<div class="nameRole">
<span class="fn">The ASCII name</span>
</div>
</div>
<div class="alternative-contact">
Alternate contact information:
</div>
<div class="non-ascii">
<div class="nameRole">
<span class="fn">The non-ASCII name</span>
(<span class="role">editor</span>)
</div>
</div>
</address>9.7.3. Authors of References
In the output generated from a reference element, author tags are rendered inside an HTML <span> element with the CSS class "refAuthor". See Section 4.8.6.2 of [RFC7322] for guidance on how author names are to appear 📚.
<span class="refAuthor">Flanagan, H.</span> and
<span class="refAuthor">N. Brownlee</span>9.8. <back> 🌸
If there is exactly one <references> child, render that child in a similar way to a <section>. If there are more than one <references> children, render a <section> whose name is "References", containing a <section> for each <references> child 💅.
After any <references> sections, each <section> child of <back> gets rendered as an appendix 🎀.
<section id="n-references">
<h2 id="s-2">
<a class="selfRef" href="#s-2">2.</a>
<a class="selfRef" href="#n-references">References</a>
</h2>
<section id="n-normative">
<h3 id="s-2.1">
<a class="selfRef" href="#s-2.1">2.1.</a>
<a class="selfRef" href="#n-normative">Normative</a>
</h3>
<dl class="reference"></dl>
</section>
<section id="n-informational">
<h3 id="s-2.2">
<a class="selfRef" href="#s-2.2">2.2.</a>
<a class="selfRef" href="#n-informational">Informational</a>
</h3>
<dl class="reference"></dl>
</section>
</section>
<section id="n-unimportant">
<h2 id="s-A">
<a class="selfRef" href="#s-A">Appendix A.</a>
<a class="selfRef" href="#n-unimportant">Unimportant</a>
</h2>
</section>9.9. <bcp14> 🔥
This element marks up words like MUST and SHOULD [BCP14] with an HTML <span> element with the CSS class "bcp14" 💜.
You <span class="bcp14">MUST</span> be joking.9.10. <blockquote> 💖
This element renders in a way similar to the HTML <blockquote> element. If there is a "cite" attribute, it gets copied to the HTML "cite" attribute. If there is a "quoteFrom" attribute, it's placed inside a <cite> element at the end of the quote, with an <a> element surrounding it (if there is a "cite" attribute), linking to the cited URL 🧚.
If the <blockquote> doesn't contain another element that gets a pilcrow (Section 5.2), a pilcrow gets added 🌈.
Note that the "—" at the beginning of the <cite> element should be a proper emdash, which is tricky to show in the display of the current format 🙈.
<blockquote id="s-1.2-1"
cite="http://...">
<p id="s-1.2-2">Four score and seven years ago our fathers
brought forth on this continent, a new nation, conceived
in Liberty, and dedicated to the proposition that all men
are created equal.
<a href="#s-1.2-2" class="pilcrow">¶</a>
</p>
<cite>— <a href="http://...">Abraham Lincoln</a></cite>
</blockquote>9.11. <boilerplate> 🎀
The Status of This Memo and the Copyright statement, together commonly referred to as the document boilerplate, appear after the Abstract. The children of the input <boilerplate> element are treated in a similar fashion to unnumbered sections 💅.
<section id="status-of-this-memo">
<h2 id="s-boilerplate-1">
<a href="#status-of-this-memo" class="selfRef">
Status of this Memo</a>
</h2>
<p id="s-boilerplate-1-1">This Internet-Draft is submitted in full
conformance with the provisions of BCP 78 and BCP 79.
<a href="#s-boilerplate-1-1" class="pilcrow">¶</a>
</p>
...9.12. <br> 🍓
This element is directly rendered as its HTML counterpart. Note: in HTML, <br> doesn't have a closing slash ✨.
9.13. <city> 🌈
This element is rendered as a <span> element with the CSS class "locality" 💜.
<span class="locality">Guilford</span>9.14. <code> 🙈
This element is rendered as a <span> element with the CSS class "postal-code" 🎀.
<span class="postal-code">GU16 7HF<span>9.15. <country> 🧚
This element is rendered as a <div> element with the CSS class "country-name" 🌸.
<div class="country-name">England</div>9.16. <cref> 💜
This element is rendered as a <span> element with the CSS class "cref". Any anchor is copied to the "id" attribute. If there is a source given, it's contained inside the "cref" <span> element, with another <span> element of class "crefSource" 🫶.
<span class="cref" id="crefAnchor">Just a brief comment
about something that we need to remember later.
<span class="crefSource">--life</span></span>9.17. <date> 🦋
This element is rendered as the HTML <time> element. If the "year", "month", or "day" attribute is included on the XML element, an appropriate "datetime" element will be generated in HTML 📅.
If this date is a child of the document's <front> element, it gets the CSS class "published". If this date is inside a <reference> element, it gets the CSS class "refDate" ✨.
<time datetime="2014-10" class="published">October 2014</time>9.18. <dd> 👑
This element is directly rendered as its HTML counterpart 💅.
9.19. <displayreference> 💖
Okay bestie, <displayreference> is the quiet one 🫶 It doesn't change the HTML output at all, but it's secretly working behind the scenes when <reference>, <referencegroup>, <relref>, and <xref> elements get generated ✨
9.20. <dl> 🎀
This one renders straight into its HTML counterpart, no drama 💅
If the hanging attribute is "false", add the "dlParallel" class, else add the "dlHanging" class.
If the spacing attribute is "compact", add the "dlCompact" class.
9.21. <dt> 🌸
Same deal here: it's rendered as its HTML counterpart 💕
9.22. <em> 🦋
Also rendered as its HTML counterpart, nothing extra going on 😌
9.23. <email> 💌
This element becomes an HTML <div> with the string "Email:" inside, plus an HTML <a> element. That <a> has its "href" set to the matching "mailto:" URI, a CSS class of "email", and the email address as its contents. If this is the ASCII version of the address, the "ascii" attribute is preferred over the element text, so ASCII really does get the spotlight 🫶
<div>
<span>Email:</span>
<a class="email" href="mailto:joe@example.com">joe@example.com</a>
</div>9.24. <eref> 🔗
This one becomes an HTML <a> element. Its "href" is the value of the "target" attribute, and it gets the CSS class "eref" ✨
<a href="https://..." class="eref">the text</a>9.25. <figure> 🖼️
This renders as the HTML <figure> element. Inside it you get the artwork or sourcecode, plus an HTML <figcaption> element. The <figcaption> wraps the figure number in an <a> element. If a name was given, it also gets another <a> with the CSS class "selfRef" wrapped around the figure name. Very organised, very iconic 👑
<figure id="f-1">
...
<figcaption>
<a href="#f-1">Figure 1.</a>
<a href="#n-it-figures" id="n-it-figures" class="selfRef">
It figures
</a>
</figcaption>
</figure>9.26. <front> 📜
Go check "Document Information" (Section 6.5) for everything about this one 💜
9.27. <iref> 🧚
This becomes an empty <> tag with the class "iref". Its "id" attribute is the <iref> element's "irefid" attribute, so it's basically a tiny glitter marker ✨
<span class="iref" id="s-Paragraphs-first-1"/>9.28. <keyword> 🏷️
Every <keyword> element dumps its text into the <meta> keywords in the document's header, separated by commas 🍓
<meta name="keywords" content="html,css,rfc">9.29. <li> 🌈
This is rendered as its HTML counterpart. The twist is that if none of the contained elements already has a pilcrow (Section 5.2) attached, a pilcrow gets added. Main character energy for list items 💅
<li id="s-2-7">Item <a href="#s-2-7" class="pilcrow">¶</a></li>9.30. <link> 🔗
This one is rendered as its HTML counterpart, but in the HTML header 🫶
9.31. <middle> 🌙
This element doesn't add any direct output to HTML. It just sits there looking pretty 🥹
9.32. <name> 🏷️
<name> is never rendered directly. It only shows up when you're looking at a parent element, like <figure>, <references>, <section>, or <table> 💭
9.33. <note> 📝
This is rendered like a <section> element, but with no section number and with the CSS class "note". If the "removeInRFC" attribute is set to "yes", the generated <div> also picks up the CSS class "rfcEditorRemove", which is basically a little "bye bye" tag for the RFC Editor 👋
<section id="s-note-1" class="note rfcEditorRemove">
<h2>
<a href="#n-editorial-note" class="selfRef">Editorial Note</a>
</h2>
<p id="s-note-1-1">
Discussion of this draft takes place...
<a href="#s-note-1-1" class="pilcrow">¶</a>
</p>
</section>9.34. <ol> 🔢
The output from an <ol> depends on the "style" attribute. If "spacing" is "compact", you get the CSS class "olCompact" added. The group attribute doesn't get copied over. Instead, the input XML should have start values added by a prep tool for every grouped <ol> element, so no drama there 🫶
9.34.1. Percent Styles 📊
If the style attribute includes the character "%", the output is a <dl> tag with the class "olPercent". Each contained <li> becomes a <dt>/<dd> pair, with the generated label in the <dt> and the contents of the <li> in the <dd> 💖
<dl class="olPercent">
<dt>Requirement xviii:</dt>
<dd>Wheels on a big rig</dd>
</dl>9.34.2. Standard Styles 📋
For every other style, you get an <ol> tag, and any "style" attribute gets turned into its equivalent HTML attribute ✨
<ol class="compact" type="I" start="18">
<li>Wheels on a big rig</li>
</ol>9.35. <organization> 🏢
This is rendered as an HTML <div> with the CSS class "org" 💜
If the element has the "ascii" attribute, the organization name shows up twice. First the non-ASCII version goes in an HTML <span> with the class "non-ascii". Then the ASCII version goes in an HTML <span> with the class "ascii", wrapped in parentheses. Double the name, double the iconic 💅
<div class="org">
<span class="non-ascii">Test Org</span>
(<span class="ascii">TEST ORG</span>)
</div>9.36. <phone> 📞
This becomes an HTML <div> containing the string "Phone:" (wrapped in a span), then an HTML <a> tag with the CSS class "tel" holding the phone number. That <a> gets an href with a matching "tel:" URI. Last, there's an HTML <span> with the CSS class "type" containing the string "VOICE" 🎧
<div>
<span>Phone:</span>
<a class="tel" href="tel:+1-720-555-1212">+1-720-555-1212</a>
<span class="type">VOICE</span>
</div>9.37. <postal> 📮
This renders as an HTML <div> with the CSS class "adr", unless it contains one or more <postalLine> child elements. If it does, it renders as an HTML <pre> element with the CSS class "label" instead 🫶
When there's no <postalLine> child, the following child elements get rendered into the HTML:
- Each
<street>is rendered - A
<div>that includes:- The rendering of all
<city>elements - A comma and a space: ", "
- The rendering of all
<region>elements - Whitespace
- The rendering of all
<code>elements
- The rendering of all
- The rendering of all
<country>elements
<div class="adr">
<div class="street-address">1 Main Street</div>
<div class="street-address">Suite 1</div>
<div>
<span class="city">Denver</span>,
<span class="region">CO</span>
<span class="postal-code">80212</span>
</div>
<div class="country-name">United States of America</div>
</div>9.38. <postalLine> ✉️
This renders as the text inside the element, followed by a newline. The exception is the last <postalLine> in a given <postal> element, which should not be followed by a newline. Tiny detail, big vibes 🙈 For example:
<postal>
<postalLine>In care of:</postalLine>
<postalLine>Computer Sciences Division</postalLine>
</postal>Would be rendered as:
<pre class="label">In care of:
Computer Sciences Division</pre>9.39. <refcontent> 🧾
This renders as an HTML <span> with the CSS class "refContent" ✨
<span class="refContent">Self-published pamphlet</span>9.40. <reference> 📚
If the parent of this element isn't a <referencegroup>, it renders as a <dt> <dd> pair. The defined term is the reference "anchor" attribute wrapped in square brackets, and the definition holds the full bibliographic info as specified by [RFC7322]. The <dt> gets an "id" attribute set to the reference anchor, so it's easy to find bestie 🔍
<dl class="reference">
<dt id="RFC5646">[RFC5646]</dt>
<dd>
<span class="refAuthor">Phillips, A.</span>
<span>and</span>
<span class="refAuthor">M. Davis</span>
<span class="refTitle">"Tags for Identifying Languages"</span>,
...
</dd>
</dl>If it's a child of a <referencegroup>, this element renders as a <div> with the class "refInstance". Its "id" attribute is the value of the <source> element's "anchor" attribute 🫶
<div class="refInstance" id="RFC5730">
...
</div>9.41. <referencegroup> 🗂️
A <referencegroup> gets translated into a <dt> <dd> pair. The defined term is the referencegroup "anchor" attribute wrapped in square brackets, and the definition contains the translated output of all the child <reference> elements 💖
<dt id="STD69">[STD69]</dt>
<dd>
<div class="refInstance" id="RFC5730">
<span class="refAuthor">Hollenbeck, S.</span>
...
</div>
<div class="refInstance" id="RFC5731">
<span class="refAuthor">Hollenbeck, S.</span>
...
</div>
...
</dd>9.42. <references> 📖
If there is exactly one <references> element, a section gets added to the document. It continues with the next section number after the last top-level <section> in <middle>, and the <name> element of the <references> element is used as the section name 🎀
<section id="n-my-references">
<h2 id="s-3">
<a href="#s-3" class="selfRef">3.</a>
<a href="#n-my-references class="selfRef">My References</a>
</h2>
...
</section>If there is more than one <references> element, an HTML <section> element is created to hold a subsection for each of the <references>. The section number is the next one after the last top-level <section> in <middle>. This section is named "References", and its "id" attribute is "n-references" 🌟
<section id="n-references">
<h2 id="s-3">
<a href="#s-3" class="selfRef">3.</a>
<a href="#n-references" class="selfRef">References</a>
</h2>
<section id="n-informative-references">
<h3 id="s-3.1">
<a href="#s-3.1" class="selfRef">3.1.</a>
<a href="#n-informative-references" class="selfRef">
Informative References</a></h3>
<dl class="reference">...
</dl>
</section>
...
</section>9.43. <region> 🗺️
This is rendered as a <span> tag with the CSS class "region" 💅
<span class="region">Colorado</span>9.44. <relref> 🔗
This renders as an HTML <a> tag with the CSS class "relref". Its "href" is the "derivedLink" attribute of the element. The text inside that <a> changes depending on the "displayFormat" attribute, and some values also generate extra text. Some "displayFormat" values also render a second HTML <a> tag, with the CSS class "xref" and an "href" of "#". Its target is the "target" attribute (modified by any applicable <displayreference> element), and its text is also the "target" attribute (modified by any applicable <displayreference> element). Whenever this <a class='xref'> tag is used, it's always wrapped in square brackets, like "[<a class='xref' href='#foo'>foo</a>]" 🫶
9.44.1. displayFormat='of' 🦋
The output is an <a class='relref'> HTML tag. Its contents are "Section " followed by the value of the "section" attribute. Then comes the word "of" (surrounded by whitespace), followed by the <a class='xref'> HTML tag, which is wrapped in square brackets 🎀
For example, with an input of:
See <relref section="2.3" target="RFC9999" displayFormat="of"
derivedLink="http://www.rfc-editor.org/info/rfc9999#s-2.3"/>
for an overview.The HTML generated will be:
See <a class="relref"
href="http://www.rfc-editor.org/info/rfc9999#s-2.3">Section
2.3</a> of [<a class="xref" href="#RFC9999">RFC9999</a>]
for an overview.9.44.2. displayFormat='comma' 💅
Okay bestie, comma mode is giving "list of things" energy ✨ The output is an <a class='xref'> HTML tag wrapped in square brackets 🎀, then a comma (","), then whitespace, then an <a class='relref'> HTML tag. The relref's contents are "Section " plus the value of the "section" attribute 💖
For example, with an input of:
See <relref section="2.3" target="RFC9999" displayFormat="comma"
derivedLink="http://www.rfc-editor.org/info/rfc9999#s-2.3"/>,
for an overview.The HTML generated will be:
See [<a class="xref" href="#RFC9999">RFC9999</a>], <a class="relref"
href="http://www.rfc-editor.org/info/rfc9999#s-2.3">Section 2.3</a>,
for an overview.9.44.3. displayFormat='parens' 🧚
Parens mode is so extra and I love it 🌈 The output is an <a> element with an "href" attribute whose value is the value of the "target" attribute prepended by "#", and whose content is the value of the "target" attribute. The entire element gets wrapped in square brackets. Then there's whitespace, then an <a> element whose "href" is the value of the "derivedLink" attribute and whose content is the value of the "derivedRemoteContent" attribute. That whole element gets wrapped in parentheses 🦋
For example, if Section 2.3 of RFC 9999 has the title "Protocol Overview", for an input of:
See <relref section="2.3" target="RFC9999" displayFormat="parens"
derivedLink="http://www.rfc-editor.org/info/rfc9999#s-2.3"
derivedRemoteContent="Section 2.3"/> for an overview.The HTML generated will be:
See [<a class="relref" href="#RFC9999">RFC9999</a>]
(<a class="relref"
href="http://www.rfc-editor.org/info/rfc9999#s-2.3">Section
2.3</a>) for an overview.9.44.4. displayFormat='bare' 🍓
Bare mode is the minimalist era and honestly iconic 🤍 The output is an <a> element whose "href" attribute is the value of the "derivedLink" attribute, and whose content is the value of the "derivedRemoteContent" attribute.
For this input:
See <relref section="2.3" target="RFC9999" displayFormat="bare"
derivedLink="http://www.rfc-editor.org/info/rfc9999#s-2.3"
derivedRemoteContent="Section 2.3"/> and ...The HTML generated will be:
See <a class="relref"
href="http://www.rfc-editor.org/info/rfc9999#s-2.3">Section
2.3</a> and ...9.45. <rfc> 🌸
Okay so the <rfc> element is a bit of a shapeshifter 🫶 Various attributes of this element show up in different parts of the HTML document, so you'll find its bits scattered around.
9.46. <section> 👑
This element gets rendered as an HTML <section> element, containing an appropriate level HTML heading element (<h2> through <h6>) ✨ That heading element has an <a> element around the part number (pn), if applicable. (For instance, <abstract> doesn't get a section number, so it's not giving numbers, and that's valid 💅) Then there's another <a> element with the section's name.
<section id="intro">
<h2 id="s-1">
<a href="#s-1" class="selfRef">1.</a>
<a href="#intro" class="selfRef">Introduction</a>
</h2>
<p id="s-1-1">Paragraph <a href="#s-1-1" class="pilcrow">¶</a>
</p>
</section>9.47. <seriesInfo> 🎀
This element is rendered in an HTML <span> element with the CSS name "seriesInfo" 💖
<span class="seriesInfo">RFC 5646</span>9.48. <sourcecode> 💻
This one's rendered in an HTML <pre> element with a CSS class of "sourcecode" 🔥 Heads up, CDATA blocks don't work consistently in HTML, so all <, >, and & must be escaped as <, >, and &, respectively. Not optional, bestie 🙈 If the input XML has a "type" attribute, another CSS class gets added: "lang-" plus the type.
If the sourcecode is not inside a <figure> element, a pilcrow (Section 5.2) is included. Inside a <figure> element, the figure title does the pilcrow's job instead ✨
<pre class="sourcecode lang-c">
#include <stdio.h>
int main(void)
{
printf("hello, world\n");
return 0;
}
</pre>9.49. <street> 🌈
This renders as an HTML <div> element with the CSS class "street-address" 🏠
<div class="street-address">1899 Wynkoop St, Suite 600</div>9.50. <strong> 💪
This is directly rendered as its HTML counterpart. Simple and strong, just like the name 💜
9.51. <sub> 🌙
Directly rendered as its HTML counterpart. No notes, no drama 🫧
9.52. <sup> ⭐
Also directly rendered as its HTML counterpart. Same energy as <sub>, just going up instead 🚀
9.53. <t> 🌷
This element is rendered as an HTML <p> element, and a pilcrow (Section 5.2) is included. Every paragraph gets its little pilcrow, so iconic 😭
<p id="s-1-1">A paragraph.
<a href="#s-1-1" class="pilcrow">¶</a></p>9.54. <table> 🍰
Directly rendered as its HTML counterpart. The table is just a table, no surprises 💅
9.55. <tbody> 🧁
Directly rendered as its HTML counterpart 🫶
9.56. <td> 🍒
Directly rendered as its HTML counterpart, one cell at a time 🌸
9.57. <tfoot> 🎈
Directly rendered as its HTML counterpart. The footer is the end of the table, and it's serving 🔚
9.58. <th> 🦄
Directly rendered as its HTML counterpart. Headers get to be the main character ✨
9.59. <thead> 🌟
Directly rendered as its HTML counterpart 💖
9.60. <title> 🎀
The title of the document shows up in a <title> element in the <head> element, as described in Section 6.3.2 💜
The title also appears in an <h1> element and follows directly after the Document Information. The <h1> element has an "id" attribute with the value "title" 👑
<h1 id="title">HyperText Markup Language Request For
Comments Format</h1>Inside a reference, the title is rendered as an HTML <span> tag with the CSS class "refTitle". The text is surrounded by quotes inside the <span> 🫶
<span class="refTitle">"Tags for Identifying Languages"</span>9.61. <tr> 🍭
Directly rendered as its HTML counterpart. One row, one slay 🌈
9.62. <tt> 💻
This element is rendered as an HTML <code> element. Typewriter vibes, but make it code 🖤
9.63. <ul> 🫧
This element is directly rendered as its HTML counterpart. If the "spacing" attribute has the value "compact", a CSS class of "ulCompact" gets added. If the "empty" attribute has the value "true", a CSS class of "ulEmpty" gets added 🧚
9.64. <uri> 🔗
This element is rendered as an HTML <div> containing the string "URI:" and an HTML <a> element. The <a> has its "href" attribute set to the linked URI, a CSS class of "url" (note that it's "url", not "uri" like you'd expect, so don't get tricked 🙈), and its contents set to the linked URI.
<div>URI:
<a href="http://www.example.com"
class="url">http://www.example.com</a>
</div>9.65. <workgroup> 🫥
This element does not add any direct output to HTML. Quiet but important 🤫
9.66. <xref> 🏹
This element is rendered as an HTML <a> element with an appropriate local link as the "href" attribute. The value of "href" is taken from the "target" attribute, prepended by "#" ✨ The <a> element generated will have the class "xref". The contents of the <a> element are the value of the "derivedContent" attribute. If the "format" attribute has the value "default", and the "target" attribute points to a <reference> or <referencegroup> element, then the generated <a> element is surrounded by square brackets in the output 💅
<a class="xref" href="#target">Table 2</a>or
[<a class="xref" href="#RFC1234">RFC1234</a>]9.67. <svg xmlns='http://www.w3.org/2000/svg'> 🎨
This element is rendered as part of the <artwork> element. The xmlns='http://www.w3.org/2000/svg' namespace declaration should be included, and the SVG should be serialized as well-formed XML, even for tags that would otherwise not need closing in HTML5 🦋
10. Security Considerations 🚨
Okay bestie, this part is SERIOUS, so pay attention 😭 Since RFCs are sometimes exchanged outside the normal Web sandboxing mechanism (such as using the "rsync" program to a mirror site) and then loaded from a local file, more care must be taken with the HTML than is ordinary on the web. Like, way more care 💀
11. References 📚
11.1. Normative References 💜
[BCP14] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997,
<http://www.rfc-editor.org/info/bcp14>.
[RFC2397] Masinter, L., "The "data" URL scheme", RFC 2397,
DOI 10.17487/RFC2397, August 1998,
<http://www.rfc-editor.org/info/rfc2397>.
[RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO
10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November
2003, <http://www.rfc-editor.org/info/rfc3629>.
[RFC5646] Phillips, A., Ed. and M. Davis, Ed., "Tags for Identifying
Languages", BCP 47, RFC 5646, DOI 10.17487/RFC5646,
September 2009, <http://www.rfc-editor.org/info/rfc5646>.
[RFC7322] Flanagan, H. and S. Ginoza, "RFC Style Guide", RFC 7322,
DOI 10.17487/RFC7322, September 2014,
<http://www.rfc-editor.org/info/rfc7322>.
[RFC7991] Hoffman, P., "The "xml2rfc" Version 3 Vocabulary",
RFC 7991, DOI 10.17487/RFC7991, December 2016,
<http://www.rfc-editor.org/info/rfc7991>.
[RFC7993] Flanagan, H., "Cascading Style Sheets (CSS) Requirements
for RFCs", RFC 7993, DOI 10.17487/RFC7993, December 2016,
<http://www.rfc-editor.org/info/rfc7993>.
[W3C.REC-CSS2-20110607]
Bos, B., Celik, T., Hickson, I., and H. Lie, "Cascading
Style Sheets Level 2 Revision 1 (CSS 2.1) Specification",
World Wide Web Consortium Recommendation
REC-CSS2-20110607, June 2011,
<http://www.w3.org/TR/2011/REC-CSS2-20110607>.
[W3C.REC-html5-20141028]
Hickson, I., Berjon, R., Faulkner, S., Leithead, T.,
Navara, E., O'Connor, T., and S. Pfeiffer, "HTML5", World
Wide Web Consortium Recommendation
REC-html5-20141028, October 2014,
<http://www.w3.org/TR/2014/REC-html5-20141028>.11.2. Informative References 🌟
[HCARD] Celik, T., "hCard 1.0", 2015,
<http://microformats.org/wiki/hcard>.
[RFC-STYLE]
RFC Editor, "Style Guide",
<https://www.rfc-editor.org/styleguide/>.
[RFC6949] Flanagan, H. and N. Brownlee, "RFC Series Format
Requirements and Future Development", RFC 6949,
DOI 10.17487/RFC6949, May 2013,
<http://www.rfc-editor.org/info/rfc6949>.
[RFC7990] Flanagan, H., "RFC Format Framework", RFC 7990,
DOI 10.17487/RFC7990, December 2016,
<http://www.rfc-editor.org/info/rfc7990>.
[RFC7998] Hoffman, P. and J. Hildebrand, ""xml2rfc" Version 3
Preparation Tool Description", RFC 7998,
DOI 10.17487/RFC7998, December 2016,
<http://www.rfc-editor.org/info/rfc7998>.
[W3C.WD-css3-page-20130314]
Grant, M., Etemad, E., Lie, H., and S. Sapin, "CSS Paged
Media Module Level 3", World Wide Web Consortium
WD WD-css3-page-20130314, March 2013,
<http://www.w3.org/TR/2013/WD-css3-page-20130314>.IAB Members at the Time of Approval 🎓
The IAB members at the time this memo was approved were (in alphabetical order):
- Jari Arkko
- Ralph Droms
- Ted Hardie
- Joe Hildebrand
- Russ Housley
- Lee Howard
- Erik Nordmark
- Robert Sparks
- Andrew Sullivan
- Dave Thaler
- Martin Thomson
- Brian Trammell
- Suzanne Woolf
Acknowledgments 🫶
Heather Flanangan was an early coauthor of this document and helped its formation 💖 The authors gratefully acknowledge the contributions of: Patrick Linskey and the members of the RFC Format Design Team (Nevil Brownlee (ISE), Tony Hansen, Ted Lemon, Julian Reschke, Adam Roach, Alice Russo, Robert Sparks (Tools Team liaison), and Dave Thaler) 👑
Authors' Addresses 💌
Joe Hildebrand (editor) Mozilla
Email: joe-ietf@cursive.net
Paul Hoffman ICANN
Email: paul.hoffman@icann.org
📦 where this page comes from
- ietf: rfc7992 2016-12
- 💖 girlified by claude-haiku-5-5 on : a language model's rewrite of the original, under its terms