\chapter{Getting Bigger} \label{bigger} A large document presents problems to both you and your reader. In preparing the document, you have the problem of breaking it into manageable pieces. Your reader has the problem of finding his way around the document. \LATEX{} helps solve your problem with commands that incorporate a number of different files into a single document, and allow you to choose which of them to process on any single execution of \LATEX. It helps solve your reader's problem by providing commands for \index{cross-referencing}cross-referencing---letting one part of the document point to another. You've probably noticed the many cross-references of the form \begin{quote} see Section~\ref{footnotes} on page~\pageref{footnotes}. \end{quote} There are are two other kinds of cross-references used in this manual: indexing and bibliographic citation. All the numbers in these cross-references---section, page and citation numbers---were generated by \LATEX{} using commands described in this chapter. The following sections describe how to break your document into parts and how to produce the various forms of cross-referencing. Section~\ref{aux} describes exactly how this is done, and explains why things work the way they do. You should consult this section if any surprises occur when using these features. Another feature that is especially useful for large documents is the ability to interact with \LATEX{} while it is processing your input. Section~\ref{typein} describes how this is done. \section{Doing it in Parts}\index{parts}\label{parts} A large document requires a large amount of input. It is inefficient to handle this input as a single large file; it's much better to split it into several smaller files. \LATEX{} provides two ways in which you can do this. Regardless of how many separate files you use, there is always one file that is the {\it main\/} \index{main file} file. This is the file whose name you give to \LATEX{}---the one we've been calling \index{myfile.tex}{\tt myfile.tex}. The simplest way to split your input into different files is with the \verb"\input"\index{!input@} command. The command \begin{verbatim} \input{gnu} \end{verbatim} in your main file causes \LATEX{} to insert the contents of the file {\tt gnu.tex} right at the current spot in your manuscript.\footnote{To maintain compatibility with standard \TEX, \LATEX{} allows you to leave out the braces around the file name, but there's no good reason to do so.} \LATEX{} acts as if the \verb"\input{gnu}" command were removed from the main file and replaced by the contents of the file {\tt gnu.tex}. Of course, \LATEX{} doesn't actually change your input files. The file {\tt gnu.tex} could also contain an \verb"\input" command, calling another file that could contain another \verb"\input" command, and so on. In addition to allowing you to split your input into convenient-sized chunks, the \verb"\input" command also makes it easy to use the same input in two or more documents. Although you'll seldom recycle text in this way, you might develop a library of \index{library of declarations} declarations that you use in many different documents. As you develop your own style of using \LATEX, you'll define a number of commands that you use in all your documents. You can write a single file, perhaps called {\tt mycmds.tex}, containing the \verb"\newcommand"\index{!newcommand} declarations (see Section~\ref{defcom}) that define these commands, as well as any other declarations you always use, and then put an \verb"\input{mycmds}" command in every main file. The file {\tt mycmds.tex} can even include the \hbox{\verb"\pagelayout"}\index{!pagelayout} and \hbox{\verb"\documentstyle"}\index{!documentstyle} commands, and you can begin your main file with \verb"\input{mycmds}". \yspace In the course of preparing a document, you'll often find yourself changing only small parts of it and wishing you could get \LATEX{} to produce only those pages that had changed, without having to process the entire input file again. With a little care, it's possible to get \LATEX{} to process any single page of your document by itself. This involves using the \verb"\noindent"\index{!noindent} command of Section~\ref{simple-text}, the page-breaking commands of Section~\ref{page-breaking}, and the renumbering commands of Section~\ref{counters}. (You'll also want to use the \verb"\nofiles"\index{!nofiles} command of Section~\ref{aux} when you do this.) It would be nice if \LATEX{} could do all that for you, allowing you to process only the page containing the changes. \LATEX{} can't because, in general, it's not possible. Adding one word to the first page could force the last word from that page onto the following page, creating a ripple effect that changes every page in the document. However, \LATEX{} does provide a mechanism for splitting your manuscript into pieces and processing the pieces separately as you revise them. The \verb"\include"\index{!include@}\index{!include'd files} command works like the \verb"\input" command described above in that the command \begin{verbatim} \include{gnu} \end{verbatim} tells \LATEX{} that the file {\tt gnu.tex} should be inserted here. However, it's possible to tell \LATEX{} not to process the file {\tt gnu.tex}, but to step all the counters\index{counters} it uses for numbering things, so subsequent text is processed as if file {\tt gnu.tex} had been processed. (See Section~\ref{counters} on page~\pageref{counters} for a discussion of counters.) To process only part of your document, you put an \verb"\includeonly"\index{!includeonly@} command in your main file, before the \verb"\begin{document}" command. The argument of the \verb"\includeonly" command is a list of file names, which are the only \verb"\include"'d files that \LATEX{} will process. Suppose your input file contains the command \begin{verbatim} \includeonly{gnu,gnat,gnash} \end{verbatim} When \LATEX{} comes to the command \begin{verbatim} \include{gnat} \end{verbatim} it will read in the file {\tt gnat.tex} as usual. However, when it comes to the command \begin{verbatim} \include{rmadlo} \end{verbatim} it will {\it not\/} read the file {\tt rmadlo.tex} because {\tt rmadlo} was not in the argument of the \verb"\includeonly" command. Instead, \LATEX{} will increment all appropriate counters so the following text will be treated exactly as if the file {\tt rmadlo} had been processed. Section~\ref{typein} on page~\pageref{typein} describes how you can get \LATEX{} to ask you what files to include, so you don't have to keep changing the \verb"\includeonly" command in your main file. This sounds too good to be true, and it is. \LATEX{} can't perform magic, and the following restrictions apply to the \verb"\include" command. \begin{enumerate} \item The text in the \hbox{\verb"\include"}'d file and the text that follows the \hbox{\verb"\include"} command must begin on new pages. More precisely, \LATEX{} executes a \hbox{\verb"\clearpage"}\index{!clearpage} command (described in Section~\ref{page-breaking}) immediately before and after executing the \hbox{\verb"\include"} command. (Remember that two \hbox{\verb"\clearpage"} commands in a row are the same as a single one, so \hbox{\verb"\include"}'ing an empty file is equivalent to executing a single \linebreak %%%%% \hbox{\verb"\clearpage"}.) You will usually put one or more complete chapters on a single \hbox{\verb"\include"}'d file. \item An \verb"\include"'d file must not contain an \verb"\include" statement. Thus, if your input file has an \begin{verbatim} \include{gnu} \end{verbatim} command, then the file {\tt gnu.tex} may not contain any \verb"\include" commands. However, {\tt gnu.tex} may contain \verb"\input" commands. \item An \verb"\include" command may {\it not\/} precede the \verb"\begin{document}" command. \end{enumerate} Remember that everything in your main file is always processed. If your main file does not have an \verb"\includeonly" command, then all the \verb"\include"'d files are processed. If your main file contains the command \begin{verbatim} \includeonly{} \end{verbatim} then all \verb"\include"'d files are skipped. The \verb"\includeonly" command has no effect on \verb"\input" commands; an \verb"\input" command always causes the specified file to be processed. (Of course, an \verb"\input" in an \verb"\include"'d file is executed only if that file is processed.) \yspace {\bf Warning:} Don't put any spaces in the argument of an \hbox{\verb"\include"} or \hbox{\verb"\includeonly"} command. \yspace \LATEX{} doesn't perform magic, so it can't know how many page or section numbers to skip for a file it has never processed it. \LATEX{} uses a very simple algorithm for setting its counters when it skips an \verb"\include"'d file, and it can produce incorrect numbering. A complete explanation of this algorithm is given in Section~\ref{aux} on page~\pageref{aux}. A simple description of how it works is contained in the following example. Suppose your main file contains \begin{verbatim} \include{gnus} \chapter{Gnats} \end{verbatim} and has an \verb"\includeonly" command that doesn't include {\tt gnu}, so \LATEX{} will skip this \verb"\include"'d file. Suppose also that the last time \LATEX{} actually processed the file {\tt gnu.tex}, the output it produced ended in Chapter~5 on page 37. The \verb"\chapter{gnats}" command will then begin Chapter~6 on page 38. This will be true even though you've added several chapters that produced 47 more pages of output before the \verb"\include" command. \LATEX{} will correctly skip over \verb"\include"'d files so long as an \verb"\include"'d file is always reprocessed whenever there is any change to the document before that \verb"\include" statement. Of course, the only changes that matter are ones that can affect the numbering. Minor modifications that don't add or delete chapters and don't change the number of pages cause no problems. What you'll probably find is that when you're working on a large manu\-script, you'll make each chapter a separate part. In the early drafts, you'll be satisfied with seeing each chapter by itself and won't worry about getting the page numbers to match properly. At some point, you'll put it all together and process the whole manuscript. Then, you'll work on individual chapters, processing each one separately. Since it takes a long time for \LATEX{} to process a long manuscript, you'll keep processing individual chapters by themselves until the numbering gets too far out of line, whereupon you'll run \LATEX{} on the entire document. \section{Index and Glossary}\index{index}\index{glossary} \label{the-index} Creating an index or a glossary is not easy, and no completely automatic system will do a very good job of it. \LATEX{} doesn't even try; all it does is write a file containing the information you'll need to do it yourself. If your input file is {\tt myfile.tex}\index{myfile.tex}, then the index information will be written on the file {\tt myfile.idx}\index{.idx file}\index{index file}. When you want an item to appear in the index, you write a command like\index{!index@} \begin{verbatim} \index{A. A. Dillo} \end{verbatim} in the text to which the index entry should point. If \LATEX{} decides to produce an index file for you, it will write the line\index{!indexentry@} \begin{verbatim} \indexentry{A. A. Dillo}{37} \end{verbatim} on the {\tt .idx} file, telling you that the item appeared on page~37. If the item appears on page~xxxvii, it will write \begin{verbatim} \indexentry{A. A. Dillo}{xxxvii} \end{verbatim} The \verb"\index" command does not produce any text. If you want to index an appearance of the word ``gnat'', you'll have to type something like \begin{verbatim} gnat\index{gnat} \end{verbatim} See Section~\ref{defcom} on page~\pageref{defcom} to find out how you can avoid having to type {\tt gnat} twice. Although you'll be putting \verb"\index" commands in your document as you write it, you won't want to produce an index until the document is finished. \LATEX{} won't write an \xsp{}{\tt .idx}\xsp{} \index{.idx file, producing} file unless you put a \hbox{\verb"\makeindex"}\index{!makeindex@} command in your input file. This command should go before the \verb"\begin{document}". Section~\ref{aux} on page~\pageref{aux} describes in more detail exactly when the \xsp{}{\tt .idx}\xsp{} file is produced. \LATEX{} provides the {\tt theindex} \index{theindex environment@} environment to make an index for you. This environment produces two-column pages, as described in Chapter~\ref{two-column}. Each main index \index{index entry} entry is begun by an \verb"\item"\index{!item, in theindex environment} command. A \index{index subentry} subentry is begun with \verb"\subitem"\index{!subitem@}, and a subsubentry \index{index subsubentry} is begun with \verb"\subsubitem"\index{!subsubitem@}. Thus, a complex entry might look like \begin{verbatim} \item gnus 24, 37, 233 \subitem good, 38, 234 \subsubitem very, 235 \subitem bad, 39, 236 \end{verbatim} Blank lines between entries are ignored. An extra vertical space is produced by the \verb"\indexspace"\index{!indexspace@} command, which is usually put before the first entry starting with a new letter. \yspace The procedure for making a glossary is completely analogous. Instead of the \hbox{\verb"\index"} command you use a \hbox{\verb"\glossary"}\index{!glossary@} command, and instead of \hbox{\verb"\makeindex"} you write \hbox{\verb"\makeglossary"}. The glossary file is named \hbox{\verb"myfile.glo"}\index{glo} instead of \hbox{\verb"myfile.idx"}, and \LATEX{} writes \hbox{\verb"\glossaryentry"}\index{!glossaryentry} instead of \hbox{\verb"\indexentry"}. However, there is no environment for glossaries that corresponds to the \hbox{\tt theindex} environment. You'll have to format the glossary yourself. \section{Cross References}\index{cross references} \label{xref} When I tell you to see the discussion of ordinary printing characters on page~\pageref{ordinary} in Section~\ref{ordinary}, you can be sure that if you turn to page~\pageref{ordinary} you'll find that discussion there. This is because you're not depending upon my care in getting things right, but on \LATEX's automatic cross-referencing facility. I began the preceding paragraph with \begin{verbatim} ... characters on page~\pageref{ordinary-char} in Section~\ref{ordinary-char}, you can be sure ... \end{verbatim} In Section~\ref{ordinary}, in input that produced the discussion of ordinary printing characters on page~\pageref{ordinary}, there appeared the command \begin{verbatim} \label{ordinary-char} \end{verbatim} The \verb"\pageref"\index{!pageref@} command produces the page number where the corresponding \verb"\label" command occurred, and the \verb"\ref"\index{!ref@} produces the section number. (See Section~\ref{simple-text} for an explanation of what the \xsp{}\verb"~"\index{tilde}\xsp{} is doing there.) The argument of the \verb"\label" command can be any string of ordinary printing characters. As usual, \index{case}\index{upper-case}upper-case and \index{lower-case}lower-case letters are considered to be different characters; \verb"\ref{gnu}" does not refer to \verb"\label{Gnu}". It's safest to stick to a single case, either upper or lower, for all your labels. You can use the \verb"\ref" command to refer to anything that \LATEX{} numbers for you, such as equations and item numbers. The \verb"\label" command causes its argument to label the innermost numbered environment that contains it. Thus, if you put a \verb"\label{gnu}" command inside Theorem~2.7, then \verb"\ref{gnu}" produces ``2.7'', and if you put it inside item 3(b) of an enumeration, then the \verb"\ref" command produces ``3(b)''. If the \verb"\label" command is not within any numbered environment, then it labels the most recent \index{!chapter}\verb"\chapter", \index{!section}\verb"\section", \index{!subsection}\verb"\subsection", or \index{!subsubsection}\verb"\subsubsection" command. As explained in Section~\ref{figures}, it is the \verb"\caption"\index{!caption} command that numbers a figure\index{figures, labeling} or table\index{tables, labeling}. To label a figure or table, you should put the \verb"\label" command inside the \hbox{\tt figure} or \hbox{\tt table} environment, right {\it after\/} the caption. \yspace A \verb"\ref" or \verb"\pageref" command can precede the corresponding \verb"\label" command. \LATEX{} accomplishes this by writing the information it needs on an auxiliary \index{auxiliary file} file having the extension {\tt .aux}\index{.aux file}. If your main file is named {\tt myfile.tex}\index{myfile.tex}, then \LATEX{} will produce an auxiliary file named {\tt myfile.aux}. Moreover, for every \index{!include'd files}\verb"\include"'d file {\tt gnu.tex}, it will generate an auxiliary file named {\tt gnu.aux}. (See Section~\ref{parts} above for a discussion of \verb"\include"'d files.) A \verb"\ref" or \verb"\pageref" command always produces the numbers that were right the last time the corresponding \verb"\label" command was processed. If the input has been changed, then these may not be the correct values. When it's wrapping things up, \LATEX{} will type a warning message if an incorrect number may have been produced by a \verb"\ref" or \verb"\pageref" command. If you receive this warning, you must run your file through \LATEX{} again to get things right. In practice, when putting the finishing touches on a document, the last few changes you make will seldom change any cross references, so you'll hardly ever have to make an extra pass just for the cross references. \LATEX{} also warns you about undefined and multiply-defined labels. If you work hard at it, you can create a \verb"\label" and corresponding \verb"\pageref" that \LATEX{} cannot handle correctly. The probability of doing that by accident is too small to worry about. The \verb"\nofiles"\index{!nofiles} command, described in Section~\ref{aux} below, suppresses the writing of the auxiliary files. However, \LATEX{} always tries to read your {\tt .aux} file, and produces a warning message if it doesn't find it. This was the cause of the \begin{verbatim} No file myfile.aux. \end{verbatim} message we saw in our example on page~\pageref{running-ex} of Section~\ref{running-ex}. Since \LATEX{} makes cross referencing so easy, you may be tempted to go overboard. Each \verb"\label" command uses up some of \TEX's string space\index{string space}, so it's a good idea to label only what you actually reference. Remember also that page references are rare in technical documents; they are used in this manual to help you browse through it without reading the whole thing. \yspace When using symbolic names for cross-referencing, it's easy to forget what name you've assigned to a section or figure. You can generate a list of your symbolic \index{symbolic names, making list of} names and what they refer to by running \LATEX{} with a special input file named {\tt lablst.tex}\index{lablst.tex}. This file will be on some system directory, and you'll have to consult a local expert to find out how to run \LATEX{} on it. When \LATEX{} processes the {\tt lablst} file, it will ask you to type in the name of the input file whose cross-references you want listed, and the name of the document style used by that file. \section{Bibliographies and Citations}\index{bibliography}\index{citations} To produce the citation \index{!cite@}\cite{knuth-tex82}, I typed \begin{verbatim} \cite{knuth-tex82} \end{verbatim} The argument of the \verb"\cite" can be any string of ordinary printing characters. (See page~\pageref{ordinary} in Section~\ref{ordinary} to find out which the ordinary printing characters are.) I also had to tell \LATEX{} that \verb"knuth-tex82" should refer to \knuth, giving it all the information appearing in the bibliography entry on page~\pageref{bibliography}. Eventually, it will be possible to put your bibliography information into one or more \index{bibliography database file}bibliography database files\index{database file}. Putting the command\index{!bibliography@} \begin{verbatim} \bibliography{mamls,gnats} \end{verbatim} will cause the bibliography to appear at that point, with the information to construct the bibliography coming from the database files named {\tt mamls.bib} and \verb"gnats.bib". If the command \verb"\cite{Knuth:gnus}" appears in your text, then an entry labeled {\tt Knuth:gnus} must appear in one of these two database files. This automatic bibliography feature will work as follows. Suppose your input file is named {\tt myfile.tex}. (If your input is split into several files, as described in Section~\ref{parts}, this is the main file.) When \LATEX{} processes the input, it records the argument of every \verb"\cite" command as well as the argument of the \verb"\bibliography" command on the {\tt .aux} \index{aux files} file or files it produces. (See Section~\ref{aux} for a complete discussion of {\tt .aux} files.) When you're ready to produce the bibliography, you will run a special program called \BIBTEX, which will produce a file named {\tt myfile.bbl} containing the \LATEX{} input that generates the bibliography. The next time you run \LATEX{} on your file {\tt myfile.tex}, executing the \verb"\bibliography" command will cause \LATEX{} to read in the file {\tt myfile.bbl} and produce the bibliography. The format of the bibliography database files will be described in a later edition of this manual. It will be compatible with the format used by \index{scribe}Scribe for its {\tt .bib} files \cite{reid-scribe-manual}. A database file will consist of a set of reference entries, each one containing the data needed to create a bibliography entry---author, title, year of publication, and so on---but no information about how the entry is to be formatted. The formatting of the bibliography will be specified by a \LATEX{} \verb"\bibstyle"\index{!bibstyle} command. For example, the command \begin{verbatim} \bibstyle{ieee} \end{verbatim} might specify that the bibliography entries be formatted in the style used by the IEEE\index{IEEE} in its publications. The \verb"\bibstyle" command can go anywhere in your input file. \yspace That's the way things will work eventually; for now, you'll have to create your own bibliography using the \verb"thebibliography" \index{thebibliography environment} environment. This environment is very much like the \verb"description" environment described in Section~\ref{list-making} on page~\pageref{list-making}. Its argument is a copy of the longest reference name or number---{\it e.g.}, {\tt 99.} or {\tt [Knuth82]}. Each bibliography entry is begun with a \verb"\bibitem"\index{!bibitem@} command instead of an \verb"\item"\index{!item} command. The \verb"\bibitem" command has a mandatory argument containing the label by which the reference is cited. For example, I created the bibliography entry \cite{knuth-tex82} on page~\pageref{bibliography} by typing \begin{verbatim} \bibitem{knuth-tex82} Knuth, Donald ... \end{verbatim} and referred to that entry by typing \begin{verbatim} \cite{knuth-tex82} \end{verbatim} Note how this caused the bibliography entry to receive a number. If I wanted it to be labeled as something like ``[Knuth83]'', I would have added an optional argument to the \verb"\bibitem" command as follows: \begin{verbatim} \bibitem[{[Knuth83]}]{knuth-tex82} Knuth, Donald ... \end{verbatim} Recall that, as discussed in Section~\ref{command-names}, you have to put braces around an optional argument that contains a right square bracket. The \verb"\bibitem" command defines the reference number produced by a \verb"\cite" command in exactly the same way that a \verb"\label" command defines the number produced by a \verb"\ref" command, which was explained in Section~\ref{xref} above. See also Section~\ref{aux} below for a more complete explanation. \section{Auxiliary Files}\label{aux} \LATEX{} can produce quite a few files when processing your input. You can keep it from producing many of them by putting a \verb"\nofiles"\index{!nofiles@} declaration before the \verb"\begin{document}" command. The ones that are of primary interest to us here are the {\tt .aux}\index{.aux files} files, which are used to implement \LATEX's \hbox{\verb"\includeonly"} command and most of its cross-referencing features. Before describing how this is done, I will list all of the files that \LATEX{} can produce if your main file is {\tt myfile.tex} and you have an \hbox{\verb"\include"}'d file named {\tt part.tex}, and under what circumstances it is produced. \begin{description}{{\tt myfile.dvi}:} \item[{\tt myfile.dvi}:] The output file.\index{.dvi file} It is always produced. \item[{\tt myfile.lst}:] The \index{.lst file} file containing everything that \TEX{} printed on your terminal and then some. It is always produced. \item[{\tt myfile.idx}:] A \index{.idx file} list of all index entries produced by \verb"\index"\index{!index} commands. This file is produced only if there is a \verb"\makeindex"\index{!makeindex} command and no \hbox{\verb"\nofiles"} command. \item[{\tt myfile.glo}:] A \index{.glo file} list of all glossary entries produced by \verb"\glossary"\index{!glossary} commands. This file is produced only if there is a \verb"\makeglossary"\index{!makeglossary} command and no \verb"\nofiles" command. \item[{\tt myfile.toc}:]\index{.toc file}Generates the table of contents. This file is produced only if there is a \hbox{\verb"\tableofcontents"}\index{!tableofcontents} command and no \verb"\nofiles" command. \item[{\tt myfile.lof}:]\index{.lof file}Generates the list of figures. This file is produced only if there is a \verb"\listoffigures"\index{!listoffigures} command and no \verb"\nofiles" command. \item[{\tt myfile.lot}:]\index{.lot file}Generates the list of tables. This file is produced only if there is a \verb"\listoftables"\index{!listoftables} command and no \verb"\nofiles" command. \item[{\tt myfile.aux}:] Described below. It is produced unless there is a \verb"\nofiles" command. \item[{\tt part.aux}:] Described below. It is produced only if {\tt part.tex} is processed and there is no \verb"\nofiles" command. \end{description} In addition to these, nonstandard document styles could produce other files, such as one for a list of programs. Since a list of programs would be handled the same as a list of figures, I will ignore this possibility. We now come to the gory details of what gets put on the {\tt .aux} files, and how this data is used. You don't really need to know any of this, and I suggest that you leave everything in \LATEX's hands and not read any further. If you run \LATEX{} twice on the entire input, the output from the second run will have all the right numbering---assuming you didn't forget any \verb"\label" commands or bibliography entries. However, if you want to understand why \LATEX{} sometimes messes up the numbering when you're making changes and processing only part of the input, then read on. A data item is written on an {\tt .aux} file whenever any of the following are encountered in the text. \begin{itemize} \item An entry for the table \index{table of contents, .aux file entry for} of contents, list of \index{list of figures, .aux file entry for} figures or list \index{list of tables, .aux file entry for} of tables. This data item contains the complete entry and whether it is a table of contents entry or one of the other two kinds of entry. \item A \verb"\label"\index{!label, .aux file entry for} command. The data item contains the argument of the \verb"\label" command. \item A \verb"\bibitem"\index{!bibitem, .aux file entry for} command. The data item contains the command's mandatory argument. \item A \verb"\cite"\index{!cite, .aux file entry for}, \verb"\bibliography"\index{!bibliography, .aux file entry for}, or \verb"\bibstyle"\index{!bibstyle, .aux file entry for} command. This data item is used only by the \BIBTEX\index{bibtex} program. \end{itemize} Any of these items may be found on either the main file's {\tt .aux} file (the file {\tt myfile.aux}) or on an \verb"\include"'d file's {\tt .aux} file (the file {\tt part.aux}), depending upon whether the command that generated that item was encountered in the main file or in the \hbox{\verb"\include"'d} file. Note that as far as the auxiliary files are concerned, text inserted with an \verb"\input" command logically belongs to the file containing that command. Whenever \LATEX{} encounters an \verb"\include"\index{!include, affect on .aux file} command, it writes the name of the \verb"\include"'d file on the main {\tt .aux} file. If \LATEX{} processes this file, upon reaching the end of the file, it writes the current values of all counters on the \verb"\include"'d file's {\tt .aux} file. This describes when everything is written on the auxiliary files, and will explain why funny things happen if you stop a \LATEX{} execution in the middle. If you stop \index{stopping latex, effect on .aux files} \LATEX{} by responding to a \xsp{}{\tt ?}\xsp{} with an \xsp{}{\tt X}\xsp{} or a \verb"I\stop", as described in Section~\ref{running-ex}, then the new {\tt .aux} files will be written for the main file and for every \verb"\include"'d file whose processing was begun. (The {\tt .lst} \index{.lst file} file will tell you if \TEX{} has begun processing an \verb"\include"'d file.) If you stop \LATEX{} by using an operating system command, the best thing to do is to use your system's directory commands to see when the {\tt .aux} files were written. Having written the {\tt .aux} files, when does \LATEX{} read them? \LATEX{} reads the previously-written version of the main {\tt .aux} file when it executes the \linebreak %%%%% \hbox{\verb"\begin{document}"} command. It then tries to read the {\tt .aux} file of every \hbox{\verb"\include"}'d file mentioned on the main file's {\tt .aux} file. It types a warning message whenever it fails to find an {\tt .aux} file. The information it reads at this time is used to determine what each \verb"\ref"\index{!ref}, \verb"\pageref"\index{!pageref} and \verb"\cite"\index{!cite} command will produce. Even though a \verb"\ref{gnu}" command comes after the \verb"\label{gnu}" command, \LATEX{} will still use the information from the {\tt .aux} file, which could be obsolete, in generating the output for the \verb"\ref{gnu}". It is while processing the \verb"\begin{document}" command that \LATEX{} warns you if two \verb"\label" commands or two \verb"\bibitem" commands had the same argument. (A \verb"\label" command and a \verb"\bibitem" command may have the same argument.) \LATEX{} reads the newly-written main {\tt .aux} file and the latest version of every \verb"\include"'d file's {\tt .aux} file when it executes the \hbox{\verb"\end{document}"} command. It does two things at this time: \begin{itemize} \item It writes the {\tt .toc}\index{.toc file}, {\tt .lof}\index{.lof file}, and {\tt .lot}\index{.lot file} files (if they should be written). \item It checks if the values assigned to any cross-referencing label have changed, and types a warning if it has. \end{itemize} You now know more than you wanted to about how \LATEX{} handles auxiliary files. This information is of hardly any use, and will only serve to reassure you that \LATEX{} is doing what it's supposed to when the cross-referencing commands surprise you. \section{Interaction} \label{typein}\index{interaction} When creating a large document, it's easy to forget about things, so you may want to leave notes for yourself. The use of the \xsp{}\verb"%"\index{percent}\xsp{} for comments\index{comments} was described in Section~\ref{simple-text}. However, this kind of passive comment is easy to overlook. Therefore, \LATEX{} provides the \verb"\typeout"\index{!typeout@} command for printing \index{messages, generating}messages on your terminal when \LATEX{} processes your file. Executing the command \begin{verbatim} \typeout{Don't forget to revise this!} \end{verbatim} prints the message \begin{verbatim} Don't forget to revise this! \end{verbatim} on your screen, and puts it in the {\tt .lst} \index{.lst file, putting things in}file. Sometimes it is useful to be able to change something from the\index{commands, entering from keyboard}\index{input, entering from keyboard} keyboard when running \LATEX{} without changing your input file. For example, you might want to enter an \verb"\includeonly"\index{!includeonly, entering from keyboard} command without putting the command in your file. Processing the command\index{!typein@} \begin{verbatim} \typein{Enter `includeonly', turkey!} \end{verbatim} causes \LATEX{} to type out \begin{verbatim} Enter `includeonly', turkey! \@typein= \end{verbatim} and then wait for you to enter some text followed by a \carrtn. The text that you type will then be processed exactly as if it had appeared in the input file right where the \verb"\typein" command appeared. The command \begin{verbatim} \typein [\turkeyed]{Enter included file names.} \end{verbatim} is similar, except instead of processing the text you type, \LATEX{} defines the command \verb"\turkeyed" to be equivalent to that text. You might follow the \verb"\typein" command with \begin{verbatim} \includeonly{\turkeyed} \end{verbatim} Had you responded to the \verb"\typein" command by typing \begin{quote} \tt gnat,gnu\carrtn \end{quote} then that \verb"\includeonly" command would be equivalent to \begin{verbatim} \includeonly{gnat,gnu} \end{verbatim} \yspace \noindent {\bf Warning:} The argument of a \verb"\typeout" or \verb"\typein" command should contain only ordinary printing characters and space characters. Commands in the argument will produce strange results.