LaTeX

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



fun.fnord.eu, Beautiful typesetting with LaTeX

The least worst mathematical typesetting system. One of the better scoured of the filthy pipes in 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 for free. That is, a tool which provides comfort for that endangered animal, the Tenured Academic, and tolerable usefulness for the rest of us.

Other alternatives include

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

… each of which I regard as similarly undesirable as the other, and, to be clear, both somewhat less desirable than LaTeX itself.

History

Standard disclaimer, before diving into the otaku-zone TeXonomy:

I am also aware that here I am doing violence to the rich and storied ecosystem by failing to mention that almost everything I mention here is but a macro system built upon Knuth’s OG TeX system. Even that is a crude simplification of the complicated truth that his original system has evolved, reimplemented and mutated in complex and subtle ways. However, this document is not a philological exploration; it is a pragmatic guide to getting documents typeset before key deadlines pass. Nonetheless some context is occasionally helpful.

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.

Wasn’t that nice. Now, let Robert Kosara rant about where this has evolved to:

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 the low-marginal-cost, low quality labour of grad students. The same labour undervaluation that keeps slave economies from developing the steam engine. As long as it is cheaper to solve typesetting problems with grad student labour, the system can shamble forward without anyone being incentivised to fix it for everyone else. Side effect: grad students also have underdeveloped software development skills and will never return to remedy the engineering mistakes of their younger selves. This will keep the average quality of the pieces of this system mediocre.

There are also standards-lock-in problems; even if someone develops a better system, will conferences and journals find it worthwhile to switch? Or will they let the old system shamble on knowing it will cost their editorial board nothing to waste everyone else’s time? Even the authors: will a newer better system be good enough to justify the cost of learning it? Will it be robust enough to last long enough that it repays its cost? Cf Moloch.

Variants

There are differences in 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 unique in their choices of pain-points, whether in formatting, interoperation, character set handling, compatibility, preferred name capitalisation, or community support. Here is a more pious take by Graham Douglas, What’s in a name: a guide to the many flavours of TeX. For now I will construe LaTeX broadly, which is to say “in principle any of these LaTeX-like engines”, which is to say ”in practice any LaTeX engine which is sufficiently similar to the baseline horror to survive the submission process to arxiv.org”.

I am indeed cognisant of the diversity and richness of buffet of failure cases I could choose from, if only in outline. However, standards lock-in being what it is, I will for now avoid arranging the deckchairs of incremental improvement on this sinking ship of legacy mess. If I must innovate, it will be to discretely shuffle over there, to the lifeboats, in which I will wait for some disruptive scholarly version of Markdown to come rescue me from LaTeX entirely.

Installing TeX

See LaTeX installation.

Reverse LaTeX

Getting LaTeX code back from screen captures photos of (formatted) equations. Rebekah Yates reports

  1. You can look things up in the Comprehensive LaTeX symbols list. It can usually be easily accessed with texdoc symbols or texdoc symbols-a4 (in MiKTeX the latter only).
  2. Another good option is to try the web-based software Detexify, which allows you to draw the symbol and tries to recognize what you’ve drawn.[…]
  3. If you are using the package unicode-math, then besides using any Unicode character list, the list of all supported symbols (texdoc unimath-symbols) is very useful as it also lists which symbols are available in the various fonts.
  4. Using unicode-math, you can also search for characters by drawing (just like with detexify) using ShapeCatcher.

Frontrunner: Mathpix. They also offer a mathematical notebook, snips.

Or! Leave the machines behind! Train yourself in speed LaTeX transcription via the gamified mathematical typesetting training system TeXnique.

Invocation

Run like a normal unix program

Per default TeX runs in an “interactive mode”, which makes usually pointless efforts to solicit my advice about badly explained syntax errors, and offers me a chance to fix them? I guess? I have never tried; why would I want to? This probably dates to some time in the 80s when users were billed per-command-line-invocation or something, and is utterly contrary to modern expectations. Anyway, here is how we get Normal-unix-halt-on-failure-with-helpful-message:

pdflatex -interaction=nonstopmode -halt-on-error

Or: Bloody-minded-compile-my-document-at-all-costs-I-don’t-care-how-it-is-broken:

pdflatex -interaction=batchmode

latexmk

The tool that makes a best-effort attempt to couple together the clanking chain of components that turn those text files into documents. It has various command-line options in the manual but examples are more explanatory to me.

See latexmk options and nomenclature. See also the latexmkrc files that it comes with for examples of advanced configuration.

🤓 oooh! I can set up latex as an automatically updating dynamical preview, even with synctex, as a poor-man-interactive-editor.

latexmk -pvc

Include in python

Generating arbitrary LaTeX in python scripts, jupyter notebooks, Pweave literate documents? For that I use an ingenious python script called using latex_fragment to ease my burden and render my 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\)')
display(l)

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

Other options include inverting this setup, and injecting python into LaTeX via an executable notebook such as knitr,

I leveraged this to make a latex renderer called latex_fragment which you should totally check out for rendering inline algorithms, or for emitting SVG equations.

Alternatively one can use the inbuilt jupyter LaTeX renderer:

#%%
from IPython.display import Latex
Latex(r'''$x=y$''')

Strikethrough

a.k.a. strikeout. Jan Söhlke says

\usepackage[normalem]{ulem}

\sout{text to be striked out}

Putting dates in drafts

Certain document classes (all?) have draft modes.

\documentclass[draft]{article}

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

\usepackage{draft watermark}
\usepackage{datetime2}
\SetWatermarkLightness{.9}
\SetWatermarkText{Draft\string@\DTMnow}
\SetWatermarkScale{.3}

On a minimalist TeX system, this may necessitate

tlmgr install draftwatermark everypage \
  datetime2 etoolbox tracklang

Spacing

Managing spacing between symbols is the major reason for existence for LaTeX. It is a hard problem, optimising for legibility of symbols on a sheet of paper for all the various sorts who might read it. One must solve for the goal of minimising the number of criticism of grumpy aesthetically-challenged pedantic folk-typographers each of whom has a different, incompatible list in their mind of what in constitutes an unspeakable crimes against legibility. Thus there are many compromises, tricks, edge-cases and other potholes to get your foot stuck in, especially in mathematical mode.

As far as individual mathematical characters goes, here is a comprehensive guide to LaTeX mathematical spacing by Werner. tl;dr if things look weird I can convert a mathematical character to an “ordinal” by wrapping it {=} and add my own manual spacing back in and it will work nicely. When that is not suffiicent, Overleaf’s Spacing in math mode is what I most often need:

\begin{align*}
f(x) &= x^2\! +3x\! +2 \\
f(x) &= x^2+3x+2 \\
f(x) &= x^2\, +3x\, +2 \\
f(x) &= x^2\: +3x\: +2 \\
f(x) &= x^2\; +3x\; +2 \\
f(x) &= x^2\ +3x\ +2 \\
f(x) &= x^2\quad +3x\quad +2 \\
f(x) &= x^2\qquad +3x\qquad +2
\end{align*}

\[ \begin{align*} f(x) &= x^2\! +3x\! +2 \\ f(x) &= x^2+3x+2 \\ f(x) &= x^2\, +3x\, +2 \\ f(x) &= x^2\: +3x\: +2 \\ f(x) &= x^2\; +3x\; +2 \\ f(x) &= x^2\ +3x\ +2 \\ f(x) &= x^2\quad +3x\quad +2 \\ f(x) &= x^2\qquad +3x\qquad +2 \end{align*} \]

K. Cooper’s even more comprehensive LaTeX Spacing Tricks is the guide for almost every type of spacing civilians will need.

To manage justification, a.k.a. text alignment, generally (Why is everything fully justified per default? It makes the spacing so ugly, at least to this aesthetically-challenged pedantic folk-typographer) one needs the \raggedright/\centering etc commands, or even the ragged2e package. See the Overleaf documentation and wikibooks.

PRO-TIP: \RaggedRight and friends destroy paragraph indentation. The fix is to restore the indent:

\newlength{\saveparindent}
\setlength{\saveparindent}{\parindent}
\RaggedRight
\setlength{\parindent}{\saveparindent}

Or you could do what a real typographer would do and put space between paragraphs, which might require some style updates.

I use RaggedRight spacing to make it easier to proofread, but generally and will be reverting to fully justified after the proofreading process, so you can ignore this problem and delete the RaggedRight directive later. This has advantages, IMO

  1. Editors will not complain about everything not being fully justified
  2. Will be harder to reviewers to read, improving chances that they will not detect mistakes and will recommend publication.

long documents

subfiles is a handy package for Multi-file LaTeX projects.

\documentclass[../main.tex]{subfiles}

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 mutations Mwahahaha.

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

Algorithms

Need to explain an algorithm? If you are permitted to list real source code, this is possible via the listings. I have yet to encounter a journal or conference that endorses this however.

Convention dictates explaining an 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 all options are, IMO, inadequate, since none of them allow me to typeset higher order functions naturally, and that is an old, thoroughly mainstream idea that I use a lot. This means, for example, that it is hard to typeset automatic differentiation. But who would need that? Anyway, this is a sub problem which I can awkwardly work around like everyone else.

tl;dr: I use

  • For formatting,

    • algorithmicx + algpseudocode (a nice default syntax that comes with algorithmicx).
    • Or algorithms which comes with only one syntax, but everyone knows is
  • inside an algorithm float.

algorithmicx

How this looks:

\usepackage{algorithmicx}
\usepackage[noend]{algpseudocode}  % skip EndFor etc
\usepackage{algorithm}   % custom floats
\begin{algorithm}
    \caption{Euclid’s algorithm}
    \label{euclid}
    \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\)
            \EndWhile\label{euclidendwhile}
            \State \textbf{return} \(b\)
              \Comment{The gcd is b}
        \EndProcedure
    \end{algorithmic}
\end{algorithm}

Algorithm line label references look like

\algref{euclid}{init}

If I am running minimalist TeX I need

tlmgr install algorithmicx algorithms

or I can do without algorithms if I do

\usepackage{float}
\newfloat{algorithm}{t}{lop}

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

algorithms provides algorithmic and an algorithm float, and seems to be fairly common and also fairly interchangeable with algorithmicx. The making your own floats does not need a package, but the algorithmic markup is non-trivial.

This seems intermittently maintained but has better reference syntax, in that referring to a line number just works - \autoref{alg:euclif:init} does what you would expect. It also seems to be preferred by IEEE.

algorithm2e

TBD.

program

program does pseudocode formatting but with substantively different syntax and styling. It looks nice but I don’t use it as it’s less compatible with the other so the odds of being able to copy and paste are low and copy-and-pasting ancient code snippets is how academia works.

IDs (ORCID, DOI etc)

Why is this not documented at [orcid.org]](https://orcid.org)? I do not know.

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

\href{https://orcid.org/0000-0001-6077-2684
}{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 made this work with the academicons package, which gets the logo via a custom font.

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

\usepackage{academicons}
\definecolor{orcidlogocol}{HTML}{A6CE39}

and in the body

\item \href{https://orcid.org/0000-0001-6077-2684
}{Dan MacKinlay \hspace{2mm} \textcolor{orcidlogocol}{\aiOrcid}  }

Or use the orcid.pdf (converted from orcid.svg):

\href{https://orcid.org/0000-0001-6077-2684}{\includegraphics[scale=0.06]{orcid.pdf}\hspace{2mm}Dan MacKinlay}

Mathematical hacks

Spacing and line breaking

the breqn package position paper expalins many of the issues here. However, the solutions that actually work in the javascript-backed LaTeX solutions are multline (nb only one i) and split environments, so in practice I use those.

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

Arrays

There is an array environemtn which is good for typsetting equations but it is too verbose for typsetting arrays of other things, like numbers.

Use amsmath matrix for that, e.g.

\begin{pmatrix}
1 & 2 & 3\\
a & b & c
\end{pmatrix}

Defining new operators

Without Limits

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

Plain style (works everywhere including old MathJax):

\newcommand{\sech}{\mathop{\mathrm{sech}}\nolimits}

amsmath style (works in AMSMath environments):

\DeclareMathOperator{\sech}{sech}

With Limits

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

Vanilla:

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

amsmath style:

\DeclareMathOperator*{\argmin}{arg\,min}

Version control

Tools such as git-latexdiff provide custom diffing for, in this case, LaTeX code in git.

Diagrams

Getting a diagram into a document?

SVG

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

\begin{figure}
    \centering
    % set width of next svg image:
    \def\svgwidth{\columnwidth}
    \input{image.pdf_tex}
\end{figure}

This can be automated using the svg tex package.

PFGPlots

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

See also general diagrams and scientific workbooks.

Editors

See LaTeX editors.

Citations and bibliographies

From within LaTeX? See BibTeX etc.

Posters

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 but I cannot find a way of making them seem anything but fugly to me and I cannot condone their use. It is hard enough to bring beauty into this world without makgint it worse.

Comments, TODOs

I quite like this one

\usepackage{todonotes}
\newcommand{\dan}[1]{\todo[inline,color=green!20!white]{\textbf{Dan:} #1}}

Miscellaneous

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}

No comments yet. Why not leave one?

GitHub-flavored Markdown & a sane subset of HTML is supported.