LaTeX Code of conduct

Dear friends,

today I would like to talk to you about one very serious topic: becoming a good LaTeX user. I say this as someone who definitely had to go through a painful conversion process. I now shall confess my sins: I used to ignore LaTeX errors when they didn’t seem to affect the output (meaning there would be PDF output, no fatal error stopping LaTeX from compiling, plus maybe no overly visible problems). I shudder to confess it now but: Nonstopmode was my best friend.

To spare you, my friends, from following me down this path of vice and misery, I want to bring up the subject of good LaTeX conduct today.

Read error messages, then ACT ON THEM

At least try to figure out what’s going on. If you make this a habit, you will not only learn a lot and actively get better at LaTeX with all the (hopefully not totally fruitless) online research you’ll be doing. But also, you will notice that it’s basically always the same misbehaviours you keep repeating document after document. Once you have reached this insight, you are in a position to better yourself.

Don’t let your standards down only because nobody’s looking or nobody ever looks at your source files anyway

At least when you’re not currently deadline-driven (and so understandably) have absolutely no patience for this), try to make your documents compile error-free. These will be some of the rare occasions you will notice the warnings and think, now that you have pruned your document from the errors, maybe the warnings might actually benefit you. I used to have so many error messages that I didn’t even notice the warnings, most of the time.

Why is bad conduct a thing with advanced LaTeX?

One thing you should know is that I am not one of those LaTeX gurus (at least not yet, muahahahaha… 😉 ). LaTeX ninja’ing, to me, means feeling empowered to do some cool fancy things with LaTeX, going beyond what most casual users do with it, but also, there is this aspect of getting what you want in unconventional ways – or, let’s be honest – in a messy way where the result counts, not who beautifully or elegantly it was done. Here, today, I want to also give credit to those hidden heroes who do things elegantly without ever telling anyone or bragging about it. Who just do what they do well because that’s the right thing to do.

I came to wonder why I wasn’t someone like that. And, while one of the answers definitely is laziness, the other is that LaTeX is seldom taught, or at least not at an advanced level. Beginner’s introductions usually content themselves with, well, introducing the basics, which is more like, listing them. And everything else, you probably learn on your own, sifting through Stackoverflow. And of course, some very knowledgeable people are on Stackoverflow and give some very helpful tips. But like this, you never learn in a systematic way (which is a big problem with learning to program in general, in my opinion).

You end up with a lot of actionable half-knowledge without ever understanding what’s really going on. And that was ok for me for a long time because LaTeX was just a tool. But once I had decided to really learn LaTeX and get good at it, I realized this was a problem. Sometimes, people make some general comments on Stackoverflow as to why you should or shouldn’t do XY. Sometimes they even explain in an understandable way why that is. Still, this is no way to learn advanced skills and while many advocate learning by tutorials or trial-and-error, especially when it comes to computer things, I don’t think that’s the way. There is some good to systematic teaching and a well thought-through class will quickly give you an understanding you wouldn’t get in thousands of hours of trial-and-error coding. Also, since there are no tutorials to learn advanced LaTeX (a situation I’m trying to aid with this blog, see this post), this approach doesn’t really apply here.

To remedy the problem, I have started to read books on LaTeX. The actionable insights you gain by this are, mostly, minimal: They are too theory-driven and complicated for absolute beginner’s but still, a good part of their content is made up of listings of basic commands which won’t bring a lot of benefit to the non-beginner, unless you are specifically interested in the theory or there is a book treating the specific problem you want to solve. So I established for myself that, apart from general laziness, a big problem about my incompetent use of LaTeX came from the fact that I just wasn’t even aware there was a ‘good style’ in the first place. And if I had a hunch that something like this must exist somehow, I just didn’t know where to look for that kind of information (apart from on demand trial-and-error problem-solving whenever the need for such a thing arises).

What is good conduct in LaTeX anyway, apart from not ignoring error warnings?

Let’s not get extensive here and stay with the basics. Good conduct is writing readable code. And, most importantly, avoid some LaTeX sins, i.e. deprecated elements (which you probably don’t use anyway if you didn’t start LaTeX 20 years ago already).

LaTeX sins to avoid (aka deprecated elements)

A list of LaTeX taboos can be found here. I’ll quickly sum up the most important ones now.

1.) Don’t use \sloppy (especially not globally)

Ok, I have to admit I sometimes totally do this. Sorry. In case you’re not familiar with \sloppy, you can use it to get rid of line overflows (which are common in LaTeX in case you didn’t notice). They happen because LaTeX doesn’t want to sacrifice the overall typesetting quality for one line where it doesn’t work. You should use \sloppy in a limited scope only or even rather change sentences so the problem doesn’t appear. It happens to me a lot with uncommon German composite words. You can also offer LaTeX information where to break a word if it doesn’t fit in the line instead of using \sloppy which will compromise the overall layout. But if the whole paragraph is made up of German nominalized complicated shit, just using \sloppy might be easier. Also, it will still work if you change the document while offering preferred hypenation might cause mistakes if your current document is not the final version.

For a vague overview of how \sloppy works: LaTeX internally has “penalties for certain behaviours, like widow lines and orphans (Hurenkinder and Schusterjungen). By defining a huge penality value for those, you tell LaTeX to avoid them in any case (also at the expense of other features of balanced typesetting). \sloppy basically ignores all sorts of “code of conduct” to ensure there are no line overflows. That’s a very imprecise explanation but gives you an overview of what’s going on more or less.

TeX’s first attempt at breaking lines is performed without even trying hyphenation: TeX sets its “tolerance” of line breaking oddities to the internal value \pretolerance, and sees what happens. If it can’t get an acceptable break, TeX adds the hyphenation points allowed by the current patterns, and tries again using the internal \tolerance value. If this pass also fails, and the internal \emergencystretch value is positive, TeX will try a pass that allows \emergencystretch worth of extra stretchability to the spaces in each line. […] \tolerance is often a good method for adjusting spacing; Plain TeX and LaTeX both set its value to 200. LaTeX’s \sloppy command sets it to 9999, as does the sloppypar environment. This value is the largest available, this side of infinity, and can allow pretty poor-looking breaks (from the TeX FAQ).

Check if you just forgot to choose all the necessary languages using the babel package. Sometimes the problem is that LaTeX just doesn’t know your languages’ hyphen rules if you didn’t explicitly declare them using babel. It sounds weird that you could forget to add babel but really, it happens to me a lot. LaTeX uses hyphenation only when necessary, meaning that it often doesn’t do any hyphenation in short documents or ‘accidentally’ gets them right even if you didn’t declare the language. So be sure to check for missing babel first.

2.) Deprecated macros

In older versions of LaTeX, you would have used {\bf ...} in curly brackets (to limit the scope) for bold face. This shouldn’t be used anymore. For a local change,  use \textbf{bold text}; for global changes in, say, a whole paragraph use: { \bfseries ... }. Analogous for all the other font faces. Locally, use  \text plus the 2 letter short name, for global scope, find out the correct “name”.

rm = roman (=serif font family \rmfamily), sf = sans serif font family (\sffamily), tt = monospaced (= “typewriter” font family \ttfamily). md = regular (\mdseries), bf = bold (\bfseries). up = upright (\upshape), sl = slanted (\slshape), sc = small caps (\scshape).

3.) Find out which packages are deprecated.

For example, font encoding should be done using \usepackage[T1]{fontenc}. A listing can be found in the taboo document (in German and in English).

You will still have documents which compile despite the errors. This is still ok when the PDF output is all that counts right now. But once you commit to better yourself, you will also be a better person overall and, from now on, have this little voice of conscience in the back of your head remining you that one should never ignore LaTeX’s warnings.

Cheers, the Ninja!