1 .. readme.txt: introduction to the html4strict writer -*- rst-mode -*-
4 =====================================================
6 =====================================================
10 :Abstract: A HTML writer, generating `XHTML 1.1` for styling
21 Docutils' default HTML Writer, ``docutils.writers.html4css1`` generates
22 output that conforms to the HTML 4.01 Transitional DTD and to the
23 Extensible HTML version 1.0 Transitional DTD (*almost* strict).
25 *Almost*, as it contains some deprecated constructs and "a minimum of
26 formatting information" in order to ensure correct display with deficient
27 but widespread browsers.
32 Goals of the `strict html writer`:
34 * Strict standards compliance.
36 * Generate good looking, readable, and accessible documents.
38 * Clear distinction of content and layout:
40 + Clean HTML output without "hard-coded" visual markup,
42 + extended configurability by CSS style sheets.
44 * `Graceful Degradation
45 <http://www.anybrowser.org/campaign/abdesign.html#degradability>`__
47 * Best viewed with any (CSS2-conforming) HTML browser. [#]_
49 * Support scientific documents (numbering tables and figures, formal
50 tables, ...). Cf. [markschenk]_.
53 .. [#] Tested with Firefox_, Midori_, Konqueror_ and Opera_. As Safari
54 and Google Chrome use the same rendering engine as Midori and
55 Konqueror (WebKit), they should work fine as well.
57 .. _firefox: http://www.mozilla.com
58 .. _opera: http://www.opera.com
59 .. _midori: http://www.twotoasts.de/index.php?/pages/midori_summary.html
60 .. _konqueror: http://konqueror.kde.org/
65 This writer is for you, if you
67 * care much about standards compliance,
69 * care less about the rendering in non-compliant browsers,
71 * want extended CSS configurability.
78 * `<html4strict/__init__.py>`_: writer module
79 * `<html4strict/html4css2.css>`_: additional CSS style sheet
83 * `<tools/rst2html_strict.py>`_: front end
87 * `<data/standalone_rst_html4strict.html>`_,
88 * `<data/standalone_rst_html4strict.txt>`_: reStructuredText Test Document
89 * `<simple-lists.html>`_,
90 * `<simple-lists.txt>`_: test the list compactation algorithm.
95 1. Copy/Link/Move the `<html4strict/>`_ directory (including its
98 * the ``docutils/writers/`` directory (alongside the standard
100 * Python's `Module Search Path`_.
102 2. Copy/Link the standard style sheet ``html4css1.css`` into this this
105 3. Copy/Link/Move `<tools/rst2html_strict.py>`_ into the binary PATH.
107 .. _Module Search Path:
108 http://docs.python.org/tutorial/modules.html#the-module-search-path
115 rst2html_strict.py [options] [<source> [<destination>]]
117 The full usage text can be obtained with the ``--help`` option.
119 For an example of programmatic use, see `<tools/rst2html_strict.py>`_.
125 The writer module subclasses the ``html4css1.Writer`` and
126 ``html4css1.HTMLTranslator`` classes. Some methods are overwritten to
127 replace deprecated HTML constructs or hard coded formatting.
129 The html4css2.css style sheet extends the standard layout for
130 CSS2-conforming Html browsers.
133 Changes to the html4css1 writer
134 -------------------------------
139 + The output conforms to the XHTML version 1.1 DTD::
141 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
142 '"http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
146 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1 plus MathML 2.0//EN"
147 "http://www.w3.org/Math/DTD/mathml2/xhtml-math11-f.dtd">
150 Docinfo and field lists based on definition lists (instead of tables)
151 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
153 + Reduced loading time for documents with long field lists.
155 + Enables CSS styling for:
157 - label width (obsoleting the ``--field-name-limit`` option)
158 - handling of long labels: truncate, wrap, ...
159 - label separator (default: ':')
160 - compact vs. open list
162 Class arguments for docinfo items
163 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
165 Items in the docinfo list are passed class arguments specifying
166 their type to enable customization the docinfo layout.
168 The default style sheet contains example definitions: author and date
169 are typeset centered and without label, if they occur as first docinfo
173 Footnotes and citations
174 ~~~~~~~~~~~~~~~~~~~~~~~
176 + Based on definition lists.
178 + Collect adjacent footnotes/citations in one list.
180 Counter for enumerated lists
181 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
183 A CSS counter for `enumerated lists`_ replaces the deprecated "start"
186 .. _enumerated lists:
187 ../../docutils/docs/ref/rst/restructuredtext.html#enumerated-lists
189 + Enables CSS styling for:
191 - label style (including nested numbers),
194 The complicated part was to find out a correct CSS rule-set to replicate the
195 standard behaviour with hanging indent (list-style: "outside"). There is a
196 `W3C example`_ to number nested list items, however, the result is similar
197 to 'list-style: inside': subsequent lines start below the label instead of a
200 Most Internet resources come to the conclusion that "there’s no
201 straightforward replacement mechanism" [tekkie]_, "the solution is
202 buried so deep in CSS2 that there's no point in trying to do it in CSS
203 for the foreseeable future" [webjunction]_, or "the main point to note
204 is that there is no direct mapping from the previous behaviour to CSS"
205 [codelair]_. `Taming Lists`_ did give valuable advise but no working
208 The common advise is "Use 'HTML 4.01 Transitional' and keep the START
209 attribute". [highdots]_, especially, since "There are arguments over
210 whether the start attribute is presentational or not, and indeed HTML5
211 has declared that it is no longer deprecated in the current working
212 drafts (at the time of writing)" [dev.opera]_.
214 However, a reasonable replacement of 'outside'-styled ordered lists
215 with CSS is possible:
217 * The ordered list defines/resets the counter, the automatic numbering
222 list-style-type: none ! important;
225 * The label is defined as "before" pseudo element. The content consists
226 of the counter and a separator (by default a trailing dot)::
229 counter-increment: item;
230 content: counter(item) ".";
233 * The label is right aligned in a box. Both the label and the list
234 content (which Docutils puts in a paragraph node) must be displayed
235 as "inline-block" so that they line up::
238 display: inline-block;
241 padding-right: 0.5em;
245 ol > li > p { display: inline-block; }
247 However, subsequent paragraphs are to be set as nested block
255 * The hanging indent is realized via a negative "textindent"
256 which must be reset for the list content to prevent over-striking::
258 ol > li { text-indent: -2.5em; }
259 ol > li > p { text-indent: 0em; }
261 The resulting list can be customized to a large extend
263 * Different label types and separators are possible, e.g.::
265 ol.lowerroman > li:before {
266 content: "(" counter(item, lower-roman) ")";
269 * nested counters (1, 1.1, 1.1.1, etc)::
271 ol.nested > li:before {
272 content: counters(item, ".") ". ";
275 * chapter/section prefix, continued lists, ...
277 .. _W3C example: http://www.w3.org/TR/CSS2/generate.html#counters
278 .. _taming lists: http://www.alistapart.com/articles/taminglists/
282 Inline literal role with ``pre-wrap``
283 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
285 In contrast to the html4css1 writer, runs of whitespace are not
286 replaced by `` `` entities (cf. bug #1938891).
288 Whitespace-handling and wrapping are configured with the CSS
289 property ``white-space: pre-wrap``:
291 Whitespace is preserved by the browser. Text will wrap when
292 necessary, and on line breaks
294 However, most browsers wrap on non-word chars, too, if set to wrap
295 at white-space. Text like "--an-option" or the regular expression
296 ``[+]?(\d+(\.\d*)?|\.\d+)`` may be broken at the wrong place!
297 The setting ``white-space: pre;`` prevents this, but also
298 prevents wrapping at white space, contrary to the specification__
300 In order to allow line-wrap at whitespace only,
301 words-with-non-word-chars are wrapped in <span>s with class "pre".
305 + White-space handling in inline literals configurable with the CSS
306 stylesheet. Possible values: ``normal, nowrap, pre, pre-wrap,
309 __ http://docutils.sf.net/docs/ref/rst/restructuredtext.html#inline-literals
312 Table styling with CSS
313 ~~~~~~~~~~~~~~~~~~~~~~
315 + No hard-coded border setting in the table head.
317 + Pre-defined table styles selected by class arguments "borderless"
318 and "booktabs" matching the interpretation in the latex2e writer.
320 SimpleListChecker also checks field-lists and docinfo
321 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
323 Unified test if a list is compactable:
327 + also works for nesting field-list in enumeration/bullet-list and
330 + also test docinfo, as a field may contain more than one paragraph
333 Docutils-generated section numbers in a <span>
334 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
336 Instead of hard-coded formatting with trailing `` ``,
337 section numbers in section headings and the toc are placed in spans
338 with ``class='sectnum'`` and separated from the heading by a CSS rule.
340 Omit redundant class arguments
341 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
343 Do not mark the first child with 'class="first"' and the last
344 child with 'class="last"' in definitions, table cells, field
345 bodies, option descriptions, and list items. Use the
346 ``:first-child`` and ``:last-child`` selectors instad.
348 Language attribute name changed to 'xml:lang'
349 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
351 The name of the language attribute changed from 'lang' in XHTML 1.0 to
352 'xml:lang' in XHTML 1.1. Documents using 'lang' do not validate.
358 The HTML4CSS1 writer does this to "produce visually compact lists
359 (less vertical whitespace)". This writer relies on CSS rules
360 for"visual compactness".
366 * The first list in the test `2.3. Enumerated Lists` should be
369 * Hanging indent for numbered section headings and ToC entries.
371 * search stylesheets along standard path if enclosed in <>
372 (like the RST syntax for include files).
374 * Validate output with "critical" cases not covered by
375 the functional test (e.g. headings with level > 6).
377 * Check, whether we should use the advise from
378 http://www.evotech.net/blog/2009/02/css-browser-support/
380 To force IE8 to render your page in IE8 compliance mode, include the
383 <meta http-equiv="X-UA-Compatible" content="IE=8" />
385 * Move widely supported constructs to the html4css1 writer.
387 * Number sections with CSS if sectnum_xform is False.
389 * Footnotes and Citations (for footnotes see
390 http://www.archiva.net/footnote/index.htm and
391 http://www.xmlplease.com/footnotes
398 `Inside A Docutils Command-Line Front-End Tool
399 <http://docutils.sourceforge.net/docs/api/cmdline-tool.html>`_
401 `API Reference Material for Client-Developers
402 <http://docutils.sf.net/docs/index.html#api-api-reference-material-for-client-developers>`_
404 http://ilovetypography.com/2008/02/28/a-guide-to-web-typography/
406 http://webtypography.net/toc/
408 http://tekkie.flashbit.net/css/replacement-for-deprecated-ol-li-start-value-html-attributes,
411 http://lists.webjunction.org/wjlists/web4lib/2001-September/026413.html,
413 .. [codelair] http://www.doheth.co.uk/codelair/html-css/deprecated#start,
416 http://www.highdots.com/forums/cascading-style-sheets/using-css-set-start-number-262555.html,
419 http://dev.opera.com/articles/view/automatic-numbering-with-css-counters/,
421 .. [markschenk] `Publishing scientific documents with XHTML and CSS
422 <http://www.markschenk.com/cssexp/publication/article.xml>`__
425 is a similar sandbox project, a HTML writer producing XHTML that
426 contains enough formatting information to be viewed without a
427 cascading style sheet by a lightweight html browser
428 (e.g. `Dillo <http://www.dillo.org>`__ or the console browser
429 `elinks <http://elinks.cz>`__).