Re: [O] Equation references in HTML export

[Nicolas Goaziou]

Hello,

Thibault Marin <address@hidden> writes:

> From 094df613ec5fd05b6d2124bc45e6f9a8cbef92e5 Mon Sep 17 00:00:00 2001
> From: thibault <address@hidden>
> 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?

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