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
"
"), or list items ("
" element. For example:
This is a description of the example
This is a description of the nested section.
This is the second description paragraph.
The author gratefully acknowledges the contributions of...
These people contributed text...
". 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 "
" element. Unordered lists ("
An explanation:
...