From: Thibault Marin <thibault.marin@gmx.com>
To: Nicolas Goaziou <mail@nicolasgoaziou.fr>
Cc: emacs-org list <emacs-orgmode@gnu.org>
Subject: Re: Equation references in HTML export
Date: Sun, 07 Jan 2018 03:11:06 -0600 [thread overview]
Message-ID: <87k1wughjp.fsf@dell-desktop.WORKGROUP> (raw)
In-Reply-To: <87shbj6zh5.fsf@nicolasgoaziou.fr>
[-- 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
next prev parent reply other threads:[~2018-01-07 9:11 UTC|newest]
Thread overview: 13+ messages / expand[flat|nested] mbox.gz Atom feed top
2018-01-05 5:30 Equation references in HTML export Thibault Marin
2018-01-06 10:41 ` Nicolas Goaziou
2018-01-07 9:11 ` Thibault Marin [this message]
2018-01-09 21:27 ` Nicolas Goaziou
2018-01-11 4:04 ` Thibault Marin
2018-01-16 18:09 ` Nicolas Goaziou
2018-01-17 4:39 ` Thibault Marin
2018-01-17 21:27 ` Nicolas Goaziou
2018-01-18 3:25 ` Thibault Marin
2018-01-19 17:39 ` Nicolas Goaziou
2018-01-17 7:35 ` Eric S Fraga
2018-01-19 4:09 ` Thibault Marin
2018-01-19 7:39 ` Eric S Fraga
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=87k1wughjp.fsf@dell-desktop.WORKGROUP \
--to=thibault.marin@gmx.com \
--cc=emacs-orgmode@gnu.org \
--cc=mail@nicolasgoaziou.fr \
/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
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public 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).