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, 0 insertions, 2415 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 deleted file mode 100644 index 23dd355da04..00000000000 --- a/Master/texmf-dist/doc/generic/FAQ-en/archive-version/faq-jot-err.tex +++ /dev/null @@ -1,2415 +0,0 @@ -% $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} |