Re: [O] Equation references in HTML export

[Thibault Marin]

Hi,


> You may be right. In this case, we may use \eqref if MathJax is
> going to be used (like your initial patch did), and do the above
> otherwise.

OK, I think that would work.  To summarize, here are the different
outputs under MathJax and the other modes:

- MathJax mode:
  - Environment:
    ,----
    | \begin{align}
    | \label{eq:org19c7f92}
    | 1 + 1 = 0
    | \end{align}
    `----
  - Link:
    ,----
    | link to \eqref{eq:org19c7f92}
    `----
- other modes, e.g. verbatim: (it is similar for the rest: dvipng,
  imagemagick, etc).:
  - Environment
    ,----
    | <div id="org19c7f92" class="equation-container">
    | <span class="equation">
    | \begin{align}
    | 1 + 1 = 0
    | \end{align}
    | 
    | </span>
    | <span class="equation-label">
    | 1
    | </span>
    | </div>
    `----
  - Link:
    ,----
    | link to equation <a href="#org19c7f92">1</a>
    `----

The attached patch produces this on my test cases.

About the CSS caption:
> I'm not sure. Have you checked how captions in other parts of
> "ox-html.el"?

I looked at other structures:
- for figures, the caption is in a `figcaption' tag if HTML5 is used or
  in a paragraph, both under the figure,
- for tables, the caption is in a `caption' tag, at the top or bottom of
  the environment depending on `:html-table-caption-above',
- As far as I can tell, source blocks get no caption.

Since there does not appear to have a common convention, I think the
proposed output (see above with "equation-container", "equation" and
"equation-label" tags) would be fine, if nobody objects.  Some CSS puts
the label on the right side, as with LaTeX export or MathJax.  This only
applies to the non-MathJax modes.


> Do we need to rely on `org-latex-caption-above', which is LaTeX
> specific? We could instead extend `org-html-table-caption-above' to
> handle LaTeX environments, and rename it `org-html-caption-above'.

I think I misunderstood what the caption does in ox-latex.  Here, in the
MathJax case, just I need to insert the `\label' inside the latex
environment, e.g. `\begin{equation}\label{org21321}' similar to what
`org-latex-latex-environment' does.  The caption itself (the equation
number) is always on the right of the equation, regardless of the mode
(MathJax or other), so this is variable is not needed anymore.


I hope the patch looks better now.  I have a few remaining questions:

- The `org-html--is-math-environment' function relies on
  `org-latex-math-environments-re' from ox-latex for the numbering
  (numbering only equations, ignoring other environments).  Is it
  acceptable?
- In non-MathJax modes, I currently pre-process the latex environment to
  change equation environments to their * version,
  e.g. "\begin{equation}" -> "\begin{equation*}".  This is to prevent
  the latex environment from adding its own labeling to the rendered
  image.  This feels like a hack.  Is there a better way to achieve
  this?
- The `org-html--insert-latex-environment-label' (the function that
  inserts `\label' inside the environment also feels like a hack.  I
  originally wanted to re-use the equivalent latex code, but maybe this
  is simpler.  Do you think we can do better?
- In the image modes (e.g. dvipng), I removed the following comment: ";;
  Do not provide a caption or a name to be consistent with `mathjax'
  handling."  I am not sure what it means and whether I should be
  concerned about it.
- I think I have been with messing this file enough now that I should
  add tests.  I didn't see any tests for ox-latex or ox-html.  Is there
  a reason for that?


Please let me know if you have any comment.

Thanks,

thibault

0001-ox-html.el-Add-label-and-number-to-equations-in-HTML.patch
Description: Text Data