sandbox/html4strict/README.txt

   1 .. readme.txt: introduction to the html4strict writer   -*- rst-mode -*-
   2 .. sectnum::
   3
   4 =====================================================
   5             The Strict HTML Writer
   6 =====================================================
   7
   8 :Author: Günter Milde
   9 :Date: $Date$
  10 :Abstract: A HTML writer, generating `XHTML 1.1` for styling
  11            with CSS 2.1.
  12
  13 .. contents::
  14
  15 Introduction
  16 ============
  17
  18 State of the art
  19 ----------------
  20
  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).
  24
  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.
  28
  29 Objective
  30 ----------
  31
  32 Goals of the `strict html writer`:
  33
  34 * Strict standards compliance.
  35
  36 * Generate good looking, readable, and accessible documents.
  37
  38 * Clear distinction of content and layout:
  39
  40   + Clean HTML output without "hard-coded" visual markup,
  41
  42   + extended configurability by CSS style sheets.
  43
  44 * `Graceful Degradation
  45   <http://www.anybrowser.org/campaign/abdesign.html#degradability>`__
  46
  47 * Best viewed with any (CSS2-conforming) HTML browser. [#]_
  48
  49 * Support scientific documents (numbering tables and figures, formal
  50   tables, ...). Cf. [markschenk]_.
  51
  52
  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.
  56
  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/
  61
  62 Audience
  63 --------
  64
  65 This writer is for you, if you
  66
  67 * care much about standards compliance,
  68
  69 * care less about the rendering in non-compliant browsers,
  70
  71 * want extended CSS configurability.
  72
  73 Manifest
  74 --------
  75
  76 * `<html4strict/>`_
  77
  78   * `<html4strict/__init__.py>`_: writer module
  79   * `<html4strict/html4css2.css>`_: additional CSS style sheet
  80
  81 * `<tools/>`_
  82
  83   * `<tools/rst2html_strict.py>`_: front end
  84
  85 * `<data/>`_
  86
  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.
  91
  92 Installation
  93 ============
  94
  95 1. Copy/Link/Move the `<html4strict/>`_ directory (including its
  96    contents) either into
  97
  98    * the ``docutils/writers/`` directory (alongside the standard
  99      writers), or
 100    * Python's `Module Search Path`_.
 101
 102 2. Copy/Link the standard style sheet ``html4css1.css`` into this this
 103    directory.
 104
 105 3. Copy/Link/Move `<tools/rst2html_strict.py>`_ into the binary PATH.
 106
 107 .. _Module Search Path:
 108    http://docs.python.org/tutorial/modules.html#the-module-search-path
 109
 110 Usage
 111 =====
 112
 113 Command line use::
 114
 115   rst2html_strict.py [options] [<source> [<destination>]]
 116
 117 The full usage text can be obtained with the ``--help`` option.
 118
 119 For an example of programmatic use, see `<tools/rst2html_strict.py>`_.
 120
 121
 122 Implementation
 123 ==============
 124
 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.
 128
 129 The html4css2.css style sheet extends the standard layout for
 130 CSS2-conforming Html browsers.
 131
 132
 133 Changes to the html4css1 writer
 134 -------------------------------
 135
 136 Document type
 137 ~~~~~~~~~~~~~
 138
 139 + The output conforms to the XHTML version 1.1 DTD::
 140
 141     <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
 142      '"http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
 143
 144   or XHTML + MathML::
 145
 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">
 148
 149
 150 Docinfo and field lists based on definition lists (instead of tables)
 151 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 152
 153 + Reduced loading time for documents with long field lists.
 154
 155 + Enables CSS styling for:
 156
 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
 161
 162 Class arguments for docinfo items
 163 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 164
 165 Items in the docinfo list are passed class arguments specifying
 166 their type to enable customization the docinfo layout.
 167
 168 The default style sheet contains example definitions: author and date
 169 are typeset centered and without label, if they occur as first docinfo
 170 fields.
 171
 172
 173 Footnotes and citations
 174 ~~~~~~~~~~~~~~~~~~~~~~~
 175
 176 + Based on definition lists.
 177
 178 + Collect adjacent footnotes/citations in one list.
 179
 180 Counter for enumerated lists
 181 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 182
 183 A CSS counter for `enumerated lists`_ replaces the deprecated "start"
 184 attribute.
 185
 186 .. _enumerated lists:
 187    ../../docutils/docs/ref/rst/restructuredtext.html#enumerated-lists
 188
 189 + Enables CSS styling for:
 190
 191   - label style (including nested numbers),
 192   - label separator.
 193
 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
 198 hanging indent.
 199
 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
 206 complete solution.
 207
 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]_.
 213
 214 However, a reasonable replacement of 'outside'-styled ordered lists
 215 with CSS is possible:
 216
 217 * The ordered list defines/resets the counter, the automatic numbering
 218   is suppressed::
 219
 220     ol {
 221       counter-reset: item;
 222       list-style-type: none  ! important;
 223     }
 224
 225 * The label is defined as "before" pseudo element. The content consists
 226   of the counter and a separator (by default a trailing dot)::
 227
 228     ol > li:before {
 229       counter-increment: item;
 230       content: counter(item) ".";
 231     }
 232
 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::
 236
 237     ol > li:before {
 238       display: inline-block;
 239       vertical-align: top;
 240       width: 2em;
 241       padding-right: 0.5em;
 242       text-align: right;
 243     }
 244
 245     ol > li > p { display: inline-block; }
 246
 247   However, subsequent paragraphs are to be set as nested block
 248   elements::
 249
 250     ol > li > p + p {
 251       display: block;
 252       margin-top: 0em;
 253     }
 254
 255 * The hanging indent is realized via a negative "textindent"
 256   which must be reset for the list content to prevent over-striking::
 257
 258     ol > li { text-indent: -2.5em; }
 259     ol > li > p { text-indent: 0em; }
 260
 261 The resulting list can be customized to a large extend
 262
 263 * Different label types and separators are possible, e.g.::
 264
 265     ol.lowerroman  > li:before {
 266       content: "(" counter(item, lower-roman) ")";
 267     }
 268
 269 * nested counters (1, 1.1, 1.1.1, etc)::
 270
 271     ol.nested > li:before {
 272       content: counters(item, ".") ". ";
 273     }
 274
 275 * chapter/section prefix, continued lists, ...
 276
 277 .. _W3C example: http://www.w3.org/TR/CSS2/generate.html#counters
 278 .. _taming lists: http://www.alistapart.com/articles/taminglists/
 279
 280
 281
 282 Inline literal role with ``pre-wrap``
 283 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 284
 285 In contrast to the html4css1 writer, runs of whitespace are not
 286 replaced by ``&nbsp;`` entities (cf. bug #1938891).
 287
 288 Whitespace-handling and wrapping are configured with the CSS
 289 property ``white-space: pre-wrap``:
 290
 291   Whitespace is preserved by the browser. Text will wrap when
 292   necessary, and on line breaks
 293
 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__
 299
 300 In order to allow line-wrap at whitespace only,
 301 words-with-non-word-chars are wrapped in <span>s with class "pre".
 302
 303 + simpler HTML code
 304
 305 + White-space handling in inline literals configurable with the CSS
 306   stylesheet. Possible values: ``normal, nowrap, pre, pre-wrap,
 307   pre-line``.
 308
 309 __ http://docutils.sf.net/docs/ref/rst/restructuredtext.html#inline-literals
 310
 311
 312 Table styling with CSS
 313 ~~~~~~~~~~~~~~~~~~~~~~
 314
 315 + No hard-coded border setting in the table head.
 316
 317 + Pre-defined table styles selected by class arguments "borderless"
 318   and "booktabs" matching the interpretation in the latex2e writer.
 319
 320 SimpleListChecker also checks field-lists and docinfo
 321 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 322
 323 Unified test if a list is compactable:
 324
 325 + cleaner code
 326
 327 + also works for nesting field-list in enumeration/bullet-list and
 328   vice versa
 329
 330 + also test docinfo, as a field may contain more than one paragraph
 331
 332
 333 Docutils-generated section numbers in a <span>
 334 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 335
 336 Instead of hard-coded formatting with trailing ``&nbsp;``,
 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.
 339
 340 Omit redundant class arguments
 341 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 342
 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.
 347
 348 Language attribute name changed to 'xml:lang'
 349 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 350
 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.
 353
 354
 355 Do not omit <p> tags
 356 ~~~~~~~~~~~~~~~~~~~~
 357
 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".
 361
 362
 363 TODO
 364 ----
 365
 366 * The first list in the test `2.3. Enumerated Lists` should be
 367   compact.
 368
 369 * Hanging indent for numbered section headings and ToC entries.
 370
 371 * search stylesheets along standard path if enclosed in <>
 372   (like the RST syntax for include files).
 373
 374 * Validate output with "critical" cases not covered by
 375   the functional test (e.g. headings with level > 6).
 376
 377 * Check, whether we should use the advise from
 378   http://www.evotech.net/blog/2009/02/css-browser-support/
 379
 380     To force IE8 to render your page in IE8 compliance mode, include the
 381     following meta tag::
 382
 383      <meta http-equiv="X-UA-Compatible" content="IE=8" />
 384
 385 * Move widely supported constructs to the html4css1 writer.
 386
 387 * Number sections with CSS if sectnum_xform is False.
 388
 389 * Footnotes and Citations (for footnotes see
 390   http://www.archiva.net/footnote/index.htm and
 391   http://www.xmlplease.com/footnotes
 392
 393
 394 References
 395 ==========
 396
 397 .. [cmdline-tool]
 398    `Inside A Docutils Command-Line Front-End Tool
 399    <http://docutils.sourceforge.net/docs/api/cmdline-tool.html>`_
 400 .. [API]
 401    `API Reference Material for Client-Developers
 402    <http://docutils.sf.net/docs/index.html#api-api-reference-material-for-client-developers>`_
 403 .. [ilovetypography]
 404    http://ilovetypography.com/2008/02/28/a-guide-to-web-typography/
 405 .. [webtypography]
 406    http://webtypography.net/toc/
 407 .. [tekkie]
 408    http://tekkie.flashbit.net/css/replacement-for-deprecated-ol-li-start-value-html-attributes,
 409    2009.
 410 .. [webjunction]
 411    http://lists.webjunction.org/wjlists/web4lib/2001-September/026413.html,
 412    2001.
 413 .. [codelair] http://www.doheth.co.uk/codelair/html-css/deprecated#start,
 414    2007.
 415 .. [highdots]
 416    http://www.highdots.com/forums/cascading-style-sheets/using-css-set-start-number-262555.html,
 417    2008.
 418 .. [dev.opera]
 419    http://dev.opera.com/articles/view/automatic-numbering-with-css-counters/,
 420    2008.
 421 .. [markschenk] `Publishing scientific documents with XHTML and CSS
 422    <http://www.markschenk.com/cssexp/publication/article.xml>`__
 423
 424 `<../html4trans>`_
 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>`__).