Writing I-Ds using HTML
draft-hallambaker-rfctool-03

Abstract

This memo presents a technique for using as subset HTML as a source format for documents in the Internet-Drafts (I-Ds) and Request for Comments (RFC) series. The HTML subset provides equivalent functionality to the traditional XML2RFC tool but is designed for ease of use with readily available editing tools.

Extensions to the HTML markup allow the use of external bibliography files to manage citations and references in the manner of BibTeX. Planned extensions include building concordances of defined terms and normative language.

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 April 30, 2015.

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. Why a New Format is Needed.

One of the more difficult aspects of working in the IETF is producing Internet Drafts that comply with the IETF formating criteria originally developed in the age of valve tube machines.

HTML2RFC is a HTML microformat for Internet Drafts (and RFCs). Documents written in the HTML2RFC microformat may be converted to a variety of target formats that currently include Internet Draft Plaintext [RFC2223], XML2RFC [RFC2629] and HTML in the IETF presentation stylesheet.

While existing tools enable the generation of documents in Internet Draft format, none provide the features necessary to allow the document editor to focus on the task of editing text rather than dealling with the distraction of producing text in the obligated format.

One area in which all recent document formats fall short is in the management of references in citations. While the online citation libraries introduced in XML2RFC are exceptionally useful, accessing them though XML entities or cut-and-paste of the citation sources is tedious and error prone. Patashnik and Lamport demonstrated a much superior system in 1985 in BibTeX.[BibTeX].

1.1. Why Existing Tools Fail

[RFC2629] which describes the XML2RFC tool was published in 1999, a time when XML was the document format of the future. Although advanced XML editing tools were expensive with poor usuability, this deficiency was expected to be resolved in the very near future. [RFC2629] did not make editing Internet Drafts easy but it was better than the available alternatives and made it possible to produce documents in both the plaintext format required for Internet Draft subissions and readable formats such as HTML.

Almost fifteen years later, XML document authoring tools are still expensive and none of the many tools the author has tried offers more than a modest improvement over editing XML source by hand. The tools merely make it a little easier to enter XML tags. The author is still required to remember the many idiosyncracies of the XML2RFC DTD which uses a mixture of case conventions (hangText vs texttable) and oddly chosen tag and attribute names. The only consistency in the design of the DTD is that it follows none of the conventions established in HTML. Even the paragraph tag is inexplicably labelled <t>.

Another area in which use of [RFC2629] is unsatisfactory is in the handling of citatitions and references. While the online library of references is certainly very useful, making use of it in a document is fiddly and time consuming. Citations must be managed in three separate parts of the document. Entity declarations linking to the external reference declarations are inserted at the top of the file while the citation is added to the end of the file. To create a reference to the citation in the body of the text we must create a crosslink to the anchor defined inside the external reference which may or may not be the same as the entity name defining the reference.

The method of handling references makes it difficult to prepare documents in offline environments (e.g. a plane) and can cause editing tools that attempt DTD validation to behave slowly or unpredictably as attempts are made to retrieve the external content while the file is being edited.

1.2. Why HTML is Better

One of the principal reasons that HTML has become the most widely used document markup format is that the basic structure markup is very simple and can be learned in a few minutes. Virtually every modern text editor offers at least the ability to generate HTML as an output markup. A wide range of HTML editing tools is available for every modern computing platform. Many of the best tools are free.

While entering HTML tags is easy, editing or reviewing text that is cluttered with markup tags is unnecessarily tedious and error prone. Editing a document describing a XML protocol in raw XML source form is particularly error prone as every occurrence of an XML markup character must be escaped, often rendering the text almost unreadable. Many HTML editors allow the editor to view source and formatted views of their document side by side or quickly switch from one to the other. This is much more efficient than trying to edit XML that is converted into readable text by a stylesheet.

The original HTML 2.0 markup described in [RFC1866] was intended to provide a means of describing the document structure. The most recent edition, HTML 5 [W3C.CR-html5-20121217] is considerably more complicated, offering a melange of structure, format, style and scripting features. Fortunately almost all the requirements of HTML2RFC are met by features of the original HTML 2.0 markup that have not been updated or obsoleted since.

1.3. Markdown Format Should be considered

Although HTML is widely supported by WYSIWYG editors, many authors favor an even simpler format. RFCs largely consist of text, section headings and bulleted lists, the popular markdown format is thus capable of meeting 90% of formatiing needs.

The traditional 'plaintext' RFC format, while excrable as a presentation format is servicable as an input format. If the markdown format was choosen carfully, it might accept traditional RFCs as input. [?Appendix] provides a trial sketch of such a scheme.

1.4. The Need to Combine XML2RFC and BibTeX Reference Management

One of the key innovations introduced in [BibTeX] was the ability to separate the tasks of document editing and bibliography management. Once compiled, a bibliography could be shared between multiple documents or even multiple users. It is not uncommon for a good bibliography file to be shared by whole university departments.

The reference management feature of xml2rfc also provides considerable advantages over previous approaches. The online library of reference descriptions is maintained by automatic tools eliminating the need to enter most entries manually. While the xml.resoure.org repository hardly exhaustive it is rare that an Internet Draft contains more than one or two citations that are outside its scope.

The major drawback to the xml2rfc approach is that the online tool fails completely when editing documents in offline mode. Authors can maintain a local cache of references they use in their own documents but they must develop the necessary tools to do so themselves.

HTML2RFC combines the advantages of the BibTeX and xml2rfc approaches. The string [!RFC1149] within the text declares a normative reference to RFC1149 while [~RFC1149] declares an informative reference. The HTML2RFC tool attempts to resolve references by consulting a local bibliography file. Unresolved references are then resolved through a set of (extensible) rules and (optionally) appended to one or more of the user's personal bibliography files. For example, citation labels that begin with the prefix 'RFC' may be resolved by a HTTP query to the xml.resource.org repository.

2. Document Markup

* Basics - elements are defined by tags,

* Elements may have attributes but these are used sparingly. In particular HTML markup conventions require that text which is normally displayed to the user be entered as element content rather than as attributes.

* character entities are used to escape the markup characters

* Except in the <pre> element, multiple spaces are collapsed to single spaces. To prevent whitespace folding, use the &nbsp; tag.

* Every HTML document must contain the following elements:

<?xml ?>
<html>
  <head>
    <title>The document title (displayed in the window frame)</title>
  <body>

    <!-- Document text goes inside here -->

  </body>
</html>

Although the HTML markup requires that a <title> element be present, the term title is understood to be text to be shown in 'title bar' of the window frame in which the document is displayed. HTML2RFC uses the first <h1> tag in the document to display the title instead as this is guaranteed to be displayed prominently in a HTML text editor while many do not bother to show the <title> element contents at all.

Following the convention established by xml2rfc, HTML2RFC divides the RFC content into front, middle and back sections. These are delimited by <h1> heading elements as follows:

Front

The front matter begins with the first <h1> element and ends at the second <h1> element.

Middle

The middle matter begins with the second <h1> element and ends at the first <h1> element with a heading that begins with the string 'Appendix:'.

Back

The back matter begins with he first <h1> element with a heading that begins with the string 'Appendix:' and runs to the end of the document.

It is not necessary to create sectionsfor References or Authors' Addresses, these will be included and given appropriate titles as necessary. The outline of an HTML2RFC document is therefore:

<?xml ?>
<html>
  <head>
    <title>The document title (displayed in the window frame)</title>
  <body>
    <h1>Document Title</h1>            <!-- Start of Front Matter -->
      <!- Document abstract, metadata and author details go here -->
      <p>First paragraph of document abstract</p>
      <p>Second paragraph of document abstract</p>
    <h1>First section</h1>            <!-- Start of Middle Matter -->
      <p>First paragraph</p>
    <h1>First section</h1>
    <h1>Second section</h1>
    <h1>Appendix:First appendix</h1>
    <h1>Second appendix</h1>
  </body>
</html>

Document structure in HTML is infered from the placement of heading elements. This approach is considerably easier to manage and less error prone than the xml2rfc approach which requires the author to correctly mark the beginning and the end of each section.

3. Document Text

HTML2RFC uses only the core HTML markup designed for declaring document structure: <h1> ... <h6>, <p>, <pre>, <ul>, <ol>, <dl>, <li>, <dt>, <dd>, <table>, <th>, <tr>, <th>, <td>.

Only the id attribute is currently recognized, all other attributes are discarded or overwritten.

Although HTML provides most of the prinitives required to markup an RFC, it does not provide the necessary tags to markup the text that appears at the front of an Internet Draft, the author names, document type and other information that is presented in the masthead and opening section. This information is declared in HTML2RFC using a 'microformat' a stylized method of using HTML tags.

This section describes the use of standard HTML markup tags to define the document structure. The microformat is described in [?Section] following. The use of the id attribute to create references to document sections is described in [?Section]

3.1. Headings

The <h1>, <h2, <h3>, <h4>, <h5>, <h6> elements specify section headings. The element content is the heading text. Document section and appendix numbers are added automatically.

The first and second <h1> element in the document are special. The first <h1> element specifies the title of the document and begins the document properties microformat section described below. The second <h1> element marks the end of the document properties microformat and the beginning of the document proper.

A <h1> element with heading text that begins with the string 'Appendix:' is an appendix heading. Once one appendix heading is encountered in a document, all the following <h1> elements are interpreted as appendix headings whether they begin with the string 'Appendix:' or not.

3.2. Paragraphs

The <p> and <pre> elements specify paragraphs. <p> elements specify ordinary paragraphs that will be formatted by the processing tool while the <pre> element is used for preformatted text such as code examples where spaces must be preserved.

3.3. Lists

The <ul> element specifies an unordered list (aka bullet point). Each list item is specified by a list item <li> element:

<ul>
  <li>A list item</li>
  <li>Another list item</li>
  <li>Yet another list item</li>
</ul>

To create an ordered list (aka numbered), the <ol> element is used instead:

<ol>
  <li>This list item will be number 1</li>
  <li>This list item will be number 2</li>
  <li>This list item will be number 3</li>
</ol>

Definition list <dl> elements contain lists of defined term <dt> and defined data <dd> tags. Although the formatting of <dt> and <dd> elements strongly sugests that they are pairs, HTML permits them to appear in any order.

<dl>
  <dt>Defined Term #1</dt>
  <dd>Definition of term #1</dd>
  <dt>Defined Term #2</dt>
  <dd>Definition of term #2</dd> 
</dl>

Lists may be nested in lists to create a hierachy. The inner list type may be the same as the type of the enclosing list or a different type.

3.4. Tables

Due to the need to support conversion to IETF Plaintext and xml2rfc formats, the html2rfc table model is considerably simpler than the html model. The colspan and rowspan attributes are ignored and the width attribute is currently unimplemented.

The <table> element specifies a table. A table element may contain only <tr> and <caption> elements. Each <tr> element specfies a row of the table. The optional <caption> element specifies a title for the table. The <caption> element is only permitted as the first and/or last element in the list:

<table>
  <caption>Table title</caption>
  <tr> .. .. .. </tr>
  <tr> .. .. .. </tr>
  <tr> .. .. .. </tr>
  <tr> .. .. .. </tr>
  <caption>Table title</caption>
</table>

Table cells are specified using the <th> or <td> elements. <th> elements specify heading cells, <td> elements specify cells in the body of the table. If the first row of a table contains at least one <th> cell, the header will be repeated at the head of each page if the table is split across pages. Note that while the formatting tool may split a table so that different rows are presented on different pages, a page boundary will not be placed in the middle of a row unless the cell is too long to present any other way.

4. Document Properties Microformat.

The document properties are specified in the front matter which begins with the first <h1> heading and ends with the second <h1> heading.

The only HTML elements permitted within the front matter are <p>, <dl>, <dt> and <dd>. All other tags are ignored but may raise warnings.

4.1. Abstract

The document abstract is specified using <p> elements. <p> elements that are empty or only contain whitespace are ignored. All other <p> elements specify a paragraph of the abstract. Since Internet Drafts are required to provide an abstract, at least one <p> element that contains text is required.

4.2. Document Properties

Document properties are tag value pairs specified using a definition list <dl> element. Each <dt> element specifies a tag and each <dd> element a value. Some document properties permit a list of values to be specified. A document can only have one file name but it can have multiple keywords. When there are multiple values for the same property, it is only necessary to specify the tag once as successive <dd> elements specify values for the tag specified in the last <dt> element encountered.

The document properties for this document are specified as follows:

<dl>
  <dt>Abrrev</dt>     <dd>Writing I-Ds using HTML</dd> 
  <dt>Docname</dt>    <dd>draft-hallambaker-html2rfc</dd> 
  <dt>Version</dt>    <dd>00</dd> 
  <dt>Area</dt>       <dd>General</dd> 
  <dt>Keyword</dt>    <dd>RFC</dd> 
                      <dd>Request For Comments</dd> 
  <dt>IPR</dt>        <dd>trust200902</dd> 
  <dt>Category</dt>   <dd>std</dd>
</dl>

The document properties have been formatted in tabular form to help comprehension but this is not necessary.

Each document property is specified by means of a case insensitive tag. In most cases the document property tag is the same as the corresponding xml2rfc element or attribute. Although most authors are likely to need to consult the documentation when specifying document properties, this is considered to be acceptable as the need to add properties to an existing document is relatively infrequent.

4.2.1. IPR Values

The IPR property specifies a label which will eventually identify a set of boilerplate text that can be imported from an external file. This will avoid the need for users to update their document authoring tools in response to changes in IETF policy.

4.2.2. Category

[TBS]

4.3. Authors

Authors are specified in the same way as the document properties. The author properties are specified as follows:

In practice the Author, surname, initials, organization and email are usually sufficient.

5. Advanced Markup.

In addition to making existing document editing tasks easier, HTML2RFC adds several new features to make maintaining a standards document easier:

• Documents may be split into multiple files facilitating use of automatically generated content.
• Citations specified in the body of the text are detected automatically and resolved to generate the necessary references.
• Concodances of defined terms and normative text may be generated.

5.1. Including Text From External Sources.

5.1.1. <?Include?> Processing Directive

The <?include?> Processing directive is used to include text from an external source. The directive takes two attributes:

file

The file name

format

The file format, xml or txt

The text from the included document is inserted at the current position in the file

In the following example, the text for Sections four and five are inserted from an external file.

<h1>Section Three</h1>
<?include file="generated.xml" format="xml"?>
<h1>Section Six</h1>

The include file processing directive is useful for combining sections of text that are either generated or verified by automatic tools.

The format parameter is intended to allow the processing tool to perform appropriate format conversion as the text is included. At present only XML fragments are supported.

Since the semantics of the processing directive are only understood by the document processing tools and are disregarded by text editors, a HTML2RFC document that includes <?include?> processing directives MUST be a well formed HTML document both before and after the external document is inserted.

One of the main advantages of moving from the XML2RFC model of specifying sections as nested XML elements to the HTML model of infering section boundaries from headings is that it makes the use of text from included files considerably more flexible.

The following format types are reserved for future use:

5.1.2. <?stylesheet?> Processing Directive

The <?stylesheet?> processing directive takes the same file= attribute as the <?include?> directive except that the directive is only processed when generating HTML output in which case the included file MUST contain a CSS stylesheet and the text is copied to the output file directly to a <style> element in the HTML <head> element.

5.2. References and Citations.

5.2.1. Citations

Citations in the body of the text are specified by means of a citation marker. The citation marker tells the document processor

• That a citation label is about to follow
• That the citation is normative or informative
• The label to be used to retrieve the corresponding reference from the bibliographic sources
• (optional) The preferred citation tag to use in the final text

Each reference is identified by means of a text label. For convenience the documents commonly referenced in IETF specifications have compact predfined labels. For example, [RFC0822] has the label RFC0822.

Citation markers have the following forms:

[.!label]

Normative reference to the reference 'label' to be presented as [label] in the final text.

[.!label/tag]

Normative reference to the reference 'label' to be presented as [tag] in the final text.

[.~label]

Informative reference to the reference 'label' to be presented as [label] in the final text.

[.~label/tag]

Informative reference to the reference 'label' to be presented as [tag] in the final text.

The document processing tool automatically resolves the citation labels to references and presents them as lists of normative and informative references.

If a document contains a normative and an informative reference to the same document, the reference is listed in the normative references section.

5.2.2. Resolving Citation Labels

Citation labels are resolved by consulting a bibliography file or bibliographic source. HTML2RFC documents may declare bibliography files and bibliographic sources by means of processing instructions. Document processing tools May consult additional built in bibliographic sources. The order of precedence for resolving bibliographic sources is:

1. Bibliography files in the order they are declared in the source document
2. Bibliographic sources in the order they are declared in the source document
3. Bibliographic sources built in to the processing tool

Bibliography files are XML fragments that contain a list of xml2rfc <reference> elements, each of which defines a single reference. The <?bibliography?> processing instruction declares a bibliography file to be searched to resolve references.

file

The filename of the bibliography to be searched

format

The format of the bibliography to be searched

cached

If present, the document processor will append any references returned from one of the bibliographic sources to the end of the file at the end of document processing.

Use of the cached attribute allows references fetched from bibliographic souces to be saved for future use.

Rather than risk inserting new references into the middle of a file, the tool appends new reference entries to the end. Since the XML specification requires that an XML document only have one toplevel document, this means that the bibliography files are actually XML fragments rather than XML documents and some XML editing tools may present the user with tedious and unnecessary warnings.

The html2rfc tool has the following bibliographic sources built in:

One of the main objectives in designing a tool that can be used to produce documents for multiple standards development organizations is to encourage other organizations to maintain bibliographic source servers providing access to authoritative versions of the documents.

5.2.3. <?bibsource?> Processing Directive

The <?bibsource?> processing directive allows additional bibliographic sources to be defined. A bibliographic source is simply a Web server that responds to a GET request to fetch the content corresponding to a URI formed from the citation label by performing a set of predefined processing rules.

Users are not expected to need to use the <?bibsource?> processing directive as the html2rfc tool contains built in rules to access all the known bibliographic sources the tool is currently capable of reading.

prefix

Specifies the labels that may be resolved through this source. The source will be used to resolve unresolved labels that start with the specified prefix.

uri

A URI pattern to be expanded to form the URI to be used to attempt resolution of the reference.

A bibliographic source is only queried if the citation label matches the prefis specified. For example, a bibliographic source with the prefix 'RFC' will be queried to attempt resolution of the citation label RFC822 but not the label draft-hallambaker-html2rfc.

The uri attribute actually specifies a URI matching pattern. The URI matching pattern may contain one or two hash '#' characters.

If one hash character is specified, it is replaced by the portion of the citation label that follows the prefix. If the citation label is RFC822 and the prefix is 'RFC', a single hash character will be replaced by the string '822'.

Several of the bibliographic sources at xml.resource.org have filenames in which the document number of numbered documents are padded with preceeding zeros. While this maintains the correct collation order for directory listings and the like, the simple character susbstitution mechanism would break unless we remembered to use RFC0822 as the citation label.

More complicated substitution capabilities may be attempted by specifying a C# string formatting directive in between two hash marks. For example the matching specifier #d4# tells the processor to convert the portion of citation label following the prefix to an integer and then format the integer with preceeding zeros so that it is at least 4 characters in length.

5.2.4. References to other document sections.

Cross references to other parts of a document are specified using the HTML id attribute and anchor <a> element.

The id attribute declares an anchor label within the current document. Anchor labels MUST NOT be declared more than once.

The processing tool automatically creates anchor labels for section headings that do not have an id attribute specified as follows:

The anchor element <a> creates a cross reference to the section identified by an anchor. The href attribute specifies the link target, in this case a URI document fragment identifier which is denoted by a hash character '#' followed by the anchor label.

If the content of the anchor element begins with the prefix [?, the entire contents of the anchor element will be replaced by a suitable cross reference text. If the content of the anchor element does not begin [?, it will not be replaced.

For example the following internal cross reference would be rendered as (see [?Section 4]) in either the HTML or Plaintext output modes.

(see <a href="#Section_4">[?Section]</a>

RFCs normally use references rather than hypertext links in the running text, this allows a reader to see which external sources are referenced by looking at just the referenced. But use of hypertext links is occasionally desirable. To do this we simply insert a hypertext link as usual but specify a full URL rather than merely a fragment.

For example, to create an external reference to the IETF Web Site ([?IETF Web]) we write:

The IETF Web site is <a href="http://www.ietf.org/">[?IETF Web]</a>

5.3. Concordance of Normative Language

Tracking the use of normative language inside the text can take considerable effort in the later stages of standards development. The keywords MUST, SHOULD and MAY defined in [RFC2119] require particular actions to be taken when determining if a specification is ready to progress from RECOMMENDED to STANDARD status.

HTML2RFC processing tools can easily identify the occurrence of normative keywords but merely counting the number of MUST keywords and the pages on which they occur adds little value since the context of the requirement is lost. Heuristic approaches such as extracting the sentence in which the normative language occurs offers only a modest improvement in clarity.

The HTML <span> element MAY be used to specify the portion of text in which the normative language is used that is sufficient to identify the term in a concordance. If the <span> element specifies an id attribute, it specifies the label to be used to identify the normative requirement in the concordance.

For example, the normative language in the preceeding paragraph is marked as follows:

<p><span id="MAY-SPAN">The HTML &lt;span&gt; element MAY be used to 
specify the portion of text in which the normative language is used 
that is sufficient to identify the term in a concordance.</span> 
If the &lt;span&gt; element specifies an id attribute, it specifies 
the label to be used to identify the normative requirement in 
the concordance.</p>

The concordance of normative language would contain the following entry as a result:

[MAY-SPAN]

The HTML <span> element MAY be used to specify the portion of text in which the normative language is used that is sufficient to identify the term in a concordance.

5.4. Concordance of Defined Terms.

The concordance of defined terms is generated in the same manner as the concordance of normative language except that the html <dfn> tag is used to specify the definition in the text. If the <dfn> tag is embedded in a <span> element, the <dfn> element is the defined term and and <span> element marks the definition. If the <dfn> tag is embedded in a <dt> element, the definition is taken from the following <dd> element.

5.5. Index Elements

Index elements are declared using the following syntax:

[*Term]

Add 'Term' to the index.

[*Term/Sub]

Add 'Sub' to the Index as a sub entry under 'Term'

6. References

6.1. Normative References

6.2. Informative References

Appendix A. rfctool Command Line Tool

rfctool is a command line tool that converts from the HTML2RFC subset of HTML to other document formats. At the time of writing these are:

html

HTML output formatted using a stylesheet that produces an IETF style masthead.

txt

IETF Plaintext format at 58 lines per page and 72 characters per line and a formfeed between lines.

xml

[~RFC2629] format to allow HTML2RFC documents to be shared with other authors.

The following commands are supported:

/about

Describe the rfctool tool

[/html] <input> [/html <htmlout>] [/xml <xmlout>] [/txt <txtout>] [/lazy]

Read the file <input> as HTML2RFC source and produce the specified output format(s).

/merge <input> <output> [/lazy]

Read the file <input>, perform processing of embedded <?include?> processing directives and write the result to the file <output>.

The default command is /html.

The /lazy option tells the tool to only process the input file if either the inpout file or the tool itself is newer than all the specified outputs. This option allows html2rfc to be used in build scripts without requiring unnecessary actions.

The /html command accepts the following options but these are not currently implemented:

/bib

Specify a bibliography file to be included

/style

Specify a file to be incorporated into the HTML output as a stylesheet

/w3c

Generate HTML output compliant with W3C formatting rules

/boilerplate

Extract boilerplate text definitions from the specified file

The tool requires that the input file be strictly compliant with XML requirements but does not perform schema validation and simply ignores markup that it does not understand. The document outputs are (or should be) fully compliant with the HTML and/or XML2RFC DTDs.

Appendix B. Markdown Syntax

Use of Markdown syntax was suggested as an alternative to HTML. The following markdown syntax would permit existing RFCs to be read as input source, simplifying (but not automating) the process of updating existing RFCs. It is assumed that any such tool would strip out header and footer information automatically, eliminating the need to distingush these from running text.

Appendix C. Features Not Implemented from XML2RFC

The following xml2rfc features are not yet implemented due to lack of time:

• Table column widths.
• Centered and right formatted table columns.
• Citation of external URL resources
• Error handling does not identify source line where problem occurred.
• Headers and footers in HTML output
• Use of <caption> tag to generate captions for tables.

The following features are described in this document but not implemented due to lack of time

• Ability to create lists of normative language sorted into MUST / SHOULD / RECOMMENDED / MAY
• Ability to specify definitions and defined terms and raise errors when defined terms have no definition
• Ability to import code files and automatically translate into examples / schemas / etc.
• Ability to read back generated HTML (round trip)
• Write out the list of errors into the HTML output as XML comments.
• Add anchors into HTML output to show page transitions.
• Lists of tables, figures
• Citation references in the XML2RFC input

The following xml2rfc features are not implemented on account of diminishing returns:

• Ability to specify symbols other than * in lists
• Use of letters rather than numbers in lists
• Use of complicated formatting in lists.
• Index entries are not supported due to a lack of a suitable HTML element to use for markup

The following features are intentionally omitted:

• Ability to chose whether to generate a ToC, depth etc. Every document needs a ToC.
• Generating output in PDF: Use a tool like wkhtmltopdf instead.

The following are really just bugs:

• The tool does not support P tags nested inside LI, DT or DD elements as separate paragraph markers
• No handling of <BR> tag
• The HTML output uses CDATA sections rather than converting control characters to entities
• The HTML output does not use a stylesheet yet
• When resolving external referencess, these are only added to the cache and will only be read on the next run of the tool

Author's Address

Table of Contents

• 1. Why a New Format is Needed.
• 1.1. Why Existing Tools Fail
• 1.2. Why HTML is Better
• 1.3. Markdown Format Should be considered
• 1.4. The Need to Combine XML2RFC and BibTeX Reference Management
• 2. Document Markup
• 3. Document Text
• 3.1. Headings
• 3.2. Paragraphs
• 3.3. Lists
• 3.4. Tables
• 4. Document Properties Microformat.
• 4.1. Abstract
• 4.2. Document Properties
• 4.2.1. IPR Values
• 4.2.2. Category
• 4.3. Authors
• 5. Advanced Markup.
• 5.1. Including Text From External Sources.
• 5.1.1. <?Include?> Processing Directive
• 5.1.2. <?stylesheet?> Processing Directive
• 5.2. References and Citations.
• 5.2.1. Citations
• 5.2.2. Resolving Citation Labels
• 5.2.3. <?bibsource?> Processing Directive
• 5.2.4. References to other document sections.
• 5.3. Concordance of Normative Language
• 5.4. Concordance of Defined Terms.
• 5.5. Index Elements
• 6. References
• 6.1. Normative References
• 6.2. Informative References
• Appendix A. rfctool Command Line Tool
• Appendix B. Markdown Syntax
• Appendix C. Features Not Implemented from XML2RFC
• Author's Address