path: root/info/impatient/pages.tex

% 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