LaTeX Tooling Guide29 Mar 2017
I'll let you in on a small secret: I hate LaTeX with a passion. It's a bloated mess with crazy syntax. It generates reams of warnings you can never totally get rid of, and some of the most confusing and/or unhelpeful errors I have ever seen. It needs to be run N times in a row. It even has a stupid name.
Don Knuth wrote TeX, and it may have been art. But, to use a fashionable word, TeX was never meant to scale to LaTeX. Pervasive use of non-hygienic macros and constant manipulations of global values is a recipe for disaster.
I wish I could avoid LaTeX completely, unfortuately conferences have templates and the only other format available is MS Word, which has its own flaws (as I recall, in how it handles numbering and floating figures).
Anyhow, the current article is about how I setup my Latex to alleviate some of these pains. I'll start with a tour of what I use, then give you a makefile and an example git repository to bring all these tools together.
Installing and Updating
See this article about available Latex distributions. I recommend sticking to the tried-and-true, so that would be MiKTeX for Windows, MacTeX for OSX and TeX Live for Linux.
If you already have a Latex distribution installed, but it is not up to date, this fantastic TeX Stack Exchange answer will tell you how to update it.
Most people will use some kind of Latex-mode that comes with their editor of choice. I edit text in Emacs, and so I use Auctex.
Nevertheless, it might be nicer to have something closer to an IDE for Latex. My option of choice here is TeXstudio. Even though most of my Latex editing is in Auctex, I use it from time to time to typeset math or help with diagnostics.
Finally, but perhaps most importantly, there are a few online Latex editors. The best of them is ShareLaTeX. Its great strength is that it saves you from doing any kind of setup, and in my own experience is super reliable.
ShareLatex also filters out unhelpful warning and errors and does its best to correlated what is left with your source file. Later in this guide we will show command line tools that do the same thing.
It's good enough as an editor, but also allows realtime collaboration on a document. Best of all, it now has the ability to sync with GitHub, meaning you can mix online and offline collaboration.
One of the famous annoyances of Latex is that it needs to be run multiple times to get references right, interleaved with runs of your bibliography tool (usually BibTeX or Biber).
Fortunately this whole process can be automated. Most Latex distribution come
with a tool called
latexmk, which does automates all these invocations for
latexmk requires Perl to run, which is not bundled with Latex.
This tends to be a caveat on Windows. If you are running Windows and want to use
latexmk, install Strawberry Perl to fix the problem.
There is a better tool, though, which is called latexrun.
latexrun does what
latexmk does, but also sanitizes Latex's output to only show helpful errors,
similar to what you would see on ShareLatex.
latexrun is a single Python3 script, which is great for portability. You can
even drop it directly in your paper's git repository.
If you're using ShareLatex or
latexrun, you're already pretty well covered
There is one more tool that bears mentioning: pulp.
pulp lets you filter out
unwanted warnings and errors, and tries to correlated errors with file
pulp's output is less pretty than that of
latexrun, but its great strength
is that it lets define custom filtering rules, to remove those annoying warnings
that you cannot get rid of, but break nothing. Or, more frequently, comes from
the class file that you are forced to use to submit you paper (I'm looking at
Here's an exemple of filtering spec to get rid of all errors that pop up when compiling the acmart example file:
!(boring | info | message | under | over | p "hyperref" & "Token not allowed in a PDF string" | "Class acmart Info" | "file:line:error style messages enabled" | "Excluding.*comment" | "Processing.*comment" | "Include comment" | "comment.cut" | "(msharpe)" | "]" && !".." )
The first line matches
pulp's default specification.
pulp can be integrated with
latexmk fairly easily, by means of a
pulp is not as friendly to install as the other tools. Here is how to install
on OSX, assuming you already have homebrew (on other platforms, you just need
to install the Haskell platform in some other way):
brew cask install haskell-platform git clone https://github.com/dmwit/pulp.git cabal update cabal install PATH="$HOME/Library/Haskell/bin:$PATH"
Unless you're working with TeXstudio or ShareLatex, you'll need to preview the generated PDF files using a PDF viewer. You want to use one that picks up changes to the PDF on the disk, and reloads it on the fly, while keeping your position in the PDF. On OSX, the built-in viewer (confusingly named Preview) does this adequately. On Windows, I'm partial to Sumatra PDF.
latexrun will automatically open a generated PDF file (using the
OS-determined associated tool).
The tooling centers around a makefile. The default configuration is to use
latexmk with pulp integration. The following commands are available:
make view: generates the PDF file and displays it
make pdf: generates the PDF file but does not display it; latex is run silently
make verbose: like
make pdf, but shows error details
make rebuild: forces a rebuild of the pdf, even if no changes are picked up
make clean: removes all temporary files (for all tools!)
make mrproper: like
make clean, but also removes the generated PDF
If you don't have
pulp, just delete or rename the
.latexmkrc file from the
latexmk is not found or doesn't work (for instance if Perl is not
installed), the makefile will fall back to using plain make rules, and
make pdf will be verbose by default.
It is also possible to use
latexrun, which is bundled in the repository, by
make run (Python3 required).
pulp can be run standalone with
make pulp (pulp is not bundled in the
repository), assuming a compilation was attempted earlier and the
.log file is
DISCLAIMER: I won't be too assiduous in maintaining this makefile, and it may even contain a few bugs. It should be taken as an example of how to do things, rather than as a toolchain to be relied on.
With all this, you'll have no Latex excuses for turning your next paper late :)