From 87a4454517e286b81051f98f50819a87ae56212c Mon Sep 17 00:00:00 2001 From: milde Date: Fri, 14 Oct 2011 07:34:03 +0000 Subject: [PATCH] Move motivation to math directive decisions to "alternatives". git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@7172 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/rst/alternatives.txt | 80 +++++++++++++++++++++++++++++++++++++++++++ docs/dev/todo.txt | 72 ++++++-------------------------------- 2 files changed, 90 insertions(+), 62 deletions(-) diff --git a/docs/dev/rst/alternatives.txt b/docs/dev/rst/alternatives.txt index 726b536fb..2f580411e 100644 --- a/docs/dev/rst/alternatives.txt +++ b/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 + `__. + + +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/docs/dev/todo.txt b/docs/dev/todo.txt index a2f520bc7..c2d7bc0c8 100644 --- a/docs/dev/todo.txt +++ b/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 -`__. +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/ -- 2.11.4.GIT