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