diff options
Diffstat (limited to 'info/impatient/pages.tex')
| -rw-r--r-- | info/impatient/pages.tex | 1153 |
1 files changed, 1153 insertions, 0 deletions
diff --git a/info/impatient/pages.tex b/info/impatient/pages.tex new file mode 100644 index 0000000000..230802e9b5 --- /dev/null +++ b/info/impatient/pages.tex @@ -0,0 +1,1153 @@ +% This is part of the book TeX for the Impatient. +% Copyright (C) 2003 Paul W. Abrahams, Kathryn A. Hargreaves, Karl Berry. +% See file fdl.tex for copying conditions. + +\input macros +\chapter {Commands for \linebreak composing pages} + +\chapterdef{pages} + +This section covers commands that deal with +pages, their components, and the output routine. +For an explanation of the conventions used in this section, +see \headcit{Descriptions of the commands}{cmddesc}. + +\begindescriptions + +%========================================================================== +\section {Interline and interparagraph spaces} + +\begindesc +\cts baselineskip {\param{glue}} +\cts lineskiplimit {\param{dimen}} +\cts lineskip {\param{glue}} +\explain +^^{line spacing} +\bix^^{interline glue} +\bix^^|\baselineskip| +\bix^^|\lineskip| +\bix^^|\lineskiplimit| +These three parameters jointly determine how much space \TeX\ leaves between +consecutive \minref{box}es of an ordinary \minref{vertical list}, +e.g., the lines of a paragraph. +This space is called ``\minref{interline glue}''. +It is also inserted between the component boxes of a vbox constructed in +internal vertical mode. +^^{vboxes//interline glue for} + +In the usual case, when the boxes aren't abnormally high or deep, \TeX\ +makes the distance from the baseline of one box to the baseline of the +next one equal to |\baselineskip|. It does this by inserting interline +glue equal to |\baselineskip| minus the depth of the upper box (as given +by ^|\prevdepth|) and the height of the lower box. But if this +interline glue would be less than |\lineskiplimit|, indicating that the +two boxes are too close together, \TeX\ inserts the |\lineskip| glue +instead.\footnote +{\TeX\ actually accounts for the beginning of a +vertical list by setting |\prevdepth| to $-1000$\pt\ and testing +|\prevdepth| before \emph{every} box. If |\prevdepth|$\>\le-1000$\pt\ +it does not insert any interline glue.} See \knuth{pages~79--80} for a +precise description. + +Note that |\baselineskip| and |\lineskip| measure \emph{different +things}: the distance between baselines on the one hand and the distance +between the bottom of one box and the top of the next box on the other +hand. See \knuth{page~78} for further details. The first example below +shows the effects of |\lineskiplimit|. + +You can obtain the effect of ^{double spacing} by doubling the value +of |\baselineskip| as illustrated in the second example below. +A change to |\baselineskip| at any point before the end of a paragraph affects +the entire paragraph. + +\example +\baselineskip = 11pt \lineskiplimit = 1pt +\lineskip = 2pt plus .5pt +Sometimes you'll need to typeset a paragraph that has +tall material, such as a mathematical formula, embedded +within it. An example of such a formula is $n \choose k$. +Note the extra space above and below this line as +compared with the other lines. +(If the formula didn't project below the line, +we'd only get extra space above the line.) +| +\produces +\baselineskip = 11pt \lineskiplimit = 1pt +\lineskip = 2pt plus .5pt +Sometimes you'll need to typeset a paragraph that has +tall material, such as a mathematical formula, embedded +within it. An example of such a formula is $n \choose k$. +Note the extra space above and below this line as +compared with the other lines. +(If the formula didn't project below the line, +we'd only get extra space above the line.) +\endexample + +\example +\baselineskip = 2\baselineskip % Start double spacing. +| +\endexample + +\eix^^{interline glue} +\eix^^|\baselineskip| +\eix^^|\lineskip| +\eix^^|\lineskiplimit| +\enddesc + +\begindesc +\cts prevdepth {\param{dimen}} +\explain +When \TeX\ adds a box to a vertical list, it sets |\prevdepth| to the +depth of that box. \TeX\ sets |\prevdepth| to $-1000$\pt\ at the start +of a vertical list, indicating that the usual interline glue should be +suppressed. +\enddesc + +\begindesc +\cts normalbaselineskip {\param{glue}} +\cts normallineskiplimit {\param{dimen}} +\cts normallineskip {\param{glue}} +\cts normalbaselines {} +\explain +The three parameters contain values for |\base!-line!-skip|, +|\line!-skip|, and |\line!-skip!-limit| respectively. +^^|\baselineskip| ^^|\lineskip| ^^|\lineskiplimit| +The |\normalbaselines| command sets |\base!-line!-skip|, +|\line!-skip|, and |\line!-skip!-limit| to the values contained in the +three parameters. +\enddesc + +\begindesc +\cts offinterlineskip {} +\explain +This command tells \TeX\ to stop inserting interline glue from +now on. Unless you want it to be in effect for the rest of the document +(which you probably don't), you should enclose it in a group +together with the text you want it to affect. +Its main purpose is to let you do interline spacing yourself, +e.g., using ^{struts}, +without interference from \TeX's normal interline glue. +|\offinterlineskip| is often useful when +you're constructing a horizontal \minref{alignment}. +^^{alignments//using \b\tt\\offinterlineskip\e\ in} +\example +\def\entry#1:#2 {\strut\quad#1\quad&\quad#2\quad\cr} +\offinterlineskip \tabskip = 0pt \halign{% +\vrule\quad\hfil#\hfil\quad\vrule& + \quad\hfil#\hfil\quad\vrule\cr +\noalign{\hrule} +\vphantom{\vrule height 2pt}&\cr \noalign{\hrule} +\entry \it Opera:\it Composer +\vphantom{\vrule height 2pt}&\cr \noalign{\hrule} +\vphantom{\vrule height 2pt}&\cr +\entry Fidelio:Beethoven +\entry Peter Grimes:Britten +\entry Don Giovanni:Mozart +\vphantom{\vrule height 2pt}&\cr \noalign{\hrule}} +| +\produces +\medskip +\def\entry#1:#2 {\strut\quad#1\quad&\quad#2\quad\cr} +\offinterlineskip \tabskip = 0pt \halign{% +\vrule\quad\hfil#\hfil\quad\vrule& + \quad\hfil#\hfil\quad\vrule\cr +\noalign{\hrule} +\vphantom{\vrule height 2pt}&\cr \noalign{\hrule} +\entry \it Opera:\it Composer +\vphantom{\vrule height 2pt}&\cr \noalign{\hrule} +\vphantom{\vrule height 2pt}&\cr +\entry Fidelio:Beethoven +\entry Peter Grimes:Britten +\entry Don Giovanni:Mozart +\vphantom{\vrule height 2pt}&\cr \noalign{\hrule}} +\endexample +\enddesc + +\begindesc +\cts nointerlineskip {} +\explain +This command tells \TeX\ not to insert interline glue in front of the +next line. +It has no effect on subsequent lines. +\enddesc + +\begindesc +\cts openup {\<dimen>} +\explain +This command increases ^|\baselineskip| by \<dimen>. +An |\openup| command before the end of a paragraph affects +the entire paragraph, so you shouldn't use |\openup| to +change |\baseline!-skip| within a paragraph. |\openup| is +most useful for typesetting tables and math displays---a +little extra space between rows often makes them more readable. +^^{alignments//space between rows of} +\example +Alice picked up the White King very gently, and lifted him +across more slowly than she had lifted the Queen; but before +she put him on the table, she thought she might well dust +him a little, he was so covered with ashes. +\openup .5\baselineskip % 1.5 linespacing. +| +\produces +Alice picked up the White King very gently, and lifted him +across more slowly than she had lifted the Queen; but before +she put him on the table, she thought she might well dust +him a little, he was so covered with ashes. +\openup .5\baselineskip %1.5 linespacing +\endexample\enddesc + +%========================================================================== +\section {Page breaks} + +%========================================================================== +\subsection {Encouraging or discouraging page breaks} + +\begindesc +\bix^^{page breaks} +\bix^^{page breaks//encouraging or discouraging} +\ctspecial break {} \xrdef{vbreak} +\explain +% +\margin{Four commands identical to ones for line breaks (\xref{hbreak}) +have been added to correct an omission. The descriptions are exactly parallel.} +% +This command forces a page break. +Unless you do something to fill out the page, you're likely to +get an underfull vbox. +|\break| can also be used in horizontal mode. +\enddesc + +\begindesc +\ctspecial nobreak {} \xrdef{vnobreak} +\explain +This command prevents a page break where it +otherwise might occur. +|\nobreak| can also be used in horizontal mode. +\enddesc + +\begindesc +\ctspecial allowbreak {} \xrdef{vallowbreak} +\explain +This command tells \TeX\ to +allow a page break where one could not ordinarily occur. +|\allowbreak| can also be used in horizontal mode. +\enddesc + +\begindesc +\ctspecial penalty {\<number>} \xrdef{vpenalty} +\explain +This command produces a \minref{penalty} item. +The penalty item makes \TeX\ more or less willing to break a page +at the point where that item occurs. +A negative penalty, i.e., a bonus, encourages a page break; +a positive penalty discourages a page break. +A penalty of $10000$ or more prevents a break altogether, +while a penalty of $-10000$ or less forces a break. +|\penalty| can also be used in horizontal mode. +\example +\def\break{\penalty-10000 } % as in plain TeX +\def\nobreak{\penalty10000 } % as in plain TeX +\def\allowbreak{\penalty0 } % as in plain TeX +| +\endexample +\enddesc + +\begindesc +\cts goodbreak {} +\explain +This command ends a paragraph and also indicates to \TeX\ that +this is a good place to break the page. +\enddesc + +\begindesc +\cts smallbreak {} +\cts medbreak {} +\cts bigbreak {} +\explain +These commands indicate increasingly desirable places for \TeX\ to +break a page. They also cause \TeX\ to +insert a ^|\smallskip|, ^|\medskip|, or +^|\bigskip| (\xref \smallskip) if the page break doesn't actually +happen. \TeX\ suppresses this skip if it occurs just after an +equal or larger skip. +\enddesc + +\begindesc +\easy\cts eject {} +\cts supereject {} +\explain +These commands force a page break at the current position +and end the current paragraph. +If you don't precede them with |\vfil| (\xref \vfil), +^^|\vfil//needed with {\tt\\eject}| +\TeX\ will try to stretch out the page contents +(and will probably complain about an underfull vbox). +The |\supereject| command, in addition, +instructs the \plainTeX\ output routine to +force out any leftover insertions, +^^{insertions//forced out by \b\tt\\supereject\e} +such as long footnotes, +so that they are produced before any more input +is processed. Thus |\supereject| is a good command to use at the end of each +chapter or other major unit of your document. +\enddesc + +\begindesc +\cts filbreak {} +\explain +This command provides a kind of conditional page break. +It tells \TeX\ to +break the page---but not if the text up to a later |\filbreak| also +fits on the same page. +By enclosing a paragraph in a pair of |\filbreak|s, +you can ensure that \TeX\ will keep a paragraph on a single page if it can. +You should not use |\filbreak| within a paragraph, since it +forces \TeX\ into vertical mode and thus ends the paragraph. +See \xrefpg{filbreak} for more advice on this subject. +\enddesc + +\begindesc +\cts raggedbottom {} +\cts normalbottom {} +\explain +Normally \TeX\ tries hard to ensure that all pages have the same depth, +i.e., that their bottom margins are equal. +The |\raggedbottom| command tells \TeX\ to +allow some variability among the bottom margins on different pages. +It's often appropriate to use |\raggedbottom| when you have material that +contains large blocks of material that should not be split across pages. +The |\normalbottom| command cancels the effect of |\raggedbottom|. + +\eix^^{page breaks//encouraging or discouraging} +\enddesc + +%========================================================================== +\subsection {Page breaking parameters} + +\bix^^{page breaks//parameters for} +\begindesc +\cts interlinepenalty {\param{number}} +\explain +This parameter specifies the \minref{penalty} for +breaking a page between the lines of a paragraph. +By setting it to $10000$ you can force all page breaks to occur +between paragraphs, provided that the pages have enough stretch so +that \TeX\ can still compose them decently. +\PlainTeX\ leaves |\inter!-linepenalty| at~$0$. +\enddesc + +\begindesc +\cts clubpenalty {\param{number}} +\explain +^^{club line} +This parameter specifies the \minref{penalty} for +breaking a page just after the first line of a paragraph. +A line by itself at the bottom of a page is called a ``club line''. +\PlainTeX\ sets |\clubpenalty| to $150$. +\enddesc + +\begindesc +\cts widowpenalty {\param{number}} +\explain +^^{widow line} +This parameter specifies the \minref{penalty} for +breaking a page just before the last line of a paragraph. +A line by itself at the top of a page is called a ``widow line''. +\PlainTeX\ sets |\widowpenalty| to $150$. +\enddesc + +\begindesc +\cts displaywidowpenalty {\param{number}} +\explain +^^{widow line}^^{math display} +This parameter specifies the \minref{penalty} for +breaking a page just before the last line of a partial paragraph +that immediately precedes a math display. +\PlainTeX\ sets |\displaywidowpenalty| to $50$. + +\enddesc + +\begindesc +\cts predisplaypenalty {\param{number}} +\explain +^^{math display} +This parameter specifies the \minref{penalty} for +breaking a page just before a math display. +\PlainTeX\ sets |\predisplaypenalty| to $10000$. +\enddesc + +\begindesc +\cts postdisplaypenalty {\param{number}} +\explain +^^{math display} +This parameter specifies the \minref{penalty} for +breaking a page just after a math display. +\PlainTeX\ leaves |\postdisplaypenalty| at $0$. +\enddesc + +\begindesc +\cts brokenpenalty {\param{number}} +\explain +This parameter specifies the \minref{penalty} for +breaking a page just after a line that ends in +a discretionary item (usually a hyphen). +^^{hyphenation} +|\brokenpenalty| applies to page breaking, while +^|\hyphenpenalty| \ctsref{\hyphenpenalty} applies to line breaking. +\PlainTeX\ sets |\brokenpenalty| to $100$. +\enddesc + +\begindesc +\cts insertpenalties {\param{number}} +\explain +\bix^^{insertions//penalties for} +\bix^^{floating material} +This parameter contains the sum of certain penalties \minrefs{penalty} +that \TeX\ accumulates as it is placing insertions onto the +current page. +These penalties are incurred when \TeX\ is processing an |\insert| +command +and discovers that a previous insertion of the same kind on this page has +been split, leaving part of it for subsequent pages. +See \knuth{pages~123--125} for the details of this +calculation. + +\margin{Material moved from a footnote to the main text.} +|\insertpenalties| has an entirely different meaning during an +^^{output routine//meaning of \b\tt\\insertpenalties\e\ in} +output routine---it's the number of insertions that have been seen +but that don't fit on the current page (see \knuth{page~125}). +\enddesc + +\begindesc +\cts floatingpenalty {\param{number}} +\explain +This parameter specifies the \minref{penalty} that +\TeX\ adds to |\insertpenalties| +^^|\insertpenalties| +when the page builder is adding an insertion to the current page +and discovers that a previous insertion of the same kind on this page has +been split, leaving part of it for subsequent pages. +\PlainTeX\ leaves |\floatingpenalty| at~$0$. +\eix^^{insertions//penalties for} +\eix^^{floating material} + +\enddesc + +\begindesc +\cts pagegoal {\param{dimen}} +\explain +This parameter specifies the +desired height for the current page. +\TeX\ sets +|\pagegoal| to the current value of |\vsize| +when it first puts a box or an insertion on the current page. +You can shorten a page while \TeX\ is working on it by +changing the value of |\pagegoal|---even if the new value is +less than the height of the material already on that page. +\TeX\ will just put the extra material on the next page. +But remember---|\pagegoal| is reset to |\vsize| again when \TeX\ +starts the next page. +\enddesc + +\begindesc +\cts pagetotal {\param{dimen}} +\explain +This parameter specifies the +accumulated natural height of the current page. +\TeX\ updates |\pagetotal| as it adds +items to the main \minref{vertical list}. + + +\enddesc + +\begindesc +\cts pagedepth {\param{dimen}} +\explain +This parameter specifies the depth of the current page. +\TeX\ updates |\pagedepth| as it adds +items to the main \minref{vertical list}. +\enddesc + +\begindesc +\cts pageshrink {\param{dimen}} +\explain +This parameter specifies the amount of \minref{shrink} +in the accumulated \minref{glue} on the current page. +\TeX\ updates |\pageshrink| as it adds +items to the main \minref{vertical list}. +\enddesc + +\begindesc +\cts pagestretch {\param{dimen}} +\cts pagefilstretch {\param{dimen}} +\cts pagefillstretch {\param{dimen}} +\cts pagefilllstretch {\param{dimen}} +\explain +These four parameters together specify the amount of \minref{stretch} +in the \minref{glue} on the current page. The amount of stretch has +the form +{\def\f#1{\hbox{\tt fi#1}}% +$n_0 + n_1\f{l} + n_2\f{ll} + n_3\f{lll}$}, with the four parameters +giving the values of the four $n_i$. +\TeX\ updates these parameters as it adds +items to the main \minref{vertical list}. + +\eix^^{page breaks//parameters for} +\eix^^{page breaks} +\enddesc + +%========================================================================== +\section{Page layout} + +\subsection {Page description parameters} + +\begindesc +\bix^^{page dimensions} +\margin{This command was also described in the `Paragraphs' section. +The combined description now appears there.} +\aux\cts hsize {\param{dimen}} +\explain +This parameter specifies the current line length. +See \xrefpg{\hsize} for a more complete explanation. +\enddesc + +\begindesc +\cts vsize {\param{dimen}} +\explain +This parameter specifies the current vertical extent of a page. +\TeX\ examines it only when it is starting a page. Thus if you change +|\vsize| in the +middle of a page, your change won't affect anything until the following page. +If you want to change the vertical extent of a page when +you're in the middle of it, you should assign the new +height to ^|\pagegoal| (\xref \pagegoal) instead. (If you +want the change to affect the following pages too, you should +change \emph{both} |\vsize| and |\pagegoal|.) +\PlainTeX\ sets |\vsize| to |8.9in|. +\eix^^{page dimensions} +\enddesc + +\begindesc +\cts hoffset {\param{dimen}} +\cts voffset {\param{dimen}} +\margin{These commands were moved up from later in the subsection.} +^^{page origin} +\idxsee{origin}{page origin} +\explain +\TeX\ normally takes the ``origin'' of a page, that is, the point where +it starts printing, as being one inch down from the top of the page and one +inch to the right of the left end of the page.\footnote{ +\TeX\ itself is indifferent to where the origin of the page is, +but this information has to be built into the device drivers +^^{device drivers//page origin known to} +that convert \dvifile s into printable form so that different devices +will yield the same results.} +The values of |\hoffset| and +|\voffset| give the horizontal and vertical offset of the actual origin +from this point. Thus if |\hoffset| and |\voffset| are both +zero, \TeX\ uses its normal origin. +\example +\hoffset = -.3in + % Start printing .7 inches from left edge of paper. +\voffset = 1in + % Start printing 2 inches from top edge of paper. +| +\endexample +\enddesc + +\begindesc +\cts topskip {\param{glue}} +\explain +\TeX\ inserts glue at the top of each +page in order to ensure that the baseline of the first box on the page +always is the same distance $d$ from the top of the page. +|\topskip| determines the amount of that glue, +called the ``|\topskip| glue'', by specifying +what $d$ should be (provided that the first box +on the page isn't too tall). +$d$ is given by the natural size of the |\topskip| glue. +If the height of the first box on the page exceeds $d$, +so that the glue would be negative, \TeX\ simply inserts no +|\topskip| glue at all on that page. + +To understand better the effect of these rules, assume that |\topskip| +has no stretch or shrink and that the first item on the page is indeed a box. +Then if the height of that box is no greater than |\topskip|, +its baseline will be |\topskip| +from the top of the page independently of its height. On the other hand, +if the height of the box is $e$ greater than |\topskip|, its baseline will be +|\topskip|\tplus$e$ from the top of the page. +See \knuth{pages~113--114} for the remaining details of how +|\topskip| works. +\PlainTeX\ sets |\topskip| to |10pt|. +\enddesc + + +\begindesc +\cts parskip {\param{glue}} +\explain +This parameter specifies the ``^{paragraph skip}'', i.e., the +vertical glue that \TeX\ inserts at the start of a paragraph. +^^{paragraphs//glue between} +See |\par| (\xref{\@par}) for more information about what happens +when \TeX\ starts a paragraph. +\PlainTeX\ sets |\parskip| to |0pt plus 0.1pt|. +\enddesc + +\begindesc +\cts maxdepth {\param{dimen}} +\explain +This parameter specifies the maximum depth of the bottom \minref{box} on +a page. It is related to |\boxmaxdepth| (\xref \boxmaxdepth). If the +depth of the bottom box on a page exceeds |\maxdepth|, \TeX\ moves the +box's reference point down so that it's +|\maxdepth| from the bottom of that box. +Without this adjustment, the bottom box on +a page could extend well into the bottom margin or even off +the page entirely. \PlainTeX\ sets |\maxdepth| to |4pt|. +\enddesc + +%========================================================================== +\subsection{Page numbers} + +\begindesc +\bix^^{page numbering} +\cts pageno {\param{number}} +\explain +This parameter contains the current page number as an integer. The page +number is normally negative for front-matter pages that are numbered +with small roman numerals instead of arabic numerals. If you change the +page number within a page, +the changed number will be used in any headers or footers that +appear on that page. +The actual +printing of page numbers is handled by \TeX's \minref{output routine}, +which you can modify. + +\PlainTeX\ keeps the page number in the \minref{register} ^|\count0|. +(|\pageno| is, in fact, a synonym for |\count0|.) +Whenever it ships out a page to the \dvifile, +^^|\shipout//{\tt\\count} registers displayed at| +\TeX\ displays the current value of |\count0| on your +terminal so that you can tell which page it is working on. +It's possible to use registers |\count1|--|\count9| for nested +levels of page numbers (you must program this yourself). +If any of these registers are nonzero, \TeX\ displays them on your +terminal also.\footnote{ +More precisely, it displays all registers in sequence from +|\count0| to |\count9|, but omits trailing zero registers. +For instance, if the values of |\count0|--|\count3| +are $(17, 0 , 0, 7)$ and the others are $0$, +\TeX\ displays the page number as {\tt [17.0.0.7]}.} +\example +This explanation appears on page \number\pageno\ +of our book. +| +\produces +This explanation appears on page \number\pageno\ +of our book. + +\nextexample +\pageno = 30 % Number the next page as 30. +Don't look for this explanation on page \number\pageno. +| +\produces +Don't look for this explanation on page 30. +\endexample +\enddesc + +\begindesc +\cts advancepageno {} +\explain +This command adds $1$ to the page number +$n$ in |\pageno| if $n\ge0$ +and subtracts $1$ from it if $n<0$. +\enddesc + +\begindesc +\easy\cts nopagenumbers {} +\explain +By default, \plainTeX\ produces a footer containing a centered page number. +This command tells \TeX\ to produce a blank footer instead. +\enddesc + +\begindesc +\cts folio {} +\explain +This command produces the current page number, whose value is the number +$n$ contained in ^|\pageno|. +If $n\ge0$, +\TeX\ produces $n$ as a decimal number, +while if $n<0$, +\TeX\ produces $-n$ in lowercase roman numerals. +\example +This explanation appears on page \folio\ of the book. +| +\produces +This explanation appears on page \folio\ of the book. +\endexample + +\eix^^{page numbering} +\enddesc + + +%========================================================================== +\subsection{Header and footer lines} + +\begindesc\secondprinting{\vglue-.75\baselineskip\vskip0pt} +\cts headline {\param{token list}} +\cts footline {\param{token list}} +\explain +These parameters +contain, respectively, the current headline (header) and the current +footline (footer). +The \plainTeX\ output routine +places the headline at the top of each page and the footline +at the bottom of each page. +The default headline is empty and the default footline is a centered +page number. + +The headline and footline should both +be as wide as |\hsize| (use |\hfil|, \xref{\hfil}, for this +if necessary). +You should always include a font-setting command in these lines, since +the current font is unpredictable when \TeX\ is calling the +output routine. If you don't set the font explicitly, +you'll get whatever font \TeX\ was using when it broke the page. + +You shouldn't try to use |\headline| or |\footline| +to produce multiline headers or footers. +Although \TeX\ won't complain, it will give you something that's very ugly. +See \xrefpg{bighead} for a method of creating multiline headers or +footers. +\example +\headline = {\tenrm My First Reader\hfil Page \folio} +| +\produces +\pageno = 10 +\line{\tenrm \noindent My First Reader\hfil Page \folio} +\par ({\it at the top of page \folio}\/) +\nextexample +\footline = {\tenit\ifodd\pageno\hfil\folio + \else\folio\hfil\fi} +% Produce the page number in ten-point italic at +% the outside bottom corner of each page. +| +\endexample\enddesc + +\secondprinting{\vfill\eject} + + +%========================================================================== +\subsection {Marks} + +\begindesc +\cts mark {\rqbraces{\<text>}} +\explain +\bix^^{marks} +This command causes \TeX\ to append a mark +containing \<mark text> +to whatever list it is currently constructing. +Generally you shouldn't use |\mark| within an +``inner'' construct such as a math formula or a \minref{box} +you've built with an |\hbox|, |\vbox|, or |\vtop| command, because +\TeX\ won't see the mark when it's constructing the main box of the page. But +if you use |\mark| in ordinary horizontal \minref{mode} +or directly in an hbox that's part of the main vertical list, +the mark migrates out +to the main \minref{vertical list}. +See \knuth{pages~259--260} for examples showing how |\mark| can be used. +\enddesc + +\begindesc +\cts firstmark {} +\cts botmark {} +\cts topmark {} +\explain +These commands expand to the mark text in an item generated by an earlier +^|\mark| command. +The mark text has the form of a token list. +\TeX\ sets the values of these commands when it +finishes placing the contents of a page into ^|\box255|, +just before calling the \minref{output routine} +as part of its \minref{page break}ing actions. \TeX\ determines +these values as follows: +\ulist\compact +\li |\firstmark| contains the tokens of the first mark on the page. +\li |\botmark| contains the tokens of the last mark on the page. +\li |\topmark| contains the tokens of the mark that is in effect at +the very top of the page. +That mark is the last mark +that \emph{preceded} the page, +i.e., the |\botmark| of the previous page. +It is empty if no marks preceded the page. +\endulist +\noindent +If a page has no marks on it, \TeX\ will set |\firstmark| and |\botmark| to +the same mark as |\topmark|, i.e., the most recent preceding mark. +The table at the bottom of \knuth{page~258} illustrates the relation among +|\firstmark|, |\botmark|, and |\topmark|. +\enddesc + +\begindesc +\cts splitfirstmark {} +\cts splitbotmark {} +\explain +^^{marks//for split lists} +These commands expand to the ^{mark text} generated by an earlier +^|\mark| command that produced an item in the item list of a vbox $V$. +The mark text has the form of a token list. +When \TeX\ +splits $V$ in response to a ^|\vsplit| command (\xref \vsplit), +it sets the values of these commands as follows: +\ulist\compact +\li |\splitfirstmark| contains the tokens of the first mark in +the item list of $V$. +\li |\splitbotmark| contains the tokens of the last mark in +the item list of $V$. +\endulist +These commands produce no tokens if there was no preceding |\vsplit|, +or if the most recent preceding |\vsplit| didn't contain any marks. +\eix^^{marks} +\enddesc + +%========================================================================== +\section {Insertions} + +\subsection {Footnotes} + +\begindesc +\easy\cts footnote {\<argument$_1$> \<argument$_2$>} +\cts vfootnote {\<argument$_1$> \<argument$_2$>} +\explain +These commands produce footnotes. +\<argument$_1$> is the ``^{reference mark}'' +for the footnote and \<argument$_2$> is its text. +The text can be several paragraphs long if necessary and can contain +constructs such as math displays, but it shouldn't contain any +\minref{insertion}s (such as other footnotes). + +You shouldn't use these commands inside a subformula of a math formula, +in a box within a box being contributed to a page, +or in an insertion of any kind. +If you're unsure whether these restrictions apply, you can be safe by +only using |\footnote| and |\vfootnote| directly within a paragraph or +between paragraphs. + +These restrictions aren't as severe as they seem because you can use +|\vfootnote| to footnote most anything. +Both |\foot!-note| and |\vfoot!-note| insert the reference mark in front of the +footnote itself, but |\vfoot!-note| doesn't insert the reference mark into the +text. +Thus, when you use |\vfoot!-note| you can +explicitly insert the reference mark +wherever it belongs without concern about the context +and place the |\vfootnote| in the next paragraph. +If you find that the footnote lands on +the page following the one where it belongs, move the |\vfootnote| back +to the previous paragraph. +There are rare circumstances where you'll need to +alter the text of your document in order to get a footnote to appear on +the same page as its reference mark. +\example +To quote the mathematician P\'olya is a ploy.\footnote +*{This is an example of an anagram, but not a strict one.} +| +\produces +To quote the mathematician P\'olya is a ploy.* +\par\line{\hskip .5in \vdots\hfil} +\nointerlineskip \bigskip +\footnoterule\par\parindent = 12pt +\textindent{*}This is +an example of an anagram, but not a strict one. +\endexample +\example +$$f(t)=\sigma\sigma t\;\raise 1ex \hbox{\dag}$$ +\vfootnote \dag{The $\sigma\sigma$ notation was explained in +the previous section.} +| +\produces +$$f(t)=\sigma\sigma t\>\raise 1ex \hbox{\dag}$$ +\par\line{\hskip .5in \vdots\hfil} +\nointerlineskip \bigskip +\footnoterule\par\parindent = 12pt +\textindent{\dag}{The $\sigma\sigma$ notation was explained in +the previous section.} +\endexample +\enddesc + +%========================================================================== +\subsection {General insertions} + +\begindesc +\bix^^{insertions//commands for} +\cts topinsert {\<vertical mode material> {\bt \\endinsert}} +\cts midinsert {\<vertical mode material> {\bt \\endinsert}} +\cts pageinsert {\<vertical mode material> {\bt \\endinsert}} +\explain +These commands produce different forms of insertions that +instruct +(or allow) \TeX\ to relocate the \<vertical mode material>: +\ulist +\li |\topinsert| attempts to put the material at the top of the current page. +If it won't fit there, |\topinsert| +will move the material to the next available top of page. +\li |\midinsert| attempts to put the material at the current position. +If it won't fit there, |\midinsert| +will move the material to the next available top of page. +\li |\pageinsert| puts the material by itself on the next page. +To avoid an underfull page, be sure to end the inserted material with +|\vfil| or fill out the excess space some other way. +% Knuth doesn't say this, but I tried an experiment that verified it. +% Nor does he say explicitly that an insertion does a \par. +\endulist +\noindent +The \<vertical mode material> +is said to be ``floating'' ^^{floating material} because \TeX\ +can move it from one place to another. +Insertions are very useful for material such as figures and tables because +you can position such material where you want it without knowing where the +page breaks will fall. + +Each of these commands implicitly ends the current paragraph, so +you should use them only between paragraphs. +You should not use them within a box or within another insertion. +If you have several insertions competing for +the same space, \TeX\ will retain their relative order. +\example +\pageinsert +% This text will appear on the following page, by itself. +This page is reserved for a picture of the Queen of Hearts +sharing a plate of oysters with the Walrus and +the Carpenter. +\endinsert +| +\endexample +\enddesc + +\begindesc +\cts endinsert {} +\explain +This command ends an insertion started by +|\topinsert|, |\midinsert|, or |\pageinsert|. +\enddesc + +\begindesc +\cts insert {\<number> \rqbraces{\<vertical mode material>}} +\explain +\minrefs{insertion} +This primitive command provides the +underlying mechanism for constructing insertions, but +it is hardly ever used outside of a \minref{macro} definition. +The definitions of the +|\foot!-note|, |\vfoot!-note|, +|\top!-insert|, |\mid!-insert|, and |\page!-insert| commands are +all built around |\insert|. +^^|\topinsert| +^^|\midinsert| ^^|\pageinsert| ^^|\footnote| ^^|\vfootnote| + +When you design insertions for a document, you should assign a different +integer code\footnote +{\texbook{} uses the term ``class'' for a code. +We use a different term to avoid confusion with the other meaning of +``class'' (\xref{class}).} +$n$ to each kind of insertion, +using the ^|\newinsert| command (\xref{\@newinsert}) to obtain the +integer codes. +The |\insert| command itself appends the \<vertical mode material> +to the current horizontal or \minref{vertical list}. +Your \minref{output routine} is responsible for +moving the inserted material from where it resides in |\box|$\,n$ +to an output page. +^^{output routine} + +\TeX\ groups together all insertions having the same code +number. Each insertion +code $n$ has four \minref{register}s associated with it: +\ulist +\li |\box|$\,n$ is where \TeX\ accumulates the material for insertions +with code $n$. When \TeX\ breaks a page, it puts into |\box|$\,n$ +as much insertion $n$ material as will fit on the page. +Your output routine should then move this material to the actual page. +You can use ^|\ifvoid| \ctsref{\@ifvoid} +to test if there is any material in |\box|$\,n$. +If not all the material fits, \TeX\ saves the leftovers for the next page. +\li |\count|$\,n$ is a magnification factor $f.$ When \TeX\ is computing +the vertical space occupied on the page +by insertion $n$ material, it multiplies the +vertical extent of this material by $f/1000$. +Thus you would ordinarily set $f$ to $500$ for a double-column insertion +and to $0$ for a marginal~note. +\li |\dimen|$\,n$ specifies the maximum amount +of insertion $n$ material that \TeX\ will put on a single page. +\li |\skip|$\,n$ specifies extra space that \TeX\ allocates on the page +if the page contains any insertion $n$ material. +This space is in addition to the space occupied by the insertion itself. +For example, it would account for the space on a page above the footnotes +(if there are~any). +\endulist +\noindent +\TeX\ sets |\box|$\,n$, and you should set the other three registers +so that \TeX\ can correctly compute the vertical space required by the +insertion. +See \knuth{pages~122--125} for further details of how \TeX\ processes this +command and of how insertions interact with page breaking. +\xrdef{endofinsert} +\enddesc + +\see |\floatingpenalty| (\xref \floatingpenalty). +\eix^^{insertions//commands for} + + +%========================================================================== +\section{Modifying the output routine} + +\bix^^{output routine} +\begindesc +\cts output {\param{token list}} +\explain +This parameter contains the current \minref{output routine}, i.e., +the token list that \TeX\ expands when it finds a page break. +\TeX\ puts the page into ^|\box255|, so |\output| is responsible +for doing something with |\box255|---either shipping it out or +putting it somewhere else. +The output routine is also responsible for attaching things such as +headers and footers. +\enddesc + +\begindesc +\cts plainoutput {} +\explain +This command invokes \plainTeX's output routine. +^^{output routine//default in \plainTeX} +\PlainTeX\ defines ^|\output| as +a token list containing the single token |\plainoutput|. +\enddesc + +\begindesc +\cts shipout {\<box>} +\explain +This command instructs \TeX\ to send \<box> to the \dvifile. +^^{\dvifile//receives boxes from \b\tt\\shipout\e} +\TeX\ expands any |\write| command in \<box> as part of |\shipout|. +^^|\write//expanded during {\tt\\shipout}| +The principal use of |\shipout| is in the output routine, but you can +use it anywhere. +\enddesc + +\begindesc +\cts deadcycles {\param{number}} +\explain +This parameter contains the number of times that \TeX\ has initiated +the \minref{output routine} since the last time it did a +^^|\shipout| |\ship!-out|.\footnote{ +More precisely, \TeX\ sets |\dead!-cyles| to $0$ whenever it executes +|\ship!-out| +and increments it by $1$ whenever it executes |\output|.} +If |\deadcycles| gets too big, you've probably gotten +\TeX\ into a loop, e.g., one where the page builder is trying the same page +break over and over again. +\enddesc + +\begindesc +\cts maxdeadcycles {\param{number}} +\explain +If the value of |\deadcycles| exceeds the value of |\maxdeadcycles|, +\TeX\ assumes that the output routine has gotten into a loop. +\TeX\ then complains and runs its own simple output routine, +equivalent to |\shipout!allowbreak\box255|, +that is likely to break the loop. +\PlainTeX\ sets |\maxdeadcycles| \hbox{to $25$}. +\enddesc + +\begindesc +\cts outputpenalty {\param{number}} +\explain +\TeX\ sets this parameter when it breaks a page. If the breakpoint was at a +\minref{penalty} item, \TeX\ removes the penalty item and +sets |\outputpenalty| to the penalty value at +the breakpoint; otherwise it sets |\outputpenalty| \hbox{to $0$}. + +Suppose that you are undoing a page break +in order to break the page at a different place than the one that \TeX\ +has just chosen. In order to reconstruct the page, you need to recreate +the penalty at \TeX's chosen breakpoint. +You can accomplish this with the command +|\penalty!allowbreak\outputpenalty|. +\enddesc + +\begindesc +\cts holdinginserts {\param{number}} +\explain +If this parameter is greater than $0$ when \TeX\ +is processing a page break, \TeX\ will refrain from processing insertions. +Setting this parameter to $1$ +can be useful when you're writing an output routine +that needs to reprocess the contents of the page, e.g., +an output routine that uses a value of |\vsize| (\xref \vsize) different from +the one used by the page builder. + +\eix^^{output routine} +\enddesc + +%========================================================================== +\section {Splitting vertical lists} + +\begindesc +\cts vsplit {\<number> {\bt to} \<dimen>} +\explain +This command causes \TeX\ to split the \minref{box} numbered +\<number>, which we'll call $B_2$, into two parts. +It uses the same algorithm that it would use if $B_2$ was a page +and it was breaking that page; +the division point then corresponds to the page break that it would find. +The box $B_2$ must be a vbox, not an hbox. +% we avoid starting the previous sentence with a symbol, a copyediting no-no. +\TeX\ puts the material preceding the division point into +another box $B_1$ and leaves the material after the division point in $B_2$. +The |\vsplit| command then produces $B_1$. +Normally you'd assign $B_1$ to a different +box register, as in the example below. +If the division point is at the end of $B_2$, +$B_2$ will be empty after the |\vsplit|. + +\TeX\ employs its usual page-breaking algorithm +^^{page breaks//in split lists} +for the split. +It uses \<dimen> for ^|\pagegoal|, the desired height of $B_1$. +The vertical extent of $B_1$ may not be exactly +\<dimen> because \TeX\ may not be able to achieve its page goal perfectly. +\TeX\ does not consider insertions in calculating the split, +so insertions in the original vertical list of $B_2$ will be retained +but won't affect the split point. + +\example +\setbox 20 = \vsplit 30 to 7in +% Split off the first seven inches or so of material from +% box 30 and place that material in box 20. +| +\endexample +\enddesc + +\begindesc +\cts splitmaxdepth {\param{dimen}} +\explain +This parameter specifies the +maximum allowable depth of a box resulting from a |\vsplit|. +|\splitmaxdepth| plays the +same role that ^|\maxdepth| (\xref \maxdepth) plays for a page. +\enddesc + +\begindesc +\cts splittopskip {\param{glue}} +\explain +This parameter specifies the glue that \TeX\ inserts at the top of +a box resulting from a |\vsplit|. +|\splittopskip| plays the +same role that ^|\topskip| (\xref \topskip) plays for a page. +\enddesc + +\see |\splitbotmark|, |\splitfirstmark| (\xref \splitfirstmark). + +\enddescriptions \endchapter \byebye |