LaTeX fragments become unlabelled when exporting to SVG (equation becomes equation*)

[Perangelot]

Actual Behavior

The code for a LaTeX fragment is changed before the .svg image to be shown in the .html is produced. For example, the equation environment becomes the equation* environment. This results in org-preview images deviating from those shown in the .html. Especially for self-defined environments, this poses a big problem because they are not displayed correctly.

Expected Behavior

I see that this is useful sometimes, but there should be a way to turn this off, that is generate the .svg images exactly the same way as they are generated for org-preview. It seems that org-blackfriday-latex-fragment does some changed, but I am not sure if it draws on defaults of org-export settings.

How to Reproduce the Issue

Run C-c C-x C-l on the equation fragment. Export the MWE file to hugo html. Compare the org and html .svgs. Select the .svg in the browser, press C-c to copy the code and paste it in an org-mode buffer. Compare the code of the equation environment and code copied from the .svg. Alternatively, compare the alt in the .md file with the code that should generate the preview.

Example Org File

#+title: Example
#+hugo_base_dir: ../
#+startup: latexpreview
#+options: tex:dvisvgm

\begin{equation}
\text{``}\exists\mathit{x}\,\text{''} 
\text{ abbreviates } 
\text{``} \lnot \forall\mathit{x}\,\lnot\text{''}
\end{equation}

Generated Markdown File or Error

+++
title = "Example"
draft = false
+++

<div class="equation-container">
<span class="equation">
<img src="/ltximg/Example (vom 09.04.2022)_1898ce671d246d2d597ad0c788ba8ce849b1e7bc.svg" alt="\begin{equation*}
\text{``}\exists\mathit{x}\,\text{''}
\text{ abbreviates }
\text{``} \lnot \forall\mathit{x}\,\lnot\text{''}
\end{equation*}
" class="org-svg" />
</span>
<span class="equation-label">
1
</span>
</div>

org-mode .svg:

html .svg:

Note: Your equation number should be on the right handside; I loaded amsmath with the leqno option which, well puts the equation numbers left.

[kaushalmodi]

It seems that org-blackfriday-latex-fragment does some changed, but I am not sure if it draws on defaults of org-export settings.

If mathjax is not used, ox-hugo falls back to returning whatever ox-html generates (the img tag referencing the SVG file and the span tag for equation). The only modificationox-html (ox-blackfriday) does is updating the SVG path in img tag so that it work with Hugo.

ox-hugo/ox-blackfriday.el

Lines 984 to 986 in 3d9cc64

	(t
	(org-blackfriday--update-ltximg-path
	(org-html-latex-fragment latex-fragment nil info))))))

Can you check if you see the same behavior if you export that to ox-html?

---

For example, the equation environment becomes the equation* environment.

Sorry, I don't know what that means.

Your equation number should be on the right handside

You'll need to control that using CSS. See this HTML in the Markdown snippet you posted:

<span class="equation-label">
1
</span>

The equation label has equation-label class. So using CSS you can move it to the right or left, shift it higher/lower, etc and even wrap that equation number with parents, and or just hide it.

Positioning that equation number is out of the scope of ox-hugo.

[kaushalmodi]

Compare the org and html .svgs. Select the .svg in the browser, press C-c to copy the code and paste it in an org-mode buffer. Compare the code of the equation environment and code copied from the .svg.

Can you post the diff you see just out of curiosity?

I don't think I'll be able to fix that here because the ox-hugo is falling back on ox-html to generate the SVG and provide the HTML snippet with the img tag and caption.

[Perangelot]

Thanks for your fast response! I should have explained some more about LaTeX, sorry.

If mathjax is not used, ox-hugo falls back to returning whatever ox-html generates (the img tag referencing the SVG file and the span tag for equation). The only modificationox-html (ox-blackfriday) does is updating the SVG path in img tag so that it work with Hugo.

Okay, thank you for this information! I had feared it, but wanted to be sure. This was valuable to know, though, because it helped spot the problem (see below).

Can you check if you see the same behavior if you export that to ox-html?

Yes, same behavior. This is proof it doesn't have to do anything with ox-hugo. I should have had that idea myself. Sorry!

Your equation number should be on the right handside

You'll need to control that using CSS. See this HTML in the Markdown snippet you posted:

What I said concerned the equation number produced by LaTeX, not by html/css. But I did not know about all that! So I could label my equations with css and even refer to them since they are not part of the image - thank you for the insight! This makes (1) (see below) obsolete. Are you familiar enough with css to tell me without effort how you can put the equation numbers left and in parentheses? I am a total beginner with css.

Sorry, I don't know what that means.

Sorry for not explaining! In LaTeX, a code chunk that looks like

\begin{env}
...
\end{env}

is called an environment, and env is the environment name. Some environments come with a starred version. The starred environments work just like the unstarred ones, but come with some minor tweaks. In the case of the the environment equation (and many other usual environments), equation* is just like equation except that it does not add any equation label. And this is exactly the diff you asked about. Now the problems I was facing were these:

1. equation environments were exported as equation* environments, so without label.
2. Some custom environments were exported incorrectly.

As it happens, I have just found the culprit of both (1) and (2): It is org-html--unlabel-latex-environment. You can find it in ox-html. I don't understand what it exactly does, but as the doc string tells us, it puts an asterisk in front of some environments (no idea which ones exactly, the doc string is quite vague). Now the function which actually creates the LaTeX environment images is org-html-latex-environment. If you replace

(let ((formula-link
             (org-html-format-latex
              (org-html--unlabel-latex-environment latex-frag)
              processing-type info)))

by

(let ((formula-link
             (org-html-format-latex latex-frag
              processing-type info)))

in that function, things work out as expected. In other words, just skip the unlabelling function. At the moment, I just copied the whole function (which is huge) in my config with these changes, but if you know a neater way to do it, please let me know!

Anyway, the problem is resolved now. Thank you for your time and patience! I intend to write an in-depth blog article about the whole topic soon - for beginners like me - in the hope that the next one wondering will read it instead of opening another request. I really appreciate your efforts.

[kaushalmodi]

Are you familiar enough with css to tell me without effort how you can put the equation numbers left and in parentheses? I am a total beginner with CSS.

I am not proficient enough in CSS to provide a solution without any iteration. I'd suggest that you just search online for stuff like "move text to left of screen CSS", "prepend text or append text using CSS", etc. and you will most likely come up with many StackOverflow solutions.

But I see later in your reply that you have figured out a workaround by modifying an ox-html function, so this is probably not needed?

As it happens, I have just found the culprit of both (1) and (2): It is org-html--unlabel-latex-environment

Looking through git revision history, I see that this was labeling change was done in https://git.savannah.gnu.org/cgit/emacs/org-mode.git/commit/?id=ba6c0f1ea9d3430f23ed7e316b0f4a6c4a66c6fd.

To fix this properly, I would suggest emailing [email protected] and the author of that commit thibault ([email protected]).

but if you know a neater way to do it, please let me know!

Emacs Advice system would help you here. I recently wrote a blog post ( https://scripter.co/using-emacs-advice-to-silence-messages-from-functions/ ) which could serve as an introduction to writing advices in Emacs Lisp.

Still, emailing the Org mode list is the right thing to do here.

---

Thank you for your time and patience! I intend to write an in-depth blog article about the whole topic soon - for beginners like me - in the hope that the next one wondering will read it instead of opening another request.

👍 I'd love to read that! Please share when you have published it. Everyone's a beginner in something. Someone always learns something when you share something.

I really appreciate your efforts.

You're welcome!

[Perangelot]

Thank you for your response! I have read into css and managed to get the parentheses working. You need to add this to your style.css in /static:

span.equation-label:before {
    content: '(';
}

span.equation-label:after {
    content: ')';
}

The alignment can be set this way:

span.equation-label {
  display: block !important;
  **text-align: left**;
  max-width: 100%;
  margin-left: -0.1 !important;
  margin-right: -0,1cm !important;
}

Now what I am left with is how to refer to the equation labels in the text with hyperlinks. Any idea?

---

After digging more through ox-html, I found out these issues (which are not ox-hugo related!):

1. Adding the css styling above produced a whitespace between the equation number and the parentheses; for example, you get ( 1 ) instead of (1).
2. Any environment (except in-line-math) gets an equation number.
3. Any environment name foo is changed to foo* (except it already ends with an asterisk).

I have put quite some elbrow-grease into possible solutions, which I would like to share with you.

Changing (1) is simple. org-html--wrap-latex-environment produces the html span class equation-label, where the equation number is then inserted. Specifically, it adds this string:

"\n<span class=\"equation-label\">\n%s\n</span>"

Now the newline commands \n before and after %s are exported as whitespace. Just replacing \n%s\n by %s (that is, leaving them out) solves the problem.

Changing (2) seems to be quite simple, too, and I think I know how to do it in theory:

1. Create a new variable ox-html-latex-environments-no-number of the form ("foo" "bar" "baz" ...), which contains all environments that should not receive equation numbers.

2. Change org-html--latex-environment-numbered-p. It is currently defined like this:

(defun org-html--latex-environment-numbered-p (element)
  "Non-nil when ELEMENT contains a numbered LaTeX math environment.
Starred and \"displaymath\" environments are not numbered."
  (not (string-match-p "\\`[ \t]*\\\\begin{\\(.*\\*\\|displaymath\\)}"
		       (org-element-property :value element))))

Now we need to adjust the regular expression in such a way that if element has \begin{foo} or \begin{bar} etc. (that is, the environment name is a member of ox-html-latex-environments-no-number), it also returns nil. I think this is doable. I thought about adding something like

  (not 
    (or
 ; starred or display math
      (string-match-p "\\`[ \t]*\\\\begin{\\(.*\\*\\|displaymath\\)}"
      (org-element-property :value element))
 ; environment of ox-html-latex-environments-no-number
    (string-match-p (format "\\begin{%s}" [any element of ox-html-latex-environments-no-number])
		       (org-element-property :value element))
))

I don't know how to express in elisp what is in brackets, though. Does this make sense to you? I am a beginner at elisp, so I can only state the ideas I have but not implement them (yet).

As to (3): Which images receive label numbers is controlled by this part of org-html-latex-environment:

 (let ((formula-link
             (org-html-format-latex
              (org-html--unlabel-latex-environment latex-frag)
              processing-type info)))

As you can see, at the moment, org-html--unlabel-latex-environment is applied to every latex-frag. So we would again need a variable org-html--latex-environments-leave-unlabelled of the same form as above whose members are all latex environments which should not be unlabelled. Then, we could implement a condition like

 (let ((formula-link
             (org-html-format-latex
   ; if latex-frag is one of org-html--unlabel-latex-environment
            (if (string-match-p (format "\\begin{%s}" 
                                   [any element of org-html--latex-environments-leave-unlabelled])
		       latex-frag) 
                   ; then do not apply org-html-format-latex to latex-frag
             (org-html-format-latex latex-frag)
                       ; else do apply org-html--unlabel-latex to latex-frag
(org-html--unlabel-latex-environment latex-frag)
              processing-type info)))

These are just beginners' thoughts, so I'm happy about any idea you have! Do you think the issues are described understandably like this? If so, I am going to report them to the org-mode maling list and the author of the relevant commit.

[kaushalmodi]

how to refer to the equation labels in the text with hyperlinks. Any idea?

I am aware of only one method which I took from the Org manual. You can find an example here: https://ox-hugo.scripter.co/doc/equations/#environments. Equations don't have the same auto-numbering as figures, tables and code snippets have.

[kaushalmodi]

Changing (1) is simple. org-html--wrap-latex-environment produces the html span class equation-label, where the equation number is then inserted. Specifically, it adds this string:

"\n<span class=\"equation-label\">\n%s\n</span>"

Now the newline commands \n before and after %s are exported as whitespace. Just replacing \n%s\n by %s (that is, leaving them out) solves the problem.

You should email this suggestion to the Org mailing list email! It definitely makes sense to not having that extra newline in HTML because HTML anyways ignores them.

[kaushalmodi]

I don't know how to express in elisp what is in brackets, though. Does this make sense to you?

Yes, it makes sense. In emacs lisp you will extract the string in the \begin, save that to ELEM and then use (member ELEM LIST) to check if ELEM is one of the elements in LIST. But you don't have to worry about that.

You can still go ahead and email the Org mode mailing list with your ideas. If something is not clear, someone will ask you to clarify.

[kaushalmodi]

@Perangelot I have converted this to a discussion as it's not related to ox-hugo. Also, this question has better visibility for other users in the Discussions area.

[Perangelot]

Alright, I am going to report it, then. The suggestion in your documentation unfortunately only works for Mathjax, but it is either Mathjax or svg. I am pretty sure you could so something with radio targets, though; they are exported correctly to markdown and really handy for equation numbering because you would only have to type in the equation number and immediately have a link. What works, for example, is

<<<eq2>>> 
\begin{equation*}
\tag{1} \hskip -15em
\text{``}\!\mathit{A} \to \mathit{B}\,\text{''} 
\text{ abbreviates } 
\text{``}\lnot ( \mathit{A} \land \lnot \mathit{B})\text{''}
\end{equation*}

and then just writing at some point in the org-buffer "eq2". It immediately turns into a hyperlink pointing to <<<eq2>>>. The only downside is that <<<eq2>>> is exported to "eq2". The markdown looks like this:

<span class="org-radio" id="org-radio--eq2">**eq2**</span>

What we need for proper equation links would be this line without eq2.

<span class="org-radio" id="org-radio--eq2"></span>

If that worked, you could make perfect references to your equations. It probably is even possible to automatically generate radio targets since the equations are laballed automatically, too.

There sure is a way to not export radio targets, and I think a simply function wihch deletes all occurrences of <<<foo>>> would suffice; you could add it to org-export-filter-radio-target-functions. Maybe this opens up a perspective for you, just wanted to let you know.

[kaushalmodi]

Check out https://ox-hugo.scripter.co/doc/anchors/#target-links.

[Perangelot]

This is awesome! If I get a response from the org-mode team, I have everything together to write full-fledged LaTeX in HTML. Can't wait to write the guide. Thank you so much!

[kaushalmodi]

@Perangelot I see that you started the discussion on the mailing list here (and here). Thanks!

Someone should reply within a week or so. If you don't hear back, you can reply all to your own message and bump the thread.

[Perangelot]

@kaushalmodi Now Thibault, the one who originally wrote the code, replied to my mail. To my reply after that, there was no reaction. I bumped the thread but still noone replied. Would it be too much to do it again?

[kaushalmodi]

@Perangelot It doesn't hurt pinging again. Also, you can send patches for the stuff you have been able to fix by yourself.

[Perangelot]

Now I have actually figured out a way to handle the problem that all environments get labelled in html. I define a variable which contains all the LaTeX environments that should not be labelled and change the predicate to consider this. This is the code plus example, heavily annotated:

;;; Variable to make exceptions ;;;

(defcustom org-html--latex-environment-unlabelled
'("equation" "displaymath")
"List of LaTeX environments which should not receive a label when exported to html.")

;;; Idea: LATEX-ENV is the string from the beginning to the end of the whole latex environment. 
Now the string within the first pair of braces of LATEX-ENV must be the environments name. 
So we extract that and call it ENV-NAME. If this name now occurs in org-html--latex-environment-unlabelled, 
it should not be labelled, so it returns nil. If it does not, it should be labelled and returns t. ;;;

(defun org-html--latex-environment-numbered-p (element)
  "Non-nil when ELEMENT is an environment not listed in org-html--latex-environment-unlabelled." 
(let* ((latex-env (org-element-property :value element))
(env-name (cadr (org-split-string latex-env "{\\|}"))))
(not (seq-contains-p org-html--latex-environment-unlabelled env-name))))


;;; Example ;;;
(setq element1 '(latex-environment (:begin nil :end 160 :value "\\begin{tabular}
p \\to q
\\end{tabular}
" :post-blank 1 :post-affiliated 117)))

(setq element2 '(latex-environment (:begin nil :end 160 :value "\\begin{equation}
p \\to q
\\end{equation}
" :post-blank 1 :post-affiliated 117)))

(org-html--latex-environment-numbered-p element1) ; t because not in org-html--latex-environment-unlabelled
(org-html--latex-environment-numbered-p element2) ; nil because in 

I have just started reading into emacs-lisp and it might be an awful piece of code. My version of org-html--latex-environment-numbered-p is also is quite different from the original function (because I do not know regular expressions). Does my code make any sense to you? And if yes, how do you send patches? I see they have the diff format but I do not know how to create such files in emacs.

[kaushalmodi]

Does my code make any sense to you?

Sorry, I haven't found time to look into this or test it out. The main reason is that I don't use LaTeX this heavily. It's best if a fellow Org/LaTeX user can comment on your code.

And if yes, how do you send patches? I see they have the diff format but I do not know how to create such files in emacs.

The best approach is to send the patches to the Org mode mailing list and then refine the patches through discussions there. I wrote up a short guide on how to create patches here: https://scripter.co/creating-a-patch-file-using-magit/.

I would suggest that you send a separate patch/email for each isolated fix.