Network Working Group J. Hildebrand
Internet-Draft Cisco Systems, Inc.
Intended status: Standards Track July 16, 2012
Expires: January 17, 2013
HTML RFC Format
draft-hildebrand-html-rfc-01
Abstract
This document defines an HTML format that can be used for the
production of Internet-Drafts and RFCs.
If you are viewing a version of this document other than the HTML
generated by the editor, your a missing vital information. Download
a canonical version from
http://cursive.net/draft-hildebrand-html-rfc-2012-07-16.html.
Status of this Memo
This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
This Internet-Draft will expire on January 17, 2013.
Copyright Notice
Copyright (c) 2012 IETF Trust and the persons identified 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) in effect on the date of
publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of
Hildebrand Expires January 17, 2013 [Page 1]
Internet-Draft HTML RFC Format July 2012
the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License.
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4
1.1. Background . . . . . . . . . . . . . . . . . . . . . . . . 4
1.2. Overview . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.3. Terminology . . . . . . . . . . . . . . . . . . . . . . . 5
2. Accessibility . . . . . . . . . . . . . . . . . . . . . . . . 5
3. HTML Format . . . . . . . . . . . . . . . . . . . . . . . . . 6
3.1. Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . 6
3.2. Basic Structure . . . . . . . . . . . . . . . . . . . . . 7
3.2.1. HTML5 . . . . . . . . . . . . . . . . . . . . . . . . 7
3.2.2. DOCTYPE . . . . . . . . . . . . . . . . . . . . . . . 7
3.2.3. Root Element . . . . . . . . . . . . . . . . . . . . . 7
3.2.4. Charset Declaration . . . . . . . . . . . . . . . . . 7
3.2.5. Style . . . . . . . . . . . . . . . . . . . . . . . . 8
3.2.6. Emphasis . . . . . . . . . . . . . . . . . . . . . . . 8
3.2.7. Comments . . . . . . . . . . . . . . . . . . . . . . . 9
3.2.8. Sections . . . . . . . . . . . . . . . . . . . . . . . 9
3.2.9. Appendices . . . . . . . . . . . . . . . . . . . . . . 10
3.2.10. Paragraphs . . . . . . . . . . . . . . . . . . . . . . 10
3.2.11. Lists . . . . . . . . . . . . . . . . . . . . . . . . 10
3.2.12. References . . . . . . . . . . . . . . . . . . . . . . 11
3.3. More Elaborate Information . . . . . . . . . . . . . . . . 12
3.3.1. Requirement Keywords . . . . . . . . . . . . . . . . . 12
3.3.2. Sections to be Removed by the RFC Editor . . . . . . . 12
3.3.3. Formatting the Table of Contents . . . . . . . . . . . 13
3.3.4. Images . . . . . . . . . . . . . . . . . . . . . . . . 13
3.3.5. SVG . . . . . . . . . . . . . . . . . . . . . . . . . 14
3.3.6. Inline Code . . . . . . . . . . . . . . . . . . . . . 15
3.3.7. Blocks of Code . . . . . . . . . . . . . . . . . . . . 15
3.3.8. ASCII Art . . . . . . . . . . . . . . . . . . . . . . 15
3.3.9. Packet Formats . . . . . . . . . . . . . . . . . . . . 16
4. Document Metadata . . . . . . . . . . . . . . . . . . . . . . 16
4.1. Document Information . . . . . . . . . . . . . . . . . . . 17
4.2. Title . . . . . . . . . . . . . . . . . . . . . . . . . . 18
4.3. Abstract . . . . . . . . . . . . . . . . . . . . . . . . . 18
4.4. IPR Statements . . . . . . . . . . . . . . . . . . . . . . 18
4.5. Author . . . . . . . . . . . . . . . . . . . . . . . . . . 19
4.6. Bibliographical Information . . . . . . . . . . . . . . . 19
5. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
5.1. Self . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
5.2. Code Sample . . . . . . . . . . . . . . . . . . . . . . . 19
5.3. Sequence Diagrams . . . . . . . . . . . . . . . . . . . . 19
5.4. ABNF . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Hildebrand Expires January 17, 2013 [Page 2]
Internet-Draft HTML RFC Format July 2012
5.5. Mathematical Formulae . . . . . . . . . . . . . . . . . . 20
6. Security Considerations . . . . . . . . . . . . . . . . . . . 20
7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 21
8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 21
8.1. Normative References . . . . . . . . . . . . . . . . . . . 21
8.2. Informative References . . . . . . . . . . . . . . . . . . 22
Appendix A. Allowable Subset of HTML . . . . . . . . . . . . . . 23
Appendix B. CSS Classes with Special Meaning . . . . . . . . . . 25
Appendix C. Element IDs with Special Meaning . . . . . . . . . . 26
Appendix D. Acknowledgments . . . . . . . . . . . . . . . . . . . 28
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 28
Hildebrand Expires January 17, 2013 [Page 3]
Internet-Draft HTML RFC Format July 2012
1. Introduction
1.1. Background
If you are viewing a version of this document other than the HTML
generated by the editor, your a missing vital information. Download
a canonical version from
http://cursive.net/draft-hildebrand-html-rfc-2012-07-16.html.
The RFC Series has been in existence for over 40 years. During much
of that time, the limitations of character set, line and page length,
and graphics restrictions of RFC documents met the most immediate
needs of the majority of authors and readers. As technology changed,
new formats that allowed for a richer set of edit, search and display
features came in to use, and tools were created to convert the plain
ASCII documents to other desired formats such as HTML, PDF, and
Microsoft Word. While the converted versions of the RFCs are widely
available, the canonical display format remains the plain text,
ASCII, line-printer structured one. The canonical source format is
nroff.
Canonical source and display versions of an RFC exists for several
reasons:
o to provide verification of the content of an RFC in case
inconsistencies are created when a document is converted to
another format or mirrored to another location
o to verify the final content of a document in cases of legal
dispute
o to aid in the conversion of the RFC in to formats requested by the
community
The current basic format of RFC source and display documents have two
characteristics that are considered by the RFC Series Editor to be
critical to the RFC Series, including:
o persistence (tools to read, edit, and print the documents remain
easily accessible to everyone)
o convertibility (the plain text version is simple to convert to
other formats)
That said, the very simple nature of the current display format in
particular introduces a variety of limitations, the list of which has
grown as changes in technology create new expectations:
o ASCII art is considered by some to be a major limitation in
expressing visually-oriented information
Hildebrand Expires January 17, 2013 [Page 4]
Internet-Draft HTML RFC Format July 2012
o the internationalization of the authorship and the Internet is
introducing Unicode [8] codepoints not expressible in 7-bit ASCII
o the more common forms of display (web pages, smaller devices) make
the limitations of page and line length a hindrance to the reading
of an RFC
o tools for people with visual impairments may stumble over the
page-oriented structure of the current format; large fonts on a
screen that is not large enough to show an entire line, for
example, can make the current format difficult to read, since
lines do not re-wrap automatically
1.2. Overview
This memo describes a format that can be used both as the canonical
input format to the RFC Series Editor (RSE), as well as an archival
format. Some document authors will write documents directly in this
format (perhaps with tooling to generate the more repetitive tasks),
and some authors will prefer other formats as their original source,
all of which MUST be able to generate the format described in this
memo.
This memo has the following goals:
1. Define a strict subset of HTML appropriate for Internet-Draft and
RFC Series documents
2. Serve as a comprehensive example of all of the HTML elements that
are permissible
1.3. Terminology
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in RFC
2119 [2].
2. Accessibility
One of the major goals of the HTML format is to ensure accessibility
for the following consumers of documents written in the format:
o People with impaired vision, including those that use large fonts
and those that use screen readers
o People with difficulty distinguishing between colors
o People who use devices with small screens, such as cell phones
o Other groups TBD
Specific instances where these goals are important in the design
Hildebrand Expires January 17, 2013 [Page 5]
Internet-Draft HTML RFC Format July 2012
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 does require that key semantic data is
not lost when read using the tools and settings that are required by
a given constituency.
3. HTML Format
The format specified here is a subset of HTML, deemed to be widely-
implemented by common browsers at the time that the specification was
created, likely to continue to be widely-implemented in the future,
and unlikely to cause security issues.
3.1. Syntax
The following rules SHALL be enforced before submittal.
o The HTML source MUST be encoded as UTF-8, as specified in RFC3629
[4].
o The HTML source MUST be formatted in the manner of well-formed XML
[11], with all element start tags having matching end tags (or
"<element />" for empty elements), and all elements properly
nested. HTML "boolean" attributes MUST be formatted in the
"attr='attr'" style.
o Single quotes (U+0027 APOSTROPHE: "'") MUST be used to quote
attribute values. Unquoted attribute values MUST NOT be used.
o HTML SHALL be indented using spaces (not tabs).
o Each child element SHALL be indented two spaces more than its
parent element, unless the child element is mixed with non-
whitespace-only text children of the same parent element.
o Each logical line MUST be terminated solely with a \n (U+000A:
LINE FEED), otherwise known as "Unix-style" line endings.
o Other than \n (U+000A: LINE FEED), code points less than " "
(U+0020: SPACE) (otherwise known as "control characters") MUST
NOT be used. Any character references that would generate these
code points (e.g. ) MUST 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
source.
o Unicode codepoints that are unassigned at the time of publication
MUST not be used.
o Any Unicode codepoint higher than ~ (U+007E: TILDE) MUST serve an
explicit purpose that enhances the understanding of the document.
Author names and examples are two known cases. The intent is that
the document MUST be understandable by a reader with the ability
to read technical English.
Hildebrand Expires January 17, 2013 [Page 6]
Internet-Draft HTML RFC Format July 2012
o Each text-containing element such as headings ("<h1>"-"<h6>"),
paragraphs ("<p>"), or list items ("<li>"), MUST be serialized as
a single line without wrapping.
NOTE: none of these rules affect the rendered output of the HTML,
but are intended to increase the chance that multiple tools that
process the format will generate identical syntax. In turn, this
will make difference tools that operate on the HTML source easier to
write.
3.2. Basic Structure
3.2.1. HTML5
The HTML comprising the document MUST be valid according to the
latest version of the HTML specification at the publishing, starting
with the version commonly known as HTML5 [12]. Although the HTML
specification mandates several of syntax and structure rules in this
document, they are called out here for emphasis.
3.2.2. DOCTYPE
The DOCTYPE of the document MUST be "html", which declares that the
document is compliant with HTML5 [12]. For example, the document
will start with exactly this string:
<!DOCTYPE html>
3.2.3. Root Element
The root element of the document MUST be "<html>". This element
SHOULD include a "lang" attribute, whose value is a RFC5646 [7]
language tag describing the natural language of the document. For
documents submitted to the RFC Series or Internet-Draft Series, the
language tag MUST be ""en"", meaning "English". If the "lang"
attribute is not present, its value should be taken to be ""en"".
3.2.4. Charset Declaration
In order to be correctly processed by browsers that load the HTML
using a mechanism that does not provide a valid MIME content-type or
charset, the HTML "<head>" element MUST contain a "<meta>" element,
with the attributes "http-equiv='Content-Type'" and
"content='text/html; charset=utf-8'". This will look like:
<meta http-equiv='Content-Type' content='text/html; charset=utf-8' />
Hildebrand Expires January 17, 2013 [Page 7]
Internet-Draft HTML RFC Format July 2012
3.2.5. Style
The "<head>" SHOULD contain an embedded CSS [9] stylesheet in a
"<style>" element. The styles in the stylesheet are to be set
consistently between documents by the RFC Editor, according to the
best practices of the day. The RFC Editor SHALL choose a stylesheet
that does not modify the meaning of the normative text of the
document. The RFC Editor SHALL make the stylesheet available via a
standard protocol (e.g. HTTP or HTTPS) for ease of authorship.
However, when a document is submitted, external stylesheets (other
than "local.css" as specified below) are NOT ALLOWED. The stylesheet
itself MUST NOT be considered as normative information.
To ensure consistent formatting, individual "style" attributes SHOULD
NOT be used in the main portion of the document source except in
highly exceptional circumstances; each use MUST be individually
justified.
Different readers of a specification will desire different tweaks to
the stylesheet. To facilitate this, the "<head>" SHOULD include a
"<link>" to a stylesheet in the same directory as the HTML file,
named "local.css", *after* the embedded stylesheet. Note that this
"local.css" file will not exist for most users; browsers will
correspondingly ignore this "<link>". When the document is used
canonically, these local style overrides MUST NOT be in effect.
For example:
<head>
<style type='text/css'>
<!--
/* RFC-editor styles */
-->
</style>
<link rel='stylesheet' type='text/css' href='local.css' />
</head>
3.2.6. Emphasis
Words or phrases may be emphasized using the "<strong>" element for
"*bold*", and the "<em>" element for "_italics_". Underlining MUST
NOT be used except for links, to avoid visual confusion. Text-only
emphasis MUST NOT be used.
The RFC Editor will set a policy that reflects the current feelings
of the community as to whether this emphasis markup is allowed in
documents that are submitted for publication in the RFC series.
Hildebrand Expires January 17, 2013 [Page 8]
Internet-Draft HTML RFC Format July 2012
3.2.7. Comments
HTML comments MAY be used, but MUST NOT contain normative
information. One example is to clarify particular choices in the
HTML format. Example:
<!-- Automatically generated: do not modify -->
3.2.8. Sections
Each section of the document SHALL be formatted as a "<div>" tag,
with a class attribute with value "section". A document-unique, "id"
attribute SHOULD be assigned to each section "<div>". The "id" MAY
be human-readable or generated.
NOTE: XML [11] requires id attributes to be unique across an entire
document:
Each section "<div>" MUST contain a header tag ("<h2>"-"<h6>") of the
appropriate depth, with top-level sections getting an "<h2>" tag, and
each nested section getting the next higher header level. If more
than five levels of headers are required, "<h6>" MUST be used for
each deeper-nested section. However, nesting sections more than five
levels deep is NOT RECOMMENDED.
The text in each header tag MUST begin with the section number.
Section numbers MUST begin at "1.", and MUST increment by one for
each successive section at the same level. Subsections MUST be
numbered by appending the subsection number to the parent section
number.
It is RECOMMENDED that the section number be wrapped in an "<a>"
element, whose "href" attribute points to the corresponding section
div with a local relative reference. This "<a>" element SHOULD have
the CSS class "self-ref".
Within a section, each "normal" paragraph MUST be surrounded by a
"<p>" element.
For example:
<div class='section' id='example'>
<h2><a class='self-ref' href='#example'>1.</a> Example Section</h2>
<p>This is a description of the example</p>
<div class='section' id='nested'>
<h3><a class='self-ref' href='#nested'>1.1.</a> Nested Section</h3>
<p>This is a description of the nested section.</p>
<p>This is the second description paragraph.</p>
</div>
Hildebrand Expires January 17, 2013 [Page 9]
Internet-Draft HTML RFC Format July 2012
</div>
3.2.9. Appendices
Appendices are special cases of top-level sections. Each appendix of
the document SHALL be formatted as a "<div>" tag, with a class
attribute with value "appendix". A document-unique, id attribute
SHOULD be assigned to each section "<div>". The id MAY be human-
readable or generated. Each appendix "<div>" MUST contain an "<h2>"
element containing text that describes the purpose of the appendix.
Appendices are identified to the reader with Latin capital letters
A-Z, in order. It is NOT RECOMMENDED to have more than 26
appendices, but if required, appendices "AA.", "AB.", etc. follow
Appendix Z.
Inside the appendix, subsections MUST be formatted per Sections
(Section 3.2.8), numbered sequentially. For example, the first
subsection of "Appendix A." is "Appendix A.1.".
For example:
<div class='appendix' id='acknowledgements'>
<h2>Appendix A. Acknowledgements</h2>
<p>The author gratefully acknowledges the contributions of...</p>
<div class='section' id='contributors'>
<h3>Appendix A.1. Contributors</h2>
<p>These people contributed text...</p>
</div>
</div>
3.2.10. Paragraphs
Paragraphs MUST be contained in a section (Section 3.2.8) "<div>" or
an appendix (Section 3.2.9) "<div>". A document-unique, "id"
attribute SHOULD be assigned to each "<p>". The "id" will usually be
machine-generated, but MAY be human-readable if desired.
It is RECOMMENDED that each paragraph be kept relatively small
compared to a "page" in previous RFC formats, so that references to
each paragraph are at least as valuable as page references have been
in previous formats.
3.2.11. Lists
Lists may be used inside a section "<div>", and may nest in other
lists as needed. However, lists MUST NOT be nested inside a "<p>"
element. Unordered lists ("<ul>") and ordered lists ("<ol>") may
both be used. For example:
Hildebrand Expires January 17, 2013 [Page 10]
Internet-Draft HTML RFC Format July 2012
<div class='section' id='lists'>
<h4>Unordered list</h4>
<p id='lists-p-1'>An explanation:</p>
<ul>
<li>One</li>
<li>Two</li>
<ol>
<li>Two.1: (this one is numbered)</li>
</ol>
</ul>
</div>
3.2.12. References
3.2.12.1. Internal References
References to other paragraphs or sections in the same document MUST
use an "<a>" element with an "href" attribute with a fragment that
points at the "id" attribute of the target (i.e. the "id" prefixed
with a "#"). The target element MUST have a human-readable "id"
attribute, which MUST be stable even when tooling generates new "id"
attributes. For example:
See <a href='#example'>Example Section</a> for more details
3.2.12.2. References to Standards
References to standards are special, in that they generate formal
bibliographical metadata. All links to standards in the main body of
the text MUST jump to the bibliographical (Section 4.6) entry; the
href MUST be of the form #[series]:[number]. For example:
href='#RFC2119'
Valid series identifiers include:
o 3gpp: The 3rd Generation Partnership Project [16]
o ansi: American National Standards Institute [17]
o ccitt: ITU Telecommunication Standardization Sector [18]
o fips: Federal Information Processing Standard [19]
o id: Internet-Drafts [20]
o ieee: Institute of Electrical and Electronics Engineers [21]
o iso: International Organization for Standardization [22]
o itu: International Telecommunication Union [23]
o nist: National Institute of Standards and Technology [24]
o oasis: Organization for the Advancement of Structured Information
Standards [25]
o pkcs: Public-Key Cryptography Standards [26]
Hildebrand Expires January 17, 2013 [Page 11]
Internet-Draft HTML RFC Format July 2012
o rfc: Request For Comments [27]
o w3c: The World Wide Web Consortium [28]
o xep: XMPP Standards Foundation [29]
The text inside the link SHOULD be a human-readable colloquial
representation of the standard name and/or number.
Normative references MUST use "<a>" elements with class "ref".
Example:
See: <a class='ref' href='#RFC2119'>RFC2119</a>
Informative references MUST use "<a>" elements with class "inforef".
Example:
See: <a class='inforef' href='#RFC2119'>RFC2119</a>
3.2.12.3. Other External References
References to other documents that are not standards SHOULD be linked
using the "http:" or "https:" URI scheme, and MUST be linked using a
a URI scheme that is widely-deployed at the time that the document is
published, and which does not raise any security or stability issues.
In particular, "javascript:" references MUST NOT be used. Links
using the "mailto:" scheme SHOULD be limited to the author's address
information.
For example:
<a href='http://example.com/'>Example</a>
3.3. More Elaborate Information
This section describes how to format several types of information
that occur regularly in documents for the Internet-Draft and RFC
Series which are not descriptive text.
3.3.1. Requirement Keywords
The RFC2119 [2] keywords in the document MAY be set off with special
markup. If so, they MUST be surrounded with a "<span>" element
continaing the CSS class "rfc2119". For example:
If so, they <span class='rfc2119'>MUST</span> be surrounded
3.3.2. Sections to be Removed by the RFC Editor
The author may want to inject notes to the reader that are not to be
a part of the final document that is published by the RFC editor.
These notes MAY use any format desired by the author that would
otherwise be legal in the document, but the outermost element of the
Hildebrand Expires January 17, 2013 [Page 12]
Internet-Draft HTML RFC Format July 2012
note MUST have a CSS "class" with value "rfceditor-remove".
<div class='rfceditor-remove'>
<h2>Editorial Notes</h2>
<p>...</p>
</div>
3.3.3. Formatting the Table of Contents
The table of contents for the document MUST appear in a "<div>"
element, which SHOULD precede any of the sections (Section 3.2.8) of
proper document content. The "<div>" element MUST have an "id"
attribute with value "toc". The "<div>" element SHOULD contain an
"<h2>" element containing the string "Table of Contents", followed by
nested "<ul>" and "<li>" elements describing the structure of the
document, with links to each of the sections (Section 3.2.8)
mentioned. For example:
<div id='toc'>
<h2>Table of Contents</h2>
<ul>
<li>
<div>1. <a href='#introduction'>Introduction</a></div>
<ul>
<li>
<div>1.1. <a href='#background'>Background</a></div>
</li>
...
NOTE: the Table of Contents SHOULD NOT be considered meta-data for
the document. The sections (Section 3.2.8) themselves SHOULD contain
all of the data that is required.
3.3.4. Images
Include an image using the "<img>" tag with a "src" attribute.
During the editing process, it may be useful to keep the value of the
"src" attribute as a file name relative to the document, or a http(s)
URL. However, upon submission, the final version of a document SHALL
include a "data:" URI as specified in RFC2397 [3].
The image MIME type of the image SHALL be "image/png", as specified
in RFC2083 [1]. The RFC Editor can allow other image types in the
future, at the Editor's discretion, as the state of the art and
common implementation patterns change.
Consider how images will look when printed. Consider how your images
will be used by vision-impaired readers, including those readers with
Hildebrand Expires January 17, 2013 [Page 13]
Internet-Draft HTML RFC Format July 2012
color vision deficiency. For example, images SHOULD NOT have
meaningful distinctions conveyed only by color differences, and
images SHOULD be available in high enough resolution that readers
with other vision deficiencies can zoom in to see detail. Images
MUST NOT be animated.
The "alt" attribute is REQUIRED, and MUST be a complete, accessible
description of the image.
The "height" and "width" attributes SHOULD be used to specify the
size of the image in pixels.
Images MUST be wrapped in a "<figure>" element. The "<figure>"
element SHOULD contain a "<figcaption>" element after the "<img>"
element, which SHOULD contain text that describes the image. For
example:
<figure>
<img src='data:image/png;base64,[BASE64-encoded PNG]'
alt='A description of the diagram'
width='236'
height='176'/>
<figcaption>Possible workflow for processing HTML RFCs</figcaption>
</figure>
Images SHOULD NOT be normative. Instead, the information contained
in the image SHOULD be adequately conveyed in the textual description
that accompanies the image.
3.3.5. SVG
SVG [10] can be included directly in the HTML source, surrounded by a
"<figure>" element and succeeded by a "<figcaption>" element, as
described in Section 3.3.4 (Section 3.3.4). The root "<svg>" element
MUST contain a "<title>" or "<desc>" element that fully describes the
diagram for accessibility to screen readers; this is similar to the
"alt" attribute on images. For example:
<figure id='fig-2'>
<svg xmlns='http://www.w3.org/2000/svg'>
<title>A sample SVG</title>
<desc>This is a sample image, with a title and description</desc>
...
</svg>
<figcaption>Sample SVG</figcaption>
</figure>
Might render as:
Hildebrand Expires January 17, 2013 [Page 14]
Internet-Draft HTML RFC Format July 2012
Note that there are currently more browsers that can deal with
"<img>" elements (or their "alt" text) than are able to generate any
sensible fallback rendering from SVG. Until this changes, authors
might consider replacing their SVG with a rendered image.
3.3.6. Inline Code
Use the "<code>" element to set aside literal references to code or
protocol elements in the middle of a paragraph. If desired, the
language of the code or protocol can be declared using a "class"
attribute starting with "language-". For example:
Use the <code class='language-html'><code></code> element
3.3.7. Blocks of Code
Larger sections of code or protocol can be included using a "<pre>"
element with a "class" attribute of "code". If desired, the language
of the code or protocol can be declared using a further "class" value
starting with "language-" (multiple "class" values are separated by
spaces in HTML). The text inside the "<pre>" element will be
rendered in a monospace font, with whitespace maintained. For
example:
<pre class='code language-html'>
<html>
<body />
</html>
</pre>
Will be rendered as:
<html>
<body />
</html>
Depending on author style, blocks of code MAY be enclosed in a
"<figure>" element, with a "<figcaption>" element that describes the
block. For example, see Figure 3.
3.3.8. ASCII Art
ASCII art is still preferred by some authors in preference to an
image or SVG. The RFC Editor may decide to prefer images
(Section 3.3.4) or SVG [10], or may decide to prohibit ASCII art in
the future, depending on the needs of the community at the time of
publishing. Until that time, to include ASCII art, wrap a "<pre>"
element with "class='ascii'" in a "<figure>" along with a
"<figcaption>", as if the "<pre>" element were an image, as specified
in the Section 3.3.4 (Section 3.3.4). For example:
Hildebrand Expires January 17, 2013 [Page 15]
Internet-Draft HTML RFC Format July 2012
<figure>
<pre class='ascii'>
+-----------+
| original | <+
+-----------+ |
| |
| nit | edit
v |
nit (no-op) +-----------+ |
+-------------- | | |
| | canonical | |
+-------------> | | -+
+-----------+
</pre>
<figcaption>Sample ASCII art</figcaption>
</figure>
3.3.9. Packet Formats
Packet format descriptions can be encoded as a "<table>" element
wrapped in a "<figure>" along with a "<figcaption>", as if the
"<pre>" element were an image, as specified in Section 3.3.4
(Section 3.3.4). For consistent formatting, the "<table>" element
should have class "pdu". For example:
<figure>
<figcaption>Sample packet format</figcaption>
<table class='pdu'> [table describing the packet] </table>
</figure>
Would be rendered as:
4. Document Metadata
Metadata for the document SHOULD be easily extractable from the
document by tools that ordinarily process HTML. Typically, the
"class" and "id" attributes can be used to query the document using
CSS [9]-style selectors. The metadata scheme SHOULD be designed such
that the element name is not required in order to select a given
piece of data. Instead, any element that can contain text can be
used for a given "class" or "id" to be selected. The value of the
data contained by the selected element(s) consists of the
concatenation of all of the text from all of the child nodes of the
selected element or elements, with each run of consecutive whitespace
Unicode codepoints [codepoints with the White_Space property, such as
U+0020 (SPACE), U+0009 (CHARACTER TABULATION), U+000A (LINE FEED),
U+000C (FORM FEED), U+000D (CARRIAGE RETURN), U+00A0 (NON-BREAKING
Hildebrand Expires January 17, 2013 [Page 16]
Internet-Draft HTML RFC Format July 2012
SPACE), and U+2029 (PARAGRAPH SEPARATOR)] compressed to a single
U+0020 (SPACE). The metadata scheme MUST allow unambiguous
selection.
The "id" attribute is used to identify pieces of data that are
guaranteed to be unique across the document. Any element with an
"id" attribute can also be used as a fragment target in a URI by
starting with the base URI of the document, then appending "#"
(U+0023: NUMBER SIGN) and the value of the "id" attribute. In CSS,
the element with a given "id" attribute value is selected by
prepending the value with "#" (U+0023: NUMBER SIGN). For example,
the following HTML in a document with the URI
"http://example.com/index.html":
<div id='example'>Important Text</div>
Can be targeted directly with the URL
"http://example.com/index.html#example", and the CSS selector
"#example".
The "class" attribute is a catch-all tagging mechanism for everything
in the document that might not be unique. Multiple classes may be
defined on a single element by setting the "class" attribute to a
space-separated list of classes. All of the elements with a given
class name can be selected in CSS by prepending the class name with
"." (U+002E: FULL STOP).
4.1. Document Information
Information about the document as a whole. The "<div>" element with
"id='document'" SHOULD be the first child element of the HTML body.
For example:
<div id='document'>
<div class='identifiers'>
<div class='workgroup'>Network Working Group</div>
<div class='series'>Internet-Draft</div>
<div class='status'>Standards Track</div>
<div class='published'>2012-07-07</div>
<div class='expires'>2013-01-07</div>
<div class='version'>00</div>
</div>
<div class='authors'>
<div class='author'>
<span class='initial'>J.</span>
<span class='surname'>Hildebrand</span>
<span class='company'>Cisco Systems, Inc.</span>
</div>
</div>
Hildebrand Expires January 17, 2013 [Page 17]
Internet-Draft HTML RFC Format July 2012
</div>
More details for this format will be included in future drafts of
this document.
4.2. Title
The title of the document MUST appear in an "<h1>" element, which
SHOULD follow dirctly after the Document Information (Section 4.1).
The "<h1>" element MUST have an "id" attribute with value "title".
For example:
<h1 id='title'>HTML RFC Format</h1>
4.3. Abstract
The abstract for the document MUST appear in a "<div>" element, which
SHOULD follow directly after the Title (Section 4.2). The "<div>"
element MUST have an "id" attribute with value "abstract". The
"<div>" element SHOULD contain an "<h2>" element containing the word
"Abstract", and MUST contain one or more "<p>" elements contianing
text that describes the document succintly. For example:
<div id='abstract'>
<h2>Abstract</h2>
<p>This document defines an HTML format...</p>
</div>
4.4. IPR Statements
The IPR boilerplate for the document MUST appear in a "<div>"
element, which SHOULD follow directly after the Abstract
(Section 4.3). The "<div>" element MUST have an "id" attribute with
value "ipr" and a CSS "class" of the name of the relevant IPR
ruleset. The only valid values for the IPR ruleset class are
"trust200902", "noModificationTrust200902", and
"noDerivativesTrust200902" at this time. The contents of the "<div>"
element are to be set correctly for the given ruleset, based on
guidance from the IETF trust. For example:
<div id='ipr' class='trust200902'>
<h2>Status of this Memo</h2>
<p>...</p>
<h2>Copyright Notice</h2>
<p>...</p>
</div>
Question: should the valid IPR classes be put in an IANA registry
Hildebrand Expires January 17, 2013 [Page 18]
Internet-Draft HTML RFC Format July 2012
along with their boilerplate expansions?
4.5. Author
NOTE: this document currently uses the approach specified by
"hCard [30]". The author recommends that the vcarddav [31] Working
Group of the IETF be tasked to propose an approach for HTML embedding
of vCard that is aligned with RFC 6350 [14]. In particular, the
"language" and "altid" mechanisms of RFC 6350 [14] are not explicitly
mentioned in hCard, and are required in order to fit the desire for
authors' names to be representable both by English readers as well as
the native language of the author.
This section will be augmented with normative text when an approach
is decided upon. A quick example (as an existence proof) can be
found in Figure 6. The rendered version can be found in the authors
section for this document.
4.6. Bibliographical Information
TBD: define microformat for bibliographical data, perhaps based on
the citation [32] work at microformats.org [33].
5. Examples
5.1. Self
This draft itself is a good example of how to use the format. Please
view-source.
5.2. Code Sample
#include <stdio.h>
int main(int argc, char **argv)
{
printf("Hello, IETF\n");
return 0;
}
5.3. Sequence Diagrams
Include an image tag with "class='sequence'", where the alt text is
the WebSequenceDiagrams.com [34] source for the diagram.
Before publication, this approach will be replaced by something more
well-specified and not requiring third-party software.
Hildebrand Expires January 17, 2013 [Page 19]
Internet-Draft HTML RFC Format July 2012
<figure>
<img class='sequence' alt='
title Authentication Sequence
Alice->Bob: Authentication Request
note right of Bob: Bob thinks about it
Bob->Alice: Authentication Response' />
<figcaption>A sample sequence diagram</figcaption>
</figure>
5.4. ABNF
Augmented Backus-Naur Form is a way of describing formal syntax,
described in RFC5234 [13]. Include ABNF (without extra indentation)
in a "<pre>" element, with CSS class "code" and "language-abnf". For
example:
<pre class='code language-abnf'>
label = top-level *4section-num
top-level = section-num / appendix-let
section-num = 1*DIGIT "."
appendix-let = 1*CAP "."
CAP = %x41-5A ; A-Z
DIGIT = %x30-39 ; 0-9
</pre>
Is rendered as:
label = top-level *4section-num
top-level = section-num / appendix-let
section-num = 1*DIGIT "."
appendix-let = 1*CAP "."
CAP = %x41-5A ; A-Z
DIGIT = %x30-39 ; 0-9
5.5. Mathematical Formulae
For now, just use an image (as specified in Section 3.3.4
(Section 3.3.4)), with the alt text being a LaTeX [35] formula that
would produce the image. For example:
Future versions of this document will likely favor SVG [10] or MathML
[15] representations of formulae, if browser support and
accessibility concerns are addressed.
6. Security Considerations
Since RFCs are sometimes exchanged outside the normal Web sandboxing
mechanism (e.g. rsync to a mirror) then loaded from a local file,
Hildebrand Expires January 17, 2013 [Page 20]
Internet-Draft HTML RFC Format July 2012
more care must be taken with the HTML than is ordinary on the Web. In
particular, the intent with the format is to forbid any embedded code
such as JavaScript as well as all mechanisms that could be used to
execute code outside of the browser such as plugins or non-static
media (such as video).
7. IANA Considerations
TBD
8. References
8.1. Normative References
[1] Boutell, T., "PNG (Portable Network Graphics) Specification
Version 1.0", RFC 2083, March 1997.
[2] Bradner, S., "Key words for use in RFCs to Indicate Requirement
Levels", BCP 14, RFC 2119, March 1997.
[3] Masinter, L., "The "data" URL scheme", RFC 2397, August 1998.
[4] Yergeau, F., "UTF-8, a transformation format of ISO 10646",
STD 63, RFC 3629, November 2003.
[5] Bradner, S., "Intellectual Property Rights in IETF Technology",
BCP 79, RFC 3979, March 2005.
[6] Bradner, S. and J. Contreras, "Rights Contributors Provide to
the IETF Trust", BCP 78, RFC 5378, November 2008.
[7] Phillips, A. and M. Davis, "Tags for Identifying Languages",
BCP 47, RFC 5646, September 2009.
[8] The Unicode Consortium, "The Unicode Standard, Version 6.1",
2012, <http://www.unicode.org/versions/Unicode6.1.0/>.
[9] Celik, T., Lie, H., Hickson, I., and B. Bos, "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>.
[10] Watt, J., Dahlstroem, E., McCormack, C., Schepers, D., Jun, F.,
Ferraiolo, J., Dengler, P., Grasso, A., Lilley, C., and D.
Jackson, "Scalable Vector Graphics (SVG) 1.1 (Second Edition)",
World Wide Web Consortium Recommendation REC-SVG11-20110816,
Hildebrand Expires January 17, 2013 [Page 21]
Internet-Draft HTML RFC Format July 2012
August 2011, <http://www.w3.org/TR/2011/REC-SVG11-20110816>.
[11] Sperberg-McQueen, C., Yergeau, F., Bray, T., Maler, E., and J.
Paoli, "Extensible Markup Language (XML) 1.0 (Fifth Edition)",
World Wide Web Consortium Recommendation REC-xml-20081126,
November 2008, <http://www.w3.org/TR/2008/REC-xml-20081126>.
[12] Hickson, I., "HTML5", World Wide Web Consortium WD WD-html5-
20120329, March 2012,
<http://www.w3.org/TR/2012/WD-html5-20120329>.
8.2. Informative References
[13] Crocker, D. and P. Overell, "Augmented BNF for Syntax
Specifications: ABNF", STD 68, RFC 5234, January 2008.
[14] Perreault, S., "vCard Format Specification", RFC 6350,
August 2011.
[15] Ion, P., Carlisle, D., and R. Miner, "Mathematical Markup
Language (MathML) Version 3.0", World Wide Web Consortium
Recommendation REC-MathML3-20101021, October 2010,
<http://www.w3.org/TR/2010/REC-MathML3-20101021>.
URIs
[16] <http://www.3gpp.org/>
[17] <http://www.ansi.org/>
[18] <http://www.itu.int/ITU-T/>
[19] <http://www.itl.nist.gov/fipspubs/>
[20] <http://www.ietf.org/id-info/>
[21] <http://www.ieee.org/>
[22] <http://www.iso.org/>
[23] <http://www.itu.int/>
[24] <http://www.nist.gov/>
[25] <http://www.oasis-open.org/>
[26] <http://www.rsa.com/rsalabs/node.asp?id=2124>
Hildebrand Expires January 17, 2013 [Page 22]
Internet-Draft HTML RFC Format July 2012
[27] <http://www.rfc-editor.org/RFCoverview.html>
[28] <http://www.w3.org/>
[29] <http://xmpp.org/>
[30] <http://microformats.org/wiki/hcard>
[31] <http://datatracker.ietf.org/wg/vcarddav/charter/>
[32] <http://microformats.org/wiki/citation>
[33] <http://microformats.org/>
[34] <http://www.websequencediagrams.com/>
[35] <http://www.latex-project.org/>
Appendix A. Allowable Subset of HTML
This section collects all of the elements that are allowed in the
HTML RFC format. Each element is listed with a set of allowed
attributes, and a list of the parent elements in which the element
may be placed. The attributes "class", "id", and "lang" are allowed
on all elements. All other elements, attributes, and nesting
approaches MUST NOT be used.
Hildebrand Expires January 17, 2013 [Page 23]
Internet-Draft HTML RFC Format July 2012
+------------+-----------------+------------------------------------+
| Element | Attributes | Parents |
+------------+-----------------+------------------------------------+
| a | href, title | address, div, figcaption, h2, h3, |
| | | h4, h5, li, p, span, td |
| address | | div |
| blockquote | | div |
| body | | html |
| br | | td, th |
| code | | li, p, td |
| div | | address, body, div, li |
| em | | p |
| figcaption | | figure |
| figure | | div |
| h1 | | body |
| h2 | | div |
| h3 | | div |
| h4 | | div |
| h5 | | div |
| head | | html |
| html | | |
| img | alt, height, | figure |
| | src, width | |
| li | | ol, ul |
| link | href, rel, type | head |
| meta | content, | head |
| | http-equiv, | |
| | name | |
| ol | | div |
| p | | blockquote, div, td |
| pre | | div, figure |
| span | | address, div, li, p, span |
| strong | | p, pre |
| svg | height, | figure |
| | viewbox, width | |
| table | | div, figure |
| tbody | | table |
| td | colspan | tr |
| th | colspan | tr |
| thead | | table |
| title | | head |
| tr | | tbody, thead |
| ul | | div, li, td |
+------------+-----------------+------------------------------------+
Hildebrand Expires January 17, 2013 [Page 24]
Internet-Draft HTML RFC Format July 2012
Appendix B. CSS Classes with Special Meaning
Although the author can add class information to any element, the
following class names have special meaning in an HTML RFC:
+------------------+---------+
| Class | Meaning |
+------------------+---------+
| adr | |
| appendix | |
| ascii | |
| author | |
| authors | |
| code | |
| company | |
| country-name | |
| date | |
| edge | |
| email | |
| expires | |
| family-name | |
| figref | |
| fn | |
| formula | |
| given-name | |
| graph | |
| hidden | |
| identifiers | |
| initial | |
| language-abnf | |
| language-c | |
| language-html | |
| locality | |
| n | |
| nickname | |
| node | |
| note | |
| org | |
| pdu | |
| postal-code | |
| published | |
| ref | |
| reflinks | |
| region | |
| rfc2119 | |
| rfceditor-remove | |
| section | |
| sectref | |
Hildebrand Expires January 17, 2013 [Page 25]
Internet-Draft HTML RFC Format July 2012
| self-ref | |
| sequence | |
| series | |
| series-info | |
| status | |
| street-address | |
| surname | |
| title | |
| toc | |
| trust200902 | |
| vcard | |
| version | |
| workgroup | |
+------------------+---------+
Appendix C. Element IDs with Special Meaning
Although the author can add an "id" attribute to any element, the
following id values SHOULD NOT be used except for the role defined
for each below:
+-----------------+-------------------------------------------------+
| ID | Meaning |
+-----------------+-------------------------------------------------+
| document | Data about the document, including dates, name, |
| | version, etc. |
| title | The title of the document, usually applied to a |
| | <h1> element. |
| abstract | The abstract for the document, usually applied |
| | to a <div> element that contains a heading and |
| | paragraphs of text. |
Hildebrand Expires January 17, 2013 [Page 26]
Internet-Draft HTML RFC Format July 2012
| ipr | The Intellectual Property Rights associated |
| | with the document. The class attribute of the |
| | same element will contain a machine-readable |
| | IPR statement name from this list: |
| | trust200902: This is appropriate for most |
| | drafts, where the entire content of the draft |
| | is written by the draft's authors, or all |
| | authors of other material have given explicit |
| | permission to use their work. |
| | noModificationTrust200902: This is appropriate |
| | for drafts where the authors wish to place the |
| | additional condition that if the draft is |
| | published as an RFC, it must have no changes |
| | other than formatting. An example might be a |
| | document published by another organization that |
| | permits copying but not modification. |
| | noDerivativesTrust200902: This is appropriate |
| | for drafts not intended to be published as |
| | RFCs. pre5378Trust200902: This is appropriate |
| | for drafts that include material submitted to |
| | the IETF prior to RFC 5378 (10 Nov 2008), where |
| | the authors of that material have not given |
| | explicit permission to use their work in this |
| | draft. An example might be a draft using |
| | material from an RFC whose author has died or |
| | cannot be located, or who thinks your draft is |
| | stupid. The element with this id will contain |
| | all of the IPR and status boilerplate text |
| | Note: an IANA registry may be required for |
| | this attribute in the future. |
| venue | The venue for discussion. Inside the element |
| | tagged with this id will be one or more <a> |
| | elements that describe the discussion venue for |
| | Internet-Drafts. |
| toc | The Table of Contents |
| references | The section containing bibliographical data, |
| | including sections for normative and |
| | informative references. |
| normative | The section containing normative document |
| | references. |
| informative | The section containing informative document |
| | references. |
| authors | The section containing data about the authors |
| | of the document. |
| security | The section containing the Security |
| | Considerations for the document. |
| iana | The section containing the IANA Considerations |
| | for the document. |
Hildebrand Expires January 17, 2013 [Page 27]
Internet-Draft HTML RFC Format July 2012
| acknowledgments | The section containing the author's |
| | acknowledgments. |
+-----------------+-------------------------------------------------+
Appendix D. Acknowledgments
The author gratefully acknowledges the contributions of: Heather
Flanagan and Patrick Linskey
Author's Address
Joe Hildebrand
Cisco Systems, Inc.
1899 Wynkoop St, Suite 600
Denver, CO 80202
United States
Email: jhildebr@cisco.com
Hildebrand Expires January 17, 2013 [Page 28]