![]() | Name | Last modified | Size | Description |
---|---|---|---|---|
![]() | Parent Directory | - | ||
![]() | xhtml11/ | 18-Aug-2015 08:37 | - | |
![]() | tools/ | 22-Mar-2013 08:14 | - | |
![]() | test/ | 28-Aug-2015 08:26 | - | |
![]() | rst2xhtml11.py | 18-Aug-2015 08:37 | 1.2K | |
![]() | rst2xhtml.py | 21-Oct-2016 09:22 | 1.2K | |
![]() | html4strict/ | 22-Mar-2013 08:14 | - | |
![]() | docs/ | 28-Jan-2012 09:45 | - | |
![]() | data/ | 22-Mar-2013 08:14 | - | |
Author: | Günter Milde |
---|---|
Date: | 2016-10-20 |
Abstract
A HTML writer, generating XHTML 1.1 for styling with CSS 2.1.
Contents
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 (at the time of creation) widespread browsers (mainly IE6).
A new HTML5 writer with most features of this writer may become part of Docutils 0.13.
Goals of the xhtml11 writer:
[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. |
This writer is for you, if you
The rst2xhtml.py front end reads standalone reStructuredText source files and produces clean XHTML 1.1 output. A CSS 2 stylesheet is required for proper rendering; a complete sample stylesheet is provided.
Reader: | Standalone |
---|---|
Parser: | reStructuredText |
Writer: | xhtml (xhtml11) |
The front end can be called from the command line (when it is installed in the BINARY PATH):
rst2xhtml.py [options] [<source> [<destination>]]
The full usage text can be obtained with the --help option.
The front end rst2xhtml.py is also an example of programmatic use.
The writer module subclasses the html_plain.Writer and html_plain.HTMLTranslator classes and adds compatibility to the strict requirements of XHTML 1.1:
There is no attribute "lang" (only "xml:lang").
Enumerated lists don't support the 'start' attribute.
The style sheet xhtml11.css adds support for a "start" value for enumerated lists via a CSS-counter. This allows also nested enumeration.
<sup> and <sub> tags are not allowed in preformatted blocks (<pre>).
The math-output configuration setting defaults to "MathML".
The xhtml11.css style sheet extends the standard layout for CSS2-conforming HTML browsers.
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">
Items in the docinfo list are passed class arguments specifying their type to enable customizing 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.
A CSS counter for enumerated lists replaces the deprecated "start" attribute.
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, ...
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".
Unified test if a list is compactable:
Instead of hard-coded formatting with trailing , section numbers in section headings and the toc are placed in spans with class='sectnum' and separated from the heading by a CSS rule.
Do not mark the first child with 'class="first"' and the last child with 'class="last"' in definitions, table cells, field bodies, option descriptions, and list items. Use the :first-child and :last-child selectors instad.
The name of the language attribute changed from 'lang' in XHTML 1.0 to 'xml:lang' in XHTML 1.1. Documents using 'lang' do not validate.
The HTML4CSS1 writer does this to "produce visually compact lists (less vertical whitespace)". This writer relies on CSS rules for"visual compactness".
[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 |