Equation references in HTML export

Equation references in HTML export

[Thibault Marin]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: 0001-ox-html.el-Add-MathJax-label-and-reference-to-equati.patch --]
[-- Type: text/x-diff, Size: 9608 bytes --]

From 094df613ec5fd05b6d2124bc45e6f9a8cbef92e5 Mon Sep 17 00:00:00 2001
From: thibault <thibault.marin@gmx.com>
Date: Thu, 4 Jan 2018 21:23:59 -0600
Subject: [PATCH] ox-html.el: Add MathJax label and reference to equations in
 HTML export

* lisp/ox-html.el (org-html-format-latex): Add "\label" to latex
environment as done for latex export.  Add optional input
`latex-environment' to trigger the insertion.
(org-html-latex-environment): Pass unprocessed latex-environment to
`org-html-format-latex' when using MathJax.
(org-html-link): Replace rendering of link from "<a href ...>" to
"\ref{}" for equations when using MathJax.


* lisp/ox-latex.el (org-latex--label): Abstract code constructing the
label id into new function.
(org-latex--label-id): New function to construct the label id (used when
inserting labels for latex or html export).
(org-latex--insert-environment-label): New function to insert label into
buffer containing latex environment string (for use in latex and html
export).
(org-latex-latex-environment): Use new function
`org-latex--insert-environment-label' to insert environment label.
---
 lisp/ox-html.el  | 66 +++++++++++++++++++++++++++++++++++-----------------
 lisp/ox-latex.el | 70 ++++++++++++++++++++++++++++++++------------------------
 2 files changed, 85 insertions(+), 51 deletions(-)

diff --git a/lisp/ox-html.el b/lisp/ox-html.el
index 90a6cede0..b5257653c 100644
--- a/lisp/ox-html.el
+++ b/lisp/ox-html.el
@@ -180,7 +180,9 @@
     (:creator "CREATOR" nil org-html-creator-string)
     (:with-latex nil "tex" org-html-with-latex)
     ;; Retrieve LaTeX header for fragments.
-    (:latex-header "LATEX_HEADER" nil nil newline)))
+    (:latex-header "LATEX_HEADER" nil nil newline)
+    ;; Options for LaTeX environments
+    (:latex-caption-above nil nil org-latex-caption-above)))
 
 \f
 ;;; Internal Variables
@@ -2788,14 +2790,23 @@ CONTENTS is nil.  INFO is a plist holding contextual information."
 
 ;;;; Latex Environment
 
-(defun org-html-format-latex (latex-frag processing-type info)
+(defun org-html-format-latex (latex-frag processing-type info
+					 &optional latex-environment)
   "Format a LaTeX fragment LATEX-FRAG into HTML.
 PROCESSING-TYPE designates the tool used for conversion.  It can
 be `mathjax', `verbatim', nil, t or symbols in
 `org-preview-latex-process-alist', e.g., `dvipng', `dvisvgm' or
 `imagemagick'.  See `org-html-with-latex' for more information.
 INFO is a plist containing export properties."
-  (let ((cache-relpath "") (cache-dir ""))
+  (let* ((cache-relpath "")
+	 (cache-dir "")
+	 (type (when latex-environment
+		 (org-latex--environment-type latex-environment)))
+	 (caption-above-p
+	  (memq type (append (plist-get info :latex-caption-above) '(math))))
+	 (caption (when (and (eq type 'math)
+			     (eq processing-type 'mathjax))
+		    (org-latex--label latex-environment info nil t))))
     (unless (eq processing-type 'mathjax)
       (let ((bfn (or (buffer-file-name)
 		     (make-temp-name
@@ -2819,6 +2830,8 @@ INFO is a plist containing export properties."
 	(setq latex-frag (concat latex-header latex-frag))))
     (with-temp-buffer
       (insert latex-frag)
+      (when (and latex-environment caption)
+	(org-latex--insert-environment-label caption caption-above-p))
       (org-format-latex cache-relpath nil nil cache-dir nil
 			"Creating LaTeX Image..." nil processing-type)
       (buffer-string))))
@@ -2832,7 +2845,8 @@ CONTENTS is nil.  INFO is a plist holding contextual information."
 	(attributes (org-export-read-attribute :attr_html latex-environment)))
     (cond
      ((memq processing-type '(t mathjax))
-      (org-html-format-latex latex-frag 'mathjax info))
+      (org-html-format-latex latex-frag 'mathjax info
+			     latex-environment))
      ((assq processing-type org-preview-latex-process-alist)
       (let ((formula-link
 	     (org-html-format-latex latex-frag processing-type info)))
@@ -3062,23 +3076,33 @@ INFO is a plist holding contextual information.  See
 	     (format "<a href=\"#%s\"%s>%s</a>" href attributes desc)))
 	  ;; Fuzzy link points to a target or an element.
 	  (_
-	   (let* ((ref (org-export-get-reference destination info))
-		  (org-html-standalone-image-predicate
-		   #'org-html--has-caption-p)
-		  (number (cond
-			   (desc nil)
-			   ((org-html-standalone-image-p destination info)
-			    (org-export-get-ordinal
-			     (org-element-map destination 'link
-			       #'identity info t)
-			     info 'link 'org-html-standalone-image-p))
-			   (t (org-export-get-ordinal
-			       destination info nil 'org-html--has-caption-p))))
-		  (desc (cond (desc)
-			      ((not number) "No description for this link")
-			      ((numberp number) (number-to-string number))
-			      (t (mapconcat #'number-to-string number ".")))))
-	     (format "<a href=\"#%s\"%s>%s</a>" ref attributes desc))))))
+	   (let* ((processing-type (plist-get info :with-latex))
+		  (latex-environment destination)
+		  (env-type (when (and latex-environment
+				       (string=
+					(car latex-environment)
+					"latex-environment"))
+			      (org-latex--environment-type latex-environment))))
+	     (if (and (eq env-type 'math) processing-type)
+		 (let ((ref (org-latex--label-id latex-environment info nil)))
+		   (format "\\eqref{%s}" ref))
+	       (let* ((ref (org-export-get-reference destination info))
+		      (org-html-standalone-image-predicate
+		       #'org-html--has-caption-p)
+		      (number (cond
+			       (desc nil)
+			       ((org-html-standalone-image-p destination info)
+				(org-export-get-ordinal
+				 (org-element-map destination 'link
+				   #'identity info t)
+				 info 'link 'org-html-standalone-image-p))
+			       (t (org-export-get-ordinal
+				   destination info nil 'org-html--has-caption-p))))
+		      (desc (cond (desc)
+				  ((not number) "No description for this link")
+				  ((numberp number) (number-to-string number))
+				  (t (mapconcat #'number-to-string number ".")))))
+		 (format "<a href=\"#%s\"%s>%s</a>" ref attributes desc))))))))
      ;; Coderef: replace link with the reference name or the
      ;; equivalent line number.
      ((string= type "coderef")
diff --git a/lisp/ox-latex.el b/lisp/ox-latex.el
index 603bae22f..a57380499 100644
--- a/lisp/ox-latex.el
+++ b/lisp/ox-latex.el
@@ -1244,6 +1244,32 @@ INFO is a plist holding contextual information."
       (let ((type (org-element-type element)))
 	(memq (if (eq type 'link) 'image type) above)))))
 
+(defun org-latex--label-id (datum info &optional force)
+  "Return label for DATUM without \label environment."
+  (let* ((type (org-element-type datum))
+	 (user-label
+	  (org-element-property
+	   (cl-case type
+	     ((headline inlinetask) :CUSTOM_ID)
+	     (target :value)
+	     (otherwise :name))
+	   datum)))
+    (and (or user-label force)
+	 (if (and user-label (plist-get info :latex-prefer-user-labels))
+	     user-label
+	   (concat (cl-case type
+		     (headline "sec:")
+		     (table "tab:")
+		     (latex-environment
+		      (and (string-match-p
+			    org-latex-math-environments-re
+			    (org-element-property :value datum))
+			   "eq:"))
+		     (paragraph
+		      (and (org-element-property :caption datum)
+			   "fig:")))
+		   (org-export-get-reference datum info))))))
+
 (defun org-latex--label (datum info &optional force full)
   "Return an appropriate label for DATUM.
 DATUM is an element or a `target' type object.  INFO is the
@@ -1255,29 +1281,7 @@ this case always return a unique label.
 
 Eventually, if FULL is non-nil, wrap label within \"\\label{}\"."
   (let* ((type (org-element-type datum))
-	 (user-label
-	  (org-element-property
-	   (cl-case type
-	     ((headline inlinetask) :CUSTOM_ID)
-	     (target :value)
-	     (otherwise :name))
-	   datum))
-	 (label
-	  (and (or user-label force)
-	       (if (and user-label (plist-get info :latex-prefer-user-labels))
-		   user-label
-		 (concat (cl-case type
-			   (headline "sec:")
-			   (table "tab:")
-			   (latex-environment
-			    (and (string-match-p
-				  org-latex-math-environments-re
-				  (org-element-property :value datum))
-				 "eq:"))
-			   (paragraph
-			    (and (org-element-property :caption datum)
-				 "fig:")))
-			 (org-export-get-reference datum info))))))
+	 (label (org-latex--label-id datum info force)))
     (cond ((not full) label)
 	  (label (format "\\label{%s}%s"
 			 label
@@ -2280,6 +2284,18 @@ could be a member of `org-latex-caption-above' or `math'."
       'src-block)
      (t 'special-block))))
 
+(defun org-latex--insert-environment-label (label caption-above-p)
+  "Insert LaTeX label LABEL in buffer containing LaTeX environment.
+When CAPTION-ABOVE-P is non nil, the label is added at the
+beginning of the environment.  Otherwise, it is added at the end."
+  (if caption-above-p
+      (progn
+	(goto-char (point-min))
+	(forward-line))
+    (goto-char (point-max))
+    (forward-line -1))
+  (insert label))
+
 (defun org-latex-latex-environment (latex-environment _contents info)
   "Transcode a LATEX-ENVIRONMENT element from Org to LaTeX.
 CONTENTS is nil.  INFO is a plist holding contextual information."
@@ -2301,13 +2317,7 @@ CONTENTS is nil.  INFO is a plist holding contextual information."
 	;; is not a math environment.
 	(with-temp-buffer
 	  (insert value)
-	  (if caption-above-p
-	      (progn
-		(goto-char (point-min))
-		(forward-line))
-	    (goto-char (point-max))
-	    (forward-line -1))
-	  (insert caption)
+	  (org-latex--insert-environment-label caption caption-above-p)
 	  (buffer-string))))))
 
 ;;;; Latex Fragment
-- 
2.15.1


[-- Attachment #2: Type: text/plain, Size: 1142 bytes --]


Hi list,

I am trying to get links to equations to work with HTML export (with Org mode
version 9.1.6 (release_9.1.6-295-ge8cd52 @ /.../org-mode-git/lisp/)).

It currently does not seem to work, as demonstrated by the following example org
file:

#+begin_src org
,#+NAME: eq-test
\begin{align}
1 + 1 = 0
\end{align}

link to equation [[eq-test]]
#+end_src

The relevant part of the resulting HTML is:

#+begin_src html
\begin{align}
1 + 1 = 0
\end{align}

<p>
link to equation <a href="#org0b47727">1</a>
</p>
#+end_src

The =align= block does not have a =label=.  The link could use =\ref= (or
=\eqref=) which is handled by MathJax.  The attached patch attempts to fix
this.  It produces the following (correct?) output:

#+begin_src html
\begin{align}
\label{eq:orgbfedefe}
1 + 1 = 0
\end{align}

<p>
link to equation \eqref{eq:orgbfedefe}
</p>
#+end_src

The patch attempts to re-use functionality from ox-latex.el to avoid code
duplication.  Please let me know if there is a better way to achieve the
same result.

Does this look like something that could eventually be merged?  Let me know if
any change is required.

Thanks,

thibault

Re: Equation references in HTML export

[Nicolas Goaziou]

Hello,

Thibault Marin <thibault.marin@gmx.com> writes:

> From 094df613ec5fd05b6d2124bc45e6f9a8cbef92e5 Mon Sep 17 00:00:00 2001
> From: thibault <thibault.marin@gmx.com>
> Date: Thu, 4 Jan 2018 21:23:59 -0600
> Subject: [PATCH] ox-html.el: Add MathJax label and reference to equations in
>  HTML export

Thank you. Some comments follow.

> * lisp/ox-html.el (org-html-format-latex): Add "\label" to latex
> environment as done for latex export.  Add optional input
> `latex-environment' to trigger the insertion.
> (org-html-latex-environment): Pass unprocessed latex-environment to
> `org-html-format-latex' when using MathJax.
> (org-html-link): Replace rendering of link from "<a href ...>" to
> "\ref{}" for equations when using MathJax.

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?

> * lisp/ox-latex.el (org-latex--label): Abstract code constructing the
> label id into new function.
> (org-latex--label-id): New function to construct the label id (used when
> inserting labels for latex or html export).

If `--' means that the function, or variable, is internal to the library
where it is defined, and should not be used elsewhere. If you intend to
export it into another library, please drop the "--" part.

> (org-latex--insert-environment-label): New function to insert label into
> buffer containing latex environment string (for use in latex and html
> export).

I don't think this function is needed. See below.

> (org-latex-latex-environment): Use new function
> `org-latex--insert-environment-label' to insert environment label.
> ---
>  lisp/ox-html.el  | 66 +++++++++++++++++++++++++++++++++++-----------------
>  lisp/ox-latex.el | 70 ++++++++++++++++++++++++++++++++------------------------
>  2 files changed, 85 insertions(+), 51 deletions(-)
>
> diff --git a/lisp/ox-html.el b/lisp/ox-html.el
> index 90a6cede0..b5257653c 100644
> --- a/lisp/ox-html.el
> +++ b/lisp/ox-html.el
> @@ -180,7 +180,9 @@
>      (:creator "CREATOR" nil org-html-creator-string)
>      (:with-latex nil "tex" org-html-with-latex)
>      ;; Retrieve LaTeX header for fragments.
> -    (:latex-header "LATEX_HEADER" nil nil newline)))
> +    (:latex-header "LATEX_HEADER" nil nil newline)
> +    ;; Options for LaTeX environments
> +    (:latex-caption-above nil nil org-latex-caption-above)))

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'.

WDYT?

>  \f
>  ;;; Internal Variables
> @@ -2788,14 +2790,23 @@ CONTENTS is nil.  INFO is a plist holding contextual information."
>  
>  ;;;; Latex Environment
>  
> -(defun org-html-format-latex (latex-frag processing-type info)
> +(defun org-html-format-latex (latex-frag processing-type info
> +					 &optional latex-environment)
>    "Format a LaTeX fragment LATEX-FRAG into HTML.
>  PROCESSING-TYPE designates the tool used for conversion.  It can
>  be `mathjax', `verbatim', nil, t or symbols in
>  `org-preview-latex-process-alist', e.g., `dvipng', `dvisvgm' or
>  `imagemagick'.  See `org-html-with-latex' for more information.
>  INFO is a plist containing export properties."

LATEX-ARGUMENT needs to be documented in the docstring.

> +	 (type (when latex-environment
> +		 (org-latex--environment-type latex-environment)))

Nitpick:

  (and latex-environment
       (or-latex--environment-type ...))

> +	 (caption-above-p

Nitpick:

  caption-above-p -> caption-above?

Also, instead of (append ... '(math)), use

 (cons 'math ...)

This is strange BTW, because `math' is not a valid value for
`org-latex-caption-above', and when TYPE is not `math', no caption is
defined (per the first `and' branch), so CAPTION-ABOVE? doesn't make any
sense.

> +	  (memq type (append (plist-get info :latex-caption-above) '(math))))
> +	 (caption (when (and (eq type 'math)
> +			     (eq processing-type 'mathjax))
> +		    (org-latex--label latex-environment info nil t))))

  (and (eq type 'math)
       (eq processing-type 'mathjax)
       (org-latex--label ...))

Since CAPTION-ABOVE? depends on CAPTION, I suggest to define them the
other way around:

  (caption (and (eq type 'math)
                (eq processing-type 'mathjax)
                (org-latex--label ...)))
  (caption-above?
           (and caption
                (memq type (cons 'math 
                                 (plist-get info :latex-caption-above)))))

>      (with-temp-buffer
>        (insert latex-frag)
> +      (when (and latex-environment caption)
> +	(org-latex--insert-environment-label caption caption-above-p))

No need for `org-latex--insert-environment-label':

  (with-temp-buffer
    (when caption-above? (insert caption "\n"))
    (insert latex-frag)
    (when (and caption (not caption-above?)) (insert caption "\n"))
    (org-format-latex ...))

> +	   (let* ((processing-type (plist-get info :with-latex))
> +		  (latex-environment destination)
> +		  (env-type (when (and latex-environment
> +				       (string=
> +					(car latex-environment)
> +					"latex-environment"))
> +			      (org-latex--environment-type latex-environment))))
> +	     (if (and (eq env-type 'math) processing-type)
> +		 (let ((ref (org-latex--label-id latex-environment info nil)))
> +		   (format "\\eqref{%s}" ref))

Again, you are not supposed to use "org-latex--" in "ox-html.el". Also,
please consider the following refactoring:

  (if (and destination
           (plist-get info :with-latex)
           (eq 'latex-environment (org-element-type destination))
           (eq 'math (org-latex--environment-type destination)))
      ;; Caption and labels are introduced within LaTeX environment. Use
      ;; "eqref" macro to refer to those in the document.
      (format "\\eqref{%s}"
              (org-latex--label-id latex-environment info nil))

Note you don't check if `:with-latex' is specifically `mathjax'.

> +(defun org-latex--insert-environment-label (label caption-above-p)
> +  "Insert LaTeX label LABEL in buffer containing LaTeX environment.
> +When CAPTION-ABOVE-P is non nil, the label is added at the
> +beginning of the environment.  Otherwise, it is added at the end."
> +  (if caption-above-p
> +      (progn
> +	(goto-char (point-min))
> +	(forward-line))
> +    (goto-char (point-max))
> +    (forward-line -1))
> +  (insert label))
> +
>  (defun org-latex-latex-environment (latex-environment _contents info)
>    "Transcode a LATEX-ENVIRONMENT element from Org to LaTeX.
>  CONTENTS is nil.  INFO is a plist holding contextual information."
> @@ -2301,13 +2317,7 @@ CONTENTS is nil.  INFO is a plist holding contextual information."
>  	;; is not a math environment.
>  	(with-temp-buffer
>  	  (insert value)
> -	  (if caption-above-p
> -	      (progn
> -		(goto-char (point-min))
> -		(forward-line))
> -	    (goto-char (point-max))
> -	    (forward-line -1))
> -	  (insert caption)
> +	  (org-latex--insert-environment-label caption caption-above-p)

See above. I think we can drop `org-latex--insert-environment-label',
and use again the two lines I suggested above.

Regards,

-- 
Nicolas Goaziou

Re: Equation references in HTML export

[Thibault Marin]

[-- 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

Re: Equation references in HTML export

[Nicolas Goaziou]

Hello,

Thibault Marin <thibault.marin@gmx.com> writes:

> 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?

That's the idea, yes.

> 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?

I'm not sure. Have you checked how captions in other parts of
"ox-html.el"?

> 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.

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.

> 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)?

I don't think other captions allow this in "ox-html.el".

WDYT?

Regards,

-- 
Nicolas Goaziou                                                0x80A93738

Re: Equation references in HTML export

[Thibault Marin]

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


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

[-- 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: 9156 bytes --]

From 70f6e350615922007e08eec7deecdcdeadd0dc04 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 (non-MathJax modes).  Make latex
environment unnumbered when compiling equations to images.  Insert latex
label in environment in MathJax mode.
(org-html-link): Calculate equation number limiting counter to equation
environments.  Use eqref for link when using MathJax
(org-html--make-unlabelled-latex-environment): New function to convert
latex math environments to unnumbered versions (e.g. "equation" ->
"equation*").
(org-html--insert-latex-environment-label): Insert latex \label inside
environment.
---
 lisp/ox-html.el | 136 +++++++++++++++++++++++++++++++++++++++++++++-----------
 1 file changed, 109 insertions(+), 27 deletions(-)

diff --git a/lisp/ox-html.el b/lisp/ox-html.el
index a3a7c5f92..0bb3eff0e 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,26 +2835,84 @@ 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--make-unlabelled-latex-environment (latex-frag)
+  "Change environment in LATEX-FRAG to an unnumbered environment.
+For instance, change an 'equation' environment to 'equation*'."
+  (let* ((lines (split-string latex-frag "\n" t))
+         (last-idx (- (length lines) 1)))
+    (setf (nth 0 lines) (replace-regexp-in-string
+                         "^\\([\n\s]*\\)\\\\begin{\\([^*}]+\\)}"
+                         "\\1\\\\begin{\\2*}" (nth 0 lines)))
+    (setf (nth last-idx lines) (replace-regexp-in-string
+                                "\\\\end{\\([^*}]+\\)}\\([\n\s]*\\)$"
+                                "\\\\end{\\1*}\\2" (nth last-idx lines)))
+    (mapconcat #'identity lines "\n")))
+
+(defun org-html--insert-latex-environment-label (label latex-frag)
+  "Insert LABEL inside LATEX-FRAG."
+  (if (org-string-nw-p label)
+      (with-temp-buffer
+	(insert latex-frag)
+	(goto-char (point-min))
+	(forward-line)
+	(insert (format "\\label{%s}\n" label))
+	(buffer-string))
+    latex-frag))
+
 (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-format-latex
+       (org-html--insert-latex-environment-label label latex-frag)
+       'mathjax info))
      ((assq processing-type org-preview-latex-process-alist)
       (let ((formula-link
-	     (org-html-format-latex latex-frag processing-type info)))
-	(when (and formula-link (string-match "file:\\([^]]*\\)" formula-link))
-	  ;; Do not provide a caption or a name to be consistent with
-	  ;; `mathjax' handling.
-	  (org-html--wrap-image
-	   (org-html--format-image
-	    (match-string 1 formula-link) attributes info) info))))
-     (t latex-frag))))
+             (org-html-format-latex
+              (org-html--make-unlabelled-latex-environment latex-frag)
+              processing-type info)))
+        (when (and formula-link (string-match "file:\\([^]]*\\)" formula-link))
+          (org-html--wrap-latex-environment
+           (org-html--format-image
+            (match-string 1 formula-link) attributes info)
+           info caption label))))
+     (t (org-html--wrap-latex-environment latex-frag info caption label)))))
 
 ;;;; Latex Fragment
 
@@ -3062,23 +3132,35 @@ INFO is a plist holding contextual information.  See
 	     (format "<a href=\"#%s\"%s>%s</a>" href attributes desc)))
 	  ;; Fuzzy link points to a target or an element.
 	  (_
-	   (let* ((ref (org-export-get-reference destination info))
-		  (org-html-standalone-image-predicate
-		   #'org-html--has-caption-p)
-		  (number (cond
-			   (desc nil)
-			   ((org-html-standalone-image-p destination info)
-			    (org-export-get-ordinal
-			     (org-element-map destination 'link
-			       #'identity info t)
-			     info 'link 'org-html-standalone-image-p))
-			   (t (org-export-get-ordinal
-			       destination info nil 'org-html--has-caption-p))))
-		  (desc (cond (desc)
-			      ((not number) "No description for this link")
-			      ((numberp number) (number-to-string number))
-			      (t (mapconcat #'number-to-string number ".")))))
-	     (format "<a href=\"#%s\"%s>%s</a>" ref attributes desc))))))
+           (if (and destination
+                    (memq (plist-get info :with-latex) '(mathjax t))
+                    (eq 'latex-environment (org-element-type destination))
+                    (eq 'math (org-latex--environment-type destination)))
+               ;; Caption and labels are introduced within LaTeX environment. Use
+               ;; "eqref" macro to refer to those in the document.
+               (format "\\eqref{%s}"
+                       (org-export-get-reference destination info))
+             (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)
+                              (org-export-get-ordinal
+                               (org-element-map destination 'link
+                                 #'identity info t)
+                               info 'link 'org-html-standalone-image-p))
+                             (t (org-export-get-ordinal
+                                 destination info nil ordinal-counter-predicate))))
+                    (desc (cond (desc)
+                                ((not number) "No description for this link")
+                                ((numberp number) (number-to-string number))
+                                (t (mapconcat #'number-to-string number ".")))))
+               (format "<a href=\"#%s\"%s>%s</a>" ref attributes desc)))))))
      ;; Coderef: replace link with the reference name or the
      ;; equivalent line number.
      ((string= type "coderef")
-- 
2.15.1

Re: Equation references in HTML export

[Nicolas Goaziou]

Hello,

Thibault Marin <thibault.marin@gmx.com> writes:

>> 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.

It looks good. Thank you.

> 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.

As a first step, it sounds acceptable, indeed. However, I assume it
would be useful to make all approaches converge on a single solution.

> 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.

OK.

> 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?

I guess so. OTOH, I assume latex environments are always math
environments. One can use LaTex export blocks for "regular" LaTeX.

Nitpick: since this is a predicate, it should be named
`org-html--math-environment-p'.

> - 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?

No idea. I hope a LaTeX expert can chime it.

Meanwhile, I think the implementation is a bit convoluted. What about
the following?

    (replace-regexp-in-string
     "\\`[ \t]*\\\\begin{\\([^*]+?\\)}"
     "\\1*"
     (replace-regexp-in-string "^[ \t]*\\\\end{\\([^*]+?\\)}[ \r\t\n]*\\'"
                               "\\1*"
                               latex-frag nil nil 1)
     nil nil 1)

> - 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?

IMO, this doesn't deserve to be a function, you can just use something
like this:

    (if (org-string-nw-p label)
        (replace-regexp-in-string "\\`.*"
                                  (format "\\&\n\\\\label{%s}" label)
                                  latex-frag)
      latex-frag)

> - 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.

IIUC, so far, Mathjax doesn't provide any caption, neither does dvipng.

> - 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?

They are not a priority. Bugs in export back-ends are usually visible
enough. Anyway this doesn't mean you cannot write some tests. Tests are
nice. However they are not mandatory in this case.

Regards,

-- 
Nicolas Goaziou                                                0x80A93738

Re: Equation references in HTML export

[Thibault Marin]

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


Hi, thanks for the review.  Please find attached an updated patch.

> I guess so. OTOH, I assume latex environments are always math
> environments. One can use LaTex export blocks for "regular" LaTeX.
I left the math check in the attached patch for now.  Please let me know
if you would like me to remove it.

> Nitpick: since this is a predicate, it should be named
> `org-html--math-environment-p'.
Done.

> Meanwhile, I think the implementation is a bit convoluted. What about
> the following?
>
>     (replace-regexp-in-string
>      "\\`[ \t]*\\\\begin{\\([^*]+?\\)}"
>      "\\1*"
>      (replace-regexp-in-string "^[ \t]*\\\\end{\\([^*]+?\\)}[ \r\t\n]*\\'"
>                                "\\1*"
>                                latex-frag nil nil 1)
>      nil nil 1)
Done.

> IMO, this doesn't deserve to be a function, you can just use something
> like this:
>
>     (if (org-string-nw-p label)
>         (replace-regexp-in-string "\\`.*"
>                                   (format "\\&\n\\\\label{%s}" label)
>                                   latex-frag)
>       latex-frag)
Done.

Thanks,

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: 8577 bytes --]

From c600a62d67decf957e9170cf9f055915bdfae05a 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--math-environment-p): 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 (non-MathJax modes).  Make latex
environment unnumbered when compiling equations to images.  Insert latex
label in environment in MathJax mode.
(org-html-link): Calculate equation number limiting counter to equation
environments.  Use eqref for link when using MathJax
(org-html--make-unlabelled-latex-environment): New function to convert
latex math environments to unnumbered versions (e.g. "equation" ->
"equation*").
---
 lisp/ox-html.el | 128 ++++++++++++++++++++++++++++++++++++++++++++------------
 1 file changed, 101 insertions(+), 27 deletions(-)

diff --git a/lisp/ox-html.el b/lisp/ox-html.el
index d242c613c..7b7d52141 100644
--- a/lisp/ox-html.el
+++ b/lisp/ox-html.el
@@ -430,6 +430,19 @@ 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;
+    vertical-align: middle;
+  }
   .inlinetask {
     padding: 10px;
     border: 2px solid gray;
@@ -2823,26 +2836,75 @@ 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--math-environment-p (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--make-unlabelled-latex-environment (latex-frag)
+  "Change environment in LATEX-FRAG to an unnumbered environment.
+For instance, change an 'equation' environment to 'equation*'."
+  (replace-regexp-in-string
+   "\\`[ \t]*\\\\begin{\\([^*]+?\\)}"
+   "\\1*"
+   (replace-regexp-in-string "^[ \t]*\\\\end{\\([^*]+?\\)}[ \r\t\n]*\\'"
+			     "\\1*"
+			     latex-frag nil nil 1)
+   nil nil 1))
+
 (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--math-environment-p))))
     (cond
      ((memq processing-type '(t mathjax))
-      (org-html-format-latex latex-frag 'mathjax info))
+      (org-html-format-latex
+       (if (org-string-nw-p label)
+	   (replace-regexp-in-string "\\`.*"
+				     (format "\\&\n\\\\label{%s}" label)
+				     latex-frag)
+	 latex-frag)
+       'mathjax info))
      ((assq processing-type org-preview-latex-process-alist)
       (let ((formula-link
-	     (org-html-format-latex latex-frag processing-type info)))
-	(when (and formula-link (string-match "file:\\([^]]*\\)" formula-link))
-	  ;; Do not provide a caption or a name to be consistent with
-	  ;; `mathjax' handling.
-	  (org-html--wrap-image
-	   (org-html--format-image
-	    (match-string 1 formula-link) attributes info) info))))
-     (t latex-frag))))
+             (org-html-format-latex
+              (org-html--make-unlabelled-latex-environment latex-frag)
+              processing-type info)))
+        (when (and formula-link (string-match "file:\\([^]]*\\)" formula-link))
+          (org-html--wrap-latex-environment
+           (org-html--format-image
+            (match-string 1 formula-link) attributes info)
+           info caption label))))
+     (t (org-html--wrap-latex-environment latex-frag info caption label)))))
 
 ;;;; Latex Fragment
 
@@ -3062,23 +3124,35 @@ INFO is a plist holding contextual information.  See
 	     (format "<a href=\"#%s\"%s>%s</a>" href attributes desc)))
 	  ;; Fuzzy link points to a target or an element.
 	  (_
-	   (let* ((ref (org-export-get-reference destination info))
-		  (org-html-standalone-image-predicate
-		   #'org-html--has-caption-p)
-		  (number (cond
-			   (desc nil)
-			   ((org-html-standalone-image-p destination info)
-			    (org-export-get-ordinal
-			     (org-element-map destination 'link
-			       #'identity info t)
-			     info 'link 'org-html-standalone-image-p))
-			   (t (org-export-get-ordinal
-			       destination info nil 'org-html--has-caption-p))))
-		  (desc (cond (desc)
-			      ((not number) "No description for this link")
-			      ((numberp number) (number-to-string number))
-			      (t (mapconcat #'number-to-string number ".")))))
-	     (format "<a href=\"#%s\"%s>%s</a>" ref attributes desc))))))
+           (if (and destination
+                    (memq (plist-get info :with-latex) '(mathjax t))
+                    (eq 'latex-environment (org-element-type destination))
+                    (eq 'math (org-latex--environment-type destination)))
+               ;; Caption and labels are introduced within LaTeX environment. Use
+               ;; "eqref" macro to refer to those in the document.
+               (format "\\eqref{%s}"
+                       (org-export-get-reference destination info))
+             (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--math-environment-p
+                       #'org-html--has-caption-p))
+                    (number (cond
+                             (desc nil)
+                             ((org-html-standalone-image-p destination info)
+                              (org-export-get-ordinal
+                               (org-element-map destination 'link
+                                 #'identity info t)
+                               info 'link 'org-html-standalone-image-p))
+                             (t (org-export-get-ordinal
+                                 destination info nil ordinal-counter-predicate))))
+                    (desc (cond (desc)
+                                ((not number) "No description for this link")
+                                ((numberp number) (number-to-string number))
+                                (t (mapconcat #'number-to-string number ".")))))
+               (format "<a href=\"#%s\"%s>%s</a>" ref attributes desc)))))))
      ;; Coderef: replace link with the reference name or the
      ;; equivalent line number.
      ((string= type "coderef")
-- 
2.15.1

Re: Equation references in HTML export

[Nicolas Goaziou]

Hello,

Thibault Marin <thibault.marin@gmx.com> writes:

> I left the math check in the attached patch for now.  Please let me know
> if you would like me to remove it.

I have no strong opinion about it. For the time being we can keep it,
and remove it later if it ever gets in the way.

I applied your patch. Thank you.

Could you write a short entry in ORG-NEWS to advertise it?

Regards,

-- 
Nicolas Goaziou

Re: Equation references in HTML export

[Thibault Marin]

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


Nicolas Goaziou writes:
> Could you write a short entry in ORG-NEWS to advertise it?
Done in the attached patch.

Thanks


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-ORG-NEWS-Add-note-about-links-to-equations-in-HTML-e.patch --]
[-- Type: text/x-diff, Size: 894 bytes --]

From 7c59f34ccd19278f10be399645f641b791e7f41b Mon Sep 17 00:00:00 2001
From: thibault <thibault.marin@gmx.com>
Date: Wed, 17 Jan 2018 21:08:59 -0600
Subject: [PATCH] ORG-NEWS: Add note about links to equations in HTML export

---
 etc/ORG-NEWS | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/etc/ORG-NEWS b/etc/ORG-NEWS
index 67f51401f..5ebfe4e8c 100644
--- a/etc/ORG-NEWS
+++ b/etc/ORG-NEWS
@@ -102,6 +102,9 @@ document, use =shrink= value instead, or in addition to align:
 #+END_EXAMPLE
 
 ** New features
+*** Add support for links to LaTeX equations in HTML export
+Use MathJax links when enabled (by ~org-html-with-latex~), otherwise
+add a label to the rendered equation.
 *** Org Tempo may used for snippet expansion of structure template.
 See manual and the commentary section in ~org-tempo.el~ for details.
 *** Exclude unnumbered headlines from table of contents
-- 
2.15.1

Re: Equation references in HTML export

[Nicolas Goaziou]

Hello,

Thibault Marin <thibault.marin@gmx.com> writes:

> Nicolas Goaziou writes:
>> Could you write a short entry in ORG-NEWS to advertise it?
> Done in the attached patch.

Applied. Thank you.

Regards,

-- 
Nicolas Goaziou                                                0x80A93738

Re: Equation references in HTML export

[Eric S Fraga]

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

On Tuesday, 16 Jan 2018 at 19:09, Nicolas Goaziou wrote:
> Thibault Marin <thibault.marin@gmx.com> writes:

[...]

>> - 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?
>
> No idea. I hope a LaTeX expert can chime it.

Not an expert but I can chime in anyway. :-)

To avoid having to hack the code, you could try using the mathtools
package and ask it to only number equations that are referenced:

    \usepackage{mathtools}  
    \mathtoolsset{showonlyrefs}  

This goes in the preamble for processing the snippets.

Untested.

-- 
Eric S Fraga via Emacs 27.0.50, Org release_9.1.6-317-gc82c21

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 194 bytes --]

Re: Equation references in HTML export

[Thibault Marin]

> To avoid having to hack the code, you could try using the mathtools
> package and ask it to only number equations that are referenced:
>
>     \usepackage{mathtools}  
>     \mathtoolsset{showonlyrefs}  

Thanks, if there is a mechanism to alter the preamble when creating the
image, that may be a preferable approach.  I'll try to look into this.

Re: Equation references in HTML export

[Eric S Fraga]

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

On Thursday, 18 Jan 2018 at 22:09, Thibault Marin wrote:
> Thanks, if there is a mechanism to alter the preamble when creating the
> image, that may be a preferable approach.  I'll try to look into this.

Have a look at org-format-latex-header.

-- 
Eric S Fraga via Emacs 27.0.50, Org release_9.1.6-352-g92176c

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 194 bytes --]