diff options
Diffstat (limited to 'docutils')
| -rw-r--r-- | docutils/docs/dev/todo.txt | 18 | ||||
| -rw-r--r-- | docutils/docs/ref/rst/directives.txt | 16 | ||||
| -rw-r--r-- | docutils/docs/user/config.txt | 4 | ||||
| -rw-r--r-- | docutils/docs/user/links.txt | 17 | ||||
| -rw-r--r-- | docutils/docs/user/rst/cheatsheet.txt | 2 | ||||
| -rw-r--r-- | docutils/docutils/math/mathtools.py | 18 | ||||
| -rw-r--r-- | docutils/docutils/parsers/rst/directives/body.py | 27 | ||||
| -rw-r--r-- | docutils/docutils/writers/html4css1/html4css1.css | 2 | ||||
| -rw-r--r-- | docutils/test/functional/expected/math_output_html.html | 14 | ||||
| -rw-r--r-- | docutils/test/functional/expected/math_output_latex.html | 24 | ||||
| -rw-r--r-- | docutils/test/functional/expected/math_output_mathjax.html | 24 | ||||
| -rw-r--r-- | docutils/test/functional/expected/math_output_mathml.xhtml | 14 | ||||
| -rw-r--r-- | docutils/test/functional/expected/standalone_rst_latex.tex | 69 | ||||
| -rw-r--r-- | docutils/test/functional/input/data/math.txt | 39 | ||||
| -rw-r--r-- | docutils/test/test_parsers/test_rst/test_directives/test_math.py | 80 |
15 files changed, 249 insertions, 119 deletions
diff --git a/docutils/docs/dev/todo.txt b/docutils/docs/dev/todo.txt index 417528479..2c636bc47 100644 --- a/docutils/docs/dev/todo.txt +++ b/docutils/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/docutils/docs/ref/rst/directives.txt b/docutils/docs/ref/rst/directives.txt index d0b00ba67..e46f22628 100644 --- a/docutils/docs/ref/rst/directives.txt +++ b/docutils/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/docutils/docs/user/config.txt b/docutils/docs/user/config.txt index 425eabd7f..618d20dad 100644 --- a/docutils/docs/user/config.txt +++ b/docutils/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/docutils/docs/user/links.txt b/docutils/docs/user/links.txt index 3154a9102..a8085c8df 100644 --- a/docutils/docs/user/links.txt +++ b/docutils/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/docutils/docs/user/rst/cheatsheet.txt b/docutils/docs/user/rst/cheatsheet.txt index 1ef0788d5..40910deac 100644 --- a/docutils/docs/user/rst/cheatsheet.txt +++ b/docutils/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] diff --git a/docutils/docutils/math/mathtools.py b/docutils/docutils/math/mathtools.py index 222994a7d..ade3e2ad1 100644 --- a/docutils/docutils/math/mathtools.py +++ b/docutils/docutils/math/mathtools.py @@ -9,18 +9,24 @@ # mathtools.py: helpers for Docutils math support # ============================================================ -def pick_math_environment(code): - """Return the right math environment to display of `code`. +def pick_math_environment(code, numbered=False): + """Return the right math environment to display `code`. The test simply looks for line-breaks (``\\``) outside environments. - Multi-line formulae are set with ``align*``, one-liners with - ``equation*``. + Multi-line formulae are set with ``align``, one-liners with + ``equation``. + + If `numbered` evaluates to ``False``, the "starred" versions are used + to suppress numbering. """ # cut out environment content: chunks = code.split(r'\begin{') toplevel_code = ''.join([chunk.split(r'\end{')[-1] for chunk in chunks]) if toplevel_code.find(r'\\') >= 0: - return 'align*' + env = 'align' else: - return 'equation*' + env = 'equation' + if not numbered: + env += '*' + return env diff --git a/docutils/docutils/parsers/rst/directives/body.py b/docutils/docutils/parsers/rst/directives/body.py index 9f4ba700a..e666ba29f 100644 --- a/docutils/docutils/parsers/rst/directives/body.py +++ b/docutils/docutils/parsers/rst/directives/body.py @@ -108,18 +108,33 @@ class ParsedLiteral(Directive): node.line = self.content_offset + 1 return [node] + messages + class MathBlock(Directive): - option_spec = {'class': directives.class_option} has_content = True + required_arguments = 0 + optional_arguments = 1 + final_argument_whitespace = True + option_spec = {'class': directives.class_option + ## TODO: support Sphinx' ``mathbase.py`` options? + # 'label': directives.unchanged, + # 'nowrap': directives.flag, + } def run(self): set_classes(self.options) - self.assert_has_content() - latex_code = '\n'.join(self.content) - node = nodes.math_block(self.block_text, latex_code, **self.options) - node.line = self.content_offset + 1 - return [node] + if not self.arguments: + self.assert_has_content() + # join lines, separate blocks + content = '\n'.join(self.content).split('\n\n') + _nodes = [] + for block in self.arguments + content: + if not block: + continue + node = nodes.math_block(self.block_text, block, **self.options) + node.line = self.content_offset + 1 + _nodes.append(node) + return _nodes class Rubric(Directive): diff --git a/docutils/docutils/writers/html4css1/html4css1.css b/docutils/docutils/writers/html4css1/html4css1.css index 013939e7b..c8d032e08 100644 --- a/docutils/docutils/writers/html4css1/html4css1.css +++ b/docutils/docutils/writers/html4css1/html4css1.css @@ -240,7 +240,7 @@ pre.address { margin-top: 0 ; font: inherit } -pre.literal-block, pre.doctest-block { +pre.literal-block, pre.doctest-block, pre.math { margin-left: 2em ; margin-right: 2em } diff --git a/docutils/test/functional/expected/math_output_html.html b/docutils/test/functional/expected/math_output_html.html index 908108268..aac8b3ba4 100644 --- a/docutils/test/functional/expected/math_output_html.html +++ b/docutils/test/functional/expected/math_output_html.html @@ -22,6 +22,7 @@ role specificator, <span class="formula"> <div class="formula"> <i>f</i>(<i>ϵ</i>) = <span class="fraction"><span class="ignored">(</span><span class="numerator">1</span><span class="ignored">)/(</span><span class="denominator">1 + exp<span class="array"><span class="arrayrow"><span class="bracket align-left">⎛</span></span><span class="arrayrow"><span class="bracket align-left">⎝</span></span></span><span class="fraction"><span class="ignored">(</span><span class="numerator"><i>ε</i></span><span class="ignored">)/(</span><span class="denominator"><i>k</i><sub><span class="text">B</span></sub><i>T</i></span><span class="ignored">)</span></span><span class="array"><span class="arrayrow"><span class="bracket align-right">⎞</span></span><span class="arrayrow"><span class="bracket align-right">⎠</span></span></span></span><span class="ignored">)</span></span> </div> +<p>A display formula can also be given as directive argument, e.g.</p> <div class="formula"> <i>N</i> = <span class="fraction"><span class="ignored">(</span><span class="numerator"><span class="text">number of apples</span></span><span class="ignored">)/(</span><span class="denominator">7</span><span class="ignored">)</span></span> </div> @@ -59,7 +60,8 @@ role specificator, <span class="formula"> <p>is <span class="formula"> |<b>M</b>| = <i>ad</i> − <i>bc</i></span> .</p> -<p>Sum and Integral with limits:</p> +<p>More than one display math block can be put in one math directive. +For example, the following sum and integral with limits:</p> <div class="formula"> <span class="limits"><span class="limit">∫</span></span><span class="scripts"><sup class="script">1</sup><sub class="script">0</sub></span><i>x</i><sup><i>n</i></sup><i>dx</i> = <span class="fraction"><span class="ignored">(</span><span class="numerator">1</span><span class="ignored">)/(</span><span class="denominator"><i>n</i> + 1</span><span class="ignored">)</span></span> </div> @@ -133,9 +135,11 @@ physical system changes in time.</p> \widehat{xxx} --> <p>Modulation Transfer Function:</p> <div class="formula"> -<span class="text">MTF</span> = <span class="array"><span class="arrayrow"><span class="bracket align-left">|</span></span><span class="arrayrow"><span class="bracket align-left">|</span></span></span><span class="fraction"><span class="ignored">(</span><span class="numerator">ℱ{<i>s</i>(<i>x</i>)}</span><span class="ignored">)/(</span><span class="denominator">ℱ{<i>s</i>(<i>x</i>)}|<sub><i>ω</i><sub><i>x</i></sub> = 0</sub></span><span class="ignored">)</span></span><span class="array"><span class="arrayrow"><span class="bracket align-right">|</span></span><span class="arrayrow"><span class="bracket align-right">|</span></span></span> = <span class="text"> abs</span><span class="array"><span class="arrayrow"><span class="bracket align-left">⎛</span></span><span class="arrayrow"><span class="bracket align-left">⎝</span></span></span><span class="fraction"><span class="ignored">(</span><span class="numerator"><span class="limits"><span class="limit">∫</span></span><span class="scripts"><sup class="script">∞</sup><sub class="script"> − ∞</sub></span><i>s</i>(<i>x</i>)<span class="text">e</span><sup><span class="text">i</span><i>ω</i><sub><i>x</i></sub><i>x</i></sup><span class="text">d</span><i>x</i></span><span class="ignored">)/(</span><span class="denominator"><span class="limits"><span class="limit">∫</span></span><span class="scripts"><sup class="script">∞</sup><sub class="script"> − ∞</sub></span><i>s</i>(<i>x</i>)<span class="text">d</span><i>x</i></span><span class="ignored">)</span></span><span class="array"><span class="arrayrow"><span class="bracket align-right">⎞</span></span><span class="arrayrow"><span class="bracket align-right">⎠</span></span></span>. +<span class="text">MTF</span> = <span class="array"><span class="arrayrow"><span class="bracket align-left">|</span></span><span class="arrayrow"><span class="bracket align-left">|</span></span></span><span class="fraction"><span class="ignored">(</span><span class="numerator">ℱ{<i>s</i>(<i>x</i>)}</span><span class="ignored">)/(</span><span class="denominator">ℱ{<i>s</i>(<i>x</i>)}|<sub><i>ω</i><sub><i>x</i></sub> = 0</sub></span><span class="ignored">)</span></span><span class="array"><span class="arrayrow"><span class="bracket align-right">|</span></span><span class="arrayrow"><span class="bracket align-right">|</span></span></span> = <span class="mathrm"> abs</span><span class="array"><span class="arrayrow"><span class="bracket align-left">⎛</span></span><span class="arrayrow"><span class="bracket align-left">⎝</span></span></span><span class="fraction"><span class="ignored">(</span><span class="numerator"><span class="limits"><span class="limit">∫</span></span><span class="scripts"><sup class="script">∞</sup><sub class="script"> − ∞</sub></span><i>s</i>(<i>x</i>)<span class="mathrm">e</span><sup><span class="mathrm">i</span><i>ω</i><sub><i>x</i></sub><i>x</i></sup><span class="mathrm">d</span><i>x</i></span><span class="ignored">)/(</span><span class="denominator"><span class="limits"><span class="limit">∫</span></span><span class="scripts"><sup class="script">∞</sup><sub class="script"> − ∞</sub></span><i>s</i>(<i>x</i>)<span class="mathrm">d</span><i>x</i></span><span class="ignored">)</span></span><span class="array"><span class="arrayrow"><span class="bracket align-right">⎞</span></span><span class="arrayrow"><span class="bracket align-right">⎠</span></span></span>. </div> -<p>Math split over two lines:</p> +<p>Math split over two lines: If a double backslash is detected outside a +<tt class="docutils literal"><span class="pre">\begin{...}</span> <span class="pre">\end{...}</span></tt> pair, the math code is wrapped in an <a class="reference external" href="ftp://ftp.ams.org/ams/doc/amsmath/short-math-guide.pdf">AMSmath</a> +<tt class="docutils literal">align</tt> environment:</p> <div class="formula"> <span class="environment"><span class="arrayrow"> <span class="arraycell align-r"> @@ -197,8 +201,8 @@ physical system changes in time.</p> </span> </span><span class="emptydot"></span> </div> -<p>Cases with the AMSmath <tt class="docutils literal">cases</tt> environment (not (yet) -supported by latex2MathML):</p> +<p>Cases with the <a class="reference external" href="ftp://ftp.ams.org/ams/doc/amsmath/short-math-guide.pdf">AMSmath</a> <tt class="docutils literal">cases</tt> environment (not (yet) supported by +HTML writers with <tt class="docutils literal"><span class="pre">--math-output=MathML</span></tt>):</p> <div class="formula"> <span class="mathrm">sgn</span>(<i>x</i>) = <span class="array"><span class="arrayrow"><span class="bracket align-l">⎧</span></span><span class="arrayrow"><span class="bracket align-l">⎨</span></span><span class="arrayrow"><span class="bracket align-l">⎩</span></span></span><span class="bracketcases"> <span class="arrayrow"> diff --git a/docutils/test/functional/expected/math_output_latex.html b/docutils/test/functional/expected/math_output_latex.html index 0ec9656ba..d9aa8ba45 100644 --- a/docutils/test/functional/expected/math_output_latex.html +++ b/docutils/test/functional/expected/math_output_latex.html @@ -22,6 +22,7 @@ A_\text{c} = <pre class="math"> f(\epsilon) = \frac{1}{1 + \exp\left(\frac{\varepsilon}{k_\text{B}T}\right)} </pre> +<p>A display formula can also be given as directive argument, e.g.</p> <pre class="math"> N = \frac{\text{number of apples}}{7} </pre> @@ -32,7 +33,8 @@ N = \frac{\text{number of apples}}{7} <p>is <tt class="math"> |\mathbf{M}| = ad - bc</tt> .</p> -<p>Sum and Integral with limits:</p> +<p>More than one display math block can be put in one math directive. +For example, the following sum and integral with limits:</p> <pre class="math"> \int_0^1 x^n dx = \frac{1}{n + 1} </pre> @@ -106,14 +108,16 @@ physical system changes in time.</p> \widehat{xxx} --> <p>Modulation Transfer Function:</p> <pre class="math"> -\text{MTF}=\left|\frac{\mathcal{F}\{s(x)\}} - {\mathcal{F}\{ s(x)\} |_{\omega_{x}=0}}\right| - =\text{abs}\left(\frac{\int_{-\infty}^{\infty}s(x) - \text{e}^{\text{i}\omega_{x}x}\text{d}{x}} - {\int_{-\infty}^{\infty}s(x)\text{d}{x}} - \right). +\text{MTF} = \left|\frac{\mathcal{F}\{s(x)\}} + {\mathcal{F}\{ s(x)\} |_{\omega _{x}=0}}\right| + = \mathrm{abs}\left(\frac + {\int _{-\infty }^{\infty }s(x) \mathrm{e}^{\mathrm{i}\omega _{x}x}\mathrm{d}{x}} + {\int _{-\infty }^{\infty }s(x)\mathrm{d}{x}} + \right). </pre> -<p>Math split over two lines:</p> +<p>Math split over two lines: If a double backslash is detected outside a +<tt class="docutils literal"><span class="pre">\begin{...}</span> <span class="pre">\end{...}</span></tt> pair, the math code is wrapped in an <a class="reference external" href="ftp://ftp.ams.org/ams/doc/amsmath/short-math-guide.pdf">AMSmath</a> +<tt class="docutils literal">align</tt> environment:</p> <pre class="math"> s_{\mathrm{out}}(x) & = s_{\mathrm{in}}(x') * s_\delta (x-x') \\ & = \int s_{\mathrm{in}}(x')s_\delta (x-x')\mathrm{d}x' @@ -125,8 +129,8 @@ s_{\mathrm{out}}(x) & = s_{\mathrm{in}}(x') * s_\delta (x-x') \\ 1 & x>0 \end{matrix}\right. </pre> -<p>Cases with the AMSmath <tt class="docutils literal">cases</tt> environment (not (yet) -supported by latex2MathML):</p> +<p>Cases with the <a class="reference external" href="ftp://ftp.ams.org/ams/doc/amsmath/short-math-guide.pdf">AMSmath</a> <tt class="docutils literal">cases</tt> environment (not (yet) supported by +HTML writers with <tt class="docutils literal"><span class="pre">--math-output=MathML</span></tt>):</p> <pre class="math"> \mathrm{sgn}(x) = \begin{cases} -1 & x<0\\ diff --git a/docutils/test/functional/expected/math_output_mathjax.html b/docutils/test/functional/expected/math_output_mathjax.html index 99205a2aa..011697c73 100644 --- a/docutils/test/functional/expected/math_output_mathjax.html +++ b/docutils/test/functional/expected/math_output_mathjax.html @@ -25,6 +25,7 @@ role specificator, <span class="math"> f(\epsilon) = \frac{1}{1 + \exp\left(\frac{\varepsilon}{k_\text{B}T}\right)} \end{equation*} </div> +<p>A display formula can also be given as directive argument, e.g.</p> <div class="math"> \begin{equation*} N = \frac{\text{number of apples}}{7} @@ -39,7 +40,8 @@ N = \frac{\text{number of apples}}{7} <p>is <span class="math"> \(|\mathbf{M}| = ad - bc\)</span> .</p> -<p>Sum and Integral with limits:</p> +<p>More than one display math block can be put in one math directive. +For example, the following sum and integral with limits:</p> <div class="math"> \begin{equation*} \int_0^1 x^n dx = \frac{1}{n + 1} @@ -120,15 +122,17 @@ physical system changes in time.</p> <p>Modulation Transfer Function:</p> <div class="math"> \begin{equation*} -\text{MTF}=\left|\frac{\mathcal{F}\{s(x)\}} - {\mathcal{F}\{ s(x)\} |_{\omega_{x}=0}}\right| - =\text{abs}\left(\frac{\int_{-\infty}^{\infty}s(x) - \text{e}^{\text{i}\omega_{x}x}\text{d}{x}} - {\int_{-\infty}^{\infty}s(x)\text{d}{x}} - \right). +\text{MTF} = \left|\frac{\mathcal{F}\{s(x)\}} + {\mathcal{F}\{ s(x)\} |_{\omega _{x}=0}}\right| + = \mathrm{abs}\left(\frac + {\int _{-\infty }^{\infty }s(x) \mathrm{e}^{\mathrm{i}\omega _{x}x}\mathrm{d}{x}} + {\int _{-\infty }^{\infty }s(x)\mathrm{d}{x}} + \right). \end{equation*} </div> -<p>Math split over two lines:</p> +<p>Math split over two lines: If a double backslash is detected outside a +<tt class="docutils literal"><span class="pre">\begin{...}</span> <span class="pre">\end{...}</span></tt> pair, the math code is wrapped in an <a class="reference external" href="ftp://ftp.ams.org/ams/doc/amsmath/short-math-guide.pdf">AMSmath</a> +<tt class="docutils literal">align</tt> environment:</p> <div class="math"> \begin{align*} s_{\mathrm{out}}(x) & = s_{\mathrm{in}}(x') * s_\delta (x-x') \\ @@ -144,8 +148,8 @@ s_{\mathrm{out}}(x) & = s_{\mathrm{in}}(x') * s_\delta (x-x') \\ \end{matrix}\right. \end{equation*} </div> -<p>Cases with the AMSmath <tt class="docutils literal">cases</tt> environment (not (yet) -supported by latex2MathML):</p> +<p>Cases with the <a class="reference external" href="ftp://ftp.ams.org/ams/doc/amsmath/short-math-guide.pdf">AMSmath</a> <tt class="docutils literal">cases</tt> environment (not (yet) supported by +HTML writers with <tt class="docutils literal"><span class="pre">--math-output=MathML</span></tt>):</p> <div class="math"> \begin{equation*} \mathrm{sgn}(x) = \begin{cases} diff --git a/docutils/test/functional/expected/math_output_mathml.xhtml b/docutils/test/functional/expected/math_output_mathml.xhtml index 3deb12dde..27d738121 100644 --- a/docutils/test/functional/expected/math_output_mathml.xhtml +++ b/docutils/test/functional/expected/math_output_mathml.xhtml @@ -27,6 +27,7 @@ role specificator, <math xmlns="http://www.w3.org/1998/Math/MathML"> <mrow><mfrac> <mrow><mi>ε</mi></mrow> <mrow><msub><mi>k</mi><mtext>B</mtext></msub><mi>T</mi></mrow></mfrac></mrow></mfenced></mrow></mfrac></mtd></mtr></mtable></math> +<p>A display formula can also be given as directive argument, e.g.</p> <math xmlns="http://www.w3.org/1998/Math/MathML" mode="display"> <mtable> <mtr> @@ -50,7 +51,8 @@ role specificator, <math xmlns="http://www.w3.org/1998/Math/MathML"> <p>is <math xmlns="http://www.w3.org/1998/Math/MathML"> <mrow><mo>|</mo><mstyle fontweight="bold"> <mrow><mi>M</mi></mrow></mstyle><mo>|</mo><mo>=</mo><mi>a</mi><mi>d</mi><mo>-</mo><mi>b</mi><mi>c</mi></mrow></math>.</p> -<p>Sum and Integral with limits:</p> +<p>More than one display math block can be put in one math directive. +For example, the following sum and integral with limits:</p> <math xmlns="http://www.w3.org/1998/Math/MathML" mode="display"> <mtable> <mtr> @@ -153,7 +155,9 @@ physical system changes in time.</p> <mrow><mo>-</mo><mo>∞</mo></mrow> <mrow><mo>∞</mo></mrow></munderover><mi>s</mi><mo>(</mo><mi>x</mi><mo>)</mo><mtext>d</mtext> <mrow><mi>x</mi></mrow></mrow></mfrac></mrow></mfenced><mo>.</mo></mtd></mtr></mtable></math> -<p>Math split over two lines:</p> +<p>Math split over two lines: If a double backslash is detected outside a +<tt class="docutils literal"><span class="pre">\begin{...}</span> <span class="pre">\end{...}</span></tt> pair, the math code is wrapped in an <a class="reference external" href="ftp://ftp.ams.org/ams/doc/amsmath/short-math-guide.pdf">AMSmath</a> +<tt class="docutils literal">align</tt> environment:</p> <math xmlns="http://www.w3.org/1998/Math/MathML" mode="display"> <mtable> <mtr> @@ -178,10 +182,10 @@ physical system changes in time.</p> <mtr> <mtd><mn>1</mn></mtd> <mtd><mi>x</mi><mo>></mo><mn>0</mn></mtd></mtr></mtable></mrow></mfenced></mtd></mtr></mtable></math> -<p>Cases with the AMSmath <tt class="docutils literal">cases</tt> environment (not (yet) -supported by latex2MathML):</p> +<p>Cases with the <a class="reference external" href="ftp://ftp.ams.org/ams/doc/amsmath/short-math-guide.pdf">AMSmath</a> <tt class="docutils literal">cases</tt> environment (not (yet) supported by +HTML writers with <tt class="docutils literal"><span class="pre">--math-output=MathML</span></tt>):</p> <div class="system-message"> -<p class="system-message-title">System Message: ERROR/3 (<tt class="docutils">functional/input/data/math.txt</tt>, line 103)</p> +<p class="system-message-title">System Message: ERROR/3 (<tt class="docutils">functional/input/data/math.txt</tt>, line 102)</p> <p> Environment not supported! Supported environment: "matrix".</p> <pre class="literal-block"> diff --git a/docutils/test/functional/expected/standalone_rst_latex.tex b/docutils/test/functional/expected/standalone_rst_latex.tex index 21cd7787a..b5ff60f1f 100644 --- a/docutils/test/functional/expected/standalone_rst_latex.tex +++ b/docutils/test/functional/expected/standalone_rst_latex.tex @@ -368,7 +368,7 @@ Paragraphs contain text and may contain inline markup: \emph{emphasis}, (\url{http://www.python.org}), external hyperlinks (\href{http://www.python.org/}{Python}\DUfootnotemark{id30}{id29}{5}), internal cross-references (\hyperref[example]{example}), external hyperlinks with embedded URIs (\href{http://www.python.org}{Python web site}), \href{http://www.python.org/}{anonymous hyperlink -references}\DUfootnotemark{id33}{id29}{5} (\href{http://docutils.sourceforge.net/}{a second reference}\DUfootnotemark{id35}{id34}{6}), footnote references (manually +references}\DUfootnotemark{id36}{id29}{5} (\href{http://docutils.sourceforge.net/}{a second reference}\DUfootnotemark{id38}{id37}{7}), footnote references (manually numbered\DUfootnotemark{id1}{id8}{1}, anonymous auto-numbered\DUfootnotemark{id2}{id12}{3}, labeled auto-numbered\DUfootnotemark{id3}{label}{2}, or symbolic\DUfootnotemark{id4}{id13}{*}), citation references (\hyperlink{cit2002}{[CIT2002]}), substitution references (\includegraphics{../../../docs/user/rst/images/biohazard.png}), and % \phantomsection\label{inline-hyperlink-targets}inline hyperlink targets @@ -862,8 +862,8 @@ This footnote shows the next symbol in the sequence. \DUfootnotetext{id16}{id16}{4}{% Here's an unreferenced footnote, with a reference to a nonexistent footnote:% -\raisebox{1em}{\hypertarget{id41}{}}% -\raisebox{1em}{\hypertarget{id17}{}}\hyperlink{id40}{\textbf{\color{red}{[}5{]}\_}}. +\raisebox{1em}{\hypertarget{id44}{}}% +\raisebox{1em}{\hypertarget{id17}{}}\hyperlink{id43}{\textbf{\color{red}{[}5{]}\_}}. } @@ -880,8 +880,8 @@ rendered separately and differently from footnotes. \end{figure} Here's a reference to the above, \hyperlink{cit2002}{[CIT2002]}, and a % -\raisebox{1em}{\hypertarget{id43}{}}% -\raisebox{1em}{\hypertarget{id19}{}}\hyperlink{id42}{\textbf{\color{red}{[}nonexistent{]}\_}} +\raisebox{1em}{\hypertarget{id46}{}}% +\raisebox{1em}{\hypertarget{id19}{}}\hyperlink{id45}{\textbf{\color{red}{[}nonexistent{]}\_}} citation. @@ -909,7 +909,7 @@ Targets may be indirect and anonymous. Thus \hyperref[targets]{this phrase} may refer to the \hyperref[targets]{Targets} section. Here's a % -\raisebox{1em}{\hypertarget{id45}{}}\hyperlink{id44}{\textbf{\color{red}`hyperlink reference without a target`\_}}, which generates an +\raisebox{1em}{\hypertarget{id48}{}}\hyperlink{id47}{\textbf{\color{red}`hyperlink reference without a target`\_}}, which generates an error. @@ -937,7 +937,7 @@ explicit targets will generate ``warning'' (level-2) system messages. Since there are two ``Duplicate Target Names'' section headers, we cannot uniquely refer to either of them by name. If we try to (like this: % -\raisebox{1em}{\hypertarget{id47}{}}\hyperlink{id46}{\textbf{\color{red}`Duplicate Target Names`\_}}), an error is generated. +\raisebox{1em}{\hypertarget{id50}{}}\hyperlink{id49}{\textbf{\color{red}`Duplicate Target Names`\_}}), an error is generated. %___________________________________________________________________________ @@ -1239,11 +1239,15 @@ allowed (e.g. inside a directive). \url{http://www.python.org/} } % -\DUfootnotetext{id34}{id35}{6}{% +\DUfootnotetext{id33}{id34}{6}{% +\url{ftp://ftp.ams.org/ams/doc/amsmath/short-math-guide.pdf} +} +% +\DUfootnotetext{id37}{id38}{7}{% \url{http://docutils.sourceforge.net/} } % -\DUfootnotetext{id36}{id37}{7}{% +\DUfootnotetext{id39}{id40}{8}{% \url{A:DOS\\path\\} } @@ -1641,7 +1645,9 @@ role specificator, $n! + \sin(x_n^2)$ and $A_\text{c} = % \begin{equation*} f(\epsilon) = \frac{1}{1 + \exp\left(\frac{\varepsilon}{k_\text{B}T}\right)} -\end{equation*}% +\end{equation*} +A display formula can also be given as directive argument, e.g. +% \begin{equation*} N = \frac{\text{number of apples}}{7} \end{equation*} @@ -1652,7 +1658,8 @@ The determinant of the matrix \end{equation*} is $|\mathbf{M}| = ad - bc$. -Sum and Integral with limits: +More than one display math block can be put in one math directive. +For example, the following sum and integral with limits: % \begin{equation*} \int_0^1 x^n dx = \frac{1}{n + 1} @@ -1713,14 +1720,16 @@ $\vec{R}$ \texttt{\textbackslash{}vec\{R\}} Modulation Transfer Function: % \begin{equation*} -\text{MTF}=\left|\frac{\mathcal{F}\{s(x)\}} - {\mathcal{F}\{ s(x)\} |_{\omega_{x}=0}}\right| - =\text{abs}\left(\frac{\int_{-\infty}^{\infty}s(x) - \text{e}^{\text{i}\omega_{x}x}\text{d}{x}} - {\int_{-\infty}^{\infty}s(x)\text{d}{x}} - \right). +\text{MTF} = \left|\frac{\mathcal{F}\{s(x)\}} + {\mathcal{F}\{ s(x)\} |_{\omega _{x}=0}}\right| + = \mathrm{abs}\left(\frac + {\int _{-\infty }^{\infty }s(x) \mathrm{e}^{\mathrm{i}\omega _{x}x}\mathrm{d}{x}} + {\int _{-\infty }^{\infty }s(x)\mathrm{d}{x}} + \right). \end{equation*} -Math split over two lines: +Math split over two lines: If a double backslash is detected outside a +\texttt{\textbackslash{}begin\{...\} \textbackslash{}end\{...\}} pair, the math code is wrapped in an \href{ftp://ftp.ams.org/ams/doc/amsmath/short-math-guide.pdf}{AMSmath}\DUfootnotemark{id34}{id33}{6} +\texttt{align} environment: % \begin{align*} s_{\mathrm{out}}(x) & = s_{\mathrm{in}}(x') * s_\delta (x-x') \\ @@ -1734,8 +1743,8 @@ Cases (``manually'', with \texttt{matrix} environment): 1 & x>0 \end{matrix}\right. \end{equation*} -Cases with the AMSmath \texttt{cases} environment (not (yet) -supported by latex2MathML): +Cases with the \href{ftp://ftp.ams.org/ams/doc/amsmath/short-math-guide.pdf}{AMSmath}\DUfootnotemark{id35}{id33}{6} \texttt{cases} environment (not (yet) supported by +HTML writers with \texttt{-{}-math-output=MathML}): % \begin{equation*} \mathrm{sgn}(x) = \begin{cases} @@ -2517,7 +2526,7 @@ Handling by the LaTeX writer: \url{http://www.w3.org/XML/Schema\#dev} \item[] \href{http://www.w3.org/XML/Schema\%dev}{URL with \%} \url{http://example.org/Schema\%dev} -\item[] \href{A:DOS\\path\\}{file with DOS path}\DUfootnotemark{id37}{id36}{7} \url{A:DOS\\path\\}\DUfootnotemark{id38}{id36}{7} +\item[] \href{A:DOS\\path\\}{file with DOS path}\DUfootnotemark{id40}{id39}{8} \url{A:DOS\\path\\}\DUfootnotemark{id41}{id39}{8} \end{DUlineblock} \DUadmonition[note]{ @@ -2528,7 +2537,7 @@ These URLs are typeset inside a LaTeX command without error. \begin{DUlineblock}{0em} \item[] \url{http://www.w3.org/XML/Schema\#dev} \item[] \url{http://example.org/Schema\%dev} -\item[] \url{A:DOS\\path\\}\DUfootnotemark{id39}{id36}{7} +\item[] \url{A:DOS\\path\\}\DUfootnotemark{id42}{id39}{8} \end{DUlineblock} } @@ -2601,41 +2610,41 @@ Undefined substitution referenced: ``problematic''. \DUadmonition[system-message]{ \DUtitle[system-message]{system-message} -\raisebox{1em}{\hypertarget{id40}{}} +\raisebox{1em}{\hypertarget{id43}{}} {\color{red}ERROR/3} in \texttt{functional/input/data/standard.txt}, line~390 -\hyperlink{id41}{ +\hyperlink{id44}{ Unknown target name: ``5''. }} \DUadmonition[system-message]{ \DUtitle[system-message]{system-message} -\raisebox{1em}{\hypertarget{id42}{}} +\raisebox{1em}{\hypertarget{id45}{}} {\color{red}ERROR/3} in \texttt{functional/input/data/standard.txt}, line~399 -\hyperlink{id43}{ +\hyperlink{id46}{ Unknown target name: ``nonexistent''. }} \DUadmonition[system-message]{ \DUtitle[system-message]{system-message} -\raisebox{1em}{\hypertarget{id44}{}} +\raisebox{1em}{\hypertarget{id47}{}} {\color{red}ERROR/3} in \texttt{functional/input/data/standard.txt}, line~426 -\hyperlink{id45}{ +\hyperlink{id48}{ Unknown target name: ``hyperlink reference without a target''. }} \DUadmonition[system-message]{ \DUtitle[system-message]{system-message} -\raisebox{1em}{\hypertarget{id46}{}} +\raisebox{1em}{\hypertarget{id49}{}} {\color{red}ERROR/3} in \texttt{functional/input/data/standard.txt}, line~439 -\hyperlink{id47}{ +\hyperlink{id50}{ Duplicate target name, cannot be used as a unique reference: ``duplicate target names''. }} diff --git a/docutils/test/functional/input/data/math.txt b/docutils/test/functional/input/data/math.txt index 2cbadf7c4..bd2190aad 100644 --- a/docutils/test/functional/input/data/math.txt +++ b/docutils/test/functional/input/data/math.txt @@ -10,9 +10,9 @@ role specificator, :math:`n! + \sin(x_n^2)` and `A_\text{c} = f(\epsilon) = \frac{1}{1 + \exp\left(\frac{\varepsilon}{k_\text{B}T}\right)} -.. math:: +A display formula can also be given as directive argument, e.g. - N = \frac{\text{number of apples}}{7} +.. math:: N = \frac{\text{number of apples}}{7} The determinant of the matrix @@ -22,24 +22,21 @@ The determinant of the matrix is :math:`|\mathbf{M}| = ad - bc`. -Sum and Integral with limits: +More than one display math block can be put in one math directive. +For example, the following sum and integral with limits: .. math:: - \int_0^1 x^n dx = \frac{1}{n + 1} - -.. math:: + \int_0^1 x^n dx = \frac{1}{n + 1} - \sum_{n=1}^m n = \frac{m(m+1)}{2} + \sum_{n=1}^m n = \frac{m(m+1)}{2} LaTeX-supported Unicode math symbols can be used in math roles and directives: The Schrödinger equation -.. math:: - - i\hbar \frac{∂}{∂t}Ψ = \hat{H}Ψ, +.. math:: i\hbar \frac{∂}{∂t}Ψ = \hat{H}Ψ, with the *wave function* :math:`Ψ`, describes how the quantum state of a physical system changes in time. @@ -72,14 +69,16 @@ Modulation Transfer Function: .. math:: - \text{MTF}=\left|\frac{\mathcal{F}\{s(x)\}} - {\mathcal{F}\{ s(x)\} |_{\omega_{x}=0}}\right| - =\text{abs}\left(\frac{\int_{-\infty}^{\infty}s(x) - \text{e}^{\text{i}\omega_{x}x}\text{d}{x}} - {\int_{-\infty}^{\infty}s(x)\text{d}{x}} - \right). + \text{MTF} = \left|\frac{\mathcal{F}\{s(x)\}} + {\mathcal{F}\{ s(x)\} |_{ω_{x}=0}}\right| + = \mathrm{abs}\left(\frac + {∫_{-∞}^{∞}s(x) \mathrm{e}^{\mathrm{i}ω_{x}x}\mathrm{d}{x}} + {∫_{-∞}^{∞}s(x)\mathrm{d}{x}} + \right). -Math split over two lines: +Math split over two lines: If a double backslash is detected outside a +``\begin{...} \end{...}`` pair, the math code is wrapped in an AMSmath_ +``align`` environment: .. math:: @@ -95,8 +94,8 @@ Cases ("manually", with ``matrix`` environment): 1 & x>0 \end{matrix}\right. -Cases with the AMSmath ``cases`` environment (not (yet) -supported by latex2MathML): +Cases with the AMSmath_ ``cases`` environment (not (yet) supported by +HTML writers with ``--math-output=MathML``): .. math:: @@ -104,3 +103,5 @@ supported by latex2MathML): -1 & x<0\\ 1 & x>0 \end{cases} + +.. _AMSmath: ftp://ftp.ams.org/ams/doc/amsmath/short-math-guide.pdf diff --git a/docutils/test/test_parsers/test_rst/test_directives/test_math.py b/docutils/test/test_parsers/test_rst/test_directives/test_math.py new file mode 100644 index 000000000..00e56c7e6 --- /dev/null +++ b/docutils/test/test_parsers/test_rst/test_directives/test_math.py @@ -0,0 +1,80 @@ +#! /usr/bin/env python + +# $Id$ +# Author: Guenter Milde <milde@users.sf.net> +# Copyright: This module has been placed in the public domain. + +""" +Tests for the 'math' directive. +""" + +from __init__ import DocutilsTestSupport + +def suite(): + s = DocutilsTestSupport.ParserTestSuite() + s.generateTests(totest) + return s + +totest = {} + +totest['argument'] = [ +["""\ +.. math:: y = f(x) +""", +"""\ +<document source="test data"> + <math_block xml:space="preserve"> + y = f(x) +"""], +] + +totest['content'] = [ +["""\ +.. math:: + + 1+1=2 +""", +"""\ +<document source="test data"> + <math_block xml:space="preserve"> + 1+1=2 +"""], +] + +totest['argument_and_content'] = [ +["""\ +.. math:: y = f(x) + + 1+1=2 + +""", +"""\ +<document source="test data"> + <math_block xml:space="preserve"> + y = f(x) + <math_block xml:space="preserve"> + 1+1=2 +"""], +] + +totest['content with blank line'] = [ +["""\ +.. math:: + + 1+1=2 + + E = mc^2 +""", +"""\ +<document source="test data"> + <math_block xml:space="preserve"> + 1+1=2 + <math_block xml:space="preserve"> + E = mc^2 +"""], +] + + +if __name__ == '__main__': + import unittest + unittest.main(defaultTest='suite') |