summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/generic/FAQ-en/archive-version/faq-jot-err.tex
diff options
context:
space:
mode:
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.tex2415
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}