Fix printing of LaTeX markdown to IPython and plain text.

[malmaud]

Resolves JuliaLang/IJulia.jl#304, which was caused by two separate issues:

• First, plain(::IO, ::LaTeX) wasn't defined, even though Base defines it for all other Markdown elements. The previous definition of writemime(..., ::LaTeX) is now implicitly defined via the Base.writemime(io::IO, ::MIME"text/plain", md::MD) = plain(io, md) definition.
• Second, latex(::IO, ::LaTeX) wasn't defined.

[hayd]

Off Topic: but this should probably also be the latex function rather than writemime. (I think that was my fault).

[hayd]

I think @one-more-minute will suggest these functions (latex and plain) should be defined in IPython.jl function. Similar to how it's done for Github/tables.

Otherwise, this looks good to me... may be worth adding a test.

[MikeInnes]

Yes, the render/ code is only meant to define rendering for standard elements. Latex is an extension, strictly speaking, so it'd be great if all Latex-related code was in one file.

FYI, plain(io, x) is meant to default to writemime(io, "text/plain", x) (and similar for latex(io, x)), so if that isn't happening properly that's a bug. Defining plain for Latex explicitly is fine though.

A test would be great to see.

[hayd]

@one-more-minute Would it make sense to move the plain/render/latex code into Common/Julia/etc ? Or even have one file for each type (like with Github tables)? Perhaps that would be more consistent (with extensions)... Happy to put something together.

[hayd]

@one-more-minute I'm a little confused about the parsing code (the code that was there before), is this/should this be:

• $..$ inline latex?
• $$..$$ block latex?

If so you have to also define latexinline.

Note: perhaps we should also support \[..\] and \(..\) syntaxes from mathjax, the latter is preferred for inline latex (since $s are quite common). In fact these may be always preferred over $ and $$!

[MikeInnes]

$...$, with one or more $ at the end, can define block or inline LaTeX objects. The only difference is the location in the tree – inlines are, well, inline within a Paragraph or another block element, whereas blocks stand on their own as direct children of MD.

I wouldn't be that opposed to MathJax-style syntax. I think what we have is consistent with IPython / Pandoc (?) but \[ is clearly less ambiguous on its own. We could also enforce two-or-more $ signs. Feel free to open an issue on this one to get some community consensus.

If so you have to also define latexinline.

Actually, this is why I only defined writemime(...). Rather than defining plain, plaininline, latex, latexinline, etc., x6, each of those functions should fall straight back on writemime. From this issue it looks like the fallbacks aren't happening so that would be the ideal fix.

Would it make sense to move the plain/render/latex code into Common/Julia/etc ? Or even have one file for each type (like with Github tables)?

It might be more consistent if Paragraph had its own file, for example, but it would also make the rendering code really hard to follow. Bootstrapping a render system for the CommonMark types in one place makes it clear what all of the functions are for and how it all works.

Once you get to extension types like tables, though, things switch around – putting table rendering code in plain.jl doesn't add any value to that file and makes the table code as a whole harder to follow. So they get their own files. I think as long as there's a clear line to draw (CommonMark vs. not) it's fine to make that distinction.

[hayd]

It might be more consistent if Paragraph had its own file, for example, but it would also make the rendering code really hard to follow.

IMO it's actually pretty nice. All you need to do is rearrange the includes in Markdown. hayd@8e3d178

[MikeInnes]

Ok, fair enough – seeing it definitely brings me around to the idea a bit more. I think I'll wait till I'm a bit more free to make any drastic refactoring decisions, but I'm not vehemently opposed at any rate.

[malmaud]

Alright, this should be ready now. I know @hayd is working on a general refactoring of the Markdown code, but for now this fixes a pressing IJulia issue.

[hayd]

Sorry for hijacking the thread! My refactor doesn't interfere with this.

@one-more-minute falling back plain to use writemime seems strange to me. My understanding of plain is that it ought to (in-spirit) be the inverse of Markdown.parse i.e. parse |> plain |> parse == parse.... IMO writemime fails this test. (Though IIRC rich.jl takes similar liberties. :p)

As an aside, perhaps we should use \[..\] rather than $$..$$ for latex. But we can tweak that after.

[MikeInnes]

Thanks!

@hayd Sure, in principle, but in general that's not possible (e.g. if you embed a plot or Ref). The alternative is to throw a bunch of method errors when people embed objects, and I'd much rather just display something useful.

Happy to see a syntax bikeshedding issue, like I said I'm not that strongly set either way.

[stevengj]

We should follow PanDoc etc. for LaTeX in Markdown, and I think that uses $ and $$ for inline and display, and in particular it uses the heuristic that the opening $ can't be followed by whitespace, while the closing $ can't be followed by a digit or preceded by whitespace. See this discussion.

[hayd]

@one-more-minute I meant as the output of latex.

[MikeInnes]

Ah, I see. Yeah, that's totally fair.

[hayd]

@stevengj see also this https://github.com/cben/mathdown/wiki/math-in-markdown of all the different things people are doing on the markdown parsing side. At the moment we're just using $ (not $$).

Note: pandoc is "Smart enough to parse nested $y = x^2 \hbox{ when $x > 2$}$ as single formula." :s

[hayd]

Elsewhere in this file it's referenced as writemime(io, MIME"text/plain"(), md), does this difference not matter?

[stevengj]

There is a writemime method that converts the string argument to a MIME object, so it should be pretty much equivalent.