troubleshooting.tex

%\chapter{When Things Go Wrong}
\chapter{出现错误的时候}\label{ch:troubleshooting}

Things go wrong, and when they go wrong it can be quite infuriating
trying to work out what has happened. This chapter aims to guide you
through the possible symptoms you might see to try to help you to an
answer.

In this chapter I am not going to deal with the detail of debugging
changes to \biblatex\ styles, but with the sort of thing that goes
rather obviously wrong for an ordinary user running properly written
styles. The manifestation of this problem is nearly always the same:
instead of citations, you have labels in square brackets in the
printed brackets (as in figure \ref{nussbaum1}; you see warnings in
the \LaTeX\ log file telling you
\begin{verbatim}
Citation 'blah' on page x undefined on input line y
\end{verbatim}
and at the end of the log file you are encouraged to |(re)run Biber|.
\index{errors|see{debugging}}
\index{debugging!empty citations}

\section{A Systematic Approach}

\indexstart{debugging!general approach}
The first thing to do in this situation is, paradoxically, to start
with a clean slate.\marginnote{If you use \package{latexmk} you can
  clean all these files away with the command \texttt{latexmk -c}.}
When you are working on a long document, you will end up with all
sorts of files in your working directory that you don't actually need,
and sometimes they can make debugging harder. So start cleanly: delete
all `automatically created' files: in particular all |.aux|, |.bcf|,
|.blg| and |.bbl| files.

\subsection{Run \LaTeX}

Now, from a command line, run |pdflatex| \angled{filename} (or
whichever \LaTeX\ you use. Don't worry much about the warnings: this
is a first clean run, and you \emph{expect} undefined citations; but
if \LaTeX\ is encountering errors, you obviously need to sort them
out: for instance, if you have misspelled |biblatex| or attempted to
load a non-existent bibliography style, you can't expect to produce
citations. Once the document compiles (with, as expected, warnings
about undefined references), you can move on to the next stage.

\subsection{Run \package{Biber}}

The next task is to run \package{Biber}.  This time, you should
examine your output, either on the console or in the log file (which
will have the extension |.blg|). If all has gone well you will see
something like figure \ref{biber:run}.
\begin{figure}
\begin{Verbatim}[frame=single,fontsize=\small]
INFO - This is Biber 2.7
INFO - Logfile is 'punctcite13.blg'
INFO - Reading 'punctcite13.bcf'
INFO - Found 1 citekeys in bib section 0
INFO - Processing section 0
INFO - Looking for bibtex format file 'biblatex-examples.bib'
       for section 0
INFO - Decoding LaTeX character macros into UTF-8
INFO - Found BibTeX data source '/biblatex-examples.bib'
INFO - Overriding locale 'en-US' defaults 'variable = shifted'
        with 'variable = non-ignorable'
INFO - Overriding locale 'en-US' defaults 'normalization = NFD'
       with 'normalization = prenormalized'
INFO - Sorting list 'nty/global/' of type 'entry' with scheme 'nty'
       and locale 'en-US'
INFO - No sort tailoring available for locale 'en-US'
INFO - Writing 'punctcite13.bbl' with encoding 'ascii'
INFO - Output to punctcite13.bbl
\end{Verbatim}
\caption{Log of a successful \package{biber} run\label{biber:run}}
\end{figure}

If \package{Biber} has run successfully, you can go on to the next
step. If you see any lines in the log which begin |ERROR| or |WARN|
then there was some sort of problem, and you will need to do more
digging.

\newthought{Once \package{Biber} has actually run}, even with
warnings, you will find that the log provides a useful diagnostic
tool. The most common errors are set out in table \ref{biber:errors},
together with their meanings and the action you should take. But this
is not a comprehensive list. Occasionally, you may get other errors:
in the worst case, the progam may simply fail to run fully. This is
very rare indeed. When it happens it is usually because of some occult
problem in your |.bib| file.

\begin{table*}
\begin{tabular}{p{5cm}p{5cm}p{5cm}}
\toprule
\ttfamily WARN - No data sources defined!                                                                                               & Your source file does not contain any \cs{addbibresource} commands.                                                                                                              & Check your source file, and make sure it includes \cs{addbibresource} commands for every data source you need.                                                                                                                                                                                                                                            \\
\midrule\ttfamily ERROR - Cannot find \angled{database file}!                                                                           & Biber was not able to find the |.bib| file you have referred to.                                                                                                                 & Make sure you have spelled the name correctly. Make sure the file is somewhere that \TeX\ can find it, either in a place in your \TeX-\textsc{mf} tree where it will be found, or in the same directory as the source file. (If you don't understand this, just play safe: put it with your source file!)                                                 \\
\midrule\ttfamily WARN - Entry \angled{label} does not parse correctly.
ERROR - BibTeX subsystem: \angled{filename} ... syntax error: found "title", expected end of entry ("\}" or ")") (skipping to next "@") & You have not written a particular entry correctly: usually (as in this case) by forgetting a comma between fields, sometimes an unescaped comment character (\%) is the culprit. & Find the entry that did not parse, and correct it.                                                                                                                                                                                                                                                                                                        \\
\midrule\ttfamily WARN - BibTeX subsystem: \angled{filename} warning: 1 characters of junk seen at toplevel                             & There is something \emph{outside} and entry, other than the beginning of a new entry. The usual reason for this is a stray comma between entries.                                & Check your |.bib| file around the place where the `junk' appeared. Note that if this happens the rest of the file will fail to parse, and you may well get missing citations too.                                                                                                                                                                         \\
\midrule\ttfamily WARN - I didn't find a database entry for \angled{label}                                                              & That citation label is not included in your \texttt{.bib} file (or it is included after an error in that file from which recovery was not possible)                              & Often this is a typo (in either the source file or the database): check there is a source with that label, spelled exactly identically. The other common source of (many!) such warnings is that if there is a spoiled entry in the \texttt{.bib} file (leading to the message about `junk' having been seen) all subsequent entries will be ignored too. \\
\bottomrule
\end{tabular}
\vspace{10pt}
\caption{Biber errors, and what they mean\label{biber:errors}}
\end{table*}

\index{debugging!errors in bib file@errors in \texttt{.bib} file}
To diagnose such an error, proceed as follows:
\begin{itemize}
\item Rename your existing |.bib| file.
\item Gradually copy your |.bib| file entries back into an empty file
  (with the old name). Either copy a few entries at a time, or use the
  technique of copying half the entries, then either removing half (if
  the first chunk failed) or progressively adding more.
\item Each time you do this, rerun \package{biber} (you shouldn't need
  to re-run \LaTeX). You should expect, and ignore, warnings about
  missing citations; you are simply looking to get a run that does not
  abort.
\item In this way you should be able to identify the problem
  entries. Remove these.
\item Retype the problematic entries by hand, checking that they are
  correct. Where an error sufficiently grave to prevent
  \package{biber} from running occurs, the problem seems usually to be
  with some unacceptable encoding in the file, and manually
  re-entering the entry will usually sort it out.
\end{itemize}

Once you have corrected any errors, re-run \package{Biber}. If you had
to correct an error in your \emph{source file} (e.g. to add or change
an \cs{addbibresource} command), you will need to re-run (pdf)-\LaTeX,
and then \package{Biber}. If you only had to change entries in the
|.bib| file, you should be OK with just running \package{Biber}.

\subsection{Finally, run \LaTeX\ again}

Once you manage to run \package{Biber} without errors or warnings,
re-run \LaTeX. This time you should get a complete compilation,
without any warnings.

There is one category of error that can sometimes occur at this
point. Just occasionally you will find that when \LaTeX\ is run you
get complaints about problems with some unicode character. The problem
occurs because \package{biber} works internally in one flavour of
unicode normalisation, but \LaTeX\ does not, and even (in fact,
especially) when unicode is used (via |\usepackage[utf8]{inputenc}|)
there can be occasional incompatibilities. If you see this sort of
trouble, try running \package{biber} with the option
|--output_safechars|.
\indexstop{debugging!general approach}

\section{A less systematic approach}

Sometimes a less systematic approach is appropriate. If a document and
bibliography have all been compiling correctly, but suddenly you start
to see problems, particularly with one or two entries, go back and
check those particular entries. If those look correct (the label is
correctly spelled in the |.tex| source, the entry seems correct in the
|.bib| file) it's worth carrying out a manual run of \package{Biber}
just to check it is working correctly.

\section{Problems with output}

\indexstart{debugging!output problems}
Problems with output have three possible sources. (a) It may be that
your bibliography style is, in some way, not to your taste. This is
not really a `bug' as such: it may well be that the style is doing
exactly what its author intended it to. There are, of course, various
ways in which you may be able to tweak a style to your liking, some of
which are discussed elsewhere in this document. But the problem is not
one of debugging. (b) It may be that there actually \emph{is} a bug in
the bibliography style you have used. These things are complex, and
bugs happen. If you are nervous about them, try to stick to
well-established and maintained styles. Other possible things to do
are to get help online\footnote{For instance at
  \url{tex.stackexchange.com}} or to contact the style's maintainer by
email. (c) It may be a problem with your |.bib| file.

It's only common sense to check the last point first. Among the common
errors in a file which will `work' are the following:
\begin{itemize}
 \item Incorrect lists of names. It's terribly easy to write
 \begin{pseudoverb}
John Smith, A. U. Thor, Joe Bloggs
 \end{pseudoverb}
 when you mean
 \begin{pseudoverb}
John Smith and A. U. Thor and Joe Bloggs
\end{pseudoverb}
\item Incorrect names, particularly forgetting to put a full stop
  after initials (especially since it often makes no difference):
  |Smith, J| instead of |Smith, J.|
\item Forgetting to put extra braces round institutional authors, so
  that |Press Complaints Commission| becomes `P. C. Commission'.
 \item Forgetting to put braces around a word whose capitalization should not be changed, so that |German| becomes |german|
 \item Inadvertently muddling similar fields, such as |pages| and
   |pagination|, |journaltitle| and |series|, |volume| and |part|.
\end{itemize}
\indexstop{debugging!output problems}

\section{Further help}
The main source of help on \biblatex\ is its manual, which can be
found either online or, on a properly installed \TeX\ system, by
typing |texdoc biblatex| at the command line. Individual styles also
have their own documentation, which is sometimes extensive. That too
can be found using the |texdoc| command, adding the name of the
package.

When the going gets tough, it's sometimes helpful to have an
experienced person look at the problem. If you don't have such a guru
on tap, you can always ask a question at
\url{http://tex.stackexchange.com}, where the |biblatex| tag appears
frequently (and the package's maintainers regularly check
questions). If you decide to do that, please consider the following:
\begin{itemize}
\item Make a good faith effort to solve the problem yourself first,
  including by making sensible searches for duplicate questions.
\item Tag your question |biblatex|.
\item Post code which illustrates the problem.
\item But \emph{don't} just post or provide a link to a huge
  file. Make a new file, using a standard class (such as |article|)
  which shows it. Similarly, remove all packages that seem to be
  irrelevant to the problem. Preparing such a document may well help
  you to isolate it. For instance, if you can't reproduce the problem
  unless you add some odd package or antiquated class file, the
  solution may be obvious.
\item Include a minimal bibliography file in the example
  itself. There's an easy way to do this:
  \begin{itemize}
  \item Add |\usepackage{filecontents}| to your preamble.
  \item Place the necessary bibliography entries, just as in your
    |.bib| file, within an environment that begins
    |\begin{\filecontents}{\jobname.bib}| and
      |\end{filecontents}|. This will cause \LaTeX\ to create such a
    file on its first run.
  \item Use |\addbibresource{\jobname.bib}| to load that file.
  \end{itemize}
\item Be absolutely specific about what the problem is, and what a
  solution would look like. Add an image which shows what is wrong and
  what you need.
\item Don't take it amiss if someone on the site manages to see that
  your question is a duplicate, and points that out. This is not an
  agressive gesture. It's sometimes hard for anyone other than an
  expert even to \emph{realise} that what look like two different
  problems are really just different manifestations of the same
  difficulty.
\end{itemize}

%%% Local Variables:
%%% coding: utf-8
%%% mode: LaTeX
%%% TeX-master: "biblatex-tutorial"
%%% End: