Network Working Group
Internet-Draft
Standards Track
2013-11-01
2014-05-01
draft-hildebrand-html-rfc
01
J. Hildebrand Cisco Systems, Inc.

HyperText Markup Language Request For Comments Format

Abstract

This document defines an HTML format that can be used for the production of Internet-Drafts and RFCs.

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 May 01, 2014.

Copyright Notice

Copyright © 2013 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 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 the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.

Editorial Notes

Distribution of this document is unlimited. Please send comments to RFC Interest.

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.html.

Disclaimer: This is just a first pass at the syntax. The author is willing to add, remove, or change any of the markup used expressly or implicitly in this document. Furthermore, the author does not claim that the current CSS used for this document is useful, interesting, or anything like what the RFC editor may eventually pick.

Table of Contents

1. Introduction

1.1. Background

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 exist for several reasons:

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:

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:

1.2. Overview

This memo describes a format that can be used as an archival output format for RFCs, and 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. Requirements

  1. The HTML has to render correctly on the following:

    • the latest released versions of Chrome, Firefox, and IE running on Windows 8 in November 2013
    • the latest released versions of Chrome, Firefox, and Safari running on Mac OS X 10.9 in November 2013
    • the latest released versions of Chrome and Safari running on iOS 7 in November 2013
    • the latest released versions of Chrome and Firefox running on Ubuntu 13.10 in November 2013
    • the latest released versions of Chrome and Firefox running on Android 4.1 in November 2013

    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 earlier versions.

  2. The HTML document must preserve all semantic information that is in the canonical XML document. One use case is that preformatted text that has different tags in the XML will also be differentiable in the HTML, making it trivial to extract all of the (for example) ABNF in an RFC with a simple program. Another use case is that someone who wants to write programs that will extract information from an RFC can do so equally well with the XML and HTML, and can choose the tool that uses one or the other format for input.
  3. A non-requirement is that the HTML document have any non-semantic information such as comments and processor instructions. (This non-requirement should be removed if they are not allowed the XML.)
  4. The HTML document must come with a default internal set of CSS formatting. This will allow for a mostly-consistent display of RFCs across browsers. It will also allow for the HTML file to be moved over different transports (such as mail) and have the result look the same.
  5. The HTML must display adequately in at least one text-based browser.
  6. The HTML document must 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 have custom CSS.
  7. No HTML tags in the document may have style information. All style information must be done through "class" and "id" attributes, with the style for those represented in the CSS alone. Exceptions can be made for formatting that is not possible in any other way in HTML5, such as table column widths.
  8. The HTML must make it easy to separate chunks into separate files. This will make creating EPUB documents easier in the future.
  9. The output needs to be HTML5. Language extensions might be acceptable after further discussion. The RFC Editor will use an automated validating tool before publishing the HTML. This requirement is not important for viewing with browsers, but is important for programs that will use the HTML format as input for processing.
  10. The HTML must not have any Javascript or other active code in <script> or <object> tags.
  11. All section, 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 as well.
  12. The abstract must be marked up or tagged in a way that search engines will extract it as summary.
  13. 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
    • Other groups TBD

    Specific instances where these goals 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 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:

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 time of publishing, starting with the version commonly known as HTML5. 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. For better backward-compatibility, the about:legacy-compat system DTD should be specified. Therefore the document will start with exactly this string:

<!DOCTYPE html SYSTEM 'about:legacy-compat'>

The SYSTEM 'about:legacy-compat' portion MAY be dropped in the future if the tooling chosen to produce this format does not require it.

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 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 charset attribute with value utf-8. This will look like:

<meta charset='utf-8' />

3.2.5. Style

The <head> SHOULD contain an embedded CSS 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>.

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 <em> element, usually rendered as italics. Strong emphasis may be donated with the <strong> element, which is usually rendered as boldface. Underlining MUST NOT be used except for links, to avoid visual confusion. Text-only emphasis such as "*bold*" 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.

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: HTML5 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>
</div>

Parent sections that contain child sections MUST NOT contain "normal" paragraphs after a sub-section. For example, the following is invalid:

<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>
  </div>
  <p>BAD PROSE!</p>
</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, 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 <div> or an appendix <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:

<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 entry; the href MUST be of the form #[series]:[number]. For example:

href='#rfc:2119'

Valid series identifiers include:

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='#rfc:2119'>RFC2119</a>

Informative references MUST use <a> elements with class inforef. Example:

See: <a class='inforef' href='#rfc:2119'>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.2.13. Quotes

Non-trivial direct quotes from other documents SHOULD use the <blockquote> element. If the quote needs a citation, wrap the <blockquote> in a <figure> and add a <figcaption> element that contains text (and possibly links) that describe the quote. For example, this code:

<figure>
  <blockquote>
    <p>Here a <code>blockquote</code> element
    is used in conjunction with a <code>figure</code> element and
    its <code>figcaption</code> to clearly relate a quote to its
    attribution (which is not part of the quote and therefore doesn't belong
    inside the <code>blockquote</code> itself):</p>
  </blockquote>
  <figcaption>Sample Quote from <a class='ref' href='#w3c:CR-html5-20130806'>HTML5</a>,
    section 4.5.4</figcaption>
</figure>

Would render as:

Here a blockquote element is used in conjunction with a figure element and its figcaption to clearly relate a quote to its attribution (which is not part of the quote and therefore doesn't belong inside the blockquote itself):
Figure 1. Sample Quote from HTML5, section 4.5.4

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 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 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 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 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 themselves SHOULD contain all of the data that is required.

3.3.4. SVG

SVG can be included directly in the HTML source, surrounded by a <figure> element and succeeded by a <figcaption> element, as described in Section . 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:

A sample SVG This is a sample image, with a title and description nit_flow original original canonical canonical original->canonical nit canonical->original edit canonical->canonical nit (no-op)
Figure 2. Sample SVG

The SVG included MUST be from a subset of TinySVG that excludes the following features:

  • Multimedia
  • Interactivity
  • Scripting
  • Animation
  • Extensibility

3.3.5. 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'>&lt;code&gt;</code> element

3.3.6. 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'>
&lt;html&gt;
  &lt;body /&gt;
&lt;/html&gt;
</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.

<figure id='blockfigure'>
<pre class='code language-html'></pre>
<figcaption>A code block wrapped in a figure.</figcaption>
</figure>
Figure 3. A code block wrapped in a figure.

3.3.7. ASCII Art

ASCII art is still preferred by some authors in preference to an image or SVG. The RFC Editor may decide to prefer SVG, 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 Section 3.3.4 image. For example:

<figure>
  <pre class='ascii'>
                  +-----------+
                  | original  | &lt;+
                  +-----------+  |
                    |            |
                    | nit        | edit
                    v            |
    nit (no-op)   +-----------+  |
  +-------------- |           |  |
  |               | canonical |  |
  +-------------&gt; |           | -+
                  +-----------+
  </pre>
  <figcaption>Sample ASCII art</figcaption>
</figure>
          
                  +-----------+
                  | original  | <+
                  +-----------+  |
                    |            |
                    | nit        | edit
                    v            |
    nit (no-op)   +-----------+  |
  +-------------- |           |  |
  |               | canonical |  |
  +-------------> |           | -+
                  +-----------+
Figure 4. Sample ASCII art

3.3.8. 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 . 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:

Figure 5. Sample packet format
Offsets Octet 0 1 2 3
Octet Bit 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31
0 0 version header len differentiated services ECN length
4 32 identification R
S
V
D
F
M
F
fragment offset
8 64 source IP
12 96 destination IP
16
...
128
...
options
...

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-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 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>
</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. 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. 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. 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 along with their boilerplate expansions?

4.5. Author

NOTE: this document currently uses the approach specified by "hCard". The author recommends that the vcarddav Working Group of the IETF be tasked to propose an approach for HTML embedding of vCard that is aligned with RFC 6350. In particular, the language and altid mechanisms of RFC 6350 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 Section 9.

<address class='vcard'>
  <span class='n hidden'>
    <span class='family-name'>Hildebrand</span>
    <span class='given-name'>Joe</span>
  </span>
  <span class='nickname hidden'>hildjj</span>
  <span class='fn'>Joe Hildebrand</span>
  <span class='org'>Cisco Systems, Inc.</span>
  <a class='email' href='jhildebr@cisco.com'>jhildebr@cisco.com</a>
  <div class='adr'>
    <div class='street-address'>1899 Wynkoop St, Suite 600</div>
    <div><span class='locality'>Denver</span>, <span class='region'>CO</span> <span class='postal-code'>80202</span></div>
    <div class='country-name'>United States</div>
  </div>
</address>
Figure 6. Sample (temporary) author information

4.6. Bibliographical Information

TBD: define microformat for bibliographical data, perhaps based on the citation work at microformats.org.

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 source for the diagram.

Before publication, this approach will be replaced by something more well-specified and not requiring third-party software.

<figure>
  <img class='sequence' alt='
title Authentication Sequence
Alice-&gt;Bob: Authentication Request
note right of Bob: Bob thinks about it
Bob-&gt;Alice: Authentication Response' />
  <figcaption>A sample sequence diagram</figcaption>
</figure>

title Authentication Sequence
Alice->Bob: Authentication Request
note right of Bob: Bob thinks about it
Bob->Alice: Authentication Response
Figure 7. A sample sequence diagram

5.4. ABNF

Augmented Backus-Naur Form is a way of describing formal syntax, described in RFC5234. 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

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, 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

8.2. Informative References

9. Authors' Addresses

Joe Hildebrand Cisco Systems, Inc.
1899 Wynkoop St, Suite 600
Denver, CO 80202
United States

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.

Element Attributes Parents
a href, title address, div, figcaption, h2, h3, h4, h5, li, p, span, td
address div
blockquote figure
body html
br td, th
code blockquote, li, p, td
div address, body, div, li
em p, span
figcaption figure
figure div
h1 body
h2 div
h3 div
h4 div
h5 div
head html
html
img alt, height, src, width figure
li 1, 1.0, 1.1, 10, 10646-1, 16, 2, 2026, 2026., 206, 2119., 2418., 2739., 3.2, 329, 3978, 4, 4748, 495, 617, 79, a, abbrev, abnf, abnf., about, additional, all, alpha, also, alto, among, an, analyzer, and, any, applications, are, as, at, audio, augmented, authors, available, backus-naur, balances, bcp, be, been, beginning, benefit, best, between, bnf, both, box, but, by, called, can, capitalized., cases, channel., character, characteristic, checking, chromaticity, color, common, communities, community, compactness, compatibility, compatible, concerning, constraints, contributions, contributors, core, coyote, creation, current, data, data-xml, day, define, defines, definitions, delivery, depths, described, describes, designed, desirable, details, detection, developed, development, differences, discussion, display, document, document:, documents, documents., email, encoding, encodings, encompasses, ensure, entities, errors., exchanging, extensible, extensions, file, follow, for, force, form, formal, format, formatted, from, full, fullname, fully, gamma, gif, graphics, groups, guidelines, has, have, heterogeneous, hill, holders., how, identifying, iec, ietf, ietf., image, images, images., improved, in, including, incorporate, indicate, individuals, information, initials, integrity, intellectual, intended, interchange., internet, interpreted, involve, ipr, is, iso, it, key, language, large, led, legitimate, level, lexical, made, many, markup, mass., matching, may, media, meet., memo, memo., modified, month, most, much, multiple, must, name, naming, near, need, network, not, note, object, object., objectives, obsoletes, octets, of, often, on, online, option., optional, originally, other, over, palo, paragraph, parsers, participants, patent, patent-free, permitting, phrase, plus, png, policies, popular, possible., power., practices, preserving, private, progressive, property, proposal, proposed, provide, provides, providing, public, range, ranges., raster, reasonable, recommended, reference, register, related, relative, rely, replace, replacement, replaces, representational, representing, requests, required, requirement, requirements, research, respecting, retain, revision, rfc, rfc2083, rfc2119, rfc2397, rfc3629, rfc3979, rfc5234, rfc5378, rfc5646, rfc6350, rfcs, rights, rule, s, sample, section, semantics, set, several, shall, sheets, should, signify, simple, simplicity, so, software, specification, specification., specifications, specifications., specifications:, specifies, standard, standards, storage, store, streamable, structured, style, such, suggestions, supplies, surname, syntax, syntax., systems., tags, target, technical, technologies, technology, telephone, that, the, their, these, they, this, tiff., to, track, transformation, transmission, transparent, truecolor, type, universal, updates, url, us-ascii, use, used, used., user-defined, uses, utf-8, value, values, values., variety, vcard, vector, version, viewing, w3c.rec-css2-20110607, w3c.rec-mathml3-20101021, w3c.rec-svg11-20110816, w3c.rec-xml-20081126, well, well-compressed, were, where, which, while, who, wide, with, within, words, work, worked, working, world, writing, year ol, ul
meta charset, content, name head
ol div
p div, li, td
pre div, figure
span address, div, li, p, span
strong p, pre
svg height, viewbox, width figure
table div, figure
tbody table
td colspan tr
th colspan tr
thead table
title head
tr tbody, thead
ul div, li, td, ul

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
docName
edge
email
expires
family-name
figref
fn
given-name
graph
hidden
identifiers
initial
initials
invalid
languag-hmtl
language-abnf
language-c
language-html
locality
n
nickname
node
note
org
pdu
postal-code
published
ref
reflinks
region
rfc2119
rfceditor-remove
section
sectref
self-ref
sequence
series
series-info
status
street-address
surname
title
toc
todo
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.
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.
acknowledgments The section containing the author's acknowledgments.

Appendix D. Acknowledgments

The author gratefully acknowledges the contributions of: Heather Flanagan and Patrick Linskey