diff options
author | Karl Berry <karl@freefriends.org> | 2009-05-24 00:31:38 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2009-05-24 00:31:38 +0000 |
commit | 3db8854079e5f66bff8e115d3e53b74a9e6b1b94 (patch) | |
tree | c76f77b61118c210746b2b9a513369908249ae7e /Master/texmf-dist/doc/texsis/base/TXSsects.doc | |
parent | 631b5bbb9b2878fe0c658883d594124839413456 (diff) |
move doc for lesser-used formats to subdirs
git-svn-id: svn://tug.org/texlive/trunk@13440 c570f23f-e606-0410-a88d-b1316a301751
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, 0 insertions, 899 deletions
diff --git a/Master/texmf-dist/doc/texsis/base/TXSsects.doc b/Master/texmf-dist/doc/texsis/base/TXSsects.doc deleted file mode 100644 index 34263d458f4..00000000000 --- a/Master/texmf-dist/doc/texsis/base/TXSsects.doc +++ /dev/null @@ -1,899 +0,0 @@ -%% 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 <<< |