Math directive and documentation update:

Math content can also be given as directive argument.

Multiple content block separated by blank lines are put in separate
nodes.

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

5 files changed, 30 insertions, 27 deletions

diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt
index 417528479..2c636bc47 100644
--- a/docs/dev/todo.txt
+++ b/docs/dev/todo.txt
@@ -1154,10 +1154,9 @@ __ rst/alternatives.html#or-not-to-do
 Math Markup
 -----------
 
-We need a generic solution, that's applicable to any output format.
 Using a standard, such as MathML_, would be best. (For an overview of
 MathML implementations and tests, see e.g. the `mathweb wiki`_ or
-the `ConTeXT MathML page`_
+the `ConTeXT MathML page`_.)
 
 .. _MathML: http://www.w3.org/TR/MathML2/
 .. _mathweb wiki: http://www.mathweb.org/wiki/MathML
@@ -1187,7 +1186,7 @@ LaTeX math syntax
   * Used for input and storage by the `Math support in Sphinx`_.
 
   * Unicode input similar to the "unicode-math" package for
-    XeTeX/LuaTeX provides for a improved readability.
+    XeTeX/LuaTeX provides for improved readability of the source.
 
   * The backtick (GRAVE ACCENT, 0x60) cannot be used in a math role.
     Fortunately, it is not required in LaTeX math mode, as the
@@ -1217,12 +1216,6 @@ See `the culmination of a relevant discussion
 
 Try to be compatible with `Math support in Sphinx`_?
 
-* When the math is only one line of text, it can also be given as a
-  directive argument.
-
-* Supports multiple equations, which should be separated by a blank
-  line.
-
 * The ``:label:`` option selects a label for the equation, by which it
   can be cross-referenced, and causes an equation number to be issued.
 
@@ -1254,7 +1247,10 @@ Which equation environments should be supported by the math directive?
   + unnumbered: `align*`
 
   + Sphinx math also supports `gather` (checking for blank lines in
-    the content).
+    the content). Docutils puts content blocks separated by blank
+    lines in separate math-block doctree nodes. (The difference of
+    `gather` to two consecutive "normal" environments is that
+    line-breaks between the two are prevented.)
 
 See http://www.math.uiuc.edu/~hildebr/tex/displays.html.
 
@@ -1318,6 +1314,8 @@ HTML/CSS
   * Hevea_ (Objective Caml)
   * eLyXer_ (Python)
 
+  The ``math-output=html`` option uses the converter from eLyXer.
+
   __ http://www.cs.tut.fi/~jkorpela/math/
   __ http://www.zipcon.net/~swhite/docs/math/math.html
   .. _TtH: ttp://hutchinson.belmont.ma.us/tth/index.html
diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt
index d0b00ba67..e46f22628 100644
--- a/docs/ref/rst/directives.txt
+++ b/docs/ref/rst/directives.txt
@@ -491,20 +491,22 @@ Math
 
 :Directive Type: "math"
 :Doctree Element: math-block
-:Directive Arguments: None.
+:Directive Arguments: One, optional: prepended to content.
 :Directive Options: Possible.
-:Directive Content: Becomes the body of the math block (display formula).
+:Directive Content: Interpreted as math block(s). 
+                    Content blocks separated by a blank line are put in 
+                    separate math-block doctree elements.
 
-The "math" directive inserts a block with mathematical content
-(display formula) into the document. The input format is *LaTeX math
-syntax* (see, e.g. the `Short Math Guide`_) with support for Unicode
-symbols, for example::
+The "math" directive inserts block(s) with mathematical content
+(display formulas, equations) into the document. The input format is
+*LaTeX math syntax* (see, e.g. the `Short Math Guide`_) with support
+for Unicode symbols, for example::
 
   .. math::
 
     α_t(i) = P(O_1, O_2, … O_t, q_t = S_i λ)
 
-For inline formulae, use the `math role`_.
+For inline math, use the `math role`_.
 
 Support for math may be limited by the output format. If a writer does
 not support math typesetting, the content is inserted verbatim.
diff --git a/docs/user/config.txt b/docs/user/config.txt
index 425eabd7f..618d20dad 100644
--- a/docs/user/config.txt
+++ b/docs/user/config.txt
@@ -779,10 +779,6 @@ _`math_output`
     .. _MathPlayer: http://www.dessci.com/en/products/mathplayer/
     .. _MathML: http://www.mathweb.org/wiki/MathML
 
-    .. _Using LaTeX syntax for mathematics:
-        http://docutils.sf.net/sandbox/jensj/latex_math/docs/latex_math.txt
-
-
 _`option_limit`
     The maximum width (in characters) for options in option lists.
     Longer options will span an entire row of the table used to render
diff --git a/docs/user/links.txt b/docs/user/links.txt
index 3154a9102..a8085c8df 100644
--- a/docs/user/links.txt
+++ b/docs/user/links.txt
@@ -35,7 +35,7 @@ Editors with reStructuredText support and docutils GUIs:
   is a plugin for Vim7 with folding.
 
 * `VOoM <http://www.vim.org/scripts/script.php?script_id=2657>`__
-   is a plugin for Vim that emulates two-pane outliner. 
+   is a plugin for Vim that emulates two-pane outliner.
    Version 4.0b2 added support for reStructuredText.
 
 * `rst mode <http://jedmodes.sf.net/mode/rst/>`__ for the
@@ -97,6 +97,9 @@ HTML variants
   created to translate the Python_ documentation, and is now `used by
   <http://sphinx.pocoo.org/examples.html>`__ a wide choice of projects.
 
+  Generates web sites (interlinked and indexed HTML pages) and/or PDF
+  from a set of rst source files.
+
 * rst2ht_ by Oliver Rutherfurd, converts reStructuredText to an .ht
   template, for use with ht2html_.
 
@@ -152,7 +155,7 @@ Others
   Emacs text editor.  Texinfo can be used to produce multiple output
   formats, including HTML, PDF, and Info.
 
-  
+
 Import
 ------
 
@@ -187,7 +190,7 @@ Extend the reStructuredText syntax or the features of Docutils.
 More extensions are in the `Docutils Sandbox`_.
 
 * Jens J. Mortensen developed `LaTeX math for reST`_, which writes to
-  LaTeX or to MathML. It's included with Docutils > 0.7 (2010-11-05).
+  LaTeX or to MathML. It's included with Docutils since 0.8 (2010-11-05).
 
 * BENI Cherniavsky has written a generic `preprocessing module`_ for
   roles and/or directives and built preprocessors for TeX math for
@@ -216,8 +219,10 @@ Development
 ```````````
 
 * Sphinx_ extends the ReStructuredText syntax to better support the
-  documentation of Software projects (but other documents can be written
-  with it too). Since version 2.6, the `Python documentation`_ is based on 
+  documentation of Software (and other) *projects* (but other documents
+  can be written with it too).
+
+  Since version 2.6, the `Python documentation`_ is based on
   reStructuredText and Sphinx.
 
 * Trac_, a project management and bug/issue tracking system, supports
@@ -250,7 +255,7 @@ Presentations
   presentations using ReportLabs' PythonPoint_.
 
 * InkSlide_ quick and easy presentations using Inkscape_. InkSlide uses
-  reStructuredText for markup, although it renders only a subset of rst. 
+  reStructuredText for markup, although it renders only a subset of rst.
 
 .. _Docutils: http://docutils.sourceforge.net/
 .. _FAQ entry about Wikis: http://docutils.sf.net/FAQ.html#are-there-any-wikis-that-use-restructuredtext-syntax
diff --git a/docs/user/rst/cheatsheet.txt b/docs/user/rst/cheatsheet.txt
index 1ef0788d5..40910deac 100644
--- a/docs/user/rst/cheatsheet.txt
+++ b/docs/user/rst/cheatsheet.txt
@@ -96,6 +96,7 @@ contents          Generate a table of contents
 sectnum           Automatically number sections, subsections, etc.
 header, footer    Create document decorations [0.3.8]
 target-notes      Create an explicit footnote for each external target
+math              Mathematical notation (input in LaTeX format)
 meta              HTML-specific metadata
 include           Read an external reST file as if it were inline
 raw               Non-reST data passed untouched to the Writer
@@ -117,6 +118,7 @@ Role Name         Description
 ================  ============================================================
 emphasis          Equivalent to *emphasis*
 literal           Equivalent to ``literal`` but processes backslash escapes
+math              Mathematical notation (input in LaTeX format)
 PEP               Reference to a numbered Python Enhancement Proposal
 RFC               Reference to a numbered Internet Request For Comments
 raw               For non-reST data; cannot be used directly (see docs) [0.3.6]