HTML writers: Outsourcing of common code to _html_base.py.

git-svn-id: https://svn.code.sf.net/p/docutils/code/trunk/docutils@7977 929543f6-e4f2-0310-98a6-ba3bd3dd1d04

1 files changed, 69 insertions, 97 deletions

diff --git a/docs/user/html.txt b/docs/user/html.txt
index a4a84621e..b2e1af0f4 100644
--- a/docs/user/html.txt
+++ b/docs/user/html.txt
@@ -2,60 +2,27 @@
 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`_
-
-  html5_polyglot_ html5      rst2html5.py   `HTML5`_          `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`_
+html
+----
 
-  =========== ============== ============== ================= ===========
-  name        alias(es)      `front-end`_   HTML version      CSS version
-  =========== ============== ============== ================= ===========
-  xhtml11_    xhtml,         rst2xhtml.py   `XHTML 1.1`_      `CSS 3`_
-              html4strict
+`html` is an alias for the default Docutils HTML writer.
+Currently, `html` is mapped to html4css1_.
 
-  html4trans_ ..             rst2html_trans `XHTML 1          no CSS
-                                            Transitional`_    required
-  =========== ============== ============== ================= ===========
+The 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.
 
-.. _front-end: tools.html
+* 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.
 
-Generic HTML writers
---------------------
 
 html4css1
-~~~~~~~~~
+---------
 
 :aliases:    html4, html_
 :front-ends: rst2html4.py, rst2html.py_
@@ -86,56 +53,6 @@ formatting hints and are tagged as "text/html" (instead of
 .. _[html4css1 writer]: config.html#html4css1-writer
 .. _html4css1.css: ../../docutils/writers/html4css1/html4css1.css
 
-
-html5_polyglot
-~~~~~~~~~~~~~~
-
-:aliases: html5
-:front-end: rst2html5.py_
-:config: `[html5 writer]`_
-
-The ``html5_polyglot`` writer generates `polyglot HTML`_ output, valid XML that
-is compatible with `HTML5`_.
-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
-
-.. _rst2html5.py: tools.html#rst2html5-py
-.. _[html5 writer]: config.html#html5-writer
-.. _minimal.css: ../../docutils/writers/html5_polyglot/minimal.css
-.. _plain.css: ../../docutils/writers/html5_polyglot/plain.css
-.. _custom style sheets: ../howto/html-stylesheets.html
-.. _viewable with any browser: http://www.anybrowser.org/campaign
-
-
-html
-~~~~
-
-`html` is an alias for the recommended Docutils HTML writer.
-Currently, `html` is mapped to html4css1_.
-
-The 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.
-
-
-
-Special HTML writers
---------------------
-
 pep_html
 ~~~~~~~~
 
@@ -170,6 +87,34 @@ S5_, the “Simple Standards-based Slide Show System” by Eric Meyer.  See
 .. _theme: tools.html#themes
 
 
+html5_polyglot
+--------------
+
+:aliases: html5
+:front-end: rst2html5.py_
+:config: `[html5 writer]`_
+
+The ``html5_polyglot`` writer generates `polyglot HTML`_ output, valid XML that
+is compatible with `HTML5`_.
+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
+
+.. _rst2html5.py: tools.html#rst2html5-py
+.. _[html5 writer]: config.html#html5-writer
+.. _minimal.css: ../../docutils/writers/html5_polyglot/minimal.css
+.. _plain.css: ../../docutils/writers/html5_polyglot/plain.css
+.. _custom style sheets: ../howto/html-stylesheets.html
+.. _viewable with any browser: http://www.anybrowser.org/campaign
+
+
 HTML writers in the sandbox
 ---------------------------
 
@@ -210,8 +155,33 @@ has some drawbacks_.)
 .. _rst2html_trans.py: ../../../sandbox/html4trans/tools/rst2html_trans.py
 
 
-HTML and CSS Versions
----------------------
+Overview
+--------
+
+=============== =========== ============== ================= ===========
+name            alias(es)   `front-end`_   HTML version      CSS version
+=============== =========== ============== ================= ===========
+html4css1_      html4,      rst2html4.py   `XHTML 1          `CSS 1`_
+                html_                      Transitional`_
+
+pep_html_       ..          rstpep2html.py `XHTML 1          `CSS 1`_
+                                           Transitional`_
+
+s5_html_        s5          rst2s5.py      `XHTML 1          `CSS 1`_
+                                           Transitional`_
+
+html5_polyglot_ html5       rst2html5.py   `HTML5`_          `CSS 3`_
+
+xhtml11_        xhtml,      rst2xhtml.py   `XHTML 1.1`_      `CSS 3`_
+                html4strict
+
+html4trans_ ..              rst2html_trans `XHTML 1          no CSS
+                                           Transitional`_    required
+=============== =========== ============== ================= ===========
+
+
+References
+----------
 
 _`HTML5`
    `HTML5, A vocabulary and associated APIs for HTML and XHTML`,
@@ -350,3 +320,5 @@ _`CSS 3`:
 
   -1 two concurring definitions:
      W3C standard and WHATWG "HTML Living Standard".
+
+.. _front-end: tools.html