Name	Last modified	Size

Parent Directory		-
tools/	22-Mar-2013 08:14	-
html4strict/	22-Mar-2013 08:14	-
docs/	28-Jan-2012 09:45	-
data/	22-Mar-2013 08:14	-

The Strict HTML Writer

Author:	Günter Milde
Date:	2010-12-06

Abstract

A HTML writer, generating XHTML 1.1 for styling with CSS 2.1.

Contents

1 Introduction

1.1 State of the art

Docutils' default HTML Writer, docutils.writers.html4css1 generates output that conforms to the HTML 4.01 Transitional DTD and to the Extensible HTML version 1.0 Transitional DTD (almost strict).

Almost, as it contains some deprecated constructs and "a minimum of formatting information" in order to ensure correct display with deficient but widespread browsers.

1.2 Objective

Goals of the strict html writer:

Strict standards compliance.
Generate good looking, readable, and accessible documents.
Clear distinction of content and layout:
- Clean HTML output without "hard-coded" visual markup,
- extended configurability by CSS style sheets.
Graceful Degradation
Best viewed with any (CSS2-conforming) HTML browser. [1]
Support scientific documents (numbering tables and figures, formal tables, ...). Cf. [markschenk].

[1]	Tested with Firefox, Midori, Konqueror and Opera. As Safari and Google Chrome use the same rendering engine as Midori and Konqueror (WebKit), they should work fine as well.

1.3 Audience

This writer is for you, if you

care much about standards compliance,
care less about the rendering in non-compliant browsers,
want extended CSS configurability.

1.4 Manifest

html4strict/
- html4strict/__init__.py: writer module
- html4strict/html4css2.css: additional CSS style sheet
tools/
- tools/rst2html_strict.py: front end
data/
- data/standalone_rst_html4strict.html,
- data/standalone_rst_html4strict.txt: reStructuredText Test Document
- simple-lists.html,
- simple-lists.txt: test the list compactation algorithm.

2 Installation

Copy/Link/Move the html4strict/ directory (including its contents) either into
- the docutils/writers/ directory (alongside the standard writers), or
- Python's Module Search Path.
Copy/Link the standard style sheet html4css1.css into this this directory.
Copy/Link/Move tools/rst2html_strict.py into the binary PATH.

3 Usage

Command line use:

rst2html_strict.py [options] [<source> [<destination>]]

The full usage text can be obtained with the --help option.

For an example of programmatic use, see tools/rst2html_strict.py.

4 Implementation

The writer module subclasses the html4css1.Writer and html4css1.HTMLTranslator classes. Some methods are overwritten to replace deprecated HTML constructs or hard coded formatting.

The html4css2.css style sheet extends the standard layout for CSS2-conforming Html browsers.

4.1 Changes to the html4css1 writer

4.1.1 Document type

The output conforms to the XHTML version 1.1 DTD:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
 '"http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">

or XHTML + MathML:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1 plus MathML 2.0//EN"
"http://www.w3.org/Math/DTD/mathml2/xhtml-math11-f.dtd">

4.1.2 Docinfo and field lists based on definition lists (instead of tables)

Reduced loading time for documents with long field lists.
Enables CSS styling for:
- label width (obsoleting the --field-name-limit option)
- handling of long labels: truncate, wrap, ...
- label separator (default: ':')
- compact vs. open list

4.1.3 Class arguments for docinfo items

Items in the docinfo list are passed class arguments specifying their type to enable customization the docinfo layout.

The default style sheet contains example definitions: author and date are typeset centered and without label, if they occur as first docinfo fields.

4.1.4 Footnotes and citations

Based on definition lists.
Collect adjacent footnotes/citations in one list.

4.1.5 Counter for enumerated lists

A CSS counter for enumerated lists replaces the deprecated "start" attribute.

Enables CSS styling for:
- label style (including nested numbers),
- label separator.

The complicated part was to find out a correct CSS rule-set to replicate the standard behaviour with hanging indent (list-style: "outside"). There is a W3C example to number nested list items, however, the result is similar to 'list-style: inside': subsequent lines start below the label instead of a hanging indent.

Most Internet resources come to the conclusion that "there’s no straightforward replacement mechanism" [tekkie], "the solution is buried so deep in CSS2 that there's no point in trying to do it in CSS for the foreseeable future" [webjunction], or "the main point to note is that there is no direct mapping from the previous behaviour to CSS" [codelair]. Taming Lists did give valuable advise but no working complete solution.

The common advise is "Use 'HTML 4.01 Transitional' and keep the START attribute". [highdots], especially, since "There are arguments over whether the start attribute is presentational or not, and indeed HTML5 has declared that it is no longer deprecated in the current working drafts (at the time of writing)" [dev.opera].

However, a reasonable replacement of 'outside'-styled ordered lists with CSS is possible:

The ordered list defines/resets the counter, the automatic numbering is suppressed:
```
ol {
  counter-reset: item;
  list-style-type: none  ! important;
}
```
The label is defined as "before" pseudo element. The content consists of the counter and a separator (by default a trailing dot):
```
ol > li:before {
  counter-increment: item;
  content: counter(item) ".";
}
```
The label is right aligned in a box. Both the label and the list content (which Docutils puts in a paragraph node) must be displayed as "inline-block" so that they line up:
```
ol > li:before {
  display: inline-block;
  vertical-align: top;
  width: 2em;
  padding-right: 0.5em;
  text-align: right;
}

ol > li > p { display: inline-block; }
```
However, subsequent paragraphs are to be set as nested block elements:
```
ol > li > p + p {
  display: block;
  margin-top: 0em;
}
```
The hanging indent is realized via a negative "textindent" which must be reset for the list content to prevent over-striking:
```
ol > li { text-indent: -2.5em; }
ol > li > p { text-indent: 0em; }
```

The resulting list can be customized to a large extend

Different label types and separators are possible, e.g.:

ol.lowerroman  > li:before {
  content: "(" counter(item, lower-roman) ")";
}

nested counters (1, 1.1, 1.1.1, etc):

ol.nested > li:before {
  content: counters(item, ".") ". ";
}

chapter/section prefix, continued lists, ...

4.1.6 Inline literal role with `pre-wrap`

In contrast to the html4css1 writer, runs of whitespace are not replaced by   entities (cf. bug #1938891).

Whitespace-handling and wrapping are configured with the CSS property white-space: pre-wrap:

Whitespace is preserved by the browser. Text will wrap when necessary, and on line breaks

However, most browsers wrap on non-word chars, too, if set to wrap at white-space. Text like "--an-option" or the regular expression [+]?(\d+(\.\d*)?|\.\d+) may be broken at the wrong place! The setting white-space: pre; prevents this, but also prevents wrapping at white space, contrary to the specification

In order to allow line-wrap at whitespace only, words-with-non-word-chars are wrapped in <span>s with class "pre".

simpler HTML code
White-space handling in inline literals configurable with the CSS stylesheet. Possible values: normal, nowrap, pre, pre-wrap, pre-line.

4.1.7 Table styling with CSS

No hard-coded border setting in the table head.
Pre-defined table styles selected by class arguments "borderless" and "booktabs" matching the interpretation in the latex2e writer.

4.1.8 SimpleListChecker also checks field-lists and docinfo

Unified test if a list is compactable:

cleaner code
also works for nesting field-list in enumeration/bullet-list and vice versa
also test docinfo, as a field may contain more than one paragraph

The first list in the test 2.3. Enumerated Lists should be compact.
Hanging indent for numbered section headings and ToC entries.
search stylesheets along standard path if enclosed in <> (like the RST syntax for include files).
Validate output with "critical" cases not covered by the functional test (e.g. headings with level > 6).
Check, whether we should use the advise from http://www.evotech.net/blog/2009/02/css-browser-support/
To force IE8 to render your page in IE8 compliance mode, include the following meta tag:
```
<meta http-equiv="X-UA-Compatible" content="IE=8" />
```
Move widely supported constructs to the html4css1 writer.
Number sections with CSS if sectnum_xform is False.
Footnotes and Citations (for footnotes see http://www.archiva.net/footnote/index.htm and http://www.xmlplease.com/footnotes

5 References

[cmdline-tool]

Inside A Docutils Command-Line Front-End Tool

[API]

API Reference Material for Client-Developers

[ilovetypography]

http://ilovetypography.com/2008/02/28/a-guide-to-web-typography/

[webtypography]

http://webtypography.net/toc/

[tekkie]

http://tekkie.flashbit.net/css/replacement-for-deprecated-ol-li-start-value-html-attributes, 2009.

[webjunction]

http://lists.webjunction.org/wjlists/web4lib/2001-September/026413.html, 2001.

[codelair]

http://www.doheth.co.uk/codelair/html-css/deprecated#start, 2007.

[highdots]

http://www.highdots.com/forums/cascading-style-sheets/using-css-set-start-number-262555.html, 2008.

[dev.opera]

http://dev.opera.com/articles/view/automatic-numbering-with-css-counters/, 2008.

[markschenk]

Publishing scientific documents with XHTML and CSS

../html4trans: is a similar sandbox project, a HTML writer producing XHTML that contains enough formatting information to be viewed without a cascading style sheet by a lightweight html browser (e.g. Dillo or the console browser elinks).

Index of /sandbox/html4strict