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   html5_polyglot_ html5_     rst2html5.py   `HTML5`_          `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 .. _rst2html.py: tools.html#rst2html-py
  86 .. _[html4css1 writer]: config.html#html4css1-writer
  87 .. _html4css1.css: ../../docutils/writers/html4css1/html4css1.css
  88
  89
  90 html5_polyglot
  91 ~~~~~~~~~~~~~~
  92
  93 :aliases: html5_
  94 :front-end: rst2html5.py_
  95 :config: `[html-polyglot writer]`_
  96
  97 The ``html5_polyglot`` writer generates `polyglot HTML`_ output, valid XML that
  98 is compatible with `HTML5`_.
  99 New features and elements will only be used if they are widely supported to
 100 make documents `viewable with any browser`_.
 101
 102 There is no hard-coded formatting information in the HTML document. Correct
 103 rendering of elements not directly supported by HTML depends on a CSS_ style
 104 sheet. The provided style sheets minimal.css_ and plain.css_ define required
 105 and optional styling rules respectively. Adaption of the layout is possible
 106 with `custom style sheets`_.
 107
 108 New in Docutils 0.13
 109
 110 .. _rst2html5.py: tools.html#rst2html5-py
 111 .. _[html-plain writer]: config.html#html-plain-writer
 112 .. _minimal.css: ../../docutils/writers/html5_polyglot/minimal.css
 113 .. _plain.css: ../../docutils/writers/html5_polyglot/plain.css
 114 .. _custom style sheets: ../howto/html-stylesheets.html
 115 .. _viewable with any browser: http://www.anybrowser.org/campaign
 116
 117
 118 html
 119 ~~~~
 120
 121 `html` is an alias for the recommended Docutils HTML writer.
 122 Currently, `html` is mapped to html4css1_.
 123
 124 The target may change with the development of HTML, browsers, Docutils, and
 125 the web.
 126
 127 * Use `get_writer_by_name('html') or the ``rst2html.py`` front end, if you
 128   want the output to be up-to-date automatically.
 129
 130 * Use a specific writer name or front end, if you depend on stability of the
 131   generated HTML code, e.g. because you use a custom style sheet or
 132   post-processing that may break otherwise.
 133
 134
 135
 136 Special HTML writers
 137 --------------------
 138
 139 pep_html
 140 ~~~~~~~~
 141
 142 :front-end: rstpep2html.py_
 143 :config:    `[pep_html writer]`_
 144
 145 This is a special writer for the generation of `Python Enhancement
 146 Proposals`_ (PEPs). It inherits from html4css1_ and adds some `PEP-specific
 147 options`_, a style sheet and template. The front-end uses also a specialised
 148 reader.
 149
 150 .. _rstpep2html.py: tools.html#rstpep2html-py
 151 .. _PEP-specific options:
 152 .. _[pep_html writer]: config.html#pep-html-writer
 153 .. _Python Enhancement Proposals: https://www.python.org/dev/peps/
 154
 155 s5_html
 156 ~~~~~~~
 157
 158 :alias:     s5
 159 :front-end: rst2s5.py_
 160 :config:    `[s5_html writer]`_
 161
 162 The `s5` writer inherits from html4css1_. It produces XHTML for use with
 163 S5_, the “Simple Standards-based Slide Show System” by Eric Meyer.  See
 164 `Easy Slide Shows With reST & S5`_ for details.
 165
 166 .. _rst2s5.py: tools.html#rst2s5-py
 167 .. _[s5_html writer]: config.html#s5-html-writer
 168 .. _Easy Slide Shows With reST & S5: slide-shows.html
 169 .. _S5: http://meyerweb.com/eric/tools/s5/
 170 .. _theme: tools.html#themes
 171
 172
 173 HTML writers in the sandbox
 174 ---------------------------
 175
 176 There are two more HTML writers in the sandbox_:
 177
 178 .. _sandbox: ../dev/policies.html#the-sandbox
 179
 180 xhtml11
 181 ~~~~~~~
 182 :aliases:   xhtml, html4strict
 183 :front-end: rst2xhtml.py
 184 :config:    `[xhtml11 writer]`
 185
 186 `XHTML 1.1`_ is the latest version of the XML based `extensible
 187 Hypertext Markup Language` with an official DTD.
 188
 189 The `xhtml11 writer`_ lives in the Docutils sandbox_ since 2008. The output
 190 conforms to the strict requirements of `XHTML 1.1`_.
 191
 192 .. _xhtml11 writer: ../../../sandbox/html4strict/README.html
 193
 194
 195 html4trans
 196 ~~~~~~~~~~
 197
 198 :front-end: rst2html_trans.py_
 199
 200 The `HTML writer for lightweight browsers`_ lives in the Docutils sandbox
 201 (`sandbox/html4trans`_) since 2008. It removes the dependency on CSS. The
 202 output conforms to `XHTML 1 Transitional`_ and contains sufficient
 203 formatting information for rendering without style sheet. (Of course, this
 204 has some drawbacks_.)
 205
 206 .. _HTML writer for lightweight browsers:
 207    ../../../sandbox/html4trans/README.html
 208 .. _drawbacks: ../../../sandbox/html4trans/README.html#drawbacks
 209 .. _sandbox/html4trans: ../../../sandbox/html4trans
 210 .. _rst2html_trans.py: ../../../sandbox/html4trans/tools/rst2html_trans.py
 211
 212
 213 HTML and CSS Versions
 214 ---------------------
 215
 216 _`HTML5`
 217    `HTML5, A vocabulary and associated APIs for HTML and XHTML`,
 218    W3C Recommendation, 28 October 2014.
 219    http://www.w3.org/TR/html5/
 220
 221 _`XHTML 1.1`
 222    `XHTML™ 1.1 - Module-based XHTML - Second Edition`,
 223    W3C Recommendation, 23 November 2010.
 224    http://www.w3.org/TR/xhtml11/
 225
 226 _`XHTML 1 Transitional`
 227    `Transitional version`_ of:
 228    `XHTML™ 1.0 The Extensible HyperText Markup Language (Second
 229    Edition)`, `A Reformulation of HTML 4 in XML 1.0`,
 230    W3C Recommendation, 26 January 2000, revised 1 August 2002.
 231    http://www.w3.org/TR/xhtml1/
 232
 233 _`XHTML Basic`
 234    `XHTML™ Basic 1.1 - Second Edition`,
 235    W3C Recommendation, 23 November 2010.
 236    http://www.w3.org/TR/xhtml-basic/
 237
 238 .. _transitional version:
 239    http://www.w3.org/TR/xhtml1/#a_dtd_XHTML-1.0-Transitional
 240
 241 _`HTML 4.01 Transitional`
 242   Transitional version of:
 243   `HTML 4.01 Specification`, W3C Recommendation 24 December 1999.
 244   http://www.w3.org/TR/html4/
 245
 246 .. _`CSS 1`:
 247
 248 _`CSS Level 1`:
 249   The features defined in the `CSS1 specification`_, but using the syntax
 250   and definitions in the `CSS 2.1`_ specification.
 251
 252 _`CSS 2.1` `Cascading Style Sheets Level 2 Revision 1 (CSS 2.1) Specification`,
 253   W3C Recommendation 07 June 2011.
 254   http://www.w3.org/TR/CSS21/
 255
 256 _`CSS 3`:
 257   CSS Level 3 builds on CSS Level 2 module by module, using the CSS2.1
 258   specification as its core.
 259
 260   Specifications: http://www.w3.org/Style/CSS/specs.en.html
 261
 262   Validator: http://jigsaw.w3.org/css-validator/
 263
 264 .. other references
 265    ----------------
 266
 267 .. _HTML Compatibility Guidelines: http://www.w3.org/TR/xhtml1/#guidelines
 268 .. _CSS: http://www.w3.org/TR/CSS/
 269 .. _CSS1 specification: http://www.w3.org/TR/2008/REC-CSS1-20080411/
 270 .. _polyglot HTML: http://www.w3.org/TR/html-polyglot/
 271
 272    .. Beware. This specification is no longer in active maintenance and the
 273       HTML Working Group does not intend to maintain it further.
 274
 275 .. Appendix
 276
 277
 278       On the question of Polyglot markup, there seems to be little
 279       consensus. One line of argument suggests that, to the extent that it
 280       is practical to obey the Robustness principle, it makes sense to do
 281       so. That is, if you're generating HTML markup for the web, and you can
 282       generate Polyglot markup that is also directly consumable as XML, you
 283       should do so. Another line of argument suggests that even under the
 284       most optimistic of projections, so tiny a fraction of the web will
 285       ever be written in Polyglot that there's no practical benefit to
 286       pursuing it as a general strategy for consuming documents from the
 287       web. If you want to consume HTML content, use an HTML parser that
 288       produces an XML-compatible DOM or event stream.
 289
 290       -- https://www.w3.org/TR/html-xml-tf-report/#conclusions
 291
 292   Further development
 293
 294   On 2016-05-25, David Goodger wrote:
 295
 296   > In addition, I'd actually like to see the HTML writer(s) with
 297   > fully-parameterized classes, i.e. removing hard-coded *classes* as well as
 298   > formatting. This way, any user who wants to (e.g.) write reST for use with
 299   > Bootstrap can easily work around any naming conflicts.
 300
 301
 302
 303   Problems with html4css1 writer:
 304
 305   1. Limiting ourself to CSS Level 1 requires use of hard-coded HTML
 306      formatting to get all rST objects mapped to HTML.
 307      Hard-coded HTML formatting is considered bad practice.
 308
 309   2. Maths cannot be included in MathML format without rendering a
 310      hmtl4css1-generated document invalid.
 311
 312      (XHTML 1.1. is the only member of the "HTML4 family" allowing embedding
 313      of MathML. However, hard-coded HTML formatting prevents its use.)
 314
 315
 316
 317   Comparison of current HTML versions
 318   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 319
 320   XHTML1.1
 321   """"""""
 322
 323   +2 XML-based with official DTD
 324      +1 allows processing with XML-tool-chain
 325      +1 allows validating against the DTD
 326
 327   +1 writer exists (in sandbox) and in active use since 2008
 328
 329   -1 "old" format
 330   -1 requires to work around restrictions lifted in HTML5
 331      ("start" argument for enumerated lists, some tags in parsed literal)
 332      which makes code and documents more complicated
 333
 334   HTML5
 335   """""
 336   +1 more recent
 337   +1 simpler to write, less restrictions
 338
 339   +1 writer exists and in active use since 2015
 340
 341   +1 new page structure elements such as <main>, <section>, <article>,
 342      <header>, <footer>, <aside>, <nav> and <figure>
 343      provide a better matches for the rst document model.
 344
 345   -1 new elements not yet supported by many browsers.
 346
 347   -2 no DTD, not SGML-based
 348      - no proper validation possible (there is an experimental validator)
 349      - no standard interface to post-processing XML-tools
 350
 351   -1 two concurring definitions:
 352      W3C standard and WHATWG "HTML Living Standard".