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 Overview
   9 --------
  10
  11 Since version 0.13, Docutils comes with a family of HTML writers to support
  12 several `HTML variants`_.
  13
  14 ============  ===========  =================   =============================
  15 alias         alias        name                output format(s)
  16 ============  ===========  =================   =============================
  17 *html* [#]_   xhtml1 or    html4css1_          `XHTML 1 Transitional`_
  18               html4 [#]_
  19 ..                         pep_html_           `XHTML 1 Transitional`_
  20
  21 *s5*                       s5_html_            `XHTML 1 Transitional`_
  22
  23 ..                         html4trans_ [#]_    `XHTML 1 Transitional`_
  24
  25 *html5*       html-base    html_base_          | HTML5_
  26                                                | `XHTML 1 Transitional`_
  27
  28 *xhtml*       html4strict  xhtml11_            | `XHTML 1.1`_
  29                                                | HTML5_
  30 ============  ===========  =================   =============================
  31
  32 For *emphazised* aliases exist ``rst2<alias>.py`` `front-end tools`_.
  33
  34 .. [#] *html* will become an alias for html-base in a future release.
  35
  36 .. [#] TODO: how to name the alias/frontend specific to the html4css1 writer
  37    replacing "html":
  38
  39    :html4:
  40
  41      +1  short form of html4css1,
  42      -1  writer produces XHTML 1, not HTML 4
  43
  44    :xhtml1:
  45
  46      +1  correct and short description of the output format.
  47      -1  may be confused with xhtml11 or xhtml (aliases for the
  48          "new" XHTML 1.1. writer inheriting from html-base).
  49
  50 .. [#] in the sandbox
  51
  52 .. _front-end tools: tools.html
  53
  54
  55 html4css1
  56 ~~~~~~~~~
  57
  58 :aliases:    html4, html
  59 :front-ends: rst2html.py_, rst2html4.py
  60 :config:     `[html4css1 writer]`_
  61
  62 The HTML Writer module, ``docutils/writers/html4css1.py``, started
  63 as a proof-of-concept reference implementation. It is the first Docutils
  64 writer and was up to release 0.13 the only official HTML writer.
  65
  66 The output conforms to the `XHTML 1 Transitional`_ specification.
  67 Correct rendering depends on a CSS_ style sheet. A reference style sheet,
  68 `html4css1.css`_, is provided with Docutils.
  69
  70 Due to the closing of empty tags required in XML but not allowed in HTML 4,
  71 generated documents do not validate as `HTML 4.01 Transitional`_.
  72 However, they follow the `HTML Compatibility Guidelines`_ for proper
  73 rendering on most HTML user agents.
  74
  75 To support the `Internet Explorer` (IE) (with a market share of about 90%
  76 at the time this writer was written), documents are tagged as "text/html"
  77 (instead of "application/xhtml+xml") and contain some hard-coded formatting
  78 hints. [#IE]_
  79
  80 .. [#IE] Conformance to CSS 2.1 has been added in the IE 8 (2009), support
  81    for XHTML in IE 9 (2011).
  82
  83 .. _rst2html.py: tools.html#rst2html-py
  84 .. _[html4css1 writer]: config.html#html4css1-writer
  85 .. _html4css1.css: ../../docutils/writers/html4css1/html4css1.css
  86
  87 --------------------------------------------------------------------------
  88
  89 The following three HTML writers inherit from `html4css1`:
  90
  91 pep_html
  92 """"""""
  93
  94 :front-end: rstpep2html.py_
  95 :config:    `[pep_html writer]`_
  96
  97 This is a special writer for the generation of `Python Enhancement
  98 Proposals`_ (PEPs). It adds some PEP-Specific
  99 Options, a style sheet and template. The front-end uses also a specialized
 100 Reader.
 101
 102 .. _rstpep2html.py: tools.html#rstpep2html-py
 103 .. _[pep_html writer]: config.html#pep-html-writer
 104 .. _Python Enhancement Proposals: https://www.python.org/dev/peps/
 105
 106 s5_html
 107 """""""
 108
 109 :alias:     s5
 110 :front-end: rst2s5.py_
 111 :config:    `[s5_html writer]`_
 112
 113 The `s5` writer produces XHTML output compatible with S5_, the “Simple
 114 Standards-based Slide Show System” by Eric Meyer.  This allows one to create
 115 `Easy Slide Shows With reST & S5`_. A theme_ is required for proper
 116 rendering
 117
 118 .. _rst2s5.py: tools.html#rst2s5-py
 119 .. _[s5_html writer]: config.html#s5-html-writer
 120 .. _Easy Slide Shows With reST & S5: slide-shows.html
 121 .. _S5: http://meyerweb.com/eric/tools/s5/
 122 .. _theme: tools.html#themes
 123
 124
 125 html4trans
 126 """"""""""
 127
 128 :front-end: rst2html_trans.py_
 129
 130 The `html4trans` writer (`sandbox/html4trans`_) removes the dependency on
 131 CSS browser support. The output conforms to `XHTML 1 Transitional`_ and
 132 contains enough formatting information to be viewed without a cascading
 133 style sheet by a lightweight html browser.
 134
 135 .. _sandbox/html4trans: ../../../sandbox/html4trans
 136 .. _rst2html_trans.py: ../../../sandbox/html4trans/tools/rst2html_trans.py
 137
 138
 139 html_base
 140 ~~~~~~~~~
 141
 142 :aliases:   html-base, html5
 143 :front-end: rst2html5.py_
 144 :config:    `[html-base writer]`_
 145
 146 The `html-base` writer produces `polyglot HTML`_ output (compatible with
 147 HTML5_ and `XHTML 1 Transitional`_). A CSS style sheet is required for
 148 proper rendering; a complete style sheet, html-base.css_, is provided by
 149 Docutils and used by default.
 150
 151 .. _rst2html5.py: tools.html#rst2html5-py
 152 .. _[html-base writer]: config.html#html-base-writer
 153 .. _html-base.css: ../../docutils/writers/html_base/html-base.css
 154
 155
 156 xhtml11
 157 ~~~~~~~
 158 :aliases:   xhtml, html4strict
 159 :front-end: rst2xhtml.py_
 160 :config:    `[xhtml11 writer]`_
 161
 162 The `xhtml11` writer inherits from html_base_ and adds compatibility to
 163 `XHTML 1.1`_ (see `its source`__ for details)
 164
 165 An additional style sheet adds support for a "start" value for enumerated
 166 lists via a CSS-counter.
 167
 168 __ ../../docutils/writers/xhtml11/__init__.py
 169 .. _rst2xhtml.py: tools.html#rst2html5-py
 170 .. _[xhtml11 writer]: config.html#xhtml11-writer
 171
 172
 173
 174 HTML variants
 175 -------------
 176
 177 _`HTML5`
 178    `HTML5, A vocabulary and associated APIs for HTML and XHTML`,
 179    W3C Recommendation, 28 October 2014.
 180    http://www.w3.org/TR/html5/
 181
 182 _`XHTML 1.1`
 183    `XHTML™ 1.1 - Module-based XHTML - Second Edition`,
 184    W3C Recommendation, 23 November 2010.
 185    http://www.w3.org/TR/xhtml11/
 186
 187 _`XHTML 1 Transitional`
 188    `Transitional version`_ of:
 189    `XHTML™ 1.0 The Extensible HyperText Markup Language (Second
 190    Edition)`, `A Reformulation of HTML 4 in XML 1.0`,
 191    W3C Recommendation, 26 January 2000, revised 1 August 2002.
 192    http://www.w3.org/TR/xhtml1/
 193
 194 .. _transitional version:
 195    http://www.w3.org/TR/xhtml1/#a_dtd_XHTML-1.0-Transitional
 196
 197 _`HTML 4.01 Transitional`
 198   Transitional version of:
 199   `HTML 4.01 Specification`, W3C Recommendation 24 December 1999.
 200   http://www.w3.org/TR/html4/
 201
 202 .. _HTML Compatibility Guidelines: http://www.w3.org/TR/xhtml1/#guidelines
 203 .. _polyglot HTML: http://www.w3.org/TR/html-polyglot/
 204 .. _CSS: http://www.w3.org/TR/CSS/