Multiline math equations in documentation

[Travis Scrimshaw]

Hey everyone,

   While reviewing #14130, there was a multiline array* environment inside of a .. MATH::, and this ended up building just fine as html, but did not compile in pdf form. For example, suppose you have:

.. MATH::

    \begin{align*}

    f(x) & = x^2 - 2 \\

    g(x) & = \frac{f(x) - x^3}{x-3}

    \end{align*}

This would build as a html doc, but would fail as a pdf doc. Is this a bug or is there a better way of doing things?

Thanks,

Travis

For reference, we reformatted the doc on #14130 to work around this.

[kcrisman]

Thanks for tracking this down, Travis.

On Wednesday, February 27, 2013 10:24:36 AM UTC-5, Travis Scrimshaw wrote:

Hey everyone,

   While reviewing #14130, there was a multiline array* environment inside of a .. MATH::, and this ended up building just fine as html, but did not compile in pdf form. For example, suppose you have:

Is this conceivably because align is in the amsmath package and we (perhaps) don't include packages in the pdf building?  I don't know if we use many such environments elsewhere in the doc.  How do these examples look in the pdf (if they are even in the reference manual)?

sage: search_src('begin{align')

coding/linear_code.py:1577:             \begin{aligned}

combinat/cluster_algebra_quiver/quiver.py:544:                    html( "$\\begin{align*} " + m + "\\end{align*}$" )

graphs/graph_decompositions/vertex_separation.pyx:151:    \begin{alignat}{2}

interacts/library.py:984:            \begin{align*}

interacts/library.py:1103:        \begin{align*}

matrix/matrix0.pyx:1893:##         s = "\\left(\\begin{align*}\n"

rings/polynomial/padics/polynomial_padic_capped_relative_dense.py:530:        \begin{align*}

[Travis Scrimshaw]

Hey,

Is this conceivably because align is in the amsmath package and we (perhaps) don't include packages in the pdf building? 

 I don't know if we use many such environments elsewhere in the doc.  How do these examples look in the pdf (if they are even in the reference manual)?

 

sage: search_src('begin{align')

coding/linear_code.py:1577:             \begin{aligned}

combinat/cluster_algebra_quiver/quiver.py:544:                    html( "$\\begin{align*} " + m + "\\end{align*}$" )

This is for output in the notebook, so it's not in the doc.

 

graphs/graph_decompositions/vertex_separation.pyx:151:    \begin{alignat}{2}

This one seems to work (I presume it compiles in the pdf doc okay), although the html does quite like the \intertext...

Here's the full doc for reference:

.. MATH::

    :nowrap:

    \begin{alignat}{2}

    \intertext{Minimize:}

    &z&\\

    \intertext{Such that:}

    x_v^t &\leq x_v^{t+1}& \forall v\in V,\ 0\leq t\leq n-2\\

    y_v^t &\leq y_v^{t+1}& \forall v\in V,\ 0\leq t\leq n-2\\

    y_v^t &\leq x_w^t& \forall v\in V,\ \forall w\in N^+(v),\ 0\leq t\leq n-1\\

    \sum_{v \in V} y_v^{t} &= t+1& 0\leq t\leq n-1\\

    x_v^t-y_v^t&\leq u_v^t & \forall v \in V,\ 0\leq t\leq n-1\\

    \sum_{v \in V} u_v^t &\leq z& 0\leq t\leq n-1\\

    0 \leq x_v^t &\leq 1& \forall v\in V,\ 0\leq t\leq n-1\\

    0 \leq u_v^t &\leq 1& \forall v\in V,\ 0\leq t\leq n-1\\

    y_v^t &\in \{0,1\}& \forall v\in V,\ 0\leq t\leq n-1\\

    0 \leq z &\leq n&

    \end{alignat}

 

interacts/library.py:984:            \begin{align*}

interacts/library.py:1103:        \begin{align*}

These are used in output, so not in the doc. 

 

matrix/matrix0.pyx:1893:##         s = "\\left(\\begin{align*}\n"

This one is commented out (actually the whole function is), so it's not in the doc.

 

rings/polynomial/padics/polynomial_padic_capped_relative_dense.py:530:        \begin{align*}

The one in padics is inside of a _mul_(), so it's not in the doc.

The big thing I'd like is consistency: If the html docbuild works, then the pdf should as well and vice versa.

Best,

Travis

[kcrisman]

 

graphs/graph_decompositions/vertex_separation.pyx:151:    \begin{alignat}{2}

This one seems to work (I presume it compiles in the pdf doc okay), although the html does quite like the \intertext...

Here's the full doc for reference:

.. MATH::

    :nowrap:

    \begin{alignat}{2}

    \intertext{Minimize:}

    &z&\\

    \intertext{Such that:}

    x_v^t &\leq x_v^{t+1}& \forall v\in V,\ 0\leq t\leq n-2\\

    y_v^t &\leq y_v^{t+1}& \forall v\in V,\ 0\leq t\leq n-2\\

    y_v^t &\leq x_w^t& \forall v\in V,\ \forall w\in N^+(v),\ 0\leq t\leq n-1\\

    \sum_{v \in V} y_v^{t} &= t+1& 0\leq t\leq n-1\\

    x_v^t-y_v^t&\leq u_v^t & \forall v \in V,\ 0\leq t\leq n-1\\

    \sum_{v \in V} u_v^t &\leq z& 0\leq t\leq n-1\\

    0 \leq x_v^t &\leq 1& \forall v\in V,\ 0\leq t\leq n-1\\

    0 \leq u_v^t &\leq 1& \forall v\in V,\ 0\leq t\leq n-1\\

    y_v^t &\in \{0,1\}& \forall v\in V,\ 0\leq t\leq n-1\\

    0 \leq z &\leq n&

    \end{alignat}

 

 

Huh.  Yeah, this looks great in pdf, and apparently alignat is in amsmath too.

Note that the whole graph section looks a little funny, because the table columns aren't always wide enough for the stuff in them.  We need wrapping...

The big thing I'd like is consistency: If the html docbuild works, then the pdf should as well and vice versa.

Totally! I'm just trying to help diagnose it. 

[John H Palmieri]

On Wednesday, February 27, 2013 7:24:36 AM UTC-8, Travis Scrimshaw wrote:

Hey everyone,

   While reviewing #14130, there was a multiline array* environment inside of a .. MATH::, and this ended up building just fine as html, but did not compile in pdf form. For example, suppose you have:

.. MATH::

    \begin{align*}

    f(x) & = x^2 - 2 \\

    g(x) & = \frac{f(x) - x^3}{x-3}

    \end{align*}

This would build as a html doc, but would fail as a pdf doc. Is this a bug or is there a better way of doing things?

The problem is the "align" environment: it is not meant to be used in math mode, but rather as a way to enter math mode instead of \[ \] delimiters (or $$ $$ delimiters, etc.). Using the ".. math::" markup tells Sphinx that the following code should be typeset in math mode, and then using \begin{align} tells it to enter math mode again, and this naturally leads to an error when you run pdflatex on it. You can look at the LaTeX source code to check (in doc/output/latex/en/...); it will probably have an align environment nested inside a gather environment.

Using an environment like "aligned" is better, since aligned is meant to be used within math mode.

So no, I don't think it's a bug.
 
--
John

[John H Palmieri]

I guess another option is as it's done in vertex_separation.pyx:

.. math::
    :nowrap:

    \begin{align*}
    ...
    \end{align*}

":nowrap:" tells Sphinx not to include math delimiters, so you're free to use align*, etc.

--
John

[Travis Scrimshaw]

Hey,

The problem is the "align" environment: it is not meant to be used in math mode, but rather as a way to enter math mode instead of \[ \] delimiters (or $$ $$ delimiters, etc.). Using the ".. math::" markup tells Sphinx that the following code should be typeset in math mode, and then using \begin{align} tells it to enter math mode again, and this naturally leads to an error when you run pdflatex on it. You can look at the LaTeX source code to check (in doc/output/latex/en/...); it will probably have an align environment nested inside a gather environment.

Using an environment like "aligned" is better, since aligned is meant to be used within math mode.

So no, I don't think it's a bug.

 

How difficult would it be to get the html docbuild to also fail on putting align* in the ".. MATH::" and would anyone be opposed to putting a note about the aligned environment in the developer's guide?

Thanks,

Travis

[kcrisman]

I'd be in favor of this, as long as whoever put that note in also did a little experimentation/research to see what other environments might accidentally get put in math mode (or need the :nowrap).

[John H Palmieri]

My guess is that the reason it works is because MathJax is being forgiving in how it parses things. I don't know if MathJax has a "strict" setting which would complain in these cases.

I think the developer's guide could have a comment about how the ".. math::" environment puts you into math mode, so using {align} won't work while {aligned} will. Also mention "nowrap".  (There have been other issues with this, for example people using \texttt{...} for the output of _latex_, even though \texttt is, as its name indicates, supposed to be used in text mode, not math mode. So I definitely think we should point out that output from _latex_ methods and anything in ".. math::" blocks should be in math mode.)
 
--
John

[Travis Scrimshaw]

Hey everyone,

My guess is that the reason it works is because MathJax is being forgiving in how it parses things. I don't know if MathJax has a "strict" setting which would complain in these cases.

Hmm...well at least behavior will now be documented.

I think the developer's guide could have a comment about how the ".. math::" environment puts you into math mode, so using {align} won't work while {aligned} will. Also mention "nowrap".  (There have been other issues with this, for example people using \texttt{...} for the output of _latex_, even though \texttt is, as its name indicates, supposed to be used in text mode, not math mode. So I definitely think we should point out that output from _latex_ methods and anything in ".. math::" blocks should be in math mode.)
 

This is now trac ticket #14230 and is ready for review.

Thanks,

Travis