\chapter{Getting Started} There are three steps in generating a document with \LATEX: \begin{enumerate} \item Preparing a manuscript\index{manuscript} file. \item Running the manuscript file through \LATEX. \item Printing \LATEX's output file. \end{enumerate} This manual is mostly about the first step, though Section~\ref{running-latex} briefly discusses the second two steps. I assume that you know how to prepare a file with a text editor, so I'll tell you only what should go into the manuscript file, not how to get it there. There is one important thing about text files that you may not be aware of. A text file is a string of characters. When you type it out, or look at the file on your screen, it appears to be a series of lines. This is because there is a special character called {\it carriage return\/}\index{carriage return} that appears between the lines. When you created that file, you probably entered those carriage return characters in your file by hitting the key marked {\it return\/} on your terminal. You should realize that these carriage return characters are in your manuscript file, and that \TEX{} regards them as a full-fledged characters, usually treating them like spaces\index{space}---the characters that are usually printed as blank spaces, which you enter by hitting the space bar on your keyboard. Before getting to our main subject, a word about text preparation is in order. To get a document formatted properly, you have to tell \LATEX{} what you want. This involves typing a lot of formatting commands. The names of commands that aren't used very often have been chosen for clarity rather than brevity. If you want, you can define your own abbreviation for any command name. Even a command with a short name can require a lot of typing if it is used very often. For example, a boldface word like ``{\bf bold}'' is produced by typing \hbox{\tt \{\\bf bold\}}. If you use a lot of boldface words, then these extra six characters (including the space after the {\tt f}) are a lot. 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, I type just one control character followed by {\tt bold} to produce \hbox{\tt \{\\bf bold\}}. If such an editor is not available on your computer, you should complain. \section{Commands} \label{commands}\index{commands} The manuscript file contains text to appear in the document plus \LATEX{} commands to specify how that text should be formatted. All \LATEX{} commands begin with the character {\tt \\}. %% } BRACE MATCHING This character, pronounced {\it backslash\/}, should not be confused with the more common {\tt /} character, as in ``1/2'' and ``and/or''. If the command takes arguments\index{argument}, they appear right after the command name and are enclosed in braces. Thus, you type {\tt \\documenttype\{report\}} to issue the command {\tt \\documenttype} with the argument {\tt report}. Don't leave any extra blank spaces in command arguments; typing {\tt \\documenttype\{report~\}} will cause an error. Although \TEX{} takes spaces inside an argument very seriously, it \index{space} adamantly refuses to pay attention to spaces after a command name. Thus, you can type \begin{example} \\documenttype \{report\} \end{example} or even \begin{example} \\documenttype \{report\} \end{example} (The carriage return is equivalent to a space.) This can cause trouble if the command does not take an argument, because all space between the command name and the next nonspace character is ignored. Most \LATEX{} commands are designed so that spaces don't get ignored when they shouldn't be, but in case you find space mysteriously disappearing after a command, just type {\tt \{\}} right after it.\footnote{There is one exception: effective with version~.96 of \TEX{}, spaces are not ignored after some command names consisting of {\tt \\} followed by %%%} BRACE MATCH HACK a single nonletter, like {\tt \\)}.} \TEX{} regards upper-case\index{case}\index{upper-case} and lower-case\index{lower-case} letters to be completely different. This means that you have to use the right case in all command names and arguments. \LATEX{} has adopted the convention that command names and arguments are lower-case, except when there are two related commands with names differing only in their case---as in {\tt \\sigma}\index{!sigma} and {\tt \\Sigma}\index{!Sigma}, which produce $\sigma$ and $\Sigma$, respectively, in mathematical formulas. \section{The Structure of the Manuscript File}\label{structure} The manuscript file has the following parts: \begin{list}{}{\itemsep{.2em}} \item {\tt \\pagelayout\{ ...\}}\index{page layout}\index{!pagelayout} \item {\tt \\documentstyle\{ ...\}}\index{document style} \index{!documentstyle} \item {\it processing commands\/}\index{processing commands} \item {\it your definitions\/}\index{definitions} \item {\tt \\text}\index{!text} \item {\it manuscript text\/} \item {\tt \\theend}\index{!theend} \end{list} These parts will be described in detail later on. Here, I'll tell you enough to get you started. The \hbox{\tt \\pagelayout}\index{!pagelayout}\index{page layout} command tells \LATEX{} what the dimensions of the output page should be. Its argument gives a page layout format followed by any options. The name of the format and of the options are separated by commas. Thus, to use a page layout called {\tt normal}, with the \hbox{\tt twoside}\index{twoside} option, you type \begin{example} \\pagelayout\{normal,twoside\} \end{example} (Remember, don't put spaces inside the braces.) You can also specify this with two separate commands by typing \begin{example} \\pagelayout\{normal\} \\pagelayout\{twoside\} \end{example} Page layout formats will vary from site to site; you'll have to ask someone what formats are available on your system. The \hbox{\tt \\documentstyle}\index{!documentstyle}\index{document style} command specifies what formatting commands are available and what they are to do. Its arguments are analogous to those of the \hbox{\tt \\pagestyle} command; to choose style {\tt preprt}\index{preprt} with options \hbox{\tt headinga} and {\tt draft}, you can type command \begin{example} \\documentstyle\{preprt,headinga,draft\} \end{example} or \begin{example} \\documentstyle\{preprt,headinga\} \\documentstyle\{draft\} \end{example} To understand what the document style definition does, suppose you want to start a new section entitled {\it Gnats and Gnus\/} in your manuscript. You would probably type the command \begin{example} \\section\{Gnats and Gnus\}\index{!section} \end{example} The document style specifies such things as whether the section starts on a new page, and in what type face the title is printed. The \hbox{\tt \\section} command might be undefined in some document styles, such as one for producing letters. Some standard document styles are described in Appendix~\ref{document styles} on page~\pageref{document styles}. The processing\index{processing commands} commands contain any special instructions for this particular execution of \LATEX{}. You won't be doing anything special for a while, so you won't be using any processing commands yet. However, there is one command you should know about that you may want to put in here; the \hbox{\tt \\typein}\index{!typein} command causes \LATEX{} to interrupt the processing of your manuscript file, type out a message, and ask you to type in one or more commands, which it then executes. (You end your input by typing a carriage return.) A typical use might be \begin{example} \\documentstyle\{report\} \\typein\{Enter documentstyle command for options, turkey.\} \end{example} which will prompt you and give you the chance to enter a \hbox{\tt \\documentstyle} command to specify options. Another use might be \begin{example} This is Version \\typein\{Type version number.\}. \end{example} You can put a \hbox{\tt \\typein} command in most places, but not in the argument of a command. The processing commands are followed by any definitions that you make. Section~\ref{definitions} on page~\pageref{definitions} describes how to define your own commands. Until you learn how to do this, there won't be anything in this part of your manuscript. The body of the document is begun with a {\tt \\text}\index{!text} command, and the whole man\-u\-script file is terminated by the command {\tt \\theend}\index{!theend}. \section{Typing Simple Stuff} For ``plain vanilla''\index{vanilla text} text, you can pretty much type what comes naturally---the rest is done for you. For example, the preceding sentence was produced by typing \begin{example} For ``plain vanilla'' text, you just type what comes naturally---the rest is done for you. \end{example} Spaces and carriage returns have no effect except to delimit words. Leaving a blank line causes \TEX{} to start a new paragraph. \TEX{} puts things where it thinks they should go, and pays no attention to how you spaced them in your manuscript file. To change the way \TEX{} formats your text, you have to type explicit commands that are described later. There are two nonobvious things to observe in the above example. The first is the way double quotes are obtained: left quotes are typed as {\tt ``} and right quotes as {\tt ''}. To get single quotes like `this', you type {\tt `this'}. The {\tt '} character is the usual typewriter single-quote character, and probably appears on your keyboard above a number. The {\tt `} character is usually represented as a right-pointing accent, and is probably hidden in some obscure spot on the keyboard. 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{example} ``this'', or ``that,'' \end{example} to produce ``this'', or ``that,'' as you prefer. The second thing to observe in the example is how typing {\tt \hspacer{.3em}---\hspacer{.3em}} produced a long dash\index{dash}. You can also get a short ``\hspacer{.1em}-\hspacer{.1em}'' dash by typing {\tt \hspacer{.3em}-\hspacer{.3em}}, and a medium-length ``\hspacer{.1em}--\hspacer{.1em}'' dash by typing {\tt \hspacer{.3em}--\hspacer{.3em}}. \TEX{} tries to put a little extra space after a sentence-ending period, but \index{space} not after a period that doesn't end a sentence. However, \TEX{} is only a program and it sometimes makes a mistake. For example, typing \begin{example} Euclid et. al. showed that I+I=II. Meanwhile, ... \end{example} causes \TEX{} to produce \begin{quote} Euclid et. al. showed that I+I=II. Meanwhile, \(\ldots\) \end{quote} \TEX{} thought that the periods after ``et'' and ``al'' ended sentences, and that the period after ``II'' didn't. If you want to know what \TEX's rules are, you can find them in Chapter 12 of \knuth. However, it's enough to know what to do when you find \TEX{} messing up like this. To correct the above example, you just type \begin{example}\index{! }\index{!hbox}%%% {{ BRACE MATCHING HACK Euclid et.\\{} al.\\{} showed that \\hbox\{I+I=II\}. Meanwhile, ... \end{example} to produce \begin{quote} Euclid et.\ al.\ showed that \hbox{I+I=II}. Meanwhile, ... \end{quote} You use a {\tt \\} %%% } BRACE MATCHING HACK followed by a space to get a normal space after a period, and you get a sentence-ending space by making the word before the period the argument of an {\tt \\hbox} command. Sometimes \label{percent}you may want to leave little notes to yourself in your manuscript file that you don't want printed. Typing \index{\string\%}{\tt \%}, tells \TEX{} to ignore everything else on the current line, including the carriage \index{carriage return}return at the end of the line. For example, you might type \begin{example} as what's his name\%{} Look up the name in Knuth's book\index{knuth} showed in 1976. \end{example} to produce \begin{quote} as what's his nameshowed in 1976. \end{quote} Whoops, you forgot that the {\tt \%} caused \TEX{} also to ignore the carriage return at the end of the line. Remember that next time; some day you might want to do that on purpose to end a manuscript line without putting space in the output. Most of the letters and characters that appear on an ordinary typewriter produce more or less what you'd expect them to. For example, typing {\tt +} produces +, and typing {\tt [} produces [\hspacer{.2em}. However, the following ten common typewriter symbols have special meanings for \TEX: \begin{quote} {\tt \#}\hspace{.6em}\index{\string\#} {\tt \$}\hspace{.6em}\index{\string\$} {\tt \~}\hspace{.6em}\index{\string\~} \%\index{\string\%}\hspace{.6em} {\tt \&}\hspace{.6em}\index{\string\&} \{\index{\string\{}\hspace{.6em} \}\index{\string\}}\hspace{.6em} {\tt \â??} (underscore)\index{underscore}\hspace{.6em} {\tt \\}\hspace{.6em}\index{\string\\} \char'017\relax{} %% } } BRACE MATCHING (caret)\index{caret} \end{quote} You can produce the first seven by typing a {\tt \\} %%%} BRACE MATCHING in front of them, typing {\tt \\\#} to get \#, {\tt \\\$} to get \$, and so on. The backslash and caret are seldom used in printed text, so \LATEX{} provides no simple way to produce them. In addition to the characters found on ordinary typewriters, many terminal\index{terminal} key\-boards\index{keyboard} have a variety of keys with strange and wonderful characters etched on them. Just because your terminal has a key labeled $\oprod$\index{\string\oprod}, don't expect to produce a $\oprod$ in your document with it; \TEX{} has no way of knowing how your keyboard is labeled. You can produce an assortment of nice symbols with \TEX{}, but you have to use special commands described in Section~\ref{symbols} on page~\pageref{symbols}. \section{Chapter and Verse} The first kind of special formats you'll probably want are chapter\index{chapters} and section\index{sections} headings. This couldn't be simpler. Chapters are begun with a {\tt \\chapter}\index{!chapter} command, having the chapter title as its argument. Thus, this chapter was begun with the command \begin{example} \\chapter\{Getting Started\} \end{example} \LATEX{} automatically started a new page, put in the chapter number, and put the title in its proper place. It also generated the table of contents\index{table of contents} entry for this chapter, but you'll have to see Section~\ref{tableofcontents} on page \pageref{tableofcontents} to find out how to make a table of contents. Sections are similarly begun with the {\tt \\section} command; this section was started with \begin{example} \\section\{Chapter and Verse\} \end{example} There are also {\tt \\subsection}\index{!subsection} and {\tt \\subsubsection}\index{!subsubsection} commands. An appendix\index{appendix} is begun with an \hbox{\tt \\appendix}\index{!appendix} command. The appendix has the same chapter and section structure as the main body of the document, but it is numbered differently. For example, the first ``chapter'' of the appendix in the {\tt report}\index{report document style} document style is labeled ``Appendix~A''. Exactly what the \hbox{\tt \\appendix} command produces is determined by the document style. Not all document styles have all these sectioning commands. In particular, the {\tt preprt} style does not have chapters, only sections, subsections and subsubsections, as well as appendix sections, {\it etc}. Document styles for producing letters\index{letters} do not have any sectioning commands. Most other formatting is done by using {\it environments\/}\index{environments}. There are many different environments, including an {\tt italic}\index{italic environment} environment for {\it italic\/} text, environments for mathematical formulas\index{formulas}, \begin{verse} And one environment,\CR It could be worse,\CR That you can use \CR For printing \index{verse environment}verse. \end{verse} These environments are described in the next chapter. The environments provided by the document style should do just about everything you need. However, sometimes you'll want to give \TEX{} explicit typesetting instructions, telling it to put some more space here, or to start a new page there. Commands for doing this are described in Chapter~\ref{telling}. \section{Footnotes}\index{footnotes} \label{footnotes} Typing footnotes is a snap with the {\tt \\foonote}\index{!footnote} command.\footnote{This was a snap.} For example, I just typed \begin{example} ... command.\\footnote\{This was a snap.\} For example, I just typed \end{example} Footnotes can be put in most sensible places. The following are the environments in which you {\it can't\/} put a footnote: a math \index{math environment}environment, a figure \index{figure} or table \index{table} \index{figure environment}\index{table environment}environment, another footnote, a \hbox{\tt tabular}\index{tabular environment} environment, or a \hbox{\tt tabbing}\index{tabbing environment} environment. You also cannot put a footnote inside a \index{boxes}box. (Boxes are discussed in Section~\ref{boxes}.) If you're using a document style like {\tt report}\index{report document style} in which footnotes are numbered consecutively within chapters, or one like {\tt preprt}\index{preprt} in which footnotes are numbered consecutively from the start of the document, then that's all you need to know. However, there may be document styles in which footnote numbering starts fresh on each page. Most of the time this will cause no problems, but sometimes \LATEX{} will foul up the footnote numbering on a page. If that happens, you'll have to use the \hbox{\tt \\nfootnote}\index{!nfootnote} command described in Section~\ref{nfootnote} on page~\pageref{nfootnote}. \section{Running \LATEX} \label{running-latex} After preparing your manuscript file, you must run the file through \TEX{}. Exactly how you do this will depend upon the computer system and the particular version of \LATEX{} you're using. You'll have to ask a local wizard what to do. \TEX{} always produces two output files: a {\tt dvi} file\index{dvi file} and a {\tt log} file\index{log file}. If your manuscript file is named \hbox{\tt gnu.tex}, then the {\tt dvi} file is named \hbox{\tt gnu.dvi} and the {\tt log} file is named \hbox{\tt gnu.log}. The {\tt dvi} file contains instructions for typesetting your document. You'll have to run it through another program to produce printed output, though on some systems \TEX{} will do this for you or set things up so you just type a carriage return to run that program. The {\tt log} file contains everything that \TEX{} typed out at you when it ran, and perhaps some extra information that probably won't interest you. If this is your first try at running the manuscript file through \TEX{}, the chances of its running without producing an error \index{error messages}\index{errors}message are infinitesimal. Moreover, \TEX{}'s error messages tell you what it objected to, not what your real mistake was---for example, it will tell you that you did something you weren't supposed to do in the current environment, but it doesn't know whether you forgot to end that environment or forgot to begin an inner environment. Sometimes you'll have to sweat a bit to figure out what went wrong, but most errors are easy to find and correct. So, let's see what you do when \TEX{} comes to a grinding halt with some error message. This error isn't likely to be the only one, and you'd like to discover the others before going back and correcting your files. So, you want to keep \TEX{} going if at all possible. \TEX{} will list the errors on the {\tt log} file; you don't have to record them. When \TEX{} discovers an error, it prints out a message followed by the prompt character {\tt ?}, and waits for a response. If you type a {\tt ?} followed by a carriage return, \TEX{} will respond by telling you all the options you have. Everything you type to \TEX{} must be followed by a carriage return, which I won't mention again. Typing {\tt h} causes \TEX{} to explain what it thinks happened. However, if the error was discovered by the \LATEX{} commands themselves, \TEX{} will reply to {\tt h} with a smart-assed reply telling you to figure the problem out yourself. Error messages generated by \LATEX{} are identified as such. In any case, you probably want to carry on by typing a carriage return, which tells \TEX{} to ignore the error and procede. Sometimes your error will get \TEX{} so confused that it can't do a sensible job of continuing, and will keep producing error messages. In this case, the best way to try to stop it is by typing \hbox{\tt i\\theend}, which will give you all the output generated up to that point. Unfortunately, this often won't work, and will just produce another error message. In that case, you can type {\tt x}, which will always get \TEX{} to stop but won't generate output for the page it was working on when the error occurred. In addition to error messages, at which it comes to a screeching halt, \TEX{} also produces various warning messages---usually telling you about an underfull \index{underfull} or overfull\index{overfull} {\tt \\hbox}\index{!hbox} or \index{!vbox}{\tt \\vbox}. These messages are discussed in Section~\ref{break}, as well as in Chapter~6 of \knuth. After you've pushed \TEX{} through your manuscript, you can examine the error messages in the {\tt log} file. An error message starts with a a notification of the type of error, which begins with a {\tt !}. It then contains information telling you what \TEX{} was doing when it encountered the error. If it was processing a command sequence, there will be a whole batch of stuff describing what was substituted for who when \TEX{} expanded the command's definition. This part of the message will end with the line of your input text containing the error. It gives its line number (counting from the beginning of your manuscript file) and then types it out on two lines, breaking after the last thing that \TEX{} processed. \LATEX{} and \TEX{} can produce a wide variety of error messages. All of \LATEX's error messages and some of \TEX's more common ones are explained in Appendix~\ref{errors}. By examining the input and reading the appropriate parts of this manual, you will usually be able to figure out what you did wrong. Appendix~\ref{errors} also lists a few common errors to check for.