Rename html_base writer to html_plain, move xhtml11 writer back to sandbox.

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

4 files changed, 246 insertions, 186 deletions

diff --git a/docutils/docs/dev/todo.txt b/docutils/docs/dev/todo.txt
index bb904c7f1..552098e3a 100644
--- a/docutils/docs/dev/todo.txt
+++ b/docutils/docs/dev/todo.txt
@@ -376,6 +376,44 @@ General
   Especially useful for character entity sets, text transform specs,
   boilerplate, etc.
 
+* Support "include" as embedded inline-compatible directive in substitution
+  definitions, e.g. ::
+
+    .. |version| include:: version.txt
+
+    This document describes version |version| of ...
+
+  (cf. Grzegorz Adam Hankiewicz's post from 2014-10-01 in docutils-devel)
+
+* Add an ``:optional: <replacement text>`` option to the "include"
+  directive? This would not throw an error for a missing file, instead a
+  warning is given and ``<replacement text>`` is used instead. It would be
+  the responsibility of the author to ensure the missing file does not lead
+  to problems later in the document.
+
+  Use cases:
+
+  + Standard rST syntax to replace Sphinx's "literalinclude"::
+
+      .. include:: blah.cpp
+         :literal:
+         :optional: file ``blah.cpp`` not found
+
+  + Variable content taken from a file, e.g.
+
+    version.txt::
+
+       .. |version| replace:: 3.1
+
+    optionally used as::
+
+       .. include:: version.txt
+          :optional: .. |version| replace:: unknown
+
+       This document describes version |version| of ...
+
+    (cf. Grzegorz Adam Hankiewicz's post from 2014-10-01 in docutils-devel)
+
 * Parameterize the Reporter object or class?  See the `2004-02-18
   "rest checking and source path"`_ thread.
 
@@ -1725,6 +1763,20 @@ when used in a document.
     either by running it at the command line with a ``--help`` option
     or through an exposed API.  [Suggestion for Optik.]
 
+  - _`body.float`: Generic float that can be used for figures, tables,
+    code listings, flowcharts, ...
+
+    There is a Sphinx extension by Ignacio Fernández Galván <jellby@gmail.com>
+
+       I implemented something for generic floats in sphinx, and submitted a
+       pull request that is still waiting::
+
+        .. float::
+           :type: figure
+           :caption: My caption
+
+      https://github.com/sphinx-doc/sphinx/pull/1858
+
 
 Interpreted Text
 ----------------
@@ -2506,9 +2558,9 @@ Image and figure directives
   + `<../../test/functional/expected/standalone_rst_html4css1.html>`__
   + `<../../test/functional/expected/standalone_rst_latex.tex>`__
 
-* According to the HTML standard
-  http://www.w3.org/TR/html4/struct/objects.html#adef-align-IMG a right- or
-  left-aligned image should be floated alongside the paragraph.
+* The default CSS styling for HTML output (plain.css, default.css) lets
+  text following a right- or left-aligned image float to the side of the
+  image/figure.
 
   + Use this default also for LaTeX?
 
diff --git a/docutils/docs/user/html.txt b/docutils/docs/user/html.txt
index c93889293..3f12f2659 100644
--- a/docutils/docs/user/html.txt
+++ b/docutils/docs/user/html.txt
@@ -5,98 +5,122 @@ 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.
 
-   The ⚠ symbol marks suggestions that are still open to
-   discussion and change.
+.. contents::
 
 Overview
 --------
 
-Docutils supports
+* `Generic HTML writers`_
 
-* state of the art HTML (html_base_, html5) ⚠
+  =========== ============== ============== ================= ===========
+  name        alias(es)      `front-end`_   HTML version      CSS version
+  =========== ============== ============== ================= ===========
+  html4css1_  html4          rst2html4.py   `XHTML 1          `CSS 1`_
+                                            Transitional`_
 
-* state of the art XHTML (xhtml11_) ⚠
+  ..          html_          rst2html.py    `XHTML 1          `CSS 1`_
+                                            Transitional`_
 
-* older user agents with no/limited support for CSS and XHTML (html4css1_
-  and descendants).
+  html_plain_ html5_         rst2html5.py   `HTML 5`_         `CSS 3`_
+  =========== ============== ============== ================= ===========
 
-Additionally, there are special purpose writers (pep_html_, s5_html_) in the
-Docutils core and others (e.g. html4trans_) in the sandbox.
+* `Special HTML writers`_
 
-=========== ============== ============== ================= ===========
-name        alias(es)      `front-end`_   HTML version(s)   CSS version
-=========== ============== ============== ================= ===========
-[#base]_                                  HTML5_, (`XHTML 1 `CSS 3`_
-                                          Transitional`_)
+  =========== ============== ============== ================= ===========
+  name        alias(es)      `front-end`_   HTML version      CSS version
+  =========== ============== ============== ================= ===========
+  pep_html_   ..             rstpep2html.py `XHTML 1          `CSS 1`_
+                                            Transitional`_
 
-[#5]_       html5 [#5]_    rst2html5.py   HTML5_,           `CSS 3`_
+  s5_html_    s5             rst2s5.py      `XHTML 1          `CSS 1`_
+                                            Transitional`_
+  =========== ============== ============== ================= ===========
 
-xhtml11_    xhtml,         rst2xhtml.py   `XHTML 1.1`_,     `CSS 3`_
-            html4strict                   (HTML5_)
+* `HTML writers in the sandbox`_
 
-html4css1_  html_ [#h]_,   rst2html.py    `XHTML 1          `CSS 1`_
-            html4                         Transitional`_
+  =========== ============== ============== ================= ===========
+  name        alias(es)      `front-end`_   HTML version      CSS version
+  =========== ============== ============== ================= ===========
+  xhtml11_    xhtml,         rst2xhtml.py   `XHTML 1.1`_      `CSS 3`_
+              html4strict
 
-pep_html_   ..             rstpep2html.py `XHTML 1          `CSS 1`_
-                                          Transitional`_
+  html4trans_ ..             rst2html_trans `XHTML 1          no CSS
+                                            Transitional`_    required
+  =========== ============== ============== ================= ===========
 
-s5_html_    s5             rst2s5.py      `XHTML 1          `CSS 1`_
-                                          Transitional`_
-=========== ============== ============== ================= ===========
 
-.. [#base] TODO: Find the right name for the basic html writer.
-.. [#5] `html5` may become the name for a specialised `html5 writer`_ in a
-   future release.
+.. _front-end: tools.html
 
-.. There is one more HTML writer in the sandbox:
+Generic HTML writers
+--------------------
 
-   html4trans_                rst2html_trans `XHTML 1          no CSS
-                              [#sandbox]_    Transitional`_    required
+html4css1
+~~~~~~~~~
 
-   .. [#sandbox] in the sandbox
+:aliases:    html4, html_
+:front-ends: rst2html4.py, rst2html.py_
+:config:     `[html4css1 writer]`_
 
-.. _front-end: tools.html
+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.
 
-html
-----
+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.
 
-Currently, `html` is an alias for the html4css1_ writer.
+Correct rendering depends on a CSS_ style sheet. A reference style sheet,
+`html4css1.css`_, is provided and used by default.
 
-.. admonition:: suggestion
+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]_
 
-  The writer alias `html` points to the "recommended Docutils HTML writer".
-  Its meaning may change with the development of HTML, browsers, Docutils, and
-  the web.
+.. [#IE] Conformance to `CSS 2.1`_ has been added in IE 8 (2009), support
+   for XHTML in IE 9 (2011).
 
-  * Use `get_writer_by_name('html') or the ``rst2html.py`` front end, if you
-    want the output to be up-to-date automatically.
+.. TODO: How to name a specific alias/front-end pointing to html4css1?
 
-  * 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
-    post-processing that may break otherwise.
+   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).
 
-html_base
------------
 
-:aliases: html-common, html5 [#5]_
-:front-end: rst2html5.py_
-:config: `[html-base writer]`_
+.. _rst2html.py: tools.html#rst2html-py
+.. _[html4css1 writer]: config.html#html4css1-writer
+.. _html4css1.css: ../../docutils/writers/html4css1/html4css1.css
+
 
-The `html_base` module is both, basis for other HTML writers and a
-versatile writer for end-users or programmatic use. ⚠
+html_plain
+~~~~~~~~~~
+
+:aliases: html5_
+:front-end: rst2html5.py_
+:config: `[html-plain writer]`_
 
-It generates `polyglot HTML`_ output (compatible with HTML5_ and `XHTML 1
-Transitional`_). New features and elements will only be used if they are
-widely supported to make documents `viewable with any browser`_.
+The `html_plain` module is both, basis for other HTML writers and a
+versatile writer for end-users or programmatic use.
 
-Correct rendering depends on a CSS_ style sheet. Leaving out hard-coded
-formatting information from the HTML code allows adaption of the layout with
-`custom style sheets`_. The provided style sheets minimal.css_ and
-plain.css_ define required and optional styling rules respectively.
+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
 
-.. admonition:: TODO
+.. TODO
 
    Find the right name for this writer. Suggestions:
 
@@ -118,108 +142,52 @@ New in Docutils 0.13
    html-base
      -1 not only base class but also suited for end-users
 
-
 .. _rst2html5.py: tools.html#rst2html5-py
-.. _[html-base writer]: config.html#html-base-writer
-.. _minimal.css: ../../docutils/writers/html_base/minimal.css
-.. _plain.css: ../../docutils/writers/html_base/plain.css
+.. _[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
 
-
-xhtml11
+Aliases
 ~~~~~~~
-: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`.
+html
+""""
 
-The `xhtml11` writer inherits from html_base_ and adds compatibility to the
-strict requirements of `XHTML 1.1`_:
+Currently, `html` is an alias for the html4css1_ writer.
 
-* There is no attribute "lang" (only "xml:lang").
+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.
 
-* Enumerated lists don't support the 'start' attribute.
+  * Use `get_writer_by_name('html') or the ``rst2html.py`` front end, if you
+    want the output to be up-to-date automatically.
 
-  The style sheet xhtml11.css_ adds support for a "start" value for
-  enumerated lists via a CSS-counter. This allows also nested enumeration.
+  * 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.
 
-* ``<sup>`` and ``<sub>`` tags are not allowed in preformatted blocks
-  (``<pre>``).
+html4
+"""""
 
-The `math-output` `config setting`_ defaults to "MathML".
+The alias `html4` provides a stable shortcut for the html4css1_ writer.
 
 New in Docutils 0.13
 
-.. _rst2xhtml.py: tools.html#rst2html5-py
-.. _config setting:
-.. _[xhtml11 writer]: config.html#xhtml11-writer
-.. _xhtml11.css: ../../docutils/writers/xhtml11/xhtml11.css
-
-
-.. _`html5 writer`:
-
 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 <video>, <aside>, or
-<section>).
-
-In Docutils 0.13, it is an alias to the html_base_ writer. ⚠
+"""""
 
+In Docutils 0.13, html5 is an alias to the html_plain_ writer.
 
-html4css1
----------
-
-:aliases:    html4 [#html4]_, html [#h]_
-:front-ends: rst2html.py_, rst2html4.py
-:config:     `[html4css1 writer]`_
-
-.. [#h] `html` may become an alias for html_base in a future release. ⚠
-
-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.
-Correct rendering depends on a CSS_ style sheet. A reference style sheet,
-`html4css1.css`_, is provided and used by default.
-
-Due to the closing of empty tags required in XML but not allowed in HTML 4,
-generated documents do not validate as `HTML 4.01 Transitional`_.
-However, they follow the `HTML Compatibility Guidelines`_ for proper
-rendering on most HTML user agents.
-
-To support the `Internet Explorer` [#IE]_ (with a market share of about 90%
-around 2002, the time this writer was written), documents are tagged as
-"text/html" (instead of "application/xhtml+xml") and contain some hard-coded
-formatting hints.
-
-.. [#IE] Conformance to `CSS 2.1`_ has been added in the IE 8 (2009), support
-   for XHTML in IE 9 (2011).
-
-.. [#html4] 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_base).
-
-
-.. _rst2html.py: tools.html#rst2html-py
-.. _[html4css1 writer]: config.html#html4css1-writer
-.. _html4css1.css: ../../docutils/writers/html4css1/html4css1.css
-
---------------------------------------------------------------------------
+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 <video>, <aside>, or
+<section>).
 
-The following three HTML writers inherit from `html4css1`:
+Special HTML writers
+--------------------
 
 pep_html
 ~~~~~~~~
@@ -228,11 +196,12 @@ pep_html
 :config:    `[pep_html writer]`_
 
 This is a special writer for the generation of `Python Enhancement
-Proposals`_ (PEPs). It adds some PEP-Specific
-Options, a style sheet and template. The front-end uses also a specialised
+Proposals`_ (PEPs). It inherits from html4css1_ and adds some `PEP-specific
+options`_, a style sheet and template. The front-end uses also a specialised
 reader.
 
 .. _rstpep2html.py: tools.html#rstpep2html-py
+.. _PEP-specific options:
 .. _[pep_html writer]: config.html#pep-html-writer
 .. _Python Enhancement Proposals: https://www.python.org/dev/peps/
 
@@ -243,9 +212,9 @@ s5_html
 :front-end: rst2s5.py_
 :config:    `[s5_html writer]`_
 
-The `s5` writer is used to prepare `Easy Slide Shows With reST & S5`_. It
-produces XHTML for use with S5_, the “Simple Standards-based Slide Show
-System” by Eric Meyer.
+The `s5` writer inherits from html4css1_. It produces XHTML for use with
+S5_, the “Simple Standards-based Slide Show System” by Eric Meyer.  See
+`Easy Slide Shows With reST & S5`_ for details.
 
 .. _rst2s5.py: tools.html#rst2s5-py
 .. _[s5_html writer]: config.html#s5-html-writer
@@ -254,15 +223,47 @@ System” by Eric Meyer.
 .. _theme: tools.html#themes
 
 
+HTML writers in the sandbox
+---------------------------
+
+There are two more HTML writers in the sandbox_:
+
+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_plain_ 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. This allows also nested enumeration.
+
+* ``<sup>`` and ``<sub>`` tags are not allowed in preformatted blocks
+  (``<pre>``).
+
+The `math-output` `config setting`_ defaults to "MathML".
+
+.. _sandbox: ../dev/policies.html#the-sandbox
+.. _rst2xhtml.py: tools.html#rst2html5-py
+.. _config setting:
+.. _[xhtml11 writer]: config.html#xhtml11-writer
+.. _xhtml11.css: ../../docutils/writers/xhtml11/xhtml11.css
+
+
 html4trans
 ~~~~~~~~~~
 
 :front-end: rst2html_trans.py_
 
-Correct rendering of HTML+CSS requires considerable resources in form of
-program code, memory space and computation time. On older machines or in
-embedded devices this might pose a serious problem.
-
 The `HTML writer for lightweight browsers`_ lives in the Docutils sandbox
 (`sandbox/html4trans`_) since 2008. It removes the dependency on CSS. The
 output conforms to `XHTML 1 Transitional`_ and contains sufficient
@@ -277,9 +278,9 @@ has some drawbacks_.)
 
 
 HTML and CSS Versions
----------------------
+~~~~~~~~~~~~~~~~~~~~~
 
-_`HTML5`
+_`HTML 5`
    `HTML5, A vocabulary and associated APIs for HTML and XHTML`,
    W3C Recommendation, 28 October 2014.
    http://www.w3.org/TR/html5/
diff --git a/docutils/docs/user/links.txt b/docutils/docs/user/links.txt
index e798fc2e9..d5ecf8f8e 100644
--- a/docutils/docs/user/links.txt
+++ b/docutils/docs/user/links.txt
@@ -146,24 +146,41 @@ website generators and HTML variants
 
   It can generate complete web sites (interlinked and indexed HTML pages),
   ePub, PDF, and others [#]_ from a set of rst source files.
-  
+
   .. [#] see http://sphinx-doc.org/config.html#options-for-epub-output
+  .. _Sphinx: http://sphinx.pocoo.org/
 
 * Nikola_  static site generator, use restructured text by
   default.
 
+  .. _nikola:  http://getnikola.com/
+
+* Pelican_ is a static site generator (mainly for blogs). Articles/pages can
+  be written in reStructuredText or Markdown format.
+
+  .. _pelican: http://docs.getpelican.com
+
 * rst2ht_ by Oliver Rutherfurd, converts reStructuredText to an .ht
   template, for use with ht2html_.
 
+  .. _rst2ht: http://www.rutherfurd.net/articles/rst-ht2html.html
+  .. _ht2html: http://ht2html.sourceforge.net/
+
 * htmlnav_ by Gunnar Schwant, is an HTML writer which supports navigation
   bars.
 
+  .. _htmlnav: http://docutils.sf.net/sandbox/gschwant/htmlnav/
+
 * rest2web_, by Michael Foord, is a tool for creating web sites with
   reStructuredText.
 
+  .. _rest2web: http://www.voidspace.org.uk/python/rest2web/
+
 * rst2chm_ by Oliver Rutherfurd, generates Microsoft HTML Help files from
   reStructuredText files.
 
+  .. _rst2chm: http://www.rutherfurd.net/software/rst2chm/
+
 * `html4strict <http://docutils.sf.net/sandbox/html4strict/>`__
   produces XHTML that strictly conforms to the XHTML 1.0 specification.
 
@@ -175,22 +192,15 @@ website generators and HTML variants
 * A `simple HTML writer`_ by Bill Bumgarner that doesn't rely on CSS
   (stylesheets).
 
-.. _Sphinx: http://sphinx.pocoo.org/
-.. _nikola:  http://getnikola.com/
-.. _rst2ht: http://www.rutherfurd.net/articles/rst-ht2html.html
-.. _ht2html: http://ht2html.sourceforge.net/
-.. _htmlnav: http://docutils.sf.net/sandbox/gschwant/htmlnav/
-.. _rst2chm: http://www.rutherfurd.net/software/rst2chm/
-.. _rest2web: http://www.voidspace.org.uk/python/rest2web/
-.. _simple HTML writer: http://docutils.sf.net/sandbox/bbum/DocArticle/
+  .. _simple HTML writer: http://docutils.sf.net/sandbox/bbum/DocArticle/
 
 ePub
 ````
- 
+
 * The `rst2epub`_ project by Robert Wierschke converts simple
-  reStructuredText doucments into valid epub files. 
-  
-  .. simple but well structured with classes/modules for epub components, 
+  reStructuredText doucments into valid epub files.
+
+  .. simple but well structured with classes/modules for epub components,
      and a standard ``setup.py`` installation file.
 
 * rst2epub2_ by Matt Harrison includes the epublib (originally by Tim
@@ -262,6 +272,11 @@ Convert other formats to reStructuredText:
 * xhtml2rest_, written by Antonios Christofides, is a simple utility
   to convert XHTML to reStructuredText.
 
+* DashTable_ by Gustav Klopp converts HTML tables into reStructuredText.
+  Colspan and Rowspan supported!
+
+  .. _DashTable: https://github.com/gustavklopp/DashTable
+
 * Sphinx_ includes a `LaTeX to Rst converter
   <http://svn.python.org/projects/doctools/converter/>`__ in its source code
   (trimmed to importing the old Python docs).
diff --git a/docutils/docs/user/tools.txt b/docutils/docs/user/tools.txt
index 597bfed4f..47cfc490e 100644
--- a/docutils/docs/user/tools.txt
+++ b/docutils/docs/user/tools.txt
@@ -101,7 +101,7 @@ rst2html.py
 
 :Reader: Standalone
 :Parser: reStructuredText
-:Writer: html (html4css1_; this will change to hmtl-base_ in future)
+:Writer: html_ (html4css1_)
 
 The ``rst2html.py`` front end reads standalone reStructuredText source
 files and produces `XHTML 1.0 Transitional`_ output.
@@ -129,7 +129,7 @@ Stylesheets
 option).  A stylesheet is required for proper rendering.  The default
 stylesheet (``docutils/writers/html4css1/html4css1.css``, located in
 the installation directory) is provided for basic use.  To use
-different stylesheet(s), you must specify the stylesheets' locations
+different stylesheet(s), specify the stylesheets' location(s)
 as comma-separated list with the "``--stylesheet``" (for a URL)
 or "``--stylesheet-path``" (for a local file) command-line option,
 or with `configuration file`_ settings (e.g. ``./docutils.conf``
@@ -138,32 +138,24 @@ or ``~/.docutils``).  To experiment with styles, please see the
 
 __ ../howto/html-stylesheets.html
 .. _html4css1: html.html#html4css1
+.. _html: html.html#html
 
-rst2xhtml.py
---------------
-
-:Reader: Standalone
-:Parser: reStructuredText
-:Writer: xhtml (xhtml11)
-
-The ``rst2xhtml11.py`` front end reads standalone reStructuredText
-source files and produces clean `XHTML 1.1`_
-output. A CSS 2 stylesheet is required for proper rendering; a complete
-stylesheet is installed and used by default.
 
 rst2html5.py
 ------------
 
 :Reader: Standalone
 :Parser: reStructuredText
-:Writer: html5 (html-base_)
+:Writer: html5 (html_plain_)
 
 The ``rst2html5.py`` front end reads standalone reStructuredText source
 files and produces simple `HTML 5`_ output (compatible to `XHTML 1.0
-Transitional`_). A CSS 2 stylesheet is required for proper rendering; a
-complete stylesheet is installed and used by default.
+Transitional`_).
+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.
 
-.. _html-base: html.html#html-base
+.. _html_plain: html.html#html-plain
 
 rstpep2html.py
 --------------