\title{Editorial}
\begin{article}
\section{So farewell then}
This will be, unless lightning strikes twice, my last edition of \BV.
I took over the job as an emergency measure from an over-loaded 
Sue Brooks during the summer of 1993, shortly before the shattering
event of the TUG conference at Aston University (I cannot be the only
member of the committee for that meeting who has never fully
recovered!). It turned out to be moderately easy, I thought, to cobble
up an issue of fun material, but the crucial change in \BV\ was due to
Rosemary Bailey, who insisted at a \ukt\ committee meeting that we
needed a bi-monthly, \emph{regular}, newsletter, come hell or high
water. She is one of the true parents of \BV\ as you see it; another
is the redoubtable Malcolm Clark, who effectively diverted the energy
he had devoted to the great \emph{\TeX line} into \BV; the third is
Robin Fairbairns, who has actually consisently turned files into
paper. My thanks to them, and everyone else who has beavered away over
the last two years on \BV, and my best wishes to whoever gets the hot
seat. You will not find this out until 1996, as the final issue of
1995 will be a revised \emph{Frequently Asked Questions}.

At the 1995 \TeX\ Users Group meeting, all delegates were given
reprints of \BV\ 4.6; towards the end of the meeting, Don Knuth
himself came to Robin Fairbairns and myself to ask for a subscription
to the newsletter. That was when it all seemed worthwhile\ldots

\section{Overload}
Any editor of a publication about \TeX\ meets the problems of
conflicting macros more than most people; curiously enough, no issue
of \BV\ has yet proved impossible to run in one go. But last time it
came close; for Herman Haverkort's packages alone, it took me several hours
to work out which packages to omit (like \LaTeX\ color), and where to
cheat. At the last moment, Rowley's article needed \texttt{amsmath},
which then fought with Bailey's work\ldots The fact that \LaTeXe\ did
not trivially permit me to load \texttt{amsmath} for the duration of
one paper only (it used to be easy in the days of \LaTeX209) is a
cause of irritation. Recalling observations in recent \BV\,s
about the direction \LaTeX{} is taking, I take the opportunity to
commend to \ukt\ members a paper by Matt Swift on `Modularity in \LaTeX'
which will appear in TUGboat 16.3 --- whatever you think of his
suggestions, it is way past time to stop relying on just hope and
goodwill as methods of preventing macro clashes.

\section{Where are the Gleanings?}
Many readers of \BV\ have turned first in the last couple of years to
Malcolm Clark's column for some witty, salacious or even sensible,
remarks. One of the threads of those gleanings has been a consistent
prodding of the international \TeX\ Users Group to get its act
together with the journal \emph{TUGboat}, which has fallen badly
behind schedule. The good news is that TUG has put in place a team to
take production work off the shoulders of the over-worked Barbara
Beeton, and let her concentrate on real editing; it is also extending
the scheme of guest editors for whole issues, which is where the
\emph{Gleanings} come in. Poacher Malcolm  has turned gamekeeper / editor, and
is working to get out a special issue of \emph{TUGboat} on SGML,
electronic documents and so forth. Hence his lack of leisure to write
us some gleanings this month --- do not worry, I am sure they will
return. \BV\ readers who are members of TUG can rest assured they
their  journal  will be firmly back on schedule by Christmas.

\section{Whatever is wrong with my \LaTeX\ file?}
For the last twelve months I have been promising myself to write an
article about debugging \LaTeX\ files; this arose from some in-house
training sessions I conducted at Elsevier about dealing with
problematic authors' files.  At last, here are my thoughts and recipes
for dealing with stubborn files that you inherit from other people.

\subsection{Golden rules}
If you do not take the following precautions, you might as well give
up now:
  \begin{enumerate}
  \item \emph{Look} at \TeX\ errors; those messages flashing across
the screen are not some kind of screen saver.
  \item Read the  log file too; did you realize it has extra
information? Specifically, it will list characters missing from a font.
  \item Lay out the source sensibly; how can you find errors if your
input is one long line of mixed macros and text?
  \item Use syntax checkers; there are many of these: I use
\emph{lacheck}, from the authors of Emacs AUC\TeX, and the one built
into Eddi4\TeX, but there are others. For \LaTeX\ especially, it is a
god send to have the missing \verb|\end{enumerate}| spotted for you.
\item \LaTeX\ has several packages to help show you what it is working
with: \texttt{showkeys} shows you the labels you define;
\texttt{syntonly} will run a \LaTeX\ file fast, ignoring fancy
typesetting;
 the \texttt{listfiles} command lists the macro files that were used at
the end (handy for checking versions), and the \texttt{draft} option
will show overfull boxes and all manner of other things for some
packages.
\item If you are a confident macro programmer, be aware of the many
\TeX\ primitives that can help you: set
\verb|\errorcontextlines| to give more context for help messages, 
use \verb|\message| to put in diagnostic messages, 
try \verb|\meaning| to find out what a macro really \emph{is} defined
as, rather that what you assumed it was. Don't despair at the amount
of verbiage \verb|\tracingall| gives you --- there is gold in them
thar log files.
\item Remember primitive programmer's debugging
techniques; if all else fails
in your quest to see why \LaTeX\ dies with that weird error in your 10000
line file, move \verb|\end{document}| gradually back up the file from the end
until it \emph{does} work, and then stare at the 10 lines which you
know provoke the error, with a wet towel around your head. It is
faster than reading all 10000 lines over and over again
hopelessly\ldots
\item \emph{Do not} mail the \LaTeX\ development team, or other
package authors, every time \TeX\
gives you an error prompt; you'll irritate hard-pressed volunteers
working in their spare time. If you wait until you have a \emph{good},
well-documented, repeatable, error condition that your friends get
too, \emph{then} you can report it, and likely get a friendly reply
and a fix.
\end{enumerate}

\subsection{Examples}
Firstly, did you think I was joking about laying out your text in a
readable  fashion? Can you easily find the error in this?
\begin{nVerbatim} 
\begin
{document}\baselineskip=12pt\newcommand
{\F}{Fig.~}\newcommand {\w}{\omega
}\newcommand {\k}{\xi }\newcommand
{\p}{\phi
}\maketitle\thispagestyle{empty}\centerline
{\bf \underline{Abstract}}\vskip
6ptA probabilisticoptimal design
methodology for complex structures
using the existing probabilistic
optimization techniques.  \vskip
12pt\centerline{\bf
\underline{Nomenclature}\vskip 6pt
\begin{tabbing}\( A
\)\hspace{0.45in} \=:
Transformation matrix\\\( a_i \)
\>: Gradient of performance
function with respect \\$\hskip
1.25in$ to $i^{th}$ random variable
\\\( b \) \>: Design variable
vector\\\( {\it CDF} \) \>:
Cumulative distribution
function\\\( {\it COV} \) \>:
Coefficient of variation \\\( C_x
\) \>: Covariance 
\end{nVerbatim}
Common sense (and the \LaTeX\ manual) will also suggest that replacing
code like:
\begin{Verbatim}
\vskip 3pt\noindent{\bf \underline{Safety
Index Interpolation}}\vskip 1pt
\end{Verbatim}
with
\begin{Verbatim}
\section{Safety Index Interpolation}
\end{Verbatim}
will considerably aid readability and maintenance.

Next, an example where the puzzling output is all explained in the
log file:
\begin{nVerbatim}
{This is not so bad, 
\bfseries\ttfamily hello?}
{This is not so bad, \scshape 
Hello \bfseries Goodbye?}
{\it\bf\Large byebye}
\end{document}
\end{nVerbatim}
Why do we not see bold typewriter or bold small caps? Because the
fonts do not exist, and \LaTeX\ tells us it has had to make
substitutions as best it can:
\begin{Verbatim}
LaTeX Font Warning: Font shape `OT1/cmtt/bx/n' 
 in size <10> not available
(Font)              Font shape `OT1/cmtt/m/n' 
 tried instead on input line 4.

LaTeX Font Warning: Font shape `OT1/cmr/bx/sc ' 
 undefined
(Font)              using `OT1/cmr/bx/n' 
 instead on input line 6.

\end{Verbatim}
What more could you ask? 

If hyphenation is your bugbear, do you
understand the difference between the following large heavy animals?
\begin{nVerbatim}
rhinoceroses
\showhyphens{rhinoceroses}
\hyphenation{rh-ino-cer-os-es}
rhinoceroses
\begin{sloppypar}
rhinoceroses
\end{sloppypar}
rh\"inoceroses
\fontencoding{T1}\selectfont
rh\"inoceroses
\par\hskip\z@skip
rhinoceroses
\end{nVerbatim}
Remember that:
\begin{enumerate}
\item \TeX\ may need help hyphenating the word; give it clues;
\item If you want justification at all costs, set the right parameters
--- \texttt{sloppypar} does a sledgehammer and nut job, but it works;
\item If you put accents in words, hyphenation dies \ldots
\item \ldots unless you use T1 encoding, which cleverly transforms
\verb|\"i| to an 8-bit character internally so that \TeX\ proceeds
happily (ah, but you need 8-bit hyphenation patterns to do a proper
job);
\item The first word of a paragraph will not hyphenate. Insert
something harmless to bypass this law.
\end{enumerate}
I expect you have all done this at some time:
\begin{nVerbatim}
\begin{figure}
\label{fig1}
\caption{This is a caption}
\end{figure}
\end{nVerbatim}
and wondered why the labels are wrong? It is \emph{not} the figure
environment which sets labels, but the \verb|\caption| command; what
the example above will do is set the label `fig1' to the value of the
most recent section, equation, list item or whatever.

Do the new \LaTeX2e\ packages puzzle you? Why doesn't this work:
\begin{nVerbatim}
\usepackage{graphicx}
\begin{document}
This is \rotatebox{75}{hello sunshine} at an angle
\end{document}
\end{nVerbatim}
Simply because rotation, colour, scaling, and graphics insertion are
all device dependent, and \LaTeX\ needs to know what dvi driver you
have. You probably meant something like:
\begin{Verbatim}
\usepackage[dvips]{graphicx}
\end{Verbatim}
Now let us look at a bad file which is quite easy to understand:
\begin{nVerbatim}
\documentclass{article}
something
\begin{document}
hello \( a=
\end{documen
\end{nVerbatim}
\LaTeX\ says of this, quite understandably:
\begin{Verbatim}
! Missing $ inserted.
<inserted text>
                $
l.4

?
)
Runaway argument?
{documen
! File ended while scanning use of \end.
<inserted text>
                \par
<*> bad

?
\end{Verbatim}
\noindent though the `missing \$' is a bit confusing when what it
meant was `missing \verb|\)|'. \emph{lacheck} does a much better job:
\begin{Verbatim}
"bad.tex", line 5: <- unmatched "\end{documen}"
"bad.tex", line 3: -> unmatched "math begin \("
"bad.tex", line 5: <- unmatched "end of file bad.tex"
"bad.tex", line 2: -> unmatched "\begin{document}"
\end{Verbatim}
However, it sees nothing wrong with
\begin{nVerbatim}
\documentclass{article}
\begin{document}
Funnies: \dag, \AA and \"
\section{Introduction}
\end{document}
\end{nVerbatim}
about which \LaTeX\ says:
\begin{Verbatim}

! Argument of \@xdblarg has an extra }.
<inserted text> 
                \par 
<to be read again> 
                   }
l.5 \section
            {Introduction}
? 
\end{Verbatim}
Make of that one what you will! How long did it take you to spot the
error? Can someone suggest a technique other than towel-round-the-head
staring to catch it?

Lastly, did your \TeX\ just say `bufsize exceeded'?
Maybe the file it was reading came from a Mac? or a word-processor
which stored each paragraph as a single long line? If it is a graphic
file, it may have come from a Mac package, and \TeX\ is throwing up
while searching for a \texttt{\%\%BoundingBox} line. You should realize
that DOS, Unix and Mac treat line-endings differently! If you don't
have a dedicated utility to fix this, try using \emph{zip} to package
up the files, and then \emph{unzip} them, using the flag to convert
text files to the local native format.

\end{article}
\endinput