<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
   "http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>

<meta http-equiv="Content-Type" content="text/html;charset=US-ASCII">

<style type="text/css">

body { color: #000000; background-color: #FFFFFF; }
del { text-decoration: line-through; color: #8B0040; }
ins { text-decoration: underline; color: #005100; }

p.example { margin-left: 2em; }
pre.example { margin-left: 2em; }
div.example { margin-left: 2em; }

code.extract { background-color: #F5F6A2; }
pre.extract { margin-left: 2em; background-color: #F5F6A2;
  border: 1px solid #E1E28E; }

p.function { }
.attribute { margin-left: 2em; }
.attribute dt { float: left; font-style: italic;
  padding-right: 1ex; }
.attribute dd { margin-left: 0em; }

blockquote.std { color: #000000; background-color: #F1F1F1;
  border: 1px solid #D1D1D1;
  padding-left: 0.5em; padding-right: 0.5em; }
blockquote.stddel { text-decoration: line-through;
  color: #000000; background-color: #FFEBFF;
  border: 1px solid #ECD7EC;
  padding-left: 0.5empadding-right: 0.5em; ; }

blockquote.stdins { text-decoration: underline;
  color: #000000; background-color: #C8FFC8;
  border: 1px solid #B3EBB3; padding: 0.5em; }

table { border: 1px solid black; border-spacing: 0px;
  margin-left: auto; margin-right: auto; }
th { text-align: left; vertical-align: top;
  padding-left: 0.8em; border: none; }
td { text-align: left; vertical-align: top;
  padding-left: 0.8em; border: none; }

</style>

<title>HTML for C++ Standards Documents</title>
</head>
<body>
<h1>HTML for C++ Standards Documents</h1>

<p>
ISO/IEC JTC1 SC22 WG21 N3325 = 12-0015 - 2012-01-15
</p>

<address>
Lawrence Crowl, crowl@google.com, Lawrence@Crowl.org
</address>

<p>
<a href="#Introduction">Introduction</a><br>
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Issues">Issues</a><br>
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Approaches">Approaches</a><br>
<a href="#Good">Good HTML</a><br>
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Compliance">HTML Standard Compliance</a><br>
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Font">Semantic Font Markup</a><br>
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Block">Semantic Block Tags</a><br>
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Quoted">Quoted Text</a><br>
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Preformatted">Preformatted Text</a><br>
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Examples">Examples</a><br>
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Tables">Tables</a><br>
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#DelIns">Deleted and Inserted Text</a><br>
<a href="#Front">WG21 Front Matter</a><br>
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Identification">Document Identification</a><br>
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Contents">Headings and the Table of Contents</a><br>
<a href="#Represent">Representing C++ Standards Concepts in HTML</a><br>
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Code">Code and Code Blocks</a><br>
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Grammar">Grammar Terms and Rules</a><br>
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Notes">Notes, etc.</a><br>
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Library">Representing Library Function Specifications</a><br>
<a href="#Editing">Showing Edits</a><br>
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Quoting">Quoting the Standard</a><br>
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#EditText">Inserted and Deleted Text</a><br>
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#EditPara">Inserted and Deleted Paragraphs</a><br>
<a href="#Formatting">Formatting the HTML Source</a><br>
<a href="#Literate">Literate Programming</a><br>
<a href="#Style">Rendering Style</a><br>
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Color">Color and Contrast</a><br>
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#TableStyle">Tables</a><br>
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#ExampleStyle">Examples</a><br>
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#ExtractedStyle">Examples</a><br>
<a href="#References">References</a><br>
<a href="#Scripts">Scripts</a><br>
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#quote_code.sh">quote_code.sh</a><br>
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#block_code.sh">block_code.sh</a><br>
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#block_extract.sh">block_extract.sh</a><br>
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#extract_code.sh">extract_code.sh</a><br>
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#contents.sh">contents.sh</a><br>
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#dynacontents.js">dynacontents.js</a><br>
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#outline.sh">outline.sh</a><br>
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#outline_with_names.sh">outline_with_names.sh</a><br>
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#style.hinc">style.hinc</a><br>
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Makefile">Makefile</a><br>
</p>


<h2><a name="Introduction">Introduction</a></h2>

<p>
At the Summer 2011 meeting,
there were several problems with the readability of various presentations.
Readability is another side of accessibility,
the ability of a wide variety of readers
to read the page under a wide variety of conditions.
</p>

<p>
This paper provides guidelines and tools
for producing widely accessible WG21 papers.
It is based on my experience in dealing with inaccessible web pages
and my experience writing accessible web pages.
</p>

<p>
These guidelines are for the production of WG21 papers.
While many of the concepts and techniques carry over into other uses,
they are incomplete with respect to those other uses.
</p>


<h3><a name="Issues">Issues</a></h3>

<p>
Contrast was the primary problem at the summer meeting.
When contrast is low, readability is poor.
Further, low contrast exaggerates focus problems.
</p>

<p>
Reliance on color is a significant problem.
First, close to 10% of men are color deficient,
which means they cannot see colors normally.
There are several kinds of deficiency,
but by far the most common is an inability to distinguish red and green.
Second, many browsers support a "high contrast" mode,
which generally ignores page-specified colors.
Third, to save costs, WG21 papers are often printed without color.
The net effect is that color differences, and particularly red versus green,
is not sufficient to convey information.
</p>

<p>
Reliance on font face is a significant problem.
The "high contrast" mode generally ignores page-specified fonts,
So font differences are also not sufficient to convey information.
</p>

<p>
Reliance on long lines is a significant problem.
Low-vision readers rely on being able to increase font size to read the text.
Larger fonts mean relatively shorter lines.
Smaller windows also achieve the effect of forcing shorter lines.
Pages need to adapt to those shorter lines.
</p>

<p>
Reliance on external tools is not presently a problem,
but could become one.
Browsers behave differently.
They are configured in various ways.
They have different sets of extensions and plug-ins.
All of this variety leads to problems when straying from plain HTML.
</p>


<h3><a name="Approaches">Approaches</a></h3>

<p>
The primary approach to solving these problems
is to rely on text to convey information,
and secondarily, to enable that text to adapt to the reader's needs.
One can decorate with style and color;
make it easier to read with style and color;
but one must make the text itself convey all needed information.
</p>

<p>
A consequence of a reliance on text is that
pages should avoid technologies that 
displace or obscure text.
Examples include embedding text in images and using Flash.
</p>

<p>
Text more effectively adapts to readers' needs
when the semantic structure of the paper
is separated from the presentational choices.
In other words, the HTML elements should carry the paper's meaning,
and separate CSS should specify presentation.
Readers can alter the applied CSS,
but altering the elements is much harder.
</p>

<p>
Plain HTML is the most accessible and most reliable way to convey information.
So, we should encode documents with HTML elements
that best represent semantics.
</p>

<p>
Reading is more comfortable when the author
respects and accepts the users' choices
in browser, settings, colors and sizes.
</p>

<p>
Finally, papers should avoid reliance on problematic technologies,
like Javascript, Java, and video.
</p>


<h2><a name="Good">Good HTML</a></h2>

<p>
Use clean, well-structured HTML.
Doing so reduces document construction and maintenance costs,
as well as making documents easier to read.
</p>

<p>
Where possible, comply with all relevant standards.
We cannot control where our documents go,
so we should help them travel easily.
</p>

<p>
Avoid machine generation of HTML,
as the results tend to work towards a particular paper-based layout
rather than provide general readability.
In particular, word processors, such as Microsoft Word,
produce really bad HTML.
</p>

<p>
Never put style information within the body of the document.
<a href="#HTMLstyleinline">[HTMLstyleinline]</a>
Instead, uses the <code>class</code> attribute
to give an element additional semantic information,
which can then be decorated with CSS specified in the document head.
</p>


<h3><a name="Compliance">HTML Standard Compliance</a></h3>

<p>
Write documents with strict HTML 4.01
<a href="#HTML401">[HTML401]</a>
standards compilance.
</p>

<pre class="example">
<code>&lt;!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
   "http://www.w3.org/TR/html4/strict.dtd"&gt;
&lt;html&gt;
&lt;head&gt;</code>
</pre>

<p>
Write documents with only the ASCII character set.
It is the common base on most systems,
and by design,
is sufficient to represent C++ source code.
</p>

<pre class="example">
<code>&lt;meta http-equiv="Content-Type" content="text/html;charset=US-ASCII"&gt;</code>
</pre>

<p>
Use character entities for non-ASCII letters.
<a href="#HTMLentity">[HTMLentities]</a>
</p>

<table>
<caption>Some Character Entities</caption>
<thead>
<tr>
<th>name</th><th>value</th>
<th>name</th><th>value</th>
<th>name</th><th>value</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>&amp;amp;</code></td><td>"&amp;"</td>
<td><code>&amp;uuml;</code></td><td>"&uuml;"</td>
<td><code>&amp;nbsp;</code></td><td>(non-breaking space)</td>
</tr>
<tr>
<td><code>&amp;lt;</code></td><td>"&lt;"</td>
<td><code>&amp;Ntilde;</code></td><td>"&Ntilde;"</td>
<td><code>&amp;mdash;</code></td><td>"&mdash;" (em dash)</td>
</tr>
<tr>
<td><code>&amp;gt;</code></td><td>"&gt;"</td>
<td><code>&amp;oacute;</code></td><td>"&oacute;"</td>
<td><code>&amp;ndash;</code></td><td>"&ndash;" (en dash)</td>
</tr>
</tbody>
</table>

<p>
Use an HTML validator.
The W3C provides one at
<a href="http://validator.w3.org">validator.w3.org</a>.
</p>


<h3><a name="Font">Semantic Font Markup</a></h3>

<p>
Browsers may ignore font specifications,
but they generally do not ignore the phrase markup elements
<a href="#HTMLphrase">[HTMLphrase]</a>
<code>em</code>, <code>strong</code>, <code>dfn</code>,
<code>code</code>, <code>samp</code>, <code>kbd</code>,
<code>var</code>, <code>cite</code>,
and <code>abbr</code>.
So, one should use one of them rather than the font style elements
<a href="#HTMLfontstyle">[HTMLfontstyle]</a>
<code>tt</code>, <code>i</code>, <code>b</code>,
<code>big</code>, <code>small</code>, <code>strike</code>,
<code>s</code>, and <code>u</code>.
One should certainly not use
the <code>font</code> element.
<a href="#HTMLfontstyle">[HTMLfontstyle]</a>
</p>

<p>
Normal emphasis should use the <code>em</code> element,
rather than the <code>i</code> element.
</p>

<p>
Strong emphasis should use the <code>strong</code> element,
rather than the <code>b</code> element.
</p>

<p>
The definition of a term should use the <code>dfn</code> element,
rather than the <code>i</code> element.
</p>

<p>
Citations should use the <code>cite</code> element.
</p>

<p>
Abbreviations should use the <code>abbr</code> element.
This element requires extra work to be effective,
and so may not find much application within WG21 papers.
</p>

<p>
Text that is variable, that is intended for substitution,
should use <code>var</code> element,
rather than the <code>i</code> element.
Grammar symbols fall directly into this category.
</p>

<p>
C++ identifiers, keywords, punctuation, and the like should use
one of the <code>code</code> element.
Sample output should use the <code>samp</code> element.
User input should use the <code>kbd</code> element.
Such text that is variable, that is intended for substitution,
should also use the <code>var</code> element.
</p>

<p>
Within C++ code, the characters
<code>&amp;</code>, <code>&lt;</code>, and <code>&gt;</code>
must be quoted.
The script <a href="#quote_code.sh">quote_code.sh</a>
will convert C++ code into properly quoted HTML.
</p>

<p>
Browsers often use the same representation for more than one phrase element.
Commonly, the common representations are in the following table.
</p>

<table>
<caption>Common Phrase Representations</caption>
<thead>
<tr><th>representation</th><th>tags</th></tr>
</thead>
<tbody>
<tr><td>normal</td><td><code>abbr acronym</code></td></tr>
<tr><td>italic</td><td><code>cite dfn em i var</code></td></tr>
<tr><td>bold</td><td><code>b strong</code></td></tr>
<tr><td>fixed-width</td><td><code>code kbd samp tt</code></td></tr>
</tbody>
</table>

<p>
Authors should excercise care to ensure that
these overloaded elements are used
in contexts where the intent is reasonably clear.
Fortunately, some of these can be mixed,
such as <code>var</code> with <code>code</code>.
</p>


<h3><a name="Block">Semantic Block Tags</a></h3>

<p>
Use elements to indicate document structure,
not just for their effect on formatting.
</p>

<p>
When the semantics of a element are not fine enough,
identify additional distinctions with class attributes.
<a href="#HTMLclass">[HTMLclass]</a>
</p>

<h3><a name="Quoted">Quoted Text</a></h3>

<p>
There are two types of quotes: block quotes and inline quotes.
<a href="#HTMLquote">[HTMLquote]</a>
</p>

<p>
Block quotes use the <code>blockquote</code> element
and denote paragraph-level quotations.
As such they always have a block-level element within them,
such as an explicit <code>p</code> element.
</p>

<p>
Inline quotes use the <code>q</code> element, 
and generally enclose short quotations.
Use inline quotes in place of quotation marks.
Some browsers fail to add the quotation marks as specified,
so this element may require some more time before it is reliable.
</p>

<h3><a name="Preformatted">Preformatted Text</a></h3>

<p>
Use the <code>pre</code> element to enclose preformatted text.
<a href="#HTMLpre">[HTMLpre]</a>
The <code>pre</code> element has definitional problems.
In particular, the browser may or may not change to a fixed-width font,
which means the author can neither avoid nor rely on a fixed-width font.
Therefore, authors should always specify a fixed-width font
immediately within the preformatted text
and ensure that it is active throughout the block.
That is,
</p>

<pre class="example">
<code>&lt;pre&gt;
line of   wait for it   text
  followed by some indentation
&lt;/pre&gt;</code>
</pre>

<p>
is not reliable.
Instead, authors should specify
</p>

<pre class="example">
<code>&lt;pre&gt;
&lt;code&gt;line of  ...  wait for it  ...  code
    some of which is indented&lt;/code&gt;
&lt;/pre&gt;</code>
</pre>

<p>
Furthermore,
while
</p>

<pre class="example">
<code>&lt;pre&gt;&lt;code&gt;
line of  ...  wait for it  ...  code
    some of which is indented
&lt;/code&gt;&lt;/pre&gt;</code>
</pre>

<p>
is cleanest,
some browsers incorrectly
<a href="#HTMLline">[HTMLline]</a>
add an extra blank line
at the beginning of the preformatted text.
</p>

<p>
In any event, preformatted text does not wrap lines,
which makes them very difficult to read when the line width
is greater than the window width.
(This problem happens when either characters are large or windows are narrow.)
Therefore, authors should strive to keep preformatted lines short.
</p>


<h3><a name="Examples">Examples</a></h3>

<p>
A significant part of WG21 documents are examples.
Represent examples with <code>class=example</code>
applied to <code>p</code> paragraphs,
<code>pre</code> preformatted text or
<code>div</code> document divisions.
Divisions contain any number of paragraphs.
</p>

<p>
For example, the example
</p>

<pre class="example">
<code>int main() {
   return 0;
}</code>
</pre>

<p>
Is represented as
</p>

<pre class="example">
<code>&lt;pre class="example"&gt;
&lt;code&gt;int main() {
   return 0;
}&lt;/code&gt;
&lt;/pre&gt;</code>
</pre>

<p>
The script <a href="#block_code.sh">block_code.sh</a>
will convert C++ code into properly quoted, preformatted, example code block.
</p>

<h3><a name="Tables">Tables</a></h3>

<p>
Tables
<a href="#HTMLtable">[HTMLtable]</a>
may consist of a caption (<code>caption</code>),
a head (<code>thead</code>),
a body (<code>tbody</code>), and
a foot (<code>tfoot</code>).
The last three elements contain rows.
The head and foot elements
enable browsers to duplicate headings and footings
when splitting a table across multiple pages.
</p>

<pre class="example">
<code>&lt;table&gt;
&lt;caption&gt;Common Phrase Representations&lt;/caption&gt;
&lt;thead&gt;
&lt;tr&gt;&lt;th&gt;representation&lt;/th&gt;&lt;th&gt;tags&lt;/th&gt;&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;&lt;td&gt;normal&lt;/td&gt;&lt;td&gt;&lt;code&gt;abbr acronym&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;
&lt;tr&gt;&lt;td&gt;italic&lt;/td&gt;&lt;td&gt;&lt;code&gt;cite dfn em i var&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;
&lt;tr&gt;&lt;td&gt;bold&lt;/td&gt;&lt;td&gt;&lt;code&gt;b strong&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;
&lt;tr&gt;&lt;td&gt;fixed-width&lt;/td&gt;&lt;td&gt;&lt;code&gt;code kbd samp tt&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;</code>
</pre>

<p>
Avoid wide tables; these tend to get truncated when printed.
Test table width by deliberately making the browser window very narrow.
</p>


<h3><a name="DelIns">Deleted and Inserted Text</a></h3>

<p>
HTML provides direct representation of deleted and inserted text.
<a href="#HTMLdelins">[HTMLdelins]</a>
These should be used in preference to ad hoc mechanisms.
</p>

<p>
The HTML standard intended these elements
for showing modifications to the document itself.
However, that is rarely a problem with WG21 papers.
Instead they need to show edits to the working draft,
and this repurposing of the elements is reasonable.
</p>

<p>
For example, to achieve
</p>

<p class="example">
This text was <del>deleted</del> <ins>inserted</ins> today.
</p>

<p>
use
</p>

<pre class="example">
<code>This text was &lt;del&gt;deleted&lt;/del&gt; &lt;ins&gt;inserted&lt;/ins&gt; today.</code>
</pre>

<p>
and do not use
</p>

<pre class="example">
<code>This text was &lt;span class="del"&gt;deleted&lt;/span&gt;
&lt;span class="ins"&gt;inserted&lt;/span&gt; today.</code>
</pre>

<p>
and certainly not
</p>

<pre class="example">
<code>This text was &lt;strike&gt;deleted&lt;/strike&gt;
&lt;u&gt;inserted&lt;/u&gt; today.</code>
</pre>

<p>
and especially not
</p>

<pre class="example">
<code>This text was &lt;span style="color:red;"&gt;deleted&lt;/span&gt;
&lt;span style="color:green;"&gt;inserted&lt;/span&gt; today.</code>
</pre>

<p>
When the deletion occurs before an insertion,
readers can use the deletion to set the context for the insertion.
So, when paired, the deletion should come before its insertion.
</p>

<p>
Unless spacing is critical to the changes,
deletions and insertions should be spaced.
However, in the presence of changing punctuation,
non-spacing markup is preferable to excessive markup,
particularly when readers may not notice it.
For example,
</p>

<pre class="example">
<code>This text &lt;del&gt;glues&lt;/del&gt;&lt;ins&gt;joins&lt;/ins&gt; words.
This text &lt;del&gt;modifies&lt;/del&gt;&lt;ins&gt; changes&lt;/ins&gt; spacing.
This text &lt;del&gt;highlights&lt;/del&gt; &lt;ins&gt;clarifies&lt;/ins&gt; changes.
Red&lt;ins&gt;, yellow&lt;/ins&gt; and green are hard to distinguish.</code>
</pre>

<p>
yields
</p>

<p class="example">
This text <del>glues</del><ins>joins</ins> words.
This text <del>modifies</del><ins> changes</ins> spacing.
This text <del>highlights</del> <ins>clarifies</ins> changes.
Red<ins>, yellow</ins> and green are hard to distinguish.
</p>

<p>
The <code>del</code> and <code>ins</code> elements
are supposed to act as either block-level or inline-level elements,
however some browsers fail to render them properly as block-level elements.
Therefore, authors should use these elements as inline elements only.
(This workaround is most annoying for tables and lists.)
</p>


<h2><a name="Front">WG21 Front Matter</a></h2>

<p>
The front matter for WG21 documents includes document identification
and possibly a table of contents or a revision history.
</p>

<h3><a name="Identification">Document Identification</a></h3>

<p>
The document identification includes a title,
which is specified
in the <code>title</code> element within the <code>head</code> element
and in the <code>h1</code> element at the top of the <code>body</code> element.
</p>

<pre class="example">
<code>&lt;title&gt;HTML for C++ Standards Documents&lt;/title&gt;
&lt;/head&gt;
&lt;body&gt;
&lt;h1&gt;HTML for C++ Standards Documents&lt;/h1&gt;</code>
</pre>

<p>
Follow the title with the document identification numbers,
which is composed of "ISO/IEC JTC1 SC22 WG21",
the WG21 paper number, the INCITS paper number,
and the ISO date.
</p>

<pre class="example">
<code>&lt;p&gt;
ISO/IEC JTC1 SC22 WG21 N3325 = 12-3325 - 2012-01-15
&lt;/p&gt;</code>
</pre>

<p>
Follow the title with the authors.
Email addresses are optional.
</p>

<pre class="example">
<code>&lt;address&gt;
Lawrence Crowl, crowl@google.com, Lawrence@Crowl.org
&lt;/address&gt;</code>
</pre>

<p>
Other optional front matter includes
a table of contents
and a revision history.
</p>

<h3><a name="Contents">Headings and the Table of Contents</a></h3>

<p>
When headings follow a simple format,
they can be easily and automatically converted into a table of contents.
The format consists of a single line
containing a heading element
and directly within that an anchor element.
The anchor provides not a reference, but a name.
That name must be unique within the file.
Using the standard's own tagging system
is often unique, but not always.
</p>

<p>
For example, the header,
</p>

<blockquote>
<h3><a name="futures.unique_future">30.6.6 Class template <code>future</code> [futures.unique_future]</a></h3>
</blockquote>

<p>
is encoded on one source line as
</p>

<p class="example">
<code>
&lt;h3&gt;&lt;a name="futures.unique_future"&gt;30.6.6 Class template &lt;code&gt;future&lt;/code&gt; [futures.unique_future]&lt;/a&gt;&lt;/h3&gt;
</code>
</p>

<p>
The script <a href="#contents.sh">contents.sh</a>
generate a table of contents.
The resulting file can be simply included into the HTML source.
</p>

<p>
Alternatively, one can use Javascript within the HTML itself
to dynamically generate the contents.
The script <a href="#dynacontents.js">dynacontents.js</a>,
courtesy of Jeffrey Yasskin,
does this task.
It assumes that the user has previously included
</p>
<p class="example">
<code>
&lt;script
src="https://ajax.googleapis.com/ajax/libs/jquery/1.7.1/jquery.min.js"
type="text/javascript"&gt;
&lt;/script&gt;"
</code>
</p>
<p>
It also assumes an <code>p</code> element, somewhere in the document,
with the id "toc", which it will fill in with the table of contents.
</p>

<p>
While the table of contents serves as an outline,
a more specific command-line tool that emits the outline
can be helpful during development.
There are two such scripts,
one that emits just the headings
and one that also emits the anchor names.
They are available as
<a href="#outline.sh">outline.sh</a> and
<a href="#outline_with_names.sh">outline_with_names.sh</a>,
respectively.
</p>


<h2><a name="Represent">Representing C++ Standards Concepts in HTML</a></h2>

<p>
Conventions on the use of HTML
in representing concepts of the C++ standard
will help in cooperative editing,
sharing of helpful tools,
and automatic translation into the LaTeX source of the standard itself.
</p>


<h3><a name="Code">Code and Code Blocks</a></h3>

<p>
Code should use the <code>code</code> element.
</p>

<p>
Non-normative code within the standard
should use the <code>var</code> phrase element.
Examples include parameter names, expository member variables,
standard meta-variables, and example implementations.
</p>

<p>
The standard often marks comments with an italic font.
Mark these with the <code>em</code> element.
</p>

<p>
Emphasized code must use the <code>strong</code> element,
because normal emphasis is usually visually indistinct from variable text.
</p>

<p>
Avoid long lines in code blocks,
as they may interfere with the readablity of the document.
</p>

<p>
For example, the partial description of a standard <code>counter</code>
might look something like the following.
</p>

<pre class="example">
<code>template&lt; typename T &gt;
class counter
{
    // <em>expository fields:</em>
<var>private:</var>
    <var>T value;</var>

public:
    // <em>construct and destruct:</em>
    counter() <var>: value( 0 ) { }</var>
    counter(const counter&amp; <var>d</var>) <strong>= default</strong>;
    ~counter() <strong>= default</strong>;

    // <em>operations:</em>
    void inc( T <var>b</var>) <var>{ value += b; }</var>
    T get() <var>{ return value; }</var>
}</code>
</pre>

<p>
It is encoded as follows.
</p>

<pre class="example">
<code>&lt;pre class="example"&gt;
&lt;code&gt;template&amp;lt; typename T &amp;gt;
class counter
{
    // &lt;em&gt;expository fields:&lt;/em&gt;
&lt;var&gt;private:&lt;/var&gt;
    &lt;var&gt;T value;&lt;/var&gt;

public:
    // &lt;em&gt;construct and destruct:&lt;/em&gt;
    counter() &lt;var&gt;: value( 0 ) { }&lt;/var&gt;
    counter(const counter&amp;amp; &lt;var&gt;d&lt;/var&gt;) &lt;strong&gt;= default&lt;/strong&gt;;
    ~counter() &lt;strong&gt;= default&lt;/strong&gt;;

    // &lt;em&gt;operations:&lt;/em&gt;
    void inc( T &lt;var&gt;b&lt;/var&gt;) &lt;var&gt;{ value += b; }&lt;/var&gt;
    T get() &lt;var&gt;{ return value; }&lt;/var&gt;
}&lt;/code&gt;
&lt;/pre&gt;</code>
</pre>


<h3><a name="Grammar">Grammar Terms and Rules</a></h3>

<p>
The C++ grammar has the structure of a descriptive list,
several terms each of which may have several definitions.
We exploit that parallel structure
by representing C++ grammar rules with descriptive lists.
</p>

<p>
Grammar terms are represented denoted by
a <code>var</code> variable-phrase element.
When a grammar term is defined,
it is contained within by
a <code>dt</code> descriptive-term element,
and marked by <code>dfn</code> definition phrase element.
(The colon outside the <code>dfn</code> element
makes automatic indexing easier.)
Each substitution rule is denoted by
a <code>dd</code> descriptive-definition element.
The optional marker is denoted by
a <code>sub</code> subscript element
within the <code>var</code> element.
Literal code is denoted by the <code>code</code> phrase element.
</p>

<p>
The grammar
</p>

<dl>
<dt><dfn>declaration-seq</dfn>:</dt>
<dd><var>declaration</var>
<var>declaration-seq<sub>opt</sub></var></dd>

<dt><dfn>static_assert-declaration</dfn>:</dt>
<dd><code>static_assert (</code>
<var>constant-expression</var> <code>,</code>
<var>string-literal</var> <code>) ;</code></dd>
</dl>

<p>
is encoded as
</p>

<pre class="example">
<code>&lt;dl&gt;
&lt;dt&gt;&lt;dfn&gt;declaration-seq&lt;/dfn&gt;:&lt;/dt&gt;
&lt;dd&gt;&lt;var&gt;declaration&lt;/var&gt;
&lt;var&gt;declaration-seq&lt;sub&gt;opt&lt;/sub&gt;&lt;/var&gt;&lt;/dd&gt;

&lt;dt&gt;&lt;dfn&gt;static_assert-declaration&lt;/dfn&gt;:&lt;/dt&gt;
&lt;dd&gt;&lt;code&gt;static_assert (&lt;/code&gt;
&lt;var&gt;constant-expression&lt;/var&gt; &lt;code&gt;,&lt;/code&gt;
&lt;var&gt;string-literal&lt;/var&gt; &lt;code&gt;) ;&lt;/code&gt;&lt;/dd&gt;
&lt;/dl&gt;</code>
</pre>


<h3><a name="Notes">Notes, etc.</a></h3>

<p>
Represent notes, footnotes and examples
by surrounding them with markers.
These markers have the form
</p>

<p class="example">
[<i>Footnote:</i>
Here is some non-normative text.
&mdash;<i>end footnote</i>]
</p>

<p>
and are encoded as
</p>

<pre class="example">
<code>[&lt;i&gt;Footnote:&lt;/i&gt;
Here is some non-normative text.
&amp;mdash;&lt;i&gt;end footnote&lt;/i&gt;]</code>
</pre>

<p>
Note that here we use the font element <code>i</code>
because it does not really fit any of the phrase markers
and because it makes searching for such uses easier.
</p>

<p>
While not part of the final standard,
rationale, editor's notes and notes to the editor
can also be represented this way.
</p>

<p>
Comments on the paper itself,
and particularly notes on work still to be done
can be marked the same way,
except using the <code>b</code> element instead of the <code>i</code> element.
This change enables rapid searching for unfinished parts of the document.
</p>


<h3><a name="Library">Representing Library Function Specifications</a></h3>

<p>
The library has special formatting requirements
for representing functions and their attributes.
Each function prototype is contained within
<code>p class="function"</code> element.
The attribute paragraphs are all contained
<code>dl class="attribute"</code> element.
Each attribute is labeled with a <code>dt</code> element
and has its body in a <code>dd</code> element.
For example,
the function definition
</p>

<div class="example">
<p class="function">
<code>dynarray(size_type <var>c</var>);</code>
</p>

<dl class="attribute">
<dt>Requires:</dt>
<dd><p>
The constructor parameter shall be greater than zero.
</p></dd>

<dt>Effects:</dt>
<dd><p>
May or may not invoke the global <code>operator new</code>.
</p></dd>
</dl>
</div>

<p>
is represented as
</p>

<pre class="example">
<code>&lt;p class="function"&gt;
&lt;code&gt;dynarray(size_type &lt;var&gt;c&lt;/var&gt;);&lt;/code&gt;
&lt;/p&gt;

&lt;dl class="attribute"&gt;
&lt;dt&gt;Requires:&lt;/dt&gt;
&lt;dd&gt;&lt;p&gt;
The constructor parameter shall be greater than zero.
&lt;/p&gt;&lt;/dd&gt;

&lt;dt&gt;Effects:&lt;/dt&gt;
&lt;dd&gt;&lt;p&gt;
May or may not invoke the global &lt;code&gt;operator new&lt;/code&gt;.
&lt;/p&gt;&lt;/dd&gt;
&lt;/dl&gt;</code>
</pre>



<h2><a name="Editing">Showing Edits</a></h2>

<p>
In the end,
papers are effective only when they edit the working draft.
This section explains how to do that.
</p>

<h3><a name="Quoting">Quoting the Standard</a></h3>

<p>
The first step in editing the standard is to quote the standard.
For that we use the <code>blockquote</code> element
with <code>class="std"</code>.
Each quoted portion of the standard
must be preceeded by a paragraph
indicating where in the standard it comes from.
The section may be known from context,
but if not, it should be stated explicitly.
So, the quote appears as
</p>

<div class="example">
<p>
Section 1.8 [intro.object] paragraph 5 says:
</p>

<blockquote class="std">
<p>
Unless it is a bit-field (9.6),
a most derived object shall have a non-zero size
and shall occupy one or more bytes of storage.
Base class subobjects may have zero size.
An object of trivially copyable or standard-layout type (3.9)
shall occupy contiguous bytes of storage.
</p>
</blockquote>
</div>

<p>
and is encoded as
</p>

<div class="example">
<pre class="example">
<code>&lt;p&gt;
Section 1.8 [intro.object] paragraph 5 says:
&lt;/p&gt;

&lt;blockquote class="std"&gt;
&lt;p&gt;
Unless it is a bit-field (9.6),
a most derived object shall have a non-zero size
and shall occupy one or more bytes of storage.
Base class subobjects may have zero size.
An object of trivially copyable or standard-layout type (3.9)
shall occupy contiguous bytes of storage.
&lt;/p&gt;
&lt;/blockquote&gt;</code>
</pre>
</div>


<h3><a name="EditText">Inserted and Deleted Text</a></h3>

<p>
One can show edits to a paragraph
by combining the quoting of the standard
with the delete and insert markup described above.
So, an edit appears as
</p>

<div class="example">
<p>
Edit section 1.8 [intro.object] paragraph 5 as follows.
</p>

<blockquote class="std">
<p>
Unless it is a bit-field (9.6),
a most derived object shall have a non-zero size
and shall occupy one or more bytes <del>of storage</del>.
Base class subobjects may have zero size.
An object of trivially copyable<ins>, trivially movable</ins>
or standard-layout type (3.9)
shall occupy contiguous bytes of storage.
</p>
</blockquote>
</div>

<p>
and is encoded as
</p>

<pre class="example">
<code>&lt;p&gt;
Edit section 1.8 [intro.object] paragraph 5 as follows.
&lt;/p&gt;

&lt;blockquote class="std"&gt;
&lt;p&gt;
Unless it is a bit-field (9.6),
a most derived object shall have a non-zero size
and shall occupy one or more bytes &lt;del&gt;of storage&lt;/del&gt;.
Base class subobjects may have zero size.
An object of trivially copyable&lt;ins&gt;, trivially movable&lt;/ins&gt;
or standard-layout type (3.9)
shall occupy contiguous bytes of storage.
&lt;/p&gt;
&lt;/blockquote&gt;</code>
</pre>


<h3><a name="EditPara">Inserted and Deleted Paragraphs</a></h3>

<p>
When deleting or inserting whole paragraphs or sections,
the <code>del</code> and <code>ins</code> elements
need not be used,
but the introductory text
should clearly indicate the edit.
In addition, the <code>blockquote</code> elements
use <code>class="stddel"</code> or <code>class="stdins"</code>, respectively.
So, full paragraph deletions and insertions
appear as
</p>

<div class="example">
<p>
Delete paragraph 12 of 2.14.5 String literals [lex.string].
</p>

<blockquote class="stddel">
<p>
Whether all string literals are distinct
(that is, are stored in nonoverlapping objects)
is implementation-defined.
The effect of attempting to modify a string literal is undefined.
</p>
</blockquote>
<p>
After paragraph 12 of 2.14.5 String literals [lex.string],
insert a new paragraph.
</p>

<blockquote class="stdins">
<p>
All string literals are distinct;
their characters never share addresses.
</p>
</blockquote>
</div>

<p>
and are encoded as
</p>

<pre class="example">
<code>&lt;p&gt;
Delete paragraph 12 of 2.14.5 String literals [lex.string].
&lt;/p&gt;

&lt;blockquote class="stddel"&gt;
&lt;p&gt;
Whether all string literals are distinct
(that is, are stored in nonoverlapping objects)
is implementation-defined.
The effect of attempting to modify a string literal is undefined.
&lt;/p&gt;
&lt;/blockquote&gt;</code>
</pre>
<pre class="example">
<code>&lt;p&gt;
After paragraph 12 of 2.14.5 String literals [lex.string],
insert a new paragraph.
&lt;/p&gt;

&lt;blockquote class="stdins"&gt;
&lt;p&gt;
All string literals are distinct;
their characters never share addresses.
&lt;/p&gt;
&lt;/blockquote&gt;</code>
</pre>


<h2><a name="Formatting">Formatting the HTML Source</a></h2>

<p>
The format of the HTML source itself
can improve its interaction with tools.
</p>

<p>
Starting each sentence on a new line
improves the stability of <code>diff</code>,
and hence of source code version control systems.
The same applies to
putting block-level elements on lines separate from live text.
</p>

<p>
When editing the source,
separating block-level elements
makes them more quickly identifiable.
</p>

<p>
More regularity in the HTML source
eases tools for converting HTML source to other forms,
like the LaTeX of the standard itself.
</p>


<h2><a name="Literate">Literate Programming</a></h2>

<p>
The C++ standard's papers are a good application
of literate programming.
<a href="#LPcom">[LPcom]</a>
<a href="#LPwiki">[LPwiki]</a>
Particularly when a papers includes
normative declarations or sample implementations,
an automatic process for extracting the code from the paper itself
helps ease adoption concerns.
</p>

<p>
The essential idea is to identify code to be extracted with a distinct class,
e.g. <code>"extract"</code>,
and then remove everything but that within those <code>code</code> elements.
That process is eased considerably
when all code text is on lines separate from other text.
Typically, this is accomplished with HTML of the form:
</p>

<pre class="example">
<code>&lt;pre class="extract"&gt;&lt;code class="extract"&gt;
echo "Hello, World!"
&lt;/code&gt;&lt;/pre&gt;</code>
</pre>

<p>
Within the code,
all HTML elements should be removed,
which enables links, phrase tags, and other markup
within the code.
Further, the critical HTML character entities,
<code>&amp;lt;</code>, <code>&amp;gt;</code>,
<code>&amp;amp;</code>, and <code>&amp;nbsp;</code>,
must be recognized and substituted.
</p>

<p>
For presentational purposes,
it is also helpful to identify the <code>pre</code> element
containing the code for extraction.
Again, use the same class as above, e.g. <code>"extract"</code>.
</p>

<p>
The script <a href="#block_extract.sh">block_extract.sh</a>
will convert C++ code into properly quoted, preformatted, extraction code block.
</p>

<p>
The HTML files can contain either a single code file,
as in 
<a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2648.html">
N2648</a>,
or multiple code files,
as in 
<a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2427.html">
N2427</a>.
In the latter case, the multiple files
are actually generated from a single-file shell script.
The <a href="#Scripts">scripts</a> in this paper follow that approach.
</p>

<p>
The script <a href="#extract_code.sh">extract_code.sh</a>
will extract the code from the HTML source of this paper.
Simply execute the resulting shell script to get copies of the scripts.
</p>


<h2><a name="Style">Rendering Style</a></h2>

<p>
Once the paper is well structured and independent of the presentation,
we must address creating a readable presentation.
We encode that presentation in a <code>style</code> element
within the <code>head</code> element of the document.
(Alternately, we could create a standard location
for a separately read CSS file.)
The proposed <code>style</code> element
is <a href="#style.hinc">style.hinc</a>
in the <a href="#Scripts">Scripts</a> section.
</p>


<h3><a name="Color">Color and Contrast</a></h3>

<p>
Color and contrast must meet specific technical requirements.
These are embodied in the
Web Content Accessibility Guidelines (WCAG).
<a href="#WCAG">[WCAG]</a>
In particular, the intensity of the foreground and background
must be sufficiently different.
In addition the hue of the foreground and background
should be sufficiently different.
Web pages exist to test colors against the various criteria.
<a href="#Snook">[Snook]</a>
Further, consideration must be given to red-green color deficiency.
</p>

<p>
By far, the most common use of color in WG21
is to mark inserted and deleted text.
The normal convention
is to use red for deleted text and green for inserted text.
However, this color combination is problematic for red-green deficient readers.
Instead, we use magenta in place of red.
The added blue to the color makes it visually distinct from green.
The other typical problem with the colors chosen
is that they are too bright to provide good contrast
with the typical light background.
So, these colors need to be resonably dark,
but still light enough to be distinct.
The foreground colors
<code>#005100</code> green and <code>#8B0040</code> red-magenta
meet the criteria against a fairly broad range of light backgrounds.
Unfortunately, once we specify a foreground color,
we must specify a specific background color.
A white background reduces printing costs.
</p>

<p>
However, these colors alone are not sufficient
to identify inserted and deleted text.
For that we must add text decoration.
In particular, we follow existing convention
and mark deleted text with a line struck through
and inserted text with an underline.
Now, even in the absence of color,
deletions and insertions are distinct.
</p>

<p>
Earlier, we described the need to
mark whole quoted paragraphs of the standard as deleted or inserted.
We do this by changing the background for the paragraph.
In particular, deleted quotes
have a <code>#FFEBFF</code> light magenta background
and inserted quotes
have a <code>#C8FFC8</code> light green background.
Regular quoted paragraphs of the standard
have a <code>#F1F1F1</code> light grey background.
Extracted code
has a <code>#F5F6A2</code> light yellow background.
Finally, each of these backgrounds
is surrounded by a thin, slightly darker, border.
This border provides an attractive edge to the quote.
More importantly,
when browsers ignore color, as in high-contrast mode,
they typically do not ignore borders.
These thin subtle borders become very visible when the color is lost.
</p>


<h3><a name="TableStyle">Tables</a></h3>

<p>
The default formatting of tables
makes identifying table cells difficult.
To address this problem
and to be consistent with the formatting of many (but not all)
of the standard's tables,
we make several formatting choices.
</p>

<ul>
<li><p>
Cell text is vertically aligned to the top,
which makes identifying rows easier.
</p></li>
<li><p>
Cell text is horizontally aligned to the left,
which makes identifying columns easier.
(Authors may choose to use right alignment for numeric columns.)
</p></li>
<li><p>
Cells are given a little bit of extra spacing.
</p></li>
<li><p>
Use a thin borders around the table, but not individual cells or the caption.
</p></li>
</ul>


<h3><a name="ExampleStyle">Examples</a></h3>

<p>
For examples, we just indent a bit.
</p>


<h3><a name="ExtractedStyle">Examples</a></h3>

<p>
For extracted code, we indent a bit
and use the background color for extracted code.
</p>


<h2><a name="References">References</a></h2>

<p>
References to WG21 papers can simply use the N-number.
References to WG14 papers can simply use "WG14" and the N-number.
These references should link to the appropriate documents,
via HTML like the following.
</p>

<pre class="example">
<code>This paper analyses the compatibility between the draft standards,
&lt;a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2010/n3035.pdf"&gt;
N3035&lt;/a&gt; and WG14
&lt;a href="http://www.open-std.org/jtc1/sc22/wg14/www/docs/n1425.pdf"&gt;
N1425&lt;/a&gt; with respect to alignment.</code>
</pre>

<p>
All other references should be elaborated in a references section,
such as this one.
The purpose of the references section
is to enable following references from printed documents.
NOTE: when there is a reference section,
it is unclear whether references should
link to the reference section entry
or link directly to the referrent.
</p>

<p>
The remainder of this section lists references for this document.
</p>

<dl>

<dt><a name="HTML401">[HTML401]</a></dt>
<dd>
<a href="http://www.w3.org/">W3C</a>,
<cite><a href="http://www.w3.org/TR/html401/">
HTML 4.01 Specification</a></cite>,
24 December 1999,
<a href="http://www.w3.org/TR/html401/">
http://www.w3.org/TR/html401/</a>
</dd>

<dt><a name="HTMLclass">[HTMLclass]</a></dt>
<dd>
<a href="http://www.w3.org/">W3C</a>,
<cite><a href="http://www.w3.org/TR/html401/">
HTML 4.01 Specification</a></cite>,
24 December 1999,
<a href="http://www.w3.org/TR/html401/struct/global.html#h-7.5.2">
7.5.2 Element identifiers: the id and class attributes</a>,
<a href="http://www.w3.org/TR/html401/struct/global.html#h-7.5.2">
http://www.w3.org/TR/html401/struct/global.html#h-7.5.2</a>.
</dd>

<dt><a name="HTMLdelins">[HTMLdelins]</a></dt>
<dd>
<a href="http://www.w3.org/">W3C</a>,
<cite><a href="http://www.w3.org/TR/html401/">
HTML 4.01 Specification</a></cite>,
24 December 1999,
<a href="http://www.w3.org/TR/html401/struct/text.html#h-9.4">
9.4 Marking document changes: The INS and DEL elements</a>,
<a href="http://www.w3.org/TR/html401/struct/text.html#h-9.4">
http://www.w3.org/TR/html401/struct/text.html#h-9.4</a>.
</dd>

<dt><a name="HTMLentity">[HTMLentity]</a></dt>
<dd>
<a href="http://www.w3.org/">W3C</a>,
<cite><a href="http://www.w3.org/TR/html401/">
HTML 4.01 Specification</a></cite>,
24 December 1999,
<a href="http://www.w3.org/TR/html401/sgml/entities.html">
24 Character entity references in HTML 4</a>,
<a href="http://www.w3.org/TR/html401/sgml/entities.html">
http://www.w3.org/TR/html401/sgml/entities.html</a>.
</dd>

<dt><a name="HTMLphrase">[HTMLphrase]</a></dt>
<dd>
<a href="http://www.w3.org/">W3C</a>,
<cite><a href="http://www.w3.org/TR/html401/">
HTML 4.01 Specification</a></cite>,
24 December 1999,
<a href="http://www.w3.org/TR/html401/struct/text.html#h-9.2.1">
9.2.1 Phrase elements:
EM, STRONG, DFN, CODE, SAMP, KBD, VAR, CITE, ABBR, and ACRONYM</a>,
<a href="http://www.w3.org/TR/html401/struct/text.html#h-9.2.1">
http://www.w3.org/TR/html401/struct/text.html#h-9.2.1</a>
</dd>

<dt><a name="HTMLfontstyle">[HTMLfontstyle]</a></dt>
<dd>
<a href="http://www.w3.org/">W3C</a>,
<cite><a href="http://www.w3.org/TR/html401/">
HTML 4.01 Specification</a></cite>,
24 December 1999,
<a href="http://www.w3.org/TR/html401/present/graphics.html#h-15.2.1">
15.2.1 Font style elements:
the TT, I, B, BIG, SMALL, STRIKE, S, and U elements</a>,
<a href="http://www.w3.org/TR/html401/present/graphics.html#h-15.2.1">
http://www.w3.org/TR/html401/present/graphics.html#h-15.2.1</a>.
</dd>

<dt><a name="HTMLfontelem">[HTMLfontelem]</a></dt>
<dd>
<a href="http://www.w3.org/">W3C</a>,
<cite><a href="http://www.w3.org/TR/html401/">
HTML 4.01 Specification</a></cite>,
24 December 1999,
<a href="http://www.w3.org/TR/html401/present/graphics.html#h-15.2.2">
15.2.2 Font modifier elements: FONT and BASEFONT</a>,
<a href="http://www.w3.org/TR/html401/present/graphics.html#h-15.2.2">
http://www.w3.org/TR/html401/present/graphics.html#h-15.2.2</a>.
</dd>

<dt><a name="HTMLline">[HTMLline]</a></dt>
<dd>
<a href="http://www.w3.org/">W3C</a>,
<cite><a href="http://www.w3.org/TR/html401/">
HTML 4.01 Specification</a></cite>,
24 December 1999,
<a href="http://www.w3.org/TR/html401/appendix/notes.html#notes-line-breaks">
B.3.1 Line breaks</a>,
<a href="http://www.w3.org/TR/html401/appendix/notes.html#notes-line-breaks">
http://www.w3.org/TR/html401/appendix/notes.html#notes-line-breaks</a>.
</dd>

<dt><a name="HTMLpre">[HTMLpre]</a></dt>
<dd>
<a href="http://www.w3.org/">W3C</a>,
<cite><a href="http://www.w3.org/TR/html401/">
HTML 4.01 Specification</a></cite>,
24 December 1999,
<a href="http://www.w3.org/TR/html401/struct/text.html#h-9.3.4">
9.3.4 Preformatted text: The PRE element</a>,
<a href="http://www.w3.org/TR/html401/struct/text.html#h-9.3.4">
http://www.w3.org/TR/html401/struct/text.html#h-9.3.4</a>.
</dd>

<dt><a name="HTMLquote">[HTMLquote]</a></dt>
<dd>
<a href="http://www.w3.org/">W3C</a>,
<cite><a href="http://www.w3.org/TR/html401/">
HTML 4.01 Specification</a></cite>,
24 December 1999,
<a href="http://www.w3.org/TR/html401/struct/text.html#h-9.2.2">
9.2.2 Quotations: The BLOCKQUOTE and Q elements</a>,
<a href="http://www.w3.org/TR/html401/struct/text.html#h-9.2.2">
http://www.w3.org/TR/html401/struct/text.html#h-9.2.2</a>.
</dd>

<dt><a name="HTMLspan">[HTMLspan]</a></dt>
<dd>
<a href="http://www.w3.org/">W3C</a>,
<cite><a href="http://www.w3.org/TR/html401/">
HTML 4.01 Specification</a></cite>,
24 December 1999,
<a href="http://www.w3.org/TR/html401/struct/global.html#h-7.5.4">
7.5.4 Grouping elements: the DIV and SPAN elements</a>,
<a href="http://www.w3.org/TR/html401/struct/global.html#h-7.5.4">
http://www.w3.org/TR/html401/struct/global.html#h-7.5.4</a>.
</dd>

<dt><a name="HTMLstyleinline">[HTMLstyleinline]</a></dt>
<dd>
<a href="http://www.w3.org/">W3C</a>,
<cite><a href="http://www.w3.org/TR/html401/">
HTML 4.01 Specification</a></cite>,
24 December 1999,
<a href="http://www.w3.org/TR/html401/present/styles.html#h-14.2.2">
14.2.2 Inline style information</a>,
<a href="http://www.w3.org/TR/html401/present/styles.html#h-14.2.2">
http://www.w3.org/TR/html401/present/styles.html#h-14.2.2</a>.
</dd>

<dt><a name="HTMLtable">[HTMLtable]</a></dt>
<dd>
<a href="http://www.w3.org/">W3C</a>,
<cite><a href="http://www.w3.org/TR/html401/">
HTML 4.01 Specification</a></cite>,
24 December 1999,
<a href="http://www.w3.org/TR/html401/struct/tables.html">
11 Tables</a>,
<a href="http://www.w3.org/TR/html401/struct/tables.html">
http://www.w3.org/TR/html401/struct/tables.html</a>.
</dd>

<dt><a name="LPcom">[LPcom]</a></dt>
<dd>
<a href="http://www.literateprogramming.com/">literateprogramming.com</a>,
<cite><a href="http://www.literateprogramming.com/">
Literate Programming</a></cite>,
<a href="http://www.literateprogramming.com/">
http://www.literateprogramming.com/</a>.
</dd>

<dt><a name="LPwiki">[LPwiki]</a></dt>
<dd>
<a href="http://en.wikipedia.org">Wikipedia</a>,
<cite><a href="http://en.wikipedia.org/wiki/Literate_programming">
Literate programming</a></cite>,
<a href="http://en.wikipedia.org/wiki/Literate_programming">
http://en.wikipedia.org/wiki/Literate_programming</a>.
</dd>

<dt><a name="Snook">[Snook]</a></dt>
<dd>
<a href="http://www.snook.ca/">snook,ca</a>,
<cite><a href="http://www.snook.ca/technical/colour_contrast/colour.html">
Colour Contrast Check</a></cite>,
6 December 2009,
<a href="http://www.snook.ca/technical/colour_contrast/colour.html">
http://www.snook.ca/technical/colour_contrast/colour.html</a>.
</dd>

<dt><a name="WCAG">[WCAG]</a></dt>
<dd>
<a href="http://www.w3.org/">W3C</a>,
<cite><a href="http://www.w3.org/TR/WCAG/">
Web Content Accessibility Guidelines (WCAG) 2.0</a></cite>,
11 December 2008,
<a href="http://www.w3.org/TR/WCAG/">
http://www.w3.org/TR/WCAG/</a>.
</dd>

</dl>

<h2><a name="Scripts">Scripts</a></h2>

<p>
This section contains several <code>sh</code>/<code>sed</code> scripts
supporting the methods in this document.
The scripts are contained within a <code>sh</code> script
that generates those files.
</p>

<h3><a name="quote_code.sh">quote_code.sh</a></h3>

<p>
This script quotes code.
The result may be used within paragraphs.
</p>

<pre><code class="extract">
cat &lt;&lt;"EOF" &gt;quote_code.sh
</code></pre>

<pre class="extract"><code class="extract">
exec sed -e '
1	i&lt;code&gt;
	s|&amp;|\&amp;amp;|g
	s|&lt;|\&amp;lt;|g
	s|&gt;|\&amp;gt;|g
$	a&lt;/code&gt;
' "$@"
</code></pre>

<pre><code class="extract">
EOF
</code></pre>

<h3><a name="block_code.sh">block_code.sh</a></h3>

<p>
This script creates an example block of code.
</p>

<pre><code class="extract">
cat &lt;&lt;"EOF" &gt;block_code.sh
</code></pre>

<pre class="extract"><code class="extract">
exec sed -e '
1	i&lt;pre class="example"&gt;
	s|&amp;|\&amp;amp;|g
	s|&lt;|\&amp;lt;|g
	s|&gt;|\&amp;gt;|g
1	s|^|&lt;code&gt;|
$	s|$|&lt;/code&gt;|
$	a&lt;/pre&gt;
' "$@"
</code></pre>

<pre><code class="extract">
EOF
</code></pre>

<h3><a name="block_extract.sh">block_extract.sh</a></h3>

<p>
This script creates an example block of code intended for extraction.
</p>

<pre><code class="extract">
cat &lt;&lt;"EOF" &gt;block_extract.sh
</code></pre>

<pre class="extract"><code class="extract">
exec sed -e '
1	i&lt;pre class="extract"&gt;&lt;code class="extract"&gt;
	s|&amp;|\&amp;amp;|g
	s|&lt;|\&amp;lt;|g
	s|&gt;|\&amp;gt;|g
$	a&lt;/code&gt;&lt;/pre&gt;
' "$@"
</code></pre>

<pre><code class="extract">
EOF
</code></pre>

<h3><a name="extract_code.sh">extract_code.sh</a></h3>

<p>
This script extracts code from an HTML source.
It can serve as the inverse function of the above,
is intended to extract more generally annotated code.
This script takes the class name as the first parameter.
</p>

<pre><code class="extract">
cat &lt;&lt;"EOF" &gt;extract_code.sh
</code></pre>

<pre class="extract"><code class="extract">
class=$1
shift
exec sed -e '
1,/&lt;code class="'$class'"&gt;/		d
/&lt;\/code&gt;/,/&lt;code class="'$class'"&gt;/	d
/&lt;\/code&gt;/,$				d
					s|&lt;[^&lt;&gt;]*&gt;||g
					s|&amp;lt;|&lt;|g
					s|&amp;gt;|&gt;|g
					s|&amp;nbsp;| |g
					s|&amp;amp;|\&amp;|g
' "$@"
</code></pre>

<pre><code class="extract">
EOF
</code></pre>

<h3><a name="contents.sh">contents.sh</a></h3>

<p>
This script creates a table of contents.
The first parameter to the script
is the depth of headings to include in the contents.
</p>

<pre><code class="extract">
cat &lt;&lt;"EOF" &gt;contents.sh
</code></pre>

<pre class="extract"><code class="extract">
usage()
{
echo "usage: $0 &lt;depth in [2-6]&gt; [&lt;file&gt;...]" 1&gt;&amp;2
}

if test $# -lt 1
then
	usage
	exit 1
fi

case $1 in
[2-6])
	DEPTH=$1
	shift
	;;
*)
	usage
	exit 1
	;;
esac

IN1="\&amp;nbsp;\&amp;nbsp;\&amp;nbsp;\&amp;nbsp;"
IN2="${IN1}{$IN1}"
IN3="${IN2}{$IN1}"
IN4="${IN3}{$IN1}"

sed -e '
1			i&lt;p&gt;
$			a&lt;/p&gt;
/&lt;h[2-'${DEPTH}']&gt;/	! d
			s|name="|href="#|
			s|&lt;/h[2-6]&gt;|&lt;br&gt;|
			s|&lt;h2&gt;||
			s|&lt;h3&gt;|'${IN1}'|
			s|&lt;h4&gt;|'${IN2}'|
			s|&lt;h5&gt;|'${IN3}'|
			s|&lt;h6&gt;|'${IN4}'|
' "$@"
</code></pre>

<pre><code class="extract">
EOF
</code></pre>

<h3><a name="dynacontents.js">dynacontents.js</a></h3>

<p>
This script creates a table of contents dynamically within the web page.
Place the script within the head of the HTML.
It assumes that the user has previously included
</p>
<p class="example">
<code>
&lt;script
src="https://ajax.googleapis.com/ajax/libs/jquery/1.7.1/jquery.min.js"
type="text/javascript"&gt;
&lt;/script&gt;"
</code>
</p>
<p>
It also assumes an <code>div</code> element, somewhere in the document,
with the id "toc", which it will fill in with the table of contents.
</p>
<p>
The browser must support Javascript,
and the browser must be network accessibile,
for the contents to appear.
</p>

<p>
Thanks to Jeffrey Yasskin for the code.
</p>

<pre><code class="extract">
cat &lt;&lt;"EOF" &gt;dynacontents.js
</code></pre>

<pre class="extract"><code class="extract">
&lt;script type="text/javascript"&gt;$(function() {
    var next_id = 0
    function find_id(node) {
        // Look down the first children of 'node' until we find one
        // with an id. If we don't find one, give 'node' an id and
        // return that.
        var cur = node[0];
        while (cur) {
            if (cur.id) return curid;
            if (cur.tagName == 'A' &amp;&amp; cur.name)
                return cur.name;
            cur = cur.firstChild;
        };
        // No id.
        node.attr('id', 'gensection-' + next_id++);
        return node.attr('id');
    };

    // Put a table of contents in the #toc nav.

    // This is a list of &lt;ol&gt; elements, where toc[N] is the list for
    // the current sequence of &lt;h(N+2)&gt; tags. When a header of an
    // existing level is encountered, all higher levels are popped,
    // and an &lt;li&gt; is appended to the level
    var toc = [$("&lt;ol/&gt;")];
    $(':header').not('h1').each(function() {
        var header = $(this);
        // For each &lt;hN&gt; tag, add a link to the toc at the appropriate
        // level.  When toc is one element too short, start a new list
        var levels = {H2: 0, H3: 1, H4: 2, H5: 3, H6: 4};
        var level = levels[this.tagName];
        if (typeof level == 'undefined') {
            throw 'Unexpected tag: ' + this.tagName;
        }
        // Truncate to the new level.
        toc.splice(level + 1, toc.length);
        if (toc.length &lt; level) {
            // Omit TOC entries for skipped header levels.
            return;
        }
        if (toc.length == level) {
            // Add a &lt;ol&gt; to the previous level's last &lt;li&gt; and push
            // it into the array.
            var ol = $('&lt;ol/&gt;')
            toc[toc.length - 1].children().last().append(ol);
            toc.push(ol);
        }
        var header_text = header.text();
        toc[toc.length - 1].append(
            $('&lt;li/&gt;').append($('&lt;a href="#' + find_id(header) + '"/&gt;')
                              .text(header_text)));
    });
    $('#toc').append(toc[0]);
})
&lt;/script&gt;
</code></pre>

<pre><code class="extract">
EOF
</code></pre>

<h3><a name="outline.sh">outline.sh</a></h3>

<p>
This script creates an outline of the document.
</p>

<pre><code class="extract">
cat &lt;&lt;"EOF" &gt;outline.sh
</code></pre>

<pre class="extract"><code class="extract">
SPC="[	 ]"
SPCSOPT="${SPC}*"
IN1="   "
IN2="${IN1}${IN1}"
IN3="${IN2}${IN1}"
IN4="${IN3}${IN1}"

exec sed -e "
/&lt;h[1-6]&gt;/	! d
		s/${SPCSOPT}&lt;h1&gt;//
		s/${SPCSOPT}&lt;h2&gt;//
		s/${SPCSOPT}&lt;h3&gt;/${IN1}&lt;h3&gt;/
		s/${SPCSOPT}&lt;h4&gt;/${IN2}&lt;h4&gt;/
		s/${SPCSOPT}&lt;h5&gt;/${IN3}&lt;h5&gt;/
		s/${SPCSOPT}&lt;h6&gt;/${IN4}&lt;h6&gt;/
		s/&lt;[^&gt;]*&gt;//g
" "$@"
</code></pre>

<pre><code class="extract">
EOF
</code></pre>

<h3><a name="outline_with_names.sh">outline_with_names.sh</a></h3>

<p>
This script creates an outline of the document,
including the anchor names.
</p>

<pre><code class="extract">
cat &lt;&lt;"EOF" &gt;outline_with_names.sh
</code></pre>

<pre class="extract"><code class="extract">
SPC="[	 ]"
SPCSOPT="${SPC}*"
SPCSREQ="${SPC}${SPCSOPT}"
DQT='"'
QUOTE='\("[^"]*"\)'
IDENT='\([^	 &gt;]*\)'
ANAME="&lt;a${SPCSREQ}name="
ENDA="${SPCSOPT}&gt;"
IN1="   "
IN2="${IN1}${IN1}"
IN3="${IN2}${IN1}"
IN4="${IN3}${IN1}"
LBL1='"[^"]\{0,5\}"'
LBL2='"[^"]\{6,13\}"'
LBL3='"[^"]\{14,21\}"'

exec sed -e "
/&lt;h[1-6]&gt;/	! d
		s|${SPCSOPT}&lt;h1&gt;||
		s|${SPCSOPT}&lt;h2&gt;||
		s|${SPCSOPT}&lt;h3&gt;|${IN1}&lt;h3&gt;|
		s|${SPCSOPT}&lt;h4&gt;|${IN2}&lt;h4&gt;|
		s|${SPCSOPT}&lt;h5&gt;|${IN3}&lt;h5&gt;|
		s|${SPCSOPT}&lt;h6&gt;|${IN4}&lt;h6&gt;|
		s|${ANAME}${QUOTE}${ENDA}|\1 |
		s|${ANAME}${IDENT}${ENDA}|"'"\1"'" |
		s|\(.*\)${QUOTE} \(.*\)$|\2	\1\3|
		s|\(${LBL1}\)|\1		|
		s|\(${LBL2}\)|\1	|
		s|&lt;[^&gt;]*&gt;||g
" "$@"
</code></pre>

<pre><code class="extract">
EOF
</code></pre>

<h3><a name="style.hinc">style.hinc</a></h3>

<p>
This style element implements the style choices described above.
It is intended for inclusion in WG21 papers.
</p>

<pre><code class="extract">
cat &lt;&lt;"EOF" &gt;style.hinc
</code></pre>

<pre class="extract"><code class="extract">
&lt;style type="text/css"&gt;

body { color: #000000; background-color: #FFFFFF; }
del { text-decoration: line-through; color: #8B0040; }
ins { text-decoration: underline; color: #005100; }

p.example { margin-left: 2em; }
pre.example { margin-left: 2em; }
div.example { margin-left: 2em; }

code.extract { background-color: #F5F6A2; }
pre.extract { margin-left: 2em; background-color: #F5F6A2;
  border: 1px solid #E1E28E; }

p.function { }
.attribute { margin-left: 2em; }
.attribute dt { float: left; font-style: italic;
  padding-right: 1ex; }
.attribute dd { margin-left: 0em; }

blockquote.std { color: #000000; background-color: #F1F1F1;
  border: 1px solid #D1D1D1;
  padding-left: 0.5em; padding-right: 0.5em; }
blockquote.stddel { text-decoration: line-through;
  color: #000000; background-color: #FFEBFF;
  border: 1px solid #ECD7EC;
  padding-left: 0.5empadding-right: 0.5em; ; }

blockquote.stdins { text-decoration: underline;
  color: #000000; background-color: #C8FFC8;
  border: 1px solid #B3EBB3; padding: 0.5em; }

table { border: 1px solid black; border-spacing: 0px;
  margin-left: auto; margin-right: auto; }
th { text-align: left; vertical-align: top;
  padding-left: 0.8em; border: none; }
td { text-align: left; vertical-align: top;
  padding-left: 0.8em; border: none; }

&lt;/style&gt;
</code></pre>

<pre><code class="extract">
EOF
</code></pre>

<h3><a name="Makefile">Makefile</a></h3>

<p>
This paper was put together with <code>make</code>,
so as to avoid manual conversions on all the examples.
It may be useful as a starting point for other papers.
</p>

<p>
The extensions used in the <code>Makefile</code> are as follows.
</p>
<table>
<thead>
<tr><th>extension</th><th>file use</th><th>comment</th></tr>
</thead>
<tbody>
<tr><td>.hsrc</td><td>source</td>
<td>an HTML source file with include directives</td></tr>
<tr><td>.hinc</td><td>source</td>
<td>an included HTML source file</td></tr>
<tr><td>.cc</td><td>source</td>
<td>a C/C++ source code file</td></tr>
<tr><td>.sh</td><td>source</td>
<td>a Bourne shell source code file</td></tr>
<tr><td>.html</td><td>product</td>
<td>a complete HTML file</td></tr>
<tr><td>.qinc</td><td>intermediate</td>
<td>a quoted version of a .hinc</td></tr>
<tr><td>.vinc</td><td>intermediate</td>
<td>a verbatim &lt;pre&gt; version of a .hinc</td></tr>
<tr><td>.cinc</td><td>intermediate</td>
<td>a contents file for an .hsrc file</td></tr>
<tr><td>.qcod</td><td>intermediate</td>
<td>a verbatim version of a source code file</td></tr>
<tr><td>.vcod</td><td>intermediate</td>
<td>a verbatim version of a .qcod file</td></tr>
<tr><td>.qext</td><td>intermediate</td>
<td>a code extraction version of a source code file</td></tr>
<tr><td>.vext</td><td>intermediate</td>
<td>a version of a .qext file</td></tr>
<tr><td>.xext</td><td>intermediate</td>
<td>the code extracted from an HTML file</td></tr>
</tbody>
</table>

<pre><code class="extract">
cat &lt;&lt;"EOF" &gt;Makefile
</code></pre>

<pre class="extract"><code class="extract">
default : help

help :
	@echo "make help      -- do nothing but print this message"
	@echo "make variables -- do nothing but show important build variables"
	@echo "make outline   -- show the paper outline"
	@echo "make documents -- build the HTML documents"
	@echo "make codefiles -- build the code files"
	@echo "make all       -- build the documents and code files"
	@echo "make test      -- test that extracted code files match sources"
	@echo "make clean     -- remove the documents and intermediate files"

INTERMEDIATE = *.qinc *.vinc *.cinc *.qcod *.vcod *.qext *.vext *.xext *.d

CPP = cpp -MMD -MP -w -P -C -traditional-cpp
DIFF = for f in *; do echo comparing $$f; diff ../$$f $$f; done

%.html : %.hsrc
	$(CPP) -MT $@ $&lt; $@

%.qinc : %.hinc
	sh quote_code.sh $&lt; &gt; $@

%.vinc : %.hinc
	sh block_code.sh $&lt; &gt; $@

%.cinc : %.hsrc
	sh contents.sh 6 $&lt; &gt; $@

%.qcod : %.cc
	sh block_code.sh $&lt; &gt; $@

%.vcod : %.qcod
	sh block_code.sh $&lt; &gt; $@

%.qext : %.sh
	sh block_extract.sh $&lt; &gt; $@

%.qext : %.js
	sh block_extract.sh $&lt; &gt; $@

%.qext : %.hinc
	sh block_extract.sh $&lt; &gt; $@

%.vext : %.qext
	sh block_code.sh $&lt; &gt; $@

%.xext : %.html
	sh extract_code.sh extract $&lt; &gt; $@

Makefile.qext : Makefile
	sh block_extract.sh $&lt; &gt; $@

SOURCES := $(shell echo *.hsrc)
PREBUILD := $(shell sh prebuild.sh $(SOURCES))
DOCUMENTS := $(SOURCES:.hsrc=.html)
CODEFILES = htmlcppstd.xext

variables :
	@echo "SOURCES  = $(SOURCES)"
	@echo "DOCUMENTS = $(DOCUMENTS)"
	@echo "PREBUILD = $(PREBUILD)"

outline :
	sh outline_with_names.sh htmlcppstd.hsrc

$(DOCUMENTS) : $(PREBUILD)

documents : $(DOCUMENTS)

codefiles : $(CODEFILES)

all : documents codefiles

testing :
	mkdir testing

test : htmlcppstd.xext testing
	cd testing ; sh ../htmlcppstd.xext ; $(DIFF)

clean :
	rm -rf testing $(DOCUMENTS) $(INTERMEDIATE)

-include *.d
</code></pre>

<pre><code class="extract">
EOF
</code></pre>

<pre><code class="extract">
cat &lt;&lt;"EOF" &gt;prebuild.sh
</code></pre>

<pre class="extract"><code class="extract">
SPC="[	 ]"
SPCSOPT="${SPC}*"
INCLDIR="^${SPCSOPT}#${SPCSOPT}include${SPCSOPT}"

exec sed -e '
/#include/	! d
/\.hinc/	d
		s/'"${INCLDIR}"'"\(.*\)".*/\1/
' "$@"
</code></pre>

<pre><code class="extract">
EOF
</code></pre>

</body>
</html>
