summaryrefslogtreecommitdiff
path: root/usergrps/uktug/baskervi/5_5/editor.tex
diff options
context:
space:
mode:
Diffstat (limited to 'usergrps/uktug/baskervi/5_5/editor.tex')
-rw-r--r--usergrps/uktug/baskervi/5_5/editor.tex307
1 files changed, 307 insertions, 0 deletions
diff --git a/usergrps/uktug/baskervi/5_5/editor.tex b/usergrps/uktug/baskervi/5_5/editor.tex
new file mode 100644
index 0000000000..58635ecf5b
--- /dev/null
+++ b/usergrps/uktug/baskervi/5_5/editor.tex
@@ -0,0 +1,307 @@
+\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