Writing I-Ds using HTML
draft-hallambaker-rfctool-01
The information below is for an old version of the document.
| Document | Type |
This is an older version of an Internet-Draft whose latest revision state is "Expired".
|
|
|---|---|---|---|
| Author | Phillip Hallam-Baker | ||
| Last updated | 2013-07-29 | ||
| RFC stream | (None) | ||
| Formats | |||
| Additional resources | |||
| Stream | Stream state | (No stream defined) | |
| Consensus boilerplate | Unknown | ||
| RFC Editor Note | (None) | ||
| IESG | IESG state | I-D Exists | |
| Telechat date | (None) | ||
| Responsible AD | (None) | ||
| Send notices to | (None) |
draft-hallambaker-rfctool-01
Internet Engineering Task Force (IETF) Phillip Hallam-Baker
Internet-Draft Comodo Group Inc.
Intended Status: Standards Track July 29, 2013
Expires: January 30, 2014
Writing I-Ds using HTML
draft-hallambaker-rfctool-01
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."
Copyright Notice
Copyright (c) 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
(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.
Hallam-Baker January 30, 2014 [Page 1]
Internet-Draft Writing I-Ds using HTML July 2013
Table of Contents
1. Why a New Format is Needed. . . . . . . . . . . . . . . . . . 3
1.1. Why Existing Tools Fail . . . . . . . . . . . . . . . . . 3
1.2. Why HTML is Better . . . . . . . . . . . . . . . . . . . 4
1.3. The Need to Combine XML2RFC and BibTeX Reference
Management . . . . . . . . . . . . . . . . . . . . . . . 4
2. Document Markup . . . . . . . . . . . . . . . . . . . . . . . 5
3. Document Text . . . . . . . . . . . . . . . . . . . . . . . . 6
3.1. Headings . . . . . . . . . . . . . . . . . . . . . . . . 8
3.2. Paragraphs . . . . . . . . . . . . . . . . . . . . . . . 9
3.3. Lists . . . . . . . . . . . . . . . . . . . . . . . . . . 9
3.4. Tables . . . . . . . . . . . . . . . . . . . . . . . . . 10
4. Document Properties Microformat. . . . . . . . . . . . . . . . 10
4.1. Abstract . . . . . . . . . . . . . . . . . . . . . . . . 10
4.2. Document Properties . . . . . . . . . . . . . . . . . . . 11
4.2.1. IPR Values . . . . . . . . . . . . . . . . . . . . . 12
4.2.2. Category . . . . . . . . . . . . . . . . . . . . . . 12
4.3. Authors . . . . . . . . . . . . . . . . . . . . . . . . . 12
5. Advanced Markup. . . . . . . . . . . . . . . . . . . . . . . . 13
5.1. Including Text From External Sources. . . . . . . . . . . 13
5.1.1. <?Include?> Processing Directive . . . . . . . . . . 13
5.1.2. <?stylesheet?> Processing Directive . . . . . . . . 15
5.2. References and Citations. . . . . . . . . . . . . . . . . 15
5.2.1. Citations . . . . . . . . . . . . . . . . . . . . . 15
5.2.2. Resolving Citation Labels . . . . . . . . . . . . . 16
5.2.3. <?bibsource?> Processing Directive . . . . . . . . . 18
5.2.4. References to other document sections. . . . . . . . 19
5.3. Concordance of Normative Language . . . . . . . . . . . . 20
5.4. Concordance of Defined Terms. . . . . . . . . . . . . . . 20
6. References . . . . . . . . . . . . . . . . . . . . . . . . . . 20
6.1. Normative References . . . . . . . . . . . . . . . . . . 20
6.2. Non Normative References . . . . . . . . . . . . . . . . 21
Appendix A: rfctool Command Line Tool . . . . . . . . . . . . . . 21
Appendix B: Features Not Implemented from XML2RFC . . . . . . . . 22
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 24
Hallam-Baker January 30, 2014 [Page 2]
Internet-Draft Writing I-Ds using HTML July 2013
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
Hallam-Baker January 30, 2014 [Page 3]
Internet-Draft Writing I-Ds using HTML July 2013
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. 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
Hallam-Baker January 30, 2014 [Page 4]
Internet-Draft Writing I-Ds using HTML July 2013
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 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
Hallam-Baker January 30, 2014 [Page 5]
Internet-Draft Writing I-Ds using HTML July 2013
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.
Hallam-Baker January 30, 2014 [Page 6]
Internet-Draft Writing I-Ds using HTML July 2013
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.
+-------------------+--------+-------------------+------------------+
| Markup | Status | Attributes | Description |
+-------------------+--------+-------------------+------------------+
| <html>, <head>, | | | Necessary for |
| <title>, <body> | | | well formed HTML |
| | | | |
| <h1>, <h2, <h3>, | | id | Title / Section |
| <h4>, <h5>, <h6> | | | Headings |
| | | | |
| <p> | | id | Paragraph |
| | | | |
| <pre> | | id | Preformatted |
| | | | text (e.g. code, |
| | | | examples) |
| | | | |
| <ol>, <ul>, <li> | | id | Bulleted and |
| | | | numbered lists |
| | | | |
| <dl>, <dt>, <dd> | | id | Definition lists |
| | | | |
| <table>, <tr>, | | id, width*, | Tables |
| <th>, <td>, | | align* | |
| <caption>* | | | |
| | | | |
| <a> | * | | Internal / |
| | | | External |
| | | | document links |
| | | | |
| <span> | * | | Mark boundaries |
| | | | of normative |
| | | | text |
| | | | |
| <dfn> | * | | Declare a |
| | | | defined term |
| | | | |
| <em> | * | | Reference a |
| | | | defined term |
| | | | |
Hallam-Baker January 30, 2014 [Page 7]
Internet-Draft Writing I-Ds using HTML July 2013
+-------------------+--------+-------------------+------------------+
| Markup | Status | Attributes | Description |
+-------------------+--------+-------------------+------------------+
| <?include?> | | file, format | Include text |
| | | | from external |
| | | | file |
| | | | |
| <?bibliography?> | | file, format, | Use the |
| | | cache | specified |
| | | | bibliography |
| | | | |
| <?bibsource?> | * | prefix, pattern | Use the |
| | | | specified |
| | | | bibliography |
| | | | resolution |
| | | | source |
| | | | |
| <?stylesheet?> | * | | Specify a style |
| | | | sheet to include |
| | | | |
| [label] | | | Normative |
| | | | reference |
| | | | |
| [label] | | | Informative |
| | | | reference |
| | | | |
| [ | | | Left square |
| | | | brace |
+-------------------+--------+-------------------+------------------+
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
Hallam-Baker January 30, 2014 [Page 8]
Internet-Draft Writing I-Ds using HTML July 2013
<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.
Hallam-Baker January 30, 2014 [Page 9]
Internet-Draft Writing I-Ds using HTML July 2013
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.
Hallam-Baker January 30, 2014 [Page 10]
Internet-Draft Writing I-Ds using HTML July 2013
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.
+-----------+-------------------------------------------+-----------+
| Tag | Description | Values |
+-----------+-------------------------------------------+-----------+
| abbrev | Abreviated document title for page | |
| | headers | |
| | | |
| docname | Document filename (excluding version) | |
| | | |
| version | Document version number | 00..99 |
| | | |
| year | Publication year | |
| | | |
| month | Publication month | |
| | | |
| day | Publication day | |
| | | |
Hallam-Baker January 30, 2014 [Page 11]
Internet-Draft Writing I-Ds using HTML July 2013
+-----------+-------------------------------------------+-----------+
| Tag | Description | Values |
+-----------+-------------------------------------------+-----------+
| ipr | Intellectual Property Rights | See below |
| | | |
| area | IETF area | |
| | | |
| workgroup | IETF working group | |
| | | |
| number | Sepcifies an RFC number | |
| | | |
| category | e.g. Standards track | See below |
| | | |
| updates | Number of an RFC updated by this RFC | |
| | | |
| obsoletes | Number of an RFC made obsolete by this | |
| | RFC | |
| | | |
| seriesno | e.g. BCP 42, STD 69 | |
+-----------+-------------------------------------------+-----------+
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:
+--------------+----------------------------------------------------+
| Tag | Description |
+--------------+----------------------------------------------------+
| author | Start new author and specify full name |
| | |
| surname | Author surname |
| | |
| initials | Author initials |
| | |
| organization | Organization |
| | |
| street | Postal address street |
| | |
Hallam-Baker January 30, 2014 [Page 12]
Internet-Draft Writing I-Ds using HTML July 2013
+--------------+----------------------------------------------------+
| Tag | Description |
+--------------+----------------------------------------------------+
| city | Postal address city |
| | |
| code | Postal address post code |
| | |
| country | Postal address country |
| | |
| phone | Telephone number |
| | |
| email | Email address |
| | |
| uri | Web site |
+--------------+----------------------------------------------------+
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
Hallam-Baker January 30, 2014 [Page 13]
Internet-Draft Writing I-Ds using HTML July 2013
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:
+--------+----------------------------------------------------------+
| Format | Use |
+--------+----------------------------------------------------------+
| xml | XML document or fragment. The initial XML document |
| | declaration is ignored. |
| | |
| html | HTML document of fragment If the toplevel element is |
| | <html>, only the contents of the inner <body> element |
| | are incorporated. |
| | |
| code | Code in an unspecified programming language |
| | |
| ebnf | Extended Bacus Naur Form |
| | |
| json | JSON text example |
| | |
| asn1 | ASN1 Schema |
| | |
| xsd | XML Schema |
| | |
| gdl | Goedel structure file |
| | |
Hallam-Baker January 30, 2014 [Page 14]
Internet-Draft Writing I-Ds using HTML July 2013
+--------+----------------------------------------------------------+
| Format | Use |
+--------+----------------------------------------------------------+
| c | C programming language |
| | |
| cs | C# |
| | |
| java | Java |
| | |
| js | Javascript |
+--------+----------------------------------------------------------+
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, [RFC822] has the label
RFC822.
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.
Hallam-Baker January 30, 2014 [Page 15]
Internet-Draft Writing I-Ds using HTML July 2013
[~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:
1Bibliography files in the order they are declared in the source
document
1Bibliographic sources in the order they are declared in the
source document
1Bibliographic 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.
Hallam-Baker January 30, 2014 [Page 16]
Internet-Draft Writing I-Ds using HTML July 2013
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:
+--------+-----------------------------+----------------------------+
| Prefix | Document Series | Example citation |
+--------+-----------------------------+----------------------------+
| RFC | Request for Comments | RFC822 |
| | | |
| RFC- | Request for Comments | RFC-822 |
| | (alternate style) | |
| | | |
| DRAFT- | Internet Draft | draft-hallambaker-html2rfc |
| | | |
| W3C- | W3C recommendations | W3C.xkms |
| | | |
| 3GPP. | 3GGP | |
| | | |
| ANSI. | ANSI standards | |
| | | |
| CCITT. | CCITT | |
| | | |
| FIPS. | Federal Information | |
| | Processing Standards | |
| | | |
| IEEE. | Selected IEEE standards | |
| | | |
| ISO. | Selected ISO standards | |
| | | |
| ITU. | Selected ITU documents | |
| | | |
| NIST. | Selected NIST documents | |
| | | |
| OASIS. | Selected OASIS documents | |
| | | |
| PKCS. | RSA Labs Public Key | PKCS.7.1993 |
| | Cryptography Standards | |
| | | |
| X. | OSI document series | X.509.2000 |
+--------+-----------------------------+----------------------------+
Hallam-Baker January 30, 2014 [Page 17]
Internet-Draft Writing I-Ds using HTML July 2013
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
d
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-htnl2rfc.
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.
Hallam-Baker January 30, 2014 [Page 18]
Internet-Draft Writing I-Ds using HTML July 2013
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:
+------------------------+----------------------------+
| id | Use |
+------------------------+----------------------------+
| Section_<n> | Section heading |
| | |
| Section_<n>_<n> | Subsection heading (etc.) |
| | |
| Appendix_<a> | Appendix heading |
| | |
| Appendix_<a>_<d> ... | Appendix subheading (etc.) |
| | |
| References | |
| | |
| References_Normative | |
| | |
| References_Informative | |
| | |
| Abstract | |
| | |
| Title | |
| | |
| Author_<n> | Author #n |
+------------------------+----------------------------+
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.
For example the following cross reference would be rendered as (see
Section 4):
(see <a href="#Section_4">[?Section]</a>
Hallam-Baker January 30, 2014 [Page 19]
Internet-Draft Writing I-Ds using HTML July 2013
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 <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.</span>
If the <span> 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.
Hallam-Baker January 30, 2014 [Page 20]
Internet-Draft Writing I-Ds using HTML July 2013
6. References
6.1. Normative References
[label] , "[Reference Not Found!]".
[W3C-CR-html5-20121217] , "[Reference Not Found!]".
[RFC2223] ,Postel, J.,Reynolds, J.K., "Instructions to RFC Authors",
RFC 2223, October 1997.
6.2. Non Normative References
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC822] , "[Reference Not Found!]".
[RFC1866] ,Berners-Lee, T.,Connolly, D.W., "Hypertext Markup
Language - 2.0", RFC 1866, November 1995.
[RFC2629] Rose, M.T., "Writing I-Ds and RFCs using XML", RFC 2629,
June 1999.
[ME-BIBTEX] Patashnik, O., "BibTeXing", 8 February 1985.
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
Hallam-Baker January 30, 2014 [Page 21]
Internet-Draft Writing I-Ds using HTML July 2013
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: 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.
* References to specific document sections.
* Citation of external URL resources
* Error handling does not identify source line where problem
occurred.
Hallam-Baker January 30, 2014 [Page 22]
Internet-Draft Writing I-Ds using HTML July 2013
* Number ordered lists in the txt output.
* Headers and footers in HTML output
* Use of <caption> tag to generate captions for tables.
The following features were considered 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 XML2RFC format
* 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
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.
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
Hallam-Baker January 30, 2014 [Page 23]
Internet-Draft Writing I-Ds using HTML July 2013
* No handling of <BR> tag
Author's Address
Phillip Hallam-Baker
Comodo Group Inc.
philliph@comodo.com
Hallam-Baker January 30, 2014 [Page 24]