% $Id: faq-jot-err.tex,v 1.3 2009/12/10 20:38:28 rf10 Exp $

\section{The joy of \TeX{} errors}

\Question[Q-erroradvice]{How to approach errors}

Since \TeX{} is a macroprocessor, its error messages are often
difficult to understand; this is a (seemingly invariant) property of
macroprocessors.  Knuth makes light of the problem in the \TeX{}book,
suggesting that you acquire the sleuthing skills of a latter-day
Sherlock Holmes; while this approach has a certain romantic charm to
it, it's not good for the `production' user of \AllTeX{}.  This
answer (derived, in part, from an article by Sebastian Rahtz in
\TUGboat{} 16(4)) offers some general guidance in dealing with \TeX{}
error reports, and other answers in this section deal with common (but
perplexing) errors that you may encounter.  There's a long list of
``hints'' in Sebastian's article, including the following:
\begin{itemize}
\item Look at \TeX{} errors; those messages may seem cryptic at first,
  but they often contain a straightforward clue to the problem.  See
  \Qref[question]{the structure of errors}{Q-errstruct} for further
  details. 
\item Read the \extension{log} file; it contains hints to things you may
  not understand, often things that have not even presented as error
  messages.
\item Be aware of the amount of context that \TeX{} gives you.  The
  error messages gives you some bits of \TeX{} code (or of the
  document itself), that show where the error ``actually happened'';
  it's possible to control how much of this `context' \TeX{} actually
  gives you.  \LaTeX{} (nowadays) instructs \TeX{} only to give you
  one line of context, but you may tell it otherwise by saying
\begin{quote}
\begin{verbatim}
\setcounter{errorcontextlines}{999}
\end{verbatim}
\end{quote}
  in the preamble of your document.  (If you're not a confident macro
  programmer, don't be ashamed of cutting that 999 down a bit; some
  errors will go on and \emph{on}, and spotting the differences
  between those lines can be a significant challenge.)
\item As a last resort, tracing can be a useful tool; reading a full
  \AllTeX{} trace takes a strong constitution, but once you know how,
  the trace can lead you quickly to the source of a problem.  You need
  to have read the \TeX{}book (see
% beware line break
  \Qref[question]{books about \TeX{}}{Q-books}) in some detail, fully
  to understand the trace.
  
  The command \csx{tracingall} sets up maximum tracing; it also sets
  the output to come to the interactive terminal, which is somewhat of
  a mixed blessing (since the output tends to be so vast~--- all but
  the simplest traces are best examined in a text editor after the event).

  The \LaTeX{} \Package{trace} package (first distributed with the
  2001 release of \LaTeX{}) provides more manageable tracing.  Its
  \csx{traceon} command gives you what \csx{tracingall} offers, but
  suppresses tracing around some of the truly verbose parts of
  \LaTeX{} itself.  The package also provides a \csx{traceoff}
  command (there's no ``off'' command for \csx{tracingall}), and a
  package option (|logonly|) allows you to suppress output to the
  terminal.
\end{itemize}
The best advice to those faced with \TeX{} errors is not to panic:
most of the common errors are plain to the eye when you go back to the
source line that \TeX{} tells you of.  If that approach doesn't work,
the remaining answers in this section deal with some of the odder
error messages you may encounter.  You should not ordinarily need to
appeal to the \Qref*[question]{wider public}{Q-gethelp}
for assistance, but if you do, be sure to
report full backtraces (see |errorcontextlines| above) and so on.
\begin{ctanrefs}
\item[trace.sty]Distributed as part of \CTANref{2etools}
\end{ctanrefs}

\Question[Q-errstruct]{The structure of \TeX{} error messages}

\TeX{}'s error messages are reminiscent of the time when \TeX{} itself
was conceived (the 1970s): they're not terribly user-friendly, though
they do contain all the information that \TeX{} can offer, usually in
a pretty concise way.

\TeX{}'s error reports all have the same structure:
\begin{itemize}
\item An error message
\item Some `context'
\item An error prompt
\end{itemize}
The error message will relate to the \emph{\TeX{}} condition that is
causing a problem.  Sadly, in the case of complex macro packages such
as \LaTeX{}, the underlying \TeX{} problem may be superficially
difficult to relate to the actual problem in the ``higher-level''
macros.  Many \LaTeX{}-detected problems manifest themselves as
`generic' errors, with error text provided by \LaTeX{} itself (or by a
\LaTeX{} class or package).

The context of the error is a stylised representation of what \TeX{}
was doing at the point that it detected the error.  As noted in
\Qref[question]{approaching errors}{Q-erroradvice}, a macro package
can tell \TeX{} how much context to display, and the user may need to
undo what the package has done.  Each line of context is split at the
point of the error; if the error \emph{actually} occurred in a macro
called from the present line, the break is at the point of the call.
(If the called object is defined with arguments, the ``point of call''
is after all the arguments have been scanned.)  For example:
\begin{verbatim}
\blah and so on
\end{verbatim}
produces the error report
\begin{verbatim}
! Undefined control sequence.
l.4 \blah
          and so on
\end{verbatim}
while:
\begin{verbatim}
\newcommand{\blah}[1]{\bleah #1}
\blah{to you}, folks
\end{verbatim}
produces the error report
\begin{verbatim}
! Undefined control sequence.
\blah #1->\bleah 
                 #1
l.5 \blah{to you}
                 , folks
\end{verbatim}
If the argument itself is in error, we will see things such as
\begin{verbatim}
\newcommand{\blah}[1]{#1 to you}
\blah{\bleah}, folks
\end{verbatim}
producing
\begin{verbatim}
! Undefined control sequence.
<argument> \bleah 
                  
l.5 \blah{\bleah}
                 , folks
\end{verbatim}

The prompt accepts single-character commands: the list of what's
available may be had by typing |?|\@.  One immediately valuable
command is |h|, which gives you an expansion of \TeX{}s original
pr\'ecis message, sometimes accompanied by a hint on what to do to
work round the problem in the short term.  If you simply type `return'
(or whatever else your system uses to signal the end of a line) at the
prompt, \TeX{} will attempt to carry on (often with rather little
success).

\Question[Q-extrabrace]{An extra `\texttt{\cbracesymbol{}}'??}
\keywords{caption heading}

You've looked at your \LaTeX{} source and there's no sign of a misplaced
\texttt{\cbracesymbol{}} on the line in question.

Well, no: this is \TeX{}'s cryptic way of hinting that you've put a
\begin{wideversion} % hyper
\Qref{fragile command}{Q-protect} in a moving argument.
\end{wideversion}
\begin{narrowversion}
fragile command in a moving argument (\Qref{}{Q-protect}).
\end{narrowversion}

For example, \csx{footnote} is fragile, and if we put that in the
moving argument of a \csx{section} command, as
\begin{quote}
\begin{narrowversion}
\begin{verbatim}
\section{Mumble\footnote{%
    I couldn't think of anything better}}
\end{verbatim}
\end{narrowversion}
\begin{wideversion}
\begin{verbatim}
\section{Mumble\footnote{I couldn't think of anything better}}
\end{verbatim}
\end{wideversion}
\end{quote}
we get told
\begin{quote}
\begin{verbatim}
! Argument of \@sect has an extra }.
\end{verbatim}
\end{quote}
The same happens with captions (the following is a simplification of a
\Newsgroup{comp.text.tex} post):
\begin{quote}
\begin{verbatim}
\caption{Energy: \[e=mc^2\]}
\end{verbatim}
\end{quote}
giving us the error message
\begin{quote}
\begin{verbatim}
! Argument of \@caption has an extra }.
\end{verbatim}
\end{quote}
The solution is usually to use a robust command in place of the one
you are using, or to force your command to be robust by prefixing it
with \csx{protect}, which in the \csx{section} case would show as
\begin{quote}
\begin{narrowversion}
\begin{verbatim}
\section{Mumble\protect\footnote{%
    I couldn't think of anything better}}
\end{verbatim}
\end{narrowversion}
\begin{wideversion}
\begin{verbatim}
\section{Mumble\protect\footnote{I couldn't think of anything better}}
\end{verbatim}
\end{wideversion}
\end{quote}
In both the \csx{section} case and the \csx{caption} case, you can
separate the moving argument, as in
\cmdinvoke*{section}[moving]{static}; this gives us another standard
route~--- simply to omit (or otherwise sanitise) the fragile command
in the moving argument.  So, one might rewrite the \csx{caption}
example as:
\begin{quote}
\begin{narrowversion}
\begin{verbatim}
\caption[Energy:  $E=mc^2$]%
        {Energy: \[E=mc^2\]}
\end{verbatim}
\end{narrowversion}
\begin{wideversion}
\begin{verbatim}
\caption[Energy:  $E=mc^2$]{Energy: \[E=mc^2\]}
\end{verbatim}
\end{wideversion}
\end{quote}
for, after all, even if you want display maths in a caption, you
surely don't want it in the list of figures.

The case of footnotes is somewhat more complex;
``\Qref[question]{footnotes in \LaTeX{} section headings}{Q-ftnsect}''
deals specifically with that issue.

\Question[Q-semanticnest]{Capacity exceeded [semantic nest\,\dots{}]}

\begin{narrowversion}
\begin{verbatim}
! TeX capacity exceeded, sorry [semantic nest
                                      size=100].
...
If you really absolutely need more capacity,
you can ask a wizard to enlarge me.
\end{verbatim}
\end{narrowversion}
\begin{wideversion}
\begin{verbatim}
! TeX capacity exceeded, sorry [semantic nest size=100].
...
If you really absolutely need more capacity,
you can ask a wizard to enlarge me.
\end{verbatim}
\end{wideversion}
Even though \TeX{} suggests (as always) that enlargement by a wizard
may help, this message usually results from a broken macro or bad
parameters to an otherwise working macro.

The ``semantic nest'' \TeX{} talks about is the nesting
of boxes within boxes.  A stupid macro can provoke the error pretty
easily:
\begin{quote}
\begin{narrowversion}
\begin{verbatim}
\def\silly{\hbox{here's \silly
                         being executed}}
\silly
\end{verbatim}
\end{narrowversion}
\begin{wideversion}
\begin{verbatim}
\def\silly{\hbox{here's \silly being executed}}
\silly
\end{verbatim}
\end{wideversion}
\end{quote}
The extended traceback
% beware of filling this line...
(see \Qref{\emph{general advice} on errors}{Q-erroradvice})
\emph{does} help, though it does rather run on.  In the case above,
the traceback consists of
\begin{verbatim}
\silly ->\hbox {
                here's \silly being executed}
\end{verbatim}
followed by 100 instances of
\begin{verbatim}
\silly ->\hbox {here's \silly 
                              being executed}
\end{verbatim}
The repeated lines are broken at exactly the offending macro; of
course the loop need not be as simple as this~--- if \csx{silly} calls
\csx{dopy} which boxes \csx{silly}, the effect is just the same and
alternate lines in the traceback are broken at alternate positions.

There are in fact two items being consumed when you nest boxes: the
other is the grouping level.  Whether you exhaust your % !line wrap
\emph{semantic nest} or your permitted \emph{grouping levels} first is
controlled entirely by the relative size of the two different sets of
buffers in your \AllTeX{} executable.

\Question[Q-noroom]{No room for a new `\emph{thing}'}

The technology available to Knuth at the time \TeX{} was written is
said to have been particularly poor at managing dynamic storage; as a
result much of the storage used within \TeX{} is allocated as fixed
arrays, in the reference implementations.  Many of these fixed arrays
are expandable in modern \TeX{} implementations, but size of the
arrays of ``registers'' is written into the specification as being 256
(usually); this number may not be changed if you still wish to call
the result \TeX{}
%% beware line wrap
(see \Qref[question]{testing \TeX{} implementations}{Q-triptrap}).

If you fill up one of these register arrays, you get a \TeX{} error
message saying
\begin{quote}
\begin{verbatim}
! No room for a new \<thing>.
\end{verbatim}
\end{quote}
The \csx{thing}s in question may be \csx{count} (the object underlying
\LaTeX{}'s \csx{newcounter} command), \csx{skip} (the object underlying
\LaTeX{}'s \csx{newlength} command), \csx{box} (the object underlying
\LaTeX{}'s \csx{newsavebox} command), or \csx{dimen}, \csx{muskip},
\csx{toks}, \csx{read}, \csx{write} or \csx{language} (all types of object
whose use is ``hidden'' in \LaTeX{}; the limit on the number of
\csx{read} or \csx{write} objects is just 16).

There is nothing that can directly be done about this error, as you can't
extend the number of available registers without extending \TeX{}
itself.
\begin{htmlversion}
  Of course, \Qref{\eTeX{}}{Q-etex}, \Qref{Omega}{Q-omegaleph} and
  \Qref{\LuaTeX{}}{Q-luatex}
\end{htmlversion}
\htmlignore
% beware line wrap here
  Of course, \eTeX{}, \ensuremath{\Omega} and \LuaTeX{}~---
  \Qref[see questions]{}{Q-etex} \Qref[,]{}{Q-omegaleph} and
  \Qref[and]{}{Q-luatex} respectively~---
\endhtmlignore
all do this, as does \Qref*{MicroPress Inc's V\TeX{}}{Q-commercial}.

One common way to encounter one of these error messages is to have
broken macros of some sort, or incorrect usage of macros (an example
is discussed in \Qref[question]{epsf problems}{Q-epsf}).

However, sometimes one just \emph{needs} more than \TeX{} can offer,
and when this happens, you've just got to work out a different way of
doing things.  An example is the % beware line wrap
\Qref*{difficulty of loading \PiCTeX{} with \LaTeX{}}{Q-usepictex}.
The more modern drawing package, \Package{pgf} with its higher-level
interface \Package{TikZ} is a common problem.

In such cases, it is usually possible to use the
\Qref*{\eTeX{}}{Q-etex} extensions (all modern distributions provide
them).  The \LaTeX{} package \Package{etex} modifies the register allocation
mechanism to make use of \eTeX{}'s extended register sets.
\Package{Etex} is a
derivative of the \plaintex{} macro file \Package{etex.src}, which is
used in building the \eTeX{} Plain format; both files are part of the
\eTeX{} distribution and are available in current distributions.

It is possible that, even with \Package{etex} loaded, you still find
yourself running out of things.  Problems could be caused by packages
that use large numbers of ``inserts'' (combinations of counter, box,
dimension and skip registers, used for storing floats and footnotes).
\Package{Morefloats} does this, of course (naturally enough,
allocating new floats), and footnote packages such as
\Package{manyfoot} and \Package{bigfoot} (which uses \Package{manyfoot}
can also give problems.  The \Package{etex} allows you to deal with
these things: the command \cmdinvoke*{reserveinserts}{n} ensures there
is room for \meta{n} more inserts.  (Hint: \Package{morefloats} needs
18 inserts, and \Package{manyfoot} seems to be happy with 10
reserved.)  Load \Package{etex} before any others, and reserve the
inserts immediately:
\begin{quote}
\begin{verbatim}
\documentclass[...]{...}
\usepackage{etex}
\reserveinserts{28}
\end{verbatim}
\end{quote}

Unfortunately, \eTeX{} doesn't help with \csx{read} or \csx{write}
objects (and neither will the \Package{etex} package).

\Question[Q-epsf]{\texttt{epsf} gives up after a bit}

Some copies of the documentation of \File{epsf.tex} seem to suggest
that the command
\begin{verbatim}
  \input epsf
\end{verbatim}
is needed for every figure included.  If you follow this suggestion
too literally, you get an error
\begin{verbatim}
  ! No room for a new \read .
\end{verbatim}
after a while; this is because each time \File{epsf.tex} is loaded, it
allocates itself a \emph{new} file-reading handle to check the figure
for its bounding box, and there just aren't enough of these things
(see \Qref[question]{no room for a new thing}{Q-noroom}).

The solution is simple~--- this is in fact an example of misuse of
macros; one only need read \File{epsf.tex} once, so change
\begin{verbatim}
  ...
  \input epsf
  \epsffile{...}
  ...
  \input epsf
  \epsffile{...}
\end{verbatim}
(and so on) with a single
\begin{verbatim}
  \input epsf
\end{verbatim}
somewhere near the start of your document, and then decorate your
\csx{epsffile} statements with no more than adjustments of
\csx{epsfxsize} and so on.

\Question[Q-badhyph]{Improper \csx{hyphenation} will be flushed}

For example
\begin{verbatim}
! Improper \hyphenation will be flushed.
\'#1->{
       \accent 19 #1}
<*> \hyphenation{Ji-m\'e
                        -nez}
\end{verbatim}
(in \plaintex{}) or
\begin{verbatim}
! Improper \hyphenation will be flushed.
\leavevmode ->\unhbox 
                      \voidb@x 
<*> \hyphenation{Ji-m\'e
                        -nez}
\end{verbatim}
in \LaTeX{}.

As mentioned in \Qref[question]{``hyphenation failures''}{Q-nohyph},
words with accents in them may not be hyphenated.  As a result, any
such word is deemed improper in a \csx{hyphenation} command.

The solution is to use a font that contains the character in question,
and to express the \csx{hyphenation} command in terms of that
character; this ``hides'' the accent from the hyphenation mechanisms.
\LaTeX{} users can be achieved this by use of the \Package{fontenc}
package (part of the \LaTeX{} distribution).  If you select an 8-bit
font with the package, as in \cmdinvoke{usepackage}[T1]{fontenc},
accented-letter commands such as the |\'||e| in
|\hyphenation{Ji-m\'||e-nez}| automatically become the single accented
character by the time the hyphenation gets to look at it.

\Question[Q-tmupfl]{``Too many unprocessed floats''}

If \LaTeX{} responds to a \cmdinvoke{begin}{figure} or
\cmdinvoke{begin}{table} command with the error message
\begin{htmlversion}
\begin{verbatim}
! LaTeX Error: Too many unprocessed floats.

See the LaTeX manual or LaTeX Companion for explanation.
\end{verbatim}
\end{htmlversion}
\htmlignore
\ifpdf
\begin{verbatim}
! LaTeX Error: Too many unprocessed floats.

See the LaTeX manual or LaTeX Companion for explanation.
\end{verbatim}
\else
\begin{verbatim}
! LaTeX Error: Too many unprocessed floats.

See the LaTeX manual or LaTeX Companion
...                           for explanation.
\end{verbatim}
\fi
\endhtmlignore
your figures (or tables) are failing to be placed properly.  \LaTeX{}
has a limited amount of storage for `floats' (figures, tables, or
floats you've defined yourself with the \Package{float} package); if
you don't let it ever actually typeset any floats, it will run out of
space.

This failure usually occurs in extreme cases of
% beware line break
\nothtml{floats moving ``wrongly'' (see }%
\Qref[question]{floats moving ``wrongly''}{Q-floats}\latexhtml{);}{;}
\LaTeX{} has found it can't place a float, and floats of the same type
have piled up behind it.  \LaTeX{}'s idea is to ensure that caption
numbers are sequential in the document: the caption number is
allocated when the figure (or whatever) is created, and can't be
changed, so that placement out of order would mean figure numbers
appearing out of order in the document (and in the list of figures, or
whatever).  So a simple failure to place a figure means that no
subsequent figure can be placed; and hence (eventually) the error.

Techniques for solving the problem are discussed in the
\nothtml{floats question (}%
\Qref[\htmlonly]{floats question}{Q-floats}\nothtml{)}
already referenced.

The error also occurs in a 
long sequence of \environment{figure} or \environment{table}
environments, with no intervening
text.  Unless the environments will fit ``here'' (and you've allowed
them to go ``here''), there will never be a page break, and so there
will never be an opportunity for \LaTeX{} to reconsider placement.
(Of course, the floats can't all fit ``here'' if the sequence is
sufficiently prolonged: once the page fills, \LaTeX{} won't place any
more floats, leading to the error.

Techniques for resolution may involve redefining the floats using the
\Package{float} package's \texttt{[H]} float qualifier, but you are unlikely
to get away without using \csx{clearpage} from time to time.
\begin{ctanrefs}
\item[float.sty]\CTANref{float}
\end{ctanrefs}

\Question[Q-atvert]{\csx{spacefactor} complaints}

The errors
\begin{verbatim}
! You can't use `\spacefactor' in vertical mode.
\@->\spacefactor 
                 \@m 
\end{verbatim}
or
\begin{verbatim}
! You can't use `\spacefactor' in math mode.
\@->\spacefactor 
                 \@m 
\end{verbatim}
or simply
\begin{verbatim}
! Improper \spacefactor.
...
\end{verbatim}
bites the \LaTeX{} programmer who uses an internal command without taking
``precautions''.  The problem is discussed in detail in
% beware line wrap
``\Qref*[question]{\texttt{@} in macro names}{Q-atsigns}'',
together with solutions.

\Question[Q-endingroup]{\csx{end} occurred inside a group}

The actual error we observe is:

\nothtml{\noindent}%
|(\end occurred inside a group at level <|\texttt{\emph{n}}|>)|

\nothtml{\noindent}%
and it tells us that something we started in the document never got
finished before we ended the document itself.  The things involved
(`groups') are what \TeX{} uses for restricting the scope of things:
you see them, for example, in the ``traditional'' font selection
commands: |{\it stuff\/}|~--- if the closing brace is left off such a
construct, the effect of \csx{it} will last to the end of the document,
and you'll get the diagnostic.

\TeX{} itself doesn't tell you where your problem is, but you can
often spot it by looking at the typeset output in a previewer.
Otherwise, you can usually find mismatched braces using an intelligent
editor (at least \ProgName{emacs} and \ProgName{winedt} offer this facility).
However, groups are not \emph{only} created by matching
\texttt{\obracesymbol{}} with \texttt{\cbracesymbol{}}:
other grouping commands are discussed elsewhere in these \acro{FAQ}s,
and are also a potential source of unclosed group.

\cmdinvoke{begin}{\meta{environment}} encloses the environment's body
in a group, and establishes its own diagnostic mechanism.  If you end
the document before closing some other environment, you get the
`usual' \LaTeX{} diagnostic
\htmlignore
\begin{dviversion}
\begin{verbatim}
! LaTeX Error: \begin{blah} on input line 6
                       ended by \end{document}.
\end{verbatim}
\end{dviversion}
\begin{pdfversion}
\begin{verbatim}
! LaTeX Error: \begin{blah} on input line 6 ended by \end{document}.
\end{verbatim}
\end{pdfversion}
\endhtmlignore
\begin{htmlversion}
\begin{verbatim}
! LaTeX Error: \begin{blah} on input line 6 ended by \end{document}.
\end{verbatim}
\end{htmlversion}
which (though it doesn't tell you which \emph{file} the
\cmdinvoke{begin}{blah} was in) is usually enough to locate the
immediate problem.  If you press on past the \LaTeX{} error, you get
one or more repetitions of the ``occurred inside a group'' message
before \LaTeX{} finally exits.  The \Package{checkend} package
recognises other unclosed \cmdinvoke{begin}{blob} commands, and
generates an ``ended by'' error message for each one, rather than
producing the ``occurred inside a group'' message, which is sometimes
useful (if you remember to load the package).

In the absence of such information from \LaTeX{}, you need to use
``traditional'' binary search to find the offending group.  Separate
the preamble from the body of your file, and process each half on its
own with the preamble; this tells you which half of the file is at
fault.  Divide again and repeat.  The process needs to be conducted
with care (it's obviously possible to split a correctly-written group
by chopping in the wrong place), but it will usually find the problem
fairly quickly.

\eTeX{} (and \elatex{}~--- \LaTeX{} run on \eTeX{}) gives you
further diagnostics after the traditional infuriating \TeX{} one~--- it
actually keeps the information in a similar way to \LaTeX{}:
\htmlignore
\begin{dviversion}
\begin{verbatim}
(\end occurred inside a group at level 3)

### semi simple group (level 3) entered
                         at line 6 (\begingroup)
### simple group (level 2) entered at line 5 ({)
### simple group (level 1) entered at line 4 ({)
### bottom level
\end{verbatim}
\end{dviversion}
\begin{pdfversion}
\begin{verbatim}
(\end occurred inside a group at level 3)

### semi simple group (level 3) entered at line 6 (\begingroup)
### simple group (level 2) entered at line 5 ({)
### simple group (level 1) entered at line 4 ({)
### bottom level
\end{verbatim}
\end{pdfversion}
\endhtmlignore
\begin{htmlversion}
\begin{verbatim}
(\end occurred inside a group at level 3)

### semi simple group (level 3) entered at line 6 (\begingroup)
### simple group (level 2) entered at line 5 ({)
### simple group (level 1) entered at line 4 ({)
### bottom level
\end{verbatim}
\end{htmlversion}
The diagnostic not only tells us where the group started, but also the
\emph{way} it started: \csx{begingroup} or |{| (which is an alias of
\csx{bgroup}, and the two are not  distinguishable at the \TeX{}-engine
level).
\begin{ctanrefs}
\item[checkend.sty]Distributed as part of \CTANref{bezos}
\end{ctanrefs}

\Question[Q-nonum]{``Missing number, treated as zero''}

In general, this means you've tried to assign something to a count,
dimension or skip register that isn't (in \TeX{}'s view of things) a
number.  Usually the problem will become clear using the
\Qref*{ordinary techniques of examining errors}{Q-erroradvice}.

Two \LaTeX{}-specific errors are commonly aired on the newsgroups.

The commonest arises from attempting to use an example from the
\Qref*{\emph{The \LaTeX{} Companion} (first edition)}{Q-books}, and is
exemplified by the following error text:
\begin{verbatim}
! Missing number, treated as zero.
<to be read again> 
                   \relax 
l.21 \begin{Ventry}{Return values}
\end{verbatim}
The problem arises because, in its first edition, the
\emph{Companion}'s examples always assumed that the \Package{calc}
package is loaded: this fact is mentioned in the book, but often not
noticed.  The remedy is to load the \Package{calc} package in any
document using such examples from the \emph{Companion}.  (The problem
does not really arise with the second edition; copies of all the
examples are available on the accompanying \CDROM{}, or on
\acro{CTAN}.)

The other problem, which is increasingly rare nowadays, arises from
misconfiguration of a system that has been upgraded from \LaTeXo{}:
the document uses the \Package{times} package, and the error appears
at \cmdinvoke{begin}{document}.  The file search paths are wrongly set
up, and your \cmdinvoke{usepackage}{times} has picked up a \LaTeXo{}
version of the package, which in its turn has invoked another which
has no equivalent in \LaTeXe{}.  The obvious solution is to rewrite
the paths so that \LaTeXo{} packages are chosen only as a last resort
so that the startlingly simple \LaTeXe{} \Package{times} package will
be picked up.  Better still is to replace the whole thing with
something more modern still; current \Package{psnfss} doesn't provide
a \Package{times} package~--- the alternative \Package{mathptmx}
incorporates \FontName{Times}-like mathematics, and a sans-serif face
based on \FontName{Helvetica}, but scaled to match \FontName{Times}
text rather better.
\begin{ctanrefs}
\item[calc.sty]Distributed as part of \CTANref{2etools}
\item[\nothtml{\rmfamily}Examples for \nothtml{\upshape}\LaTeX{} Companion]\CTANref{tlc2}
\item[The psnfss bundle]\CTANref{psnfss}
\end{ctanrefs}

\Question[Q-typend]{``Please type a command or say \csx{end}''}

Sometimes, when you are running \AllTeX{}, it will abruptly stop and
present you with a prompt (by default, just a |*| character).  Many
people (including this author) will reflexively hit the `return'
key, pretty much immediately, and of course this is no help at all~---
\TeX{} just says:
\begin{verbatim}
(Please type a command or say `\end')
\end{verbatim}
and prompts you again.

What's happened is that your \AllTeX{} file has finished prematurely,
and \TeX{} has fallen back to a supposed including file, from the
terminal.  This could have happened simply because you've omitted
the \csx{bye} (\plaintex{}), \cmdinvoke{end}{document} (\LaTeX{}), or
whatever.  Other common errors are failure to close the braces round a
command's argument, or (in \LaTeX{}) failure to close a verbatim
environment: in such cases you've already read and accepted an
error message about encountering end of file while scanning something.

If the error is indeed because you've forgotten to end your document,
you can insert the missing text: if you're running \plaintex{}, the
advice, to ``say \csx{end}'' is good enough: it will kill the run; if
you're running \LaTeX{}, the argument will be necessary:
\cmdinvoke{end}{document}.  

However, as often as not this isn't the problem, and (short of
debugging the source of the document before ending) brute force is
probably necessary.  Excessive force (killing the job that's
running \TeX{}) is to be avoided: there may well be evidence in the
\extension{log} file that will be useful in determining what the
problem is~--- so the aim is to persuade \TeX{} to shut itself down
and hence flush all log output to file.

If you can persuade \TeX{} to read it, an end-of-file indication
(control-|D| under Unix, control-|Z| under Windows) will provoke
\TeX{} to report an error and exit immediately.  Otherwise you should
attempt to provoke an error dialogue, from which you can exit (using
the |x| `command').  An accessible error could well be inserting an
illegal character: what it is will depend on what macros you are
running.  If you can't make that work, try a silly command name or
two.

\Question[Q-unkgrfextn]{``Unknown graphics extension''}

The \LaTeX{} graphics package deals with several different types of
\acro{DVI} (or other) output drivers; each one of them has a potential
to deal with a different selection of graphics formats.  The package
therefore has to be told what graphics file types its output driver
knows about; this is usually done in the \meta{driver}\extension{def} file
corresponding to the output driver you're using.

The error message arises, then, if you have a graphics file whose
extension doesn't correspond with one your driver knows about.  Most
often, this is because you're being optimistic: asking
\ProgName{dvips} to deal with a \extension{png} file, or \PDFTeX{} to deal with
a \extension{eps} file: the solution in this case is to transform the graphics
file to a format your driver knows about.

If you happen to \emph{know} that your device driver deals with the
format of your file, you are probably falling foul of a limitation of
the file name parsing code that the graphics package uses.  Suppose
you want to include a graphics file \File{home.bedroom.eps} using the
\ProgName{dvips} driver; the package will conclude that your file's
extension is \extension{bedroom.eps}, and will complain.

The \Package{grffile} package deals with the last problem (and
others~--- see the package documentation); using the package, you may
write:
\begin{quote}
\begin{verbatim}
\usepackage{graphicx}
\usepackage{grffile}
...
\includegraphics{home.bedroom.eps}
\end{verbatim}
\end{quote}
or you may even write
\begin{quote}
\begin{verbatim}
\includegraphics{home.bedroom}
\end{verbatim}
\end{quote}
and \Package{graphicx} will find a \extension{eps} or \extension{pdf}
(or whatever) version, according to what version of \AllTeX{} you're
running.

If for some reason you can't use \Package{grffile}, you have three
unsatisfactory alternatives:
\begin{itemize}
\item Rename the file~--- for example \File{home.bedroom.eps}\arrowhyph{}%
  \File{home-bedroom.eps}
\item Mask the first dot in the file name:
\begin{verbatim}
\newcommand*{\DOT}{.}
\includegraphics{home\DOT bedroom.eps}
\end{verbatim}
\item Tell the graphics package what the file is, by means of options
  to the \csx{includegraphics} command:
\begin{narrowversion}
\begin{verbatim}
\includegraphics[type=eps,ext=.eps,
                 read=.eps]{home.bedroom}
\end{verbatim}
\end{narrowversion}
\begin{wideversion}
\begin{verbatim}
\includegraphics[type=eps,ext=.eps,read=.eps]{home.bedroom}
\end{verbatim}
\end{wideversion}
\end{itemize}
\begin{ctanrefs}
\item[grffile.sty]Distributed as part of the \CTANref{oberdiek} collection
\end{ctanrefs}

\Question[Q-nodollar]{``Missing \texttt{\$} inserted''}

There are certain things that \emph{only} work in maths mode.  If your
document is not in maths mode and you have an |_| or a |^| character,
\TeX{} (and by inheritance, \LaTeX{} too) will say
\begin{verbatim}
! Missing $ inserted
\end{verbatim}
as if you couldn't possibly have misunderstood the import of what you
were typing, and the only possible interpretation is that you had
committed a typo in failing to enter maths mode.  \TeX{}, therefore,
tries to patch things up by inserting the \texttt{\$} you `forgot', so that
the maths-only object will work; as often as not this will land you in
further confusion.

It's not just the single-character maths sub- and superscript
operators: anything that's built in or declared as a maths operation,
from the simplest lower-case \csx{alpha} through the inscrutable
\csx{mathchoice} primitive, and beyond, will provoke the error if
misused in text mode.

\LaTeX{} offers a command \csx{ensuremath}, which will put you in maths
mode for the execution of its argument, if necessary: so if you want
an \csx{alpha} in your running text, say
\cmdinvoke{ensuremath}{\csx{alpha}}; if the bit of running text somehow
transmutes into a bit of mathematics, the \csx{ensuremath} will become
a no-op, so it's pretty much always safe.

\Question[Q-fontunavail]{Warning: ``Font shape \dots{}\ not available''}

\LaTeX{}'s font selection scheme maintains tables of the font families
it has been told about.  These tables list the font families that
\LaTeX{} knows about, and the shapes and series in which those font
families are available.  In addition, in some cases, the tables list
the sizes at which \LaTeX{} is willing to load fonts from the family.

When you specify a font, using one of the \LaTeX{} font selection
commands, \LaTeX{} looks for the font (that is, a font that matches
the encoding, family, shape, series and size that you want) in its
tables.  If the font isn't there at the size you want, you will see a
message like:
\htmlignore
\begin{dviversion}
\begin{verbatim}
LaTeX Font Warning: Font shape `OT1/cmr/m/n' in
...                 size <11.5> not available
(Font)              size <12> substituted on
...                 input line ...
\end{verbatim}
(All the message texts in this answer have been wrapped so that they
will fit in the narrow columns of this version of the \acro{FAQ}.  The
continuation marker is |...| at the start of the broken-off portion of
the line.)

\end{dviversion}
\begin{pdfversion}
\begin{verbatim}
LaTeX Font Warning: Font shape `OT1/cmr/m/n' in size <11.5> not available
(Font)              size <12> substituted on input line ...
\end{verbatim}
\end{pdfversion}
\endhtmlignore
\begin{htmlversion}
\begin{verbatim}
LaTeX Font Warning: Font shape `OT1/cmr/m/n' in size <11.5> not available
(Font)              size <12> substituted on input line ...
\end{verbatim}
\end{htmlversion}
There will also be a warning like:
\htmlignore
\begin{dviversion}
\begin{verbatim}
LaTeX Font Warning: Size substitutions with
...                 differences
(Font)              up to 0.5pt have occurred.
\end{verbatim}
\end{dviversion}
\begin{pdfversion}
\begin{verbatim}
LaTeX Font Warning: Size substitutions with differences
(Font)              up to 0.5pt have occurred.
\end{verbatim}
\end{pdfversion}
\endhtmlignore
\begin{htmlversion}
\begin{verbatim}
LaTeX Font Warning: Size substitutions with differences
(Font)              up to 0.5pt have occurred.
\end{verbatim}
\end{htmlversion}
after \LaTeX{} has encountered \cmdinvoke{end}{document}.

The message tells you that you've chosen a font size that is not in
\LaTeX{}'s list of ``allowed'' sizes for this font; \LaTeX{} has
chosen the nearest font size it knows is allowed.  In fact, you can
tell \LaTeX{} to allow \emph{any} size: the restrictions come from the
days when only bitmap fonts were available, and they have never
applied to fonts that come in scaleable form in the first place.
Nowadays, most of the fonts that were once bitmap-only are also
available in scaleable (Adobe Type~1) form.  If your installation uses
scaleable versions of the Computer Modern or European Computer Modern
(\acro{EC}) fonts, you can tell \LaTeX{} to remove the restrictions;
use the \Package{type1cm} or \Package{type1ec} package as appropriate.

If the combination of font shape and series isn't available, \LaTeX{}
will usually have been told of a fall-back combination that may be
used, and will select that:
\htmlignore
\begin{dviversion}
\begin{verbatim}
LaTeX Font Warning: Font shape `OT1/cmr/bx/sc'
...                 undefined
(Font)              using `OT1/cmr/bx/n'
...                 instead on input line 0.
\end{verbatim}
\end{dviversion}
\begin{pdfversion}
\begin{verbatim}
LaTeX Font Warning: Font shape `OT1/cmr/bx/sc' undefined
(Font)              using `OT1/cmr/bx/n' instead on input line 0.
\end{verbatim}
\end{pdfversion}
\endhtmlignore
\begin{htmlversion}
\begin{verbatim}
LaTeX Font Warning: Font shape `OT1/cmr/bx/sc' undefined
(Font)              using `OT1/cmr/bx/n' instead on input line 0.
\end{verbatim}
\end{htmlversion}

Substitutions may also be ``silent''; in this case, there is no more
than an ``information'' message in the log file.  For example, if you
specify an encoding for which there is no version in the current font
family, the `default family for the encoding' is selected.  This
happens, for example, if you use command \csx{textbullet}, which is
normally taken from the maths symbols font, which is in |OMS|
encoding.  My test log contained:
\htmlignore
\begin{dviversion}
\begin{verbatim}
LaTeX Font Info:    Font shape `OMS/cmr/m/n' in
...                 size <10> not available
(Font)              Font shape `OMS/cmsy/m/n'
...                 tried instead on input
...                 line ...
\end{verbatim}
\end{dviversion}
\begin{pdfversion}
\begin{verbatim}
LaTeX Font Info:    Font shape `OMS/cmr/m/n' in size <10> not available
(Font)              Font shape `OMS/cmsy/m/n' tried instead on input line ...
\end{verbatim}
\end{pdfversion}
\endhtmlignore
\begin{htmlversion}
\begin{verbatim}
LaTeX Font Info:    Font shape `OMS/cmr/m/n' in size <10> not available
(Font)              Font shape `OMS/cmsy/m/n' tried instead on input line ...
\end{verbatim}
\end{htmlversion}

In summary, these messages are not so much error messages, as
information messages, that tell you what \LaTeX{} has made of your
text.  You should check what the messages say, but you will ordinarily
not be surprised at their content.
\begin{ctanrefs}
\item[type1cm.sty]\CTANref{type1cm}
\item[type1ec.sty]\CTANref{type1ec}
\end{ctanrefs}

\Question[Q-buffovl]{Unable to read an entire line}

\TeX{} belongs to the generation of applications written for
environments that didn't offer the sophisticated string and i/o
manipulation we nowadays take for granted (\TeX{} was written in
Pascal, and the original Pascal standard made no mention of i/o, so
that anything but the most trivial operations were likely to be
unportable).

When you overwhelm \TeX{}'s input mechanism, you get told:
\begin{verbatim}
! Unable to read an entire line---bufsize=3000.
    Please ask a wizard to enlarge me.
\end{verbatim}
(for some value of `3000'~--- the quote was from a
\Newsgroup{comp.text.tex} posting by a someone who was presumably
using an old \TeX{}).

As the message implies, there's (what \TeX{} thinks of as a) line in
your input that's ``too long'' (to \TeX{}'s way of thinking).  Since
modern distributions tend to have tens of thousands of bytes of input
buffer, it's somewhat rare that these messages occur ``for real''.
Probable culprits are:
\begin{itemize}
\item A file transferred from another system, without translating
  record endings.  With the decline of fixed-format records (on
  mainframe operating systems) and the increased intelligence of
  \TeX{} distributions at recognising other systems' explicit
  record-ending characters, this is nowadays rather a rare cause of
  the problem.
\item A graphics input file, which a package is examining for its
  bounding box, contains a binary preview section.  Again,
  sufficiently clever \TeX{} distributions recognise this situation,
  and ignore the previews (which are only of interest, if at all, to a
  \TeX{} previewer).
\end{itemize}

The usual advice is to ignore what \TeX{} says (i.e., anything about
enlarging), and to put the problem right in the source. 

If the real problem is over-long text lines, most self-respecting text
editors will be pleased to automatically split long lines (while
preserving the ``word'' structure) so that they are nowhere any longer
than a given length; so the solution is just to edit the file.

If the problem is a ridiculous preview section, try using
\ProgName{ghostscript} to reprocess the file, outputting a ``plain
\extension{eps}'' file.  (\ProgName{Ghostscript} is distributed with a script
\ProgName{ps2epsi} which will regenerate the preview if necessary.)
Users of the shareware program \ProgName{GSview} will find buttons to
perform the required transformation of the file being displayed.
\begin{ctanrefs}
\item[ghostscript]Browse \CTANref{ghostscript}
\item[GSview]Browse \CTANref{gsview}
\end{ctanrefs}

\Question[Q-formatstymy]{``Fatal format file error; I'm stymied''}

\AllTeX{} applications often fail with this error when you've been
playing with the configuration, or have just installed a new version.

The format file contains the macros that define the system you want to
use: anything from the simplest (\plaintex{}) all the way to the most
complicated, such as \LaTeX{} or \CONTeXT{}.  From the command you
issue, \TeX{} knows which format you want.

The error message
\begin{verbatim}
  Fatal format file error; I'm stymied
\end{verbatim}
means that \TeX{} itself can't understand the format you want.
Obviously, this could happen if the format file had got corrupted, but
it usually doesn't.  The commonest cause of the message, is that a new
binary has been installed in the system: no two \TeX{} binaries on the
same machine can
understand each other's formats.  So the new version of \TeX{} you
have just installed, won't understand the format generated by the one
you installed last year.

Resolve the problem by regenerating the format; of course, this
depends on which system you are using.
\begin{itemize}
\item On a te\TeX{}-based system, run
\begin{verbatim}
  fmtutil --all
\end{verbatim}
  or
\begin{verbatim}
  fmtutil --byfmt=<format name>
\end{verbatim}
  to build only the format that you are interested in.
\item On a \miktex{} system, click \texttt{Start}\arrowhyph{}%
\texttt{Programs}\arrowhyph{}%
\texttt{\miktex{} \emph{version}}\arrowhyph{}%
\texttt{\miktex{} Options}, and in the options window, click
  \texttt{Update now}.
\end{itemize}

\Question[Q-nonpdfsp]{Non-\acro{PDF} special ignored!}

This is a \PDFTeX{} error: \PDFTeX{} is running in \acro{PDF} output
%  beware line break at end line
mode, and it has encountered a \nothtml{\csx{special} command (}%
\Qref{\csx{special}}{Q-specials}\latexhtml{)}{ command}.  \PDFTeX{} is
able to generate its own output, and in this mode of operation has no
need of \csx{special} commands (which allow the user to pass
information to the driver being used to generate output).

Why does this happen?  \LaTeX{} users, nowadays, hardly ever use
\csx{special} commands on their own~--- they employ packages to do the
job for them.  Some packages will generate \csx{special} commands
however they are invoked: \Package{pstricks} is an example (it's very
raison d'\^etre is to emit \PS{} code in a sequence of \csx{special}
commands).  \Package{Pstricks} may be dealt with by other means (the
\Package{pdftricks} package offers a usable technique).

More amenable to correction, but more confusing, are packages (such as
\Package{color}, \Package{graphics} and \Package{hyperref}) that
specify a ``driver''.  These packages have plug-in modules that
determine what \csx{special} (or other commands) are needed to generate
any given effect: the \texttt{pdftex} driver for such packages knows not to
generate \csx{special} commands.  In most circumstances, you can let
the system itself choose which driver you need; in this case
everything will act properly when you switch to using \PDFLaTeX{}.  If
you've been using \ProgName{dvips} (and specifying the |dvips| driver)
or \ProgName{dvipdfm} (for which you have to specify the driver), and
decide to try \PDFLaTeX{}, you \emph{must} remove the |dvips| or
|dvipdfm| driver specification from the package options, and let the
system recognise which driver is needed.
\begin{ctanrefs}
\item[pdftricks.sty]\CTANref{pdftricks}
\item[pstricks.sty]\CTANref{pstricks}
\end{ctanrefs}

\Question[Q-8000]{Mismatched mode ljfour and resolution 8000}

You're running \ProgName{dvips}, and you encounter a stream of error
messages, starting with ``\texttt{Mismatched mode}''.  The mode is the
default used in your installation~--- it's set in the \ProgName{dvips}
configuration file, and \texttt{ljfour} is commonest (since it's the
default in most distributions), but not invariable.

The problem is that \ProgName{dvips} has encountered a font for which
it must generate a bitmap (since it can't find it in Type~1 format),
and there is no proforma available to provide instructions to give to
\MF{}.

So what to do?  The number 8000 comes from the `\texttt{-Ppdf}' option
to \ProgName{dvips}, which you might have found from the answer
\nothtml{``wrong type of fonts'' (}% beware % beware line breaks
\Qref{``wrong type of fonts''}{Q-fuzzy-type3}\nothtml{)}.  The obvious
solution is to switch to the trivial substitute `\texttt{-Pwww}',
which selects the necessary type~1 fonts for \acro{PDF} generation,
but nothing else: however, this will leave you with undesirable bitmap
fonts in your \acro{PDF} file.  The ``proper'' solution is to find a
way of expressing what you want to do, using type~1 fonts.

\Question[Q-toodeep]{``Too deeply nested''}

This error appears when you start a \LaTeX{} list.

\LaTeX{} keeps track of the nesting of one list inside another.  There
is a set of list formatting parameters built-in for application to
each of the list nesting levels; the parameters determine indentation,
item separation, and so on.  The \environment{list} environment (the
basis for list environments like \environment{itemize} and
\environment{enumerate}) ``knows'' there are only 6 of these sets.

There are also different label definitions for the
\environment{enumerate} and \environment{itemize} environments at
their own private levels of nesting.  Consider this example:
\begin{quote}
\begin{verbatim}
\begin{enumerate}
\item first item of first enumerate
  \begin{itemize}
  \item first item of first itemize
    \begin{enumerate}
    \item first item of second enumerate
    ...
    \end{enumerate}
  ...
  \end{itemize}
...
\end{enumerate}
\end{verbatim}
\end{quote}
In the example,
\begin{itemize}
\item the first \environment{enumerate} has labels as for a
  first-level \environment{enumerate}, and is indented as for a
  first-level list;
\item the first \environment{itemize} has labels as for a first level
  \environment{itemize}, and is indented as for a second-level list;
  and
\item the second \environment{enumerate} has labels as for a
  second-level \environment{enumerate}, and is indented as for a
  third-level list.
\end{itemize}
Now, as well as \LaTeX{} \emph{knowing} that there are 6~sets of
parameters for indentation, it also \emph{knows} that there are only
4~types of labels each, for the environments \environment{enumerate}
and \environment{itemize} (this ``knowledge'' spells out a requirement
for class writers, since the class supplies the sets of parameters).

From the above, we can deduce that there are several ways we can run
out of space: we can have 6~lists (of any sort) nested, and try to
start a new one; we can have 4~\environment{enumerate} environments
somewhere among the set of nested lists, and try to add another one;
and we can have 4~\environment{itemize} environments somewhere among
the set of nested lists, and try to add another one.

What can be done about the problem?  Not much, short of rewriting
\LaTeX{}~--- you really need to rewrite your document in a slightly
less labyrinthine way.

\Question[Q-inputlev]{Capacity exceeded~--- input levels}

The error
\begin{wideversion}
\begin{verbatim}
! TeX capacity exceeded, sorry [text input levels=15].
\end{verbatim}
\end{wideversion}
\begin{narrowversion}
\begin{verbatim}
! TeX capacity exceeded, sorry
                         [text input levels=15].
\end{verbatim}
\end{narrowversion}
is caused by nesting your input too deeply.  You can provoke it with
the trivial (\plaintex{}) file \File{input.tex}, which contains
nothing but: 
\begin{verbatim}
\input input
\end{verbatim}
In the real world, you are unlikely to encounter the error with a
modern \TeX{} distribution.  Te\TeX{} (used to produce the error
message above) allows 15 files open for \TeX{} input at any one time,
which is improbably huge for a document generated by real human
beings.

However, for those improbable (or machine-generated) situations,
some distributions offer the opportunity to adjust the parameter
|max_in_open| in a configuration file.

\Question[Q-hyperdupdest]{\PDFTeX{} destination \dots{}\ ignored}

The warning:
\begin{quote}
\begin{wideversion}
\begin{verbatim}
! pdfTeX warning (ext4): destination with the same identifier
(name{page.1}) has been already used, duplicate ignored
\end{verbatim}
\end{wideversion}
\begin{narrowversion}
\begin{verbatim}
! pdfTeX warning (ext4): destination with
  the same identifier (name{page.1}) has
  been already used, duplicate ignored
\end{verbatim}
{\small NB: message text wrapped to fit in the column\par}
\end{narrowversion}
\end{quote}
arises because of duplicate page numbers in your document.  The
problem is usually soluble: see % beware line break
\Qref*[question]{\acro{PDF} page destinations}{Q-pdfpagelabels}~--- which
answer also describes the problem in more detail.

If the identifier in the message is different, for example
\texttt{name\{figure.1.1\}}, the problem is (often) due to a problem of
package interaction.  The \File{README} in the \Package{hyperref}
distribution mentions some of these issues~--- for example,
\environment{equation} and \environment{eqnarray} as supplied by the
\Package{amsmath} package; means of working around the problem are
typically supplied there.

Some packages are simply incompatible with
\Package{hyperref}, but most work simply by ignoring it.  In most
cases, therefore, you should load your package before you load
\Package{hyperref}, and \Package{hyperref} will patch things up so
that they work, so you can utilise your (patched) package \emph{after}
loading both:
\begin{quote}
  \cmdinvoke{usepackage}{\emph{your package}}\\
  \texttt{...}\\
  \cmdinvoke{usepackage}[\emph{opts}]{hyperref}\\
  \texttt{...}\\
  \meta{code that uses your package}
\end{quote}
\begin{wideversion}
For example:
\begin{quote}
\begin{verbatim}
\usepackage{float}          % defines \newfloat
...
\usepackage[...]{hyperref}  % patches \newfloat
...
\newfloat{...}{...}{...}
\end{verbatim}
\end{quote}
\end{wideversion}
\begin{narrowversion}
So, if we need \csx{newfloat}:
\begin{quote}
\cmdinvoke{usepackage}{float}
\end{quote}
will define the command,
\begin{quote}
\cmdinvoke{usepackage}[\emph{opts}]{hyperref}
\end{quote}
will patch it, and now: 
\begin{quote}
\cmdinvoke{newfloat}{...}{...}{...}
\end{quote}
will use the command, patched to create `proper' hyperreferences.
\end{narrowversion}
You should load packages in this order as a matter of course, unless
the documentation of a package says you \emph{must} load it after
\Package{hyperref}.  (There are few packages that require to be
loaded after hyperref: one such is \Class{memoir}'s
``\Package{hyperref} fixup'' package \Package{memhfixc}.)

If loading your packages in the (seemingly) ``correct'' order doesn't
solve the problem, you need to \Qref*{seek further help}{Q-gethelp}.

\Question[Q-altabcr]{Alignment tab changed to \csx{cr}}

This is an error you may encounter in \LaTeX{} when a tabular
environment is being processed.  ``Alignment tabs'' are the
\texttt{\&} signs that separate the columns of a tabular; so the error
message
\begin{quote}
\begin{narrowversion}
\begin{verbatim}
! Extra alignment tab has been 
                            changed to \cr
\end{verbatim}
\end{narrowversion}
\begin{wideversion}
\begin{verbatim}
! Extra alignment tab has been changed to \cr
\end{verbatim}
\end{wideversion}
\end{quote}
could arise from a simple typo, such as:
\begin{quote}
\begin{verbatim}
\begin{tabular}{ll}
  hello   & there & jim \\
  goodbye & now
\end{tabular}
\end{verbatim}
\end{quote}
where the second \texttt{\&} in the first line of the table is more than the
two-column \texttt{ll} column specification can cope with. In this
case, an extra ``\texttt{l}'' in that solves the problem.  (If you
continue from the error in this case, ``\texttt{jim}'' will be moved
to a row of his own.)  Another simple typo that can provoke the error
is:
\begin{quote}
\begin{verbatim}
\begin{tabular}{ll}
  hello   & there
  goodbye & now
\end{tabular}
\end{verbatim}
\end{quote}
where the `\texttt{\bsbs }' has been missed from the first line of the table.
In this case, if you continue from the error, you will find that
\LaTeX{} has made a table equivalent to:
\begin{quote}
\begin{verbatim}
\begin{tabular}{ll}
  hello   & there goodbye\\
  now
\end{tabular}
\end{verbatim}
\end{quote}
(with the second line of the table having only one cell).

Rather more difficult to spot is the occurrence of the error when
you're using alignment instructions in a ``\texttt{p}'' column:
\begin{quote}
\begin{verbatim}
\usepackage{array}
...
\begin{tabular}{l>{\raggedright}p{2in}}
here & we are again \\
happy & as can be
\end{tabular}
\end{verbatim}
\end{quote}
the problem here (as explained in % ! line break
\Qref[question]{tabular cell alignment}{Q-tabcellalign}) is that the
\csx{raggedright} command in the column specification has overwritten
\environment{tabular}'s definition of \texttt{\bsbs }, so that
``\texttt{happy}'' appears in a new line of the second column, and the
following \texttt{\&} appears to \LaTeX{} just like the second
\texttt{\&} in the first example above.

Get rid of the error in the way described in % ! linebreak
\Qref[question]{tabular cell alignment}{Q-tabcellalign}~--- either use
\csx{tabularnewline} explicitly, or use the \csx{RBS} trick described
there.
\begin{ctanrefs}
\item[array.sty]Distributed as part of \CTANref{2etools}
\end{ctanrefs}

\Question[Q-divzero]{Graphics division by zero}

While the error
\begin{quote}
\begin{verbatim}
! Package graphics Error: Division by 0.
\end{verbatim}
\end{quote}
can actually be caused by offering the package a figure which claims
to have a zero dimension, it's more commonly caused by rotation.

Objects in \TeX{} may have both height (the height above the baseline)
and depth (the distance the object goes below the baseline).  If you
rotate an object by 180\,degrees, you convert its height into depth,
and vice versa; if the object started with zero depth, you've
converted it to a zero-height object.

Suppose you're including your graphic with a command like:
\begin{quote}
\begin{wideversion}
\begin{verbatim}
\includegraphics[angle=180,height=5cm]{myfig.eps}
\end{verbatim}
\end{wideversion}
\begin{narrowversion}
\begin{verbatim}
\includegraphics[angle=180,%
                height=5cm]{myfig.eps}
\end{verbatim}
\end{narrowversion}
\end{quote}
In the case that \File{myfig.eps} has no depth to start with, the
scaling calculations will produce the division-by-zero error.

Fortunately, the \Package{graphicx} package has a keyword
\pkgoption{totalheight}, which allows you to specify the size of the
image relative to the sum of the object's \pkgoption{height} and
\pkgoption{depth}, so
\begin{quote}
\begin{wideversion}
\begin{verbatim}
\includegraphics[angle=180,totalheight=5cm]{myfig.eps}
\end{verbatim}
\end{wideversion}
\begin{narrowversion}
\begin{verbatim}
\includegraphics[angle=180,%
           totalheight=5cm]{myfig.eps}
\end{verbatim}
\end{narrowversion}
\end{quote}
will resolve the error, and will behave as you might hope.

If you're using the simpler \Package{graphics} package, use the
\texttt{*} form of the \csx{resizebox} command to specify the use of
\pkgoption{totalheight}:
\begin{quote}
\begin{verbatim}
\resizebox*{!}{5cm}{%
  \rotatebox{180}{%
    \includegraphics{myfig.eps}%
  }%
}
\end{verbatim}
\end{quote}
\begin{ctanrefs}
\item[graphics.sty,graphicx.sty]Both parts of the \CTANref{graphics} bundle
\end{ctanrefs}

\Question[Q-missbegdoc]{Missing \csx{begin}\marg{document}}

Give it a file of plain text, or a \LaTeX{} file that really does have no
\cmdinvoke{begin}{document} command in it, and \LaTeX{} will produce
this error, quite correctly.  \LaTeX{} \emph{needs}
\cmdinvoke{begin}{document} so as to know when to execute the commands
that finish off the document preamble.

Other than that, the error can occur as a result of an error of yours,
of a corrupt \extension{aux} file, or of a buggy class or package.

The errors you might commit are absent-mindedly typing a document
command (such as \csx{section}) in the preamble of your document,
missing the comment marker from the beginning of a line, or giving too
many arguments to one of the setup commands related to the class or a
package that you have loaded.

A corrupt \extension{aux} file might be due to any number of things;
delete the file and to run \LaTeX{} again, twice.  If the error
recurs, it's probably due to a buggy class or package.

If the error occurs while \LaTeX{} is reading a class or package, then
there's probably a bug in the file.  The author of the class or
package stands the best chance of finding the bug, but with luck you
(or someone you ask on a mailing list or on \Newsgroup{comp.text.tex})
will be able to spot the problem and provide a work-around.  Always
report such bugs, even if you have found a work-around.

\Question[Q-normalszmiss]{\csx{normalsize} not defined}

The \LaTeX{} error:
\begin{quote}
\begin{narrowversion}
\begin{verbatim}
The font size command \normalsize is not
   defined: there is probably something
   wrong with the class file.
\end{verbatim}
\end{narrowversion}
\begin{wideversion}
\begin{verbatim}
The font size command \normalsize is not defined:
there is probably something wrong with the class file.
\end{verbatim}
\end{wideversion}
\end{quote}
is reporting something pretty fundamental (document base font size not
set up).  While this \emph{can}, as the message implies, be due to a
broken class file, the more common cause is that you have simply
forgotten to put a \csx{documentclass} command in your document.

\Question[Q-manymathalph]{Too many math alphabets}

\TeX{} mathematics is one of its most impressive features, yet the
internal structure of the mechanism that produces it is painfully
complicated and (in some senses) pathetically limited.  One area of
limitation is that one is only allowed 16~''maths alphabets''

\LaTeX{} offers the user quite a lot of flexibility with allocating
maths alphabets, but few people use the flexibility directly.
Nevertheless, there are many packages that provide symbols, or that
manipulate them, which allocate themselves one or more maths alphabet.

If you can't afford to drop any of these packages, there's
still hope if you're using the \Package{bm} package to support
\Qref*{bold maths}{Q-boldgreek}: \Package{bm} is capable
of gobbling alphabets as if there is no tomorrow.  The package defines
two limiter commands: \csx{bmmax} (for \emph{bold} symbols; default~4)
and \csx{hmmax} (for \emph{heavy} symbols, if you have them;
default~3), which control the number of alphabets to be used.  

Any reduction of the \csx{\emph{xx}max} variables will slow
\Package{bm} down~--- but that's surely better than the document not
running at all.  So unless you're using maths fonts (such as
\FontName{Mathtime Plus}) that feature a heavy symbol weight, suppress all
use of heavy families by
\begin{quote}
\begin{verbatim}
  \renewcommand{\hmmax}{0}
\end{verbatim}
\end{quote}
and then steadily reduce the bold families, starting with
\begin{quote}
\begin{verbatim}
  \renewcommand{\bmmax}{3}
\end{verbatim}
\end{quote}
until (with a bit of luck) the error goes away.
\begin{ctanrefs}
\item[bm.sty]Distributed as part of \CTANref{2etools}
\end{ctanrefs}

\Question[Q-ouparmd]{Not in outer par mode}

The error:
\begin{quote}
\begin{verbatim}
! LaTeX Error: Not in outer par mode.
\end{verbatim}
\end{quote}
comes when some ``main'' document feature is shut up somewhere it
doesn't like.

The commonest occurrence is when the user wants a figure somewhere
inside a table:
\begin{quote}
\begin{verbatim}
\begin{tabular}{|l|}
  \hline
  \begin{figure}
  \includegraphics{foo}
  \end{figure}
  \hline
\end{tabular}
\end{verbatim}
\end{quote}
a construction that was supposed to put a frame around the diagram,
but doesn't work, any more than:
\begin{quote}
\begin{verbatim}
\framebox{\begin{figure}
  \includegraphics{foo}
  \end{figure}%
}
\end{verbatim}
\end{quote}
The problem is, that the \environment{tabular} environment, and the
\csx{framebox} command restrain the \environment{figure} environment
from its natural m\'etier, which is to float around the document.

The solution is simply not to use the \environment{figure} environment
here:
\begin{quote}
\begin{verbatim}
\begin{tabular}{|l|}
  \hline
  \includegraphics{foo}
  \hline
\end{tabular}
\end{verbatim}
\end{quote}
What was the float for?~--- as written in the first two examples, it
serves no useful purpose; but perhaps you actually wanted a diagram
and its caption framed, in a float.

It's simple to achieve this~--- just reverse the order of the
environments (or of the \environment{figure} environment and the
command):
\begin{quote}
\begin{verbatim}
\begin{figure}
  \begin{tabular}{|l|}
    \hline
    \includegraphics{foo}
    \caption{A foo}
    \hline
  \end{tabular}
\end{figure}
\end{verbatim}
\end{quote}
The same goes for \environment{table} environments (or any other sort
of float you've defined for yourself) inside tabulars or box commands;
you \emph{must} get the float environment out from inside, one way or
another.

\Question[Q-errmissitem]{Perhaps a missing \csx{item}?}

Sometimes, the error
\begin{quote}
\begin{verbatim}
Something's wrong--perhaps a missing \item
\end{verbatim}
\end{quote}
actually means what it says:
\begin{quote}
\begin{verbatim}
\begin{itemize}
  boo!
\end{itemize}
\end{verbatim}
\end{quote}
produces the error, and is plainly in need of an \csx{item} command.

You can also have the error appear when at first sight things are
correct:
\begin{quote}
\begin{verbatim}
\begin{tabular}{l}
  \begin{enumerate}
  \item foo\\
  \item bar
  \end{enumerate}
\end{tabular}
\end{verbatim}
\end{quote}
produces the error at the \texttt{\bsbs }.  This usage is just wrong; if you
want to number the cells in a table, you have to do it ``by hand'':
\begin{quote}
\begin{verbatim}
\newcounter{tablecell}
...
\begin{tabular}{l}
  \stepcounter{tablecell}
  \thetablecell. foo\\
  \stepcounter{tablecell}
  \thetablecell. bar
\end{tabular}
\end{verbatim}
\end{quote}
This is obviously untidy; a command \csx{numbercell} defined as:
\begin{quote}
\begin{verbatim}
\newcounter{tablecell}
...
\newcommand*{\numbercell}{%
  \stepcounter{tablecell}%
  \thetablecell. % **
}
\end{verbatim}
\end{quote}
could make life easier:
\begin{quote}
\begin{verbatim}
\begin{tabular}{l}
  \numbercell foo\\
  \numbercell bar
\end{tabular}
\end{verbatim}
\end{quote}
Note the deliberate introduction of a space as part of the command,
marked with asterisks.  Omitted above, the code needs to set the
counter \ltxcounter{tablecell} to zero
(\cmdinvoke{setcounter}{tablecell}{0}) before each tabular that uses it.

The error also regularly appears when you would never have thought
that a \csx{item} command  might be appropriate.  For example, the
seemingly innocent:
\begin{quote}
\begin{verbatim}
\fbox{%
  \begin{alltt}
    boo!
  \end{alltt}%
}
\end{verbatim}
\end{quote}
produces the error (the same happens with \csx{mbox} in place of
\csx{fbox}, or with either of their ``big brothers'', \csx{framebox} and
\csx{makebox}).  This is because the \environment{alltt} environment
uses a ``trivial'' list, hidden inside their definition.  (The
\environment{itemize} environment also has this construct inside
itself, in fact, so \cmdinvoke{begin}{itemize} won't work inside an
\csx{fbox}, either.)  The list construct wants to happen between
paragraphs, so it makes a new paragraph of its own.  Inside the
\csx{fbox} command, that doesn't work, and subsequent macros convince
themselves that there's a missing \csx{item} command.

To solve this rather cryptic error, one must put the
\environment{alltt} inside a paragraph-style box.  The following
modification of the above \emph{does} work:
\begin{quote}
\begin{verbatim}
\fbox{%
  \begin{minipage}{0.75\textwidth}
    \begin{alltt}
      hi, there!
    \end{alltt}
  \end{minipage}
}
\end{verbatim}
\end{quote}
The code above produces a box that's far too wide for the text.  One
may want to use something that allows % ! line break
\Qref*{variable size boxes}{Q-varwidth} in place of the
\environment{minipage} environment.

Oddly, although the \environment{verbatim} environment wouldn't work
inside a \csx{fbox} command argument (see % ! line break
\Qref[question]{verbatim in command arguments}{Q-verbwithin}), you
get an error that complains about \csx{item}: the environment's
internal list bites you before \environment{verbatim} has even had a
chance to create its own sort of chaos.

Another (seemingly) obvious use of \csx{fbox} also falls foul of this
error:
\begin{quote}
\begin{verbatim}
\fbox{\section{Boxy section}}
\end{verbatim}
\end{quote}
This is a case where you've simply got to be more subtle; you should
either write your own macros to replace the insides of \LaTeX{}'s
sectioning macros, or  look for some alternative in the packages
discussed in % ! line break
``\Qref*[question]{The style of section headings}{Q-secthead}''.

\Question[Q-errparnum]{Illegal parameter number in definition}

The error message means what it says.  In the simple case, you've
attempted a definition like:
\begin{quote}
\begin{verbatim}
\newcommand{\abc}{joy, oh #1!}
\end{verbatim}
\end{quote}
or (using \TeX{} primitive definitions):
\begin{quote}
\begin{verbatim}
\def\abc{joy, oh #1!}
\end{verbatim}
\end{quote}
In either of the above, the definition uses an argument, but the
programmer did not tell \AllTeX{}, in advance, that she was going to.
The fix is simple~--- \cmdinvoke{newcommand}{\csx{abc}}[1], in the
\LaTeX{} case, |\def\abc#1| in the basic \TeX{} case.

The more complicated case is exemplified by the attempted definition:
\begin{quote}
\begin{verbatim}
\newcommand{\abc}{joy, oh joy!%
  \newcommand{\ghi}[1]{gloom, oh #1!}%
}
\end{verbatim}
\end{quote}
will also produce this error, as will its \TeX{} primitive equivalent:
\begin{quote}
\begin{verbatim}
\def\abc{joy, oh joy!%
  \def\ghi#1{gloom, oh #1!}%
}
\end{verbatim}
\end{quote}
This is because special care is needed when defining one macro within
the code of another macro.  This is explained elsewhere, separately
for \Qref*[question]{\LaTeX{} definitions}{Q-ltxhash} and for
\Qref*[question]{\TeX{} primitive definitions}{Q-hash}

\Question[Q-fllost]{Float(s) lost}

The error
\begin{quote}
\begin{verbatim}
! LaTeX Error: Float(s) lost.
\end{verbatim}
\end{quote}
seldom occurs, but always seems deeply cryptic when it \emph{does}
appear.

The message means what it says: one or more figures, tables, etc., or
marginpars has not been typeset.  (Marginpars are treated internally
as floats, which is how they come to be lumped into this error
message.)

The most likely reason is that you placed a float or a \csx{marginpar}
command inside another float or marginpar, or inside a
\environment{minipage} environment, a \csx{parbox} or \csx{footnote}.
Note that the error may be detected a long way from the problematic
command(s), so the techniques of % ! line break
\Qref*{tracking down elusive errors}{Q-erroradvice} all need to be
called into play.

This author has also encountered the error when developing macros that
used the \LaTeX{} internal float mechanisms.  Most people doing that
sort of thing are expected to be able to work out their own problems\dots{}

\Question[Q-texorpdf]{Token not allowed in PDFDocEncoded string}

The package \Package{hyperref} produces this error when it doesn't
know how to make something into a ``character'' that will go into one
of its \acro{PDF} entries.  For example, the (unlikely) sequence
\begin{quote}
\begin{verbatim}
\newcommand{\filled}[2]{%
  #1%
  \hfil
  #2%
}
\section{\filled{foo}{bar}}
\end{verbatim}
\end{quote}
provokes the error.  \Package{Hyperref} goes on to tell you:
\begin{quote}
\begin{verbatim}
removing `\hfil' on input line ...
\end{verbatim}
\end{quote}
It's not surprising: how would \emph{you} put the
typesetting instruction \csx{hfil} into a \acro{PDF} bookmark?

\Package{Hyperref} allows you to define an alternative for such
things: the command \csx{texorpdfstring}, which takes two
arguments~--- the first is what is typeset, the second is what is put
into the bookmark.  For example, what you would probably like in this
case is just a single space in the bookmark; if so, the erroneous
example above would become:
\begin{quote}
\begin{verbatim}
\newcommand{\filled}[2]{%
  #1%
  \texorpdfstring{\hfil}{\space}%
  #2%
}
\section{\filled{foo}{bar}}
\end{verbatim}
\end{quote}
and with that definition, the example will compile succesfully
(\Package{hyperref} knows about the macro \csx{space}).
\LastEdit*{2009-05-29}

\Question[Q-optionclash]{Option clash for package}

So you've innocently added:
\begin{quote}
\cmdinvoke{usepackage}[draft]{graphics}
\end{quote}
to your document, and \LaTeX{} responds with
\begin{wideversion}
\begin{quote}
\begin{verbatim}
! LaTeX Error: Option clash for package graphics.
\end{verbatim}
\end{quote}
\end{wideversion}
\begin{narrowversion}
\begin{quote}
\begin{verbatim}
! LaTeX Error: Option clash for package
                                    graphics.
\end{verbatim}
\end{quote}
\end{narrowversion}

The error is a complaint about loading a package % ! line break
\emph{with options}, more than once (\LaTeX{} doesn't actually examine
what options there are: it complains because it can't do anything with
the multiple sets of options).  You can load a package
any number of times, with no options, and \LaTeX{} will be happy, but
you may only supply options when you first load the package.

So perhaps you weren't entirely innocent~--- the error would have
occurred on the second line of:
\begin{quote}
\cmdinvoke{usepackage}[dvips]{graphics}\\
\cmdinvoke{usepackage}[draft]{graphics}
\end{quote}
which could quite reasonably (and indeed correctly) have been typed:
\begin{quote}
\cmdinvoke{usepackage}[dvips,draft]{graphics}
\end{quote}

But if you've not made that mistake (even with several lines
separating the \csx{usepackage} commands, it's pretty easy to spot),
the problem could arise from something else loading the package for
you.  How do you find the culprit?  The "\texttt{h}" response to the
error message tells you which options were loaded each time.
Otherwise, it's down to the log analysis games discussed in % ! line break
``\Qref*{How to approach errors}{Q-erroradvice}''; the trick to remember
is that that the process of loading each file is parenthesised in the
log; so if package \Package{foo} loads \Package{graphics}, the log
will contain something like:
\begin{quote}
\begin{verbatim}
(<path>/foo.sty ...
...
(<path>/graphics.sty ...
...)
...
)
\end{verbatim}
\end{quote}
(the parentheses for \Package{graphics} are completely enclosed in
those for \Package{foo}; the same is of course true if your class
\Class{bar} is the culprit, except that the line will start with the
path to \texttt{bar.cls}).

If we're dealing with a package that loads the package you are
interested in, you need to ask \LaTeX{} to slip in options when
\Package{foo} loads it.  Instead of:
\begin{quote}
\cmdinvoke{usepackage}{foo}\\
\cmdinvoke{usepackage}[draft]{graphics}
\end{quote}
you would write:
\begin{quote}
\cmdinvoke{PassOptionsToPackage}{draft}{graphics}\\
\cmdinvoke{usepackage}{foo}
\end{quote}
The command \csx{PassOptionsToPackage} tells \LaTeX{} to behave as if
its options were passed, when it finally loads a package.  As you would
expect from its name, \csx{PassOptionsToPackage} can deal with a list
of options, just as you would have in the the options brackets of
\csx{usepackage}.

More trickily, instead of:
\begin{quote}
\cmdinvoke{documentclass}[...]{bar}\\
\cmdinvoke{usepackage}[draft]{graphics}
\end{quote}
you would write:
\begin{quote}
\cmdinvoke{PassOptionsToPackage}{draft}{graphics}\\
\cmdinvoke{documentclass}[...]{bar}
\end{quote}
with \csx{PassOptionsToPackage} \emph{before} the \csx{documentclass}
command.

However, if the \Package{foo} package or the \Class{bar} class loads
\Package{graphics} with an option of its own that clashes with
what you need in some way, you're stymied.  For example:
\begin{quote}
\cmdinvoke{PassOptionsToPackage}{draft}{graphics}
\end{quote}
where the package or class does:
\begin{quote}
\cmdinvoke{usepackage}[final]{graphics}
\end{quote}
sets \pkgoption{final} \emph{after} it's dealt with option you passed to
it, so your \pkgoption{draft} will get forgotten.  In extreme cases,
the package might generate an error here (\Package{graphics} doesn't
go in for that kind of thing, and there's no indication that
\pkgoption{draft} has been forgotten).

In such a case, you have to modify the package or class itself
(subject to the terms of its licence).  It may prove useful to contact
the author: she may have a useful alternative to suggest.

\Question[Q-checksum]{Checksum mismatch in font}

When \MF{} generates a font it includes a checksum in the font bitmap
file, and in the font metrics file (\acro{TFM}).  \AllTeX{} includes
the checksum from the \acro{TFM} file in the \acro{DVI} file.

When \ProgName{dvips} (or other \acro{DVI} drivers) process a
\acro{DVI} file, they compare checksums in the \acro{DVI} file to
those in the bitmap fonts being used for character images.  If the
checksums don't match, it means the font metric file used by \AllTeX{}
was not generated from the same \MF{} program that generated the
font.

This commonly occurs when you're processing someone else's \acro{DVI}
file.

The fonts on your system may also be at fault: possibilities are that
the new \acro{TFM} was not installed, or installed in a path after an
old \acro{TFM} file, or that you have a personal cache of bitmaps from
an old version of the font.

In any case, look at the output -- the chances are that it's perfectly
\acro{OK}, since metrics tend not to change, even when the bitmaps are
improved.  (Indeed, many font designers~--- Knuth included~---
maintain the metrics come what may.)

If the output \emph{does} look bad, your only chance is to regenerate
things from scratch.  Options include: flushing your bitmap cache,
rebuild the \acro{TFM} file locally, and so on.

\Question[Q-entercompmode]{Entering compatibility mode}

You run your \LaTeX{} job, and it starts by saying
\begin{quote}
\begin{verbatim}
Entering LaTeX 2.09 COMPATIBILITY MODE
\end{verbatim}
\end{quote}
followed by lines of asterisks and \texttt{!!WARNING!!}.

This means that the document is not written in ``current'' \LaTeX{}
syntax, and that there is no guarantee that all parts of the document
will be formatted correctly.

If the document is someone else's, and you want no more than a copy to
read, ignore the error.  The document may fail elsewhere, but as often
as not it will provide a \extension{dvi} or \extension{pdf} that's
adequate for most purposes.

If it's a new document you have just started working on, you have been
misled by someone.  You have written something like:
\begin{quote}
  \cmdinvoke{documentstyle}{article}
\end{quote}
or, more generally:
\begin{quote}
  \cmdinvoke*{documentstyle}[options]{class}
\end{quote}
These forms are (as the warning says) \LaTeXo{} syntax, and to get rid
of the warning, you must change the command.

The simple form is easy to deal with:
\begin{quote}
  \cmdinvoke{documentstyle}{article}
\end{quote}
should become:
\begin{quote}
  \cmdinvoke{documentclass}{article}
\end{quote}
The complex form is more difficult, since \LaTeXo{} ``options''
conflate two sorts of things~--- options for the class (such as
\pkgoption{11pt}, \pkgoption{fleqn}), and packages to be loaded.
So:
\begin{quote}
  \cmdinvoke{documentstyle}[11pt,verbatim]{article}
\end{quote}
should become:
\begin{quote}
  \cmdinvoke{documentclass}[11pt]{article}\\
  \cmdinvoke{usepackage}{verbatim}
\end{quote}
because \pkgoption{11pt} happens to be a class option, while
\Package{verbatim} is a package.

There's no simple way to work out what are class options under
\LaTeXo{}; for \Class{article}, the list includes \pkgoption{10pt},
\pkgoption{11pt}, \pkgoption{12pt}, \pkgoption{draft},
\pkgoption{fleqn}, \pkgoption{leqno}, \pkgoption{twocolumn} and
\pkgoption{twoside}~--- anything else must be a package.

Your document may well ``just work'' after changes like those above;
if not, you should think through what you're trying to do, and consult
documentation on how to do it~--- there are lots of % ! line break
\Qref*{free tutorials}{Q-tutorials*} to help you on your way, if you
don't have access to a \LaTeX{} manual of any sort.