emacs-orgmode@gnu.org archives
 help / color / mirror / code / Atom feed
From: Brian Powell <powellb@hawaii.edu>
To: Nicolas Goaziou <mail@nicolasgoaziou.fr>
Cc: emacs-orgmode@gnu.org
Subject: Re: [PATCH] Re: Inconsistent use of \ref and \eqref in ox-latex and ox-html
Date: Mon, 20 Apr 2020 09:52:05 -1000	[thread overview]
Message-ID: <m2eesiyly2.fsf@hawaii.edu> (raw)
In-Reply-To: <87imhurtzf.fsf@nicolasgoaziou.fr>

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


  reply	other threads:[~2020-04-20 19:54 UTC|newest]

Thread overview: 8+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2020-04-10 21:56 Brian Powell
2020-04-18  8:00 ` Nicolas Goaziou
2020-04-19  7:22   ` Brian Powell
2020-04-19 10:46     ` Nicolas Goaziou
2020-04-19 23:13       ` [PATCH] " Brian Powell
2020-04-20 16:40         ` Nicolas Goaziou
2020-04-20 19:52           ` Brian Powell [this message]
2020-04-21 17:46             ` Nicolas Goaziou

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

  List information: https://www.orgmode.org/

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=m2eesiyly2.fsf@hawaii.edu \
    --to=powellb@hawaii.edu \
    --cc=emacs-orgmode@gnu.org \
    --cc=mail@nicolasgoaziou.fr \
    --subject='Re: [PATCH] Re: Inconsistent use of \ref and \eqref in ox-latex and ox-html' \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

Code repositories for project(s) associated with this inbox:

	https://git.savannah.gnu.org/cgit/emacs/org-mode.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).