Nicer rendering of LaTeX formulas in docstrings on the REPL

[fingolfin]

Right now, if a docstring contains LaTeX math, it renders nicely in HTML, but in the REPL help system, the raw TeX source is shown.

Couldn't the translation describe in latex_symbols from stdlib/REPL/src/latex_symbols.jl be applied to Markdown docstrings, too?

This would require accessing that code from stdlib/Markdown, which then would have to access REPL, or else that translation code would have to be factored out into a separate place. I believe one would want to perform some more transformations, too (e.g. map \mathbb{Z} to \bbZ).

It might also not look great in all cases, so perhaps an option for docstring authors to somehow opt-out of this translation for certain docstrings might be necessary?

[timholy]

Those seem like good ideas. Another, perhaps more comprehensive approach: https://github.com/Kolaru/MathTeXEngine.jl looks like it's mostly targeting Makie, but I bet it could also be leveraged to do what you want (if it doesn't already). Maybe consider collaborating with them? If you need a couple of hooks in Base.Docs to get it integrated into the REPL help display, we could add that separately.

[fingolfin]

So how would that work? Surely this shouldn't be a stdlib. So is implied the idea that my package would depend on MathTeXEngine.jl (resp. something that pulls it in and uses it to register suitable callbacks with the REPL code responsible for displaying docstring) in order to enable better rendering of its docstrings?

I guess that breaks it down into (at least) the following tasks:

1. figure out how to modify docstrings to deal with math in it (e.g. similar to @doc Markdown.doc""".... """ -- though I wonder about how to compose these: I'd like to combine math and markdown). I imagine this might scan for $....$ and $$....$$ sequences, also \(...\) and \[...\] (possibly configurable, just like MathJax allows)
2. these snippets could then be transformed using stdlib/REPL/src/latex_symbols.jl or https://github.com/Kolaru/MathTeXEngine.jl or something else
3. the result needs to be used to render the docstring nicely in the terminal. In the simplest version, this might just transform the docstring text (by replacing say $a^2+\beta_2$ by a²+𝛽₂) although of course for more complex formulas, this is not enough (but for my applications, I am hoping it suffices)
4. if the above is not enough, figure out how to hook into the Julia code rendering the docstrings to the REPL, and turn that into a suitable set of hooks for it. Then the sky is the limit, e.g. some terminals now allow inserting pixel graphics

[timholy]

You've already thought about it more than me 😄 . But yes, that was generally the kind of thing I was imagining. Perhaps your package wouldn't have to depend on MathTeXEngine, it might be more of an "environment" thing (if the user has loaded MathTeXEngine then you get pretty-printed LaTeX at the REPL, otherwise you get raw LaTeX). I'll be curious to see what you come up with!

[fingolfin]

A user implemented something in this direction, see https://discourse.julialang.org/t/97498 (there is also a thread on Slack). They posted their code on Slack, but not yet in a public Git repo. It currently uses Autom.jl, so if this should be integrated into Julia core that dependency would have to be replaced. But perhaps this could also be an external package? Then we'd have to add some hooks: Right now it works by overriding Markdown.terminline, which of course is acceptable as a temporary hack but not a good final solution