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

[Brian Powell <powellb@hawaii.edu>]

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