From c52d45835e0756fd5e6c3c4ef795b9417c00212a Mon Sep 17 00:00:00 2001 From: milde Date: Mon, 27 Feb 2012 11:15:38 +0000 Subject: [PATCH] Update TODO list math input formats (todo), move inline markup recognition alternatives to "alternatives". git-svn-id: https://docutils.svn.sourceforge.net/svnroot/docutils/trunk@7372 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docutils/docs/dev/rst/alternatives.txt | 154 ++++++++++++++++++--------------- docutils/docs/dev/todo.txt | 103 ++++++++++++---------- 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 - `__. + :``.,;!?\\``: 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 + `__. + + + ------------------- ... 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 + `__. -.. _Math support in Sphinx: http://sphinx.pocoo.org/ext/math.html LaTeX output -- 2.11.4.GIT