Move motivation to math directive decisions to "alternatives".

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

2 files changed, 90 insertions, 62 deletions

diff --git a/docutils/docs/dev/rst/alternatives.txt b/docutils/docs/dev/rst/alternatives.txt
index 726b536fb..2f580411e 100644
--- a/docutils/docs/dev/rst/alternatives.txt
+++ b/docutils/docs/dev/rst/alternatives.txt
@@ -1847,6 +1847,86 @@ was implemented by recognising the second group in the example above and
 transforming it into ``\cite{cite1,cite2}``.)
 
 
+Math Markup
+===========
+
+Using a standard, such as MathML_\ [#]_ seems a good start. However,
+
+    MathML in its full XML form was never thought to be usable as an
+    input format: for a start it is far too verbose as necessitated by
+    its intention to be expressive.
+
+    -- http://www.w3.org/Math/Roadmap/
+
+Like for non-mathematical content, a different input format is needed.
+
+.. [#] For an overview of MathML implementations and tests, see e.g.
+   the `mathweb wiki`_ or the `ConTeXT MathML page`_.
+
+.. _MathML: http://www.w3.org/TR/MathML2/
+.. _mathweb wiki: http://www.mathweb.org/wiki/MathML
+.. _ConTeXT MathML page: http://wiki.contextgarden.net/MathML
+
+Input formats
+-------------
+
+LaTeX math syntax
+  * Intended for input by a human, widely used, and well documented.
+
+  * Can be used for both, input and internal storage.
+
+  * Convertible to all supported output formats (building on
+    existing extensions like `latex_math`_ (LaTeX2MathML) or the math
+    support in Sphinx
+
+  * Used by the `Math support in Sphinx`_.
+
+  * Unicode input similar to the "unicode-math" package for
+    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
+    ``\grave`` macro is used instead of ``\```.
+
+  .. _latex_math: ../../../sandbox/jensj/latex_math/
+  .. _Math support in Sphinx: http://sphinx.pocoo.org/ext/math.html
+
+
+ASCIIMath_
+  Simple, ASCII based math input language (see also `ASCIIMath tutorial`_).
+
+  * The Python module ASCIIMathML_ translates a string with ASCIIMath into a
+    MathML tree. Used, e.g., by MultiMarkdown__.
+
+  * For conversion to TeX, there is JavaScript script at
+    http://dlippman.imathas.com/asciimathtex/ASCIIMath2TeX.js
+
+  .. _ASCIIMath: http://www1.chapman.edu/~jipsen/mathml/asciimath.html
+  .. _ASCIIMath tutorial:
+     http://www.wjagray.co.uk/maths/ASCIIMathTutorial.html
+  .. _ASCIIMathML: http://pypi.python.org/pypi/asciimathml/
+  __ http://fletcherpenney.net/multimarkdown/
+
+`Unicode Nearly Plain Text Encoding of Mathematics`_
+   format for lightly marked-up representation of mathematical
+   expressions in Unicode.
+
+   (Unicode Technical Note. Sole responsibility for its contents rests
+   with the author(s). Publication does not imply any endorsement by
+   the Unicode Consortium.)
+
+   .. _Unicode Nearly Plain Text Encoding of Mathematics:
+      http://www.unicode.org/notes/tn28/
+
+itex
+  See `the culmination of a relevant discussion in 2003
+  <http://article.gmane.org/gmane.text.docutils.user/118>`__.
+
+
+Since Docutils 0.8, a "math" role and directive using LaTeX math
+syntax as input format is part of reStructuredText.
+
+
 -----------------
  Not Implemented
 -----------------
diff --git a/docutils/docs/dev/todo.txt b/docutils/docs/dev/todo.txt
index a2f520bc7..c2d7bc0c8 100644
--- a/docutils/docs/dev/todo.txt
+++ b/docutils/docs/dev/todo.txt
@@ -1153,6 +1153,8 @@ The following sub-section is intended to replace the 5 inline markup rules in
 the reStructuredText Markup Specification's section on `inline markup`_.
 The composition of the character classes is open for discussion_.
 
+The actual change needs to be done in `parsers.rst.states.Inliner`.
+
 Inline markup syntax rules
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -1320,67 +1322,12 @@ Do this in the setup script and use the resulting string literal?
 Math Markup
 -----------
 
-Using a standard, such as MathML_\ [#]_ seems a good start. However,
-
-    MathML in its full XML form was never thought to be usable as an
-    input format: for a start it is far too verbose as necessitated by
-    its intention to be expressive.
-
-    -- http://www.w3.org/Math/Roadmap/
-
-Like for non-mathematical content, a different input format is needed.
-
-.. [#] For an overview of MathML implementations and tests, see e.g.
-   the `mathweb wiki`_ or the `ConTeXT MathML page`_.
-
-.. _MathML: http://www.w3.org/TR/MathML2/
-.. _mathweb wiki: http://www.mathweb.org/wiki/MathML
-.. _ConTeXT MathML page: http://wiki.contextgarden.net/MathML
-
-
-Input formats
-`````````````
-
-LaTeX math syntax
-  * Intended for input by a human, widely used, and well documented.
-
-  * Can be used for both, input and internal storage.
-
-  * Convertible to all supported output formats (building on
-    existing extensions like `latex_math`_ (LaTeX2MathML) or the `math
-    support in Sphinx`_ (see below for `HTML output`_).
-
-  * Used by the `Math support in Sphinx`_.
-
-  * Unicode input similar to the "unicode-math" package for
-    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
-    ``\grave`` macro is used instead of ``\```.
-
-ASCIIMathML_
-  Used, e.g., by MultiMarkdown__
-
-  .. _ASCIIMathML: http://www1.chapman.edu/~jipsen/mathml/asciimath.html
-  __ http://fletcherpenney.net/multimarkdown/
-
-
-`Unicode Nearly Plain Text Encoding of Mathematics`_
-   format for lightly marked-up representation of mathematical
-   expressions in Unicode.
-
-   (Unicode Technical Note. Sole responsibility for its contents rests
-   with the author(s). Publication does not imply any endorsement by
-   the Unicode Consortium.)
-
-   .. _Unicode Nearly Plain Text Encoding of Mathematics:
-      http://www.unicode.org/notes/tn28/
+Since Docutils 0.8, a "math" role and directive using LaTeX math
+syntax as input format is part of reStructuredText.
 
-LaTeX math syntax was used as input format for the "math" role and directive.
-See also `the culmination of a relevant discussion
-<http://article.gmane.org/gmane.text.docutils.user/118>`__.
+Provide for `alternative input formats`__?
 
+__ ./rst/alternatives.html#math-markup
 
 Try to be compatible with `Math support in Sphinx`_?
 
@@ -1417,9 +1364,9 @@ Which equation environments should be supported by the math directive?
 
   + Sphinx math also supports `gather` (checking for blank lines in
     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.)
+    lines in separate math-block doctree nodes. (The only difference of
+    `gather` to two consecutive "normal" environments seems to be that
+    page-breaks between the two are prevented.)
 
 See http://www.math.uiuc.edu/~hildebr/tex/displays.html.
 
@@ -1453,6 +1400,7 @@ MathML_
 
   __ http://msevior.livejournal.com/26377.html
   __ http://hutchinson.belmont.ma.us/tth/mml/ttmmozform.html
+  .. _MathML: http://www.w3.org/TR/MathML2/
   .. _latex_math: ../../../sandbox/jensj/latex_math/
   .. _latex2mathml: ../../docutils/math/latex2mathml.py
   .. _Blahtex: http://gva.noekeon.org/blahtexml/