Re: Equation references in HTML export

[Thibault Marin <thibault.marin@gmx.com>]

[-- Attachment #1: Type: text/plain, Size: 3142 bytes --]


Hi, thank you for the review.

> I'm not convinced that inserting label and, more importantly,
> caption within the environment is the way to go. For example, that
> will not work when `org-html-with-latex' is set `verbatim'. Couldn't
> we simply wrap a HTML label and caption above, or below, the whole
> environment so it DTRT in all cases?

It is true that my patch did not address the verbatim mode, I was
focusing on the MathJax output.  The reason I initially decided to rely
on MathJax is that I thought it would be better to take advantage of
MathJax support for LaTeX label and references.  It was then sufficient
to delegate rendering of the latex-environment and links to ox-latex,
although I ended with some unpleasant code to achieve that.

To make sure I understand the desired HTML output, do you mean that
instead of producing this HTML:
,----
| \begin{align}
| \label{eq:orgbfedefe}
| 1 + 1 = 0
| \end{align}
`----
and relying on MathJax to manage references, we should produce something
like the following?
,----
| <div id="orgbfedefe" class="equation-container">
| \begin{align}
| 1 + 1 = 0
| \end{align}
| <!-- insert the equation number -->
| </div>
`----

Am I understanding correctly?

The advantage of this approach is that it is consistent with how the
other types of references (figures, source blocks, etc.) are managed and
it should work with the verbatim mode.

I have a few questions about the "caption" (i.e. the equation number):

1. Where should it be placed?  In a `<span>' tag like it is done for
   figures?  Ideally, I would like to have the caption (i.e. the
   equation number) on the right side of the equation, as it is done in
   LaTeX, should this be done with CSS?  Should there be a user option
   for the position of the caption?
2. Should we disable MathJax's equation numbering and replace it with
   ours?  I am afraid this may break the setup of users already relying
   on MathJax to label and reference equations.
3. Should there be an option to customize the formatting of the equation
   number, both on the right of the equation itself and in links
   (e.g. wrap the number between parentheses, as `\eqref' dose)?

The attached patch tries to implement some version of this approach.
The code looks less hackish to me, but I still rely on a variable
external to ox-html.el: I use `org-latex-math-environments-re' to
determine if the LaTeX block is a math block; this is used to limit
counters to equations environments, ignoring other types of latex
environments.  Also note that I did not disable MathJax auto-numbering
in the attached patch, so equations have two numbers.

My main concern with this revised version of the patch is the possible
conflicts between MathJax and org equation numbers:
- Only one equation number should be shown, and MathJax and org counters
  may not match (e.g. with multiline equations).
- If we disable MathJax auto-numbering, it seems that we would be losing
  the possibility to have labels on individual lines of multiline
  equations.  Is it true?

Please let me know how you would like me to move forward with this.

Thanks in advance.

thibault


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-ox-html.el-Add-label-and-number-to-equations-in-HTML.patch --]
[-- Type: text/x-diff, Size: 5253 bytes --]

From 4f57de3208bfe7a86f17c89c15fdc99283701e82 Mon Sep 17 00:00:00 2001
From: thibault <thibault.marin@gmx.com>
Date: Sun, 7 Jan 2018 03:04:39 -0600
Subject: [PATCH] ox-html.el: Add label and number to equations in HTML export

* lisp/ox-html.el (org-html--wrap-latex-environment): New function
wrapping the content of latex environments in HTML <div> tags, adding
"id" and equation number.
(org-html--is-math-environment): New function determining if a latex
environment is a math environment.
(org-html-latex-environment): Use `org-html--wrap-latex-environment' to
wrap equation in HTML container.
(org-html-link): Calculate equation number limiting counter to equation
environments.
---
 lisp/ox-html.el | 57 +++++++++++++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 53 insertions(+), 4 deletions(-)

diff --git a/lisp/ox-html.el b/lisp/ox-html.el
index 90a6cede0..566f057ac 100644
--- a/lisp/ox-html.el
+++ b/lisp/ox-html.el
@@ -430,6 +430,18 @@ for the JavaScript code in this tag.
   .footdef  { margin-bottom: 1em; }
   .figure { padding: 1em; }
   .figure p { text-align: center; }
+  .equation-container {
+    display: table;
+    text-align: center;
+    width: 100%;
+  }
+  .equation {
+    vertical-align: middle;
+  }
+  .equation-label {
+    display: table-cell;
+    text-align: right;
+  }
   .inlinetask {
     padding: 10px;
     border: 2px solid gray;
@@ -2823,16 +2835,49 @@ INFO is a plist containing export properties."
 			"Creating LaTeX Image..." nil processing-type)
       (buffer-string))))
 
+(defun org-html--wrap-latex-environment (contents info &optional caption label)
+  "Wrap CONTENTS string within appropriate environment for equations.
+INFO is a plist used as a communication channel.  When optional
+arguments CAPTION and LABEL are given, use them for caption and
+\"id\" attribute."
+  (format "\n<div%s class=\"equation-container\">\n%s%s\n</div>"
+          ;; ID.
+          (if (org-string-nw-p label) (format " id=\"%s\"" label) "")
+          ;; Contents.
+          (format "<span class=\"equation\">\n%s\n</span>" contents)
+          ;; Caption.
+          (if (not (org-string-nw-p caption)) ""
+            (format "\n<span class=\"equation-label\">\n%s\n</span>"
+                    caption))))
+
+(defun org-html--is-math-environment (element &optional info)
+  "Non-nil when ELEMENT is a LaTeX math environment.
+Math environments match the regular expression defined in
+`org-latex-math-environments-re'.
+INFO is a plist used as a communication channel.  This function
+is meant to be used as a predicate for `org-export-get-ordinal' or
+a value to `org-html-standalone-image-predicate'."
+  (string-match-p org-latex-math-environments-re
+                  (org-element-property :value element)))
+
 (defun org-html-latex-environment (latex-environment _contents info)
   "Transcode a LATEX-ENVIRONMENT element from Org to HTML.
 CONTENTS is nil.  INFO is a plist holding contextual information."
   (let ((processing-type (plist-get info :with-latex))
 	(latex-frag (org-remove-indentation
 		     (org-element-property :value latex-environment)))
-	(attributes (org-export-read-attribute :attr_html latex-environment)))
+	(attributes (org-export-read-attribute :attr_html latex-environment))
+        (label (and (org-element-property :name latex-environment)
+                    (org-export-get-reference latex-environment info)))
+        (caption (number-to-string
+                  (org-export-get-ordinal
+                   latex-environment info nil
+                   #'org-html--is-math-environment))))
     (cond
      ((memq processing-type '(t mathjax))
-      (org-html-format-latex latex-frag 'mathjax info))
+      (org-html--wrap-latex-environment
+       (org-html-format-latex latex-frag 'mathjax info)
+       info caption label))
      ((assq processing-type org-preview-latex-process-alist)
       (let ((formula-link
 	     (org-html-format-latex latex-frag processing-type info)))
@@ -2842,7 +2887,7 @@ CONTENTS is nil.  INFO is a plist holding contextual information."
 	  (org-html--wrap-image
 	   (org-html--format-image
 	    (match-string 1 formula-link) attributes info) info))))
-     (t latex-frag))))
+     (t (org-html--wrap-latex-environment latex-frag info caption label)))))
 
 ;;;; Latex Fragment
 
@@ -3065,6 +3110,10 @@ INFO is a plist holding contextual information.  See
 	   (let* ((ref (org-export-get-reference destination info))
 		  (org-html-standalone-image-predicate
 		   #'org-html--has-caption-p)
+		  (ordinal-counter-predicate
+		   (if (string= (car destination) "latex-environment")
+		       #'org-html--is-math-environment
+		     #'org-html--has-caption-p))
 		  (number (cond
 			   (desc nil)
 			   ((org-html-standalone-image-p destination info)
@@ -3073,7 +3122,7 @@ INFO is a plist holding contextual information.  See
 			       #'identity info t)
 			     info 'link 'org-html-standalone-image-p))
 			   (t (org-export-get-ordinal
-			       destination info nil 'org-html--has-caption-p))))
+			       destination info nil ordinal-counter-predicate))))
 		  (desc (cond (desc)
 			      ((not number) "No description for this link")
 			      ((numberp number) (number-to-string number))
-- 
2.15.1