adam-p
TeX: offline rendering and image insertion
See #144 and #261 for background.
We currently (and have always) used a third-party service for TeX rendering -- Google and now CodeCogs. There are two really bad things that come with this:
- User math is being sent to the third party.
- If the third party service goes away (like when Google shut down the API we were using), the rendering dies. And not just when writing a new email, but also when reading the email.
The ideal would be to render the math image locally and include it in the rendered MD->HTML output. A big problem with that is that there's no easy way to do it with (for example) Gmail; images with inline data don't work, etc.
However, maybe it's possible to do this by pasting the image; see this comment for details. This is no small task, as it's a fundamental change. It needs a proof of concept that can be tested in multiple email providers and other sites -- there's a very good chance that they don't all support image-pasting and so this method would work worse than the current DOM-insertion-with-remote-image method.
TeXSend-Gmail userscript works quite well with Markdown Here in Gmail ... so maybe it can be integrated directly into the MHD extension as an additional option.
I have implemented the paste approach, added local TeX rendering, and I'm hoping for some feedback from people who use TeX. There's a beta extension you can install here (you should disable or uninstall the other extension or else it's going to be confusing). You can find it here: https://chromewebstore.google.com/detail/markdown-here/enihccblfeliefaickgkbpfeeakjdffh
I'm still cleaning up the code before pushing, but I think it's working well. There are explanatory notes in the options page -- check near the new option and in the changelist.
@cben: Can you try this out? (And everyone else, of course.)
Whoa, that's cool! Renders crisp math, works in Gmail, zero communication to CodeCogs — not when composing nor when receiving mail, adjusts size & color to surrounding text, even sets baseline beautifully e.g.:
### below $\frac1{1+\frac1{1+\frac1{1+n}}}$ baseline
> # above $\frac{1+\frac{1+\frac{1+n}1}1}1$ baseline
👏 ✨ 🙏 👏
My first feedback is on the config UI.
- IIUC the way to enable it is enable both checkboxes. If I enable only the experimental one, math is not rendered.
- IIUC the URL is meaningless in the new mode (despite its checkbox being necessary).
- The "Privacy Issues:" are not relevant to experimental mode. Same for much of the "customization"?
What do you think of making it radio buttons?
- [x] First a checkbox for enabling math rending at all.
Under that, 2 radio buttons (all greyed out when off):- External rendering (stable).
[URL text box]
(Reset to default) Privacy issues:
...
Customization and Use:
... - Clipboard-based rendering (experimental). ... same explanations and warning ... ("~~If you don't use TeX math, then there is no reason to enable this feature.~~" can be omitted?)
- External rendering (stable).
As https://github.com/adam-p/markdown-here/issues/630#issuecomment-3212607178 says you also implemented display math :tada:
AFAICT the rules are: Enclose in double dollars, and put on its own line.
To be precise, the formula can be split into multiple lines but opening $$ must be first on its line (other than markdown prefixes like - or > ).
My own interest is 99.9% gmail, but I imagine a clipboard-based approach may affect inter-operability with other WYSIWYG editors?
Do you have any specific ones you care about?
-
[x] https://ckeditor.com/ckeditor-5/demo/feature-rich/ — Math rendering works, and some markdown renders.
- 🎉 It actually's major improvement, afaict NO MARKDOWN renders without the new mode (or in firefox running mainline MDH), even with text that contains zero math!
- [ ] Clicking CKEditor's ALT text button on the resulting images shows JSON, includes TeX source but kinda noisy. From peeking at console ("[ClipboardRenderer] Cleaned up JSON alt on 15 unprocessed images") I suspect that was not the end goal.
- Can't un-render, but can Ctrl+Z. Was same before.
-
[x] https://trix-editor.org/ — Rendering works, but:
- Inline formulas display on they own lines with "Add a caption" — was same with old render, Trix just doesn't support inline images?
- [ ] The img tags have no alt text at all. Was same before (though theoretically, src=codecogs... URL allowed recovery of TeX source).
- Can't un-render, but can Ctrl+Z. Was same before. This also undoes the last edit action before render, making it fragile to use.
-
[x] https://www.tiny.cloud/docs/tinymce/latest/cloud-quick-start/ - Works well.
- [ ] img baselines are not honored.
- [x] Alt text == TeX source.
- [x] Un-render works smoothly.
I guess the important ones are other webmail sites?
- [x] My wife has a university https://Outlook.com account, let's see... Yes, renders nicely!
- [ ] img baselines are not honored.
- [x] Alt text == TeX source.
- Un-render is lossy, in particular loses formulas! Can Ctrl+Z twice, may also undoe last edit action(s) before render? making it fragile to use.
Anyway, this looks great to release with opt-in/out config 👏🚀
🎉 Another win of MathJax for heavy TeX users, that was impossible with per-image CodeCogs etc., is ability to define custom macros once, and use them in all your formulas. Example:
define: $\newcommand{\foo}{F\frac{o}{o}} OK$ (OK helps see it worked, otherwise renders empty image)
use: $\foo + \foo$
This works because MathJax keeps macros in global-ish state between renders.
A funny side effect is one can define a macro in one email, then use in rendering an entirely different email... A bit unintuitive, and with \renewcommand can even mess up standard commands.
- Resetting that state doesn't seem documented for MJ v3.2? I had some notes here: https://github.com/cben/CodeMirror-MathJax/issues/2#issuecomment-27267154 for v2.4, and here is Davide Cervone cooking some newer magic 🧙♂️ .
I don't think you want to bother with undocumented internals. Reload the GMail tab is good enough workaround IMHO.
Equation numbering is similarly stateful. Numbers ("tags") are not by default auto-assigned, you'd have to enable it in src/common/mathjax-config.js.
I suspect the more pragmatic use is assign \tag manually anyway, and hard-code the references too:
As equation $(22)$ will teach us...
$$\begin{align}
\tag{11} 1+1=2 \\
\tag{22} 2+2=4
\end{align}$$
That was $(22)$.
But we can use manual \tags to preview the problem one would face with auto-numbered \label if you did enable tags: 'ams' in the config:
As equation $\eqref{2e}$ will teach us...
$$\begin{align}
\tag{11} 1+1=2 \\
\tag{22} \label{2e} 2+2=4
\end{align}$$
That was $\eqref{2e}$.
On 1st render, the forward reference doesn't work:
(not certain why; I believe MJ can resolve forward refs, though maybe they have to be part of one typeset call?)
After un-render and 2nd render, both eqrefs work, but the equation refuses to render because \label{2e} collides with an already known label — from 1st render:
Workarounds are make new label e.g. s/2e/2f/g, or reload the GMail tab, going back to 1st result.
And with auto-numbering, even a fresh label would still get progressively higher numbers!
The official texReset() API can fix it.
Even with that, auto-numbering can get messy if one renders/un-renders selections instead of whole doc...
TLDR: Both are good enough as-is.
My first feedback is on the config UI.
Yes, the config UI isn't final. I'll take your suggestions into account when I finalize it.
There is still some meaning (for now) when the TeX URL is unchecked but clipboard rendering is checked: everything still uses clipboard rendering, but without math support enabled. This combination isn't exactly nonsensical, but... there's no good reason for non-math people to use clipboard rendering.
On the other hand... Now that all the caveats of math rendering are gone, it could just be on for everyone, with no option to turn it off. But that means clipboard rendering for everyone. And that means clipboard permissions for everyone. So no.
(Also, there has been one user email me confused about why his dollar amounts would sometimes get turned into math. I told him to disable math.)
As #630 (comment) says you also implemented display math 🎉 AFAICT the rules are: Enclose in double dollars, and put on its own line. To be precise, the formula can be split into multiple lines but opening
$$must be first on its line (other than markdown prefixes like-or>).
I think you are correct. Is that behaviour to your satisfaction?
