From c32067e8fc140d141dad46841697be8a99d224ac Mon Sep 17 00:00:00 2001
From: milde <milde@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Sun, 12 Apr 2015 10:06:43 +0000
Subject: [PATCH] Small HTML fixes and documentation updates.

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk@7865 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docutils/docs/user/html.txt                       | 26 ++++++++++++++++++-----
 docutils/docutils/utils/math/__init__.py          |  5 +++--
 docutils/docutils/utils/math/latex2mathml.py      | 11 ++++++++++
 docutils/docutils/writers/html_base/html-base.css |  5 +++--
 docutils/docutils/writers/xhtml11/__init__.py     |  5 +----
 docutils/docutils/writers/xhtml11/xhtml11.css     |  4 ++--
 6 files changed, 41 insertions(+), 15 deletions(-)

diff --git a/docutils/docs/user/html.txt b/docutils/docs/user/html.txt
index c83de8c94..ac4ed90a7 100644
--- a/docutils/docs/user/html.txt
+++ b/docutils/docs/user/html.txt
@@ -63,13 +63,28 @@ For *emphazised* aliases exist ``rst2<alias>.py`` `front-end tools`_.
 .. _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_common`, or simply `html` (name
-   currently used as alias by `html4css1`_). Suggestions welcome.
+   `XHTML Basic`_ document type) or `html_common`
+   Suggestions welcome.
 
 
 :aliases:   html-base, html5
@@ -130,9 +145,10 @@ The `math-output` `config setting`_ defaults to "MathML".
 html5
 """""
 
-The writer name `html5` is reserved for a HTML writer that makes use of the
-new features and objects defined in HTML5 (like <video>, <aside>, or
-<section>) that are not (yet) fit for use in `html-base`.
+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>).
 
 
 html4css1
diff --git a/docutils/docutils/utils/math/__init__.py b/docutils/docutils/utils/math/__init__.py
index 4c38a1e86..d9d19570b 100644
--- a/docutils/docutils/utils/math/__init__.py
+++ b/docutils/docutils/utils/math/__init__.py
@@ -17,8 +17,9 @@ It contains various modules for conversion between different math formats
 
 :math2html:    LaTeX math -> HTML conversion from eLyXer
 :latex2mathml: LaTeX math -> presentational MathML
-:unichar2tex: Unicode character to LaTeX math translation table
-:tex2unichar: LaTeX math to Unicode character translation dictionaries
+:unichar2tex:  Unicode character to LaTeX math translation table
+:tex2unichar:  LaTeX math to Unicode character translation dictionaries
+:tex2mathml_extern: Wrapper for TeX -> MathML command line converters
 """
 
 # helpers for Docutils math support
diff --git a/docutils/docutils/utils/math/latex2mathml.py b/docutils/docutils/utils/math/latex2mathml.py
index 4c2980574..c0f233178 100644
--- a/docutils/docutils/utils/math/latex2mathml.py
+++ b/docutils/docutils/utils/math/latex2mathml.py
@@ -558,3 +558,14 @@ def handle_keyword(name, node, string):
         raise SyntaxError(u'Unknown LaTeX command: ' + name)
 
     return node, skip
+
+def tex2mathml(tex_math, inline=True):
+    """Return string with MathML code corresponding to `tex_math`. 
+    
+    `inline`=True is for inline math and `inline`=False for displayed math.
+    """
+    
+    mathml_tree = parse_latex_math(tex_math, inline=inline)
+    return ''.join(mathml_tree.xml())
+
+    
diff --git a/docutils/docutils/writers/html_base/html-base.css b/docutils/docutils/writers/html_base/html-base.css
index ee5e2e4a3..65e128451 100644
--- a/docutils/docutils/writers/html_base/html-base.css
+++ b/docutils/docutils/writers/html_base/html-base.css
@@ -147,7 +147,8 @@ dl > dd p:first-child { margin-top: 0; }
 /* dl > dd p:last-child  { margin-bottom: 0; } */
 
 /* lists nested in definition lists */
-dd > ul, dd > ol { padding-left: 0pt; }
+/* :only-child is not part of CSS 2.1 (introduced in CSS 3) */
+dd > ul:only-child, dd > ol:only-child { padding-left: 1em; }
 
 dt span.classifier { font-style: italic }
 dt span.classifier:before {
@@ -458,7 +459,7 @@ p.rubric {
 
 /* can be styled in a custom stylesheet */
 
-/* Document Header & Footer */
+/* Document Header and Footer */
 
 div.footer, div.header {
   clear: both;
diff --git a/docutils/docutils/writers/xhtml11/__init__.py b/docutils/docutils/writers/xhtml11/__init__.py
index f57d2ba34..fe105fee2 100644
--- a/docutils/docutils/writers/xhtml11/__init__.py
+++ b/docutils/docutils/writers/xhtml11/__init__.py
@@ -16,10 +16,7 @@
 Strict eXtensible HyperText Markup Language (XHTML) document Writer.
 
 This is a variant of Docutils' `html-base` writer.
-
-* The output conforms to the XHTML version 1.1 DTD.
-* It contains no hard-coded formatting information that would prevent
-  configuration by cascading style sheets.
+The output conforms to the XHTML version 1.1 DTD.
 """
 
 __docformat__ = 'reStructuredText'
diff --git a/docutils/docutils/writers/xhtml11/xhtml11.css b/docutils/docutils/writers/xhtml11/xhtml11.css
index 88677b160..8daabdd91 100644
--- a/docutils/docutils/writers/xhtml11/xhtml11.css
+++ b/docutils/docutils/writers/xhtml11/xhtml11.css
@@ -92,8 +92,8 @@ ol.nested > li:before, ol.nested  ol > li:before {
   content: counters(item, ".") " ";
 }
 
-/* <sup> and <sub> tags (possible with parsed-literal) are not allowed */
-/* in <pre> --- use <span>					       */
+/* "sup" and "sub" tags (possible with parsed-literal) are not allowed */
+/* in "pre" --- use "span"					       */
 
 .subscript {
   vertical-align: sub;
-- 
2.11.4.GIT