Chapter 7
Large Documents
7.1 The Root File
When preparing large reports, theses, papers, and the like, it is easier to work on them by chapters or sections. The way to do this is to create a separate .TEX file for each chapters or section and a “root” .TEX file that (1) specifies the type of document, (2) the style and formatting to be used, (3) any new commands or macros you will be using, (4) commands to create special parts (for example, a table of contents or an index), and (5) the particular .TEX files to be included. In Fig. 7.1 an example of a root file is given that you 
consisting of several .TEX files.
The root file has two parts: first is the preamble where information about styles, page dimensions, and new or redefined commands (macros) are placed. The second portion between the egin{document} and end{document} contains the names of the .TEX files containing the document text as well as other commands to generate special sections, such as the table of contents.
Note the two includeonly statements in Fig. 7.1, one of which is commented out (with the % symbol). The uncommented statement is used to work on only a single part of the document (here ch2.tex). When the whole document is to be processed, switch the %;, between these two includeonly statements. Also uncomment the lines containing tableofcontents and listoffigures when ready to produce the final document.
Figure 7.1: Example root file for a large document
7.2 Macros in the Preamble
In the preamble of the root file, you can include definitions of new commands and environments, as well as new definitions for existing commands. The ability to create such new commands and environments is the hallmark of a pert. A good document should have few complex series of nested commands in the document proper. Rather, new commands and environments should be created so that the writer can concentrate on what he or she is writing and not be distracted by wrestling with formatting problems during the writing phase.
In Chapter 9, methods for creating macros together with several useful examples are presented. Here are a few simple examples to show how macros are placed in the preamble.
Over time you will acquire many useful macros that you will want available for all your documents. Rather than place them individually in the preamble, put them in a separate file (with extension .TEX) and bring them into a document with the input command as illustrated in the above example. Equivalently, you can place them in a style (.STY) file and include this style file as a style option in the documentstyle command (see Fig. 7.1).
Also notice that preamble macros that involve 
and internal variables (those with © as part of their names) must be placed between the statements makeatletter and makeatother. When placed in style files (.STY), these bracketing statements are not necessary.
7.3 Loading Style Files
Style files are a special type of macro file. However, they are generally involved with making changes at the heart of or even of . As such, they alter commands that include the © symbol. For example, a style file might include the statement def
ightmark{expandafter©rightmarkotmark} Files that contain such statements should be read into a document through the optional style parameter list in the documentstyle command as, for example,
document style[texnotes, mystyle, 12pt]{report}.
In this example texnotes and mystyle are style files (with extension .STY) to be included in the document. Note that the order of listing the style files determines which commands are entered first.
Sometimes you will want to have a style file loaded after all other style files and preamble commands have been entered. It is possible, but unusual, to load style files and commands containing the © symbol from within the preamble by bracketing them with makeatletter and makeatother, as in
makeatletter
def
ightmark{expandafter@rightmarkotmark}
input wrapfig.sty
makeatother
Finally, be aware of the danger of using too many style files together. One file can redefine parameters or commands set by another. This can cause great havoc in your document. Sometimes the problem can be cured by entering the style files in a different order. Also, trying to load too many style files may exhaust the internal memory of your compiler.
7.4 Front Matter
Before the chapters of your report or book, there generally will be several pages of front matter: title page, dedication, preface, list of contents, list of figures, list of tables, and so on.
7.4.1 Title Page
For the title page, it is often easier to lay out a page using vspace, Huge, and other such standard commands, and to avoid any of the itle, author, and other special commands that are used by to create title pages. Although this approach is contrary to the philosophy of freeing the user from formatting concerns, it does allow you to create your own cover design. For example, the cover page of an early draft of this book was produced with
If you are using a prescribe journal style (for example, REVTEX. STY or IEEE. STY, then, of course, you should use the style’s title-page commands to create the title page and not perform your own formatting.
7.4.2 Preface
Create the preface like any other chapter using the chapter*{Pref ace} command, where the * prevents any incrementing of the chapter counter and suppresses any numbering or entries in the table of contents.
7.4.3 Table of Contents
The ableofcontents command in the root file shown in Fig. 7.1 will automatically cause a table of contents to be generated. Actually this command causes a file called fn.TOC (where fn is the name of the root file) to be created, and the file by the same name created in the previous run is used in creating the index in the .DVI file. Thus it takes at least two runs to create a table of contents that reflects the current pagination and sectioning of the document. If the pagination of your table of contents affects the pagination of the remainder of the document, then three passes are necessary. On the second pass, the number of pages in the table of contents may change, thereby changing the page numbering in the rest of document. Only if the pagination of the front matter is independent of the pagination of the main document (as in this document) will two passes suffice.
This multiple-pass procedure for creating a table of contents allows you to edit and modify the fn.TOC file prior to ing the whole document for the last time. In this way you can cause the table of contents to be printed as you want.
The amount of detail included in the table of contents is controlled by the counter tocdepth. The value of this counter determines the level of the least significant sectional unit to be included. Chapters are level 0, sections are level 1, subsections level 2, and so on. Thus, to include only chapters and sections titles in the table of contents, place in the preamble setcounter{tocdepth}{l}.
7.4.4 Lists of Figures and Tables
will automatically produce a list of figures with their captions if the command listoffigures is encountered during the processing of the root file. Similarly, a listoftables command will produce a list of figures and their captions. The page numbers used in these lists are those found during the previous processing of the file. Thus, to ensure correct pagination, the root file has to be processed at least twice.
Often the captions used in tables and figures are very lengthy, and an abbreviated caption for the list of tables and figures is desired. You may manually edit the .LOF and .LOT files created during the first processing. However, a better way is to provide the figure or table with a shorter caption to be used in the lists. The general form of the caption command is
caption [entry-for-LOF/LOT] {caption-f or-figure/table}
7.4.5 Adding Entries to Contents, Tables, and Figures Lists
If you use the * form of sectioning commands to produce an unnumbered heading, no entry will be made to the table of contents .TOC file. However, you can manually add an entry for such a section or for any other item you want included. To add an entry, denoted by entry, to either the .TOC .LOF or .LOT file, use the command
addcontentsline{file} {format} {entry}
Here file is the file to which entry is to be added (either TOC, LOF, or LOT). The format parameter controls the format of the entry and must be figure or table if
file is LOF or LOT, respectively. If file is TOC, then format is the appropriate sectional unit such as chapter or subsection.
To add a section number to the table of contents entry and to make the entry align with the other subsection entries, use
addcontentsline{toc}{subsection}{protect%
umberline{5.3.7}{Test Title}}
7.4.6 Roman Page Numbering for Front Matter
Pagination style and numbering for the front matter will generally be different (usually lowercase roman numerals) from that of the rest of the document (usually arabic numbers beginning with 1 on the first page of Chapter 1). This change in pagination between the front matter and the body of the document is easily done in . First place the command pagenumbering{roman} before the first part of the front matter (for example, in Fig. 7.1 before the ableofcontents statement). Then on the first page of the document body (usually right after the first chapter{…} command in the body) put the command pagenumbering{arabic}.
7.4.7 Reformatting the Table of Contents
The spacing between entries in the table of contents (or lists of figures and tables) is controlled by the parameter parskip. You may want extra space between paragraphs in the document (also controlled by parskip) and yet not between the entries in the table of contents. To force the table of contents to be single spaced while placing separation between text paragraphs, the ableofcontents line in the root file should resemble
parskip 0ex ableofcontents parskip 1.5ex
In the table of contents, places a row of dots between a heading entry on the left and its page numbers on the right. The spacing between these dots is controlled by the parameter 
©dotsep
Also, you will find that, if you have many pages (> 999) or if your use a long page numbering scheme (for example, section-page), the box used for the page numbers in the table of contents will be too small, and the leader dots will overlap the page numbers. To avoid this, change the box width for the page numbers by placing in the preamble something like
makeatletter
enewcommand{@pnumwidth}{2.4em} %-- TOC Page No. width
makeatother
7.5 Excluding Part of the Input
When working on a long .TEX file, it is convenient to exclude parts of the file from being ed so as to speed the processing time. Perhaps the simplest way is to put iffalse at the beginning of the text to be ignored and fi at the end of the excluded text.
7.6 Footnotes
Footnotes are readily added to a document with the footnote[num]{text} command. Here num is an optional number for the footnote. If it is omitted, the next footnote number will automatically be used.
Footnotes are sequentially numbered throughout a chapter. The counter for footnotes is automatically reset to 1 at the beginning of each new chapter. Long footnotes can be broken across a page boundary by .
7.6.1 Footnotes in a Heading1
1This is a footnote referenced in a subsection heading
The footnote command is fragile and must be protected when attached to a moving argument such as a section heading (that is, use protectfootnote{…}).
An alternative way to place a footnote reference in a section heading is to use the optional argument in the section command so that footnote is no longer in a “moving argument” and hence no longer needs to be protected. For example the heading for this subsection was produced with
section[Footnotes in a Heading]{Footnotes in a Headingfootnote{This is a
footnote referenced in a subsection heading}}
7.6.2 Changing the Footnote Symbol
The footnote symbols * † ‡ § ¶ * * † † ‡ ‡ can be used instead of numbers by placing the following command in the preamble (or body) of your document.
enewcommand{ hefootnote}{fnsymbol{footnote}}
Since there are only nine footnote symbols, make sure that no chapter has more that nine footnotes.
To specify a particular footnote symbol, the optional argument of the footnote command is used, for example, footnote[2]{…}. The footnote symbols can be restored to the normal arabic form with
enewcommand{ hefootnote}{arabic{footnote}}
7.6.3 Footnotes inside Boxes
The footnote command can be used only in normal paragraph mode. To attach a footnote to text that is in a box, use the pair of commands footnotemark[num] and footnotetext[num]{text}, as in the following example.
7.7 Cross References
One of the great powers of is the ability to refer to some document part that has a number (for example, a chapter, section, subsection, equation, etc.) anywhere in the document without having to keep track of the numbering.
To make forward or backward references to chapters, sections, tables, figures, equations, eqnarrays, and items in an enumerate environment use the label command to attach a reference key to the item. This label command is used to define the reference key immediately after the item to which you may want to make a reference. For example, if a reference is to be made elsewhere in the document to a specific chapter, then, when that chapter is defined, you might input
chapter{An Important Chapter}label{imptchpt}
Here the reference key to this chapter is imptchpt. Whenever you want to refer to this chapter, use
ef{imptchpt}, and whenever you want to refer to the page on which this chapter begins use pageref{imptchpt}. For example, you might enter
The most important theorems are discussed in
Chapter~ ef{imptchpt}, which begins on page~pageref{imptchpt}.
7.8 Citations and Bibliography
A nice feature of [2, 3] is its ability to make citations and their numbering relatively easy. In preparing a large document, it is usual to add and delete references during the many revisions, and makes this job relatively easy.
7.8.1 The Bibliography List
The trick to referencing in is first to make an itemized bibliography list and then to include it in the .TEX file (usually at the end) enclosed by the environment command egin{thebibliography}{size…end{thebibliography} where size is the largest (widest) anticipated citation number (which is used to determine the spacing needed in the bibliographic list). For example, if 3-digit citation numbers are anticipated, then set size = 999. In the bibliography list, each reference is identified with the ibitem{key}, where key is some unique identifier for the reference that follows. Then, in the text you need only use cite{key} to have the citation inserted. A typical bibliography list might look like
egin{thebibliography}{9}
ibitem{La86} L. Lamport, LaTeX:
{it A Document Preparation System},
Addison-Wesley, New York, NY 1986.
ibitem{CSF} A. B. Chilton, J. K. Shultis
and R. E. Faw,
{it Principles of Radiation Shielding},
Prentice-Hall, New York, NY 1984.
end{thebibliography}
7.8.2 Making References in the Text
Once the bibliography file is created, you can easily reference your favorite books [2, 1] or even your favorite page [1, page 193]. This output is produced with
Once the bibliography file is created, you can easily reference your favorite books cite{La86,CSF} or even your favorite page cite[page 193]{CSF}. This output is produced with
A word of warning. numbers the references in the order that they appear in the bibliography list not in the order of their citation in the text. You need to reorder manually your bibliography list if you seek ascending reference numbering throughout the document.
7.8.3 Printing the Bibliography
automatically begins printing the bibliography on a new page when it encounters the bibliography list in the input file. No special commands are needed! See the example bibliography output at the end of this chapter. In article document style the bibliography is entitled “References” whereas in book and report styles it is labeled “Bibliography”.
7.8.4 Citation Variations
Instead of using numbers inside square brackets for references, lets you use any symbolism you want. For example, the last item in the bibliography list used in this chapter is
ibitem[NONAME]{junk} N. 0. Name, {it Never Referenced
Book}, NoName Publ. Co., NoWhere U.S.A., 1991.
where [NONAME] is the citation label to be used in place of citation numbers. Then, to make this citation [NONAME, page 0], you would enter:
… make this citation cite[page 0]{junk}, you would ...
7.9 References and Citations in Captions
The caption command used in figures and tables is fragile. This means that other commands cannot be embedded in the caption without first protecting them. Here is an example of a table whose captions contains both a citation and a reference to a table.
Table 7.1: Test table whose caption contains a reference, in this case to itself, Table 7.1, and has a citation [2] to a bibliographic item
The caption for this table was produced with the following input statements. Notice that both the
ef and cite commands in the caption must be protected.
caption{Test table whose caption contains a reference,
in this case to itself, Table~protect
ef{reftable},
and has a citation protectcite{La86} to a bibliographic
item} label{reftable}
The same trick will not work for making a footnote reference in the caption of a table. Using protectfootnote produces two footnotes! One awkward way to put a footnote reference into the table caption is to manually place the symbol in the caption and also to manually place the footnote after the table.
7.10 Making an Index
Generating an index for a large document is a complex affair. helps automate the process, but it still involves a lot of manual work. Here is the procedure.
Step 1: Use the index command throughout your document next to the each word where an index entry should be made, for example,
… used violins, tubas, and bagpipesindex{instruments} in the...
When ready to start making the index, place the command makeindex in the preamble of the root file. The index command in the input files is normally ignored by . The makeindex command, however, causes to process the index entries and create an .IDX file (with the same name as that of the root document) that contains an entry for each index item. The entries in the .IDX file look something like
…
indexentry{instruments}{59}
indexentry{apples}{62}
indexentry{badbad}{63}
Generally, you will not use the makeindex command until you have a final version of the document and are ready to do the final printing.
Step 2: The next step is performed outside . With your editor take the .IDX file and (1) alphabetize the entries, (2) combine similar entries, (3) create second-and third-level entries, and (4) reformat to obtain a file of the form
…
item instruments 63, 75, 127
subitem bagpipes, 63
subsubitem sound of, 75, 89
item ions 5, 25, 67, 122
indexspace
item jack-o’-lantern 52
item jargon 1, 15, 273
…
The indexspace forces a separation between the i and j entries in the index that will eventually be produced. Also you can add to the basic form shown. For example, you could have all primary entries in boldface by using {f instruments}, for example, in the preceding file.
Step 3: At the place in your document where you want the index to be printed (usually at the end), put the lines created in step 2 between egin{the index}…end{theindex}. When encounters this entry, it will begin a new page, place a large index title, and produce a two-column index.
7.10.1 Doing It Yourself
The above procedure is cumbersome at best. Often it is easier while proofreading the final draft to directly create with your editor the file generated in Step 2 above. Alternatively, several programs are available that will more easily prepare an index file (after manually entering the various entries) whose output you can convert into the form needed by step 2. These manually produced index files can then be printed by using the method of step 3.
7.10.2 The MAKEINDEX Program
A freely available program MAKEINDEX will greatly automate the creation of an index. This C program was written by Pehong Chen assisted by M. Harrison and Leslie Lamport, and it can be found in many Internet archives.
Creating an index with this program also involves several steps but requires far less manual effort. Here is the procedure.
1. Mark each word(s) for which you want an entry in the index (with special notation used for subentries and cross references), specify the makeidx option in the documentstyle command, place the makeindex command in the preamble, and just before the end{document} place the commands
cleardoublepage printindex
2. After compiling your document file (for example, MYD0C.TEX) for the first time, an .IDX file will be produced (for example, MYDOC.IDX).
3. Then run the MAKEINDEX program to create an index file (MYDOC.IND) with the command MAKEIDX MYDOC.IDX.
4. Finally, your document file one more time to produced a finished index at the end of your document.
Bibliography
[1] A. B. Chilton, J. K. Shultis and R. E. Faw, Principles of Radiation Shielding, Prentice Hall, New York, NY, 1984.
[2] L. Lamport, : A Document Preparation System, Addison-Wesley, New York, NY, 1986.
[3] J. Hahn, 
for Everyone, Personal , Inc., Mill Valley, CA, 1991.
[4] D. L. Knuth, The TeXbook, Addison-Wesley, New York, NY, 1990.
[5] A. Johnstone, Concisely, Prentice Hall, New York, NY, 1992.
[NONAME] N. O. Name, Never Referenced Book, NoName Publ. Co., NoWhere, U.S.A., 1991.
This was produced from the bibliography list
egin{thebibliography}{NONAME}
hispagestyle{texnotes}
ibitem{CSF} A. B. Chilton, J. K. Shultis and R. E. Faw,
{it Principles of Radiation Shielding},
Prentice Hall, New York, NY, 1984.
ibitem{La86} L. Lamport, LaTeX: {it A Document Preparation
System}, Addison-Wesley, New York, NY, 1986.
ibitem{Ha91} J. Hahn, {it LaTeX for Everyone}, Personal
TeX, Inc., Mill Valley, CA, 1991.
ibitem{Kn90} D. L. Knuth, (it The TeXbook}, Addison-Wesley,
New York, NY, 1990.
ibitem{Jo92} A. Johnstone, {it LaTeX Concisely},
Prentice Hall, New York, NY, 1992.
ibitem[NONAME]{junk} N. 0. Name, {it Never Referenced Book},
NoName Publ. Co., NoWhere, U.S.A., 1991.
end{thebibliography}