A small sample of a LaTeX document showing some text and an equation

LaTeX Tips and Tricks for Thesis Writing

As a last-year Ph.D. student, I am tying up loose ends and writing my thesis. In astronomy, LaTeX is the default typesetting tool, so I’ve used it for my SPIE paper (which I should really put up on arXiv) among many other term papers and sundry projects. Now I “get” to use it for the thesis as well. This is the largest LaTeX project I have tried to date, so it has been more annoying than previous projects as well. Here, I’ll go through a couple of the tricks I’m using to make my life a little better.

First, I’d like to share…

The Strange Table Error Parable

…which I sat down and wrote after fixing a particularly persistent error message. I don’t know why I wrote it as a tall tale instead of a plain comment, but here we are.

Once upon a time there was a table in the faraway land known as LaTeX. It cried and cried nonstop saying "You can't use vadjust in vertical mode!" None of the king’s horses and none of the king’s men could calm it down. One day, the king sent for all of his soothsayers and priests and asked them to calm the table. The soothsayers tried transforming the table into an entirely different table (one that had been known throughout the land for its calmness), but still it bawled. The priests cast their eyes to the heavens and prayed, but to no avail. After casting all of them into exile, the king asked the court Jester what they would have him do. The Jester said, in their usual way,

“Why King, be it not obvi’s from the start?
This table longs and longs straight from its heart!
For peace and calm and air and slow of pace.
My liege, give your poor subject its own space!”

The king stroked his long beard. silent for an eternity. eventually, he went to the table and gave it empty space on all sides around it. The table fell into a deep and restful sleep. The king gave the Jester a badge of honor shaped like a return key, and the kingdom was quiet and peaceful ever after.

The moral of this story is put a blank line before \begin{table} and another one after \end{table} lest you be cursed with woeful error messages.

Finally, a Decent Way to Compile Documents

TexFot, for filtering junk warnings

As my thesis grows, so did the number of junk warnings printed out by the engine. I discovered texfot, a tiny Perl script that removes junk boilerplate messages from the output of LaTeX. I settled on using the command:

env max_print_line=999 texfot pdflatex main.tex

This worked well for a while, until my thesis grew more and the compile time grew as well. When I eventually got fed up with that as well, I embarked on a journey through Stack Exchange posts on LaTeX speedup. My biggest complaint was the fact that I had to wait for compilation twice in order to get all the cross-references right. Someone suggested the -draftmode option, which does not produce a PDF file, for the first run. Even with 100 pages of thesis (so far), draft mode runs almost instantly.

Arara, an inline compile script

Then I ran across something called arara, a compiler helper for LaTeX. It allows you to just run

arara main.tex

as long as you have a compilation scheme defined at the top of your .tex file. Mine looks like this:

% arara: pdflatex: {draft: yes, options: "-halt-on-error -file-line-error-style"}
% arara: bibtex
% arara: pdflatex: {draft: yes, options: "-halt-on-error -file-line-error-style"}
% arara: pdflatex: {synctex: yes, options: "-halt-on-error -file-line-error-style"}

This enables draft mode for the first two runs of pdflatex and synctex on the last run when the PDF is actually generated. My only complaint is that arara is written in Java and takes a couple seconds to start. This offsets my time savings a little.

PDF Compression Level

For even more time savings, I found you can put a couple more commands at the top of the document before setting the document class:

\pdfcompresslevel 1
\pdfobjcompresslevel 1

I think the default compression level is “highest”, which takes significantly longer for only minimal size reduction. In this day and age, who cares if your PDF is 14 MB as opposed to 10? (200 MB is still too much for me however, which is what I get if I set the compression level to zero.)

Makefile Forcing

I use Sublime Text for the most part, and its default build behavior is to simply run make. I’ve always been told that the proper execution of pdflatex and bibtex is too complicated for make to understand, so I configured it to just launch arara and call it a day. This requires making sure that make always runs the build procedure, which is accomplished by using a force rule

main.pdf: FORCE
	arara main.tex


To be entirely honest I do not know why this works, but I need to get back to writing so we’ll leave it at that. I think the next step will be to translate my arara script to a make script so that I don’t have to wait for the Java overhead.

Synctex: Why Didn’t I Hear About This Before?

I have often used Overleaf chiefly because of its ability to jump from PDF to code. But Overleaf Free strictly limits compile time, and my thesis easily exceeds that. During my journey through TeX Stack Exchange, I heard someone mention Synctex, which I hadn’t heard of (or had heard and ignored). Synctex powers Overleaf’s jump to code feature! So if I run Synctex on my end (and have a compatible PDF viewer, which I do), I now have that feature locally on my computer!

Synctex is reported to slow down compilation, which is why my arara header above runs the first compilations in draft mode without synctex and only activates synctex on the final run. This doesn’t cause any problems either, since synctex only needs to be run last time through.

When I’m on Mac, the PDF viewer Skim does synctex out of the box. On Linux however, I had to do more poking around. I usually use Evince, which has sketchy synctex support. Apparently, it emits a signal over Dbus whenever you ctrl+click in a document, requesting a synctex lookup. So, you have to have something ready to receive this message. A nice option is this script: https://github.com/Vinno97/evince-synctex





Leave a Reply

Your email address will not be published. Required fields are marked *