Update TODO list

math input formats (todo),
move inline markup recognition alternatives to "alternatives".

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

2 files changed, 145 insertions, 112 deletions

diff --git a/docutils/docs/dev/rst/alternatives.txt b/docutils/docs/dev/rst/alternatives.txt
index 545698a05..b94958588 100644
--- a/docutils/docs/dev/rst/alternatives.txt
+++ b/docutils/docs/dev/rst/alternatives.txt
@@ -1847,84 +1847,46 @@ 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
+Inline markup recognition
+=========================
 
+Implemented 2011-12-05 (version 0.9):
+Extended `inline markup recognition rules`_.
 
-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__.
+Non-ASCII whitespace, punctuation characters and "international" quotes are
+allowed around inline markup (based on `Unicode categories`_). The rules for
+ASCII characters were not changed.
 
-  * For conversion to LaTeX, there is a JavaScript script at
-    http://dlippman.imathas.com/asciimathtex/ASCIIMath2TeX.js
+Rejected alternatives:
 
-  .. _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/
+a) Use `Unicode categories`_ for all chars (ASCII or not)
 
-`Unicode Nearly Plain Text Encoding of Mathematics`_
-   format for lightly marked-up representation of mathematical
-   expressions in Unicode.
+   +1  comprehensible, standards based,
+   -1  many "false positives" need escaping,
+   -1  not backwards compatible.
 
-   (Unicode Technical Note. Sole responsibility for its contents rests
-   with the author(s). Publication does not imply any endorsement by
-   the Unicode Consortium.)
+b) full backwards compatibility
 
-   .. _Unicode Nearly Plain Text Encoding of Mathematics:
-      http://www.unicode.org/notes/tn28/
+   :Pi: only before start-string
+   :Pf: only behind end-string
+   :Po: "conservative" sorting of other punctuation:
 
-itex
-  See `the culmination of a relevant discussion in 2003
-  <http://article.gmane.org/gmane.text.docutils.user/118>`__.
+        :``.,;!?\\``: Close
+        :``¡¿``:   Open
 
+   +1  backwards compatible,
+   +1  logical extension of the existing rules,
+   -1  exception list for "other" punctuation needed,
+   -1  rules even more complicated,
+   -1  not clear how to sort "other" punctuation that is currently not
+       recognized,
+   -2  international quoting convention like
+       »German ›angular‹ quotes« not recognized.
 
-Since Docutils 0.8, a "math" role and directive using LaTeX math
-syntax as input format is part of reStructuredText.
+.. _Inline markup recognition rules:
+   ../../ref/rst/restructuredtext.html#inline-markup-recognition-rules
+.. _Unicode categories:
+   http://www.unicode.org/Public/5.1.0/ucd/UCD.html#General_Category_Values
 
 
 -----------------
@@ -2686,6 +2648,62 @@ I've thought a bit more on this, and I came up with two possibilities:
 Both of these alternatives are flawed.  Any other ideas?
 
 
+Math Markup
+===========
+
+Since Docutils 0.8, a "math" role and directive using LaTeX math
+syntax as input format is part of reStructuredText.
+
+Use a "Transform" for math format conversions as extensively discussed in
+the "math directive issues" thread in May 2008
+
+Provide for alternative math input formats
+(see also http://osdir.com/ml/text.docutils.devel/2008-05/threads.html).
+
+MathML_
+  Not for hand-written code but maybe usefull when pasted in (or included
+  from a file)
+
+  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
+
+
+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 LaTeX, there is a 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>`__.
+
+
+
 -------------------
  ... Or Not To Do?
 -------------------
diff --git a/docutils/docs/dev/todo.txt b/docutils/docs/dev/todo.txt
index 9a918e52d..6292a4627 100644
--- a/docutils/docs/dev/todo.txt
+++ b/docutils/docs/dev/todo.txt
@@ -1123,70 +1123,85 @@ Misc
 * Generalize docinfo contents (bibliographic fields): remove specific
   fields, and have only a single generic "field"?
 
-Inline markup recognition rules
--------------------------------
+Math Markup
+-----------
 
-The `inline markup`_ recognition rules were devised intentionally to allow
-90% of non-markup uses of "*", "`", "_", and "|" *without* resorting to
-backslashes.  For 9% of the remaining 10%, use inline literals or literal
-blocks. Only those who understand the escaping and inline markup rules
-should attempt the remaining 1%.  ;-)
+Since Docutils 0.8, a "math" role and directive using LaTeX math
+syntax as input format is part of reStructuredText.
 
-.. _inline markup: ../ref/rst/restructuredtext.html#inline-markup
+Open issues:
 
-Changes need to be done in `parsers.rst.states.Inliner`.
+* Use a "Transform" for math format conversions as extensively discussed in
+  the "math directive issues" thread in May 2008
+  (http://osdir.com/ml/text.docutils.devel/2008-05/threads.html)?
 
-Alternatives
+* Generic "math-output" option (currently specific to HTML).
+  (List of math-output preferences?)
 
-a) Use `Unicode categories`_ for all chars (ASCII or not)
+* Try to be compatible with `Math support in Sphinx`_?
 
-   +1  comprehensible, standards based,
-   -1  many "false positives" need escaping,
-   -1  not backwards compatible.
+  * The ``:label:`` option selects a label for the equation, by which it
+    can be cross-referenced, and causes an equation number to be issued.
+    In Docutils, the option ``:name:`` sets the label.
+    Equation numbering is not implemented yet.
 
-b) full backwards compatibility
+  * Option ``:nowrap:`` prevents wrapping of the given math in a
+    math environment (you have to specify the math environment in the
+    content).
 
-   :Pi: only before start-string
-   :Pf: only behind end-string
-   :Po: "conservative" sorting of other punctuation:
+.. _Math support in Sphinx: http://sphinx.pocoo.org/ext/math.html
 
-        :``.,;!?\\``: Close
-        :``¡¿``:   Open
+* Equation numbering and references. (Should be handled in a unified way
+  with other numbered entities like formal tables and images.)
 
-   +1  backwards compatible,
-   +1  logical extension of the existing rules,
-   -1  exception list for "other" punctuation needed,
-   -1  rules even more complicated,
-   -1  not clear how to sort "other" punctuation that is currently not
-       recognized,
-   -2  international quoting convention like 
-       »German ›angular‹ quotes« not recognized.
+alternative input formats
+`````````````````````````
 
-.. _Unicode categories:
-   http://www.unicode.org/Public/5.1.0/ucd/UCD.html#General_Category_Values
+Use a directive option to specify an alternative input format, e.g. (but not
+limited to):
 
+MathML_
+  Not for hand-written code but maybe usefull when pasted in (or included
+  from a file)
 
-Math Markup
------------
+  For an overview of MathML implementations and tests, see, e.g.,
+  the `mathweb wiki`_ or the `ConTeXT MathML page`_.
 
-Since Docutils 0.8, a "math" role and directive using LaTeX math
-syntax as input format is part of reStructuredText.
+  .. _MathML: http://www.w3.org/TR/MathML2/
+  .. _mathweb wiki: http://www.mathweb.org/wiki/MathML
+  .. _ConTeXT MathML page: http://wiki.contextgarden.net/MathML
 
-Provide for `alternative input formats`__?
 
-__ ./rst/alternatives.html#math-markup
+ASCIIMath_
+  Simple, ASCII based math input language (see also `ASCIIMath tutorial`_).
 
-Try to be compatible with `Math support in Sphinx`_?
+  * The Python module ASCIIMathML_ translates a string with ASCIIMath into a
+    MathML tree. Used, e.g., by MultiMarkdown__.
 
-* The ``:label:`` option selects a label for the equation, by which it
-  can be cross-referenced, and causes an equation number to be issued.
-  In Docutils, this would be called ``:name:``.
+  * For conversion to LaTeX, there is a JavaScript script at
+    http://dlippman.imathas.com/asciimathtex/ASCIIMath2TeX.js
 
-* Option ``:nowrap:`` prevents wrapping of the given math in a
-  math environment (you have to specify the math environment in the
-  content).
+  .. _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>`__.
 
-.. _Math support in Sphinx: http://sphinx.pocoo.org/ext/math.html
 
 
 LaTeX output