Mathjax: equation \label and \ref

[slymz]

Feature request! Can we have \label and \ref facilities for equations?

This may be a popular one indeed, but I couldn't find it on issue list (or mention of it in the documentation). And is basically been discussed long back: http://sourceforge.net/projects/mathjax/forums/forum/948700/topic/3817124

Thank you!

[dpvc]

It is on the list of things to add, but we have been concentrating on performance and bug fixes for the 1.1 release. I have not forgotten about it, and it is one of the things that should be added following version 1.1.

Davide

[dpvc]

I have posted an implementation of automatic equation numbering, along with the \label and \ref macros, in the issue71 branch of my fork of MathJax. This required some important changes to the core routines of MathJax, so you should be cautious when using this, as those changes are very new, and so haven't had the shake-down that the rest of the core has. I am confident that they are OK, but there may be subtleties that we find as they see more use.

There are new configuration parameters (see the config/defaults.js file) that control the equation numbering. In particular, The TeX.equationNumbers.autoNumber configuration parameter controls how MathJax handles automatic numbering. By default, no automatic numbering is done (so the default is the same as the current MathJax behavior). But you can set

MathJax.Hub.Config({
  TeX: { 
     equationNumbers: {  autoNumber: "AMS"  },
     extensions: ["AMSmath.js"]
  }
});

to get numbering for the AMS environments (equation, align, gather, multline, etc.), with the starred environments suppressing the numbers. You can use \tag to provide your own equation number, and \label and \ref to access the equation number within the text of the page. (The \ref command is now recognized both in and out of math mode.)

If you set autoNumber to "all" then every displayed equation will be numbered automatically.

An issue to keep in mind: the equation numbers are handled using the mlabeledtr MathML element, which is not implemented by Firefox (neither version 3 nor 4), so if you use the NativeMML renderer, the equation numbers will not be shown. Note that the combined configuration files that include "HTMLorMML" will select NativeMML output in Firefox, for example. This can be overridden by specifying

<script type="text/x-mathjax-config">
MathJax.Hub.Config({
  MMLorHTML: { prefer: { Firefox: "HTML" } }
});
</script>

prior to loading MathJax.js in order to force Firefox to use the HTML-CSS output renderer rather than the NativeMML renderer (while still allowing IE/MathPlayer to use MathML).

I am still working on this branch, so changes my still be made. I'm not happy with the method used to handle forward references, and may be changing how that works (though that will be internal, and won't change how it appears to authors or users).

Davide

[vbeffara]

That's absolutely fantastic, thanks a lot !

One bug though, typing \text{(see \eqref{cs})} while in math mode seems to eat the second closing parenthesis. Adding a space before it works perfectly.

[dpvc]

OK, I'll check into it. There must be an index that is off by 1 when the reference is being removed from the text.

[dpvc]

I have fixed the incorrect index that was causing the character following the \eqref to be dropped. You can update your copy of the issue71 branch to get the fix.

Davide

[dpvc]

Note: I also updated it so that you don't have to explicitly request the AMSmath extension; if you turn on auto-numbering, it will be loaded automatically now.

Davide

[fred-wang]

==> Setting to testcase wanted as I plan to add unit tests to cover this feature.

[dpvc]

There are a lot of things to test, here. Forward references, backward references, references to no-existent labels, the use of \tag to override the automatic numbering, the use of \notag and \nonumber to prevent numbering, the numbering for the different AMS environments, the different settings for autoNumber, and so on. It will be a pain, I'm sorry to say.

[fred-wang]

Yes, I'm aware of it. That's why I'm only tagging the issue as testcase wanted and postpone writing these tests.
However, if some contributors are kind enough to list the different use cases and give ideas for tests (maybe even write them), then it will really be helpful.

[fred-wang]

I've prepared a couple of tests for this.

Configuration/tex2jax/processRefs-1.html
Configuration/TeX/equationNumbers/autoNumber-1.html
Configuration/TeX/equationNumbers/autoNumber-2.html
Configuration/TeX/equationNumbers/autoNumber-3.html
Configuration/TeX/equationNumbers/autoNumber-4.html
Configuration/TeX/equationNumbers/formatID-1.html
Configuration/TeX/equationNumbers/formatNumber-1.html
Configuration/TeX/equationNumbers/formatTag-1.html
Configuration/TeX/equationNumbers/formatURL-1.html
LaTeXToMathML/references/eqref-1.html
LaTeXToMathML/references/label-1.html
LaTeXToMathML/references/ref-1a.html
LaTeXToMathML/references/ref-1b.html
LaTeXToMathML/references/ref-2.html
LaTeXToMathML/references/ref-3.html
LaTeXToMathML/references/tag-1.html
LaTeXToMathML/references/tag-2.html
LaTeXToMathML/references/notag-1.html

==> In testsuite

There is an extra comma in tex2jax.js, line 181, which makes IE crash.

[fred-wang]

It seems that the mlabeledtr disappear with Firefox when native MathML is enabled. Consider for example:

http://devel.mathjax.org/testing/testsuite/Configuration/TeX/equationNumbers/formatTag-1.html?mathJaxPath=http://devel.mathjax.org/testing/mathjax/dpvc/issue71/

[fred-wang]

test results:
http://devel.mathjax.org/testing/web/results/issueReviews/issue71/

[dpvc]

There is an extra comma in tex2jax.js, line 181, which makes IE crash.

Yes, I already spotted that and have fixed it in the v2.0-candidate branch (since I have merged all the separate branches, I haven't been making change in them separately any longer).

It seems that the mlabeledtr disappear with Firefox when native MathML is enabled.

This is because Firefox doesn't implement <mlabeledtr>, and it drops any such rows, so rather than have the math disappear, MathJax changes to a plain <mtr> and drops the label as a compromise. (This should be on the list of Firefox problems, if it isn't already. Now that automatic numbering is part of MathJax, this is going to be a more serious limitation for Firefox's native MathML, and is one of the reasons that v2.0 is probably going to change the default to prefer HTML-CSS rather than NativeMML for Firefox.)

[fred-wang]

For Firefox, why do we remove the label? We may leave it, even if it is not well positioned?

[dpvc]

Because the label is the first <mtd> in an <mlabeledtr>, just replacing the <mlabeledtr> with <mtr> would throw off the columns. You would either have to go back and insert blank entries in all the other (unlabeled) rows of the table, or would have to move the label to the end of the row, possibly adding blank entries to make sure that the label is past the right-hand column used in any other row of the table. Both of these were more complicated than I wanted to do. The expectation with the NativeMML output jax was to not modify the MathML any more than absolutely necessary, and I only did this much in order to avoid losing the mathematics entirely. I don't think it is wise to try to work around every native MathML bug in every browser's renderer. My original hope was that Firefox would eventually implement the missing features, and the removal of the label would be temporary, but this doesn't seem to be in offing any time soon.

Davide

[fred-wang]

Note that a change for mlabeledtr is targeted for Firefox 9:
https://bugzilla.mozilla.org/show_bug.cgi?id=356870

The content of mlabeledtr is now displayed as a normal row, except the label which is hidden by default (this can be overridden using a CSS rule).

For the bug to implement mlabeledtr, see
https://bugzilla.mozilla.org/show_bug.cgi?id=689641

[fred-wang]

Firefox 9 has been released and includes the workaround for mlabeledtr, so MathJax won't need to do it itself for that version.

[GrahamDennis]

Is there any chance of getting \label to (possibly optionally) set the id attribute on the equation to something predictable and derived from the label? This would enable references from other documents to a given equation.

For example, at the moment, if I have

\begin{align}
F &= m a \label{NewtonsLaw}
\end{align}

This will generate an id mjx-eqn-1 if it's the first equation. This works within the document because \eqref{NewtonsLaw} generates a link to mjx-eqn-1.

However, I can't refer to the equation from another HTML document without knowing the equation number. i.e. I can't create an external link to http://www.mywebsite.com/mypage.html#mjx-eqn-NewtonsLaw

[dpvc]

@grahamdennis -- good idea. I have modified the v2.0-candidate branch to include the changes needed to make that happen. The changes needed are small, so you could edit your own copy of AMSmath.js and the TeX/config.js files to include them.

Davide

[GrahamDennis]

Thanks @dpvc!

[fred-wang]

I'm about to update the tests to take into account the latest change.

[fred-wang]

Firefox 9 has been released and includes the workaround for mlabeledtr, so MathJax won't need to do it itself for that version.

Davide, did you take this comment into account for MathJax 2.0? With MathJax workaround removed, Firefox users will be able to display the label if they want to, using the simple CSS rule mlabeledtr > mtd:first-child { display: table-cell; }.

[dpvc]

Yes, the work-around for <mlabeledtr> is conditionally applied, and isn't used for FF9 and above. See the NativeMML jax.js file line 492.

[fred-wang]

OK, great! Thanks.

[emptymalei]

Can I set it to number equations only when \label is added? I don't use \label and \ref very often.

I know I can use equation* environment in LaTeX, but unfortunately, I am using Markdown and * is reserved for markdown syntax.

Thank you.

[dpvc]

@emptymalei, there is no setting for what you are looking for, but you could use explicit \tag{} macros when you want a numbered equation. This would require you to do the numbering yourself, but if you only need a few references, that might work for you. So you would use \label{} and \tag{} together to number an equation and provide a label to refer to it by later.

[emptymalei]

@dpvc Thank you. I 'll try \tag{}.

[simonmysun]

Hi,

Thank you all for the amazing project and this amazing feature. Here I have a small problem. When modifying maths with \label inside, the labels will be multiply defined(to reproduce this you may try to edit a formula with \label in any MathJax live demo).

I believe it can be fixed by removing the label definition in MathJax when replacing the HTML elements. But I haven't find any interface to inform this removing, or any code that can clear the definitions without refreshing the page.

Does any have any idea what I can do?

Thank you in advance.

[pkra]

Please don't re-use threads.

You'll want to read the documentation on resetting equation numbers.

[simonmysun]

Alright I thought it is an incomplete feature rather than bug. I'll start a new issue.

The equation numbers can be resetted, but the labels cannot.

[dpvc]

The labels are reset as well by resetEquationNumbers(), though the documentation could be clearer about that.

[simonmysun]

Thank you very much! It must be my wrong usage leading to the failure. Thank you again. Sorry for disturbing.

[cben]

It seems MathJax.InputJax.TeX.resetEquationNumbers() was a 2.x construct: http://docs.mathjax.org/en/v2.7-latest/advanced/typeset.html#reset-automatic-equation-numbering
optional args undocumented but explained by Davide at https://github.com/mathjax/MathJax/issues/1705#issuecomment-282743204, thanks.
In 3.x replaced by MathJax.texReset() http://docs.mathjax.org/en/v3.0-latest/web/typeset.html#tex-reset
[of course, tons of things changed in 3.0. this is mostly to help future me find this again as I'm still on 2.x ;-) It's a bit unfortunate lots of 2.x doc links are now breaking if they were to "latest/"...]