\chapter{First steps} \section{A brief history} \LaTeX\ can be thought of as the fusion of two developments in computing software. One of these developments was \TeX; the other was \Scribe\index{scribe@\protect{\Scribe}}. Both are embedded in the academic world. Both came to fruition in the latter part of the 70's, and as such, preceded the introduction of personal computers. They also parallel the rise of large scale database systems, and the demise of traditional hand-set type. \subsection{\TeX} \TeX\ itself was developed as a typesetting tool by Donald Knuth\index{Knuth} of Stanford University~\cite{DEK84}. Knuth wrote the first version of \TeX\index{tex@\protect{\TeX}} in the late 1970s \cite{DEK79}, primarily as a way of controlling the printed quality of his multi-volume work \textsl{The Art of Computer Programming}~\cite{DEK68}. To some extent, and more particularly with the early versions, \TeX\ tended to place some emphasis on the arrangement of the marks on the paper. After all, Knuth finishes~\cite{DEK84} with the exhortation: `\textsc{Go Forth} {and create masterpieces of the publishing art!}'. He was clearly thinking in terms of marks on paper. Because of this attention to this relatively low level of detail, \TeX\ is sometimes described as a \emph{procedural} or \emph{typographic markup}\index{markup} system. \subsection{\Scribe} \Scribe\index{scribe@\protect{\Scribe}} was written by Brian Reid at Carnegie-Mellon~\cite{BR80}, and described in his thesis in 1980. In essence, \Scribe\ ignored the content of the document, concentrating on the relationship of the parts: in a sense it imposed, or revealed, the implicit inter-relationships present. We may be prepared to acknowledge that a document is composed of (say) \begin{itemize} \item front matter \item main text \item annexed (or back) matter \end{itemize} and within each of these major divisions, we can identify subdivisions. The front matter might comprise \begin{itemize} \item title page \item author's dedication \item table of contents \item list of figures \item foreword \item preface \item acknowledgements \end{itemize} and so on. Some of these elements may be optional. This presents structure as very hierarchical, but it is possible to construct arrangements which are not so fiercely arranged, and share features with other, less formal, types of organisation. One of the major points to make is that \Scribe\ was a system of \emph{descriptive} or \emph{logical markup}\index{markup}: it described the structure of the document. It made no comment about the arrangement of the words on the page. In fact, there need be no `page', in the sense of `paper' page. Changing the characteristics of the `carrier medium' changed nothing about the document structure. While it is possible to disagree with extreme versions of this viewpoint \cite{MC96}, it did offer a powerful and attractive way to separate documents from the worries of formatting. \subsection{\LaTeX} Leslie Lamport~\cite{LL85} took the ideas of \Scribe\ and the typesetting capabilities of \TeX\ and fused them into \LaTeX, a piece of software where an author could include an account of the structure\index{structure} together with the content -- the words. Lamport sought to devise a system where the author need know nothing about the details of typesetting -- justification, choice of typeface, page breaking, ligatures, and so on. Merely by saying that the document was a `book', or a `report', the text would be formatted appropriately. In contemporary jargon, \TeX\ is described as the \emph{formatting} or \emph{typesetting engine} whose presence need never be revealed. The author concentrates on the content, merely guiding the structure gently by noting features like sections, subsections, figures, etc. To this Lamport added or adapted tools to sweep up tables of contents, lists of figures, cross referencing, bibliographic control and indexing. Perhaps these \emph{value added} tools\index{tools} are the features which still give \LaTeX\ the edge over almost any other software of this type. That and the fact that it is available, if not freely, certainly very cheaply. A great deal of the work on \TeX\ and \LaTeX\ has been done through the public domain. This does not mean it was done for free: a great deal of money was spent, one way or another, in perfecting these tools. Fortunately for the rest of us, a lot of it was `public' (i.e.~taxpayers') money, rather than `commercial' money. Even the commercial versions of \TeX\ and \LaTeX\ are very cheap when compared to `comparable' commercial alternatives. \LaTeX\ absorbed all \TeX's mathematical capability. Since \LaTeX\ is written in \TeX\ (which itself has some pretensions to being a programming language), anything that is possible in \TeX\ can also be done in \LaTeX, so we have lost no functionality. This is really only theoretically true, since, as we may see, \TeX\ itself has some memory limitations: once the \LaTeX\ functionality is loaded, there is limited space left for other things. But this is an architectural problem rather than a conceptual one. One of Lamport's advantages was that he was able to work with Knuth, as Knuth was developing the `final' version of \TeX. Certain requirements which came to light with the development of the early versions of \LaTeX\ were incorporated into \TeX82, the version of \TeX\ which we all used until Knuth \cite{DEK89} made some relatively small changes in 1989; this latter change was a relatively straightforward and painless upgrade which may even have gone unnoticed by some. Lamport is quoted somewhere as saying that he could not have achieved what he had done without the active cooperation of Knuth. This is not to minimise Lamport's achievement, since \LaTeX\ is a wholly remarkable piece of software. It has defects, but to a large extent these turn out not to be too limiting. Some of its problems are really problems inherent in \TeX. But more of that later (perhaps). \subsection{\LaTeXe}\index{latex!latex2e@\protect{\LaTeXe}} Some other changes have to be documented. For a long period, \LaTeX\ was also known as \LaTeX\,2.09\index{latex!latex2.09@\protect{\LaTeX}\,2.09}. This actually covered an incremental refinement where bug fixes were gradually incorporated without changing the version number and was leading to uncertainty of what was the `current' version of \LaTeX, and some divergence of what it actually constituted. This was not altogether satisfactory. By 1990 there was the beginning of a proposal to change \LaTeX\ substantially \cite{FM90}, for a variety of sound reasons. Ultimately this gelled into a proposal for a new version to be called \LaTeX3\index{latex!latex3@\protect{\LaTeX}\,3} \cite{FMCR92}. In the meantime, to hold us until the new version is ready, a consolidation, \LaTeXe\ was publicly released in 1994. This is the version of \LaTeX\ which constitutes the core of this discussion. From time to time it will be necessary to recap some of the history which brought us to \LaTeXe, but by and large the discussion is directed at \LaTeXe. When some peculiarity of \LaTeXe\ is mentioned it will be referred to as such, but most of the time, \LaTeX\ and \LaTeXe\ will mean the same thing. When will \LaTeX3 be released? Or rather, will your investment in learning \LaTeX\ be lost when \LaTeX3 appears? I hope not, not least since my investment will be lost too. It will take some time before \LaTeX3 appears, and even when it does, the concepts will likely stay much the same, although there may be detail changes \cite{DCCRFM98}. Furthermore, it is likely that there may be some sort of compatibility mode, where existing (or \emph{legacy}) documents written in \LaTeX\ will be capable of being processed with \LaTeX3. Nothing should be wasted. The investment is just too vast to risk. \subsection{A proviso} One possible disadvantage of the \LaTeX\slash\Scribe\ approach is that it requires that you have a notion of just what it is you are trying to do: some people write electronic or digital documents in a very haphazard, piecemeal fashion, jumping around the document, and basically losing track of things. If this is the way you work, and you resent the rigour of structure, seeing it as a straight-jacket rather than scaffolding, you may be unhappy with \LaTeX. A little bit of discipline may help to refine your ideas, and, in the longer term, achieve more. It is certainly true that you will not learn all there is to know about \LaTeX\ from this brief account. On the other hand, with its aid, you may learn enough to be able to produce (apparently) complex documents, and without too much trouble. Systems which are learned quickly sometimes lack stamina. To some extent \LaTeX\ can be approached in an `intuitive' way, but no-one is likely to try to claim that it is especially `user-friendly', at least, not until you are properly introduced. \section{A note on pronunciation} Some people get very worked up about the pronunciation of \TeX\ and \LaTeX. Knuth says of `\TeX'\index{tex@\protect{\TeX}} \begin{quote} ``Insiders pronounce the $\chi$ of \TeX\ as the Greek chi, not as a `x', so that \TeX\ rhymes with the word blecchhh. It's the `ch' sound in Scottish words like {\em loch\/} or German words like {\em ach}; it's a Spanish `j' and a Russian `kh'.'' \end{quote} Unfortunately, few of the English-speaking world are equipped to pronounce \emph{loch}, and the German-speaking world has (at least) two pronunciations of \emph{ach} -- the less obvious, southern German form, is like \emph{ash} or perhaps \emph{asch}. In the end, the majority of English-speakers seem to end up with \emph{tecks} or \emph{teck}. Lamport sagely notes: \begin{quote} ``\dots pronunciation is best determined by usage, not fiat. \TeX\ is usually pronounced \emph{teck}, making \emph{lah}-teck, lah-\emph{teck}, and \emph{lay}-teck the logical choices; but language is not always logical, so \emph{lay}-tecks is also possible.'' \end{quote} About the only possibility Lamport does not cover is \emph{L-A-teck}, so perhaps we can conclude that that is not a recommended pronunciation. Of course, Knuth's description, as given here, begs the question a little, since it does not say where the Greek chi comes from. Knuth's original notion, in naming the software \TeX, was to use the roman form of $\tau\epsilon\chi$, which is the beginning of the Greek word transliterated as \emph{tekhn\=e}, which we use in words like \emph{technology}. To the Greeks this encompassed art \emph{and} technology. A better rendition into contemporary english would probably be something like \emph{craftsmanship}. An exposition of \emph{tekhn\=e} might be the Parthenon in Athens, or even any piece of work which was the responsibility of Isambard Kingdom Brunel. But, however we pronounce `\TeX' and `\LaTeX', we will always recognize the logos, which are so difficult to produce in most every other system. If you do have to write \TeX\ or \LaTeX\ in a system where you cannot drop the `E' or raise the `A', write them like `TeX' and `LaTeX'. \begin{question} What would you say were the structural elements of a memo? or a letter? What are the bits which are always present? \end{question} \begin{question} This question cannot be answered immediately, but it may be revealing if you keep it in your mind as you read through the book. Ponder on the extent to which developments in software are related to available hardware. Try to imagine the sort of hardware and operating systems which were available as Knuth was developing \TeX. Contrast that with the hardware and operating systems which have led to the development of \textsl{wysiwyg} (what you see is what you get) software. What might Knuth and Lamport have done if they were developing \TeX\slash\LaTeX\ today? \end{question} \begin{question} Take a word processing or document formatting system with which you are familiar -- \texttt{nroff}, Runoff, \textsl{Pagemaker}, WordPerfect, Word, FrameMaker, Interleaf, Quark Xpress, lout, \textsc{html}, paper and pencil, typewriter, etc., and note down what seem to be their \emph{descriptive} and \emph{procedural} elements. Which bits are concerned only with positioning of characters on the page, and which bits describe items independently of their form? There may even be a third category where the positioning and the `content' are combined. \end{question} \section{Let's try it} Since \LaTeX\ was developed for documentation, it is a good idea to start with a fairly straightforward document and see what it is we have to do in order to translate it onto the page. We will assume that `marks on paper' are the goal. The `paperless office' still seems as far away as ever, despite efforts from most computer manufacturers, Xerox {\sc parc}, and the damage being done to the forests of the world. We will begin with the output: the end product of the document preparation process. This end product, Figure~\ref{ishmael}, is not spectacular, but it does have some interesting features, most of which we probably take for granted. \begin{figure*} \centerline{\fbox{\includegraphics{ishmael}}} \caption{}\label{ishmael} \end{figure*} If we examine the input file, we will see that the text is enclosed between the instructions in the following manner:\index{documentclass@\texttt{documentclass}} \begin{small} \begin{verbatim} \documentclass{book} \begin{document} \chapter{Example formatted file} I stuffed a shirt or two into my old carpet-bag, tucked it under my arm, and started for Cape Horn and the Pacific. Quitting the good city of old Manhatto, I duly arrived in New Bedford. It was on a Saturday night in December. Much was I disappointed upon learning that the little packet for Nantucket had already sailed, and that no way of reaching that place would offer, till the following Monday. As most young candidates for the pains and penalties of whaling stop at this same New Bedford, thence to embark on their voyage, it may as well be related that I, for one, had no idea of so doing. For my mind was made up to sail in no other than a Nantucket craft, because there was a fine boisterous something about everything connected with that famous old island, which amazingly pleased me. Besides though New Bedford has of late been gradually monopolizing the business of whaling, and though in this matter poor old Nantucket is now much behind her, yet Nantucket was her great original --- the Tyre of this Carthage; --- the place where the first dead American whale was stranded. Where else but from Nantucket did those aboriginal whalemen, the Red-Men, first sally out in canoes to give chase to the Leviathan? And where but from Nantucket, too, did that first adventurous little sloop put forth, partly laden with imported cobblestones --- so goes the story --- to throw at the whales, in order to discover when they were nigh enough to risk a harpoon from the bowsprit? Now having a night, a day, and still another night following before me in New Bedford, ere I could embark for my destined port, it became a matter of concernment where I was to eat and sleep meanwhile. It was a very dubious-looking, nay, a very dark and dismal night, bitingly cold and cheerless. I knew no-one in the place. With anxious grapnels I had sounded my pocket, and only brought up a few pieces of silver, --- ``So, wherever you go, Ishmael,'' said I to myself, as I stood in the middle of a dreary street shouldering my bag, and comparing the gloom towards the north with the darkness towards the south --- ``wherever in your wisdom you may conclude to lodge for the night, my dear Ishmael, be sure to inquire the price, and don't be too particular.'' \end{document} \end{verbatim} \end{small} \LaTeX\ has handled all the details of page size, line-breaks, page-breaks (take my word on that one), hyphenation, ligaturing, paragraph indentation, justification, the white space between lines, and so on. These are all implied through the adoption of the `book' document style. Another feature which may have appeared transparently is the text's division into paragraphs. If you leave a blank line, \LaTeX\ will implicitly assume that this represents a paragraph break. And by default it will leave indentation at the beginning of the paragraph. \section{Elementary typography} What are ligatures\index{ligature}? In many ways they are left-overs from the days of scribes. They are recognized `running together' of letters, to form a new symbol. The most common examples, found in many typefaces are: \begin{center} \begin{tabular}{r@{\quad$\to$\quad}l} f{\,}f&ff\\ f{\,}i&fi\\ f{\,}l&fl\\ f{\,}f{\,}i&ffi\\ f{\,}f{\,}l&ffl \end{tabular} \end{center} This is not simply a `very close' duo or trio of individual letters, but a completely new symbol. This is by no means a universal transformation. It is bound by typeface, by culture, and by time. Gutenberg's original 42 line Bible, printed in about 1455, has at least 50 different ligatures. He was trying to emulate the work of scribes. They had evolved all sorts of shortenings which he strove to adopt. By the 19th century, English had standardized on the 5 or so above, but `ct' and `st' ligatures persisted at least up to the middle of this century, although in rather specialist typefaces. Although ligatures are more common in `serifed' typefaces, some sans serif faces do have ligatures. Equally some fairly traditional serifed faces have abandoned them. Stanley Morison, who is credited with the design of the `Times' typeface, may well be rotating in his grave now that \textsl{The Times} has dispensed with ligatures. \LaTeX\ takes care of ligatures without even thinking about it too deeply. It also takes care of `kerning'\index{kern}. Kerning is a much more recent introduction, and occurs where letters overlap, but do not touch. This is much more noticeable in capital letters: OXO or WAVE ought to be good examples, where the horizontal extent of each character overlaps with that of the next character. Again, kerning is not supported in all fonts. In particular, you would probably not want kerning in a font which was supposed to look like typewriter characters. Kerning relates to the moving together of characters to make the letter spacing more pleasing: it might be better to describe this as `less displeasing'. We may notice when a book is difficult to read because of the typography: we seldom notice when it is easy to read. This is as it should be. A warning: exposure to \TeX\ and \LaTeX\ can affect your enjoyment of the printed word. You start to look at the typography much more closely. It can destroy some books entirely. You may perhaps notice some other things which are done entirely automatically, and which tend to distinguish `typesetting' systems from `desktop publishing' or word processing systems. The first distinguishing feature is the three different sorts of horizontal rules or dashes, used in text (although in Figure~\ref{ishmael} only two of them are used): In fact, dashes\index{dash} come in lots of forms. Formally we identify the following: the hyphen, the en-dash\index{en-dash}, and the em-dash\index{em-dash} (and the minus\index{minus} sign too, but we'll look at that later): see Table~\ref{dashit}. In most typestyles these will be different characters. A hyphen\index{hyphen} is fairly obvious, and is conveyed to \LaTeX\ as a \texttt{-} symbol. An en-dash is a longer symbol (about the length of an N in the current font), and is therefore conveyed to \LaTeX\ as \verb|--|; an en-dash is usually employed to convey the idea of a range, for example 1--10. Occasionally too, an en-dash is used when two names are joined, like Runge--Kutta or Russell--Hertzsprung, although they are often just hyphenated. Thirdly, the em-dash is even longer (related to the capital M), and is given to \LaTeX\ as \verb|---|. The em-dash is punctuation in text. (The minus is a mathematical symbol which has to be given in maths -- to be covered later -- as \verb|$-$|.) \begin{table*} \begin{center} \begin{tabular}{lccl} \hline `correct name' & \LaTeX\ form & typeset form & example\\ \hline hyphen & \verb|-| & - & hy-phen\\ en-dash & \verb|--| & -- & 1--7 \\ em-dash & \verb|---| & --- & Knuth---the archi\TeX t\\ minus & \verb| - | & $-$ & $x-y$ \\ \hline \end{tabular} \caption{Length and meaning of horizontal lines\label{dashit}} \end{center} \end{table*} Another feature is treated by \LaTeX\ as a sort of ligature\index{ligature}. Quotation marks\index{quotation mark} (i.e.\ double inverted commas) come in open and close varieties in many fonts. \LaTeX\ employs the quote (also known as \textit{apostrophe} and \textit{prime}) and grave. On one of my keyboards `quote' is on the right of the keyboard, just beside the \verb|return| key). The left quote, or {\it grave} is at the top left of the keyboard, beyond the numerical characters). Unfortunately, the `extra' characters on a keyboard do not have standardized positions, and the location on your keyboard may differ. Clearly, this provides you with only a single inverted left or right comma at a time. \LaTeX\ `ligatures' a pair of inverted commas, whether they be grave or quote, to form a single `double' quote mark. Thus, to form a double open quote mark on output (the `66' form) -- `` -- type a pair of graves -- \verb|``|, and to form the corresponding (`99') close double quotes -- '' -- type a pair of quotes -- \verb|''|. The double quote symbol on your keyboard -- \verb|"| -- should not be used. \section{In the beginning} The content of \emph{every} document we write with \LaTeX\ has a beginning and end delimited by the \verb|\begin{document}|\index{begin@\texttt{begin}} -- \verb|\end{document}|\index{end@\texttt{end}}\index{document@\texttt{document}} pairing. Note that this is the beginning and end of textual content of the document. It is not the beginning and end of the file of information. While it seems that there is little point in placing anything after the \verb|\end{document}| statement, since it will never by seen by \LaTeX, it is somewhere to keep notes, odd ideas and even pieces of text you plan to use in the future. This is described as a `document' \emph{environment}. The notion of an enclosed environment, with a matching \verb+\begin+ and \verb+\end+ pair is fairly fundamental to \LaTeX. The very beginning of the file of information has a \verb|\documentclass| statement. This statement will be modified by additional instructions which will determine many of the layout alternatives which will be adopted; it also has some bearing on the sorts of structures which are available. \LaTeX\ has a small number of fixed document \emph{classes}\index{class} associated with it. \section{Classes of style, flair and panache} The basic \LaTeX\ document classes\index{document classes} are \texttt{book}, \texttt{report}, \texttt{article}, \texttt{letter}, \texttt{slides}, \texttt{proc} and \texttt{ltxdoc}. The first four of these were the original `styles' released with \LaTeX\ and documented (to some extent) in the original manual \cite{LL85}. The remainder were introduced with \LaTeXe, when the concept of `document class' was also introduced, and separated carefully (though not wholly convincingly) from `style'\index{style} (see also~\cite{LL94}). In general the names are descriptive, meaningful and obvious. For those already familiar with \LaTeX\ the class \texttt{slides} replaces \SliTeX, while \texttt{proc} is intended to handle a conference proceedings. The last, \texttt{ltxdoc} is an indirect product of the documentation effort related to \LaTeXe\ and \LaTeX3, and is intended to assist in the documentation of classes and styles. It will not be examined here. There are other classes around, many of which are referred to and described in the \textsl{\LaTeX{} Companion} \cite{MGFMAS94}. In theory, these classes and styles should be documented in what Lamport refers to as the \textsl{Local Guide}. He had the notion that every installation would have a locally produced \textsl{Guide} which would contain useful information on the availability of fonts, classes, styles, support software, and so on. \textsl{Guides} are usually conspicuous by their absence. The \textsl{Companion} is an admirable substitute. The implications of each style are sometimes hard to grasp. Just how does \texttt{report} differ from \texttt{article}? To some extent this is to misunderstand the function of the classes and the model of \emph{declarative markup}\index{markup} which was outlined earlier. Lamport worked with a number of document designers to develop the classes\slash styles. And he made it a non-trivial job to `tweak' the classes\slash styles to adapt them. In other words, he felt (very strongly) that you, as the user, should get on with what you were good at, namely writing, and let \LaTeX\ get on with what it was good at, namely formatting. To be fair, \LaTeXe\ does simplify some modes of modification. Everybody wants to tweak. And not everybody enjoys the layouts adopted by Lamport. They certainly come out of a particular typographic tradition, one which is not universal. It is one possible comment that the original \LaTeX\ book does not use the \texttt{book} layout available with \LaTeX. To use a particular class, we say\index{documentclass@\texttt{documentclass}} \begin{verbatim} \documentclass{report} \end{verbatim} or whichever of the classes we wish to choose. In addition, there are \emph{options}\index{options}, which modify the fundamental class. For example, there are \texttt{11pt} and \texttt{12pt} options which allow us to change the basic size of the font used in the main body of the text. By default, \LaTeX\ uses a 10 point font for its `body text'. \emph{Options} precede the \emph{class}, and are enclosed in square brackets: \begin{verbatim} \documentclass[11pt]{report} \end{verbatim} \begin{question} The example in Figure~\ref{ishmael} was created using the \texttt{book} class (since it is really a chapter from a book). To get some crude notion of the effects of changing styles (and options), you could edit the \verb|\documentclass| statement to create \texttt{article}s or \texttt{report}s at 10, 11 or 12 point. \end{question} \begin{question} What other document classes do you require? \end{question} Although there are few document classes, there are far more options. There are also lots of `packages'\index{package} which allow us to change some aspect of the default presentation and features of \LaTeX. Changing an option or package is far easier than tackling a class. Later we may look at the modifying or creating packages to alter the default behaviour of \LaTeX. Clearly the options \texttt{10pt}, \texttt{11pt} and \texttt{12pt} are mutually exclusive. A document may have only one basic type size. But there are other options which affect some other aspect of the presentation. For example, \texttt{twoside} formats the output for printing on both sides of the page (`duplex' printing). Of course this does not mean they will come out of the printer printed on both sides. It simply affects the physical position of the mass of text on odd and even pages, so that when they are used as masters (in a photocopier, for example), the text will fall in a position which ensures that there is no `show through': that is, you cannot see the other page's text as a `shadow' through the paper, since it is obscured by the text on the page you are reading. Such subtle niceties are the traditional concern of printers. Another option is \texttt{twocolumn}, which produces two-column output. When we specify several options, they are separated by commas: \begin{verbatim} \documentclass[twocolumn,11pt,twoside]{report} \end{verbatim} \begin{table*} \begin{minipage}{.5\textwidth} \begin{center} \begin{tabular}{|ll|} \hline \verb+\documentclass+&principal \texttt{options}\\ \hline \texttt{book} & twocolumn, 10pt, 11pt, 12pt, twoside\\ \texttt{report} & twocolumn, 10pt, 11pt, 12pt, twoside\\ \texttt{article} & twocolumn, 10pt, 11pt, 12pt, twoside\\ \texttt{letter} & 10pt, 11pt, 12pt\\ \texttt{slide} &\\ \texttt{proc} & twocolumn, 10pt, 11pt, 12pt, twoside\\ \texttt{ltxdoc} & twocolumn, 10pt, 11pt, 12pt, twoside\\ \hline \end{tabular} \caption{Some of the default range of classes and their options\label{range}} \end{center} \end{minipage} \begin{minipage}{.5\textwidth} \begin{center} \begin{tabular}{|ll|} \hline size options&paper size\\ \hline \texttt{a4paper}&$210\,\textrm{mm}\times297\,\textrm{mm}$\\ \texttt{a5paper}&$148\,\textrm{mm}\times210\,\textrm{mm}$\\ \texttt{b5paper}&$176\,\textrm{mm}\times250\,\textrm{mm}$\\ \hline \texttt{letterpaper}&$8.5\,\textrm{in}\times11\,\textrm{in}$\\ \texttt{legalpaper}&$8.5\,\textrm{in}\times14\,\textrm{in}$\\ \texttt{executivepaper}&$7.25\,\textrm{in}\times10.5\,\textrm{in}$\\ \hline \end{tabular} \caption{The range of page size options\label{size}\index{size}} \end{center} \end{minipage} \end{table*} \begin{question} Try a few options. Does \texttt{twoside} work correctly on your printer? Be bold. \end{question} There are also a set of built in page sizes, Table~\ref{size}, which do two things: they set the height and width of the text itself, and they also position where the text will be placed on the page. Obviously \LaTeX\ cannot know what page size you will ultimately use, and selecting \texttt{a4paper} will not guarantee that the output device, perhaps a laser printer, is actually loaded with the correct size of paper. If you do not use any of these size options, the default is \texttt{letterpaper}, a rather distressing result outside the US. If you were using some other size of paper (perhaps for a book), it would be necessary to set the width and height of the text through some other means. This method is likely to be inappropriate. It is also possible to add another option to these, \texttt{landscape}, which swaps the height and width to give a `landscape' orientation rather than the more normal `portrait'. \section{More information} Part of the structure of a document will be the `front' matter: things like the title, the author, and so on. \LaTeX\ allows you to include this information too. We can write something like \begin{verbatim} \title{The Carpet-Bag} \author{Herman Melville} \date{1851} \end{verbatim} By itself, this does nothing. Until we say \verb|\maketitle|\index{title}, this information does not appear on the page. Since we would expect a title to appear at the beginning of a document, the \verb|\title|, \verb|\author| and \verb|\date| should normally appear before we try to write out the title. The `best' place for the information is therefore between the \verb|\documentclass| specification and the \verb|\begin{document}| statement. From time to time this location will be described as the document \emph{preamble}. But to be truthful, it can go anywhere. If you do not specify a \verb|\date|, \LaTeX\ will use the current one (which happens to be \today). In order to omit the date entirely, you could type \verb+\date{}+. The empty braces are necessary: \verb+\date+ by itself would not give you an acceptable result. \begin{verbatim} \documentclass[twocolumn,11pt]{book} \title{The Carpet-Bag} \author{Herman Melville} \date{1851} \begin{document} \maketitle . . \end{document} \end{verbatim} \begin{question} Go ahead, do it. Of course you do not have to use \texttt{twocolumn} or the \texttt{book} document class. \end{question} \section{Some back-tracking} All along we have ignored the presence of some key characters. I have presented instructions like \verb|\documentclass|\index{backslash} and \verb|\begin| without much fanfare. The backslash character, `\verb|\|', is of major importance. All \LaTeX\ instructions are introduced by such a character. In a sense, it is the \TeX\slash\LaTeX\ `escape character'. Whatever follows a \verb|\| is treated in a special way, and will not appear on the page as such. Obviously there are ways of making backslashes appear on the page, since this document was produced through \LaTeX. Note too that \LaTeX\ is case-sensitive\index{case sensitive}. \verb|\DocumentClass| will not be understood. In very general terms, the majority of the instructions you supply specifically for \LaTeX\ will be in lower case. Only a few instructions use upper case characters. A \LaTeX\ instruction\index{command}\index{instruction} may be constructed in \emph{only} one of two ways. The first\label{commands}, most flexible way, which we have used already, is by a backslash followed by an arbitrary number of alphabetic characters. Thus we might expect to see the following as legal \LaTeX\ instructions: \begin{center} \begin{tabular}{lll} \verb|\documentclass|&\verb|\raggedbottom|&\verb|\section|\\ \verb|\maketitle|&\verb|\vspace|&\verb|\hspace|\\ \verb|\kill|&\verb|\sloppy|&\verb|\newpage|\\ \verb|\framebox|&\verb|\line|&\verb|\circle| \end{tabular} \end{center} Each one of these is a legitimate instruction which already exists in \LaTeX. The alternative form is a backslash followed by a \emph{single non-alphabetic} character. Thus we might expect to see the following: \begin{center} \begin{tabular}{lll} \verb|\~|&\verb|\\|&\verb|\.|\\ \verb|\1|&\verb|\#|&\verb|\ | \end{tabular} \end{center} Note that `space'\index{space} is a legitimate non-alphabetic character. Since it is sometimes difficult to see when `space' is meant, from time to time we will use \verb*| | to indicate a space which occurs between words and\slash or instructions; when \verb*|\ | is used it indicates the instruction where a space is the non-alphabetic character (In \LaTeX\ this instruction actually generates a space). We do not find instructions like \begin{center} \begin{tabular}{lll} \verb|\A4|&\verb|\half-sized|&\verb|\up&down|\\ \verb|\1.1|&\verb|\(longer)|&\verb|\m.clark| \end{tabular} \end{center} On the other hand, the \emph{option}s\index{options} may be made up of mixtures of alphabetic and non-alphabetic characters (as we have already seen: \verb+11pt+ or \verb+A4paper+). Options are always enclosed by the square brackets. The \textit{argument} to an instruction, is the part in braces (or \textit{curly} brackets). An instruction with an argument\index{argument} \emph{always} requires an argument, although as suggested earlier, the argument could be `null' -- \verb|\date{}|. Sometimes you may only specify one of a handful of alternatives, as in the case of the arguments of \verb|\documentclass|, while in other cases, like \verb|\author|, you have complete freedom. There are also instructions which require no argument at all -- \verb|\maketitle| is an example. The braces\index{braces} are never printed by \LaTeX. Of course, there are ways to print \verb|{| and \verb|}| or even $\}$ and $\{$, but we shall look at them later. \begin{question} What does happen when you specify a non-existent document class, or a non-existent option? Hint: try it. Advice: Don't Panic (in large friendly letters). \end{question} \section{Trying to correct mistakes} If you did the last exercise, you will have deliberately made mistakes on input, and will have encountered \LaTeX's error\index{errors} processing capability. It is possible to correct errors as \LaTeX\ is running interactively. If you should successfully correct the input in this way, you must also remember to correct the original (assuming you might just need to re-run sometime). To be more truthful, you may have met both \LaTeX's error processing, \emph{and} \TeX's. Neither is especially elegant. One of the most common mistakes is to invoke an instruction which does not exist -- either because you let intuition take the upper hand and assume that the instruction must exist, or, more likely, because you mis-spell it. \LaTeX\ will object: \begin{verbatim} ! Undefined control sequence. l.3 \start {section}{Start} ? \end{verbatim} \LaTeX\ is trying hard to indicate where the error lies, principally by breaking the line to indicate just where it has foundered. In the example above, it is the instruction \verb+\start+. At this point it is wise to note that (\La)\TeX\ refers to a `control sequence'\index{control sequence|see{instruction}}, a piece of jargon which is often replaced by the word `command'\index{command}, and in this text by `instruction'\index{instruction}. Note however that we are left with a \verb|?| prompt. Let's be intuitive, and assume that \LaTeX\ has something up its sleeve, like additional help. How do you get help? How about typing `\texttt{h}'? Lo, something else appears. \begin{verbatim} The instruction at the end of the top line of your error message was never \def'ed. If you have misspelled it (e.g., `\hobx'), type `I' and the correct spelling (e.g., `I\hbox'). Otherwise just continue, and I'll forget about whatever was undefined. ? \end{verbatim} Well, who can understand that? Not very helpful at all. But we've still been left with a question mark. Let's try `\texttt{h}' again. \begin{verbatim} Sorry, I already gave what help I could... Maybe you should try asking a human? An error might have occurred before I noticed any problems. ``If all else fails, read the instructions.'' \end{verbatim} This is one of (\La)\TeX's attempts at humour or light heartedness. All the same, it is probably good advice. In response to the `\texttt{?}' prompt, you have several options. You may type any of the following: \begin{description} \item[\texttt{?}\quad] where (\La)\TeX\ gives a summary of the following options: \begin{verbatim} Type to proceed, S to scroll future error messages, R to run without stopping, Q to run quietly, I to insert something, E to edit your file, 1 or ... or 9 to ignore the next 1 to 9 tokens of input, H for help, X to quit. \end{verbatim} \item[\texttt{}\quad] just prod the \verb|return| key (or the \verb+enter+ key). \TeX\ proceeds as best it can, until it encounters another error. \item[\texttt{X} or \texttt{x}\quad] \LaTeX\ stops (eXits); you are returned to the operating system. Any pages which have already been completed may not be lost, but the current one will certainly be lost; the previous one might be as well. \item[\texttt{E} or \texttt{e}\quad] this stands for `edit', and should drop you into an editor. Not all implementations have this linking of \LaTeX\ and editors. If you do not drop into an editor, you will simply be returned to the operating system prompt. The best way to find out if it does work on your system is to try it. If it does work you would find yourself editing the erroneous file, at about the right line -- or rather, where \LaTeX\ thinks the error occurred. Often it is remarkably close to the error. \item[\texttt{I} or \texttt{i}\quad] you may now type text to be Inserted at the current place in input. At first this seems intimidating, but with some practice it does become a viable route. Its major drawback is that you tend to forget these `dynamic' corrections. \item[a number between 1 and 99\quad] \LaTeX\ deletes this number of characters and instructions from input. The characters or instructions are those which are waiting to be read -- in other words, \LaTeX\ has not yet `seen' them, or tried to do anything with them. \LaTeX\ then asks for more information (you could insert, etc.): \LaTeX\ sees an instruction as a single item: it also sees a character as a single item -- otherwise termed `token'\index{token} -- for example, \verb|\textbf{bold}| is seen as the 7 `tokens' \verb|\textbf|, \verb|{|, \verb|b|, \verb|o|, \verb|l|, \verb|d| and \verb|}|. A space is treated as a token, \emph{except} when it immediately follows a instruction. \item[\texttt{H} or \texttt{h}\quad] (\La)\TeX\ gives some sort of help. \item[\texttt{S} or \texttt{s}\quad] this is like typing \verb|| (or \verb||) for every subsequent error message. The error messages are logged, but you have no chance of interaction. \item[\texttt{R} or \texttt{r}\quad] this is like {\tt S}, only worse; under no circumstances stop. \item[\texttt{Q} or \texttt{q}\quad] even even worse; \LaTeX\ suppresses all output to the terminal (goes a lot faster, subjectively), but perhaps not the best route unless you are very confident that you know what you are doing, which obviously you don't, else you would not have made a mistake in the first place. There is an instruction equivalent, \verb|\batchmode|, which gives a good clue of when this would be most commonly used. \end{description} There is obviously a temptation to just type \verb|| and let \LaTeX\ surge ahead to report on any other errors. Unfortunately the corrections \LaTeX\ may have made in order to do something apparently sensible may lead to other mistakes later on. When I don't feel up to mental gymnastics I much prefer to leave \LaTeX\ (by typing \texttt{x} or \texttt{e}), correct the error, and then return to \LaTeX. \section{Hints} Don't panic. Error messages are often difficult to fathom, and it can be easier to solve the problem with reference to your text and the instructions which were included in the file than to attempt to understand what the error message is saying. But do not ignore the messages entirely. Sometimes they can be uncannily accurate and helpful. What are the common errors?\index{errors} Failing to balance braces (every open brace must have a corresponding close brace). This is really quite difficult to correct through the error reporting and correction procedure outlined above. If you have a brace open, \LaTeX\ may do quite a lot of work before you realise that something has gone wrong. In such a case it is almost impossible to put things back together in a reasonable way. Sometimes this situation manifests itself when processing finished and you see a message that \begin{verbatim} (\end occurred inside a group at level 1) \end{verbatim} In a similar way, from time to time you might fail to `\verb|\end|' something you have `\verb|\begin|ned'; again the same message may appear. More readily apparent, you may \verb|\begin| something but \verb|\end| it with the wrong thing. Mis-types are a frequent source of problems. After all, if you type \verb+artical+ for \verb+article+, \LaTeX\ can hardly be expected to divine your intention. Any instruction which is presented to \LaTeX\ `incorrectly' will present a problem. It really does not care about your own spelling. It does care about the instructions you give it, and since it thinks you know best, it attempts to follow your orders to the letter. Apart from that, what can go wrong?