diff options
Diffstat (limited to 'Master/texmf-dist/doc/texsis/base/TXSsects.doc')
| -rw-r--r-- | Master/texmf-dist/doc/texsis/base/TXSsects.doc | 899 |
1 files changed, 899 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/texsis/base/TXSsects.doc b/Master/texmf-dist/doc/texsis/base/TXSsects.doc new file mode 100644 index 00000000000..34263d458f4 --- /dev/null +++ b/Master/texmf-dist/doc/texsis/base/TXSsects.doc @@ -0,0 +1,899 @@ +%% 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 <<< |