troubleshooting.tex

\chapter{When Good Type Goes Bad}

With luck, you're off to a solid start with \LaTeX.
But as with any complicated tool, you will eventually run into trouble.
Here are some common problems and things you can try to fix them.

\section{Fixing overflow}

\mbox{When \LaTeX{} can't break a paragraph into well-spaced lines,
it gives up and overflows} into the margin.
You can sometimes remedy this with some ``emergency stretch''\quotekern.
If you add \texttt{\textbackslash emergencystretch=\allowbreak<width>}
to the preamble,
\LaTeX{} will try to set troublesome paragraphs a second time,
stretching or shrinking the total space in each line by up to the provided
width.\punckern\footnote{\LaTeX{} has pretty sane defaults for how much
it stretches and shrinks spacing.
You probably don't want to make \texttt{<width>} larger than an em or two.}
If that still doesn't help, tweak the wording of problematic paragraphs.
This can be frustrating, but the alternative is for \LaTeX{} to create spacing
that is too loose---where\quad
words\quad have\quad large\quad gaps\quad between\quad
them---or too tight, where\! words\! are\! awkwardly\! crammed\! together.

\section{Avoiding widows and orphans}

Good layouts avoid \introduce{widow} and \introduce{orphan}
(also called \introduce{club}) lines:
ones that get separated from the rest of their paragraph by a page boundary.
\LaTeX{} tries to prevent these, but its page-splitting algorithm
is much more primitive than its paragraph-splitting one.\punckern\footnote{%
This is because 1980s computers didn't have enough \acronym{ram} to do so.
Seriously---Knuth wrote at the time,
``The computer doesn't have enough high-speed memory capacity to remember the
contents of several pages,
so \TeX{} simply chooses each page break as best it can, by a process of
`local' rather than `global' optimization.\quotekern''\,\endnote{Knuth,
\textit{The \TeX book}, 110}}
You can make \LaTeX{} try harder to avoid orphans and widows with:
\begin{leftfigure}
\begin{lstlisting}
\widowpenalty=<penalty>
\clubpenalty=<penalty>
\end{lstlisting}
\end{leftfigure}
\verb|<penalty>| is a value between 0 and 10000.
When these values are maximized,
\LaTeX{} is never allowed to leave orphans or widows,
at \emph{any} cost.\punckern\footnote{When considering a given layout,
\LaTeX{} assigns penalties, or ``badness''\quotekern,
to anything that arguably makes a document look worse.
It chooses whichever layout it can find with the least badness.}
This can produce some really odd layouts,
so be sure to review your pages if you choose large penalties.

\section{Handling syntax errors}
If you confuse \LaTeX{}---say, by issuing commands that don't exist,
or forgetting to end an environment---it will print an
error message,\punckern\footnote{Usually this contains a succinct summary of
the problem and the number of the line(s) it occurred on. Occasionally,
\LaTeX{} gets \emph{really} confused and emits something so cryptic it gives
\cpp{} template errors a run for their money.
As you use \LaTeX, you will start to get a feel for what sorts of
mistakes cause these rare, but enigmatic messages.}
then display an interactive prompt starting with \texttt{?}\,.
Here you can enter instructions for how to proceed.
Once upon a time, when computers were thousands of times slower and
\LaTeX{} took that much longer to re-run, this was more useful.
Today, we probably just want to quit,
then try again once we've fixed our document.
To exit the prompt, type \texttt{X}, then press Enter.
Better yet, you can tell \LaTeX{} to give up as soon as it finds trouble
by running your engine with the \monobox{-halt-on-error} flag:
\begin{leftfigure}
\begin{lstlisting}
$ lualatex -halt-on-error myDocument.tex
\end{lstlisting}
\end{leftfigure}
\vfill

\noindent Good luck!