Math in reStructuredText with LaTeX

Question

I would like to use a lightweight markup language to take notes in my college classes.

My editor of choice is gedit, and I found reStructuredText Tools for Gedit, which will run the reStructuredText processor and render the HTML in a pane in gedit. This is great, and 80% of the way there.

But for many of my classes I need to include math equations or greek characters in my notes. Although I'm not very familiar with LaTeX, my understanding is that it has these capabilities.

How can I use LaTeX in a reST document? Would the reST document need to be processed into LaTeX, then that rendered into HTML, or is there a better way? Would markdown make this easier? I can modify the gedit plugin if necessary.

Lastly, does anyone do this? Any other suggestions for taking class notes in a plain text editor?

Thanks!

Answer 1

LaTeX and ReST are two solutions to the same problem (whole-document markup), and I'm not sure that one would be happy living inside the other.

• LaTeX first, then ReST: LaTeX needs to precisely position typographical elements in order to lay out equations (and everything else). ReST wouldn't take the LaTeX output (PostScript or similar) as input.
• ReST first, then LaTeX: You'd have to write an output formatter for ReST that output LaTeX code, and define extensions in ReST to prevent it from misinterpreting your equations or other explicit TeX. Your output from LaTeX will still be something akin to PostScript or PDF.

I've seen code for using a subset of TeX to generate a graphic equation which is then pulled into HTML or similar (for example,Trac's LaTeX Formula macro), which may be the best available solution.

Answer 2

The problem is that reST doesn't really have plugins. You might choose an extensible framework such as Sphinx; a plugin for JSMath is already included, and a plugin for MathJax is also possible. Additionally Sphinx makes use of LaTeX to directly build PDF documents.

Another more lightweight solution consists in editing the reST template to include MathJax so that you can just use MathJax's (LaTeX-like) syntax in the document.

But usually I just use LaTeX directly for anything serious—the customization capabilities of these lightweight markup languages just aren't comprehensive enough for everything.

Answer 3

Pandoc's markdown extension permits inline or display LaTeX math; you just put it between (immediately adjoining) dollar signs like so: $\sqrt{-1}$'s and it's treated as you'd expect. I use this feature all the time, and don't think it's impractical at all. See the manual http://johnmacfarlane.net/pandoc/README.html#math

Once the markdown is parsed, pandoc can write HTML, LaTeX, ReST, RTF, DocBook, ODT, manpages etc., etc. If a LaTeX math context does not involve fancy LaTeX packages, it can even parse the math into MathML, so it renders immediately in HTML or RTF. (It supplies a number of options for dealing with LaTeX math in non-LaTeX documents.)

Pandoc also parses ReST (and HTML, and not-too-fancy LaTeX). I had thus hoped to give a solution involving the ReSt reader, but it seems to have no special machinery for dealing with math; see the discussion of issue 249 http://code.google.com/p/pandoc/issues/detail?id=249 I will study again more closely to see.

I don't think anyone has cooked up a pandoc plugin for Gedit yet (there is elaborate support in emacs and in TextMate, I know) -- that would be awesome!

Answer 4

This item from the Docutils FAQ describes one way to relatively easily include TeX math. You first define a role for interpreted text that passes the equation through directly to LaTeX:

.. role:: raw-latex(raw)
    :format: latex

Then you can use that role in your text

The area of a circle is :raw-latex:`$\pi r^2$`

The FAQ entry also mentions a few other ways to do this, including a preprocessor approach that can be used to render the math to an image when generating HTML.