summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/generic/FAQ-en/faq-jot-err.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/generic/FAQ-en/faq-jot-err.tex')
-rw-r--r--Master/texmf-dist/doc/generic/FAQ-en/faq-jot-err.tex182
1 files changed, 156 insertions, 26 deletions
diff --git a/Master/texmf-dist/doc/generic/FAQ-en/faq-jot-err.tex b/Master/texmf-dist/doc/generic/FAQ-en/faq-jot-err.tex
index 9eec4396699..dad92238703 100644
--- a/Master/texmf-dist/doc/generic/FAQ-en/faq-jot-err.tex
+++ b/Master/texmf-dist/doc/generic/FAQ-en/faq-jot-err.tex
@@ -1,4 +1,4 @@
-% $Id: faq-jot-err.tex,v 1.9 2011/07/06 23:09:00 rf10 Exp rf10 $
+% $Id: faq-jot-err.tex,v 1.12 2011/10/29 07:43:12 rf10 Exp rf10 $
\section{The joy of \TeX{} errors}
@@ -460,6 +460,89 @@ accented-letter commands such as the |\'||e| in
|\hyphenation{Ji-m\'||e-nez}| automatically become the single accented
character by the time the hyphenation gets to look at it.
+\Question[Q-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
@@ -1518,31 +1601,78 @@ If you're using the simpler \Package{graphics} package, use the
\Question[Q-missbegdoc]{Missing \csx{begin}\marg{document}}
-Give it a file of plain text, or a \LaTeX{} file that really does have no
-\cmdinvoke{begin}{document} command in it, and \LaTeX{} will produce
-this error, quite correctly. \LaTeX{} \emph{needs}
-\cmdinvoke{begin}{document} so as to know when to execute the commands
-that finish off the document preamble.
-
-Other than that, the error can occur as a result of an error of yours,
-of a corrupt \extension{aux} file, or of a buggy class or package.
-
-The errors you might commit are absent-mindedly typing a document
-command (such as \csx{section}) in the preamble of your document,
-missing the comment marker from the beginning of a line, or giving too
-many arguments to one of the setup commands related to the class or a
-package that you have loaded.
-
-A corrupt \extension{aux} file might be due to any number of things;
-delete the file and to run \LaTeX{} again, twice. If the error
-recurs, it's probably due to a buggy class or package.
-
-If the error occurs while \LaTeX{} is reading a class or package, then
-there's probably a bug in the file. The author of the class or
-package stands the best chance of finding the bug, but with luck you
-(or someone you ask on a mailing list or on \Newsgroup{comp.text.tex})
-will be able to spot the problem and provide a work-around. Always
-report such bugs, even if you have found a work-around.
+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}