Skip to content

Loading…

equation \label and \ref #71

Closed
slymz opened this Issue · 27 comments

6 participants

@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
MathJax member

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 dpvc added a commit to dpvc/MathJax that referenced this issue
@dpvc dpvc Add support for automatic line numbers, and the \label and \ref macro…
…s (resolves issue #71)
7e2ed03
@dpvc
MathJax member

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
MathJax member

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
MathJax member

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
MathJax member

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
MathJax member

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.

@dpvc
MathJax member

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
MathJax member

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 dpvc added a commit to dpvc/MathJax that referenced this issue
@dpvc dpvc Allow element ID's to use \label name rather than equation number (op…
…tionally). Requested in issue #71.
f4eecb6
@dpvc
MathJax member

@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

@ivanov ivanov referenced this issue in ipython/ipython
Closed

Figure out MathJax 2 support #1313

@fred-wang

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

@dpvc dpvc closed this
@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
MathJax member

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
MathJax member

@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{}.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Something went wrong with that request. Please try again.