%% TXSsects.doc - Chapters and Sections - TeXsis version 2.18 %% @(#) $Id: TXSsects.doc,v 18.3 2001/04/06 21:54:45 myers Exp $ %======================================================================* % (C) Copyright 1989-1998 by Eric Myers and Frank E. Paige % This file is a part of TeXsis. Distribution and/or modifications % are allowed under the terms of the LaTeX Project Public License (LPPL). % See the file COPYING or ftp://ftp.texsis.org/texsis/LPPL %======================================================================* \ifx\undefined\bs \texsis\input TXSdocM.doc\draft\input Manual.aux\fi \section{Typesetting Complete Papers\label{sect.papers}} The commands described so far are useful for creating the body of a simple physics paper, but they are not enough to typeset a complete paper. A physics paper generally has a title, one or more authors and their addresses or professional affiliations, and perhaps an abstract. Longer documents may be divided into sections, or even chapters, and there might even be a table of contents or an index. This section describes the commands for creating the basic structural elements of a complete paper: the title material and divisions into chapters, sections, and subsections. It also includes a discussion of more advanced topics, such as how to create a table of contents or an index, and how to control the running headlines at the top of the page. Later, \Sect{fmts} discusses more specialized document layouts for conference proceedings or for papers submitted to specific journals, while \Sect{letr} describes the commands for producing letters, memos, referee reports, and similar specialized documents. It is often convenient to be able to typeset the same document in more than one format. Therefore, all complete papers in \TeXsis\ use the same general structure, and one can select the particular document format to be used by changing only one or two commands at the beginning of the manuscript file. The commands to typeset the title page and to break the paper up into sections are still the same, even if they behave slightly differently according to the particular format selected. For example, if you give the \cs{paper} command then the title page material will appear at the top of the first page, and the text of the paper will also begin on that page. If you simply change \cs{paper} to \cs{preprint} the title page material will appear on a page by itself, with a banner (defined by \cs{banner}) across the top of the page, and the text will begin on the next page. Using any of the other document formats described in \Sect{fmts} will cause the title page material to be formatted slightly differently. At this point an example may be more instructive than more discussion. Here is how a famous paper\reference{BCS} J.~Bardeen, L.~N.~Cooper, and J.~R.~Schrieffer, \journal Phys. Rev.;108,1175(1957) \endreference would have begun had it been typeset with \TeXsis: \TeXexample |smalltt\texsis \preprint \pubdate{July 8, 1957} \pubcode{hep-cats/yymmnnn} \titlepage \title Theory of Superconductivity \endtitle \author J.~Bardeen Department of Physics University of Illinois Urbana, Illinois 61801 \endauthor \and \author L.~N.~Cooper Department of Physics and Astronomy The Ohio State University Columbus, OH 43210 \endauthor \and \author J.~R.~Schrieffer Department of Theoretical Physics University of Birmingham Birmingham, England B15 2TT \endauthor \abstract A theory of superconductivity is presented, based on the fact that... \endabstract \toappear{Physical Review} \endtitlepage \section{Introduction} The main facts which a theory of superconductivity must explain are... |endTeXexample \noindent A more complete example paper is given in the file |Example.tex|, which is included in the standard distribution of \TeXsis. In the rest of this section each of the elements in these examples and several others related to the overall structure of a complete paper will be explained. %==================================================* \subsection{Types of Documents \label{sect.types}} A complete \TeXsis\ paper should start with the \cs{texsis} macro described in \Sect{start}. (While this is not required if you also use one of the macros listed below, it does serve to indicate unambiguously that the document is to be typeset with \TeXsis.) The \cs{texsis} macro can be followed by a command to specify whether the document should be typeset as a simple paper or conference proceeding, a preprint, a book, etc. This macro will provide sensible defaults for the layout, although additional commands can be given to override them. The following basic document types are included in \TeXsis: \description{XManuscript\quad}\clump % \itm{\CS{paper}} Produces a paper with the title and abstract at the top of the first page, such as for submission to a conference proceeding. The text begins on the first page, below the title and abstract. % \itm{\CS{preprint}} Produces a paper in a preprint format, with the title material by itself on the first page. A \cs{banner} is put across the top of the title page, and the text begins on the page following. % \itm{\CS{eprint}} Produces a paper in a format suitable for submission to the Los Alamos preprint archives (the ``e-print bulletin boards,'' such as hep-ph, hep-th, hep-lat, or qc-gr). % \itm{\CS{Manuscript}} Similar to \CS{preprint}, but with true double spacing for manuscripts submitted for publication in journals such as the {\sl Physical Review}, which require this. % \itm{\CS{book}} A book or other long document with a separate title page, running headlines, a table of contents, etc. Page numbers are printed in opposite corners on left and right handed pages. % \itm{\CS{thesis}} Similar to \CS{book}, this format is for typesetting a doctoral dissertation or similar document. It may be customized for your own university. % \enddescription After the command defining the type of document you can add optional commands to modify the default layout. For example, you might want to use \example |\texsis| \n |\paper| \n |\hsize=|\meta{dimen} \n |\vsize=|\meta{dimen} \n |\singlespaced| \endexample to produce a single-spaced conference proceeding of a specified size. Macros to create more specialized documents in some of the common formats used by physics journals and conferences are described in \Sect{fmts}. Since \TeXsis\ obviously cannot include all the possible formats, that section also contains some hints about how to modify a format to fit your needs. %==================================================* \subsection{The Title ``Page'' \label{sect.title}} A complete paper almost always starts with a title. Most probably it will also include the names of the authors, and often it will include an abstract. Sometimes the title, author's name(s) and abstract appear on a separate page, while sometimes they simply appear at the top of the first page of the paper. In any case we will refer to all this material together as the ``title page'' material. \TeXsis\ has a standardized method for entering the title page material, whether it will actually appear on a page by itself or not. You begin the title page material with \CS{titlepage} and end it with \CS{endtitlepage}. Between these two control sequences you can use any of the commands listed below to enter the various parts of the title page material. (An example appears at the beginning of this section). \description{Xendauthor}\clump\tolerance=1700 % \itm{\CS{title}} Begins the title of the paper. All lines up to a following \cs{endtitle} are centered and printed in \cs{Tbf} type. Line endings in the input file {\sl are} respected, just as with \cs{obeylines}. % \itm{\CS{author}} Begins an entry for an author's name and address, which should appear on the lines that follow. Line endings in the input file {\it are} respected. The first line to follow is the author's name, which is printed centered in |\bf| type. All subsequent lines are centered in normal type. End with |\endauthor|. % \itm{\CS{and}} Prints the word "and," centered and with appropriate vertical separation. It can be used either between sets of |\author| \dots\ |\endauthor| or between multiple addresses for the same author. % \itm{\CS{authors}} An alternative to |\author| for papers with many authors. Here line endings are not respected; instead, the list of authors is divided into lines as evenly as possible, and each line is centered and printed in Roman type. End with \cs{endauthors}. % \itm{\CS{institution}\arg{symbol}\arg{address}} Prints the symbol and the institution address centered on a line. A |\medskip| is placed before the first address to separate the names and addresses. |\institution| should be placed after the author list but before |\endauthors| to work correctly. % \itm{\CS{abstract}} Begins the abstract. The word "ABSTRACT" is centered above the abstract. The left and right margins are brought in relative to the text of the paper. End with |\endabstract|. % \itm{\CS{pacs}\arg{codes}} Prints the PACS (Physics and Astronomy Classification Scheme) codes on the title page. % \itm{\CS{submitted}\arg{Journal}} Prints the phrase ``Submitted to {\sl Journal}'' centered on the page, with the name of the journal printed in |\sl| type. % \itm{\CS{toappear}\arg{Journal}} Similar to |\submitted|, this prints the phrase ``To appear in {\sl Journal}'' on the title page, with the name of the journal printed in |\sl| type. % \itm{\CS{disclaimer}\arg{contract}} Prints a standard DOE disclaimer for contract number \meta{contract}, printed in 10~pt.\ type, as a footnote. % \enddescription The advantage to entering the title page material this way is that if you change the overall document format, either from \cs{paper} to \CS{preprint} or to one of the more specialized formats described in \Sect{fmts}, then the title page material will automatically be changed to match the document format selected. \bigskip The \cs{banner} macro is called in the \CS{preprint} document format to put the date, a preprint code number, and the name of your institution or organization at the top of the title page. The name of the institution can be changed by saying \example |\def\ORGANIZATION{|\meta{name}|}| \endexample and this change can be made permanent by putting it into the file |TXSsite.tex| when \TeXsis\ is being installed. \def\tmp{}\ifx\ORGANIZATION\tmp (When this manual was printed, the \CS{ORGANIZATION} macro was empty.) \else When this manual was printed, the \CS{ORGANIZATION} macro was: \example \ORGANIZATION \endexample \fi The preprint date and document number can be specified by putting \example\obeylines \CS{pubdate}\arg{date} \CS{pubcode}\arg{code-number} \endexample before the \cs{titlepage}. If these are omitted, the date defaults to the current month and year and the document number defaults either to something set as the default when \TeXsis\ was installed or to the current \TeXsis\ version number. The default at this installation is \ATunlock "\@DOCcode". \ATlock If you really want to customize the look of your paper you can create your own \cs{banner} macro. \bigskip If you are submitting your paper to one of the \idx{preprint archives} at Los Alamos, such as |hep-lat|, |hep-ph|, or |hep-th|, you can have the archive server automatically insert the preprint number it assigns your document when it is submitted. To do this put % Important: putting \relax here and below inhibits any such substitutions % in this manual if it gets put out on such a server. \example \CS{pubcode}|{hep-lat|\relax|/yymmnnn}| \endexample near the top of the document (change ``\idx{hep-lat}'' as appropriate to the archive you are using). When you submit a paper to an archive with the ``put'' command the server will translate any occurrence in the input file of the sequence ``|hep-lat|\relax|/yymmnnn|'' to ``|hep-lat/|'' followed by the 7 digit paper number. You must use the exact string of characters ``|yymmnnn|'' for this to work. When someone else gets your paper from the server and prints a copy it will have the assigned document code in the banner at the top of the title page. \bigbreak The standard \cs{footnote} macro cannot be used to make footnotes to titles and authors's names, because these special fields use internal vertical mode, where footnotes are not allowed. You should instead use the \cs{vfootnote} macro of plain \TeX\ for such purposes. In this case you must put the reference mark in the title or author list yourself (for example, with |${}^*$|), and then say |\vfootnote*{The footnote}| somewhere else on the page, outside of the internal vertical mode material (the author or title blocks). ``Footnotes'' identifying institutions in a long list of authors are often centered on lines immediately below the author list. \CS{authors} and \CS{institution} can be used for this. For example, the author list of one well known paper\reference{DIS} E.D. Bloom, et al., Phys.\ Rev.\ Letters \vol{23}, 930 (1969) \endreference could be typed as follows: \TeXexample |smalltt\authors E.D.~Bloom,$^a$ M.~Breidenback,$^b$ D.H.~Coward,$^a$ H.~DeStaebler,$^a$ J.~Drees,$^a$ J.I.~Friedman,$^b$ G.C.~Hartmann,$^{b,c}$ H.W.~Kendall,$^b$ G.~Miller,$^a$ L.W.~Mo,$^a$ R.E.~Taylor$^a$ \institution{a}{Stanford Linear Accelerator Center, Stanford, CA 94305} \institution{b}{Department of Physics and Laboratory for Nuclear Science, Massachusetts Institute of Technology, Cambridge MA 02139} \institution{c}{Xerox Corporation, Rochester, NY} \endauthors |endTeXexample This produces \authors E.D.~Bloom,$^a$ M.~Breidenback,$^b$ D.H.~Coward,$^a$ H.~DeStaebler,$^a$ J.~Drees,$^a$ J.I.~Friedman,$^b$ G.C.~Hartmann,$^{b,c}$ H.W.~Kendall,$^b$ G.~Miller,$^a$ L.W.~Mo,$^a$ R.E.~Taylor$^a$ \institution{a}{Stanford Linear Accelerator Center, Stanford, CA 94305} \institution{b}{Department of Physics and Laboratory for Nuclear Science, Massachusetts Institute of Technology, Cambridge MA 02139} \institution{c}{Xerox Corporation, Rochester, NY} \endauthors \noindent Note that \cs{institution} must come {\sl before} the \cs{endauthors}. %==================================================* \subsection{Chapters and Sections \label{sect.sects}} The following commands can be used to create and automatically number the divisions of a document, including chapters, sections, and appendices: \singlelinetrue % make label overhang \description{\hskip 3cm}\clump \itm{\CS{chapter}\arg{title}\quad} Begins a chapter with \meta{title} printed in |\Tbf| type on a new page. \itm{\CS{section}\arg{title}\quad} Begins a section with the \meta{title} printed in |\tbf| type. This does {\it not} begin on a new page (although you certainly can start a section on a new page by saying |\vfill\supereject| first.) \itm{\CS{subsection}\arg{title}\quad} Begins a subsection with the \meta{title} printed in |\bf| type. \itm{\CS{subsubsection}\arg{title}\quad} Begins a sub-subsection entitled \meta{title}. This is a lower level than even a subsection and should only be used when truly appropriate. \itm{\CS{Appendix}\arg{label}\arg{title}} Begins a chapter-like appendix labeled by the letter \meta{label} (generally A, B, C, \dots or I, II, III, \dots). The \meta{title} is printed in |\Tbf| type at the top of a new page. \itm{\CS{appendix}\arg{label}\arg{title}} Begins a section-like appendix labeled by the letter \meta{label} (generally A, B, C, \dots or I, II, III, \dots). The \meta{title} is printed in |\tbf| type. \itm{\CS{nosechead}\arg{title}} The \meta{title} is typeset like a subsection headline, but without a subsection number. This is suitable for acknowledgments, lists of references and such. \enddescription The title appears at the top of the section or subsection, left justified in the appropriate typestyle for the document type and with an appropriate amount of vertical spacing below. These and other details of the layout vary with the document format. In general \CS{chapter} is appropriate mainly for books or theses; the manual you are reading now uses only \CS{section} and \CS{subsection} divisions. As you may have noticed from this manual, the first paragraph of a section or subsection is not indented. This is the usual practice for most well-designed books, though it may seem odd at first. It isn't that strange if you think of the indentation of a paragraph as a way to mark a {\sl separation between} paragraphs, rather than as a way to mark the beginning of a paragraph. But if you really want to indent that first paragraph, just begin it with \cs{par}. On the other hand, if you put any kind of commands or macro definitions between the \CS{section} or \CS{subsection} and the first paragraph then this will interfere with the suppression of the indentation. You can easily fix this by either moving your macro definitions elsewhere or putting in a \cs{noindent} by hand. By default chapter, section, and subsection numbers are printed with the titles, and the chapter and section numbers are also attached to equation, figure and table numbers in the form ``$cc.ss.nn$'', where $cc$ is the chapter number, $ss$ the section number, and $nn$ the equation number. The inclusion of the chapter and section numbers can be turned on or off with the commands \description{~showchaptIDfalse\qquad} \itm{\CS{showchaptIDtrue}} Display chapter numbers. \itm{\CS{showchaptIDfalse}} Do not display chapter numbers. \itm{\CS{showsectIDtrue}} Display section numbers. \itm{\CS{showsectIDfalse}} Do not display section numbers. \enddescription \bigskip \CS{Appendix} and \CS{appendix} give chapter-like and section-like appendices, respectively. The chapter or section number is replaced by a letter, which is given as the first argument, and the title, which is the second argument, is printed in the same format as a chapter or section title. For example, \TeXexample \appendix{A}{Review of Functional Integration} |endTeXexample \noindent The letter labeling the appendix is attached to the equation numbers if \CS{showchaptIDtrue} or \CS{showsectIDtrue} is used. You can omit the letter by using an empty first argument, as in \TeXexample \appendix{}{Leading logarithm approximation} |endTeXexample \noindent in which case the result is the same as setting \CS{showchaptIDfalse} or \CS{showsectIDfalse}. \bigskip A skip called \CS{sectionskip} is used before the title of any section-like division (i.e., a |\section| or an |\appendix)|; a skip called \CS{subsectionskip} is used for any lower-level division, that is, a \CS{subsection}, \CS{subsubsection}, or a \CS{nosechead}. Of course these are all removed by \TeX\ if the section starts on a new page. Furthermore, any of these divisions will start on a new page if less than a minimum length given by \CS{sectionminspace} remains on the current page. The defaults for these parameters are \TeXexample \sectionskip=2cm plus 8pt minus 8pt % skip before \section \subsectionskip=1cm plus 4pt minus 4pt % skip before \subsection \sectionminspace=0.25\vsize % new page if less left |endTeXexample but they can be changed to any legal \TeX\ skip or dimension either throughout the document or in a local group. For example, you could use \TeXexample \begingroup \subsectionskip=\sectionskip \fourteenpoint \nosechead{Acknowledgments} \endgroup |endTeXexample to make a \CS{nosechead} which looks like a |\section|. \bigskip Ordinarily the order of appearance of the sections of a document are not changed, so there is no automatic mechanism for labeling the sections. Any of the divisions described above can be labeled by inserting \cs{label}\arg{label} into the title text. The \meta{label} should have the form \meta{type.name}, where \meta{type} is |chap|, |sect|, etc., to avoid possible conflicts with other kinds of labels. The corresponding numbers can then be referred to with |\use{|\meta{type.name}|}|, as described in \Sect{labels}. If the title of a chapter or section is too long, a break in the line can be inserted with the \cs{n} command. This will also break the line in the title when it appears in the table of contents. If running headlines are being used (see \Sect{headline}) then only the first part of the title, up to the \cs{n}, will be used for the running headline. You can always reset the headline by hand with |\setHeadline| (see \Sect{headline}). You can customize the behavior of the section-making macros by adding your own definitions for the macros \index{customization!chapters and sections}% \example \CS{everychapter}, \CS{everysection}, \CS{everysubsection}, \CS{everysubsubsection}, \endexample which are called immediately before making the corresponding division of the document, or for the macros \example \CS{afterchapter}, \CS{aftersection}, \CS{aftersubsection}, \CS{aftersubsubsection}, \endexample which are called immediately afterwards. By default all of these macros do nothing. As an example, if you wanted every section to begin on a new page, and you wanted numbered footnotes created by \cs{NFootnote} to start over counting from one at the begining of each section, you could define: \TeXexample \def\everysection{\vfill\supereject \footnum=0} |endTeXexample The full text of the title of the current chapter, section, and subsection is saved in \CS{ChapterTitle}, \CS{SectionTitle}, and \CS{SubsectionTitle}, so that you may do whatever you want with these later in the chapter or section. An example of how these might be used with \CS{aftersubsection} to change the running headlines is given in \Sect{headline}. Another way you can control the results produced by \CS{chapter} and \CS{section} is to change the way the chapter or section number is printed, by changing the definitions of the macros \CS{ChapterStyle}, \CS{SectionStyle}, or \CS{SubsectionStyle}. These macros take one argument, the chapter or section number, and by default they simply return that argument. By substituting your own definition you can do almost anything you like to the section number. For example, it is often desired that the section number printed as a Roman numeral rather than as an Arabic numeral. The following definition will convert the section number to an upper-case Roman numeral: \TeXexample \def\SectionStyle#1{\uppercase\expandafter{\romannumeral #1}} |endTeXexample Even more customized behavior of the section-making macros is possible. For example, \cs{Tbf} and \cs{tbf} can also be defined as macros which take a single argument, which is arranged to be the title of the section or chapter. To see how this works it may be best to look at the definitions of \CS{chapter} and \CS{section} and the like in the source file |TXSsects.tex|. For very specialized applications you could even copy the definitions in this file to the TXSmods.tex file or your own personal style file and then alter them however you like. %==================================================* \subsection{The Master File} An useful concept for typesetting a long document is that of the\index{master file} {\em Master File}. The idea is to create one small file which initializes \TeXsis\ with \cs{texsis}, makes any special definitions or sets parameters, and then reads in the actual text of the document in sections using the |\input| command. As a simple example consider a manuscript called MUONS. The master file is called |MUONS.tex|, and contains the following: \TeXexample |smalltt\texsis % initialize TeXsis \input MyMacros % special macros for this paper \input MUONSr % references for the paper \input MUONS0 % title page for the paper \input MUONS1 % first section of manuscript \input MUONS2 % second section of manuscript \ListReferences % print the reference list \end |endTeXexample The file |MyMacros.tex| contains any special macro definitions used in this paper. (If there are none, leave this line out.) The file |MUONSr.tex| contains the references used in this paper, beginning with |\referencelist| and ending with |\endreferencelist|, as described in \Sect{refs}. The file |MUONS0.tex| contains the commands for producing the title page of the paper, as described in \Sect{fmts}. The actual text of the manuscript is divided into two parts, which are kept in the files |MUONS1.tex| and |MUONS2.tex|. To process the entire document one simply runs \TeXsis\ on the master file with the command \TeXexample texsis MUONS |endTeXexample \noindent If you are familiar with computer programming you may think of the master file as the main program and the other files as subroutines called by the main program. One of the great advantages of using a master file, aside from keeping the manuscript organized, is that it lets you work on a single section of the paper at a time. For example, suppose you want to run off a draft of just the first section of the paper called MUONS above. You don't need to process the references, the title page, or the second section of the paper. Recall that the percent sign (|%|) is the comment character in \TeX\ --- anything appearing on a line after a |%| is ignored by \TeX. Thus we simply edit the master file and put a |%| in front of certain lines, like this: \TeXexample |smalltt\texsis % initialize TeXsis \draft % optional draft mode \input MyMacros % special macros for this paper % \input MUONSr % references for the paper % \input MUONS0 % title page for the paper \input MUONS1 % first section of manuscript % \input MUONS2 % section section of manuscript % \ListReferences % print the references \end |endTeXexample Now when you run \TeXsis\ on this file only the first section of the paper will be processed, but it will use the macros defined in |MyMacros.tex|, as well as any other definitions that you might add to the master file. Once the first section is error free you can repeat the process on the second section of the paper, without rerunning the first section. After both sections are correct you can reinstate all lines in the master file and process the whole document. %==================================================* \subsection{Table of Contents \label{sect.conts}} The section-making macros just described automatically make an entry in a \idx{table of contents} for the document being prepared. The title of the chapter or section and the page number are stored in a table of contents file (which ends with the extension ``|.toc|'') until needed, then the table of contents is created simply by saying \CS{Contents}. If your document is divided into chapters, like a book, the table of contents should appear on a page with a Roman numeral page number (which is obtained by setting \cs{pageno} to a negative value). For example: \TeXexample \book % document format for a book \input Chapt1 % input chapters... ... \vfill\supereject % eject last page, including figures \pageno=-3 % print on pages iii, iv, ... \nosechead{Contents} % label TOC without section # \Contents % generate table of contents |endTeXexample The table of contents is usually printed at the {\sl end\/} of the document so that all the page numbers are correct. You then simply move these pages to the front of the document by hand. Alternately, you can say \CS{Contents} at the beginning of your document to read in the table of contents file produced by a previous run of \TeXsis, although then you must process the document twice to be sure that the page numbers are correct. It is important to note that nothing is written to the table of contents file unless \CS{Contentstrue} is set. The default for most documents is \CS{Contentsfalse}, since one usually does not want a table of contents for a short paper or a memo or a letter. The exceptions are \cs{book} and \cs{thesis}, which automatically set \CS{Contentstrue}. In any case, if you want a table of contents you can explicitly state \CS{Contentstrue}. While an entry in the table of contents is created by \cs{chapter} or \cs{section}, no entry is made for \cs{nosechead}. In this case, or in any case, you can insert an entry into the table of contents ``by hand'' by saying \example \CS{addTOC}\arg{level}\arg{title}\arg{page} \endexample where \meta{level} is the level of division for the entry being made, with 0 for chapters, 1 for sections and 2 for subsections. This controls how much vertical space is put around the table of contents entry and how much the entry is indented in the list. % The \meta{title} is the text of the title as it should appear in the table of contents. Text which is too long for one line will be split over several lines, but you can force a line break where you want one with \cs{n}. The \meta{page} is the page number for the entry you are making. Generally you'll use \cs{folio} here to just use the current page number, whatever that may be. Thus to make a section level entry in the table of contents having the title ``Acknowledgments'' you would simply say \TeXexample \addTOC{1}{Acknowledgments}{\folio} |endTeXexample Entries made in the table of contents by \cs{chapter}, \cs{section}, etc. will optionally begin with the chapter or section number, depending upon whether \cs{showchaptIDtrue} and \cs{showsectIDtrue} are selected. The decision whether or not to show the chapter or section number is made when the table of contents is printed by \CS{Contents}, not when the \cs{chapter} or \cs{section} is begun. Thus it is possible to have the section numbers showing at the beginning of the section, but to then have no section numbers in the table of contents by saying \cs{showsectIDfalse} immediately before saying \CS{Contents}. \bigbreak It is possible to write commands or other text to the table of contents file while it is being created, using the command \CS{TOCwrite}\arg{stuff}. For example, the heading separating the appendices from the rest of the entries in the table of contents of this Manual was created by saying \TeXexample \TOCwrite{\bigskip\noexpand\nosechead{Appendices:}} |endTeXexample \noindent before the appendices were created. The \cs{noexpand} prevents the |\nosechead| from being expanded until later, after the table of contents file is read back in by \CS{Contents} \bigbreak What if you want the table of contents to appear in the table of contents itself!? Naturally it should appear first (even though it may be printed at the end of the document). You can use the tagging mechanism described in \Sect{labels} to make a ``forward reference'' to the page number. At the beginning of the document you can create the table of contents entry by saying \TeXexample \addTOC{0}{Table of Contents}{\noexpand\use{page.TOC}} |endTeXexample \noindent The \cs{noexpand} prevents the \cs{use} from being expanded until later, after the table of contents file is read back in. Later, when you actually print the table of contents you would first tag the page number, then invoke \CS{Contents}, like so: \TeXexample \nosechead{Table of Contents} \tag{page.TOC}{\folio} \Contents |endTeXexample \Ignore % NO, WE DON'T DO IT \noindent As a demonstration of this we have done this for the table of contents for this manual. For more information about \cs{tag} and \cs{use} see \Sect{labels}.\relax \endIgnore %======================================================================* \subsection{Running Headlines and Footlines \label{sect.headline}} In Plain \TeX, whenever a page is output an optional headline and footline are added at the top and bottom of the page. In \TeXsis\ the footline is normally blank, while the headline contains the page number in the upper right corner. The \cs{book} and \cs{thesis} formats also display a running headline, centered in 10~pt.\ italic type, containing the chapter or section title. Running headlines and page numbers are {\bf not} printed on any page containing a \cs{title} or a new \cs{chapter}. For an example of running headlines look at the top of any page in this Manual. \CS{nopagenumbers} turns off the running headlines and footlines, just as it does in Plain \TeX. In \TeXsis\ saying \CS{pagenumbers} restores the standard headlines and footlines. Saying \CS{bookpagenumbers} puts odd page numbers in the upper right corner and even page numbers in the upper left corner, the normal convention for books. This is the default for \cs{book}. \CS{RunningHeadstrue}, the default for \cs{book} (and \cs{thesis}), displays the running headline text \cs{HeadText}, as well as the page number. |\RunningHeadsfalse| turns off the running headlines but leaves the page numbers. \cs{HeadText} is defined by \cs{chapter} to be the chapter title in 10~pt.\ italic type; if no chapters are used, then it is defined by \cs{section} to be the section title. You can change the running headline yourself with the command \CS{setHeadline}\arg{text}. For example, the headline at the top of this page could have been created by saying \example\tt \CS{setHeadline}|{|\HeadText|}| \endexample The headline text appears in typestyle \CS{HeadFont}, which you can change to suit your tastes. The default is |\tenit|, but for this manual we used |\def\HeadFont{\tensl}|. Running headlines are not normally affected by \cs{subsection}, but it is easy to have each subsection change the runing headlines by defining \cs{aftersubsection} to include a \CS{setHeadline} command. As a useful example, suppose that each subsection is to have a running headline composed of both the title of the section and the title of the subsection. You could have this done automatically by defining something like: \TeXexample \def\aftersubsection{\setHeadline{\SectionTitle: \SubsectionTitle}} |endTeXexample The rest of this section will have such running headlines as an example. \def\aftersubsection{\setHeadline{\SectionTitle: \SubsectionTitle}} \bigskip %<-- needed to force page break before next section! %======================================================================* \subsection{How to Make an Index \label{sect.index}} The traditional way to make an index for a book was to write key~words on 3$\times$5 ``index'' cards, and to then write on these card the numbers of the pages on which the key words occurred. The cards were then sorted by hand and then their contents also sorted and typed in order to make the index. This was a tedious and time consuming task. Fortunately this whole process has been modernized so that an index can be made almost automatically. Still, it takes a certain amount of care to create a useful, well constructed index. An important part of designing a good index is deciding which key~words will be useful in the index and which key~words will not. A computer cannot make these decisions for you. Making an index with \TeX\ still involves collecting the index entries, sorting them (and removing duplicate references), and then producing the final index. The first and last steps are accomplished with a set of plain \TeX\ macros known as |index.tex|, while the sorting and collating of the index entries is done by a separate computer program called |makeindex|.\index{makeindex}\ This is how we made the index for this Manual, which starts on page~\use{pg.index}. To create an entry in the index you can say \CS{index}\arg{key}, where \meta{key} is the key~word to be entered into the index, or more simply you can say \CS{idx}\arg{word}, which both includes the word in the text and makes an index entry for it; saying ``\CS{idx}|{Frisbee}|'' is the same as saying ``|Frisbee|\CS{index}|{Frisbee}|''. Either of these indexing commands writes the index entry to a file with the name extension ``|.idx|''. Once your document has been processed by \TeX\ this file will contain all of the ``raw'' index entries. The entries in the raw index file are not sorted, and there may be many duplications. The |makeindex|\index{makeindex} program will sort the index entries and reformat them in a form appropriate for printing the index. The output from the |makeindex| program is a file with the extension ``|.ind|''. So if your manuscript file is called |myfile.tex| and you have run it through \TeXsis\ you should find a file called |myfile.idx| containing the raw index entries. You would run the |makeindex| program like so, \example |makeindex myfile.idx| \endexample to produce the processed index file |myfile.ind|. (You can leave off the |.idx| extension for the raw file and |makeindex| will assume it.) To print the index you can either include it in another pass of the full document, by saying \TeXexample \input \jobname.ind |endTeXexample \noindent in the manuscript file, or you can print it separately by adding ``|\input index|'' to the begining of the |myfile.ind| file and running it through \TeX\ or \TeXsis. If you set \CS{markindextrue} then indexed words selected with \CS{idx} will appear in the printed output inside a ruled box like so: \begingroup \markindextrue \idx{Frisbee}. \endgroup The box does not interfere with or change the word or line spacing. These ``proof marks'' are useful for draft copies when you are putting together the index, but obviously you do not want them to appear in the final copy, so the default is |\markindexfalse|. The |index.tex| macros are distributed with \TeXsis, but |makeindex| is not. If you do not have the |makeindex| program you can get the C source code for it from the \TeXsis\ anonymous ftp site, |ftp.texsis.org|. It is a well-known program, and is also available from CTAN in the directory {\tt indexing/makeindex}. Note that the |index.tex| macros work with plain \TeX\ as well as \TeXsis, and they work with |makeindex| in its default mode, even though that default mode was originally intended for \LaTeX\ code. For more information about how to make full use of |makeindex| see the file |index.tex|, the Unix man page for makeindex(1), and the original paper by Chen and Harrison\reference{makeindex} Pehong Chen and Michael A. Harrison, ``Index Preparation and Processing'', in {\sl Software: Practice and Experience}, \vol{19}, 897-915 (1988) \endreference describing how they designed the |makeindex| program. \def\aftersubsection{\relax} %>>> EOF TXSsects.doc <<<