=====================
Docutils HTML writers
=====================
.. note:: This document is a working draft. Naming of writers, aliases, and
front-ends may change before the release of Docutils 0.13.
Since version 0.13, Docutils comes with a family of HTML writers to support
* state of the art HTML (html_base_, html5),
* state of the art XHTML (xhtml11_), and
* older user agents with no/limited support for CSS and XHTML (html4css1_
and descendants).
Overview
--------
========== =========== ================= =============================
alias alias name output format(s)
========== =========== ================= =============================
*html5* html-base html_base_ | HTML5_
[#]_ | `XHTML 1 Transitional`_
*xhtml* html4strict xhtml11_ | `XHTML 1.1`_
| HTML5_
*html* *xhtml1* or html4css1_ `XHTML 1 Transitional`_
[#]_ *html4*
[#]_
.. pep_html_ `XHTML 1 Transitional`_
*s5* s5_html_ `XHTML 1 Transitional`_
.. html4trans_ [#]_ `XHTML 1 Transitional`_
========== =========== ================= =============================
For *emphazised* aliases exist ``rst2.py`` `front-end tools`_.
.. [#] `html5` may become the name of an advanced HTML5 writer derived from
html-base in a future release.
.. [#] `html` may become an alias for html-base in a future release.
.. [#] TODO: how to name the alias/frontend pointing to html4css1?
:html4:
+1 short form of html4css1,
-1 writer produces XHTML 1, not HTML 4
:xhtml1:
+1 correct and short description of the output format.
-1 may be confused with xhtml11 or xhtml (aliases for the
"new" XHTML 1.1. writer inheriting from html-base).
.. [#] in the sandbox
.. _front-end tools: tools.html
html
~~~~
The writer name `html` is an alias pointing to the "recommended Docutils
HTML writer". Its meaning may change with the development of HTML, browsers
and the web.
* Use `get_writer_by_name('html') or the ``rst2html.py`` front end, if you
want the output to be up-to-date automatically.
* Use a more specific writer name or front end, if you depend on stability
of the generated HTML code, e.g. because you use a custom style sheet or
postprocessing that may break otherwise.
html_base
~~~~~~~~~
.. note:: The name `html_base` will change to a more appropriate one.
Candidates are
* `html_basic` (but beware of confusion with the `XHTML
Basic`_ document type),
* `html-generic`, `html-conservative`, or
* `html_common` (the greatest common denominator of (X)HTML variants
currently in use).
:aliases: html-base, html5
:front-end: rst2html5.py_
:config: `[html-base writer]`_
The `html-base` writer is both, basis for more specialized HTML writers and
working code generating clean and highly compatible documents.
It generates modern `polyglot HTML`_ output (compatible with HTML5_
and `XHTML 1 Transitional`_). Correct rendering depends on a CSS_ style
sheet. An example style sheet, html-base.css_, is provided and used by
default.
New features and elements will only be used if they are widely supported to
make documents `viewable with any browser`_. Leaving out hard-coded
formatting information from the HTML code allows adaption of the layout with
`custom style sheets`_.
.. _rst2html5.py: tools.html#rst2html5-py
.. _[html-base writer]: config.html#html-base-writer
.. _html-base.css: ../../docutils/writers/html_base/html-base.css
.. _custom style sheets: ../howto/html-stylesheets.html
.. _viewable with any browser: http://www.anybrowser.org/campaign
xhtml11
"""""""
:aliases: xhtml, html4strict
:front-end: rst2xhtml.py_
:config: `[xhtml11 writer]`_
`XHTML 1.1`_ is the current version of the XML based `extensible Hypertext
Markup Language`.
The `xhtml11` writer inherits from html_base_ and adds compatibility to the
strict requirements of `XHTML 1.1`_:
* There is no attribute "lang" (only "xml:lang").
* Enumerated lists don't support the 'start' attribute.
The style sheet xhtml11.css_ adds support for a "start" value for
enumerated lists via a CSS-counter.
* ```` and ```` tags are not allowed in preformatted blocks
(``
``) but possible in reStructuredText with the "parsed-literal"
directive.
The `math-output` `config setting`_ defaults to "MathML".
.. _rst2xhtml.py: tools.html#rst2html5-py
.. _config setting:
.. _[xhtml11 writer]: config.html#xhtml11-writer
.. _xhtml11.css: ../../docutils/writers/xhtml11/xhtml11.css
html5
"""""
The writer name `html5` is reserved for a HTML writer that makes use of new
features and objects defined in HTML5 but not (yet) fit for use in
`html-base` because of limited browser support (like