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 Since version 0.13, Docutils comes with a family of HTML writers to support
   9
  10 * state of the art HTML (html_base_, html5),
  11
  12 * state of the art XHTML (xhtml11_), and
  13
  14 * older user agents with no/limited support for CSS and XHTML (html4css1_
  15   and descendants).
  16
  17
  18 Overview
  19 --------
  20
  21 ==========  ===========  =================   =============================
  22 alias       alias        name                output format(s)
  23 ==========  ===========  =================   =============================
  24 *html5*     html-base    html_base_          | HTML5_
  25 [#]_                                         | `XHTML 1 Transitional`_
  26
  27 *xhtml*     html4strict  xhtml11_            | `XHTML 1.1`_
  28                                              | HTML5_
  29
  30 *html*      *xhtml1* or  html4css1_          `XHTML 1 Transitional`_
  31 [#]_        *html4*
  32             [#]_
  33 ..                       pep_html_           `XHTML 1 Transitional`_
  34
  35 *s5*                     s5_html_            `XHTML 1 Transitional`_
  36
  37 ..                       html4trans_ [#]_    `XHTML 1 Transitional`_
  38 ==========  ===========  =================   =============================
  39
  40 For *emphazised* aliases exist ``rst2<alias>.py`` `front-end tools`_.
  41
  42 .. [#] `html5` may become the name of an advanced HTML5 writer derived from
  43    html-base in a future release.
  44
  45 .. [#] `html` may become an alias for html-base in a future release.
  46
  47 .. [#] TODO: how to name the alias/frontend pointing to html4css1?
  48
  49    :html4:
  50
  51      +1  short form of html4css1,
  52      -1  writer produces XHTML 1, not HTML 4
  53
  54    :xhtml1:
  55
  56      +1  correct and short description of the output format.
  57      -1  may be confused with xhtml11 or xhtml (aliases for the
  58          "new" XHTML 1.1. writer inheriting from html-base).
  59
  60 .. [#] in the sandbox
  61
  62 .. _front-end tools: tools.html
  63
  64
  65 html
  66 ~~~~
  67
  68 The writer name `html` is an alias pointing to the "recommended Docutils
  69 HTML writer". Its meaning may change with the development of HTML, browsers
  70 and the web.
  71
  72 * Use `get_writer_by_name('html') or the ``rst2html.py`` front end, if you
  73   want the output to be up-to-date automatically.
  74
  75 * Use a more specific writer name or front end, if you depend on stability
  76   of the generated HTML code, e.g. because you use a custom style sheet or
  77   postprocessing that may break otherwise.
  78
  79
  80 html_base
  81 ~~~~~~~~~
  82
  83 .. note:: The name `html_base` will change to a more appropriate one.
  84    Candidates are
  85
  86    * `html_basic` (but beware of confusion with the `XHTML
  87      Basic`_ document type),
  88    * `html-generic`, `html-conservative`, or
  89    * `html_common` (the greatest common denominator of (X)HTML variants
  90       currently in use).
  91
  92
  93 :aliases:   html-base, html5
  94 :front-end: rst2html5.py_
  95 :config: `[html-base writer]`_
  96
  97 The `html-base` writer is both, basis for more specialized HTML writers and
  98 working code generating clean and highly compatible documents.
  99
 100 It generates modern `polyglot HTML`_ output (compatible with HTML5_
 101 and `XHTML 1 Transitional`_). Correct rendering depends on a CSS_ style
 102 sheet. An example style sheet, html-base.css_, is provided and used by
 103 default.
 104
 105 New features and elements will only be used if they are widely supported to
 106 make documents `viewable with any browser`_. Leaving out hard-coded
 107 formatting information from the HTML code allows adaption of the layout with
 108 `custom style sheets`_.
 109
 110 .. _rst2html5.py: tools.html#rst2html5-py
 111 .. _[html-base writer]: config.html#html-base-writer
 112 .. _html-base.css: ../../docutils/writers/html_base/html-base.css
 113 .. _custom style sheets: ../howto/html-stylesheets.html
 114 .. _viewable with any browser: http://www.anybrowser.org/campaign
 115
 116
 117 xhtml11
 118 """""""
 119 :aliases:   xhtml, html4strict
 120 :front-end: rst2xhtml.py_
 121 :config:    `[xhtml11 writer]`_
 122
 123 `XHTML 1.1`_ is the current version of the XML based `extensible Hypertext
 124 Markup Language`.
 125
 126 The `xhtml11` writer inherits from html_base_ and adds compatibility to the
 127 strict requirements of `XHTML 1.1`_:
 128
 129 * There is no attribute "lang" (only "xml:lang").
 130
 131 * Enumerated lists don't support the 'start' attribute.
 132
 133   The style sheet xhtml11.css_ adds support for a "start" value for
 134   enumerated lists via a CSS-counter.
 135
 136 * ``<sup>`` and ``<sub>`` tags are not allowed in preformatted blocks
 137   (``<pre>``) but possible in reStructuredText with the "parsed-literal"
 138   directive.
 139
 140 The `math-output` `config setting`_ defaults to "MathML".
 141
 142 .. _rst2xhtml.py: tools.html#rst2html5-py
 143 .. _config setting:
 144 .. _[xhtml11 writer]: config.html#xhtml11-writer
 145 .. _xhtml11.css: ../../docutils/writers/xhtml11/xhtml11.css
 146
 147
 148 html5
 149 """""
 150
 151 The writer name `html5` is reserved for a HTML writer that makes use of new
 152 features and objects defined in HTML5 but not (yet) fit for use in
 153 `html-base` because of limited browser support (like <video>, <aside>, or
 154 <section>).
 155
 156
 157 html4css1
 158 ~~~~~~~~~
 159
 160 :aliases:    html4, html
 161 :front-ends: rst2html.py_, rst2html4.py
 162 :config:     `[html4css1 writer]`_
 163
 164 The HTML Writer module, ``docutils/writers/html4css1.py``, started
 165 as a proof-of-concept reference implementation. It is the first Docutils
 166 writer and was up to release 0.13 the only official HTML writer.
 167
 168 The output conforms to the `XHTML 1 Transitional`_ specification.
 169 Correct rendering depends on a CSS_ style sheet. A reference style sheet,
 170 `html4css1.css`_, is provided and used by default.
 171
 172 Due to the closing of empty tags required in XML but not allowed in HTML 4,
 173 generated documents do not validate as `HTML 4.01 Transitional`_.
 174 However, they follow the `HTML Compatibility Guidelines`_ for proper
 175 rendering on most HTML user agents.
 176
 177 To support the `Internet Explorer` [#IE]_ (with a market share of about 90%
 178 around 2002, the time this writer was written), documents are tagged as
 179 "text/html" (instead of "application/xhtml+xml") and contain some hard-coded
 180 formatting hints.
 181
 182 .. [#IE] Conformance to CSS 2.1 has been added in the IE 8 (2009), support
 183    for XHTML in IE 9 (2011).
 184
 185 .. _rst2html.py: tools.html#rst2html-py
 186 .. _[html4css1 writer]: config.html#html4css1-writer
 187 .. _html4css1.css: ../../docutils/writers/html4css1/html4css1.css
 188
 189 --------------------------------------------------------------------------
 190
 191 The following three HTML writers inherit from `html4css1`:
 192
 193 pep_html
 194 """"""""
 195
 196 :front-end: rstpep2html.py_
 197 :config:    `[pep_html writer]`_
 198
 199 This is a special writer for the generation of `Python Enhancement
 200 Proposals`_ (PEPs). It adds some PEP-Specific
 201 Options, a style sheet and template. The front-end uses also a specialized
 202 reader.
 203
 204 .. _rstpep2html.py: tools.html#rstpep2html-py
 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 is used to prepare `Easy Slide Shows With reST & S5`_. It
 216 produces XHTML for use with S5_, the “Simple Standards-based Slide Show
 217 System” by Eric Meyer.
 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 html4trans
 227 """"""""""
 228
 229 :front-end: rst2html_trans.py_
 230
 231 Correct rendering of HTML+CSS requires considerable resources in form of
 232 program code, memory space and computation time. On older machines or in
 233 embedded devices this might pose a serious problem.
 234
 235 The `HTML writer for lightweight browsers`_ lives in the Docutils sandbox
 236 (`sandbox/html4trans`_) since 2008. It removes the dependency on CSS. The
 237 output conforms to `XHTML 1 Transitional`_ and contains sufficient
 238 formatting information for rendering without style sheet. (Of course, this
 239 has some drawbacks_.)
 240
 241 .. _HTML writer for lightweight browsers:
 242    ../../../sandbox/html4trans/README.html
 243 .. _drawbacks: ../../../sandbox/html4trans/README.html#drawbacks
 244 .. _sandbox/html4trans: ../../../sandbox/html4trans
 245 .. _rst2html_trans.py: ../../../sandbox/html4trans/tools/rst2html_trans.py
 246
 247
 248 HTML variants
 249 -------------
 250
 251 _`HTML5`
 252    `HTML5, A vocabulary and associated APIs for HTML and XHTML`,
 253    W3C Recommendation, 28 October 2014.
 254    http://www.w3.org/TR/html5/
 255
 256 _`XHTML 1.1`
 257    `XHTML™ 1.1 - Module-based XHTML - Second Edition`,
 258    W3C Recommendation, 23 November 2010.
 259    http://www.w3.org/TR/xhtml11/
 260
 261 _`XHTML 1 Transitional`
 262    `Transitional version`_ of:
 263    `XHTML™ 1.0 The Extensible HyperText Markup Language (Second
 264    Edition)`, `A Reformulation of HTML 4 in XML 1.0`,
 265    W3C Recommendation, 26 January 2000, revised 1 August 2002.
 266    http://www.w3.org/TR/xhtml1/
 267
 268 _`XHTML Basic`
 269    `XHTML™ Basic 1.1 - Second Edition`,
 270    W3C Recommendation, 23 November 2010.
 271    http://www.w3.org/TR/xhtml-basic/
 272
 273 .. _transitional version:
 274    http://www.w3.org/TR/xhtml1/#a_dtd_XHTML-1.0-Transitional
 275
 276 _`HTML 4.01 Transitional`
 277   Transitional version of:
 278   `HTML 4.01 Specification`, W3C Recommendation 24 December 1999.
 279   http://www.w3.org/TR/html4/
 280
 281 .. _HTML Compatibility Guidelines: http://www.w3.org/TR/xhtml1/#guidelines
 282 .. _polyglot HTML: http://www.w3.org/TR/html-polyglot/
 283 .. _CSS: http://www.w3.org/TR/CSS/