\chapter{Getting Stylish} \section{Table of Contents} \label{tableofcontents} Producing a table of contents\index{table of contents} is easy; you just put the command \begin{example} \\tableofcontents\index{!tableofcontents} \end{example} where you want the table of contents to go, and \LATEX{} miraculously puts it there. The only restriction is that the table of contents must precede anything that's listed in it. More precisely, it must precede any command such as \hbox{\tt \\section}\index{!section} that produces a table of contents entry. Exactly what the \hbox{\tt \\tableofcontents} command produces will depend upon the \index{document style}document style. Some styles won't produce a table of contents at all, so this command will be undefined. The command will generate the word ``CONTENTS'', but you will be responsible for adding any space above it, and for placing it on its own page. (See the \index{!newpage}\hbox{\tt \\newpage} command in Section~\ref{pbreak}.) If the table of contents precedes the commands that generate its entries, how does \LATEX{} know what to put in it? The first time \LATEX{} processes your manuscript, it doesn't, and it will produce an empty table of contents. However, as it processes the manuscript, \LATEX{} produces an \index{auxiliary files}auxiliary output \index{file} file with the information it needs to generate the table of contents. If your manuscript file is named \hbox{\tt gnu.tex} then the name of the file containing the table of contents information will be \index{toc}\hbox{\tt gnu.toc}. The first time it processes \hbox{\tt gnu.tex}, \LATEX{} will type a warning message saying that it couldn't find file \hbox{\tt gnu.toc}. Many document styles will also allow you to generate a list of \index{list of figures}figures and a list of \index{list of tables}tables, with the commands \index{!listoffigures}\hbox{\tt \\listoffigures} and \index{!listoftables}\hbox{\tt \\listoftables}, respectively. They work the same as the \hbox{\tt \\tableofcontents} command, producing the files \index{lof}\hbox{\tt gnu.lof} and \index{lot}\hbox{\tt gnu.lot} instead of \hbox{\tt gnu.toc}. Sometimes you'll want to add your own entry to a table of contents or a list of figures. This is done with the \index{!tableentry}\hbox{\tt \\tableentry} command. Look at the table of contents to observe the effect of the command \tableentry{toc}{\hspace{3.8em}7.8.9.\hspace{.7em}Gnats and Gnus} \begin{example} \\tableentry\{toc\}\{\\hspace\{3.8em\}7.8.9.\\hspace\{.7em\}Gnats and Gnus\} \end{example} which I just inserted in the manuscript. Note that making {\tt toc} the the first argument specifies the table of contents. You would use {\tt lof} or {\tt lot} to insert an entry in the list of figures or list of tables. In addition to the \hbox{\tt \\tableentry}, which produces a normal entry, there's an analogous \hbox{\tt \\tablemainentry}\index{!tablemainentry} command for producing a main entry. For example, I obtained the table of contents entry for the introduction of this manual by typing the command \begin{example} \\tablemainentry\{toc\}\{Introduction\} \end{example} In document styles having only a single type of entry, these two commands will be equivalent. To leave extra space above or below the entry produced by one of these commands, you must use a strut\index{strut} in the entry. (Struts are described on page~\pageref{strut} of Section~\ref{strut}.) On rare occassions, \LATEX{} may mess up a table of contents entry. For example, some document styles may not be able to handle chapter or section names that are too long to fit on one line. As a last recourse, you can edit the {\tt toc}\index{toc} file yourself to set things right. The file will contain mysterious commands, but you should be able to figure out what to do---for example, to shorten an entry so it will fit on one line. Of course, this should be the very last thing you do, when producing the final output. Don't forget to use a \hbox{\tt \\nofiles}\index{!nofiles} command (described in Section~\ref{counters}) to keep \LATEX{} from rewriting the {\tt toc} file. \section{Page Layout}\index{page layout} A page of output consists of three units: the head, the text and the foot. The head and foot are used for page numbers and various things that people like to put at the top and bottom of pages, such as the title of the current chapter. The text consists of everything that comes directly from your manuscript file, including figures and footnotes. The \hbox{\tt pagelayout}\index{!pagelayout} command specifies the size of each of these three units and where they go on the page. It determines the size of the \hbox{\tt \\textwidth}\index{!textwidth} and \hbox{\tt \\textheight}\index{textheight} distances, which are the dimensions of the text on the page. (See Section~\ref{distance}.) There are two versions of most page layout formats: one designed for documents that will be printed on just one side of the paper, and the second for documents that are printed on both sides, like real books. For most page layout formats, the first is considered to be the standard one and the second is obtained by the \index{twoside}\hbox{\tt twoside} option---for example, by typing \begin{example} \\pagelayout\{normal,twoside\} \end{example} \section{Page Styles}\index{page style}\label{pagestyle} The page layout determines the size and position of the page's head and foot. The {\it page style\/}\index{page style} determines what goes in them. The page style changes at various points in a document. For example, the title page has no page number, and the first page of a chapter has a different head and foot from the rest of the text, as does the page preceding it if the chapter begins on the right-hand page in a two-sided page layout. Fortunately, you don't have to worry about these changes; \LATEX{} handles them automatically. However, there are certain points in the manuscript, usually when you're beginning a new part of the document, where you may want to tell \LATEX{} to change the page style---for example, when you begin the table of contents or go from the introduction to the main body of the text. Also, you can override \LATEX's choice of page style if you disagree with it. There \hbox{\tt \\pagestyle}\index{!pagestyle} and \hbox{\tt \\thispagestyle}\index{!thispagestyle} commands are used to change the page style. They are the same except that the \hbox{\tt \\pagestyle} command changes the style from the current page on, while \hbox{\tt \\thispagestyle} changes it only for the current page, reverting afterwards to the style specfied by the preceding \hbox{\tt \\pagestyle} command. (If the change occurs on the page preceding the one you thought it should, see page~\pageref{page-breaking} in Section~\ref{page-breaking} for an explanation of why you and \TEX{} may have different ideas about what the ``current page'' is.) The argument of the \hbox{\tt \\pagestyle} or \hbox{\tt \\thispagestyle} command specifies the page style. What page styles are available will depend upon the document \index{document style}style. Below are some standard options that will be available in many document styles. \begin{description}{{\tt endchapter}:} \labelitem{{\tt plain}:}Just\index{plain page style} a plain page number. \labelitem{{\tt empty}:} Produces \index{empty page style}empty heads and feet---no page number. \labelitem{{\tt headings}:} Puts\index{headings page style} running headings on each page. The document \index{document style}style specifies what goes in the headings; there will usually be several options that provide different kinds of headings. \labelitem{{\tt myheadings}:} You\index{myheadings page style} specify what is to go in the heading. \hspace{0pt plus .5pt minus .5pt}The command \hbox{\tt \\lhead\{Gnus\}}\index{!lhead} tells \LATEX{} to make ``Gnus'' the text of the heading on left-hand pages. There's a similar \hbox{\tt \\rhead}\index{!rhead} command for the right-hand pages and a \hbox{\tt \\head}\index{!head} command to set both headings at once, which you will use for one-sided documents. These commands change the heading starting with the current page. They specify only the text of the headings; the document style determines the type style and where the page number goes. \labelitem{{\tt endchapter}:} Used \index{endchapter} for the left-hand page that precedes the beginning of a new chapter in two-sided documents. \end{description} Remember that the \hbox{\tt pagestyle} command changes the style starting with the current page. If you want the \hbox{\tt headings} page style begin after the introduction, starting with the first chapter, then the correct sequence of commands is: \begin{example} ... ending our introduction. \\newpage\index{!newpage} \\pagestyle\{headings\} \\chapter\{Armadillos I Have Known\}\index{!chapter} \end{example} The \hbox{\tt \\chapter} command may need to know what page style is in effect in order to set up the headings, so it is preceded by the \hbox{\tt \\pagestyle} command. The \hbox{\tt headings} page style won't take effect until the second page of the chapter because the \hbox{\tt \\chapter} command generates a \hbox{\tt \\thispagestyle} command that takes precedence. Although the document style determines where the page number goes, you get to \index{page numbering} decide what the number looks like. The \hbox{\tt \\pagenumbering}\index{!pagenumbering} command determines the number style. The standard choices for its argument are \hbox{\tt arabic}\index{arabic} and \hbox{\tt roman} to produce plain arabic numerals (like 248) or roman numerals (like \@roman{248}), respectively. This command also resets the page number to 1. See the \hbox{\tt \\setpagenumber}\index{!setpagenumber} command in Section~\ref{counters} for how to start with a different page number. Recall that\label{clearpage} I mentioned in Section~\ref{pbreak} that the \hbox{\tt \\clearpage}\index{!clearpage} command can change the page style of the pages that it puts out. This command is designed to finish the page preceding the first page of a chapter. When two-sided printing is specified, as is the case when the \hbox{\tt twoside}\index{twoside} document style option is specified, this preceding page is printed using the \hbox{\tt endchapter}\index{endchapter} page style if it falls on the left-hand (even-numbered) page. Don't worry about this now, but if something goes wrong, you should know exactly what \LATEX{} does. The \hbox{\tt \\clearpage} command can produce several pages of output---the last page of actual text, plus any figures following that page of text. When two-sided printing is in effect, the first even-numbered page put out by the \hbox{\tt \\clearpage} and all subsequent pages it produces will have the \hbox{\tt endchapter} page style. \chapter{To What Are You Referring?} You often want one part of your document to refer to another part. In the main text, you may want to refer to a section, a figure, or a bibliography entry; in the index, you want to refer to a page. This chapter tells you how to do it. \section{Cross References}\index{cross references} \label{cross-references} You have probably observed the many cross references in this document. When I tell you to see the discussion of page breaking\index{page breaking} on page~\pageref{page-breaking} of Section~\ref{page-breaking}, you can turn to page~\pageref{page-breaking} and find that discussion. I did this by placing the command \begin{example} \\label\{page-breaking\}\index{!label} \end{example} at the beginning of that discussion, and then referring to it by typing \begin{example} see the discussion of page breaking on page\~\\pageref\{page-breaking\} of section\~\\ref\{page-breaking\} \end{example} The \hbox{\tt \\pageref}\index{!pageref} command produces the page number where the label occurred, and the \hbox{\tt \\ref}\index{!ref} produced the section number. The {\tt \~} after \hbox{\tt page} ensures that ``page'' and ``\pageref{page-breaking}'' appear on the same line, as explained in Section~\ref{lbreak}. The label \hbox{\tt page-breaking} is an arbitrary piece of text that was easy for me to remember. You can use letters, numbers and punctuation in a label, but you shouldn't use any of \TEX's special characters like {\tt \\}\index{!} %%% } BRACE MATCHING HACK and \index{\string\% }{\tt \%}, or strange things like carriage \index{carriage return}returns. Also, \index{case}\index{upper-case}upper-case and \index{lower-case}lower-case letters are different; \hbox{\tt \\ref\{gnu\}} does not refer to \hbox{\tt \\label\{Gnu\}}. It's safest to stick to a single case, either upper or lower, for all your labels. You can use the {\tt \\ref} command to refer to anything that \LATEX{} numbers for you, such as equations and item numbers. The \hbox{\tt \\label} command causes its argument to label the innermost numbered environment that contains it. Thus, if you put a \hbox{\tt \\label\{gnu\}} command inside Theorem~2.7, then \hbox{\tt \\ref\{gnu\}} produces ``2.7'', and if you put it inside item 3(b) of an enumeration, then the {\tt \\ref} command produces ``3(b)''. If the {\tt \\label} command is not within any numbered environment, then it labels the most recent \index{!chapter}\hbox{\tt \\chapter}, \index{!section}\hbox{\tt \\section}, \index{!subsection}\hbox{\tt \\subsection}, or \index{!subsubsection}\hbox{\tt \\subsubsection} command. The {\tt \\ref} or \hbox{\tt \\pageref} command can precede the corresponding \hbox{\tt \\label} command. \LATEX{} accomplishes this by writing the information it needs on an auxiliary \index{auxiliary file} file\index{file} having the extension {\tt aux}\index{aux}, so if your manuscript file is \hbox{\tt gnu.tex} then the auxiliary file will be named \hbox{\tt gnu.aux}. If you change the manuscript file, then the cross references may not be correct the next time you run the file through \LATEX. When you produce your final output, you can run the file through \LATEX{} twice to make sure that the cross references are correct. 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. If you work hard at it, you can create a \hbox{\tt \\label} and corresponding \hbox{\tt \\pageref} that \LATEX{} cannot handle correctly. The probability of doing that by accident is too small to worry about. \LATEX{} warns you about undefined and multiply-defined labels. It types only the first few warning messages and then shuts up. The exact number of warnings it will type is determined by the document \index{document style}style. The \hbox{\tt \\nofiles}\index{!nofiles} command, described in Section~\ref{counters}, suppresses the writing of the {\tt aux} file. However, \LATEX{} always tries to read your {\tt aux} file, and produces a warning message if it doesn't find it. Since \LATEX{} makes cross referencing so easy, you may be tempted to go overboard. Each \hbox{\tt \\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. \section{Bibliographies and Citations}\index{bibliography}\index{citations} To cite a reference like \cite{knuth@tex82}, you write something like \begin{example} \\cite\{knuth:tex82\}\index{!cite} \end{example} where \hbox{\tt knuth:tex82} is an arbitrary label associated with the particular reference---in this case, with \knuth{} by Donald Knuth\index{knuth}. How do you tell \LATEX{} what reference to associate with this label? Eventually, you will create a bibliography by puting a command like \begin{example} \\bibliography\{mamls,gnats\}\index{!bibliography} \end{example} where you want it to go. The argument of this command says that the labels used in your {\tt \\cite} commands refer to references in \index{bibliography database file}bibliography database files\index{database file}\index{file} named \hbox{\tt mamls.bib} and \hbox{\tt gnats.bib}. These database files are used for all your documents; the \hbox{\tt \\bibliography} command extracts the references that appear in this particular one. The \LATEX{} bibliography database files will be compatible with Scribe\index{Scribe} bibliography files \cite{reid@scribe@manual}. To get the information from your database files, you will run a special program called \PRETEX{}\index{pretex} to process your main file, say \hbox{\tt gnu.tex}. \PRETEX{} will generate a file named \hbox{\tt gnu.bbl}\index{bbl file} that will be read by \LATEX{} when it processes your \hbox{\tt \\bibliography} command. That's the way things will work eventually; for now, you'll have to create your own bibliography using the \hbox{\tt bibliography} \index{bibliography environment} environment. This environment is very much like the \hbox{\tt 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]}. To assign your own names, use a command such as \begin{example} \\biblabelitem\{[Knuth82]\}\{knuth:tex82\} \end{example} which will produce an entry named ``[Knuth82]'' that is referred to by the command \begin{example} \\cite\{knuth:tex82\} \end{example} If you want your bibliography entries numbered, begin each one with a \hbox{\tt \\bibitem} command whose single argument specifies the label for that entry. \LATEX{} will provide the numbers. \section{Index and Glossary}\index{index}\index{glossary} \label{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. When you want an item to be indexed, you write a command like \begin{example} \\index\{A. A. Dillo\}\index{!index} \end{example} in the text where the item appears. If \LATEX{} decides to produce an index file for you, it will write the line \begin{example} \\indexentry\{A. A. Dillo\}\{\\\@{}arabic\{37\}\}% \index{!indexentry}\index{!@arabic} \end{example} telling you that the item appeared on a page that was numbered 37. It would have produced something like \begin{example} \\indexentry\{A. A. Dillo\}\{\\\@{}roman\{37\}\}\index{!@roman} \end{example} if it had appeared on page~\@roman{37}. The commands \hbox{\tt \\\@{}arabic} and \hbox{\tt \\\@{}roman} are ordinary \LATEX{} commands; I ended the preceding sentence by typing \begin{example} if it had appeared on page\~\\\@{}roman\{37\}. \end{example} The document \index{document style}style will provide commands to help you format the index, and may define the \hbox{\tt \\indexentry} command. However, you will have to edit the {\tt idx} file to produce an index; changing the \hbox{\tt \\indexentry} commands is at most a minor inconvenience. When \LATEX{} writes an index file, it calls it \hbox{\tt gnu.idx}\index{idx} if your manuscript file is named \hbox{\tt gnu.tex}. To get \LATEX{} to write this file, you have to include a \hbox{\tt \\makeindex}\index{!makeindex} command. \LATEX{} won't produce the index file if a \hbox{\tt \\nofiles}\index{!nofiles} command precedes the \hbox{\tt \\makeindex} command. The procedure for making a glossary is completely analogous. Instead of the \hbox{\tt \\index} command you use a \hbox{\tt \\glossary}\index{!glossary} command, and instead of \hbox{\tt \\makeindex} you write \hbox{\tt \\makeglossary}. The glossary file is named \hbox{\tt gnu.glo}\index{glo} instead of \hbox{\tt gnu.idx}, and \LATEX{} writes \hbox{\tt \\glossaryentry}\index{!glossaryentry} instead of \hbox{\tt \\indexentry}. Note that the \hbox{\tt \\index} and \hbox{\tt \\glossary} commands do not produce any text. If you want to index an appearance of the word ``gnat'', you'll have to type something like \begin{example} gnat\\index\{gnat\}\index{gnat} \end{example} \section{Doing it in Parts}\index{parts}\label{parts} \LATEX{} provides a mechanism for splitting your manuscript into pieces and processing the pieces separately as you revise them. You prepare a {\it root\/} \index{root file}file and one or more {\it part\/} \index{part file}files, each containing portions of the manuscript. Suppose that the root file is named \hbox{\tt gnu.tex} and the parts are \hbox{\tt gnat1.tex}, \hbox{\tt gnat2.tex}, and \hbox{\tt gnat3.tex}. The root file looks like an ordinary manuscript file, except that it contains three {\tt \\include}\index{!include} commands like \begin{example} \\include\{gnat1\} \end{example} which tells \LATEX{} that the material contained in file \hbox{\tt gnat1.tex} belongs at that point in the manuscript. The part files contain nothing but manuscript text; they have no document style command, {\tt \\text} command, or any of the other similar stuff described in Section~\ref{structure} that the main file contains. To generate the entire document, you run \LATEX{} on the root file as usual; when an {\tt \\include} command is encountered, the indicated file will be read and processed at that point. However, suppose you want to process only the part of the document contained on files \hbox{\tt gnat1.tex} and \hbox{\tt gnat3.tex}. If you just processed these files by themselves, the page numbers, section numbers, {\it etc.} would be all wrong. However, you can process the root file plus these two files by putting the following among the main file's processing commands\index{processing commands} \begin{example} \\doparts\{gnat1,gnat3\} \end{example} This will cause \LATEX{} to process only the root and those two parts, magically getting the right page numbers, section numbers, cross-references, and so on. A \hbox{\tt \\doparts} prevents \LATEX{} from writing a new {\tt toc}\index{toc} file, so the table of \index{table of contents}contents will not be changed to reflect changes to the manuscript. (Tables of contents are discussed in Section~\ref{tableofcontents}.) Lists of \index{list of figures}figures and \index{list of tables}tables lists are also left unchanged. To process the entire manuscript, you should remove the \hbox{\tt \\doparts} command; you should not use a \hbox{\tt \\doparts} command specifying all the parts. You might find the \hbox{\tt \\typein}\index{!typein} command described in Section~\ref{structure} to be a convenient way of entering the \hbox{\tt \\doparts} command. The \hbox{\tt \\include} command executes a \hbox{\tt \\clearpage}\index{!clearpage} (see Section~\ref{pbreak} on page~\pageref{pbreak}) before and after processing the included file, so the included file and the material that follows it must begin on a new page. Typically, the root will contain the title page, table of contents and bibliography, and a part will consist of one or more complete chapters. Unfortunately, this system isn't perfect, and changes to one part that should change the way things in another part are numbered sometimes don't. To understand when this will happen, you have to know how the \hbox{\tt \\include} mechanism works. When you process the complete document, \LATEX{} produces a separate {\tt aux} file for the root and for each part. A part's {\tt aux} file records the page numbers, section numbers, {\it etc.} in effect at the end of each {\tt \\include} statement. When processing only certain parts, \LATEX{} uses these numbers to reset the page number and all counters\index{counters} when it comes to an {\tt \\include} of a file it's not processing. (See page~\pageref{counters} of Section~\ref{counters} for a discussion of counters.) As \LATEX{} processes the manuscript, it writes a new {\tt aux} file for the root and for any part that is being included. So, everything will work out fine when you process parts so long as a change to a part doesn't change anything that is globally numbered, like the number of pages or theorems. What you'll probably find is that when you're working on a large manuscript, you'll make each chapter a separate part. In the early drafts, you'll be satisfied with seeing each chapter by itself, and you 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 to run a long manuscript through \TEX, you'll keep processing individual chapters by themselves until the numbering gets too far out of line, whereupon you'll run the whole document through \LATEX{}. Recall that \LATEX{} does a \hbox{\tt \\clearpage}\index{!clearpage} before and after each included part. What if your document uses the \hbox{\tt preprt}\index{preprt} style in which sections, the largest subdivisions, don't necessarily begin on new pages? You might still want to process your manuscript in pieces. In this case you should use \hbox{\tt \\include} commands just like before when producing rough drafts; it doesn't hurt to have extra page breaks in these drafts. When you're ready to produce the final document, just remove the \hbox{\tt \\doparts} command and replace each command like \hbox{\tt \\include\{gnat.2\}} by the raw \TEX{} command \hbox{\tt \\input gnat.2\index{!input}} Note the absence of braces!