Inconsistent use of \ref and \eqref in ox-latex and ox-html

Inconsistent use of \ref and \eqref in ox-latex and ox-html

[Brian Powell]

This topic was discussed in 2015:

<https://lists.gnu.org/archive/html/emacs-orgmode/2015-02/msg00527.html>

However, it seems that it we are still stuck with inconsistent exports between latex and HTML.

The issue is that when exporting equation numbers with ox-html, it uses MathJax's \eqref that wraps the equation in parentheses, for example:

"Refer to (3) for more."

However, when exporting the same document with ox-latex, it uses Latex's \ref that does not wrap the equation in parentheses. Would it be possible to add an option or variable to ox-html for the user to select whether to use \ref or \eqref on export? 

For those of us that publish to HTML and PDF, it is very difficult because you end up with either double or no parentheses.

My proposed fix would be a change to ox-html from:

               (format "\\eqref{%s}"
                       (org-export-get-reference destination info))

to

               (format (if org-html-export-mathjax-ref "\\ref{%s}" "\\eqref{%s}")
                       (org-export-get-reference destination info))

The variable org-html-export-mathjax-ref is non-nil to use \ref vs. nil to be the default \eqref.

Cheers, 
Brian	
	

Re: Inconsistent use of \ref and \eqref in ox-latex and ox-html

[Nicolas Goaziou]

Hello,

Brian Powell <powellb@hawaii.edu> writes:

> The issue is that when exporting equation numbers with ox-html, it uses MathJax's \eqref that wraps the equation in parentheses, for example:
>
> "Refer to (3) for more."
>
> However, when exporting the same document with ox-latex, it uses Latex's \ref that does not wrap the equation in parentheses. Would it be possible to add an option or variable to ox-html for the user to select whether to use \ref or \eqref on export? 
>
> For those of us that publish to HTML and PDF, it is very difficult because you end up with either double or no parentheses.
>
> My proposed fix would be a change to ox-html from:
>
>                (format "\\eqref{%s}"
>                        (org-export-get-reference destination info))
>
> to
>
>                (format (if org-html-export-mathjax-ref "\\ref{%s}" "\\eqref{%s}")
>                        (org-export-get-reference destination info))
>
> The variable org-html-export-mathjax-ref is non-nil to use \ref vs.
> nil to be the default \eqref.

The variable could be more general, e.g.,
org-html-export-equation-reference-format, and default to "\\ref{%s}".
Note the export back-ends do not use variables directly. It would be

  (format (plist-get info :html-equation-reference-format)
          (org-export-get-reference destination info))

where the correspondence between :html-equation-reference-format is set
in back-end definition.

Also, it needs to be referenced in "HTML specific properties" section of
the manual.

Would you want to propose a patch ?

Regards,

-- 
Nicolas Goaziou

Re: Inconsistent use of \ref and \eqref in ox-latex and ox-html

[Brian Powell]

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

Nicolas,

Thank you for the message. I spent about 2 hours on it today learning more about lisp and the internals to explain your email to me. I learned a lot.

I have modified ox-html.el to include a local OPTION as well as a customizable setting. I tested with both as well as with an export option. All three worked correctly. I also updated the org-manual.org.

Please find my patch attached.

Cheers,
Brian



[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: equation-ref.diff --]
[-- Type: text/x-patch, Size: 3147 bytes --]

diff --git a/doc/org-manual.org b/doc/org-manual.org
index 6d5a34e56..69a36d6c7 100644
--- a/doc/org-manual.org
+++ b/doc/org-manual.org
@@ -12531,6 +12531,15 @@ settings described in [[*Export Settings]].
   to typeset LaTeX math in HTML documents.  See [[*Math formatting in
   HTML export]], for an example.
 
+- =HTML_EQUATION_REFERENCE_FORMAT= ::
+
+  #+cindex: @samp{HTML_EQUATION_REFERENCE_FORMAT}, keyword
+  #+vindex: org-html-equation-reference-format
+  Specify the MathJax command for referencing equations
+  (~org-html-equation-reference-format~). The default is to wrap in
+  parentheses using "\\eqref{%s}". Setting to "\\ref{%s}" is consistent
+  with LaTeX export.
+
 - =HTML_HEAD= ::
 
   #+cindex: @samp{HTML_HEAD}, keyword
@@ -12898,6 +12907,9 @@ files.  This method requires that the dvipng program, dvisvgm or
 ImageMagick suite is available on your system.  You can still get this
 processing with
 
+The command for formatting equation references can be configured via
+~org-html-equation-reference-format~.
+
 : #+OPTIONS: tex:dvipng
 
 : #+OPTIONS: tex:dvisvgm
diff --git a/lisp/ox-html.el b/lisp/ox-html.el
index e70b8279b..4848028a2 100644
--- a/lisp/ox-html.el
+++ b/lisp/ox-html.el
@@ -121,6 +121,7 @@
     (:html-link-home "HTML_LINK_HOME" nil org-html-link-home)
     (:html-link-up "HTML_LINK_UP" nil org-html-link-up)
     (:html-mathjax "HTML_MATHJAX" nil "" space)
+    (:html-equation-reference-format "HTML_EQUATION_REFERENCE_FORMAT" nil org-html-equation-reference-format t)
     (:html-postamble nil "html-postamble" org-html-postamble)
     (:html-preamble nil "html-preamble" org-html-preamble)
     (:html-head "HTML_HEAD" nil org-html-head newline)
@@ -761,6 +762,20 @@ The function should return the string to be exported."
 
 ;;;; LaTeX
 
+(defcustom org-html-equation-reference-format "\\eqref{%s}"
+  "MathJax command to use when referencing equations.
+
+Default is to wrap equations in parentheses (using \"\\eqref{%s}\)\".
+
+Most common values are:
+
+  \"\\eqref{%s}\"    Wrap the equation in parentheses
+  \"\\ref{%s}\"      Do not wrap the equation in parentheses"
+  :group 'org-export-html
+  :package-version '(Org . "9.3")
+  :type 'string
+  :safe t)
+
 (defcustom org-html-with-latex org-export-with-latex
   "Non-nil means process LaTeX math snippets.
 
@@ -3113,9 +3128,9 @@ INFO is a plist holding contextual information.  See
                     (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}"
+	       ;; environment.  Use "ref" or "eqref" macro, depending on user
+               ;; preference to refer to those in the document.
+               (format (plist-get info :html-equation-reference-format)
                        (org-export-get-reference destination info))
              (let* ((ref (org-export-get-reference destination info))
                     (org-html-standalone-image-predicate

[-- Attachment #3: Type: text/plain, Size: 1670 bytes --]




On Fri, Apr 17 2020, Nicolas Goaziou wrote:

> Hello,
>
> Brian Powell <powellb@hawaii.edu> writes:
>
>> The issue is that when exporting equation numbers with ox-html, it uses MathJax's \eqref that wraps the equation in parentheses, for example:
>>
>> "Refer to (3) for more."
>>
>> However, when exporting the same document with ox-latex, it uses Latex's \ref that does not wrap the equation in parentheses. Would it be possible to add an option or variable to ox-html for the user to select whether to use \ref or \eqref on export?
>>
>> For those of us that publish to HTML and PDF, it is very difficult because you end up with either double or no parentheses.
>>
>> My proposed fix would be a change to ox-html from:
>>
>>                (format "\\eqref{%s}"
>>                        (org-export-get-reference destination info))
>>
>> to
>>
>>                (format (if org-html-export-mathjax-ref "\\ref{%s}" "\\eqref{%s}")
>>                        (org-export-get-reference destination info))
>>
>> The variable org-html-export-mathjax-ref is non-nil to use \ref vs.
>> nil to be the default \eqref.
>
> The variable could be more general, e.g.,
> org-html-export-equation-reference-format, and default to "\\ref{%s}".
> Note the export back-ends do not use variables directly. It would be
>
>   (format (plist-get info :html-equation-reference-format)
>           (org-export-get-reference destination info))
>
> where the correspondence between :html-equation-reference-format is set
> in back-end definition.
>
> Also, it needs to be referenced in "HTML specific properties" section of
> the manual.
>
> Would you want to propose a patch ?
>
> Regards,

Re: Inconsistent use of \ref and \eqref in ox-latex and ox-html

[Nicolas Goaziou]

Hello,

Brian Powell <powellb@hawaii.edu> writes:

> Thank you for the message. I spent about 2 hours on it today learning
> more about lisp and the internals to explain your email to me.
> I learned a lot.

Thank you.

> I have modified ox-html.el to include a local OPTION as well as
> a customizable setting. I tested with both as well as with an export
> option. All three worked correctly. I also updated the org-manual.org.
>
> Please find my patch attached.

You need to provide a commit message, using git format-patch
mechanism.

> +- =HTML_EQUATION_REFERENCE_FORMAT= ::
> +
> +  #+cindex: @samp{HTML_EQUATION_REFERENCE_FORMAT}, keyword
> +  #+vindex: org-html-equation-reference-format
> +  Specify the MathJax command for referencing equations
> +  (~org-html-equation-reference-format~). The default is to wrap in
> +  parentheses using "\\eqref{%s}". Setting to "\\ref{%s}" is consistent
> +  with LaTeX export.

I don't think this is required. We do not document every variable for
export back-ends.

>  ImageMagick suite is available on your system.  You can still get this
>  processing with
>  
> +The command for formatting equation references can be configured via
> +~org-html-equation-reference-format~.
> +
>  : #+OPTIONS: tex:dvipng

This change is odd. You insert your sentence between an explanation and
its related example. Anyway, per above, this is not needed.

However, it would be nice to reference that variable in

  Publishing > Configuration > Options for the exporters > HTML specific properties

>  : #+OPTIONS: tex:dvisvgm
> diff --git a/lisp/ox-html.el b/lisp/ox-html.el
> index e70b8279b..4848028a2 100644
> --- a/lisp/ox-html.el
> +++ b/lisp/ox-html.el
> @@ -121,6 +121,7 @@
>      (:html-link-home "HTML_LINK_HOME" nil org-html-link-home)
>      (:html-link-up "HTML_LINK_UP" nil org-html-link-up)
>      (:html-mathjax "HTML_MATHJAX" nil "" space)
> +    (:html-equation-reference-format "HTML_EQUATION_REFERENCE_FORMAT" nil org-html-equation-reference-format t)
>      (:html-postamble nil "html-postamble" org-html-postamble)
>      (:html-preamble nil "html-preamble" org-html-preamble)
>      (:html-head "HTML_HEAD" nil org-html-head newline)
> @@ -761,6 +762,20 @@ The function should return the string to be exported."
>  
>  ;;;; LaTeX
>  
> +(defcustom org-html-equation-reference-format "\\eqref{%s}"
> +  "MathJax command to use when referencing equations.
> +
> +Default is to wrap equations in parentheses (using \"\\eqref{%s}\)\".

It might be useful to explicitly state this is a format control string,
expecting a single argument, the actual reference.

> +Most common values are:
> +
> +  \"\\eqref{%s}\"    Wrap the equation in parentheses
> +  \"\\ref{%s}\"      Do not wrap the equation in parentheses"
> +  :group 'org-export-html
> +  :package-version '(Org . "9.3")

It should be "9.4". 

> +	       ;; environment.  Use "ref" or "eqref" macro, depending on user
> +               ;; preference to refer to those in the document.

Indentation problem?

> +               (format (plist-get info :html-equation-reference-format)
>                         (org-export-get-reference destination info))

OK.

As a side note that you can achieve the same without this variable,
using a link filter, e.g. (untested):

     (defun my-html-filter-references (text backend info)
       "Change \eqref{...} into \ref{...}."
       (when (org-export-derived-backend-p backend 'html)
         (replace-regexp-in-string "\\`\\\\eqref{" "\\\\ref{" text)))

     (add-to-list 'org-export-filter-link-functions
                  'my-html-filter-references)

Anyway, would you mind sending an updated patch?

Regards,

-- 
Nicolas Goaziou

[PATCH] Re: Inconsistent use of \ref and \eqref in ox-latex and ox-html

[Brian Powell]

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


Nicolas, thank you for the feedback, and I apologize for my errors.

On Sun, Apr 19 2020, Nicolas Goaziou wrote:
>
> You need to provide a commit message, using git format-patch
> mechanism.
>

Apologies while I learn the procedure. I have corrected the issues below and generated a commit patch attached. Please let me know if there are any problems.

> However, it would be nice to reference that variable in
>
>   Publishing > Configuration > Options for the exporters > HTML specific properties
>

It is now listed in this section and removed from the others.

>
> It might be useful to explicitly state this is a format control string,
> expecting a single argument, the actual reference.
>
>
> It should be "9.4".
>

Both are corrected.

>
> Indentation problem?
>

The indentation problem is in the original org code.

Thank you for all of your help and efforts.

Cheers,
Brian


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-add-org-html-equation-reference-format-to-customize-.patch --]
[-- Type: text/x-patch, Size: 3499 bytes --]

From a7c078e4b5f3d97fa7db0e1df192e26e6953ef71 Mon Sep 17 00:00:00 2001
From: Brian Powell <powellb@hawaii.edu>
Date: Sun, 19 Apr 2020 12:59:53 -1000
Subject: [PATCH] add org-html-equation-reference-format to customize MathJax
 ref command

---
 doc/org-manual.org |  1 +
 lisp/ox-html.el    | 23 ++++++++++++++++++++---
 2 files changed, 21 insertions(+), 3 deletions(-)

diff --git a/doc/org-manual.org b/doc/org-manual.org
index 6d5a34e56..4b1a14ef4 100644
--- a/doc/org-manual.org
+++ b/doc/org-manual.org
@@ -15851,6 +15851,7 @@ Settings]]), however, override everything.
 | ~:html-link-use-abs-url~                       | ~org-html-link-use-abs-url~                       |
 | ~:html-mathjax-options~                        | ~org-html-mathjax-options~                        |
 | ~:html-mathjax-template~                       | ~org-html-mathjax-template~                       |
+| ~:html-equation-reference-format~              | ~org-html-equation-reference-format~              |
 | ~:html-metadata-timestamp-format~              | ~org-html-metadata-timestamp-format~              |
 | ~:html-postamble-format~                       | ~org-html-postamble-format~                       |
 | ~:html-postamble~                              | ~org-html-postamble~                              |
diff --git a/lisp/ox-html.el b/lisp/ox-html.el
index e70b8279b..0565d47f0 100644
--- a/lisp/ox-html.el
+++ b/lisp/ox-html.el
@@ -121,6 +121,7 @@
     (:html-link-home "HTML_LINK_HOME" nil org-html-link-home)
     (:html-link-up "HTML_LINK_UP" nil org-html-link-up)
     (:html-mathjax "HTML_MATHJAX" nil "" space)
+    (:html-equation-reference-format "HTML_EQUATION_REFERENCE_FORMAT" nil org-html-equation-reference-format t)
     (:html-postamble nil "html-postamble" org-html-postamble)
     (:html-preamble nil "html-preamble" org-html-preamble)
     (:html-head "HTML_HEAD" nil org-html-head newline)
@@ -761,6 +762,22 @@ The function should return the string to be exported."
 
 ;;;; LaTeX
 
+(defcustom org-html-equation-reference-format "\\eqref{%s}"
+  "MathJax command to use when referencing equations. This is a
+format controls string, expecting a single argument, the equation
+being referenced that is generated on export.
+
+Default is to wrap equations in parentheses (using \"\\eqref{%s}\)\".
+
+Most common values are:
+
+  \"\\eqref{%s}\"    Wrap the equation in parentheses
+  \"\\ref{%s}\"      Do not wrap the equation in parentheses"
+  :group 'org-export-html
+  :package-version '(Org . "9.4")
+  :type 'string
+  :safe t)
+
 (defcustom org-html-with-latex org-export-with-latex
   "Non-nil means process LaTeX math snippets.
 
@@ -3113,9 +3130,9 @@ INFO is a plist holding contextual information.  See
                     (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}"
+	       ;; environment.  Use "ref" or "eqref" macro, depending on user
+               ;; preference to refer to those in the document.
+               (format (plist-get info :html-equation-reference-format)
                        (org-export-get-reference destination info))
              (let* ((ref (org-export-get-reference destination info))
                     (org-html-standalone-image-predicate
-- 
2.26.0

Re: [PATCH] Re: Inconsistent use of \ref and \eqref in ox-latex and ox-html

[Nicolas Goaziou]

Hello,

Brian Powell <powellb@hawaii.edu> writes:

> Nicolas, thank you for the feedback, and I apologize for my errors.

No need to apologize! Peer review is about catching the mistakes we all
do.

> I have corrected the issues below and generated a commit patch attached. Please let me know if there are any problems.

Thank you! I have some more work for you, if you don't mind ;)

> Subject: [PATCH] add org-html-equation-reference-format to customize MathJax
>  ref command

The commit message should reference the file being modified. I suggest
something along the lines:

    Add customizable format string for equations

    * lisp/ox-html.el (org-html-equation-reference-format): New variable.

> +(defcustom org-html-equation-reference-format "\\eqref{%s}"
> +  "MathJax command to use when referencing equations. This is a
> +format controls string, expecting a single argument, the equation
> +being referenced that is generated on export.

Small nit here. The first line of a docstring must contain complete
sentences only. Therefore you need to move "This is a" part to the line
below.

Also : controls -> control

Otherwise, it looks good! Could you provide an entry in ORG-NEWS about
it? I think Version 9.4 > Miscellaneous is a fine place for it.

Regards,

-- 
Nicolas Goaziou

Re: [PATCH] Re: Inconsistent use of \ref and \eqref in ox-latex and ox-html

[Brian Powell]

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


Thanks again. Please find attached patch addressing issues below.

Cheers,
Brian


On Mon, Apr 20 2020, Nicolas Goaziou wrote:

>> Subject: [PATCH] add org-html-equation-reference-format to customize MathJax
>>  ref command
>
> The commit message should reference the file being modified. I suggest
> something along the lines:
>
>     Add customizable format string for equations
>
>     * lisp/ox-html.el (org-html-equation-reference-format): New variable.

updated

>> +(defcustom org-html-equation-reference-format "\\eqref{%s}"
>> +  "MathJax command to use when referencing equations. This is a
>> +format controls string, expecting a single argument, the equation
>> +being referenced that is generated on export.
>
> Small nit here. The first line of a docstring must contain complete
> sentences only. Therefore you need to move "This is a" part to the line
> below.
>
> Also : controls -> control
>
> Otherwise, it looks good! Could you provide an entry in ORG-NEWS about
> it? I think Version 9.4 > Miscellaneous is a fine place for it.

Done and done.


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Add-customizable-format-string-for-equations-in-HTML.patch --]
[-- Type: text/x-patch, Size: 4493 bytes --]

From f3a8e7d99a390c6dd965f347d95f35780e7d3a77 Mon Sep 17 00:00:00 2001
From: Brian Powell <powellb@hawaii.edu>
Date: Mon, 20 Apr 2020 09:49:12 -1000
Subject: [PATCH] Add customizable format string for equations in HTML export

* lisp/ox-html.el (org-html-equation-reference-format): New variable.
* doc/org-manual.org update to reference new variable
---
 doc/org-manual.org |  1 +
 etc/ORG-NEWS       |  9 +++++++++
 lisp/ox-html.el    | 25 ++++++++++++++++++++++---
 3 files changed, 32 insertions(+), 3 deletions(-)

diff --git a/doc/org-manual.org b/doc/org-manual.org
index 6d5a34e56..4b1a14ef4 100644
--- a/doc/org-manual.org
+++ b/doc/org-manual.org
@@ -15851,6 +15851,7 @@ Settings]]), however, override everything.
 | ~:html-link-use-abs-url~                       | ~org-html-link-use-abs-url~                       |
 | ~:html-mathjax-options~                        | ~org-html-mathjax-options~                        |
 | ~:html-mathjax-template~                       | ~org-html-mathjax-template~                       |
+| ~:html-equation-reference-format~              | ~org-html-equation-reference-format~              |
 | ~:html-metadata-timestamp-format~              | ~org-html-metadata-timestamp-format~              |
 | ~:html-postamble-format~                       | ~org-html-postamble-format~                       |
 | ~:html-postamble~                              | ~org-html-postamble~                              |
diff --git a/etc/ORG-NEWS b/etc/ORG-NEWS
index f6f806b8f..fbee0124d 100644
--- a/etc/ORG-NEWS
+++ b/etc/ORG-NEWS
@@ -384,6 +384,15 @@ now. E.g.,
 This bug [[https://lists.gnu.org/archive/html/emacs-orgmode/2013-08/msg00072.html][originally reported]] by Matt Lundin and investigated by Andrew
 Hyatt has been fixed.  Thanks to both of them.
 
+*** Format of equation reference in HTML export can be specified
+
+By default, HTML (via MathJax) and LaTeX export equation references
+using different commands. LaTeX must use \ref{%s} because it is used
+for all labels; however, HTML (via MathJax) uses \eqref{%s} for equations
+producing inconsistent output. New option
+~org-html-equation-reference-format~ sets the command used in
+HTML export.
+
 * Version 9.3
 
 ** Incompatible changes
diff --git a/lisp/ox-html.el b/lisp/ox-html.el
index e70b8279b..266467345 100644
--- a/lisp/ox-html.el
+++ b/lisp/ox-html.el
@@ -121,6 +121,7 @@
     (:html-link-home "HTML_LINK_HOME" nil org-html-link-home)
     (:html-link-up "HTML_LINK_UP" nil org-html-link-up)
     (:html-mathjax "HTML_MATHJAX" nil "" space)
+    (:html-equation-reference-format "HTML_EQUATION_REFERENCE_FORMAT" nil org-html-equation-reference-format t)
     (:html-postamble nil "html-postamble" org-html-postamble)
     (:html-preamble nil "html-preamble" org-html-preamble)
     (:html-head "HTML_HEAD" nil org-html-head newline)
@@ -761,6 +762,24 @@ The function should return the string to be exported."
 
 ;;;; LaTeX
 
+(defcustom org-html-equation-reference-format "\\eqref{%s}"
+  "The MathJax command to use when referencing equations.
+
+This is a format control string that expects a single string argument
+specifying the label that is being referenced. The argument is
+generated automatically on export.
+
+The default is to wrap equations in parentheses (using \"\\eqref{%s}\)\".
+
+Most common values are:
+
+  \"\\eqref{%s}\"    Wrap the equation in parentheses
+  \"\\ref{%s}\"      Do not wrap the equation in parentheses"
+  :group 'org-export-html
+  :package-version '(Org . "9.4")
+  :type 'string
+  :safe t)
+
 (defcustom org-html-with-latex org-export-with-latex
   "Non-nil means process LaTeX math snippets.
 
@@ -3113,9 +3132,9 @@ INFO is a plist holding contextual information.  See
                     (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}"
+	       ;; environment.  Use "ref" or "eqref" macro, depending on user
+               ;; preference to refer to those in the document.
+               (format (plist-get info :html-equation-reference-format)
                        (org-export-get-reference destination info))
              (let* ((ref (org-export-get-reference destination info))
                     (org-html-standalone-image-predicate
-- 
2.26.1

Re: [PATCH] Re: Inconsistent use of \ref and \eqref in ox-latex and ox-html

[Nicolas Goaziou]

Hello,

Brian Powell <powellb@hawaii.edu> writes:

> Thanks again. Please find attached patch addressing issues below.

Perfect. Applied. Thank you!

I forgot to add TINYCHANGE at the end of the commit message, but I added
you to the list of contributors.

Regards,

-- 
Nicolas Goaziou