The Living Thing / Notebooks :


…and ΤeΧ, and ConTeXt and XeTeX and TeXleMeElmo

Beautiful typesetting with LaTeX (Thanks

See also citation management, text editors, diagrams, markdown.

The least worst mathematical typesetting system. One of the better scoured of the filthy pipes in the academic plumbing. De facto standard for mathematicians, especially those who are not so impertinent as to insist in writing in non-English languages, or are not so shallow as gainsay the simple delights in the painstaking handicraft of manually setting line breaks, or who have grad students who will deal with all that shit for free. That is, a tool which meets the needs of that endangered animal, the Tenured Academic, and that the rest of us survive.

Other alternatives include

  1. using MS Word, and
  2. stabbing your eyeballs with a pencil

… each of which I regard as similarly undesirable, and, to be clear, both even less desirable than LaTeX itself. Just because LaTeX is the best does not mean it is not also the least worst.

Addendum: No, thank you internet commentariat, but I am aware there are differences due to various different engines, formats, macro systems etc, giving us ConTeXT and LaTeX and TeX and pdfTeX and XeTeX and LuaTeX, and that they are all refreshingly different in their choices of pain-points, whether in in formatting, interoperation, character set handling, compatibility, preferred name capitalisation, or community support. I am cognisant of the buffet of failure cases I could choose from, if only in broad outline. However, standards lock-in being what it is, I believe I must avoid arranging the deckchairs of incremental improvement on this sinking ship. If I must do something, it will be to discretely wait over there, near the lifeboats, for some amped-up scholarly version of Markdown to come rescue me from the entire tiresome problem.


Eddie Smith, From boiling lead and black art: An essay on the history of mathematical typography; the only thing on this page you might conceivably read for pleasure.

Robert Kosara has an excellent rant:

The tools of the trade for academics and others who write research papers are among the worst software has to offer. Whether it’s writing or citation management, there are countless issues and annoyances. How is it possible that this fairly straightforward category of software is so outdated and awful?

Grad students, Robert, and their zero-marginal-cost labour. The same labour undervaluation that keeps slave economies from developing the steam engine.

Here is a more pious take by Graham Douglas, What’s in a name: a guide to the many flavours of TeX.

Cheat sheets

Latex Math Symbols.

Reverse LaTeX

Get LaTeX back from screen captures or even photos (!) of (formatted) equations Mathpix. They also offer a mathematical notebook, snips. Or sketch that one tricky symbol into detexify.

Or! Leave the machines behind! Train yourself in speed LaTeX transcription via the gamified math typing game TeXnique.


Vanilla TeX

I put this at the start of every file I touch.

% !TEX encoding = UTF-8 Unicode

then after the documentclass


Now, I can actually use utf8.

In practice this is smoother with XeLaTeX, which will require some additional declarations in order to function as expected, which for some reason are not set per default.

% Fix incommensurability of font sizes which per default is awful

This is not usually painful in modern LaTeX as such. However, the 💩 hits the fän if I try to use non-ascii ©haracters in BibTeX. I use BibLaTeX/biber instead. Sometimes a journal will advise against it but they don’t seem to notice if I ignore them, and it saves me much time.


Everything just works AFAICT. It’s incompatible with a couple of primordial packages which do various fake unicode hacks (like the ucs package) but I don’t think those are actually needed anyway.

If I decided to go hardcore unicode I could use unicode even for equations, via unicode-math.

With this package, changing maths fonts is as easy as changing text fonts — and there are more and more maths fonts appearing now. Maths input can also be simplified with Unicode since literal glyphs may be entered instead of control sequences in your document source.

This would grant me the power to change maths fonts easily. Also if I were to copy-paste equations from a PDF to LaTeX, they would be somewhat less mangled. The price is that it has certain quirks, e.g. with curly letters. Also, usually I do not typically have a choice of maths fonts because versions are stipulated in the style guide for the journal/conference/thesis I am writing. Therefore, while this is nifty, it adds burdens but brings insufficiently many benefits. The logic of collective action dictates I ignore it for now.

Include LaTeX in python

Generating arbitrary LaTeX in python scripts, jupyter notebooks, Pweave literate documents? Use an ingenious python script called using latex_fragment to ease your burden and render your latex fragments inline. It was written by that paragon of coding cleanliness, that tireless crusader for not-dicking-around, me.

from IPython.display import display_latex, display
import latex_fragment
l = latex_fragment.LatexFragment(r'\(x=y\)')

Note also that pandoc markdown already includes LaTeX support for LaTeX output.

Other options include inverting this setup, and including python in LaTeX via an executable notebook such as knitr.

Make TeX run like a normal unix program

As opposed to the default, a pointless error-interaction-mode-that-briefly-seemed-useful-in-the-80s.


pdflatex -interaction=nonstopmode -halt-on-error


pdflatex -interaction=batchmode

Putting dates in your drafts

I’m sure there must be a better way of doing this. Certain document classes (all?) have draft modes.


A universal (not document-class-dependent) option was suggested by the Malaysian LaTeX User Group, Putting Dates in Watermarks:

\usepackage{draft watermark}
\SetWatermarkText{Draft\[email protected]\DTMnow}

This may neccessitate

tlmgr install draftwatermark everypage datetime2 etoolbox tracklang


Managing spacing is the major reason for existence for LaTeX. Thus is is curious how fragile and unintuitive it is. Here is a comprehensive guide to LaTeX spacing by Werner.

Death-or-define macro

Death-or-define is how I think of the trick to force a macro definition redefinition even if there is no definition to be redefined – handy if I am rendering latex from some tricky source such as jupyter, or where I don’t have control over the overall document outside my section but don’t care about wreaking havoc on my collaborators; some other poor sap can deal with the macro mutation weirdness.

\renewcommand{\foo}[1]{bar: #1}


There are two dominant ways to insert emoji into laTeX.

You can try a dirty, shiny hack to include color emoji as images.

Hello, 🌎.

Elegant but less colourful, XeTeX has native monochrome emoji via DejVu Sans.


\newfontfamily\DejaSans{DejaVu Sans}
\newcommand\todo{{\color{green}\DejaSans 🚧}}

  \todo mention {\DejaSans 😁😂😃😇😉😈😋😍😱}


Convention dictates explaining your algorithm with pseudocode. This obviates the problem of the uncertain semantics of particular programming languages, by replacing them with the semantics of no programming language at all.

There is a confusing profusion of options for doing this and they are all, IMO, inadequate, since none of them allow me to typeset higher order functions naturally, and that is an old and thoroughly mainstream idea. This means, for example, that it is hard to typeset automatic differentiation.

tl;dr: I use

How this looks:

\usepackage[noend]{algpseudocode}  % skip EndFor etc
\usepackage{algorithm}   % custom floats
    \caption{Euclid’s algorithm}
    \begin{algorithmic}[1] % The argument is the first line number
        \Procedure{Euclid}{\(a,b\)} \Comment{The g.c.d. of a and b}
            \State \(r\gets a \bmod b\) \label{init}
            \While{\(r\not=0\)} \Comment{We have the answer if r is 0}
                \State \(a \gets b\)
                \State \(b \gets r\)
                \State \(r \gets a \bmod b\)
            \State \textbf{return} \(b\)\Comment{The gcd is b}

Algorithm line label references look like


If I am running minimalist TeX I need

tlmgr install algorithmicx algorithms

or I can do without algorithms if I do


Or perhaps I wish to typeset real code in a real language? minted enables this, allowing colour-highlighted math-enabled code rendering, bringing to LaTeX documents the conveniences that have been available to everyone else for some decades now.

There are alternatives. algorithms provides algorithmic and seems to be fairly common and also fairly interchangeable. Neither of these packages have been updated in a decade, so they are both suspicious, but they work OK.

program does pseudocode formatting but with very different syntax and styling. It looks nice but I don’t use it as it’s less compatible with the other major players algorithmic so the odds of being able to copy and paste are low.

IDs (ORCID, DOI etc)

AFAICT, at the basic level you create a hyperlink, e.g.

}{Dan MacKinlay }

But what if I want the fancy logo so that everyone knows I cleverly did the ORCID thing? If I am using some benighted conference stylesheet from the 90s this is unlikely to work. But for a more modern situation (e.g. IEEE is usually current) I might be able to get an attractive green logo. I have made this work with the academicons package, which gets the logo via a custom font.

Then, for example ORCID is set up, in the preamble:


and in the body

\item \href{
}{Dan MacKinlay \hspace{2mm} \textcolor{orcidlogocol}{\aiOrcid}  }

Installing TeX

With special emphasis on installing only the needful things.

MacTeX or MikTex or TexLive or whatever waste your hard disk space if you install the whole gigantic thing. 5Gb for a 1980s typesetting system is cheeky, especially from people who delight in claiming that Microsoft Word is over-engineered, and that they are keeping it serious with their svelte, elegant, professional alternative. But LaTeX is not “serious typesetting”, except in the sense that driving a panzer to work is “serious commuting”. (In this metaphor, Microsoft Word is some kind of polka-dotted clown car, as far as mathematics is concerned.)

However! You can install only what you need using a so-called “minimalist” distribution. (Which is still hundreds of megabytes, but we are going to have to take what breaks we can here.)

Manual BasicTeX

The most generic way of doing this on macOS is to install basictex.

A gotcha for this method is that it only works for one year, then you must start over. Then I get cut off from updates, and have to do a crazy tedious procedure to get another year’s life out of TeX.

It seems you can possibly get rolling incremental updates with homebrew-installed TeX or TinyTex but I haven’t tested this personally with an actual rollover.


If you are an R user, there is tinytex, a semi-managed minimalist LaTeX distribuiton which will automatically install what given R packages need.


You install things via


or using tlmgr as usual

It includes build helpers, e.g.


Homebrew TeX

On macOS at least, this command installed minimal TeX.

brew cask install basictex

There is also a maximal install for the bloody-minded.

brew cask install mactex

Distro package maanger

One can install the tex-full or similarly-named distribution

It’s a mess otherwise, since only supports releases for one year (and an Ubuntu distro is supported for much longer, so likelihood is that you will rapidly find your Ubuntu-supported texlive no longer compatible with the texlive-supported tlmgr without a major OS upgrade.)

Docker TeX

All this TeX wrangling seems depressing and time-wasting. You can side-step some details by running containerized tex, and just ignore a lot of the nonsense. (Not the hard disk space wastage and bloat; that is kind of built-in.) blang/latex-docker is one set of such dockerfiles with a good reputation. There are some newer ones, e.g. schickling/latex, about which I know yet less.

Installing TeX packages

Ok, so if I have installed a possibly minimal TeX, I isntall things as needed, using the TeX package management system tlmgr.

For example, to render jupyter notebooks, I found I needed:

tlmgr install \
    adjustbox \
    collectbox \
    collection-fontsrecommended \
    enumitem \
    logreq \
    ucs \

There are more examples of dependency sets below.

In addition to the basic system install, on Debian/Ubuntu I needed set it up via:

tlmgr init-usertree

and possibly also:

sudo apt-get install xzdec

If that doesn’t work you might need alternate methods such as manual install, or TinyTex, documented below.

When I am not sure precisely which teX package I need but I do know the same of a file which is missing, e.g. times.sty, the following command will find me candidates.

tlmgr search --global --file "/times.sty"

Weird errors can arise in this manual method. When I got .fmt made by different executable version, the following magical incantation seemed to fix it.

sudo fmtutil --all


sudo fmtutil-sys --all

I keep the installation up to date using the following incantation:

tlmgr update --self --all
tlmgr path add
fmtutil-sys --all

Alone amongst all the packages I have tried, biber, the biblatex executable, seems to want special care, and its symlink is not correctly created by tlmgr.

tlmgr install biber
ln -s ~/.TinyTeX/bin/x86_64-linux/biber ~/bin/biber

Example minimalist TeX dependencies

To handle fancier jupyter notebook via ipypublish, we also need

tlmgr install \
    latexmk \

To handle biblatex:

tlmgr install biblatex

To handle modern referencing:

tlmgr install placeins \
    todonotes \
    chngcntr \
    doi \
    mdframed \
    needspace \

To handle pandoc:

tlmgr install amsfonts \
    amsmath \
    lm \
    unicode-math \
    ifxetex \
    ifluatex \
    listings  \  # (if the --listings option is used)
    fancyvrb \
    longtable \
    booktabs \
    graphicx \
    grffile \
    xstring \
    logreq \
    biblatex \  # if biblatex is used
    biber \  # if biber is used
    fontspec \  # if xelatex or luatex
    polyglossia  \  # if xelatex
    xecjk \  # if xelatex
    bidi   # if xelatex

To handle Anki flashcard rendering:

tlmgr install bbm-macros \

To handle latex_fragment:

tlmgr install standalone \

To handle .eps files.

tlmgr install epstopdf

To handle Tom Pollard’s markdown thesis:

tlmgr install truncate \
    tocloft \
    wallpaper \
    morefloats \
    sectsty \
    siunitx \
    threeparttable \
    l3packages \
    l3kernel \

To format orcid references:

tlmgr install academicons

Looking nice

Templates such as the famous Legrand Orange Book and other modern-looking things can be found online at e.g.

No TeX at all

You just want equations? You don’t need TeX-the-software, just TeX-the-markup. Lots of things can render TeX math. In particular if you have an HTML or a markdown document with mathematical markup, many mathematical typesetting options are available. In fact, too many, all with incompatible syntax of course. The de facto standard is pandoc, which is what I usually use for turning my markdown+math into various documents (including, for example, parts of this blog).


MathJax allows you to put LaTeX equations online easily without bothering with the rest of that bullshit.


Katex is a faster competitor to MathJax, but is not yet as widely supported. Katex even eliminated another pain point, having supported macros since 0.10.rc1. You couldn’t define macros inline which was tedious because macros are ubiquitous in real mathematics work. Now you can either inject them via config, or use the esoteric low-level \gdef to get LaTeX-like behaviour, since \renewcommand exists but doesn’t persist between equations, which makes it pointless for anything except prototyping individual macro definitions. KaTex support of maths markup is not as complete as MathJax. In particular

Inlined HTML mathematics

Both MathJax and KaTeX are eventually slow if you have enough equations in a document - MathJax sooner than KaTeX, but neither scales to the documents I write as a mathematician. You ideally want something different. There are a few attempts to do this.

bookish is a project by parser nerd Terrence Parr which, like my latex_fragment, translates TeX markup to SVG, but in addition works out how to align the SVG with text correctly via herculean effort.

This approach is shared with Daan Leijen’s Madoko (introductory paper), which does math rendering in PDF or HTML as embedded SVG.

Both these last 2 projects took the unusual step of not using the de facto standard for markdown/academia, pandoc, in favour of implementing their own new engines.

Amazingly, despite pandoc already employing a somewhat obscure academic functional language (Haskell), Makodo chose an even obscurer academic functional language, koka. At least his one compiles to javascript, so I guess it’s not totally alien territory. Nonetheless… Anyway, it also includes some nifty publish-to-the-web features, and citation support, so maybe you don’t care about this obscurity.

There is another school of methods of rendering mathematics in HTML, which is the school who note that you can render MathJax without a browser using node.js, saving some time for the reader who need not mess around with a complicated post hoc multi-phase javascript-based rendering procedure. Presumably this could be implemented for KaTeX too. The tool du jour is MathJax-node-page which comes with a CLI mjpage which will pre-render HTML for you—it even claims to render math as SVG too, through forbidden magic into which it is best not to enquire too closely. See also mathmd. Wikipedia aims to leverage this approach via their mathoid project.

There are some full-pipeline tools which leverage this. The one that looks shiniest is ReLaXed, which also makes the case for their take on this approach

Many of us prefer markup languages (Markdown, LaTeX, etc.) to GUI document-editors like MS Office or Google Docs. This is because markup languages make it easier to quickly write documents in a consistent style.

However, Markdown is limited to the title/sections/paragraphs structure, and LaTeX has obscure syntax and errors that also make it difficult to stray from the beaten track.

On the other hand, web technologies have never looked so good.

ReLaXed is an attempt at finding the most comfortable way to leverage this for desktop PDF creation.

However, I need citations in my workflow, and it is not immediately clear how I would inject those into such an end-to-end solution, at least not without writing yet another plugin— however, possibly Zotero could help with its HTML citation reports or maybe one of the word processor plugins supports HTML documents? It merits investigation. Not by me.

Gerby looks to be somewhere intermediate between a new markup language and HTML presentation; it generates a large indexed website from a latex document instead of a PDF.

If you have a LaTeX document which

you will run into the problem that

Gerby addresses these problems by providing an online tag-based view, instead of just having a big PDF. Gerby is tailored towards making large online textbooks and reference works more accessible.


Native web rendering of mathematics is provided by MathML, but it is supported, more or less, only in Firefox, and also is an ugly syntax to write by hand. It’s more of a display backend for LaTeX math, or for some kind of equation editor. Unless this is more widely taken up I won’t be investigating it for my own use. In particular, I don’t know how fast it is, which is the major pain point with the javascript-based options. There are utils to convert LaTeX math to MathML, e.g. [Texzilla], or LaTeXML, which I have not tried.

Mathematical hacks

Math size

I forget this all the time. Explained by overleaf, Math font size ordering is

\displaystyle       % Size for equations in display mode
\textstyle          % Size for equations in text mode
\scriptstyle        % Size for first sub/superscripts
\scriptscriptstyle  % Size for subsequent sub/superscripts

Defining new operators

Without Limits

i.e. limits on the side, \({\mathop{\mathrm{sech}}\nolimits}^2 x.\).

Plain style (works everywhere including old MathJax):


amsmath style (works in AMSMath environments):


With Limits

i.e. limits underneath \({\mathop{\rm arg\,max}}_{x\to\infty} x\).

plain style:

\newcommand{\sech}{\mathop{\rm sech}\limits}

amsmath style:




Martin H says, on including SVG in TeX, that the smoothest route is to convert the SVG into PDF+tex, as per Johan Engelen’s manual:

inkscape -D -z --file=image.svg --export-pdf=image.pdf --export-latex

Then invoke using

    \def\svgwidth{\columnwidth}   % sets width of next svg image

This can be automated using the svg tex package.


PGFPlots is a native diagramming/plotting package which supports PDF output.

See also general diagrams and scientific workbooks.


Why are there so many editors for LaTeX? They all seem reasonably interchangeable in terms of features. I just use whichever one I can remember the name of at the time.

Ideally I’d like easy TeX rendering from within my normal editor vs code but there are always weird friction points so I’ve given up on that for now.


texshop is the open-source stalwart editor on macOS. It makes reasonable progress towards being intuitive. Its name is in my muscle memory. Configure document setting via magic comments.

% !TeX encoding = UTF-8
% !TeX program = xelatex
% !BIB program = biber


The TeXWorks project is an effort to build a simple TeX front-end program (working environment) that will be available for all today’s major desktop operating systems—in particular, MS Windows (7/8/8.1/10), typical GNU/Linux distros and other X11-based systems, as well as Mac OS X. It is deliberately modeled on Dick Koch’s award-winning TeXShop for Mac OS X, which is credited with a resurgence of TeX usage on the Mac platform.

It’s minimalist, shipping without a billion typesetting macros, which is both a plus and a minus. I like minimalist, but also I don’t want to have to remember every bloody latex command.

Bizarre bonus feature: you can script it using javascript.


TeXStudio is an integrated writing environment for creating LaTeX documents. Our goal is to make writing LaTeX as easy and comfortable as possible. Therefore TeXstudio has numerous features like syntax-highlighting, integrated viewer, reference checking and various assistants. For more details see the features.

TeXstudio is open source and is available for all major operating systems.

Fun fact: This was forked from TexMaker ten years ago.

TexStudio has a million features. The UI is an exercise in brutalist maximalism and excessive featuritis, but it does do more or less everything you want. Many LaTeX macros, which is handy. Also heaps of stuff you will never want and wish would stop crowding your menu? Extensive built-in SVN support? yep.

Amazing feature: has image drag-n-drop support.

The manual buries the lede, but TeXStudio does support setting the compile parameters per-document via magic comments. E.g. put this at the start of your document to set it up with modern encoding and bibliography support:

% !TeX encoding = UTF-8
% !TeX program = xelatex
% !TeX TXS-program:bibliography = txs:///biber
% !BIB program = biber


Tex Maker is a free, modern and cross-platform LaTeX editor for linux, macosx and windows systems that integrates many tools needed to develop documents with LaTeX, in just one application. Texmaker includes unicode support, spell checking, auto-completion, code folding and a built-in pdf viewer with synctex support and continuous view mode. […] Texmaker is released under the GPL license.

VS Code & LaTex-Workshop

LaTeX-Workshop is the de facto standard VS Code LaTeX extension. Originally I was not a fan because despite having many features it ended up being confusing when things went wrong. (Where WAS that syntax error?)

The new version is much better; you just need to make sure the little TeX sidebar is active and everything becomes apparent. Now it provides nearly as good a LaTeX preview experience as, say, TeXshop, similar TeX integration and superior text editing, and is worth trying.

It doesn’t support XeTeX or latexmk -pdf per default; you need to write a new “recipe”, and presumably keep the old ones too? The result is lengthy. I haven’t tested the latexmk ones since latexmk is not installed on my campus machine.

    "": [
            "name": "latexmk 🔃",
            "tools": [
            "name": "xelatexmk 🔃",
            "tools": [
            "name": "platexmk 🔃",
            "tools": [
            "name": "pdflatex ➞ bibtex ➞ pdflatex`×2",
            "tools": [
            "name": "xelatex ➞ biber ➞ xelatex",
            "tools": [
    "": [
            "name": "latexmk",
            "command": "latexmk",
            "args": [
            "env": {}
            "name": "platexmk",
            "command": "latexmk",
            "args": [
            "env": {}
            "name": "xelatexmk",
            "command": "latexmk",
            "args": [
            "env": {}
            "name": "pdflatex",
            "command": "pdflatex",
            "args": [
            "env": {}
            "name": "xelatex",
            "command": "xelatex",
            "args": [
            "env": {}
            "name": "bibtex",
            "command": "bibtex",
            "args": [
            "env": {}
            "name": "biber",
            "command": "biber",
            "args": [
            "env": {}

You can then choose a recipte for a given porject by setting the workspace variable workshop.latex.recipe.default.


atom-latex and the atom latex package both bring LaTeX support to the Atom editor though I haven’t worked out the difference. The latter supports literate coding so is morally superior I suppose.


Mathematica can export mathematics to TeX and is a good, if colossally overengineered, editor for equations. It has the bonus power to automate many tedious steps of working, and the disadvantage of being Mathematica.


LyX is a document processor that encourages an approach to writing based on the structure of your documents (WYSIWYM) and not simply their appearance (WYSIWYG).

LyX combines the power and flexibility of TeX/LaTeX with the ease of use of a graphical interface. This results in world-class support for creation of mathematical content (via a fully integrated equation editor) and structured documents like academic articles, theses, and books. In addition, staples of scientific authoring such as reference list and index creation come standard.

This graphical editor thing is a noble goal but TBH not my top priority, and seems to never support quite the features that I would use and thus it is dead to me.


TeXmacs is another WYSIWYM thing – if you want to integrate a beautiful but obscure and irregularly maintained notebook-style interface with your typesetting. Some do.

Once again, I’d rather use knitr etc for integrating my diagrams and keep the GUIs separate, but this is personal preference.


Posters HOWTO.

a0poster is popular, as expounded by Morales de Luna, but I secretly feel that it sounds like a nightmare of legacy postscript nonsense and doesn’t even look good. sciposter is a popular a0poster variant.

tikzposter and beamerposter are both highlighted on sharelatex and are truly fugly. Why would anyone who claims to care about design inflict this on the world?


IEEE style specialties

IEEEtran stylesheets have some special equation formatting noûs.

\begin{IEEEeqnarray}{rCl}Z&=&x_1 + x_2 + x_3 + x_4 + x_5 + x_6\IEEEnonumber\\&&+\:a + b%\end{IEEEeqnarray}