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 I am doing violence to the rich and storied ecosystem by failing to mention that almost everything I mention 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 try to do that half way through formatting instead of in my text editor where my fixes will actually persist? 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, alternatively, bloody-minded-compile-my-document-at-all-costs-I-don’t-care-how-it-is-broken:

pdflatex -interaction=batchmode

latexmk

A popular 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

Tectonic

Tectonic addresses a lot of my complaints in one fell swoop. I wonder if there is friction using it, or if it is as seamless as I might hope. The solution seems to be a light wrapping/forking of mainline LaTeX using modern tools.

Tectonic is a modernized, complete, self-contained TeX/LaTeX engine, powered by XeTeX and TeXLive.

… TeX is quite archaic in some ways, but it’s still the tool of choice for documents that require precision typography or ones that involve lots of mathematical equations, which makes it especially important in the sciences. Tectonic converts TeX files into PDF files.

Tectonic is beta software but has been demonstrated to work well in a variety of real-world situations. Contributions in any form --- documentation, bug reports, test cases, new features --- are most welcome. The user forum is the place to start.

Advertised features:

  • Tectonic automatically downloads support files so you don’t have to install a full LaTeX system in order to start using it. If you start using a new LaTeX package, Tectonic just pulls down the files it needs and continues processing. The underyling "bundle" technology allows for completely reproducible document compiles. Thanks to the Dataverse Project for hosting the large LaTeX resource files!
  • Tectonic has sophisticated logic and automatically loops TeX and BibTeX as needed, and only as much as needed. In its default mode it doesn’t write TeX’s intermediate files and always produces a fully-processed document.
  • The tectonic command-line program is quiet and never stops to ask for input.
  • Thanks to the power of XeTeX, Tectonic can use modern OpenType fonts and is fully Unicode-enabled.
  • The Tectonic engine has been extracted into a completely self-contained library so that it can be embedded in other applications.
  • Tectonic has been forked from the old-fashioned WEB2C implementation of TeX and is developed in the open on GitHub using modern tools like the Rust language.
  • Tectonic can be used from Github Actions to typeset your documents whenever a change to them is made:
  • setup-tectonic - Use tectonic in your github action workflows (supports caching and optionally biber)
  • compile-latex - Thanks to Vinay Sharma for creating the action.

It is hard to imagine getting uptake because it doesn’t use enough cute 1980s typesetting stunts like naming itself canonically TECTONIC.

brew install tectonic

Manual is not linked as obviously as it could be. See here.

Include in python

Generating arbitrary LaTeX in python scripts, jupyter notebooks, Pweave literate documents? For that I use an ingenious python script called 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)

You should totally check it out for rendering inline algorithms, or for emitting SVG equations.

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.

In jupyter, the inbuilt jupyter LaTeX renderer will display maths ok via HTML+JS, so why would we use this?

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

For one, once this thing has rendered there are no external dependencies, so a notebook which display mathematics this way also works when you are offline. For another, this can display other stuff than mathematics, for example, specialised LaTeX-only things like pseudocode, and weird font samples, and exotic diagram types like Feynman diagrams and parse trees.

Strikethrough

a.k.a. strikeout. Jan Söhlke says this works great in text mode.

\usepackage[normalem]{ulem}

\sout{text to be struck through}

Strikethrough is weird in math mode; the cancel package is recommended. In mathjax, this needs an extension.

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 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 revert to fully justified after the proofreading process. This has advantages:

  1. Editors will not complain about everything not being fully justified
  2. Reviewers will find it harder to read, reducing the chance they will detect any inconvenient errors I made.

Commenting out

The obvious way to comment stuff out is with the % comment marker. For long blocks, Martin Scharrer suggests

You can use \iffalse ... \fi to make (La)TeX not compile everything between it. However, this might not work properly if you have unmatched \ifxxx ... \fi pairs inside them or do something else special with if-switches. It should be fine for normal user text.

There is also the comment package which gives you the comment environment which ignores everything in it verbatim. It allows you to define own environments and to switch them on and off. You would use it by placing \usepackage{comment} in the preamble.

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

See LaTeX algorithms.

IDs (ORCID, DOI etc)

Why is this not documented at orcid.org? I do not know. So now I document it here. AFAICT, at the basic level I should simply 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 hidebound conference stylesheet from the 90s this is unlikely to work. But for a more modern setups (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 redners the logo using 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 (which I converted from orcid.svg, feel free to use it):

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

Mathematical hacks

See LaTeX mathematics hacks.

Version control

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

Diagrams

Getting a diagram or a plot into into a document? See also general diagrams for tools which create generic types of diagram. Consider scientific workbooks, which often include automatic conversion of inline plots.

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 workflow from SVG->PDF->LaTeX can be automated using the svg tex package.

PFGPlots

PGFPlots is a native diagramming/plotting package which supports PDF output for TiKZ-style diagrams.

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}

Convertion to other markup formats

Maybe you want to throw the original latex out? in whicih case see LaTeX-free mathematics

  • pandoc converts to everything

  • ConTeXt can handle XHTML natively

  • plasTeX

    is a LaTeX document processing framework written entirely in Python. It currently comes bundled with an XHTML renderer (including multiple themes), as well as a way to simply dump the document to a generic form of XML. Other renderers can be added as well and are planned for future releases…

    plasTeX differs from other tools like LaTeX2HTML, TeX4ht, TtH, etc in that the parsing and rendering of the document are completely separated. This separation makes it possible to render the document in multiple output formats.

    It is active, being used by high-profile online projects such as the collaborative textbooks stacks and kerodon.

  • HEVEA — an older HTML converter with medocre maths support (so why would you even bother?) Manual lives here.

  • LaTeX2HTML, TeX4ht, TtH,…


No comments yet. Why not leave one?

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