mathjax
Improve docs for equation numbering
(Recently wrote something up for a sponsor; here's an extracted piece)
It might help to play around with http://cdn.mathjax.org/mathjax/latest/test/sample-eqnum.html while reading what follows.
There are three settings:
"all""AMS""none"
Does auto mean every equation is numbered or just the ability for every equation to be numbered?
Let's start with the second half.
"none" disables automatic numbering (see more below) but you can always label (display-mode) equations manually. This involves three macros:
\label{}-- adds a label which also acts as an ID for \ref{}\ref{}-- creates a link that references the equation (elsewhere in the page)\tag{}-- overrides the "printed" label so that it can be different from the ID created by \label{}.- E.g. "\label{eq:newton} \tag{Newton's First Law of Motion}" -- you'll use \ref{eq:newton} but the equation label will read "Newton's First Law of Motion".
- This also affects the name of the link generated by \ref{eq:newton}. (* you can use \tag{ } without label to get a label without an ID but that's bad practice.)
- E.g. "\label{eq:newton} \tag{Newton's First Law of Motion}" -- you'll use \ref{eq:newton} but the equation label will read "Newton's First Law of Motion".
Note that equation labels only work on display-mode equations (since we try to be faithful to LaTeX whenever possible).
Also note that you can still link to any (inline) equation or equation fragment by using MathJax's non-standard \cssId{id}{some math} macro (from the HTML extension); this macro wraps some math's output in a span with id so that you can then use a regular hyperlink to link to that.
Now for the first half -- automatic numbering.
Both "all" and "AMS" will have (some) equations automatically numbered. They differ and there are a couple of overrides.
"AMS" means equation numbers are attached only to equations made with equation-like environments (\begin{equation}, \begin{split} etc). This follows the AMSMath LaTeX package (which is probably one reason we have so little documentation for it).
"all" additionally numbers all display-mode mathematics (i.e., anything in [ ... ] ).
Now for the caveats.
Both automatic numbering methods will ignore certain equations:
- ignore: the starred environments, e.g., \begin{equation*} -- again, faithful LaTeX behavior.
- ignore: any equation with \notag in it
- override: explicitly labeling with \label or \tag{} will apply those and not increment the counter
You may want to be more careful about the word "label" versus "equation number" or "tag". For example, when you say "you can always label (display-mode) equations manually" I think you are referring to equation numbers (tags) not labels. In LaTeX, a label refers to an internal reference name used to access some number (like section number, page number, equation number) whose value might change as the document is edited. (You explain this when referring to \label{} and \ref{}). A label is not the equation number shown at the right (or left) of a displayed equation. That is the equation number, or more generally, its tag. Using "label" to refer to this will cause confusion to LaTeX users.
Your description from \tag{} suffers from this problem. You seem to imply that \tag{} is used to get a different printed equation identifier than the one used in \label{}, but the \label{} macro has nothing to do with whether there is a printed equation identifier or not, and why its value is. The \label{} macro simply provides an internal reference name to whatever the equation identifier is, if there is one (either generated automatically by the environment, or explicitly by \tag{}); \label{} does not say there should be a printed equation identifier, nor does it say what that identifier should be. That is the job of \tag{}, \notag, and the starred and un-starred environments. If \label{} is used in an expression that does not have an equation identifier, then it assigns its name as a reference to an empty string.
So, if equation numbering is set to none, for example, then
\[E=mc^2 \label{Einstein}\]
will display with no equation identifier, and \ref{Einstien} will display as ??? since there is no equation number for the labeled equation.
The way to force an equation to have a printed identifier is with \tag{}, so
\[E=mc^2 \tag{A}\]
will produce an equation with a printed identifier of (A). It will also have an HTML element with its id attribute set to mjx-eqn-A. There is no label for this equation, so \ref{} can not be used refer to it at this point.
Adding a \label{} macro, as in
\[E=mc^2 \tag{A}\label{Einstein}\]
still produces the same output (an equation identified by (A) at the right margin), but now there is an internal label called Einstein for use with \ref{} and \eqref{}. Using \ref{Einstein} will produce A in the document, and \eqref{Einstein} will produce (A). The HTML element now has id et to mjx-eqn-Einstein (unless useLabelIds is set to false).
Thanks for the corrections! I think I made the same mistake a while back -- darn. I'll update my message.
Does this read better?
It might help to play around with http://cdn.mathjax.org/mathjax/latest/test/sample-eqnum.html while reading what follows.
There are three settings:
"all""AMS""none"
Does auto mean every equation is numbered or just the ability for every equation to be numbered?
Let's start with the second half.
"none" disables automatic numbering (see more below) but you can always label (display-mode) equations manually. This involves three macros:
\tag{}-- defines the "printed" label (in the equation and when referenced).\label{}-- acts as an ID\ref{}-- creates a link to the ID generated by \label{} with the content of \tag{} (this is used elsewhere in the page)- E.g. "\label{eq:newton} \tag{Newton's First Law of Motion}" -- you'll use \ref{eq:newton} and it will will produce a link with "Newton's First Law of Motion".
(* you can use \tag{ } without label to get a label without an ID but that's bad practice.)
Note that equation labels only work on display-mode equations (since we try to be faithful to LaTeX whenever possible).
But also note that you can still link to any (inline) equation or equation fragment by using MathJax's non-standard \cssId{id}{some math} macro (from the HTML extension); this macro wraps some math's output in a span with id so that you can then use a regular hyperlink to link to that.
Now for the first half -- automatic numbering.
Both "all" and "AMS" will have (some) equations automatically numbered. They differ and there are a couple of overrides.
In general, the automatic method gives you the result of \label{NUMBER}\tag{NUMBER} keeps track of the current number automagically; see information about escaping below.
"AMS" means equation numbers are attached only to equations made with equation-like environments (\begin{equation}, \begin{split} etc). This follows the AMSMath LaTeX package (which is probably one reason we have so little documentation for it).
"all" additionally numbers all display-mode mathematics (i.e., anything in [ ... ] ).
You can still define \label{} so that you can reference a specific equation (i.e., without setting \tag{}).
You can also escape the automatic numbering by using \tag{} and \notag. Starred environments, e.g., \begin{equation*} also do not take part in the auto-numbering -- again, faithful LaTeX behavior.
I'm still a little concerned about calling the printed equation identifier a "label", since that can lead to confusion with \label{} (and may be the source of your own confusion over this). If you want a short term, "tag" might be better, as that is at least consistent with the TeX usage. "Equation number" is agnostic about the macro used, but is a bit inaccurate as the tag need not be a number. I used "equation identifier", which is horrible, but at last doesn't conflate the two ideas.
Here's my rewrite:
It might help to play around with http://cdn.mathjax.org/mathjax/latest/test/sample-eqnum.html while reading what follows.
There are three settings:
"all""AMS""none"
Does auto mean every equation is numbered or just the ability for every equation to be numbered?
Let's start with the second half.
"none" disables automatic numbering (see more below) but you can always tag (display-mode) equations manually. This involves four macros:
\tag{}-- defines the identifier that appears to the right or left of the equation on the page, and that is used to refer to the equation from other locations of the document.\label{}-- provides an internal ID that refers to the equation in which it appears.\ref{}or\eqref{}-- creates a link to the equation containing the associated\label{}.
The \tag{} macro automatically encloses the tag in parentheses (e.g., \tag{A} would put (A) at the right margin of the equation in which it appears). Adding a star after the \tag prevents the parentheses from being added (e.g., \tag*{A} uses A rather than (A) as the tag at the right).
The \ref{} macro uses the associated tag (without parentheses) as the text for the link to the equation. In contrast, the \eqref{} macro includes the parentheses.
For example, if you use \label{eq:newton} \tag{Newton's First Law of Motion} in a displayed equation, it will have (Newton's First Law of Motion) displayed at the right margin next to the equation, and you can use \ref{eq:newton} elsewhere in the page to refer to that equation; it will produce a link to that equation with using the text "Newton's First Law of Motion" as the link-text. If you use \eqref{eq:newton}, the link text will be "(Newton's First Law of Motion)".
Note that equation labels only work on display-mode equations, since those are the only ones that can be tagged or numbered (the label equates an id with the tag or equation number).
Note also that you can still link to any (inline) equation or equation fragment by using MathJax's non-standard \cssId{id}{some math} macro (from the HTML extension); this macro wraps some math's output in a span with id so that you can then use a regular hyperlink to link to that.
Now for the first half -- automatic numbering.
Both "all" and "AMS" will have (some) equations automatically numbered. They differ and there are a couple of overrides.
In general, the automatic method is like having \tag{NUMBER} added to (some) display equations automatically, and it keeps track of the current number automagically; see information about escaping below.
"AMS" means equation numbers are attached only to equations made with equation-like environments (\begin{equation}, \begin{multline} etc). This follows the AMSMath LaTeX package (which is probably one reason we have so little documentation for it).
"all" numbers all display-mode mathematics (i.e., anything in \[ ... \], $$...$$, or \begin{xyz}...\end{xyz}).
You can use \label{} with any equation that has an automatic equation number or an explicit \tag{} so that you can reference that equation via \ref{} or \eqref{} from anywhere on the page.
You can also escape the automatic numbering by using \tag{} and \notag. Here, \tag{} overrides the number with the tag you have given (and doesn't increment the counter), while \notag prevents a number from being assigned to that equation. Starred environments, e.g., \begin{equation*}, also do not take part in the auto-numbering -- again, faithful LaTeX behavior.
I'm still a little concerned about calling the printed equation identifier a "label", since that can lead to confusion with \label{} (and may be the source of your own confusion over this).
Right. I think this confusion of mine was caused by mlabeledtr and the spec's use of "label". Of course xkcd#927
Re:
\tag{}-- defines the identifier that appears to the right or left of the equation on the page, and that is used to refer to the equation from other locations of the document.
FWIW, "identifier and "refer" seem slightly confusing to me since it's close to id and \ref{}. But I have no idea how to make it clearer either :-(
I actually didn't know about \tag* and the difference between \ref and \eqref, so thanks for that clarification!
I think this confusion of mine was caused by
mlabeledtrand the spec's use of "label".
OK, makes sense. Since this is documenting the TeX control sequences, I'd stick with the TeX terminology.
"identifier and "refer" seem slightly confusing to me since it's close to
idand\ref{}.
Yes, "identifier" and "reference" are pretty generic and it is hard to distinguish which thing they actually indicate (the printed marker, or the internal id for that marker). If you want to be consistent, then I'd use "tag" for "identifier". Of course, here "tag" is probably not helpful, since you are explaining \tag{}. Perhaps
\tag{}-- defines the symbol that appears at the right (or left) of the equation and used to identify the equation from elsewhere in the document.
might be better?