HyperText Markup Language Request For Comments Format
draft-hildebrand-html-rfc-03

Abstract

This document defines the HTML format that should be used for the production of Internet-Drafts and RFCs. The HTML output will include a default CSS to enable page layout, and the HTML itself includes semantic information only. This format will be rendered from the canonical XML format for an RFC.

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 December 8, 2014.

Copyright Notice

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

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.

In 2013, after a great deal of community discussion, the decision was made to shift from the plain text, ASCII-only canonical format to XML [I-D.hoffman-xml2rfc]. Several different publication formats will be rendered from that canonical XML, including HTML, PDF, TXT, and EPUB.

This memo describes an HTML format that will be used as one of the publication formats for the RFC Series. It defines a strict subset of HTML appropriate for Internet-Draft and RFC Series documents, and serves as a comprehensive example of all of the HTML elements that are permissible. The CSS that defines the visual layout, while included in the HTML file, will be described in a separate document [W3C.REC-CSS2-20110607]. The HTML itself will represent semantic information only.

1.2. Terminology

In this document, the key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" are to be interpreted as described in BCP 14, RFC 2119 [RFC2119].

2. Requirements for HTML

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.

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.

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 e-mail) and have the result look the same.

The HTML must display adequately in at least one text-based browser. Any use of javascript must not negatively impact the ability to read the document.

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.

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 [W3C.CR-html5-20130806], such as table column widths.

The HTML must make it easy to separate chunks into separate files. This will make creating EPUB documents easier in the future.

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.

The HTML must not have any Javascript or other active code in <script> or <object> tags.

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.

The abstract must be marked up or tagged in a way that search engines will extract it as summary.

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 difficult;y 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.

The HTML document does not require the inclusion of non-semantic information such as comments and processor instructions.

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:

• The HTML source MUST be encoded as UTF-8, as specified in RFC3629. Note that RFC3629 forbids "surrogate" codepoints in the range U+D800 to U+DFFF.
• The document MUST be valid HTML5.
• Single quotes (U+0027 APOSTROPHE: ') MUST be used to quote attribute values. Unquoted attribute values MUST NOT be used.
• Each logical line MUST be terminated solely with a \n (U+000A: LINE FEED), otherwise known as "Unix-style" line endings.
• 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.
• Each text-containing element such as headings (<h1>-<h6>), paragraphs (<p>), or list items (<li>), MUST be serialized as a single line without wrapping.
• The contents of <pre> elements MUST NOT be modified by processing tools. The following rules apply to all elements except for <pre>:
  • HTML SHALL be indented using spaces (not tabs).
  • 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.

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. The document will start with exactly this string:

<!DOCTYPE html'>

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 will not be generated by the rendering agent from the canonical XML.

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

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

Reference format must follow the guidance in the RFC Style Guide [I-D.iab-styleguide].

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):

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

<pre class='code language-html'>
&lt;html&gt;
  &lt; /&gt;
&lt;/html&gt;
</pre>

<html>
  < />
</html>

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

<figure>
  <pre class='ascii'>

                +-----------+
                | original  | &lt;+
                +-----------+  |
                  |            |
                  | nit        | edit
                  v            |
  nit (no-op)   +-----------+  |
+-------------- |           |  |
|               | canonical |  |
+-------------&gt; |           | -+
                +-----------+

  </pre>
  <figcaption>Sample ASCII art</figcaption>
</figure>

<figure>
  <figcaption>Sample packet format</figcaption>
  <table class='pdu'> [table describing the packet] </table>
</figure>

<div id='example'>Important Text</div>

<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'>03</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>

<h1 id='title'>HTML RFC Format</h1>

<div id='abstract'>
  <h2>Abstract</h2>
  <p>This document defines an HTML format...</p>
</div>

<div id='ipr' class='trust200902'>
  <h2>Status of this Memo</h2>
  <p>...</p>
  <h2>Copyright Notice</h2>
  <p>...</p>
</div>

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

#include \<stdio.h\>
int main(int argc, char **argv)
{
    printf("Hello, IETF\n");
    return 0;
}

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

title Authentication Sequence Alice->Bob: Authentication 
Request note right of Bob: Bob thinks about it Bob->Alice: 
Authentication Response 

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