Chapter 13: Troubleshooting

During typesetting, it may happen that LaTeX prints out warning messages. It's even possible that LaTeX doesn't produce the desired output and shows error messages instead. That's absolutely normal and can be caused, for example, by minor typos in command names or by unbalanced braces. Even professional LaTeX typesetters have to deal with errors—they just know how to do it efficiently.

Don't worry too much about the potential errors—let LaTeX check it for you. Then you just need to do the corrections at the places pointed out by LaTeX.

This chapter prepares us to do the following:

• Understanding and fixing errors
• Handling warnings
• Avoiding obsolete classes and packages
• General troubleshooting

Let's first tackle error handling.

Technical requirements

You can use a local LaTeX installation, or you can compile the example code online at https://latexguide.org/chapter-13.

The code is available on GitHub: https://github.com/PacktPublishing/LaTeX-Beginner-s-Guide-Second-Edition/tree/main/Chapter_13_-_Troubleshooting.

Understanding and fixing errors

If the LaTeX typesetting engine encounters a problem, it will issue an error message. This is informative and it's intended to help you. So, read the messages carefully. Besides the line number where the error occurred, LaTeX provides a diagnostic message.

Concentrate on the very first error message. If you continue typesetting, other errors might just be a consequence of the first one that confused the compiler.

Let's create a tiny test document. For sure, you've encountered those "Hello world!" printing programs—we shall write one in LaTeX. Though we are used to the uncommon capitalization used in the words TeX and LaTeX, we will now try and see if the \Latex command works as well:

1. Create a new document containing these lines:

   \documentclass{article}
   \begin{document}
   \Latex\ says: Hello world!
   \end{document}

2. Click on Typeset to compile the document. LaTeX will stop and print out the following message...

Handling warnings

Warning messages are for your information. They don't always point to a severe problem, but often it's a good idea to read these tips carefully and act accordingly. This may improve your document.

We will test this now. Let's say we want to emphasize text that is in a sans-serif font. We expect italic sans-serif text as a result.

Let's try this:

1. Take our "Hello world!" example and modify it this way:

   \documentclass{article}
   \renewcommand{\familydefault}{\sfdefault}
   \begin{document}
   \emph{Hello world!}
   \end{document}

2. Compile. LaTeX will print out a warning in the log file:

   LaTeX Font Warning: Font shape `OT1/cmss/m/it' in size <10> not available
   (Font) Font shape `OT1/cmss/m/sl' tried instead on input line 4.

3. Check the output:

Figure 13.4 – Slanted shape instead of italic shape

The \familydefault macro stands for the default font family used in the LaTeX document...

Avoiding obsolete classes and packages

At the end of Chapter 11, Developing Large Documents, we talked about the dangers of outdated information. LaTeX exists for decades, and so do tutorials, examples, packages, and templates. Many are totally outdated and some even refer to the old LaTeX standard 2.09, where even document classes didn't exist. We pointed to the definitive guide, l2tabu, that comes to the rescue.

Many problems just occur because of the use of obsolete packages. For example, some that aren't maintained anymore may conflict with newer packages. Often, you just need to find the recommended successor of an obsolete package and use that.

To help you in that matter, here's a short list showing obsolete packages and their respective recommended successors:

Figure 13.5 – Obsolete packages and recommended successors

That's not set in stone. Of course, you may still use the so-called obsolete packages. They may work...

General troubleshooting

There may be situations where we cannot solve a problem simply by reading and acting on warnings or error messages. Imagine a mysterious error, an untraceable error location, irresolvable references, or just unclear messages from classes or packages.

Locating the cause by the line number printed out by LaTeX, or by knowing what we've done since the previous typesetting run, usually helps. Once we've found a problematic line or chunk, we can remove or fix it. Otherwise, it might become difficult.

Here are the first general steps we can work through:

• Compile several times. This may be necessary for correct referencing, positioning of floating figures, creating a table of contents, bibliographies, and lists of tables and figures.
• Check the order in which you load the packages. Some packages, such as hyperref, don't work well if loaded before or after specific packages. You may just swap some lines to correct or test that.
• Remove...

Summary

This chapter prepared us to solve problems that might occur in our LaTeX document.

Specifically, we learned about locating and fixing errors, understanding warning messages, and analyzing LaTeX's typesetting log file.

Correcting errors is absolutely necessary. Dealing with warnings is a valuable bonus. If you encounter any problem that you cannot solve on your own, don't hesitate to ask for help on a LaTeX Internet forum such as https://latex.org. In that forum, we have a section dedicated to this book, LaTeX Beginner's Guide, where I would be happy to answer your questions.

For LaTeX friends who are online, it's often an easy task to use this information to solve your problem, and definitely, a lot of LaTeX enthusiasts have fun helping other LaTeX users. The next chapter will discuss LaTeX internet forums and many other online resources.