diff options
Diffstat (limited to 'usergrps/uktug/baskervi/5_5/editor.tex')
-rw-r--r-- | usergrps/uktug/baskervi/5_5/editor.tex | 307 |
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 |