===================== 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. .. contents:: Overview -------- * `Generic HTML writers`_ =========== ============== ============== ================= =========== name alias(es) `front-end`_ HTML version CSS version =========== ============== ============== ================= =========== html4css1_ html4 rst2html4.py `XHTML 1 `CSS 1`_ Transitional`_ .. html_ rst2html.py `XHTML 1 `CSS 1`_ Transitional`_ html_plain_ html5_ rst2html5.py `HTML 5`_ `CSS 3`_ =========== ============== ============== ================= =========== * `Special HTML writers`_ =========== ============== ============== ================= =========== name alias(es) `front-end`_ HTML version CSS version =========== ============== ============== ================= =========== pep_html_ .. rstpep2html.py `XHTML 1 `CSS 1`_ Transitional`_ s5_html_ s5 rst2s5.py `XHTML 1 `CSS 1`_ Transitional`_ =========== ============== ============== ================= =========== * `HTML writers in the sandbox`_ =========== ============== ============== ================= =========== name alias(es) `front-end`_ HTML version CSS version =========== ============== ============== ================= =========== xhtml11_ xhtml, rst2xhtml.py `XHTML 1.1`_ `CSS 3`_ html4strict html4trans_ .. rst2html_trans `XHTML 1 no CSS Transitional`_ required =========== ============== ============== ================= =========== .. _front-end: tools.html Generic HTML writers -------------------- html4css1 ~~~~~~~~~ :aliases: html4, html_ :front-ends: rst2html4.py, rst2html.py_ :config: `[html4css1 writer]`_ The HTML Writer module, ``docutils/writers/html4css1.py``, started as a proof-of-concept reference implementation. It is the first Docutils writer and was up to release 0.13 the only official HTML writer. The output conforms to the `XHTML 1 Transitional`_ specification. It does not validate as `HTML 4.01 Transitional`_ due to the closing of empty tags required in XML but not allowed in HTML 4. However, the output follows the `HTML Compatibility Guidelines`_ for proper rendering on most HTML user agents. Correct rendering depends on a CSS_ style sheet. A reference style sheet, `html4css1.css`_, is provided and used by default. To support the `Internet Explorer` (with a market share of about 90% around 2002, the time this writer was written), documents contain some hard-coded formatting hints and are tagged as "text/html" (instead of "application/xhtml+xml"). [#IE]_ .. [#IE] Conformance to `CSS 2.1`_ has been added in IE 8 (2009), support for XHTML in IE 9 (2011). .. TODO: How to name a specific alias/front-end 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_plain). .. _rst2html.py: tools.html#rst2html-py .. _[html4css1 writer]: config.html#html4css1-writer .. _html4css1.css: ../../docutils/writers/html4css1/html4css1.css html_plain ~~~~~~~~~~ :aliases: html5_ :front-end: rst2html5.py_ :config: `[html-plain writer]`_ The `html_plain` module is both, basis for other HTML writers and a versatile writer for end-users or programmatic use. The ``html_plain`` writer generates `polyglot HTML`_ output that is compatible with `HTML 5`_ and `XHTML 1 Transitional`_. New features and elements will only be used if they are widely supported to make documents `viewable with any browser`_. There is no hard-coded formatting information in the HTML document. Correct rendering of elements not directly supported by HTML depends on a CSS_ style sheet. The provided style sheets minimal.css_ and plain.css_ define required and optional styling rules respectively. Adaption of the layout is possible with `custom style sheets`_. New in Docutils 0.13 .. TODO Find the right name for this writer. Suggestions: html-common ±0 common definitions for XHTML and HTML5 html-plain ±0 simple, plain, unadorned. html-simple ±0 simple html-vanilla -0 too long, too colloquial html-basic -1 does not produce `XHTML Basic`_ html-lcd `Lowest Common Denominator` -- supporting HTML 5, XHTML 1, and older (HTML 4 + CSS2) browsers. -1 cryptic html-base -1 not only base class but also suited for end-users .. _rst2html5.py: tools.html#rst2html5-py .. _[html-plain writer]: config.html#html-plain-writer .. _minimal.css: ../../docutils/writers/html_plain/minimal.css .. _plain.css: ../../docutils/writers/html_plain/plain.css .. _custom style sheets: ../howto/html-stylesheets.html .. _viewable with any browser: http://www.anybrowser.org/campaign Aliases ~~~~~~~ html """" Currently, `html` is an alias for the html4css1_ writer. Suggestion The alias `html` points to the "recommended Docutils HTML writer". Its target may change with the development of HTML, browsers, Docutils, 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 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 post-processing that may break otherwise. html4 """"" The alias `html4` provides a stable shortcut for the html4css1_ writer. New in Docutils 0.13 html5 """"" In Docutils 0.13, html5 is an alias to the html_plain_ writer. In future releases, `html5` may become a separate HTML writer that makes use of new features and objects defined in HTML5 but not (yet) fit for use in `html_plain`_ because of limited browser support (like