Use "align" environment to wrap math equations instead of "gather"

[xuhdev]

Using align brings the benefit when multiple math equations are in one math directive, alignment is provided. We also use "aligned" to wrap the equations since in this way all the equations will be given only one label/tag, while previously only the first equation is labeled.

[tk0miya]

\label{None} will be generated here if label is None and numbering(math_number_all) is True.

[tk0miya]

Now, master branch has broken.
Multiple labels are assigned to multiple equations if definitions are separated by blank line.

Input:

.. math::
   :label: test

     E &= mc^2

   x^2 &= y^2 + z^2

In stable:

In master:

This PR:

This PR fixes the problem same time. it looks good.

But I don't know about the difference between gather and align environments.
Can anyone review this?

[xuhdev]

@tk0miya I've updated the PR so None label would not be generated.

gather is for the case where no alignment is desired among the equations, align is for the case where alignment is desired (section 3.5 and 3.6 in the doc). I recommend using align; the only case I can think of where gather behaves different with align is that, when the two equations occupies multiple lines and each of them has their own internal alignment, which however do not share the same alignment with each other. In this case, in the context of Sphinx, we can just ask the user to write the equations into two different math directives.

[xuhdev]

For example, the following LaTeX source:

\documentclass{article}
\usepackage{amsmath}

\begin{document}

Align:

\begin{align}
  \begin{aligned}
\begin{split}a &= b + c\\ &= d + e\end{split}
\\\begin{split}x + y &= z \\ &= u \end{split}
\end{aligned}
\end{align}

Gather:

\begin{gather}
  \begin{aligned}
\begin{split}a &= b + c\\ &= d + e\end{split}
\\\begin{split}x + y &= z \\ &= u \end{split}
\end{aligned}
\end{gather}

\end{document}

You can view the difference here. It also makes sense semantically when multi equations grouped together in a math directive in Sphinx are aligned.

[tk0miya]

Thank you for the thorough explanation. I understand clearly.
LGTM!

[tk0miya]

BTW, I found this article::
http://tex.stackexchange.com/questions/321/align-vs-equation

This says using align is bad idea and it should use equation by default.
How about the combination of equation and aligned?
I want to hear your opinion before merge this.

[birkenfeld]

Also (without having taken a closer look) keep backwards compatibility in mind please.

[xuhdev]

@tk0miya Yes, equation seems in general space better for single equations. We can use equation for single equations, since it's made for single equations (see the doc section 3.2). Do you want me to make the change?

Actually I think that gather (which we used to use) should space the same as align for single equations, because they are both made for multiple equations. But you guys can decide whether single equations should space "differently" (using equation for a better spacing) than before.

[tk0miya]

Thank you for comment.
Ok, I don't want to make changes between single equation and multiple ones.

Finally, I vote +1 to this again.

[xuhdev]

shall we merge this? :)

[tk0miya]

no objections? I will merge this in Sunday.

[xuhdev]

Also I believe the tag latex does not belong here...

[tk0miya]

Oops. You're right.

[tk0miya]

Thank you always!