Where We Are Now

I recently stumbled across a tool called latexrun, which aims to build your LaTeX files in a much more clean, and user-friendly way.

For those of you that haven't used LaTeX before, when building a LaTeX project, you need to compile the .tex files into (among other formats) a final .pdf, which is usually done by invoking pdflatex file.tex or xelatex file.tex. However, in order to update references, diagrams, and other metadata within the document, you will need to perform (up to) three passes of pdflatex. This can be either performed manually, or by using the latexmk tool, which orchestrates this for you, including determining whether it actually does need to keep going, or if it's updated all the resources.

However, the output of these multiple runs can get fairly unwieldy. For example, when building my Git workshop slides, the output of make was a total of 1643 lines. That is a huge amount of output - almost three times as many as the actual file I was compiling! This process is one that I'll be running either on every save, or at periodic intervals while working on LaTeX documents, and I'll be potentially reading through fairly regularly. A sample of the output itself looks like this:

(...)
Package pgfplots Warning: running in backwards compatibility mode (unsuitable t
ick labels; missing features). Consider writing \pgfplotsset{compat=1.14} into
your preamble.
 on input line 57.

ABD: EverySelectfont initializing macros (./intro-to-git-workshop.nav)
Underfull \hbox (badness 2818) in paragraph at lines 59--59
[]\EU1/lmss/m/n/20.74 AN INTRODUCTION TO GIT –
(/usr/share/texmf-dist/tex/latex/amsfonts/umsa.fd)
(/usr/share/texmf-dist/tex/latex/amsfonts/umsb.fd)
(/usr/share/texmf-dist/tex/latex/wasysym/uwasy.fd)
(/usr/share/texmf-dist/tex/latex/euenc/eu1lmtt.fd)
<use  "backgrounds/title.pdf" > [1] (./intro-to-git-workshop.toc) [2] [3]
[4]

LaTeX Font Warning: Font shape `EU1/lmss/m/sc' in size <12> not available
(Font)              Font shape `EU1/lmr/m/sc' tried instead on input line 92.

[5] [6] <use  "images/pre-vcs.png" > [7] [8] <use  "images/snapshots.png" >
[9] [10] [11] [12] <use  "images/areas.png" >
Overfull \vbox (9.22456pt too high) detected at line 211
[13] [14])
Runaway argument?
\let \AtEndDocument \@firstofone \@enddocumenthook \@checkend {docume\ETC.
! File ended while scanning use of \beamer@collect@@body.
<inserted text>
                \par
<\*> intro-to-git-workshop.tex

?

All the extra output obscures errors and makes it very difficult to understand what's going on or going wrong. My debugging is often "going up the logs until I can find something that from experience looks like it could be an issue". It's even less scientific than it sounds because I actually just look at the structure of the output - sometimes errors are output in a specific way alongside the rest of the log, so I look for that. If there was much less output to hide the real issues, it wouldn't be quite so difficult, even with a page on the LaTeX wiki about errors and warnings. I even found that while working on my dissertation (written in LaTeX), I would actually just leave the files with broken compilations, as it was easier not to worry about it until a later point.

latexrun to the Rescue

However, when the above error, latexrun provides the following, more friendly, output:

(...)
intro-to-git-workshop.tex:211: warning: Overfull \vbox (8.83098pt too high) (page 13)
intro-to-git-workshop.tex:222: warning: Reference `sub:good_commit_messages' on page 14 undefined
intro-to-git-workshop.tex: error: File ended while scanning use of \beamer@collect@@body
      at <inserted text> \par
                         ^
    from <*> intro-to-git-workshop.tex
intro-to-git-workshop.tex: error: Emergency stop: job aborted, no legal \end found
      at <*> intro-to-git-workshop.tex

With the much more bite-sized and obvious errors and warnings that latexrun outputs, it's not hard to see why I'm looking to update my starter kit for LaTeX documents to integrate with latexrun as it makes debugging even just simply compiling the files so much easier.