docs/user/html.txt

   1 =====================
   2 Docutils HTML writers
   3 =====================
   4
   5 .. note:: This document is a working draft. Naming of writers, aliases, and
   6    front-ends may change before the release of Docutils 0.13.
   7
   8 .. contents::
   9
  10 Overview
  11 --------
  12
  13 * `Generic HTML writers`_
  14
  15   =========== ============== ============== ================= ===========
  16   name        alias(es)      `front-end`_   HTML version      CSS version
  17   =========== ============== ============== ================= ===========
  18   html4css1_  html4          rst2html4.py   `XHTML 1          `CSS 1`_
  19                                             Transitional`_
  20
  21   ..          html_          rst2html.py    `XHTML 1          `CSS 1`_
  22                                             Transitional`_
  23
  24   html_plain_ html5_         rst2html5.py   `HTML 5`_         `CSS 3`_
  25   =========== ============== ============== ================= ===========
  26
  27 * `Special HTML writers`_
  28
  29   =========== ============== ============== ================= ===========
  30   name        alias(es)      `front-end`_   HTML version      CSS version
  31   =========== ============== ============== ================= ===========
  32   pep_html_   ..             rstpep2html.py `XHTML 1          `CSS 1`_
  33                                             Transitional`_
  34
  35   s5_html_    s5             rst2s5.py      `XHTML 1          `CSS 1`_
  36                                             Transitional`_
  37   =========== ============== ============== ================= ===========
  38
  39 * `HTML writers in the sandbox`_
  40
  41   =========== ============== ============== ================= ===========
  42   name        alias(es)      `front-end`_   HTML version      CSS version
  43   =========== ============== ============== ================= ===========
  44   xhtml11_    xhtml,         rst2xhtml.py   `XHTML 1.1`_      `CSS 3`_
  45               html4strict
  46
  47   html4trans_ ..             rst2html_trans `XHTML 1          no CSS
  48                                             Transitional`_    required
  49   =========== ============== ============== ================= ===========
  50
  51
  52 .. _front-end: tools.html
  53
  54 Generic HTML writers
  55 --------------------
  56
  57 html4css1
  58 ~~~~~~~~~
  59
  60 :aliases:    html4, html_
  61 :front-ends: rst2html4.py, rst2html.py_
  62 :config:     `[html4css1 writer]`_
  63
  64 The HTML Writer module, ``docutils/writers/html4css1.py``, started
  65 as a proof-of-concept reference implementation. It is the first Docutils
  66 writer and was up to release 0.13 the only official HTML writer.
  67
  68 The output conforms to the `XHTML 1 Transitional`_ specification. It does
  69 not validate as `HTML 4.01 Transitional`_ due to the closing of empty tags
  70 required in XML but not allowed in HTML 4. However, the output follows the
  71 `HTML Compatibility Guidelines`_ for proper rendering on most HTML user
  72 agents.
  73
  74 Correct rendering depends on a CSS_ style sheet. A reference style sheet,
  75 `html4css1.css`_, is provided and used by default.
  76
  77 To support the `Internet Explorer` (with a market share of about 90% around
  78 2002, the time this writer was written), documents contain some hard-coded
  79 formatting hints and are tagged as "text/html" (instead of
  80 "application/xhtml+xml"). [#IE]_
  81
  82 .. [#IE] Conformance to `CSS 2.1`_ has been added in IE 8 (2009), support
  83    for XHTML in IE 9 (2011).
  84
  85 .. TODO: How to name a specific alias/front-end pointing to html4css1?
  86
  87    html4
  88      | +1 short form of html4css1,
  89      | -1 writer produces XHTML 1, not HTML 4
  90    xhtml1
  91      | +1 correct and short description of the output format.
  92      | -1 may be confused with xhtml11 or xhtml (aliases for the
  93           "new" XHTML 1.1. writer inheriting from html_plain).
  94
  95
  96 .. _rst2html.py: tools.html#rst2html-py
  97 .. _[html4css1 writer]: config.html#html4css1-writer
  98 .. _html4css1.css: ../../docutils/writers/html4css1/html4css1.css
  99
 100
 101 html_plain
 102 ~~~~~~~~~~
 103
 104 :aliases: html5_
 105 :front-end: rst2html5.py_
 106 :config: `[html-plain writer]`_
 107
 108 The `html_plain` module is both, basis for other HTML writers and a
 109 versatile writer for end-users or programmatic use.
 110
 111 The ``html_plain`` writer generates `polyglot HTML`_ output that is
 112 compatible with `HTML 5`_ and `XHTML 1 Transitional`_. New features and
 113 elements will only be used if they are widely supported to make documents
 114 `viewable with any browser`_.  There is no hard-coded formatting information
 115 in the HTML document. Correct rendering of elements not directly supported
 116 by HTML depends on a CSS_ style sheet. The provided style sheets
 117 minimal.css_ and plain.css_ define required and optional styling rules
 118 respectively. Adaption of the layout is possible with `custom style
 119 sheets`_.
 120
 121 New in Docutils 0.13
 122
 123 .. TODO
 124
 125    Find the right name for this writer. Suggestions:
 126
 127    html-common
 128      ±0 common definitions for XHTML and HTML5
 129    html-plain
 130      ±0 simple, plain, unadorned.
 131    html-simple
 132      ±0 simple
 133    html-vanilla
 134      -0 too long, too colloquial
 135    html-basic
 136      -1 does not produce `XHTML Basic`_
 137    html-lcd
 138      `Lowest Common Denominator` -- supporting HTML 5, XHTML 1,
 139      and older (HTML 4 + CSS2) browsers.
 140
 141      -1 cryptic
 142    html-base
 143      -1 not only base class but also suited for end-users
 144
 145 .. _rst2html5.py: tools.html#rst2html5-py
 146 .. _[html-plain writer]: config.html#html-plain-writer
 147 .. _minimal.css: ../../docutils/writers/html_plain/minimal.css
 148 .. _plain.css: ../../docutils/writers/html_plain/plain.css
 149 .. _custom style sheets: ../howto/html-stylesheets.html
 150 .. _viewable with any browser: http://www.anybrowser.org/campaign
 151
 152 Aliases
 153 ~~~~~~~
 154
 155 html
 156 """"
 157
 158 Currently, `html` is an alias for the html4css1_ writer.
 159
 160 Suggestion
 161   The alias `html` points to the "recommended Docutils HTML writer".
 162   Its target may change with the development of HTML, browsers, Docutils, and
 163   the web.
 164
 165   * Use `get_writer_by_name('html') or the ``rst2html.py`` front end, if you
 166     want the output to be up-to-date automatically.
 167
 168   * Use a specific writer name or front end, if you depend on stability of
 169     the generated HTML code, e.g. because you use a custom style sheet or
 170     post-processing that may break otherwise.
 171
 172 html4
 173 """""
 174
 175 The alias `html4` provides a stable shortcut for the html4css1_ writer.
 176
 177 New in Docutils 0.13
 178
 179 html5
 180 """""
 181
 182 In Docutils 0.13, html5 is an alias to the html_plain_ writer.
 183
 184 In future releases, `html5` may become a separate HTML writer that makes use
 185 of new features and objects defined in HTML5 but not (yet) fit for use in
 186 `html_plain`_ because of limited browser support (like <video>, <aside>, or
 187 <section>).
 188
 189 Special HTML writers
 190 --------------------
 191
 192 pep_html
 193 ~~~~~~~~
 194
 195 :front-end: rstpep2html.py_
 196 :config:    `[pep_html writer]`_
 197
 198 This is a special writer for the generation of `Python Enhancement
 199 Proposals`_ (PEPs). It inherits from html4css1_ and adds some `PEP-specific
 200 options`_, a style sheet and template. The front-end uses also a specialised
 201 reader.
 202
 203 .. _rstpep2html.py: tools.html#rstpep2html-py
 204 .. _PEP-specific options:
 205 .. _[pep_html writer]: config.html#pep-html-writer
 206 .. _Python Enhancement Proposals: https://www.python.org/dev/peps/
 207
 208 s5_html
 209 ~~~~~~~
 210
 211 :alias:     s5
 212 :front-end: rst2s5.py_
 213 :config:    `[s5_html writer]`_
 214
 215 The `s5` writer inherits from html4css1_. It produces XHTML for use with
 216 S5_, the “Simple Standards-based Slide Show System” by Eric Meyer.  See
 217 `Easy Slide Shows With reST & S5`_ for details.
 218
 219 .. _rst2s5.py: tools.html#rst2s5-py
 220 .. _[s5_html writer]: config.html#s5-html-writer
 221 .. _Easy Slide Shows With reST & S5: slide-shows.html
 222 .. _S5: http://meyerweb.com/eric/tools/s5/
 223 .. _theme: tools.html#themes
 224
 225
 226 HTML writers in the sandbox
 227 ---------------------------
 228
 229 There are two more HTML writers in the sandbox_:
 230
 231 xhtml11
 232 ~~~~~~~
 233 :aliases:   xhtml, html4strict
 234 :front-end: rst2xhtml.py
 235 :config:    `[xhtml11 writer]`
 236
 237 `XHTML 1.1`_ is the current version of the XML based `extensible Hypertext
 238 Markup Language`.
 239
 240 The `xhtml11` writer inherits from html_plain_ and adds compatibility to the
 241 strict requirements of `XHTML 1.1`_:
 242
 243 * There is no attribute "lang" (only "xml:lang").
 244
 245 * Enumerated lists don't support the 'start' attribute.
 246
 247   The style sheet xhtml11.css_ adds support for a "start" value for
 248   enumerated lists via a CSS-counter. This allows also nested enumeration.
 249
 250 * ``<sup>`` and ``<sub>`` tags are not allowed in preformatted blocks
 251   (``<pre>``).
 252
 253 The `math-output` `config setting`_ defaults to "MathML".
 254
 255 .. _sandbox: ../dev/policies.html#the-sandbox
 256 .. _rst2xhtml.py: tools.html#rst2html5-py
 257 .. _config setting:
 258 .. _[xhtml11 writer]: config.html#xhtml11-writer
 259 .. _xhtml11.css: ../../docutils/writers/xhtml11/xhtml11.css
 260
 261
 262 html4trans
 263 ~~~~~~~~~~
 264
 265 :front-end: rst2html_trans.py_
 266
 267 The `HTML writer for lightweight browsers`_ lives in the Docutils sandbox
 268 (`sandbox/html4trans`_) since 2008. It removes the dependency on CSS. The
 269 output conforms to `XHTML 1 Transitional`_ and contains sufficient
 270 formatting information for rendering without style sheet. (Of course, this
 271 has some drawbacks_.)
 272
 273 .. _HTML writer for lightweight browsers:
 274    ../../../sandbox/html4trans/README.html
 275 .. _drawbacks: ../../../sandbox/html4trans/README.html#drawbacks
 276 .. _sandbox/html4trans: ../../../sandbox/html4trans
 277 .. _rst2html_trans.py: ../../../sandbox/html4trans/tools/rst2html_trans.py
 278
 279
 280 HTML and CSS Versions
 281 ---------------------
 282
 283 _`HTML 5`
 284    `HTML5, A vocabulary and associated APIs for HTML and XHTML`,
 285    W3C Recommendation, 28 October 2014.
 286    http://www.w3.org/TR/html5/
 287
 288 _`XHTML 1.1`
 289    `XHTML™ 1.1 - Module-based XHTML - Second Edition`,
 290    W3C Recommendation, 23 November 2010.
 291    http://www.w3.org/TR/xhtml11/
 292
 293 _`XHTML 1 Transitional`
 294    `Transitional version`_ of:
 295    `XHTML™ 1.0 The Extensible HyperText Markup Language (Second
 296    Edition)`, `A Reformulation of HTML 4 in XML 1.0`,
 297    W3C Recommendation, 26 January 2000, revised 1 August 2002.
 298    http://www.w3.org/TR/xhtml1/
 299
 300 _`XHTML Basic`
 301    `XHTML™ Basic 1.1 - Second Edition`,
 302    W3C Recommendation, 23 November 2010.
 303    http://www.w3.org/TR/xhtml-basic/
 304
 305 .. _transitional version:
 306    http://www.w3.org/TR/xhtml1/#a_dtd_XHTML-1.0-Transitional
 307
 308 _`HTML 4.01 Transitional`
 309   Transitional version of:
 310   `HTML 4.01 Specification`, W3C Recommendation 24 December 1999.
 311   http://www.w3.org/TR/html4/
 312
 313 .. _`CSS 1`:
 314
 315 _`CSS Level 1`:
 316   The features defined in the CSS1 specification, but using the syntax
 317   and definitions in the `CSS 2.1`_ specification.
 318
 319 _`CSS 2.1` `Cascading Style Sheets Level 2 Revision 1 (CSS 2.1) Specification`,
 320   W3C Recommendation 07 June 2011.
 321   http://www.w3.org/TR/CSS21/
 322
 323 _`CSS 3`:
 324   CSS Level 3 builds on CSS Level 2 module by module, using the CSS2.1
 325   specification as its core.
 326
 327   Specifications: http://www.w3.org/Style/CSS/specs.en.html
 328
 329   Validator: http://jigsaw.w3.org/css-validator/
 330
 331 .. other references
 332    ----------------
 333
 334 .. _HTML Compatibility Guidelines: http://www.w3.org/TR/xhtml1/#guidelines
 335 .. _polyglot HTML: http://www.w3.org/TR/html-polyglot/
 336 .. _CSS: http://www.w3.org/TR/CSS/