\chapter{Getting Started} \label{strt} \section{Preparing an Input File} \label{input-file} Your input to \LATEX{} is a \index{input file}text file. On most computers, file \index{file names} names have two parts separated by a period, like {\tt always.iys}. The first part of your input file's name can be anything, but the second part should be {\tt tex}. I'll use \index{myfile.tex}{\tt myfile.tex} as my standard example input-file name, but you can use any name you like. I assume that you know how to prepare a file with a text editor, so I'll just tell you what should go into the manuscript file, not how to get it there. First, however, I'll mention some important things about text files that you may not be aware of. A text file is a string of characters. There are two kinds of characters, printing\index{printing characters} and nonprinting\index{nonprinting characters} ones. The printing characters are all those characters like \xsp{}\verb"q"\Xsp, \xsp{}\verb"%"\xsp{} or \xsp{}{\tt =}\xsp{} that light up phosphors on the screen, or put ink on the paper when the file is printed. All the rest are nonprinting characters. The nonprinting characters are just as real as the printing ones, and it's important to know about them. When you look at a text file, it appears to be a series of lines composed of characters and horizontal spaces, the characters usually being grouped into words. The lines and spaces are actually produced by certain nonprinting \index{nonprinting characters}characters that are in the file. The spaces between words are most often the result of space \index{space character}characters that are put into the file when you hit the space bar on your keyboard. In this manual, I'll usually denote space characters by blank spaces, just like they appear on your terminal's screen. However, when I want to emphasize that there's a space character present in the input file, I'll use the symbol \xsp{}\index{!sp}\verb*" "\xsp{} to denote that character. Unlike an ordinary character such as \xsp{}{\tt q}\Xsp, it's often hard to tell whether you've typed one or two space characters. Fortunately, you don't have to worry about that. \LATEX{} treats any number of consecutive \xsp{}\verb*" "\xsp{} characters just the same as a single one. There's another key on your terminal that produces empty space on the screen or printed page: the \index{tab}{\it tab\/} key. Hitting this key enters a nonprinting character called {\it tab\/} that acts like one or more space characters. \LATEX{} treats a tab character exactly the same as a \xsp{}\verb*" "\xsp{} character. Since one \xsp{}\verb*" "\xsp{} is the same as several to \LATEX, you never have to worry about whether that blank space on your screen is caused by a tab character or some \xsp{}\verb*" "\xsp{} characters. I usually won't mention the tab character, but everything I say about \xsp{}\verb*" "\xsp{} will apply to tab as well. Your file is broken into a series of lines by a nonprinting character called {\it carriage return\/}\index{carriage return} that appears between the lines. I will use \carrtn{}\index{!!carrtn} as the name for this carriage return character.\footnote{On many computer systems, a carriage return is really two characters---a plain carriage return and a line feed. This is of no concern, since \TEX{} treats them as a single character.} The \carrtn{} characters were probably entered in your file by hitting the key marked {\it return\/} on your terminal. Just like a \xsp{}{\tt q}\xsp{} or a \xsp{}\verb*" "\Xsp, a \carrtn{} is a full-fledged character. Most of the time, \TEX{} treats a \carrtn{} as if it were a \xsp{}\verb*" "\Xsp, but you'll see that there are cases when this isn't true. There's one other nonprinting character that you might find in your file: the {\it new-\index{new-page character}page\/} character, sometimes called \index{control-l}{\it Control-L}. If your text editor has a command for starting a new page, it probably works by putting a new-page character in the file. \TEX{} treats a new-page character as if it were a blank line. Text files can also contain some weird \index{weird characters} nonprinting characters, like the one that makes your terminal beep. Those characters don't belong there; \TEX{} will come to a grinding halt if it finds one. Fortunately, it's hard to get such characters into your file, so you needn't worry about them. There are a number of funny printing characters hiding in the corners of your keyboard that you may find yourself typing for the first time when you prepare \LATEX{} input. First and foremost is the {\tt \bs} \index{!!bs} character (pronounced \index{backslash}``backslash''). It should not be confused with the more familiar {\tt /} character, as in {\tt 1/2}. You'd better practice typing the {\tt \bs} because you'll use it a lot. Every \LATEX{} command begins with a {\tt \bs}. In typing the input for this chapter, I've used the {\tt \bs} characters about as often as the letter {\tt d}. Your keyboard should have three kinds of bracketing pairs: parentheses \index{parentheses} {\tt (} and {\tt )}, square \index{brackets}brackets {\tt [}\index{[} and \index{]}{\tt ]}, and curly \index{braces}braces {\tt \lb}\index{!!lb} and {\tt \rb}\index{!!rb}. \LATEX{} makes special use of the square brackets and curly braces. There should be three quote \index{quote characters} characters on your keyboard: {\tt "}\index{"}, {\tt '}\index{'} and {\tt `}\index{`}. You can forget about the {\tt "} (double quote); you won't need it at all. The {\tt '} is called ``right \index{right quote}quote'' and the {\tt `} is called ``left \index{left quote}quote'' for reasons that will soon be obvious. The {\tt '} is probably in a prominent position on the keyboard, perhaps over the {\tt 7}; it may look more like $'$ or \rule[3pt]{.6pt}{3.7pt} on your screen. The {\tt `} is probably squirreled away in a corner, and may appear on your screen as \`{} . Among the printing characters, the following ten play a special role in \TEX{} and are called {\it special \index{special printing characters} printing characters}, or simply {\it special characters}. \begin{verbatim} # $ % & ~ â?? ^ \ { } \end{verbatim} While you're perusing your keyboard, it would be a good idea to pick them out. The first four \index{!!sharp}\index{!!dollar}\index{!!percent}\index{!!ampersand}are everyday symbols that you're familiar with. The tilde \index{tilde} character \xsp{}\verb"~"\xsp{} is probably hidden at the edge of your keyboard; the caret \xsp{}\index{caret}\verb"^"\xsp{} may be denoted by a \index{!!uparrow}\xsp{}$\uparrow$\Xsp; the underscore \index{underscore} \xsp{}\verb"â??"\xsp{} sometimes appears on the screen as a \index{!!leftarrow}$\leftarrow$. You might want to paint these ten special character keys red because they are the characters that have a special meaning to \TEX. Whenever you put one of these characters into your file, you're doing something special. The \label{ordinary} remaining printing characters are called the {\it ordinary \index{ordinary printing characters}printing characters}. They are the upper- and lowercase letters, the ten digits \mbox{{\tt 0} $\ldots$ {\tt 9}} and the following. \begin{verbatim} . : ; , ? ! " ` ' ( ) [ ] < > - = + / * | @ \end{verbatim} Note that uppercase and lowercase letters are distinct characters. Don't confuse the uppercase letter {\tt O} (oh)\index{O}\index{oh} with the digit {\tt 0}\index{0} (zero)\index{zero}. Also, don't confuse the letter {\tt l}\index{l} (the lowercase \index{el}{\it el\/}) with the digit {\tt 1}\index{1} (one)\index{one}. The only characters that should appear in your file are the ordinary and special printing characters and the nonprinting characters \xsp{}\verb*" "\Xsp, \carrtn, {\it tab\/} and {\it new-page}. Some terminals\index{terminal} have a variety of keys with strange characters etched on them. Pressing one of these keys usually issues a command to your editor without putting the strange character in the file. However, some of them may put weird characters in your file. \TEX{} does not like such characters and will either complain bitterly or do strange things if it finds one in an input file. If your keyboard happens to have a key labeled \xsp{}\index{!!leq}$\leq$\Xsp, you will be tempted to try to produce \xsp{}$1\leq 2$\xsp{} by typing {\tt 1}$\leq${\tt 2}. Don't, unless you've been assured by a local expert that it works; otherwise, it probably won't. It's easy enough to generate a \xsp{}$\leq$\xsp{} with ordinary \LATEX{} commands. To get a document formatted properly, you have to tell \LATEX{} what you want. This involves a lot of typing. Being a fast typist helps, but it's still quite a chore. For example, a boldface\index{boldface} word like {\bf bold} is produced by typing \index{!bf}\verb*"{\bf bold}", which means typing six characters besides the four in {\tt bold}. All these extra characters can add up to a lot of extra work. Fortunately, a good text editor like EMACS\index{emacs} \cite{emacs} can be customized to reduce the amount of typing required. In my own personal version of EMACS, typing a single control character produces \verb*"{\bf }" and leaves the cursor just before the {\tt \rb}. Typing \verb*"{\bf bold}" takes only two extra keystrokes (the second to move past the {\tt \rb}) instead of six. This special EMACS command, together with a bunch of similar ones, saves me a lot of work. If you can't do this with an editor available on your computer, you should complain. A good text editor can also help you avoid errors. The easiest error to make in your input is to leave out a curly brace. \TEX{} expects braces to come in matched \index{braces,matching} pairs and gets very unhappy when they don't. With my editor, a single keystroke generates a pair of braces, so I can't forget to type the closing {\tt \rb}. There's also a command that checks the entire file for unmatched braces, in case I accidentally deleted a single brace. Adding these commands to my editor eliminated 90\% of my \TEX{} errors. \section{Starting and Ending} Your input file starts with commands to tell \TEX{} how you want your document formatted---how wide the text should be, how sections are to be numbered, and so on. You may eventually want to decide all this yourself, but to start out, you'll choose some standard format. The first part of the format is called the {\it page layout\index{page layout}}. Your own computer installation will have its own selection of page layouts, but there should be a standard one called {\tt normal}\index{normal page layout}. To use it, you begin your file with the command \begin{verbatim} \pagelayout{normal} \end{verbatim} The \verb"\pagelayout"\index{!pagelayout} command specifies the dimensions of things on the page, such as the height and width of the text. The second part of the format that you must specify is called the {\it document \index{document style} style}. It determines such things as how sections are numbered and where figures are placed. Two standard document styles are {\tt report}\index{report document style} and \hbox{\tt article}\index{article document style}. The major difference between them is that the largest division in the {\tt report} style is the chapter, each chapter starting on a new page, while the largest division in the \hbox{\tt article} style is the section, where a section need not start on a new page. Both styles have sections, subsections and subsubsections. To choose the {\tt article} document style, the second command in your file will be: \begin{verbatim} \documentstyle{article} \end{verbatim} You can, of course, obtain the {\tt report} style by typing {\tt report} instead of {\tt article}. The \verb"\pagelayout" and \verb"\documentstyle" commands are then followed by a\index{!begin[document]} \begin{verbatim} \begin{document} \end{verbatim} command. After this comes the actual text of the document. The file ends with the command\index{!end[document]} \begin{verbatim} \end{document} \end{verbatim} The \verb"\begin{document}" and \verb"\end{document}" will make more sense to you later. For now, just remember that they have to be there, and concentrate on the important stuff---the text that generates the printed output. So, you just need to know that your file looks like this: \begin{verbatim} \pagelayout{normal} \documentstyle{article} \begin{document} ... your text goes here ... \end{document} \end{verbatim} \section{Typing Simple Text}\index{simple text}\label{simple-text} Producing simple text is easy; you can pretty much type what comes naturally. The rest is done for you. For example, the preceding two sentences were obtained by typing \begin{verbatim} Producing simple text is easy; you can pretty much type what comes naturally. The rest is done for you. \end{verbatim} \TEX{} ignored how many spaces \index{space character} I put between words---it treats any number of consecutive \xsp{}\verb*" "\xsp{} characters like a single \xsp{}\verb*" "\Xsp. It also considers a \index{!carrtn}\carrtn{} to be the same as a \xsp{}\verb*" "\xsp{} and does its own line \index{line breaking}breaking. A new \index{paragraph}paragraph is begun by leaving one or more blank lines---in other words, by any sequence of \index{!!carrtn}\carrtn{} and \xsp{}\verb*" "\xsp{} characters containing at least two \carrtn{}'s. A new paragraph is normally \index{indentation,paragraph}indented, but the indentation can be \index{paragraph indentation, suppressing} suppressed by typing \index{!noindent}\verb"\noindent" at the beginning of the paragraph. Below is a list of other things that come up frequently in simple text. \yspace \noindent{\bf Quotes:} \index{quotes} Double quotes are produced by typing two \index{`}{\tt `} characters for the left quotes and two \index{'} {\tt '} characters for the right quotes. For example, typing {\tt ``quote''} produces ``quote''. You get single quotes, as in `single' by typing single {\tt `} and {\tt '} characters, as in {\tt `single'}. The observant reader will note that I use the logical rather than the conventional method of mixing quotation marks and punctuation, writing ``this'', and not ``this.'' ``This'', being my own personal preference, is not a \LATEX{} policy. You can type \begin{verbatim} ``this'', or ``that,'' \end{verbatim} to produce ``this'', or ``that,'' as you prefer. \yspace \noindent {\bf Dashes:} \index{dashes} \TEX{} provides three sizes of dash: -, --, and ---. They are produced by typing one, two, or three {\tt -} characters, respectively, as in \begin{verbatim} three sizes of dash: -, --, and ---. \end{verbatim} A minus \index{minus sign}sign, as in $4-2=2$, is not the same as a dash. If you're using a minus sign, then you're writing a mathematical formula and you should refer to Section~\ref{math} on page~\pageref{math}. \yspace \noindent {\bf Space after periods:} \index{space}\index{period, space after}\TEX{} tries to put a little extra space after a sentence-ending period, but not after a period that doesn't end a sentence. However, \TEX{} is rather simple-minded, and it thinks that a period ends a sentence unless it follows an upper-case letter. This works most of the time, but look what happens if you type: \begin{verbatim} Euclid et al. proved I + I = II. Meanwhile ... \end{verbatim} \TEX{} produces \begin{quote} Euclid et al. proved I + I = II. Meanwhile \(\ldots\) \end{quote} thinking that the period after {\tt al} ends a sentence, and the period after {\tt II} doesn't. To force \TEX{} to do the right thing, you should type: \begin{verbatim} Euclid et al.\ proved ... II\mbox{}. Meanwhile ... \end{verbatim} The \verb*"\ " \index{!space} tells \TEX{} to make an ordinary space, and the \verb"\mbox{}" separates the upper-case {\tt I} from the period. \yspace \noindent {\bf Special characters:} All of the ordinary \index{ordinary printing characters} printing characters listed on page~\pageref{ordinary} produce more or less what you'd expect them to. For example, typing {\tt +} produces +, and typing {\tt [} produces [\hspace*{.2em}. However, the ten special \index{special characters}characters \begin{verbatim} # $ % & ~ â?? ^ \ { } \end{verbatim} have special meanings for \TEX. The following six can be produced by typing a {\tt \bs } in front of them: \begin{verbatim} # $ % & { } \end{verbatim} For example, typing \verb"\$20" yields \$20. The other four special characters are used so seldom in text that \LATEX{} doesn't provide such a simple method of generating them. How to obtain them, as well as a host of other symbols, is explained in in Sections \ref{nonm-sym} and \ref{math-symbols}. \yspace \noindent {\bf Preventing line breaks:}\index{line breaking, preventing} \TEX{} produces nice, neat, justified paragraphs from your ragged input, hyphenating words if necessary. Sometimes it breaks a line \index{line breaking} where you don't want it to. For example, it looks bad if I refer to page 28, and the line is broken between the ``page'' and the ``28''. You can prevent this from happening by typing \verb"page~28". \index{tilde}The \xsp{}\verb"~"\xsp{} acts like a single \xsp{}\verb*" "\Xsp, except that it prevents \TEX{} from breaking the line there. Don't leave a space before or after the \xsp{}\verb"~"\Xsp; it will produce an extra space in the document. \yspace \noindent {\bf Comments:}\index{comments} Sometimes you may want to leave little notes to yourself in the input file that you don't want printed. Typing \xsp{}\verb"%"\xsp{}\index{percent} tells \TEX{} to ignore everything else on the current line, including the \carrtn{}\index{!carrtn, ignoring} at the end. For example, you might type \begin{verbatim} as what's his name% Look up the name! showed in 1976. \end{verbatim} to produce \begin{quote} as what's his nameshowed in 1976. \end{quote} However, the next time you'll remember that the \xsp{}\verb"%"\xsp{} causes \TEX{} to ignore the \carrtn{} as well as the text, and you'll type \xsp{}\verb*"name %"\Xsp. You'll also remember this if you ever want to end a line in your input file without putting space in the output. \yspace Now \index{sectioning commands} that you know how to enter ordinary text, you'll want to structure your text in units---sections, subsections and subsubsections if you're using the {\tt article}\index{article document style} style, or chapters, sections, subsections and subsubsections if you're using the {\tt report}\index{report document style} style. I've already mentioned that this chapter was begun by typing the command\index{!chapter} \begin{verbatim} \chapter{Getting Started} \end{verbatim} and you can probably guess that the following section\index{!section} was begun with \begin{verbatim} \section{Commands} \end{verbatim} The \index{!subsection}\verb"\subsection" and \index{!subsubsection}\verb"\subsubsection" commands are similar. You can find more information about these and other sectioning commands in Section~\ref{sectioning} on page~\pageref{sectioning}. \yspace \noindent {\bf Warning:} Don't try putting any \LATEX{} commands in the name of a chapter or (sub[sub])section before reading Section~\ref{sectioning}. There are still a few more things you'd probably like to add, such as a title page and a table of contents. After finishing this chapter, you'll be able to find and read the sections in later chapters that tell you how. Although you'll eventually want to do that, you should probably start out the easy way---by copying from a friend. Given a \LATEX{} input file, it's pretty simple to figure out which commands create the title page, and what you have to change to generate your name instead of his. In fact, the friendly people who install \LATEX{} on your computer system should also provide some sample input files for you to browse through. \section{Commands} \index{commands} \label{commands} To type fancier text, you have to issue \LATEX{} commands. Before learning about what the commands do, you should learn their syntax and taxonomy. The material in this section may seem abstract and unmotivated, but knowing it will make it easier for you to understand how commands work. Your effort now will be amply rewarded in a little while. I will illustrate the general rules by using some specific commands as examples. Don't worry about what these commands do; for now we're just interested in the syntax. The commands themselves are explained in later chapters. \subsection{Command Names and Arguments} \index{command-names} \index{arguments} \label{command-names} A \LATEX{} command begins with the command name, which consists of a {\tt \bs} followed by either (i) a string of letters or (ii) a single nonletter. Here are some of the commands you've encountered so far. \begin{verbatim} \bf \mbox \noindent \begin \$ \end{verbatim} Another useful command is \index{!today}\verb"\today", which causes \LATEX{} to produce today's date---that is, the date on which you ran your file through \LATEX{}. Here's how I can tell you that this edition of this chapter was generated on \today. \begin{verbatim} Here's how ... was generated on \today. \end{verbatim} Most command names are of the first kind, having of a string of letters. \TEX{} regards lowercase and uppercase letters as completely different, so \verb"\large", \verb"\Large" and \verb"\LARGE" are three different commands. Most \LATEX{} command names have only lowercase letters; the exceptions are generally like the three ``large'' commands, where uppercase letters are used to distinguish otherwise identically-spelled commands. (As you'll see in Section~\ref{type-size}, \verb"\LARGE" is larger than \verb"\Large", which is larger than \verb"\large".) If you write \verb"\$one", \TEX{} knows that this is a \verb"\$" command followed by the text \xsp{}\verb"one"\xsp{} because the only command names having nonletters are two-character names like \verb"\$". However, if you write \xsp{}\verb"\todayone"\Xsp, \TEX{} wouldn't think that this is the command \verb"\today" followed by the text \xsp{}\verb"one"\Xsp. Instead, it regards it as a command named \verb"\todayone", and since there's no such command, it will report an error. You have to tell \TEX{} where a command name ends by putting a nonletter after it. You can write \verb*"\today1" or \verb*"\today one" or \verb"\today-one", since \xsp{}\verb"1"\Xsp, \xsp{}\verb*" "\xsp{} and \xsp{}\verb"-"\xsp{} are nonletters. The most common way to end a command name is with a \xsp{}\verb*" "\Xsp, so \TEX{} ignores all \index{spaces}spaces following a command name. However, this can cause trouble, since typing \begin{verbatim} \today was a sunny day. \end{verbatim} produces \begin{quote} \today was a sunny day. \end{quote} Leaving more spaces after the \verb"\today" won't help---\TEX{} treats any series of spaces the same as a single space. You can get \TEX{} to stop ignoring spaces by typing \verb"{}". I can tell you that \today{} was a sunny day by typing either of the following: \begin{verbatim} \today{} was a sunny day \today {} was a sunny day. \end{verbatim} The special character commands like \verb"\$" and \verb"\#" are exceptions to this rule; spaces are {\it not\/} ignored after these commands. Typing \verb*"\$ .99" produces \$~.99. Many commands have arguments, which are enclosed in curly braces. For example, when you type \verb"\mbox{xyz}", \verb"xyz" is the argument of the \verb"\mbox" command. Typing \verb"\mbox{}" gives \verb"\mbox" a null argument. If a command takes more than one argument, each one is enclosed by curly braces. \verb"\parbox"\index{!parbox} is a command taking two arguments, so you type \begin{verbatim} \parbox {2in}{A Parbox} \end{verbatim} to give a \verb"\parbox" command whose first argument is {\tt 2in} and whose second argument is \xsp{}\hbox{\tt A Parbox}\Xsp. Don't worry about what these commands mean; just observe the syntax. Spaces after the command name are ignored, but you must not leave any spaces between arguments. Some commands have one or more optional \index{optional arguments}arguments, an optional argument being enclosed in square \index{square brackets} brackets. The \verb"\parbox" command has an optional argument that may appear before the other two, so \begin{verbatim} \parbox [t]{2in}{A Parbox} \end{verbatim} has the optional argument \xsp{}{\tt t}\xsp{} and with the same two mandatory arguments as before. The place where an optional argument comes is fixed; for \verb"\parbox" it can come only right after the command name. \TEX{} will be very confused if you try to put it somewhere else, like between the two mandatory arguments. There should be no space between any two arguments, whether they're optional or mandatory. Some \LATEX{} commands have a variant\index{variant commands} form indicated by writing a {\tt *}\index{*} at the end of its name. The variant form is also called the {\tt *}-form\index{*-form}. For example, there's a \index{!!chapter*}\verb"\chapter*" command that works just like the \verb"\chapter" command except that it doesn't add a chapter number or a table of contents entry. \yspace You now know how to write commands in the normal $99{44\over 100}\%$ of the cases. Let's learn what surprises the other $.56\%$ has to offer. Optional arguments provide two kinds of surprises. Consider a command like \verb"\item" \index{!item} that has one optional argument and no mandatory ones, so you can type either \verb"\item[foo]" or \verb*"\item foo". In the first case \xsp{}{\tt foo}\xsp{} is the argument of the \verb"\item" command, and in the second case it is the text that follows the command. Now, what happens if we want to type an \verb"\item" command followed by the text {\tt [foo]}? If we type \verb*"\item [foo]", \TEX{} ignores the space and considers {\tt foo} to be the argument. To prevent this, we must type \verb"\item{}[foo]" or \verb*"\item {}[foo]". The \verb"{}" tells \LATEX{} to stop looking for an optional argument as well as telling it to stop ignoring spaces. Now suppose we want to make not {\tt foo} but {\tt [foo]} the optional argument of the \verb"\item" command, with the square brackets as part of the argument. If we type \verb"\item[[foo]]", \LATEX{} will take {\tt [foo} to be the argument, enclosed by the first {\tt [} and the first {\tt ]}, and it will regard the second {\tt ]} as part of the text following the \verb"\item[[foo]" command. Once again, curly braces come to the rescue. If we type \verb"\item[{[foo]}]", then \LATEX{} will interpret \verb"{[foo]}" as argument; the extra curly braces will do no harm. This trick must be used whenever there's a {\tt [} in the text that could be mistaken for the left bracket delimiting an optional argument. The {\tt *}-commands provide a related surprise. Although we think of the {\tt *} as part of the command name, \TEX{} actually regards it as an optional argument. Unlike the ordinary optional arguments that are enclosed by square brackets, you can leave spaces between the {\tt *} and the following argument. Thus, any of the following is acceptable: \newpage %%%%%% \begin{verbatim} \chapter*{Introduction} \chapter* {Introduction} \chapter *{Introduction} \end{verbatim} If a command with no mandatory arguments has a {\tt *}-form, then we have the same problem, and the same solution, as with the \verb"\item" command. One such command is \xsp{}\verb"\\"\Xsp. To follow the plain \xsp{}\verb"\\"\xsp{} command with a \xsp{}{\tt *}\xsp{} as part of the text, we must use a \verb"{}"---typing \xsp{}\verb*"\\ {}*"\xsp{} instead of \xsp{}\verb*"\\ *"\Xsp. \LATEX{} would interpret \xsp{}\verb*"\\ *"\xsp{} as the {\tt *}-form of the command. \yspace These problems are actually quite rare. Most of the time, you just have to know the following rules. \begin{itemize} \item Command names begin with {\tt \bs}. \item Spaces following a command name are ignored, except for the special-character \index{special character commands} commands like \xsp{}\verb"\$"\Xsp. Use \xsp{}\verb"{}"\index{braces}\xsp{} \index{!lb!rb}to make \TEX{} stop ignoring spaces. \item The variant form of a command has a {\tt *} at the end of the name. \item Mandatory arguments are enclosed by curly braces \verb"{}". \item Optional arguments are enclosed by square brackets {\tt []}. \item There must be no spaces between arguments. \end{itemize} There are a few minor exceptions to some of these rules, but you'll hardly notice them. They are all as benign as the exception to the first rule that you've already encountered: the \xsp{}\verb"~"\xsp{} command. To avoid rare but unpleasant surprises, you should also remember these exceptional situations. \begin{itemize} \item Use \verb"{}" if a {\tt [} can be mistaken for the beginning of an optional argument. \item A {\tt ]} that's part of an optional argument must be inside braces. \item Use \verb"{}" if a \xsp{}{\tt *}\xsp{} can be mistaken for a variant-command indicator. \end{itemize} There's one more little thing you might like to know about command arguments. It's not important, but it can save you a bit of typing. An argument need not be enclosed in braces if it consists of either a single command name or a single letter or digit. If the second argument of a \verb"\parbox" command is the single command \verb"\today", then you can type either of the following: \begin{verbatim} \parbox {2in}\today \parbox {2in}{\today} \end{verbatim} However, if the argument is \verb"\mbox{\today}", then you must use braces because the \verb"\parbox"'s argument then consists of a command name plus argument rather than just a command name. \subsection{The Taxonomy of Commands} There are five \index{command classes}classes of \LATEX{} commands. Understanding the differences among these classes will enable you to use the commands properly and will help you to remember individual commands. \subsubsection*{Text-Producing Commands} \index{text-producing commands} A text-producing command places a piece of text in the document. The actual text is usually specified by an argument, as in the \index{!mbox}\verb"\mbox" command. There may be other arguments that specify how the text is to be formatted; the argument that specifies the text is almost always the last argument. Sometimes, as in the \verb"\today"\index{!today} command, there is no text-specifying argument because \LATEX{} decides what text to insert. An important subclass of text-producing commands are the space-producing \index{space-producing commands} commands. The ``text'' they produce consists of blank space, an argument specifying how much blank space. Most text-producing commands put their text at the current position in the document. There are two cases in which the text may appear elsewhere: \begin{itemize} \item Footnotes \index{footnotes} appear at the bottom of the page. \item Marginal \index{marginal notes} notes are placed in the margin, like the one on the \marginpar[\it \raggedleft This is an example of a mar\-gin\-al note.]{\it\raggedright This is an example of a mar\-gin\-al note.} \ifodd\count0 right\else left\fi. \end{itemize} Figures \index{figures} and \index{tables}tables may also be moved from where they appear in the input file, but they're not made with text-producing commands. \subsubsection*{Environments} \index{Environments} Text-producing commands are designed for formatting short pieces of text. To format a large piece, you use an \index{environment}{\it environment}. An environment begins with a \verb"\begin"\index{!begin} command and ends with a matching \index{!end}\verb"\end" command. The above itemized list was produced with an {\tt itemize} \index{itemize environment} environment, which I typed as follows. \begin{verbatim} \begin{itemize} \item Footnotes appear ... \item Marginal notes ... \end{itemize} \end{verbatim} The environment is begun with the \verb"\begin{itemize}" command and is ended with the \verb"\end{itemize}". The stuff between these two commands is {\it not\/} an argument. Don't worry now about what goes between the \verb"\begin" and the \verb"\end" commands; just remember that the {\tt itemize} environment has no arguments. Some environments do have \index{environment arguments} arguments. These arguments appear as extra arguments to the \verb"\begin" command. For example, there's an {\tt array} \index{array environment} environment, used to make arrays in mathematical formulas, with a single mandatory argument. Typing \begin{verbatim} \begin{array}{llr} ... \end{array} \end{verbatim} creates an array environment whose argument is \xsp{}{\tt llr}\Xsp. Environment arguments can be mandatory or optional. Just remember that the environment's arguments become additional arguments to the \verb"\begin", and all the rules given in Section~\ref{command-names} apply. Environments can be \index{nesting environments} nested in the obvious way. For example, figures \index{figures} are made by the {\tt figure} \index{figure environment} environment. To make a figure that contains an itemized list, you type: \begin{verbatim} \begin{figure} ... \begin{itemize} ... \end{itemize} ... \end{figure} \end{verbatim} In fact, your entire document is produced by a {\tt document} \index{document environment} environment---that's what the \verb"\begin{document}" and \verb"\end{document}" commands are for. Each environment has rules about what other environments may appear inside it. For example, the {\tt document} \index{document environment} environment can't contain another {\tt document} environment, so you'll only have one \verb"\begin{document}" command in your file. \verb"\begin" and \verb"\end" commands have to come in matched pairs, just like curly braces. Forgetting an \verb"\end" is a common error that your text \index{text editing} editor should help you avoid. Mine produces a matching \verb"\begin"--\verb"\end" pair with a single command. A few environments have {\tt *}-forms. For example, if you're producing two-column \index{two-column output} output, the {\tt figure} environment makes a figure that's one-column wide and the {\tt figure*} \index{figure* environment} environment makes a two-column-wide figure. To use the {\tt figure*} environment, you type \begin{verbatim} \begin{figure*} ... \end{figure*} \end{verbatim} Notice that the {\tt *} becomes part of the environment name. It does {\it not\/} act like an optional argument, as in ordinary commands. \subsubsection*{Declarations} \index{declarations} \label{decls} A {\it declaration\/} is a command that causes \TEX{} to change the way it's doing things. For example, the \index{!bf}\verb"\bf" command tells \TEX{} to start using {\bf \index{boldface}boldface type, as I just did by typing} \begin{verbatim} ... using \bf boldface type, as I just did by ... \end{verbatim} Note how \TEX{} typeset everything after the \verb"\bf" command in boldface. How did I get \TEX{} to stop using the bold typeface and revert to its normal \index{roman} typeface? For the answer, you first have to understand the concept of \index{nesting}nesting. As \TEX{} processes your input, it can best be thought of as traveling through the levels of a subterranean building. \TEX{} starts out at street level. Every time it encounters a \xsp{}\verb"{"\xsp{} or a \xsp{}\verb"\begin"\Xsp, \TEX{} goes down a flight of \index{stairs}stairs to the next lower level, and every time it encounters a \xsp{}\verb"}"\xsp{} or an \xsp{}\verb"\end"\xsp{} it goes up a flight of stairs to the next higher level. Thus, it remains underground from the time it hits your \verb"\begin{document}" command until it reaches the \verb"\end{document}". Every time \TEX{} descends a flight of stairs, it paints on them what led it down those steps, painting either a \xsp{}\verb"{"\xsp{} or a \xsp{}\verb"\begin"\xsp{} command, and covering over anything that what was previously painted there. When it next ascends those steps, it must have been directed to do so by the corresponding \xsp{}\verb"}"\xsp{} or \xsp{}\verb"\end"\Xsp. If it had painted \verb"\begin{itemize}" on the steps, it can only be directed up them by an \verb"\end{itemize}", not by a \xsp{}\verb"}"\xsp{} or an \verb"\end{figure}". Thus, you can't type \begin{verbatim} \begin{figure} { ... \end{figure} } is wrong! \end{verbatim} because the \verb"\end{figure}" would cause \TEX{} to try walking up a flight of steps painted with a \xsp{}\verb"{"\Xsp. The braces that enclose an argument are somewhat different from other braces. In almost all cases, the braces enclosing an argument of a \LATEX{} command cause \TEX{} to go down a flight of steps to start processing the argument, and back up the steps when it's through. So, when \TEX{} encounters the command \verb"\mbox{arg}", it's at a lower level when processing the {\tt arg} than it is before and after the command. As explained in Section~\ref{defcom}, when you define your own commands, you can choose whether or not the argument braces should cause \TEX{} to change levels. A declaration normally stays in effect as long as \TEX{} remains at or below the current level. As soon as \TEX{} returns to the next higher level, it forever forgets about the declaration. The region in which a declaration is in effect is called its \index{scope}{\it scope}. We can produce a single {\bf bold} word by typing \verb"{\bf bold}" because the scope of the \verb"\bf" declaration ends with the right brace. The following input shows how \TEX{} reacts to a \verb"\bf" declaration, assuming that it begins when \TEX{} is producing output in a Roman typeface. \begin{verbatim} This is Roman. {Still Roman. \bf Start boldface \begin{itemize} ... boldface ... \end{itemize} Still boldface.} Back to Roman. {Still Roman.} \end{verbatim} One declaration can be superceded by a countermanding declaration. The \xsp{}\verb"\bf"\xsp{} declaration in our example superceded a prior declaration that told \TEX{} to use a Roman typeface. The \xsp{}\verb"\bf"\xsp{} declaration can in turn be superceded by another typeface declaration, such as \xsp{}\verb"\it"\index{!it}\Xsp, which tells \TEX{} to use an italic\index{italic} typeface. Adding an \xsp{}\verb"\it"\xsp{} command to the previous example gives the following. \begin{verbatim} This is Roman. {Still Roman. \bf Start boldface \begin{itemize} ... boldface. \it Start italic ... \end{itemize} Back to boldface.} Back to Roman. {Still Roman.} \end{verbatim} Note that the \verb"\end{itemize}" ends the scope of the \xsp{}\verb"\it"\xsp{} command, but leaves \TEX{} within the scope of the \xsp{}\verb"\bf"\Xsp. Any declaration \index{declarations as environments} can be used as an environment---you just remove the \xsp{}\verb"\"\xsp{} to get the environment name. For example, you can type \begin{verbatim} \begin{bf} A bold sentence.\end{bf} \end{verbatim} The environment is the scope of the \verb"\bf" command, so this is equivalent to typing \begin{verbatim} {\bf A bold sentence.} \end{verbatim} You should use the {\tt bf} environment when one or more paragraph are all in boldface, since you'll probably find it hard to keep braces matched properly when they're far apart. Some environments make changes within them that supersede declarations made outside the environment. These will be mentioned when the environment is explained. Some declarations are \index{global declarations}{\it global}, meaning that they remain in effect even when \TEX{} climbs above its current level. These are generally declarations whose effects you would not expect to end with the current environment. For example, page \index{page numbering} numbering is outside the province of environments and normal scoping, so a declaration like \index{!pagenumbering}\verb"\pagenumbering{roman}", which causes \LATEX{} to number the current page i, the next page ii, and so on, is global. \subsubsection*{Page-Breaking and Line-Breaking Commands} This is a small class of commands that tell \TEX{} where to end a page or a line, or where not to end it. \subsubsection*{Indirect Commands} \index{indirect commands} This class is a mixed bag of commands that have one thing in common: they don't have any direct effect on \TEX's output. For example, Section~\ref{sectioning} describes an indirect command for adding a table of \index{table of contents} contents entry with the current page number. Executing it has no effect on what is produced during the current execution---\TEX{} probably generated the table of contents before seeing the command. However, the next time you run your file through \LATEX, the entry will magically appear in the table of contents. An indirect command is sometimes placed right in the middle of a paragraph, usually between words. When this happens, you're faced with the question of whether to leave a \index{space, around an indirect command} space on each side of the command, or to attach the command to one of the two adjoining words. Usually it makes no difference. However, sometimes you may wind up with an extra space between the words, or, less often, with no space between them. When that happens, it will be obvious what you should do to correct the situation. However, by the time you see your output, you'll probably have forgotten all about the indirect command and all you'll see is the extra space. When that happens, remember to look at the input to see if there's an indirect command causing the problem. An extra space is removed by attaching the command to either of the adjacent words. A missing space is usually corrected by adding a space before the command. \section{Modes} \index{modes} \label{modes} When \TEX{} is processing your input text, it is always in one of three {\it modes}: \begin{itemize} \item Paragraph \index{paragraph mode}mode \item Math mode\index{math mode} \item Left-to-right \index{left-to-right mode} mode, called LR \index{LR mode} mode for short. \end{itemize} \TEX{} changes mode only when it goes up or down a staircase to a different level, though not all level changes produce mode changes. Mode changes occur only when entering or leaving an environment, or when \TEX{} is processing the argument of certain text-producing commands. The description of each environment and text-producing command describes whether it causes a mode change. Paragraph mode is the most common; it's the one \TEX{} is in when processing ordinary text. In that mode, \TEX{} breaks your text into lines and breaks the lines into pages. \TEX{} is in math mode when it's generating a mathematical formula---you'll learn about that in Section~\ref{math}. Before getting to LR mode, I must explain a bit more about how \TEX{} processes text. As I explained in Section~\ref{input-file}, the input to \TEX{} is a string of characters. \TEX's output is a sequence of pages, each page consisting of a sequence of lines and vertical spaces, and each line consisting of a sequence of characters and horizontal spaces. To distinguish the printed representation of a character from the input character, I will call the former a \index{glyph}{\it glyph}. Thus, the character \xsp{}{\tt t}\xsp{} in your input file might generate any one of the following glyphs in the printed output. \begin{quote} t \ \ {\bf t} \ \ {\it t\/} \ \ {\Large t} \end{quote} In paragraph mode, \TEX{} translates each ordinary printing character into the corresponding glyph and translates \xsp{}\index{!!sp}\verb*" "\xsp{} and \index{!!carrtn}\carrtn{} characters into horizontal spaces---except when they end a paragraph. \TEX{} regards each string of glyphs as a word, and it breaks the text into lines of words, with space between them. If necessary, it will hyphenate \index{hyphenation} words to keep the spaces between them from getting too large. Text-producing \index{text-producing commands} commands generate glyphs and/or spaces. Typing \verb"\today" today (\today) produces exactly the same sequence of glyphs and spaces as typing \begin{quote} {\tt \today} \end{quote} \TEX{} could start a new line between the day and the year. However, some text-producing commands produce a \index{box}{\it box\/}, which is a chunk of text that \TEX{} treats exactly like a single glyph. One such command is \index{!mbox}\verb"\mbox". Typing \begin{verbatim} \mbox{no way} \end{verbatim} tells \TEX{} to make a box with ``\mbox{no way}'' inside it. Just looking at the output, there's usually no way of knowing that I used an \xsp{}\verb"\mbox"\xsp{} command instead of simply typing \xsp{}\hbox{\tt no way}\Xsp. However, the output is a lot different to \TEX{}. \TEX{} regards the box produced by a \xsp{}\verb"\mbox"\xsp{} command as if it were a single glyph, so the command \begin{verbatim} \mbox{no way} \end{verbatim} produces something that looks to \TEX{} like \begin{quote} \fbox{no way} \end{quote} There's no way that \TEX{} can split \fbox{no way} across two different lines, just as there is no way for it to split the glyph \xsp{}{\it A\/}\xsp{} into two pieces. So, if you want keep \TEX{} from splitting something across lines, just use the \xsp{}\verb"\mbox"\xsp{} command to put it in a box. Now let's return to LR mode. The canonical example of when \TEX{} is in LR mode is while it is processing the argument of an \verb"\mbox" command. In LR mode, as in paragraph mode, \TEX{} considers the output that it produces to be a string of words with spaces between them. However, unlike paragraph mode, \TEX{} keeps going from right to left; it never starts a new line in LR mode. Even if you put a hundred words into an \verb"\mbox", \TEX{} would keep typesetting them from left to right inside a single box, and then complain because the resulting box was too wide to fit on a line. \TEX{} is in LR mode when it starts making a box with an \verb"\mbox" command. You can get it to enter a different mode inside the box---for example, you can make it enter math mode to put a formula in the box. There are also several text-producing commands and environments for making a box that put \TEX{} in paragraph mode. The box made by one of the commands or environments will be called a \index{parbox}{\it parbox}, named after \verb"\parbox"\index{!parbox}, the exemplar of these commands. When \TEX{} is in paragraph mode while making a box, it is said to be in \index{inner paragraph mode}{\it inner\/} paragraph mode. Its normal paragraph mode, which it starts out in, is called \index{outer paragraph mode}{\it outer\/} paragraph mode. There are some things, like making footnotes\index{footnotes}, that \TEX{} can do in outer paragraph mode but not in inner paragraph mode. I'll warn you about them as we go along. While we're on the subject of boxes, I should mention that sometimes you'll want to make a great big box and stick it on its own line. If you leave a blank line before and after the box, \TEX{} will view it as if it were a one-character paragraph. However, remember that you must use a \verb"\noindent"\index{!noindent} command if you don't want the paragraph indentation. \section{Getting Fancier} Section~\ref{simple-text} told you how to produce simple output. Most of the rest of this manual is about how to produce fancier output. The purpose of this section is to help you find what you need. The first place to look for something is in the table \index{table of contents, using} of contents. Suppose you want to write \index{theorems}theorems and would like an environment to format them for you. Scanning through the table of contents quickly reveals that Section~\ref{theorems} is the place to look. However, you shouldn't go right there. The information in this manual is tree-structured. Section~\ref{theorems} is a subsection of Section~\ref{simple-par}, which is a subsection of Section~\ref{paragraph-making}. Before reading Section~\ref{theorems}, you should read the introduction to Section~\ref{paragraph-making} and the introduction to Section~\ref{simple-par}. The introduction to a section is everything from the beginning of the section until the beginning of its first subsection, so the introduction to Section~\ref{simple-par} starts at the beginning of that section and ends at the beginning of Section~\ref{simple-par}.1. To use a command or environment, you may have to understand other things about \LATEX. I assume that you know everything in this chapter---especially the material in Section \ref{commands} and \ref{modes}. When knowledge of other material is required, I will tell you where to find that material. The introduction to each section tells you what's in that section. If you think you might need a paragraph-making environment, but don't know what kind, you should read the introduction to Section~\ref{paragraph-making}. If the table of contents doesn't help, you might can try the \index{index, using}index. However, the index is designed to help you find information about a specific topic like footnotes, not to tell you what features \LATEX{} provides. Chapter~\ref{basics} contains the more elementary commands---the ones you're likely to use right away. The environments and commands of this chapter generally allow \LATEX{} to handle the formatting, under the control of the document style. Chapter~\ref{doit} contains commands and environments that allow you to control exactly how things are formatted, as well as commands for changing document-style parameters. Chapter~\ref{two-column}, which discusses two-column output, should really be part of Chapter~\ref{doit}. However, I wanted to show you an example of two-column output, and it's hard to produce just part of a chapter in that format. Chapter~\ref{bigger} describes commands that you won't need until you start producing larger documents. These include commands for splitting your input into several files, and cross-referencing commands. Finally, Chapter~\ref{errors} will help you cope when something goes wrong. \section{Running \LATEX{}}\index{running !!latex} You now know how to prepare an input file; it's time to learn how to run \LATEX{} on that file. Let's suppose that you've created an input file named \index{myfile.tex}{\tt myfile.tex}, you've checked that there are no unmatched curly braces, and you're ready to run it and see what happens. I'd like to tell you that your file will sail through \LATEX{} and produce beautiful output, but the chances of that happening on the first try are rather slim. Your input file will almost certainly contain \index{errors}errors, so you must be prepared to deal with them. To give you some idea of what you'll run into, we'll try the short input shown in Figure~\ref{fig:rn}. \begin{figure} \begin{verbatim} \pagelayout{normal} \documentstyle{article} \begin{document} Look at this \begin{simple} error. And at this \parbox{nasty} one. Is there a little town in Wales called Llegharffysloughlarwaghaurllysgnforghallyl? \end{document} \end{verbatim} \caption{The file {\tt myfile.tex}.\label{fig:rn}} \end{figure} Note that it has two errors: there's a spurious \verb"\begin{simple}" command, and the \verb"\parbox" command is missing one of its mandatory arguments. The first thing we must do is start the \LATEX{} program. On my computer, I do this by typing {\tt latex}\carrtn{}, but you may have to type something else on yours. It all depends upon what operating \index{operating system} system you're using. \LATEX{} starts by typing \index{**}{\tt **}, which is its way of asking for the name of the input file. Since our file is named {\tt myfile.tex}, we respond by typing \index{myfile}{\tt myfile}\carrtn{}. \LATEX{} then types out the following bunch of junk. (It may type something a little different on your computer.) \begin{footnotesize} \begin{verbatim} This is TeX, Tops-20 Version 1.0 (preloaded format=lplain 84.02.07) (PS:MYFILE.TEX.4 LaTeX Version 2.0 - Release 7 Feb 84 (PS:NORMAL.PLO.2 Page Layout 'normal' -- version of 21 Mar 1984. ) (PS:ARTICLE.STY.65 Document Style 'article'. Version 1.0 - released 8 Jun 1984 ) No file myfile.aux. \end{verbatim} \end{footnotesize} We needn't worry about any of this, it's just \LATEX's way of saying hello. The first time you run \LATEX{} on your system, it's a good idea to check that the version number it types is 2.0. If it isn't, then the version of \LATEX{} you're running is different from the version described in this manual, and you should ask a local expert if there are any important changes that you should know about. The `{\tt No file myfile.aux}' message appears the first time we run \LATEX{} on {\tt myfile.tex}. Afterwards, a file named {\tt myfile.aux} \index{.aux file} will appear in our directory. As explained in Section~\ref{xref}, the file {\tt myfile.aux} is used to implement \LATEX's automatic \index{cross-referencing}cross-referencing feature. Since we're not doing any cross-referencing, this file is totally useless. If we don't delete it, then the next time we run the file through \LATEX{}, that message will be replaced by: \begin{footnotesize} \begin{verbatim} (PS:MYFILE.AUX.1 ) \end{verbatim} \end{footnotesize} The next thing that \LATEX{} types is much more important; it's the error message for the spurious \verb"\begin{simple}" command. Before we look at it, I should explain the precise relation between \LATEX{} and \TEX. Most of the commands \index{commands, latex versus tex} that you use are \LATEX{} commands, which means that they were defined by me in terms of more primitive \TEX{} commands. \LATEX{} makes some effort to catch errors, but it won't catch them all. (It would slow \LATEX{} down too much to do a lot of error checking.) If \LATEX{} misses an error, \TEX{} will probably catch it. Unfortunately, it will appear to \TEX{} as an error in one of the \TEX{} commands that I wrote that implements the \LATEX{} command you typed. Keeping all this in mind, let's look at what's typed out when the \verb"\begin{simple}" command is encountered. \begin{footnotesize} \begin{verbatim} LaTeX error. See LaTeX manual for explanation. Type H for immediate help. ! Environment simple undefined. \@latexerr ...for immediate help.}\errmessage {#1} \endgroup l.4 Look at this \begin{simple} error. ? \end{verbatim} \end{footnotesize} The first two lines of this message tell us that we're in luck---the error was detected by \LATEX{} before any lower-level \TEX{} errors occurred. The next line, beginning with the \xsp{}{\tt !}\Xsp, is called the {\it error \index{error indication line}indication\/} line. It tells us what the problem is. Section~\ref{latex-errors} gives a list of all \LATEX{}-generated error indications, and tells you how to find out exactly what caused them. In this case, the problem is simple---there's no such environment as {\tt simple}. After the error indication line, there is a bunch of stuff that will be quite meaningless to you and should be ignored. (If you're curious, you'll have to read \knuth\index{texbook} to find out what it all means.) After it comes a pair of lines called the {\it error \index{error locator}locator}, followed by a line containing only a question \index{question mark} mark. In this message, the error locator begins with {\tt l.4}. The error locator tells us how much of our input \TEX{} had read when the error was discovered. The {\tt l.4} says that the error was found when processing the fourth line of our input. Following the {\tt l.4}, \TEX{} types input line four, split into two lines. Where the split occurs tells us exactly how far \TEX{} had gotten when it discovered the error---the first line showing what \TEX{} had read and the second line showing what it hadn't. In this case, the error was discovered right after \TEX{} read the \verb"\begin{simple}" command. An error locator might consist of a single line followed by a blank line, meaning that \TEX{} had read everything on the line before finding the error. The error locator might also be completely blank, indicating that \TEX{} discovered the error when it was processing a blank input line. The final line of the message, the one consisting of the question mark, tells us that \TEX{} has stopped and is waiting for us to tell it what to do. We'll accept \LATEX's offer of help and type \xsp{}{\tt H}\carrtn. It responds with the following helpful message. \begin{footnotesize} \begin{verbatim} Your command was ignored. Type I to replace it with another command, or to continue without it. ? \end{verbatim} \end{footnotesize} The question mark at the end again tells us that \TEX{} has stopped and wants us to type something. Since there's nothing that we want to replace the \verb"\begin{simple}" command with, we'll just type \carrtn{} and let \LATEX{} proceed. The next message we get is caused by the error in the \verb"\parbox" command. \begin{footnotesize} \begin{verbatim} ! Missing number, treated as zero. n n asty \@iparbox ...true $\vcenter \fi \fi \fi {\hsize #2 \@parboxrestore #3}\if@pbo... l.5 And at this \parbox{nasty} o ne. ? \end{verbatim} \end{footnotesize} \noindent The absence of the `{\tt LaTeX Error}' at the beginning tells us that the error was detected by \TEX{} instead of \LATEX. \TEX's error-handling mechanism doesn't know anything about \LATEX{} commands, so we can't expect much help from the the error indicator line. Some common \TEX{} error indicators and their causes are listed in Section~\ref{tex-errors}, so you can try looking there for help. You can also type \xsp{}{\tt H\carrtn}\xsp{} and see what advice \TEX{} gives you, but most of the time it won't be too helpful. Right now, let's see what we can discover by ourselves. As usual, we can ignore everything between the error indicator and the error locator. The error locator tells us that the error was detected right after \TEX{} read the {\tt o} that followed the \verb"\parbox" command. As this example shows, \TEX{} can go past the point where the real error is before it discovers that something is wrong. Fortunately, it didn't go very far, and we have the incorrect \verb"\parbox" command displayed before us. Unfortunately, there's nothing we can do about it now. At this point, you may be tempted to stop \LATEX{}, correct the errors, and try again. Don't. You should always let \LATEX{} go as far as it can in your file before giving up. Whenever you find one error there are probably several more beyond it, so you should find as many as you can each time you run \LATEX. To let \LATEX{} continue, we type \carrtn{}. We then get the following error message. \begin{footnotesize} \begin{verbatim} ! Illegal unit of measure (pt inserted). n n asty \@iparbox ...true $\vcenter \fi \fi \fi {\hsize #2 \@parboxrestore #3}\if@pbo... l.5 And at this \parbox{nasty} o ne. ? \end{verbatim} \end{footnotesize} Once again, this message was generated by \TEX{} rather than \LATEX{}, so we can ignore everything but the error locator. It tells us that \TEX{} hasn't gotten any further; it's at the same place in our input where it was the last time. \TEX{} found something else wrong when processing the incorrect \verb"\parbox" command. Undaunted, we type \carrtn{} and carry on. \TEX{} next types the following message. \begin{footnotesize} \begin{verbatim} Overfull \hbox (68.3333pt too wide) in paragraph at lines 5--5 []\tenrm nastyo \hbox(6.19444+1.94444)x0.0 .\hbox(0.0+0.0)x40.0 .\tenrm n .\tenrm a .\tenrm s .\tenrm t .etc. \end{verbatim} \end{footnotesize} \noindent This is a warning \index{warning message} message rather than an error message. There's no question-mark line, so \TEX{} is still running. The fact that it's warning us about something at ``{\tt lines 5--5}'' gives us a clue that the problem was probably caused by the bad \verb"\parbox" command, and the presence of the word ``nasty'', the argument of that command, in the message confirms our suspicions. \TEX{} is telling us that our incorrect \verb"\parbox" command produced some bad-looking output, which isn't surprising. The next thing that \TEX{} types is the following: \pagebreak[3] \begin{footnotesize}\label{running-ex} \begin{verbatim} Overfull \hbox (1.94412pt too wide) in paragraph at lines 7--9 []\tenrm Is there a lit-tle town in Wales called Llegharffys-lough-lar-waghau-r llysgn- \hbox(6.94444+1.94444)x340.0, glue set - 1.0 .\hbox(0.0+0.0)x40.0 .\tenrm I .\tenrm s .\glue 3.33333 plus 1.66666 minus 1.1111 .\tenrm t .etc. \end{verbatim} \end{footnotesize} \noindent This is also a warning---in fact, the same kind of ``\verb"Overfull \hbox"'' \index{overfull !hbox} warning we saw above. You'll see a lot of these warnings. They happen when \TEX{} can't find a good way to break a \index{line breaking} paragraph into lines, so it gives up and leaves a line sticking out in the margin. Section~\ref{line-breaking} on page~\pageref{line-breaking} tells you how to deal with this problem. Another warning you're likely to see is an `\verb"Underfull \vbox"' message. It occurs when \TEX{} can't find a good place to start a new \index{page breaking} page. You needn't worry about this warning, but you should check Section~\ref{page-breaking} on page~\pageref{page-breaking} if, when you look at the output, you're not happy with \TEX's page breaking. Other warning messages are explained in Chapter~\ref{errors}. While we've been pondering this message, \LATEX{} has continued processing the input file, printing: \begin{footnotesize} \begin{verbatim} [1] (PS:MYFILE.AUX.2) \end{verbatim} \end{footnotesize} \noindent \TEX{} typed the {\tt [1]} right after producing the first page of output. Had there been a second page, it would have typed {\tt [2]} immediately after that page was produced. Of course our tiny file produced only a single page, but you should pay attention to those numbers when you're running \LATEX{}; they'll help you correlate the error messages on your terminal with the printed output. The `{\tt (PS:MYFILE.AUX.2)}' can be ignored, but it does tell you that \TEX{} has reached your \verb"\end{document}" command and is now finishing up. \TEX's final words to us are: \begin{footnotesize} \begin{verbatim} Output written on PS:MYFILE.DVI.2 (1 page, 392 bytes). Transcript written on PS:MYFILE.LST.2. \end{verbatim} \end{footnotesize} They tell us that the output was written on a file called {\tt myfile.dvi}, and \index{.dvi file}that everything \TEX{} typed out on our terminal plus some additional information was also written on the file \index{.lst file} {\tt myfile.lst}. We didn't bother writing down all the error information that was typed because it will be waiting for us on this ``{\tt .lst}'' file. We've finished running \LATEX, but we still haven't seen our output. At the moment, it's just sitting on the file {\tt myfile.dvi}. We have to run some other program to actually print it. Exactly how this is done depends upon your particular computer system, so you'll have to ask a local expert what to do next. \yspace In this example, things went pretty smoothly. Even though there was a nasty error (the missing \verb"\parbox" argument), we could get \TEX{} to continue past it by typing \carrtn{} after the two error messages. A single error can easily generate five or ten error \TEX{} messages. Sometimes \TEX{} gets so confused by an error that it either won't go any further, producing error after error with the same error locator, or else it starts thinking that almost everything is an error. If that happens, you'll have to correct the error and rerun \TEX{} in order to get any further. The best way to stop \index{stopping latex} \LATEX{} after an error is to type \verb"I \stop"\carrtn{} in response to its question mark. If that just produces another error message, then you should type {\tt X}\carrtn; this will always cause \TEX{} to quit. \TEX{} will produce a {\tt .dvi} file with the output that was generated so far, as well as a {\tt .lst} file with all the error messages. \TEX{} may stop without any error message, simply typing a \index{*}{\tt *}. The most likely cause of this is a missing \index{!end{document},missing}\verb"\end{document}" command, but other errors can also have this result. If it happens, you should type \index{!stop}\verb"\stop"\carrtn. If that doesn't work, you'll have to stop \TEX{} by whatever means your operating system provides for halting uncooperative programs. Even experienced \LATEX{} users are sometimes mystified by an error. When that happens to you, the most important thing to remember is \begin{center} \Large DON'T PANIC.\vspace{.1in} \end{center} Instead, turn to Chapter~\ref{errors} to find out what to do. \section{Some Words of Advice} A major goal of \LATEX{} is to allow you to change the way your document is formatted by changing a few declarations without having to change the text itself. However, no matter how much one tries, changing the format may require some changes to the text. You can change the width of your lines with a single declaration, but, if you make the lines too narrow, you may have to change some things that no longer fit on a single line. The proper use of \LATEX{} allows you to minimize the number of changes that have to be made to your text when you reformat it. When you tell \LATEX{} how to print a recipe, you'll probably specify how far the list of ingredients should be indented from the left margin. You could give the distance in inches, but you might have to change that distance if you changed the line width. A better method would be to specify the distance as a certain fraction of the line width, so the same \LATEX{} commands would produce the right indentation regardless of the line width. An \label{advice} even better way to avoid having to change the text of your recipes when changing the format is to define \index{commands,defining} a \verb"\recipe" command, using the \index{!newcommand}\hbox{\verb"\newcommand"} command described in Section~\ref{defcom}. That way, you just have to change the definition of the \verb"\recipe" command to change how every recipe is printed; you never have to change the individual recipes. Whenever your document contains a special class of objects like recipes, you should define a command to generate them. This will usually save you a lot of typing, since you don't have to repeat the formatting commands every time. However, even if it doesn't, you should still define a command to generate these objects because that makes it easier to change how they are formatted. Defining a command \verb"\hoare"\index{!hoare} so that \begin{verbatim} \hoare{P}{S}{Q} \end{verbatim} produces \begin{quote} $\{P\}\,S\,\{Q\}$ \end{quote} doesn't save any typing. But, if you decide that there should be more space in the expression, so it looks like \begin{quote} $\{\,P\,\}\;\,S\;\,\{\,Q\,\}$ \end{quote} then only the definition of \verb"\hoare" has to be changed; you don't have to change every occurrence of the notation. The experienced \LATEX{} user makes extensive use of its command-defining features. \yspace Another thing the experienced \LATEX{} user does is avoid wasting his time and his computer's time running \LATEX{} over and over again with the same input. Documents, except for very short ones, are written a little bit at a time. You'll naturally want to see \LATEX's output as you produce the input. However, after you write the first ten pages and get \LATEX{} to print them for you, it's silly to keep regenerating those ten pages every time you write some more input. It's especially silly to wait while \LATEX{} processes those ten pages again in order to find the errors in your new input. You should always run \LATEX{} on new input by itself, without any of the old input. Only after there are no more errors in the new input should it be added to the old. If it's fairly short, then the entire document might be processed by \LATEX{} every time you add new text. For a larger document, you should use the methods described in Section~\ref{parts} to avoid this reprocessing.