We’ve just a made a change to the syntax for embedding MathJax equations in R Markdown documents. The change was made to eliminate some parsing ambiguities and to support future extensibility to additional formats.
The revised syntax adds a “latex” qualifier to the $ or $$ equation begin delimiter. It looks like this:
This change was the result of a few considerations:
- Some users encountered situations where the $<equation>$ syntax recognized standard text as an equation. There was an escape sequence (\$) to avoid this but for users not explicitly aware of MathJax semantics this was too hard to discover.
- The requirement to have no space between equation delimiters ($) and the equation body (intended to reduce parsing ambiguity) was also confusing for users.
- We want to eventually support ASCIIMath and for this will require an additional qualifier to indicate the equation format.
RStudio v0.96.227 implements the new MathJax syntax and is available for download now.
7 comments
Comments feed for this article
May 27, 2012 at 10:17 pm
jeromyanglim
I’m really enjoying the work you are doing with R Markdown.
That said, personally, I preferred the original $…$ syntax. It was consistent with LaTeX documents (e.g., you can copy and paste formulas easily), consistent with Mathjax and Markdown on Stack Exchange sites, and consistent with the typical configuration of Mathjax on blogs and websites. The new $latex format is also more verbose especially when there are a lot of inline mathematics.
That said, I can understand that it was causing problems, especially for users unfamiliar with Mathjax. I wonder whether an alternative solution would be to have an option regarding configuration of MathJax (although I understand that the whole point of MathJax in RStudio is to keep things clear and simple).
Ultimately, it would be nice if the process in R Studio was more explicit about the commands that are called, so that any R Markdown document could be readily shared with others who don’t have RStudio installed. For example, I’m still not sure how I would issue commands in a makefile to replicate the functionality of knitr and RStudio’s markdown to HTML conversion.
May 28, 2012 at 7:10 am
jjallaire
Hi Jeromy,
Yes, I very much sympathize with your line of thought here. For that reason we didn’t take changing the syntax lightly. The biggest issue was that users not doing embedded math were mysteriously having (invalid) equations appear within their documents. It was of course possible to get out of this with \$ but if they weren’t aware of the $ $ syntax in the first place it wasn’t intuitive to even consider that two $ symbols (e.g. used for currency) might be the source of the problem.
For what it is worth, in changing the syntax we did try to remain consistent with prior art. The $latex syntax is actually the same one used by the wp-latex plugin (http://wordpress.org/extend/plugins/wp-latex/faq/).
In terms of doing R Markdown without RStudio, we are going to be releasing a v0.5 update of the markdown package (http://cran.r-project.org/web/packages/markdown/index.html) next week which will do what you are asking for. The current version of the package (v0.4) works however just renders HTML fragments. The new version will do full HTML pages with base64-encoded images, nice CSS, MathJax, and R syntax highlighting. The knit::knit2html function calls markdown::markdownToHTML so users you share you Rmd files with will only need to call one function in order to replicate the behavior of the RStudio Knit HTML button.
J.J.
May 28, 2012 at 7:27 pm
jeromyanglim
Thanks for the thoughtful response.
May 29, 2012 at 12:12 am
jeromyanglim
I also asked a question on StackOverflow about command-line options for migrating scripts from the old to the new mathjax format: http://stackoverflow.com/q/10792946/180892 I figured any answers might interest people reading this.
June 5, 2012 at 12:00 pm
Carl Boettiger (@cboettig)
The markdown support has been a great innovation, but I think a lot of that utility is lost when the syntax becomes inconsistent with other tools. For instance, the knitr book is a great example of how markdown can be used to create readable source-code that can be rendered nicely in github flavored markdown automatically compiled into a docx, pdf, or epub by pandoc-flavored markdown, displayed on a blog using jekyll, etc.
I understand that $latex is recognized by several wordpress plugins, but typically wordpress users are already using wordpress shortcodes and so their input isn’t pure markdown, if it’s markdown at all. It would be nice to keep something that is consistent with tools such as pandoc, or uses one of the many delimiters already implemented in the mathjax syntax.
My solution has been to use span/div around mathjax syntax in markdown files, which is ignored by most markdown parsers. Unrendered equations already aren’t very readable, so dropping back into html seems a conventional solution (though also not pandoc compatible…)
Thanks for the great work with the markdown package, etc, sorry to be a stick-in-the-mud.
June 8, 2012 at 4:55 pm
jjallaire
Thanks Jeromy and Carl for your feedback and patience with us as we sorted this out. We’ve just rolled out an update (v0.96.304) that includes a much more robust and flexible implementation of equation embedding.
We now support the traditional $ … $ syntax (with disambiguation constraints based on pandoc and org-mode) as well as the $latex $ syntax. All the details are here:
http://www.rstudio.org/docs/authoring/using_markdown_equations
Thanks again for your feedback and hope this works the way you’d like it to!
J.J.
June 12, 2012 at 12:27 am
jeromyanglim
Awesome. It’s great that we now have the choice of delimiters. This will make it a lot easier to work with both latex and markdown, and also to move between built in markdown to HTML compilation and other options like pandoc. I think the tight incorporation of equation support in RStudio is fantastic.