3 Hacking Down

The previous section illustrated how to build up a minimal example. This section shows how to hack down a minimal example. Again, we are going to start with a 300 page document which contains many images, tables and a bibliography.

\documentclass{myuniversityscustomclass}

\usepackage{nonstandardpackage}
\usepackage{anothernonstandardpackage}
% lots of other packages

\usepackage{glossaries}

% lots of your own command and environment definitions

\newglossaryentry{minex}{name={Minimal Example},
description={A small document illustrating failing behaviour},
text={minimal example}}

% lots more glossary definitions

\author{John Doe}
\title{Astounding Discoveries}

\begin{document}
\maketitle
\tableofcontents
\listoffigures
\listoftables

% 300 or so pages of text, graphics, tables and
% sundry other stuff

% Somewhere in the document is the following:
A \gls{minex is essential when encountering a \TeX\ or \LaTeX\ 
error you don't understand.

% Lots more text, figures, tables and a bibliography
\end{document}

This document is causing the following error:

Runaway argument?
{minexam is essential when encountering a \TeX \ or \LaTeX \^^Merror
\ETC.
! Paragraph ended before \\@gls was complete.
<to be read again>
                   \par

Suppose you don't understand what the error is or whereabouts in the document it is occurring⁶.

Since you don't know what command is causing the problem, you can't use the approach illustrated in the previous section. So you will need to use the hacking down approach.

Before doing anything else, make a copy of the problem document. Call the copy, say, test.tex, and only edit this. Don't start messing around with the original document until you've solved the problem, otherwise you could lose your work!

One way of tracking down the problem is to use a binary search. Suppose your document contains 1000 lines of source code, then go to line 500 of your test document (i.e. half-way through it) and insert the line⁷:

\end{document}

(Make sure you don't put it inside a group or environment.)

Now pass the test document to LaTeX. You may get some warning messages as a result of omitting half the document, but don't worry about that for now.

If the error still occurs, then the problem is in the first half of the document. In which case, delete everything after the first \end{document} (in your test file), and repeat the process.
If the error goes away, then the problem is in the second half of the document. In which case, delete everything after \begin{document} up to, and including, the first \end{document} (in your test file), and repeat the process.

Continue the process until you only have one paragraph left in your document. If this has an \input or \include command, first remove (or comment out) the command. If the problem goes away then the error is in that file, in which case replace the \input or \include command with the contents of the relevant file in your test file, and repeat the process. Once you have finished, it's a good idea to add \listfiles.

Let's suppose we now have a test file that looks like:

\listfiles
\documentclass{myuniversityscustomclass}

\usepackage{nonstandardpackage}
\usepackage{anothernonstandardpackage}
% lots of other packages

\usepackage{glossaries}

% lots of your own command and environment definitions

\newglossaryentry{minex}{name={Minimal Example},
description={A small document illustrating failing behaviour},
text={minimal example}}

% lots more glossary definitions

\begin{document}

A \gls{minex is essential when encountering a \TeX\ or \LaTeX\ 
error you don't understand.

\end{document}

It may be that you can now identify the problem, but let's suppose you still don't know what's wrong. The next thing to do is to remove unnecessary information in the preamble. If you have defined any commands or environments in the preamble that aren't used in the problem paragraph, then delete them. This includes any new theorems or glossary entries and so on. In this example, the problem paragraph contains a glossary entry, so keep the definition for that entry, and delete all the others:

\listfiles
\documentclass{myuniversityscustomclass}

\usepackage{nonstandardpackage}
\usepackage{anothernonstandardpackage}
% lots of other packages

\usepackage{glossaries}

\newglossaryentry{minex}{name={Minimal Example},
description={A small document illustrating failing behaviour},
text={minimal example}}

\begin{document}

A \gls{minex is essential when encountering a \TeX\ or \LaTeX\ 
error you don't understand.

\end{document}

Now, one by one, remove any packages that aren't contributing to the problem. Each time you remove a package, run the test file through LaTeX. If the error goes away, then put the package back in. If removing a package causes an “Undefined control sequence” error, then remove the undefined command as well. If the problem goes away, add the command and package back again. For example, if I remove the line:

\usepackage{glossaries}

then I will get an error as neither \newglossaryentry nor \gls will be defined. If I remove those commands, the original error message will go away. So I have to leave those commands in and keep the glossaries package in the test file.

Next, try substituting the class file for the article or report class file. If the error goes away, then the original class file is contributing to the problem, in which case put it back again. If this class file is not publicly available (for example, it may be an in-house class file, such as a university thesis, which has restricted access) then contact the author of the class file, and send the test file and log file. (Remembering, of course, to first search the documentation.)

If you followed all of the above steps, then the test file should now look like:

\listfiles
\documentclass{article}

\usepackage{glossaries}

\newglossaryentry{minex}{name={Minimal Example},
description={A small document illustrating failing behaviour},
text={minimal example}}

\begin{document}

A \gls{minex is essential when encountering a \TeX\ or \LaTeX\ 
error you don't understand.

\end{document}

In this example, you should now be able to work out that there is a missing closing brace to the argument of \gls. If, however, you still can't work out the problem, then (assuming that you've already read the documentation and searched relevant forums or newsgroup archives) copy and paste the test file in a message to somewhere like TeX on StackExchange or The LaTeX Community or comp.text.tex.

Footnotes

... occurring ⁶: Actually, in this example it should print the line number in the error message since \gls is a short command, but not all runaway argument errors give a helpful line number, so let's pretend it hasn't.
... line ⁷: LaTeX will finish the document when it reaches the first \end{document}, and ignore everything that comes after it.

⇦

⇧

⇨