This post collects some notes on using LaTeX to render mathematical documents and formulae, mostly focused on a Linux machine. For background, I typically use LaTeX for one of two (related) purposes:

  1. Render math for my blog posts, which are usually written using reStructuredText. This sometimes includes diagrams generated using TikZ.
  2. Write personal (unpublished) notes on math-y subjects entirely in LaTeX. These are typically short (up to 10-20 pages), single-subject booklets.

I don't currently use LaTeX for either precise typesetting or for authoring very large, book-sized documents.

Editing

For day-to-day authoring, I find TeXstudio to be excellent. It has everything I need for local editing with a convenient preview window. I really like that TeXstudio doesn't hide the fact that it's just a graphical veneer on top of command-line LaTeX tooling, and lets you examine what it's doing through logs.

Note that web-based solutions like Overleaf exist; I can see myself using that, especially if collaborating with others or having to author LaTeX from a diverse set of computers and OSes, but for local editing of git-backed text files, TeXstudio is great.

Converting to other formats with pandoc

pandoc is very capable for converting documents from LaTeX to other formats. Recently I find that it's easier to write math-heavy blog posts in LaTeX, and then convert them to reStructuredText with pandoc.

For example, the recent post on Hilbert spaces was written like this and then converted using this command:

$ pandoc -f latex -s -t rst hilbert.tex

The resulting reStructuredText is very readable and requires very little tweaking before final publishing. pandoc supports many formats, so if you use Markdown or something else, it should work similarly well.

Rendering standalone formulae or diagrams

A useful feature of LaTeX tooling is the ability to render a specific formula in standalone mode to an image. We can write the formula into its own file (call it standaloneformula.tex):

\documentclass[preview]{standalone}
\usepackage{amsmath}
\begin{document}
\(
\int_{-\infty}^\infty e^{-x^2}\,dx=\sqrt{\pi}
\)
\end{document}

In case you were wondering, this is the Gaussian integral:

\[\int_{-\infty}^\infty e^{-x^2}\,dx=\sqrt{\pi}\]

Once we have that standalone .tex file, there's a number of things we can do. First, the texlive package should be installed [1]. Using apt:

$ sudo apt install texlive-full

Now, we can run the tools from texlive, for example pdflatex:

$ pdflatex standaloneformula.tex

This creates a PDF file that's useful for previews. To convert the .tex file to an image in SVG format, we'll use a two-step process:

$ latex standaloneformula.tex

... generates standaloneformula.dvi

$ dvisvgm standaloneformula.dvi

... generates standaloneformula.svg

If we want a PNG file instead of SVG:

$ dvipng -D 300 standaloneformula.dvi

The latexmk tool can build a .tex file into a PDF whenever the input file changes, so running:

$ latexmk -pvc standaloneformula.tex

And opening the PDF in a separate window, we can observe live refreshes of edits without having to recompile explicitly. While useful in some scenarios, I find that TeXstudio already does this well.

The same tooling flow works for TikZ diagrams! A standalone LaTeX document containing a single tikzpicture element can also be rendered to a SVG or PNG using the same exact commands.

Docker versions

If you'd rather not install all these tools directly but use Docker instead, the texlive image can be used to do the same things:

$ docker pull texlive/texlive:latest

And now we can use the same invocations, just through docker:

$ docker run --rm -u $(id -u):$(id -g) \
    -v "$PWD":/workdir -w /workdir texlive/texlive:latest \
    latex standaloneformula.tex

$ docker run --rm -u $(id -u):$(id -g) \
    -v "$PWD":/workdir -w /workdir texlive/texlive:latest \
    dvisvgm standaloneformula.dvi

Positioning of formulae embedded in text

When a formula like \frac{n+1}{n^2-1} is embedded in text, it should be aligned properly to look good with the surrounding text. The information required to do this is emitted by tools like dvisvgm and dvipng; for example:

$ dvisvgm standaloneformula.dvi
pre-processing DVI file (format version 2)
processing page 1
  computing extents based on data set by preview package (version 14.0.6)
  width=81.267395pt, height=9.86894pt, depth=4.388947pt
  graphic size: 81.267395pt x 14.257887pt (28.562223mm x 5.011074mm)
  output written to standaloneformula.svg
1 of 1 page converted in 0.147623 seconds

Note the height=..., depth=... line in the output. The height is the total height of the formula, and depth is its height below the "baseline" (how much down it should stick out from the line). In my blog, these two are translated to attributes on the image element embedding the SVG. Height is translated to style="height: ... and depth to vertical-align: ....


[1]If the machine already has TeXstudio installed, texlive is almost certainly installed as well.