diff options
Diffstat (limited to 'Master/texmf-dist/doc/generic/FAQ-en/archive-version/faq-jot-err.tex')
-rw-r--r-- | Master/texmf-dist/doc/generic/FAQ-en/archive-version/faq-jot-err.tex | 2415 |
1 files changed, 2415 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/generic/FAQ-en/archive-version/faq-jot-err.tex b/Master/texmf-dist/doc/generic/FAQ-en/archive-version/faq-jot-err.tex new file mode 100644 index 00000000000..23dd355da04 --- /dev/null +++ b/Master/texmf-dist/doc/generic/FAQ-en/archive-version/faq-jot-err.tex @@ -0,0 +1,2415 @@ +% $Id: faq-jot-err.tex,v 1.23 2012/11/10 14:25:12 rf10 Exp rf10 $ + +\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-tex-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}[trace] +\end{ctanrefs} +\LastEdit{2011-06-01} + +\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 similar (but more sensible): +\begin{quote} +\begin{verbatim} +\caption{Energy: \(e=mc^2\)} +\end{verbatim} +\end{quote} +is more tiresome, still: there's no error when you first run the +job~\dots{} but there is on the second pass, when the list of figures +(or tables) is generated, giving: +\begin{quote} +\begin{verbatim} +! LaTeX Error: Bad math environment delimiter. +\end{verbatim} +\end{quote} +in the \csx{listoffigures} processing. + +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} +However, 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: (Einstein's equation)]% + {Energy: \(E=mc^2\)} +\end{verbatim} +\end{narrowversion} +\begin{wideversion} +\begin{verbatim} +\caption[Energy: (Einstein's equation)]{Energy: \(E=mc^2\)} +\end{verbatim} +\end{wideversion} +\end{quote} +In practice, inserting mathematics in a moving argument has already +been addressed in \latexe{} by the robust command \csx{ensuremath}: +\begin{quote} +\begin{verbatim} +\caption{Energy: \ensuremath{E=mc^2}} +\end{verbatim} +\end{quote} +So: always look for alternatives to the \csx{protect} route. + +Footnotes can be even more complex; % ! line break +``\Qref*[question]{footnotes in \LaTeX{} section headings}{Q-ftnsect}'' +deals specifically with that issue. +\LastEdit{2012-02-09} + +\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 \Qref[question]{\etex{}}{Q-etex}, + \Qref[question]{\ensuremath{\Omega}}{Q-omegaleph} and + \Qref[question]{\LuaTeX{}}{Q-luatex} +\endhtmlignore +all do this, as does \Qref*{MicroPress Inc's V\TeX{}}{Q-commercial}. + +The commonest 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 also a common source of such problems. + +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 can be caused by packages +that use large numbers of ``inserts'' (inserts are 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} extensions allow you to deal with +these things: the command \cmdinvoke*{reserveinserts}{n} ensures there +is room for \meta{n} more inserts. Hint: by default +\Package{morefloats} adds 18 inserts (though it can be instructed to +use more), and \Package{manyfoot} seems to be happy with 10 reserved, +but there are `hard' limits that we cannot program around~--- the +discussion of \Qref*{running out of floats}{Q-tmupfl} has more about this. +It is essential that you load \Package{etex} before any other +packages, and reserve any extra inserts immediately: +\begin{quote} +\begin{verbatim} +\documentclass[...]{...} +\usepackage{etex} +\reserveinserts{28} +\end{verbatim} +\end{quote} + +The \eTeX{} extensions don't help with \csx{read} or \csx{write} +objects (and neither will the \Package{etex} package), but the +\Package{morewrites} package can provide the \emph{illusion} of large +numbers of \csx{write} objects. +\begin{ctanrefs} +\item[morewrites.sty]\CTANref{morewrites} +\end{ctanrefs} + +\Question[Q-epsf]{\texttt{epsf} gives up after a bit} + +Some copies of the documentation of \File{epsf.tex} seemed once 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 +\begin{flatversion} + \Qref[question]{hyphenation failures}{Q-nohyph}, +\end{flatversion} +\begin{hyperversion} + ``\Qref[question]{hyphenation failures}{Q-nohyph}'', +\end{hyperversion} +``words'' containing \csx{accent} commands may not be hyphenated. As +a result, any such word is deemed improper in a \csx{hyphenation} +command. + +Hyphenation happens as paragraphs are laid out; by this time, \tex{} +knows what font is used for each glyph; thus it knows the encoding +being used. So the solution to the problem is to use a font that +contains the accented character; doing this this ``hides'' the accent +from the hyphenation mechanisms. + +For \LaTeX{} users, this is quite an easy task; they select an 8-bit +font with the package, as in \cmdinvoke{usepackage}[T1]{fontenc}, and +accented-letter commands such as the \csx{'}\texttt{e} in +\cmdinvoke{hyphenation}{Ji-m\csx{'}e-nez} automatically become the +single accented character by the time the hyphenation gets to look at +it. + + +\Question[Q-optionclash]{Option clash for package} + +So you've innocently added: +\begin{quote} +\cmdinvoke{usepackage}[draft]{foo} +\end{quote} +to your document, and \LaTeX{} responds with +\begin{quote} +\begin{wideversion} +\begin{verbatim} +! LaTeX Error: Option clash for package foo. +\end{verbatim} +\end{wideversion} +\begin{narrowversion} +\begin{verbatim} +! LaTeX Error: Option clash for package foo. +\end{verbatim} +\end{narrowversion} +\end{quote} + +The error is a complaint about loading a package % ! line break +\emph{with options}, more than once. \LaTeX{} complains because it +has no means of examining the options, rather than because it +\emph{knows} there is a problem. (You may load a package any number +of times in a document's preamble, with no options, and \LaTeX{} will +ignore every loading request after the first; 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}. + +The problem is more tricky if your document class loads a package you +want options for. In this case, 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-optclash]{Option clash for package} + +The error message +\begin{quote} +\begin{verbatim} +! LaTeX Error: Option clash for package footmisc +\end{verbatim} +\end{quote} +means what it says~--- your document contains a (potentially) clashing +pair of options; sadly, it is not always obvious how the error has +arisen. + +If you simply write: +\begin{quote} +\begin{verbatim} +\usepackage[a]{foo} +... +\usepackage{foo} +\end{verbatim} +\end{quote} +\latex{} is happy, as it is with: +\begin{quote} +\begin{verbatim} +\usepackage[a]{foo} +... +\usepackage[a]{foo} +\end{verbatim} +\end{quote} +since \latex{} can see there's no conflict (in fact, the second load +does nothing). + +Similarly, +\begin{quote} +\begin{verbatim} +\usepackage[a,b]{foo} +... +\usepackage[a]{foo} +\end{verbatim} +\end{quote} +produces no error and does nothing for the second load. + +However +\begin{quote} +\begin{verbatim} +\usepackage[a]{foo} +... +\usepackage[b]{foo} +\end{verbatim} +\end{quote} +produces the error; even if option `\pkgoption{b}' is an alias for +option `\pkgoption{a}'~--- \latex{} doesn't ``look inside'' the package +to check anything like that. + +The general rule is: the first load of a package defines a set of +options; if a further \csx{usepackage} or \csx{RequirePackage} also +calls for the package, the options on that call may not extend the set +on the first load. + +Fortunately, the error (in that sort of case) is easily curable +once you've examined the preamble of your document. + +Now, suppose package \Package{foo} loads \Package{bar} with option +\pkgoption{b}, and your document says: +\begin{quote} +\begin{verbatim} +\usepackage{foo} +... +\usepackage[a]{bar} +\end{verbatim} +\end{quote} +or +\begin{quote} +\begin{verbatim} +\usepackage[a]{bar} +... +\usepackage{foo} +\end{verbatim} +\end{quote} +the error will be detected, even though you have only explicitly +loaded \Package{bar} once. Debugging such errors is tricky: it may +involve reading the logs (to spot which packages were called), or the +documentation of package \Package{foo}. + +\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{quote} +\begin{wideversion} +\begin{verbatim} +! LaTeX Error: Too many unprocessed floats. + +See the LaTeX manual or LaTeX Companion for explanation. +\end{verbatim} +\end{wideversion} +\begin{narrowversion} +\begin{verbatim} +! LaTeX Error: Too many unprocessed floats. + +See the LaTeX manual or LaTeX Companion +... for explanation. +\end{verbatim} +\end{narrowversion} +\end{quote} +your figures (or tables) are not being 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 +something you have done has prevented \latex{} from typesetting +floats, it will run out of storage space. + +This failure usually occurs in extreme cases of % ! line break +\Qref*{floats moving ``wrongly''}{Q-floats}; +\LaTeX{} has found it can't place a float, and floats of the same type +have piled up behind it. + +How does this happen?~--- \LaTeX{} guarantees that caption numbers are +sequential in the document, but the caption number is allocated when +the figure (or whatever) is created, and can't be changed. Thus, if +floats are placed out of order, their caption numbers would also +appear out of order in the body of the document (and in the list of +figures, or whatever). As a result, enforcement of the guarantee +means that simple failure to place a float means that no subsequent +float can be placed; and hence (eventually) the error. + +Techniques for solving the problem are discussed in the % ! line break +\Qref*{floats question}{Q-floats} already referenced. + +An alternative \emph{may} be to use the \Package{morefloats} package. +The package will allocate more ``float skeletons'' than \latex{} +does by default; each such skeleton may then be used to store a +float. Beware that even with \Package{morefloats}, the number you can +allocate is limited; even with the \Package{etex} package (which makes +available many more registers, etc., than \latex{} does by default; +\etex{} can create lots more registers, but none of those ``beyond +the original \TeX{} default'' may be used in float skeletons). Thus, +\Package{etex} may offer some relief, but it can \emph{not} be +regarded as a panacea + +The error also occurs in a long sequence of float 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} +\item[morefloats.sty]\CTANref{morefloats} +\end{ctanrefs} + +\Question[Q-atvert]{\csx{spacefactor} complaints} + +The errors +\begin{quote} +\begin{narrowversion} +\begin{verbatim} +! You can't use `\spacefactor' in +... vertical mode. +\@->\spacefactor + \@m +\end{verbatim} +\end{narrowversion} +\begin{wideversion} +\begin{verbatim} +! You can't use `\spacefactor' in vertical mode. +\@->\spacefactor + \@m +\end{verbatim} +\end{wideversion} +\end{quote} +or +\begin{quote} +\begin{verbatim} +! You can't use `\spacefactor' in math mode. +\@->\spacefactor + \@m +\end{verbatim} +\end{quote} +or simply +\begin{quote} +\begin{verbatim} +! Improper \spacefactor. +... +\end{verbatim} +\end{quote} +bite the \LaTeX{} programmer who uses an internal command without +taking ``precautions''. An internal-style command such as \csx{@foo} +has been defined or used in a private macro, and it is interpreted as +\csx{@}, followed by the `text' \texttt{foo}. (\csx{@} is used, for +real, to set up end-of-sentence space in some circumstances; it uses +\csx{spacefactor} to do that.) + +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}[checkend] +\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-latex-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}[calc] +\item[\nothtml{\rmfamily}Examples for \nothtml{\upshape}\LaTeX{} Companion]\CTANref{tlc2} +\item[The psnfss bundle]\CTANref{psnfss} +\end{ctanrefs} +\LastEdit{2011-06-01} + +\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 Oberdiek collection + \CTANref{oberdiek}[grffile] +\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 \environment{tabular} +(or \environment{array} or matrix) environment; 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. + +The \Package{amsmath} package adds a further twist; when typesetting +a matrix (the package provides many matrix environments), it has a +fixed maximum number of columns in a matrix~--- exceed that maximum, +and the error will appear. By default, the maximum is set to 10, but +the value is stored in counter \texttt{MaxMatrixCols} and may be +changed (in the same way as any counter): +\begin{quote} +\begin{verbatim} +\setcounter{MaxMatrixCols}{20} +\end{verbatim} +\end{quote} +\begin{ctanrefs} +\item[array.sty]Distributed as part of \CTANref{2etools}[array] +\end{ctanrefs} +\LastEdit{2011-07-06} + +\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}} + +The \emph{preamble} of your document is the stuff before +\cmdinvoke{begin}{document}; you put \csx{usepackage} commands and +your own macro definitions in there. \latex{} doesn't like +\emph{typesetting} anything in the preamble, so if you have: +\begin{itemize} +\item typed the odd grumble, +\item created a box with \csx{newsavebox} and put something in it + using \csx{sbox} (or the like), +\item forgotten to put \cmdinvoke{begin}{document} into the document, + at all, or even +\item gave it the wrong file +\end{itemize} +the error is inevitable and the solution is simple~--- judicious use +of comment markers (`\texttt{\textpercent{}}') at the beginning of a +line, moving things around, providing something that was +missing~\dots{} or switching to the correct file. + +The error may also occur while reading the \extension{aux} file from an +earlier processing run on the document; if so, delete the +\extension{aux} file and start again from scratch. If the error +recurs, it could well be due to a buggy class or package. + +However, it may be that none of the above solves the problem. + +If so, remember that things that appear before \csx{documentclass} are +also problematical: they are inevitably before +\cmdinvoke{begin}{document}! + +Unfortunately, modern editors are capable of putting things there, and +preventing you from seeing them. This can happen when your document +is being `written' in \Qref*{Unicode}{Q-unicode}. The Unicode +standard defines ``Byte Order Marks'' (\acro{BOM}), that reassure a +program (that reads the document) of the way the Unicode codes are +laid out. Sadly ordinary \latex{} or \pdflatex{} choke on +\acro{BOM}s, and consider them typesetting requests. The error +message you see will look like: +\begin{quote} +\begin{verbatim} +! LaTeX Error: Missing \begin{document}. +... +l.1 <?> + <?><?>\documentclass{article} +\end{verbatim} +\end{quote} +(Those \texttt{<?>}s are your operating system's representation of an +unknown character; on the author's system it's a reverse video +`\texttt{?}' sign.) + +You can spot the \acro{BOM} by examining the bytes; for example, the +Unix \ProgName{hexdump} application can help: +\begin{quote} +\begin{verbatim} +$ hexdump -C <file> +00000000 ef bb bf 5c 64 6f 63 75 ... +\end{verbatim} +\end{quote} +The \texttt{5c 64 6f 63 75} are the ``\csx{docu}'' at the start of +(the `real' part of) your document; the three bytes before it form the +\acro{BOM}. + +How to stop your editor from doing this to you depends, of course, on +the editor you use; if you are using \acro{GNU E}macs, you have to +change the encoding from \texttt{utf-8-with-signature} to `plain' +\texttt{utf-8}; instructions for that are found on +% ! line break +\href{http://stackoverflow.com/questions/3859274/}{the ``stack overflow'' site} + +(So far, all instances of this problem that the author has seen have +afflicted \acro{GNU E}macs users.) + +Fortunately \xetex{} and \luatex{} know about \acro{BOM}s and what to +do with them, so \latex{} using them is ``safe''. + +\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} + \newcommand{\hmmax}{0} +\end{verbatim} +\end{quote} +(before loading \Package{bm}), and then steadily reduce the bold +families, starting with +\begin{quote} +\begin{verbatim} + \newcommand{\bmmax}{3} +\end{verbatim} +\end{quote} +(again before loading \Package{bm}), until (with a bit of luck) the +error goes away. +\begin{ctanrefs} +\item[bm.sty]Distributed as part of \CTANref{2etools}[bm] +\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 its 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-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. + +\Question[Q-includeother]{\latex{} won't include from other directories} + +You wanted to \cmdinvoke{include}{../bar/xyz.tex}, but \latex{} says: +\begin{quote} +\begin{wideversion} +\begin{verbatim} +latex: Not writing to ../bar/xyz.aux (openout_any = p). +! I can't write on file `../bar/xyz.aux'. +\end{verbatim} +\end{wideversion} +\begin{narrowversion} +\begin{verbatim} +LaTeX: Not writing to ../bar/xyz.aux + (openout_any = p). +! I can't write on file `../bar/xyz.aux'. +\end{verbatim} +(The first line of that message is wrapped, here.) +\end{narrowversion} +\end{quote} +The error comes from \tex{}'s protection against writing to +directories that aren't descendents of the one where your document +resides. (The restriction protects against problems arising from +\latex{}ing someone else's malicious, or merely broken, document. If +such a document overwrites something you wanted kept, there is obvious +potential for havoc.) + +Document directory structures that can lead to this problem will look +like the fictional \File{mybook}: +\begin{quote} +\begin{verbatim} +./base/mybook.tex +./preface/Preface.tex +./preface/*** +./chapter1/Intro.tex +... +\end{verbatim} +\end{quote} +With such a structure, any document directory (other than the one +where \File{mybook.tex} lives), seems ``up'' the tree from the +base directory. (References to such files will look like +\cmdinvoke{include}{../preface/Preface}: the ``\texttt{..}'' is the +hint.) + +But why did it want to write at all?~--- % ! line break +``\Qref*{what's going in in my \csx{include}}{Q-include}'' explains +how \csx{include} works, among other things by writing an +\extension{aux} file for every \csx{includ}ed file. + +Solutions to the problem tend to be drastic: +\begin{enumerate} +\item Restructure the directories that hold your document so that the + master file is at the root of the tree: + \begin{quote} +\begin{verbatim} +./mybook.tex +./mybook/preface/Preface.tex +./mybook/preface/*** +./mybook/chapter1/Intro.tex +... +\end{verbatim} + \end{quote} + and so on. +\item Did you actually \emph{need} \csx{include}?~--- if not, you can + replace \csx{include} by \csx{input} throughout. (This only works + if you don't need \csx{includeonly}.) +\item You \emph{could} patch your system's \File{texmf.cnf}~--- if you + know what you're doing, the error message should be enough of a + hint; this action is definitely not recommended, and is left to + those who can ``help themselves'' in this respect. +\end{enumerate} +\LastEdit*{2012-02-13} + +\Question[Q-expl3-old]{Support package \Package{expl3} too old} + +Some (rather modern) packages are written using the % ! line break +\Qref*{\latex{}3 programming environment}{Q-LaTeX3}. Since \latex{}3 +is still under development, the author cannot reliably guess what +version of \latex{}3 the user has installed, and whether that version +is adequate for the current package. Thus the package's code often +checks the user's installation, and complains if it's older than the +author's installation at time of testing. The error message is: +\begin{quote} +\begin{verbatim} +! Support package expl3 too old. +\end{verbatim} +\end{quote} +The ``additional help'' tells you the solution: update your \latex{}3 +installation. The relevant things are \Package{l3kernel} (the +programming environment, which contains the \Package{expl3} mentioned +in the error message) and \Package{l3packages} (\latex{}3 constructs +such as command definitions). + +While this sounds a drastic remedy, it is no longer the major +undertaking it once was~--- if you are using a modern \tex{} +distribution that you installed yourself, ask it to update over the +internet; if that choice is not available, install from the +\extension{tds.zip} files available for both packages on \ctan{}. +\begin{ctanrefs} +\item[l3kernel \nothtml{\rmfamily}bundle]\CTANref{l3kernel} +\item[l3packages \nothtml{\rmfamily}bundle]\CTANref{l3packages} +\end{ctanrefs} +\LastEdit*{2013-02-20} |