% 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 horizontal and \linebreak vertical modes}

\chapterdef{hvmodes}

This section covers commands that have corresponding or identical
forms for both horizontal and vertical modes.
These commands provide boxes, spaces, rules, leaders,
and alignments.
For an explanation of the conventions used in this section,
see \headcit{Descriptions of the commands}{cmddesc}.

\begindescriptions

%==========================================================================
\section {Producing space}

%==========================================================================

\subsection {Fixed-width horizontal space}

\begindesc
\bix^^{space//producing}
\bix^^{horizontal space}
\cts thinspace {}
\explain
This command produces a positive \minref{kern}
whose width is one-sixth of an em
(\xref{dimdefs})
i.e., it causes \TeX\ to move its position right by that amount.
It is useful
when you have a nested quotation, for example,
and you want to separate the levels of quotes.
\TeX\ won't break a line at
a |\thinspace|.\minrefs{line break}

\example
``\thinspace`A quote.'\thinspace''\par
24,\thinspace 29--31,\thinspace 45,\thinspace 102
|
\produces
``\thinspace`A quote.'\thinspace''\par
24,\thinspace 29--31,\thinspace 45,\thinspace 102
\endexample
\enddesc

\begindesc
\cts negthinspace {}
\explain
This command
produces a negative kern whose width is one-sixth of an em
(\xref{dimdefs}),
i.e., it causes \TeX\ to move its position left by that amount.
It is useful for bringing together characters that are a little too
far apart.
\TeX\ won't break a line at a |\negthinspace|.\minrefs{line break}
\example
The horror, the horror\negthinspace, the horror of it all!!
|
\produces
The horror, the horror\negthinspace, the horror of it all!
\endexample
\enddesc

\begindesc
\cts enspace {}
\explain
This command produces a \minref{kern} whose width is one ^{en}
(half of an em, see \xrefpg{dimdefs}).
\TeX\ won't break a line
at an |\enspace| unless it's followed by glue.
In a bulleted list, the bullets are usually separated from the following
text by an |\enspace|.
\example
Lemma 1.\enspace There exists a white rabbit.
|
\produces
Lemma 1.\enspace There exists a white rabbit.
\endexample
% the enspace here follows the \proclaim convention (Knuth p. 355).
\enddesc

\begindesc
\easy\cts enskip {}
\cts quad {}
\cts qquad {}
\explain
^^{en}
Each of these commands 
produces a glob of horizontal \minref{glue}
that can neither stretch nor shrink.
\TeX\ can break a line \minrefs{line break} at such glue.
The width of these glues (which are relative to the current font)
are as follows for |cmr10|, the default \plainTeX\ font:
\medskip

\def\distance#1{\hbox{\strut $\rightarrow$\vrule\hskip #1\vrule$\leftarrow$}}

{\def\l#1{\hfil$#1$\thinspace em}
\tabskip 3pc \halign{#&#&\hfil#\hfil\cr
{\it Command}&{\it Space}&{\it Illustration}\cr
\noalign{\vskip 4pt}
|\enskip|&\l{\frac 1/2}&\distance{.5em}\cr
|\quad|&\l1&\distance{1em}\cr
|\qquad|&\l2&\distance{2em}\cr
}}
\example
en\enskip skip; quad\quad skip; qquad\qquad skip
|
\produces
en\enskip skip; quad\quad skip; qquad\qquad skip
\endexample
\eix^^{horizontal space}
\enddesc

%==========================================================================
\subsection {Fixed-length vertical space}

\begindesc
\bix^^{vertical space}
\easy\cts smallskip {}
\cts medskip {}
\cts bigskip {}
\explain
These commands produce successively larger
amounts of vertical space:
\display{{\def\bar{\kern 2pt\hrule width 5pc} 
\def\lbl#1{\hbox to 5pc{\hfil #1skip\hfil}}
\leavevmode
\vtop{\lbl{small}\bar\smallskip\bar}\quad
\vtop{\lbl{med}\bar\medskip\bar}\quad\vtop{\lbl{big}\bar\bigskip\bar}}}
\noindent
|\smallskip| skips by $3$ points and can stretch or
shrink by $1$ point.  |\med!-skip| is equivalent to two |\smallskip|s
and |\bigskip| is equivalent to two |\medskip|s.

These commands end a paragraph since they are inherently vertical.
The skips that they produce
are in addition to the normal interparagraph skip.
\example
Hop \smallskip skip \medskip and \bigskip jump.
|
\produces
Hop \smallskip skip \medskip and \bigskip jump.
\endexample
\enddesc

\begindesc
\cts smallskipamount {\param{glue}}
\cts medskipamount {\param{glue}}
\cts bigskipamount {\param{glue}}
\explain
These parameters specify the amounts of glue produced by
the |\small!-skip|, |\med!-skip|, and |\big!-skip| commands.
By changing these parameters you change the effect of the commands.
The default values (for \plainTeX)
correspond to a quarter of a linespace, half a linespace,
and a full linespace.
We recommend that you maintain this ratio by changing
these values whenever
you change |\baselineskip| (\xref\baselineskip).
^^|\baselineskip//and {\tt\\smallskipamount}, etc.|
\eix^^{vertical space}

\enddesc

%==========================================================================
\subsection {Variable-size space}

\begindesc
\easy\cts hskip {\<dimen$_1$> {\bt plus} \<dimen$_2$> {\bt minus} \<dimen$_3$>}
\cts vskip {\<dimen$_1$> {\bt plus} \<dimen$_2$> {\bt minus} \<dimen$_3$>}
^^{vertical skip}^^{vertical glue}
^^{horizontal skip}^^{horizontal glue}
\bix^^{horizontal space}
\bix^^{vertical space}
\explain
These commands produce horizontal and vertical glue respectively.
In the simplest and most common case when only \<dimen$_1$> is present,
|\hskip| skips to the right by \<dimen$_1$>
and |\vskip| skips down the page by \<dimen$_1$>.
More generally, these commands
produce \minref{glue} whose natural size is
\<dimen$_1$>, whose stretch is \<dimen$_2$>, and whose shrink is \<dimen$_3$>.
Either the |plus| \<dimen$_2$>, the |minus |\<dimen$_3$>,
or both can be omitted.
If both are present, the |plus| must come before the |minus|.
An omitted value
is taken to be zero. Any of the \<dimen>s can be negative.

You can use |\hskip| in math mode, but you can't use |mu| units
\seeconcept{mathematical unit}
for any of the dimensions.  If you want |mu| units, use |\mskip|
(\xref\mskip) instead.

\example
\hbox to 2in{one\hskip 0pt plus .5in two}
|
\produces
\hbox to 2in{one\hskip 0pt plus 2in two}

\doruler{\8\8}2{in}
\nextexample
\hbox to 2in{Help me!! I can't fit
{\hskip 0pt minus 2in} inside this box!!}
|
\produces
\hbox to 2in{Help me! I can't fit
{\hskip 0pt minus 2in} inside this box!}

\doruler{\8\8}2{in}
\nextexample
\vbox to 4pc{\offinterlineskip% Just show effects of \vskip.
   \hbox{one}\vskip 0pc plus 1pc \hbox{two}
      \vskip .5pc \hbox{three}}
|
\produces
\smallskip
\vbox to 4pc{\offinterlineskip% Just show effects of \vskip.
   \hbox{one}\vskip 0pc plus 1pc \hbox{two}
      \vskip .5pc \hbox{three}}
\endexample
\enddesc

\begindesc
\cts hglue {\<glue>}
\cts vglue {\<glue>}
^^{vertical glue}
^^{horizontal glue}
\explain
The |\hglue| command produces horizontal \minref{glue} that won't disappear at
a line break; the |\vglue| command
produces vertical \minref{glue} that won't disappear at a page break. 
In other respects these commands are just like |\hskip| and |\vskip|.
You can use |\vglue| to produce blank space at the top of a page,
e.g., above a title on the first page of a document, but
^|\topglue| (next) is usually better for this purpose.
\enddesc

\begindesc
\cts topglue {\<glue>}
\explain
\margin{Command added; recent addition to \TeX}
This command\footnote{|\topglue| was added to \TeX\ in version 3.0,
later than the other enhancements introduced by ^{\newTeX}
(\xref{newtex}).  It is first described in the \emph{eighteenth\/}
edition of \texbook.} causes the space from the top of the page to the
top of the first box on the page to be \<glue> precisely.
The top of the page is considered to be at the baseline of an
imaginary line of text just above the top line of the page.
More precisely, it's a distance |\topskip| above the origin as given by
|\hoffset| and |\voffset|.

This command is useful because \TeX\ ordinarily adjusts the glue
produced by |\topskip| in a complex way.  By using |\topglue| you can
control the position of the first box on the page without worrying about
those adjustments.

\enddesc

\begindesc
\cts kern {\<dimen>}
\explain
The effect of this command depends on the mode that \TeX\ is in when 
it encounters it:
\ulist

\li In a horizontal mode, \TeX\ moves its position to the right (for a positive
kern) or to the left (for a negative kern).

\li In a vertical mode, \TeX\ moves its position down the page (for a positive
kern) or up the page (for a negative kern).

\endulist
\noindent
Thus a positive kern produces empty space while a negative kern
causes \TeX\ to back up over something that it's already produced.
This notion of a kern ^^{kerns}
is different from the notion of a kern in some computerized
typesetting systems---in \TeX, positive kerns push two letters \emph{apart}
instead of bringing them closer together.

A kern is similar to
\minref{glue}, except that (a)~a kern can neither stretch nor shrink,
and (b)~\TeX\ will only break a line or a page at a kern if the kern
is followed by glue and is not part of a math formula.
If \TeX\ finds a kern at the
end of a line or a page, it discards the kern.
If you want to get the effect of a kern that never disappears,
use ^|\hglue| or ^|\vglue|.

You can use |\kern| in math mode, but you can't use |mu| units
\seeconcept{mathematical unit}
for \<dimen>.  If you want |mu| units, use |\mkern|
(\xref\mkern) instead.
^^{line breaks//kerns at}
^^{page breaks//kerns at}

\example
\centerline{$\Downarrow$}\kern 3pt % a vertical kern
\centerline{$\Longrightarrow$\kern 6pt % a horizontal kern
   {\bf Heed my warning!!}\kern 6pt % another horizontal kern
   $\Longleftarrow$}
\kern 3pt % another vertical kern
\centerline{$\Uparrow$}
|
\produces
\centerline{$\Downarrow$}\kern 3pt % a vertical kern
\centerline{$\Longrightarrow$\kern 6pt % a horizontal kern
   {\bf Heed my warning!}\kern 6pt % another horizontal kern
   $\Longleftarrow$}
\kern 3pt % another vertical kern
\centerline{$\Uparrow$}
\endexample
\enddesc

\begindesc
\makecolumns 4/2:
\cts hfil {}
\cts hfill {}
\cts vfil {}
\cts vfill {}
\explain
\bix^^{glue//infinitely stretchable}
These commands produce infinitely stretchable horizontal 
and vertical glue that
overwhelms any finite stretch that may be present.
|\hfil| and |\hfill| produce horizontal glue, while
|\vfil| and |\vfill| produce vertical glue.

|\hfill| is infinitely larger than |\hfil|.
If both |\hfill| and |\hfil| appear in the same \minref{box},
the |\hfill| will consume all the available extra space
and the |\hfil| will be effectively ignored.
|\hfill| can in turn be overwhelmed by |\hskip 0pt plus 1filll|.
The glue produced by
|\hfil| and |\hfill| never shrinks.

The behavior of |\vfil| and |\vfill| is analogous.

\example
\hbox to 2in{Left\hfil Middle \hfil Right}
|
\produces
\hbox to 2in{Left\hfil Middle \hfil Right}

\doruler{\8\8}2{in}
\nextexample
\hbox to 2in{Left\hfil Middle \hfill Right}
|
\produces
\hbox to 2in{Left\hfil Middle \hfill Right}

\doruler{\8\8}2{in}
\nextexample
\leftline{%
\vbox to 4pc{%
   \hbox{Top}\vfil\hbox{Middle}\vfil \hbox{Bottom}}\quad
\vbox to 4pc{%
   \hbox{Top}\vfil\hbox{Middle}\vfill\hbox{Bottom}}}
|
\produces
\smallskip
\leftline{%
\vbox to 4pc{%
   \hbox{Top}\vfil\hbox{Middle}\vfil \hbox{Bottom}}\quad
\vbox to 4pc{%
   \hbox{Top}\vfil\hbox{Middle}\vfill\hbox{Bottom}}}
\endexample

\eix^^{glue//infinitely stretchable}
\enddesc

\begindesc
\cts hss {}
\cts vss {}
\explain
These commands produce horizontal and vertical glue
that is both infinitely stretchable and
infinitely shrinkable. The glue can shrink
to a negative distance, producing the effect of backspacing along a line
(for |\hss|) or moving back up a page (for |\vss|).

\example
\line{text\hfil\hbox to 0pt{margin\hss}}
% `margin\hss' shrinks to the zero width of the hbox.
|
\produces
\line{text\hfil\hbox to 0pt{margin\hss}}
\nextexample
\vbox to 1pc{\hrule width 6pc % Top of box.
   \hbox{1} \vskip 1pc\hbox to 2pc{\hfil 2}
   % The \vss absorbs the extra distance produced by \vskip.
   \vss \hbox to 3pc{\hfil 3}
   \hrule width 6pc}% Bottom of box.
|
\produces
\medskip
\vbox to 1pc{\hrule width 6pc % top of box
   \hbox{1} \vskip 1pc\hbox to 2pc{\hfil 2}
   \vss \hbox to 3pc{\hfil 3}
   \hrule width 6pc}% bottom of box
\vskip 2.5pc
\endexample
\enddesc

\begindesc
\cts hfilneg {}
\cts vfilneg {}
\explain
^^{glue//negative}
These commands cancel the effect of a preceding |\hfil|
or |\vfil|. While |\hfil| and |\vfil|
produce infinitely stretchable positive \minref{glue}, |\hfilneg| 
and |\vfilneg| produce infinitely stretchable negative glue.
(Thus, $n$ |\hfilneg|s cancel $n$ ^|\hfil|s, and similarly for
|\vfilneg|.)
The main use of |\hfilneg| and |\vfilneg|
is to counteract the effect of an |\hfil| or |\vfil|
inserted by a \minref{macro}.

|\hfilneg| and |\vfilneg| have
the curious property that if they are the only infinitely stretchable
glue in a box, they produce exactly the same effect as |\hfil|
and |\vfil|.

\example
\leftline{\hfil on the right\hfilneg}
% Cancel the \hfil that \leftline produces to the right
% of its argument.
|
\produces
\leftline{\hfil on the right \hfilneg}
% Cancel the \hfil that \leftline produces to the right
% of its argument.
%
\nextexample
\def\a{\hbox to 1pc{\hfil 2}\vfil}
\vbox to 4pc{\hbox{1} \vfil \a
   \vfilneg \hbox to 2pc{\hfil 3}}
|
\produces
\smallskip
\def\a{\hbox to 1pc{\hfil 2}\vfil}
\vbox to 4pc{\hbox{1} \vfil \a
   \vfilneg \hbox to 2pc{\hfil 3}}
\endexample\enddesc

{\emergencystretch=2em
\see |\hbadness| and |\vbadness| (\xref \vbadness),
|\hfuzz| and |\vfuzz| (\xref \vfuzz),
\conceptcit{leaders}.\par}
\eix^^{space//producing}
\eix^^{horizontal space}
\eix^^{vertical space}

%==========================================================================
\section {Manipulating boxes}

%==========================================================================
\subsection {Constructing hboxes and vboxes}

\begindesc
\bix^^{box commands}
^^{hboxes//constructing with \b\tt\\hbox\e}
%
\cts hbox {\rqbraces{\<horizontal mode material>}}
\aux\cts hbox {{\bt to} \<dimen> \rqbraces{\<horizontal mode material>}}
\aux\cts hbox {{\bt spread} \<dimen> \rqbraces{\<horizontal mode material>}}
\explain
This command produces an hbox
(horizontal \minref{box}) containing \<horizontal mode material>.
The braces around \<horizontal mode material> define a group.
\TeX\ doesn't break the \<horizontal mode material> into lines,
since it's in restricted horizontal mode when it's assembling the box.
\TeX\ won't change the size of the box once it's been produced.

|\hbox| is often useful when you want to keep some text all on one line.
If your use of |\hbox| prevents \TeX\ from breaking lines in an acceptable
way, \TeX\ will complain about an overfull hbox.

The width of the hbox depends on the arguments to |\hbox|:
\ulist\compact
\li If you specify only \<horizontal mode material>,
the hbox will have its natural \minref{width}.
\li If you specify |to| \<dimen>, the width of the hbox will be \<dimen>.
\li If you specify |spread| \<dimen>, the width of the hbox will be
its natural width plus \<dimen>, i.e., the hbox will be spread out by
\<dimen>.
\endulist

The ^|\hfil| command (\xref\hfil) is useful for filling out an
hbox with empty space when the material in the box isn't as wide as
the width of the box.
\example
\hbox{ugly suburban sprawl}
\hbox to 2in{ugly \hfil suburban \hfil sprawl}
\hbox spread 1in {ugly \hfil suburban \hfil sprawl}
% Without \hfil in the two preceding lines,
% you'd get `underfull hbox'es.
|
\produces
\hbox{ugly suburban sprawl}
\hbox to 2in{ugly \hfil suburban \hfil sprawl}
\hbox spread 1in {ugly \hfil suburban \hfil sprawl}
% Without \hfil in the two preceding lines,
% you'd get `underfull hbox'es.

\doruler{\8\8\8}3{in}
\endexample
\enddesc

\begindesc
\cts vtop {\<vertical mode material>}
\aux\cts vtop {{\bt to} \<dimen> \rqbraces{\<vertical mode material>}}
\aux\cts vtop {{\bt spread} \<dimen> \rqbraces{\<vertical mode material>}}
\cts vbox {\rqbraces{\<vertical mode material>}}
\aux\cts vbox {{\bt to} \<dimen> \rqbraces{\<vertical mode material>}}
\aux\cts vbox {{\bt spread} \<dimen> \rqbraces{\<vertical mode material>}}
\explain
^^{hbox//constructing with \b\tt\\hbox\e}
These commands
produce a \minref{vbox} (vertical \minref{box})
containing \<vertical mode material>.
The braces around \<vertical mode material> define a group.
\TeX\ is in internal vertical mode when it's assembling the box.
\TeX\ won't change the size of the box once it's been produced.

The difference between |\vtop| and |\vbox| lies in where \TeX\ puts
the reference point of the constructed vbox.
Ordinarily, the reference point gotten from |\vtop| tends to be at or near
the top of the constructed vbox,
while
the reference point gotten from |\vbox| tends to be at or near
the bottom of the constructed vbox.
Thus a row of vboxes all constructed with |\vtop|
will tend to have their tops nearly in a line,
while a row of vboxes all constructed with |\vbox|
will tend to have their bottoms nearly in a line.

|\vtop| and |\vbox| are often useful
when you want to keep some text together on a single page.
(For this purpose, it usually doesn't matter which command you use.)
If your use of these commands
prevents \TeX\ from breaking pages in an acceptable
way, \TeX\ will complain that it's found an overfull or underfull vbox while
|\output| is active.

The height of a vbox depends on 
the arguments to |\vtop| or |\vbox|.
For |\vbox|, \TeX\ determines the height as follows:
\ulist\compact
\li If you specify only \<vertical mode material>,
the vbox will have its natural height.
\li If you specify |to| \<dimen>,
the height of the vbox will be \<dimen>.
\li If you specify |spread| \<dimen>, the height of the vbox will be
its natural height plus \<dimen>, i.e.,
the height of the vbox will be stretched vertically by \<dimen>.
\endulist
\noindent
For |\vtop|,
\TeX\ constructs the box using its rules for |\vbox| and then
apportions the vertical extent between the height and the depth as
described below.

Ordinarily, the width of a constructed vbox is the width of the widest
item inside it.\footnote
{More precisely, it's the distance from the reference point to the rightmost
edge of the constructed vbox.  Therefore,
if you move any of the items right using ^|\moveright| or
^|\moveleft| (with a negative distance),
the constructed vbox might be wider.}
The rules for apportioning the vertical extent between the
height and the depth are more complicated:
\ulist
\li For |\vtop|,
the height is the height of its first item, if that item is a box or rule.
Otherwise the height is zero. The depth is whatever vertical
extent remains after the height is subtracted.
\li For |\vbox|,
the depth is the depth of its last item, if that item is a box or rule.
Otherwise the depth is zero. The height is whatever vertical
extent remains after the depth is subtracted.%
\footnote{In fact, there's a further complication.
Suppose that after the depth has been determined
using the two rules just given, the depth turns out to be greater than
^|\boxmaxdepth|.
Then the depth is reduced to |\boxmaxdepth| and the height is adjusted
accordingly.} 
\endulist

The |\vfil| command (\xref\vfil) is useful for filling out a vbox
^^|\vfil//filling a vbox|
with empty space when the material in the box isn't as tall as
the vertical extent of the box.
\example
\hbox{\hsize = 10pc \raggedright\parindent = 1em
\vtop{In this example, we see how to use vboxes to
produce the effect of double columns.  Each vbox
contains two paragraphs, typeset according to \TeX's
usual rules except that it's ragged right.\par
This isn't really the best way to get true double
columns because the columns}
\hskip 2pc
\vtop{\noindent
aren't balanced and we haven't done anything to choose
the column break automatically or even to fix up the
last line of the first column.\par
However, the technique of putting running text into a
vbox is very useful for placing that text where you
want it on the page.}}
|
\produces
\hbox{\hsize = 10pc \raggedright\parindent = 1em
\vtop{In this example, we see how to use vboxes to
produce the effect of double columns.  Each vbox
contains two paragraphs, typeset according to \TeX's
usual rules except that it's ragged right.\par
This isn't really the best way to get true double
columns because the columns}
\hskip 2pc
\vtop{\noindent
aren't balanced and we haven't done anything to choose
the column break automatically or even to fix up the
last line of the first column.\par
However, the technique of putting running text into a
vbox is very useful for placing that text where you
want it on the page.}}
\nextexample
\hbox{\hsize = 1in \raggedright\parindent = 0pt
\vtop to .75in{\hrule This box is .75in deep. \vfil\hrule}
\qquad
\vtop{\hrule This box is at its natural depth. \vfil\hrule}
\qquad
\vtop spread .2in{\hrule This box is .2in deeper than
                  its natural depth.\vfil\hrule}}
|
\produces
\hbox{\hsize = 1in \raggedright\parindent=0pt
\vtop to .75in{\hrule This box is .75in deep. \vfil\hrule}
\qquad
\vtop{\hrule This box is at its natural depth. \vfil\hrule}
\qquad
\vtop spread .2in{\hrule This box is .2in deeper than
                  its natural depth.\vfil\hrule}}
\nextexample
% See how \vbox lines up boxes at their bottoms
% instead of at their tops.
\hbox{\hsize = 1in \raggedright
\vbox to .5in{\hrule This box is .5in deep.\vfil\hrule}
\qquad
\vbox to .75in{\hrule This box is .75in deep.\vfil\hrule}}
|
\produces
\hbox{\hsize = 1in \raggedright
\vbox to .5in{\hrule This box is .5in deep.\vfil\hrule}
\qquad
\vbox to .75in{\hrule This box is .75in deep.\vfil\hrule}}
\vskip 16pt % to avoid running into the next command description
\endexample
\enddesc

\begindesc
\margin{Two commands interchanged here.}
\cts boxmaxdepth {\param{dimen}}
\explain
This parameter contains a dimension $D$.
\TeX\ will not construct a box whose depth exceeds $D$.
If you produce a box whose depth $d$ would exceed $D$,
\TeX\ will transfer the
excess depth to the height of the box, effectively moving the 
\minref{reference point} of the box down by $d-D$.
If you set |\boxmaxdepth| to zero, \TeX\ will line up a row of vboxes
so that their bottom boundaries all lie on the same horizontal line.
\PlainTeX\ sets |\boxmaxdepth| to |\maxdimen| \ctsref{\maxdimen},
so |\boxmaxdepth| won't affect your boxes unless you change it.
\enddesc

\begindesc
\cts underbar {\<argument>}
\explain
This command puts \<argument> into an \minref{hbox}
and underlines it without regard to anything that protrudes below the
\minref{baseline} of the box.
\example
\underbar{Why not learn \TeX?}
|
\produces
\underbar{Why not learn \TeX?}
\endexample
\enddesc

\begindesc
\cts everyhbox {\param{token list}}
\cts everyvbox {\param{token list}}
\explain
These parameters contain token lists that \TeX\ expands at the start of
every \minref{hbox} or \minref{vbox} that it constructs.
Any items resulting from the expansion then become
the beginning of the list of items for the box.
By default these token lists are empty.
\enddesc

%==========================================================================
\subsection {Setting and retrieving the contents of boxes}

\begindesc
\bix^^{box registers}
%
\cts setbox {\<register>\thinspace{\bt =}\thinspace\<box>}
\cts box {\<register>}
\explain
^^{assignments//of boxes}
These commands respectively set and retrieve the contents
of the box register 
whose number is \<register>.  
Note that you set a box register a little differently than
you set the other kinds of registers: you use 
|\setbox|$\,n$~|=| rather than |\box|$\,n$~|=|.

\emph{Retrieving the contents of a box register
with these commands has the side effect of emptying it,
so that the box register become void.}  If you don't want that to happen, 
you can use |\copy| (see below) to retrieve the contents.
You should use |\box| in preference to |\copy|
when you don't care about what's in a box register after you've used it,
so as not to exhaust \TeX's memory by filling it with obsolete boxes.
\example
\setbox0 = \hbox{mushroom}
\setbox1 = \vbox{\copy0\box0\box0}
\box1
|
\produces
\setbox0 = \hbox{mushroom}
\setbox1 = \vbox{\copy0\box0\box0}
\box1
\endexample
\enddesc

\begindesc
\cts copy {\<register>}
\explain
^^{boxes//copying}\minrefs{box}
This command
produces a copy of box register \<register>.
This command is useful when you want to retrieve the contents of a box
register but don't want to destroy the contents.
(Retrieving the register contents with ^|\box| makes the register void.)
\example
\setbox0 = \hbox{good }
Have a \copy0 \box0 \box0 day!!
|
\produces
\setbox0 = \hbox{good }
Have a \copy0 \box0 \box0 day!
\endexample
\enddesc

\begindesc
\cts unhbox {\<register>}
\cts unvbox {\<register>}
^^{boxes//extracting contents of}
\explain
These commands produce the list contained in box register \<register> and make
that box register void.
|\unhbox| applies to box registers containing 
hboxes and |\unvbox| applies to box registers containing vboxes.
You should use these commands in preference to |\unhcopy| and |\unvcopy|
(see below)
when you don't care about what's in the box register after you've used it,
so as not to exhaust \TeX's memory by filling it with obsolete boxes.
\example
\setbox0=\hbox{The Mock Turtle sighed deeply, and
drew the back of one flapper across his eyes. }
\setbox1=\hbox{He tried to speak, but sobs choked 
               his voice. }
\unhbox0 \unhbox1
% \box0 \box1 would set two hboxes side by side
% (and produce a badly overfull line).
\box1 % produces nothing
|
\produces
\setbox0=\hbox{The Mock Turtle sighed deeply, and
drew the back of one flapper across his eyes. }
\setbox1=\hbox{He tried to speak, but sobs choked 
               his voice. }
\unhbox0 \unhbox1
% \hbox0 \hbox1 would set two hboxes side by side
% (and produce a badly overfull line).
\box1 % Produces nothing.
\endexample
\enddesc

\begindesc
\cts unhcopy {\<register>}
\cts unvcopy {\<register>}
^^{boxes//extracting contents of}
^^{boxes//copying }\minrefs{box}
\explain
These commands produce the list contained in box register \<register> and
leave the contents of the register undisturbed.
|\unhcopy| applies to box registers containing hboxes
and |\unvcopy| applies to box registers containing vboxes.
\example
\setbox0=\hbox{The Mock Turtle sighed deeply, and
drew the back of one flapper across his eyes. }
\setbox1=\hbox{He tried to speak, but sobs choked his 
          voice. }
\unhcopy0 \unhcopy1\par\noindent
% \box0 \box1 would set two hboxes side by side
% (and produce a badly overfull line).
\box1 % Produces an hbox (which can't be broken).
|
\produces
\setbox0=\hbox{The Mock Turtle sighed deeply, and
drew the back of one flapper across his eyes. }
\setbox1=\hbox{He tried to speak, but sobs choked his 
          voice. }
\unhcopy0 \unhcopy1\par\noindent
% \hbox0 \hbox1 would set two hboxes side by side
% (and produce a badly overfull line).
\box1 % produces an hbox (which can't be broken)
\endexample
\enddesc

\see |\wd|, |\dp|, |\ht| (\xref\ht).
\eix^^{box registers}

%==========================================================================
\subsection {Shifting boxes}

\begindesc
\cts moveleft {\<dimen> \<box>}
\cts moveright {\<dimen> \<box>}
\bix^^{boxes//shifting}
\minrefs{box}
\explain
These commands move \<box> left or right by \<dimen> (which can be
negative). You can only apply |\moveleft| and |\moveright| to a box
that's in a \minref{vertical list}.
\example
\vbox{\vbox{Phoebe}\vbox{walked}%
\moveleft 20pt\vbox{a}\moveright 20pt\vbox{crooked}%
\vbox{mile.}}
|
\produces
\hfuzz = \maxdimen
\vbox{\vbox{Phoebe}\vbox{walked}%
\moveleft 20pt\vbox{a}\moveright 20pt\vbox{crooked}%
\vbox{mile.}}
\endexample
\enddesc

\begindesc
\cts lower {\<dimen> \<box>}
\cts raise {\<dimen> \<box>}
\explain
These commands move \<box> up or down by \<dimen>
(which can be negative).
You can only apply |\raise| and |\lower| to a box
that's in a \minref{horizontal list}.
\example
Are you feeling \lower 6pt \hbox{depressed} about the
                \raise 6pt \hbox{bump} on your nose?
|
\produces
Are you feeling \lower 6pt \hbox{depressed} about the
                \raise 6pt \hbox{bump} on your nose?
\endexample

\eix^^{boxes//shifting}
\enddesc

%==========================================================================
\subsection {Dimensions of box registers}

\begindesc
\bix^^{box registers}
\bix^^{dimensions//of box registers}
\cts ht {\<register>\param{dimen}}
\cts dp {\<register>\param{dimen}}
\cts wd {\<register>\param{dimen}}
\explain
These parameters refer to the ^{height}, ^{depth}, and ^{width}
respectively of \minref{box} \minref{register} \<register>.
You can use them to find out the dimensions of a box.
You can also change the dimensions of a box, but it's a tricky business;
if you want to be adventurous you can
learn all about it from \knuth{pages~388--389}.
\example
\setbox0 = \vtop{\hbox{a}\hbox{beige}\hbox{bunny}}%
The box has width \the\wd0, height \the\ht0,
and depth \the\dp0.
|
\produces
\setbox0 = \vtop{\hbox{a}\hbox{beige}\hbox{bunny}}%
The box has width \the\wd0, height \the\ht0,
and depth \the\dp0.
\endexample
\eix^^{box registers}
\eix^^{dimensions//of box registers}
\enddesc

%==========================================================================
\subsection {Struts, phantoms, and empty boxes}

\begindesc
\margin{This subsection is a merger of two previous subsections.
The commands have also been reordered.}
\bix^^{struts}
\cts strut {}
\explain
This command produces a box whose width is zero
and whose height (|8.5pt|) and depth (|3.5pt|)
are those of a more or less typical line of type in |cmr10|,
the default \plainTeX\ font.
Its main use is in forcing lines to have the same height
when you've disabled \TeX's interline glue with
|\offinter!-lineskip| ^^|\offinterlineskip| or a similar command,
e.g., when you're constructing an alignment.
If the natural height of a line is
too short, you can bring it up to standard by including a |\strut|
in the line.  The strut will force the height and depth of the line
to be larger, but it won't print anything or consume any horizontal
space.

If you're setting type in a font that's bigger or smaller than |cmr10|,
you should redefine |\strut| for that context.
\example
\noindent % So we're in horizontal mode.
\offinterlineskip % So we get the inherent spacing.
% The periods in this vbox are not vertically equidistant.
\vtop{\hbox{.}\hbox{.(}\hbox{.x}
   \hbox{.\vrule height 4pt depth 0pt}}\qquad
% The periods in this vbox are vertically equidistant
% because of the struts.
\vtop{\hbox{.\strut}\hbox{.(\strut}\hbox{.x\strut}
   \hbox{.\vrule height 4pt depth 0pt\strut}}
|

\produces
\noindent % So we're in horizontal mode.
\offinterlineskip % So we get the inherent spacing.
% The periods in this vbox are not vertically equidistant.
\vtop{\hbox{.}\hbox{.(}\hbox{.x}
   \hbox{.\vrule height 4pt depth 0pt}}\qquad
% The periods in this vbox are vertically equidistant
% because of the struts.
\vtop{\hbox{.\strut}\hbox{.(\strut}\hbox{.x\strut}
   \hbox{.\vrule height 4pt depth 0pt\strut}}
\endexample
\enddesc

\begindesc
\cts mathstrut {}
\explain
This command produces a phantom formula whose width is zero
and whose height and depth are the same as those of a left parenthesis.
|\mathstrut| is in fact defined as `|\vphantom(|'.
Its main use is for getting radicals, underbars, and overbars to line
up with other radicals, underbars, and overbars in a formula.
It is much like ^|\strut| (\xref \strut),
except that it adjusts itself to the different \minref{style}s
that can occur in math formulas.  
\example
$$\displaylines{
\overline{a_1a_2} \land \overline{b_1b_2} 
\quad{\rm versus}\quad \overline{a_1a_2\mathstrut}
  \land \overline{b_1b_2\mathstrut}\cr
\sqrt{\epsilon} + \sqrt{\xi} \quad{\rm versus}\quad
\sqrt{\epsilon\mathstrut} + \sqrt{\xi\mathstrut}\cr}$$
|
\dproduces
\kern 4pt
$$\displaylines{
\overline{a_1a_2} \land \overline{b_1b_2} 
\quad{\rm versus}\quad \overline{a_1a_2\mathstrut}
  \land \overline{b_1b_2\mathstrut}\cr
\sqrt{\epsilon} + \sqrt{\xi} \quad{\rm versus}\quad
\sqrt{\epsilon\mathstrut} + \sqrt{\xi\mathstrut}\cr}$$
\endexample
\eix^^{struts}
\enddesc

\begindesc
\cts phantom {\<argument>}
\explain
\bix^^{boxes//phantom}
\bix^^{phantoms}
This command produces an empty \minref{box}
having the same size and placement
that \<argument> would have were it typeset.  
One use of |\phantom| is for reserving space for a symbol that for some
reason needs to be drawn in by hand.
\example
$1\phantom{9}2$
|
\produces
$1\phantom{9}2$
\endexample
\enddesc

\begindesc
\cts hphantom {\<argument>}
\cts vphantom {\<argument>}
\explain
These commands produce phantom boxes\minrefs{box}\ that
don't print anything:
\ulist\compact
\li |\hphantom| produces a box with the same width as \<argument>
but zero height and depth.
\li |\vphantom| produces a box with the same height and depth as \<argu\-ment>
but zero width.
\endulist
\noindent
Their main purpose is to force a subformula to have a certain minimum
horizontal or vertical dimension.
\example
$$\left[\vphantom{u\over v}t\right] \star
      \left[{u\over v}\right]\quad
   \{\hphantom{xx}\}$$
|
\dproduces
\kern 4pt
$$\left[\vphantom{u\over v}t\right] \star
      \left[{u\over v}\right]\quad
   \{\hphantom{xx}\}$$
\endexample
\enddesc

\begindesc
\cts smash {\<argument>}
\explain
This command typesets \<argument>,
but forces the height and depth of its containing \minref{box} to be zero.
You can use |\smash| and |\vphantom| in combination to give a subformula
any height and depth that you wish.
\example
$${\smash{r_m \brace r_n}\vphantom{r}} \Longrightarrow r$$
|
\dproduces
\kern 4pt
$${\smash{r_m \brace r_n}\vphantom{r}} \Longrightarrow r$$
\endexample
\eix^^{boxes//phantom}
\eix^^{phantoms}
\enddesc

\begindesc
^^{boxes//empty}
\cts null {}
\explain
This command produces an empty \minref{hbox}.
\example
\setbox0 = \null
The null box \null has width \the\wd0, height \the\ht0,
and depth \the\dp0.
|
\produces
\setbox0 = \null
The null box \null has width \the\wd0, height \the\ht0,
and depth \the\dp0.
\endexample
\enddesc


%==========================================================================
\subsection {Parameters pertaining to malformed boxes}

\begindesc
\bix^^{boxes//overfull}
\bix^^{boxes//underfull}
\cts overfullrule {\param{dimen}}
\explain
This parameter specifies the width of the rule 
that \TeX\ appends to an overfull \minref{hbox}.
\PlainTeX\ sets it to |5pt|.
\enddesc

\begindesc
\cts hbadness {\param{number}}
\cts vbadness {\param{number}}
\explain
These parameters specify the thresholds of horizontal and vertical
\minref{badness} for reporting underfull or overfull boxes.
|\hbadness| applies to hboxes and |\vbadness| applies to vboxes.
If the badness of a constructed box exceeds the threshold,
\TeX\ will report an error.  If you raise the thresholds
(the \plainTeX\ defaults are both $1000$),
\TeX\ will be less likely to complain.
Note that the settings of |\hbadness| and |\vbadness| have no effect on
the appearance of your typeset document; they only affect the error
messages that you get.
See \knuth{page~302} for a precise description
of how \TeX\ decides when to complain about an overfull or underfull
box.

\margin{The material on tolerance was inappropriate here and has been
removed.  A new example replaces it.}
\example
\hbadness = 10000 % Suppress any hbadness complaints.
\hbox to 2in{a b}\par
\hbadness = 500 % Report hbadness exceeding 500.
\hbox to 2in{a\hskip 0pt plus .5in b}
|
\logproduces
Underfull \hbox (badness 5091) detected at line 4
\tenrm a b

\hbox(6.94444+0.0)x144.54, glue set 3.70787
.\tenrm a
.\glue 0.0 plus 36.135
.\tenrm b
|
\endexample
\enddesc

\begindesc
\cts badness {}
\explain
This command yields the numerical value of the badness of the \minref{box}
(either horizontal or vertical) that \TeX\ has most recently produced.
If the box was overfull, |\badness| will be $1000000$; in all other cases
it will be between $0$ and $10000$.
\enddesc

\begindesc
\cts hfuzz {\param{dimen}}
\cts vfuzz {\param{dimen}}
\explain
These parameters specify the amount that
a \minref{box} can exceed its natural size before \TeX\ considers it to be
overfull. ^^{boxes//overfull}
|\hfuzz| applies to hboxes and |\vfuzz| applies to vboxes.
\PlainTeX\ sets both parameters to |0.1pt|.
\example
\hfuzz = .5in
\hbox to 2in{This box is longer than two inches.}
% No error results
|
\produces
\hfuzz = .5in
\hbox to 2in{This box is longer than two inches.}
% No error results
\doruler{\8\8\8}3{in}
\endexample

\eix^^{boxes//overfull}
\eix^^{boxes//underfull}
\eix^^{box commands}
\enddesc

\see |\tolerance| \ctsref{\tolerance}.
%==========================================================================
\section {Retrieving the last item from a list}

\begindesc
^^{boxes//last box in a list}
^^{kerns//last kern in a list}
^^{penalties//last penalty in a list}
^^{glue//last glue item in a list}
\margin{This section has been moved in its entirety from the chapter
(`Commands for general operations')}
\cts lastkern {}
\cts lastskip {}
\cts lastpenalty {}
\cts lastbox {}
\explain
These control sequences yield the value of the last item on the current
list.  They aren't true commands because they can only appear as
part of an argument.
If the last item on the list isn't of the indicated type,
they yield a zero value (or an empty box, in the case of |\lastbox|).
For example,
if the last item on the current list is a \minref{kern},
|\lastkern| yields the dimension of that kern; if it
isn't a kern, it yields a dimension of $0$.

Using |\lastbox| has the additional effect of removing the last box from
the list.
If you want the original |\last!-box| to remain on the list, you
have to add a copy of it to the list.
|\last!-box| is not permitted in a math list or in the main
vertical~list.

These control sequences are
most useful after macro calls that might have inserted entities of
the indicated kinds. 

\example
\def\a{two\kern 15pt}
one \a\a\hskip 2\lastkern three\par
% Get three times as much space before `three'.
\def\a{\hbox{two}}
one \a
\setbox0 = \lastbox % Removes `two'.
three \box0.
|
\produces
\def\a{two\kern 15pt}
one \a\a\hskip 2\lastkern three\par
% get three times as much space before `three'
\def\a{\hbox{two}}
one \a
\setbox0 = \lastbox % removes `two'
three \box0.
\endexample
\enddesc

\begindesc
\cts unkern {}
\cts unskip {}
\cts unpenalty {}
\explain
If the last item on the current list is of type \minref{kern},
\minref{glue}, or \minref{penalty} respectively, these commands remove it
from that list.  If the item isn't of the right type, these commands have
no effect.  Like ^|\lastbox|, you can't apply them to lists in math mode or to
the main vertical list.
These commands
are most useful after a macro call that is known to have inserted
a specific item that you don't want there.
\TeX\ doesn't provide an ^|\unbox| command because |\lastbox| produces
nearly the same effect.
\enddesc


%==========================================================================
\section {Rules and leaders}

\begindesc
\bix^^{rules}
\bix^^{horizontal rules}
\bix^^{vertical rules}
%
\cts hrule {}
\aux\cts hrule {\bt height \<dimen> width \<dimen> depth \<dimen>}
\cts vrule {}
\aux\cts vrule {{\bt width \<dimen> height \<dimen> depth \<dimen>}}
\explain
The |\hrule| command produces a horizontal rule; the |\vrule| command
produces a vertical rule.  You can specify any or all of the width,
height, and depth of the rule---\TeX\ supplies default values for those
that you omit.  You can give the dimensions of the rule in any order;
the forms listed above show just two of the possible combinations.  You
can even give a dimension of a given kind more than once---if you do,
the last one is the one that counts.

If you don't specify the width of a horizontal rule, the rule is
extended horizontally to the boundaries of the innermost \minref{box} or
\minref{alignment} that contains the rule.  If you don't specify the
height of a horizontal rule, it defaults to |0.4pt|; if you don't
specify the depth of a horizontal rule, it defaults to |0pt|.

If you don't specify the width of a vertical rule, it defaults to
|0.4pt|.  If you don't specify the height or the depth of a vertical
rule, the rule is extended to the boundary of the innermost \minref{box}
or \minref{alignment} that contains the rule.

\TeX\ treats a horizontal rule as an inherently vertical item
and a vertical rule as an inherently horizontal item.
Thus a horizontal rule is legal only in a \minref{vertical mode},
while a vertical rule is legal only in a \minref{horizontal mode}.
^^{horizontal mode//rules in}
^^{vertical mode//rules in}
If this seems surprising, visualize it---a horizontal rule runs
from left to right and separates vertical items in a sequence, while
a vertical rule runs up and down and
separates horizontal items in a sequence.

\example
\hrule\smallskip
\hrule width 2in \smallskip
\hrule width 3in height 2pt \smallskip
\hrule width 3in depth 2pt
|
\produces
\medskip
\hrule\smallskip
\hrule width 2in \smallskip
\hrule width 3in height 2pt \smallskip
\hrule width 3in depth 2pt
\nextexample
% Here you can see how the baseline relates to the
% height and depth of an \hrule.
\leftline{
   \vbox{\hrule width .6in height 5pt depth 0pt}
   \vbox{\hrule width .6in height 0pt depth 8pt}
   \vbox{\hrule width .6in height 5pt depth 8pt}
   \vbox{\hbox{ baseline}\kern 3pt \hrule width .6in}
}
|
\produces
\medskip
\leftline{
   \vbox{\hrule width .6in height 5pt depth 0pt}
   \vbox{\hrule width .6in height 0pt depth 8pt}
   \vbox{\hrule width .6in height 5pt depth 8pt}
   \vbox{\hbox{ baseline}\kern 3pt \hrule width .6in}
}
\nextexample
\hbox{( {\vrule} {\vrule width 8pt} )}
\hbox {( {\vrule height 13pt depth 0pt}
   {\vrule height 13pt depth 7pt} x)}
% the parentheses define the height and depth of each of the 
% two preceding boxes; the `x' sits on the baseline
|
\produces
\medskip
\hbox{( {\vrule} {\vrule width 8pt} )}
\hbox {( {\vrule height 13pt depth 0pt}
   {\vrule height 13pt depth 7pt} x)}
\endexample

\eix^^{rules}
\eix^^{horizontal rules}
\eix^^{vertical rules}
\enddesc

\begindesc
\bix^^{leaders}
\easy\cts leaders {\<box or rule> \<skip command>}
\cts cleaders {\<box or rule> \<skip command>}
\cts xleaders {\<box or rule> \<skip command>}
\explain
These commands produce \minref{leaders}, i.e., they fill a 
horizontal or vertical space with
copies of a pattern \seeconcept{leaders}.
The \<box> or \<rule> specifies a leader,
i.e., a single copy of the pattern,
while the \<skip command> specifies a 
window to be filled with a
row or a column of the leaders.
The pattern is repeated as many times as will fit into the window.
If \<skip command> is a horizontal skip, the window 
contains a row of leaders and \TeX\ must be in a horizontal mode;
if \<skip command> is a vertical skip, the window
contains a column of leaders and \TeX\ must be in a vertical mode.

The commands differ in how they arrange the repeated pattern in the space
and where they put any leftover space:

\ulist\compact
\li For |\leaders|, \TeX\ aligns a row of leaders with the left end of
the innermost \minref{box} $B$ that is to contain the result of the
|\leaders| command.
It aligns a column of leaders with the top of $B$.
Those leaders that fall entirely within the window are retained.
Any leftover space at the top and bottom of the window is left empty.
\li For |\cleaders|, the leaders are centered within the window.
\li For |\xleaders| the pattern is uniformly distributed throughout the window.
If the leftover space is $l$ and the leader is repeated  $n$ times,
\TeX\ puts space of width or height $l/(n+1)$ between adjacent leaders and
at the two ends (left and right or top and bottom) of the leaders.
\endulist

\example
\def\pattern{\hbox to 15pt{\hfil.\hfil}}
\line{Down the Rabbit-Hole {\leaders\pattern\hfil} 1}
\line{The Pool of Tears {\leaders\pattern\hfil} 9}
\line{A Caucus-Race and a Long Tale {\cleaders\pattern
      \hfil} 19}
\line{Pig and Pepper {\xleaders\pattern\hfil} 27}
|
\produces
\def\pattern{\hbox to 15pt{\hfil.\hfil}}\par
\line{Down the Rabbit-Hole {\leaders\pattern\hfil} 1}
\line{The Pool of Tears {\leaders\pattern\hfil} 9}
\line{A Caucus-Race and a Long Tale {\cleaders\pattern
      \hfil} 19}
\line{Pig and Pepper {\xleaders\pattern\hfil} 27}
\nextexample
\def\bulletfill{\vbox to 3ex{\vfil\hbox{$\bullet$}\vfil}}%
\def\mybox{\vbox to 1in}
\def\myrule{\hrule width 4pt}\hsize=2in
\hrule \line{%
   \mybox{\myrule depth 8pt \leaders\bulletfill\vfill}
   \hfil
   \mybox{\myrule depth 15pt \leaders\bulletfill\vfill}
   \hfil
   \mybox{\myrule depth 18pt \cleaders\bulletfill\vfill}
   \hfil
   \mybox{\myrule depth 12pt \xleaders\bulletfill\vfill}%
}\hrule
|
\produces
\medskip
\def\bulletfill{\vbox to 3ex{\vfil\hbox{$\bullet$}\vfil}}%
\def\mybox{\vbox to 1in}\def\myrule{\hrule width 4pt}\hsize=2in
\hrule \line{%
   \mybox{\myrule depth 8pt \leaders\bulletfill\vfill}
   \hfil
   \mybox{\myrule depth 15pt \leaders\bulletfill\vfill}
   \hfil
   \mybox{\myrule depth 18pt \cleaders\bulletfill\vfill}
   \hfil
   \mybox{\myrule depth 12pt \xleaders\bulletfill\vfill}%
}\hrule
\endexample\enddesc

\begindesc
\cts dotfill {}
\cts hrulefill {}
\explain
^^{fill}
These commands respectively fill the enclosing horizontal space with 
a row of dots on the baseline and with
a horizontal line on the baseline.
It's usually a good idea to leave a space between 
|\dotfill| or |\hrulefill|
and any text that precedes or follows it (see the example below).
\example
\hbox to 3in{Start {\dotfill} Finish}
\hbox to 3in{Swedish {\hrulefill} Finnish}
|
\produces
\par\hbox to 3in{Start {\dotfill} Finish}
\hbox to 3in{Swedish {\hrulefill} Finnish}
\endexample\enddesc

\begindesc
\cts leftarrowfill {}
\cts rightarrowfill {}
\explain
^^{fill}
These commands fill the enclosing horizontal space with
left-pointing or right-pointing ^{arrows}.
\example
\hbox to 3in{\vrule \rightarrowfill \ 3 in 
             \leftarrowfill\vrule}
|
\produces
\medskip
\hbox to 3in{\vrule \rightarrowfill \ 3 in 
        \leftarrowfill\vrule}
\endexample

\eix^^{leaders}
\enddesc

%==========================================================================
\section {Alignments}

%==========================================================================
\subsection {Tabbing alignments}

\begindesc
\bix^^{tabbing alignments}
\bix^^{alignments//commands for}
%
\ctspecial + {{\bt \<text>\thinspace\&\thinspace\<text>%
   \thinspace\& $\cdots$ \\cr}} 
\ctsxrdef{@plus}
\cts tabalign {}
\explain
These commands begin a single line in a  tabbed \minref{alignment}.
The only difference between |\+| and |\tabalign| is that 
|\+| is an outer macro---you can't use it when \TeX\ is reading tokens at
high speed \seeconcept{outer}.

If you place an `|&|' at a position
to the right of all existing tabs in a tabbing alignment,
the `|&|' establishes a new tab at that position.
\example
\cleartabs % Nullify any previous \settabs.
\+ {\bf if }$a[i] < a[i+1]$ &{\bf then}&\cr
\+&&$a[i] := a[i+1]$;\cr
\+&&{\it found }$:=$ {\bf true};\cr
\+&{\bf else}\cr
\+&&{\it found }$:=$ {\bf false};\cr
\+&{\bf end if};\cr
|
\produces
\cleartabs % Nullify any previous \settabs.
\+ {\bf if }$a[i] < a[i+1]$ &{\bf then}&\cr
\+&&$a[i] := a[i+1]$;\cr
\+&&{\it found }$:=$ {\bf true};\cr
\+&{\bf else}\cr
\+&&{\it found }$:=$ {\bf false};\cr
\+&{\bf end if};\cr
\endexample
\enddesc

\begindesc
\cts settabs {\<number> {\bt \\columns}}
\aux\cts settabs {{\bt \\+} \<sample line> {\bt \\cr}}
\explain
The first form of
this command defines a set of tab stops ^^{tabs}
for a tabbing \minref{alignment}.
It tells \TeX\ to set the tab stops so as to divide each line into
\<number> equal parts.  \TeX\ takes the length of a line to be
|\hsize|, as usual.  You can make the alignment narrower by decreasing
|\hsize|.
\margin{paragraph ``The tab settings $\ldots$'' moved to below.}
\example
{\hsize = 3in \settabs 3 \columns
\+$1$&one&first\cr
\+$2$&two&second\cr
\+$3$&three&third\cr}
|
\produces
{\hsize = 3in \settabs 3 \columns
\+$1$ & one & first\cr
\+$2$ & two & second\cr
\+$3$ & three & third\cr}

\noindent\doruler{\8\8\8}3{in}
\smallskip
\endexample

The second form of this command defines tab stops by setting the tab stops
at the positions indicated by the `|&|'s in the sample line.
The sample line itself does not appear in the output.  When you
use this form you'll usually want to put material into the sample line that is
somewhat wider than the widest corresponding material in the alignment,
in order to produce space between the columns.
That's what we've done in the 
example below.  The material following the last tab
stop is irrelevant, since \TeX\ does not need to position
anything at the place where the |\cr|~appears.

The tab settings established by |\settabs| remain in effect until
you issue a new |\settabs| command or end a group containing
the |\settabs| command.
This is true for both forms of the command.

\example
% The first line establishes the template.
\settabs \+$1$\qquad & three\quad & seventh\cr
\+$1$&one&first\cr
\+$2$&two&second\cr
\+$3$&three&third\cr
|
\produces
\settabs \+$1$\qquad & three\quad & seventh\cr % the sample line
\+$1$&one&first\cr
\+$2$&two&second\cr
\+$3$&three&third\cr
\smallskip
\endexample
\enddesc

\begindesc

\cts cleartabs {}
\explain
This command clears all the tabs to the right of the current column.
Its main use is in applications such as typesetting computer programs
in which the tab positions change from line to line.
\enddesc

\see |\cr|, |\endline|, |\crcr| (\xref \endline).
\eix^^{tabbing alignments}

%==========================================================================
\subsection {General alignments}

\begindesc
\cts halign {{\bt \rqbraces{\<preamble> \\cr \<row> \\cr $\ldots$ \<row> \\cr}}}
   \xrdef{@and}\xrdef{@pound}
\aux\cts halign {{\bt to \<dimen>%
   \rqbraces{\<preamble> \\cr \<row> \\cr $\ldots$ \<row> \\cr}}}
\aux\cts halign {{\bt spread \<dimen>%
   \rqbraces{\<preamble> \\cr \<row> \\cr $\ldots$ \<row> \\cr}}}
\explain
This command produces a horizontal \minref{alignment} consisting of a
sequence of rows, where each row in turn contains a sequence of column
entries.  \TeX\ adjusts the widths of the column entries to accommodate
the widest one in each column.

A horizontal alignment can only appear when \TeX\ is in a vertical
\minref{mode}.  We recommend that you first study alignments in general
(\xref{alignment}) before you attempt to use this command.

An alignment consists of a ^{preamble}
followed by the text to be aligned. The preamble,
which describes the layout of the rows that follow, consists of a
sequence of column templates, separated by `|&|' and ended
by |\cr|.
\bix^^{template}
\bix^^{entry (column or row)}
Each row consists of a sequence of column
entries, also separated by `|&|' and ended by |\cr|. Within
a template, `|#|' indicates where \TeX\ should insert the
corresponding text of a column entry. 
In contrast, |\settabs| uses a fixed implicit template of `|#|',
i.e., it just inserts the text as is.

\TeX\ typesets each column entry in restricted horizontal mode,
i.e., as the contents of an \minref{hbox},
and implicitly encloses it in a group.

The |to| form of this command instructs \TeX\
to make the width of the alignment be \<dimen>,
adjusting the space between columns as necessary.
The |spread| form of this command instructs \TeX\
to make the alignment wider by \<dimen> than its natural width.
These forms are like the corresponding forms of |\hbox| \ctsref\hbox.

See |\tabskip| \ctsref\tabskip{} for an example using the
|to| form.

\example
\tabskip = 1em \halign{%
   \hfil\it#\hfil&\hfil#\hfil&#&\hfil\$#\cr
   United States&Washington&dollar&1.00\cr
   France&Paris&franc&0.174\cr
   Israel&Jerusalem&shekel&0.507\cr
   Japan&Tokyo&yen&0.0829\cr}
|
\produces
\tabskip = 1em \halign{%
   \hfil\it#\hfil&\hfil#\hfil&#&\hfil\$#\cr
   United States&Washington&dollar&1.00\cr
   France&Paris&franc&0.174\cr
   Israel&Jerusalem&shekel&0.507\cr
   Japan&Tokyo&yen&0.0829\cr}
\endexample
\enddesc

\begindesc
{\tighten
\cts valign {{\bt \rqbraces{\<preamble>\\cr \<column>\\cr $\ldots$
   \<column>\\cr}}}
\aux\cts valign {{\bt to \<dimen>%
   \rqbraces{\<preamble>\\cr \<column>\\cr $\ldots$ \<column>\\cr}}}
\aux\cts valign {{\bt spread \<dimen>%
   \rqbraces{\<preamble>\\cr \<column>\\cr $\ldots$ \<column>\\cr}}}
\par}
\explain
This command produces a vertical \minref{alignment}
consisting of
a sequence of columns, where each column in turn contains a sequence
of row entries.
\TeX\ adjusts the heights of the row entries to accommodate the tallest one
in each row.

A vertical alignment
can only appear when \TeX\ is in a horizontal \minref{mode}.
Because vertical alignments are (a)~conceptually somewhat difficult and
(b)~not often used, we recommend that you learn about
alignments in general
(\xref{alignment}) and the |\halign| command (see above) before
you attempt to use the |\valign| command.

An alignment consists of a ^{preamble}
followed by the text to be aligned. The preamble,
which describes the layout of the columns that follow,
consists of a
sequence of row templates, separated by `|&|' and ended
by |\cr|.
\bix^^{template}
Each column consists of a sequence of ^{row}
entries, also separated by `|&|' and ended by |\cr|. Within
a template, `|#|' indicates where \TeX\ should insert the
corresponding text of a row entry. 

\TeX\ typesets each row entry in internal vertical
mode, i.e., as the contents of a \minref{vbox},
and implicitly encloses the entry in a group.
It always gives the vbox zero depth.
Any text or other horizontal mode material in a row entry then puts \TeX\
into ordinary horizontal mode.
(This is just an application of the general rules for \TeX's behavior
in internal vertical mode.)
The usual paragraphing parameters apply in this case:
the row entry has an initial
indentation of |\parindent| (\xref\parindent) and 
its lines have the
|\leftskip| and |\rightskip| (\xref\leftskip) \minref{glue}
appended to~them.

Note in particular that a row entry containing text has
a width of |\hsize| (\xref\hsize).  Unless you reset
|\hsize| to the row width that you want, you're likely to
encounter overfull \minref{hbox}es, or find that
the first column takes up the width of the entire page, or both.
\eix^^{entry (column or row)}

Normally, you need to include a \minref{strut}
^^{struts//in vertical alignments}
in each
template so that the rows don't come out crooked as a result
of the varying heights of the entries in the alignment.  You
can produce a strut with the |\strut| command.

The |to| form of this command instructs \TeX\
to make the vertical extent of the alignment be \<dimen>,
adjusting the space between rows as necessary.
The |spread| form of this command instructs \TeX\
to make the alignment taller by \<dimen> than its natural height.
These forms are like the corresponding forms of |\vbox| \ctsref\vbox.

\example
{\hsize=1in \parindent=0pt
\valign{#\strut&#\strut&#\strut&#\strut\cr
   bernaise&curry&hoisin&hollandaise\cr
   ketchup&marinara&mayonnaise&mustard\cr
   rarebit&tartar\cr}}
|
\produces
{\hsize=1in \parindent=0pt \leftskip=0pt
\valign{#\strut&#\strut&#\strut&#\strut\cr
   bernaise&curry&hoisin&hollandaise\cr
   ketchup&marinara&mayonnaise&mustard\cr
   rarebit&tartar\cr}}
\nextexample
% same thing but without struts (shows why you need them)
{\hsize=1in \parindent=0pt
\valign{#&#&#&#\cr
   bernaise&curry&hoisin&hollandaise\cr
   ketchup&marinara&mayonnaise&mustard\cr
   rarebit&tartar\cr}}
|
\produces
{\hsize=1in \parindent=0pt \leftskip=0pt
\valign{#&#&#&#\cr
   bernaise&curry&hoisin&hollandaise\cr
   ketchup&marinara&mayonnaise&mustard\cr
   rarebit&tartar\cr}}
\endexample
\enddesc

\begindesc
\cts ialign {}
\explain
This command behaves just like ^|\halign|,
except that it first sets the |\tabskip| glue to zero and
sets |\everycr| empty.
\enddesc

\begindesc
\cts cr {}
\explain
This command ends the preamble of a horizontal or vertical
alignment, a row of a horizontal or tabbing alignment,
or a column of a vertical alignment.
You can cause \TeX\ to take certain actions whenever it sees a |\cr|
by setting the value of the ^|\everycr| parameter \ctsref\everycr.
\enddesc

\begindesc
\cts endline {}
\explain
This command is a synonym for the ^|\cr| command.  It is useful when
you've redefined |\cr| but still need access to the original definition.
\enddesc

\begindesc
\cts crcr {}
\explain
This command behaves just like ^|\cr|, except that \TeX\ ignores it if
it comes immediately after a |\cr| or a ^|\noalign|.
Its main application is as a safety measure to avoid a misleading error
message caused by a \minref{macro} that expects an argument ending in |\cr|.
If you put |\crcr| after the `|#|$n$' that denotes such an argument
in the macro's definition, the
macro will work properly whether or not the argument ends with |\cr|.
\enddesc

\begindesc
\cts omit {}
\explain
This command tells \TeX\ to ignore a template in a horizontal or vertical
\minref{alignment} while processing a particular column or row entry
respectively.
|\omit| must appear as the first item in a column or row entry; in effect,
it overrides the template from the preamble with the simple
template `|#|'.


\example
\tabskip = 2em\halign{%
   \hfil\it#\hfil&\hfil#\hfil&#&\hfil\$#\cr
   United States&Washington&dollar&1.00\cr
   \omit \dotfill France\dotfill&Paris&franc&0.174\cr
   Israel&Jerusalem&shekel&0.507\cr
   Japan&Tokyo&yen&0.0829\cr}
|
\produces
\tabskip = 2em\halign{%
   \hfil\it#\hfil&\hfil#\hfil&#&\hfil\$#\cr
   United States&Washington&dollar&1.00\cr
   \omit \dotfill France\dotfill&Paris&franc&0.174\cr
   Israel&Jerusalem&shekel&0.507\cr
   Japan&Tokyo&yen&0.0829\cr}
\nextexample
{\hsize=1.2in \parindent=0pt 
\valign{(#)\strut&(#)\strut&(#)\strut&(#)\strut\cr
   bernaise&curry&hoisin&hollandaise\cr
   ketchup&\omit\strut{\bf MARINARA!!}&mayonnaise&mustard\cr
   rarebit&tartar\cr}}
|
\produces
{\hsize=1.2in \parindent=0pt \leftskip=0pt
\valign{(#)\strut&(#)\strut&(#)\strut&(#)\strut\cr
   bernaise&curry&hoisin&hollandaise\cr
   ketchup&\omit\strut{\bf MARINARA!}&mayonnaise&mustard\cr
   rarebit&tartar\cr}}
\endexample
\enddesc

\begindesc
\cts span {}
\explain
The meaning of this command depends on whether it appears in a preamble
or in an alignment entry.
\ulist
\li Normally, \TeX\ does not expand tokens in the preamble
when it reads them.
Putting |\span| in front of a token in the preamble causes
that token to be expanded immediately according to \TeX's usual rules
of \minref{macro} expansion.
\li Putting |\span| instead of `|&|' between two column or row entries
causes those columns or rows to be combined.
For a horizontal alignment,
the width of the combined column is the sum of the
widths of the component columns.
For a vertical alignment,
the height of the combined row is the sum of the
heights of the component rows.
The template of the combined column or combined row forms a single group,
so font-setting commands preceding a |\span| affect everything up to
the next `|&|'.
\endulist
\noindent
|\span| is rarely useful by itself outside of a template,
but it provides the basic mechanism
for defining ^|\multispan|.
\enddesc

\begindesc
\cts multispan {\<number>}
\explain
This command tells \TeX\ that the following
\<number> columns in a row of a horizontal alignment,
or
\<number> rows in a column of a vertical alignment,
should be combined into a single column or row (as with
|\span|) and that their templates should be omitted (as with |\omit|).

\example
\tabskip = 13pt\halign{%
   \hfil\it#\hfil&\hfil#\hfil&#&\hfil\$#\cr
   United States&Washington&dollar&1.00\cr
   France&Paris&franc&0.174\cr
   Israel&Jerusalem &
      \multispan 2 \hfil\it(no information)\hfil \cr
   Japan&Tokyo&yen&0.0829\cr}
|
\produces
\tabskip = 13pt\halign{%
   \hfil\it#\hfil&\hfil#\hfil&#&\hfil\$#\cr
   United States&Washington&dollar&1.00\cr
   France&Paris&franc&0.174\cr
   Israel&Jerusalem &
      \multispan 2 \hfil\it(no information)\hfil \cr
   Japan&Tokyo&yen&0.0829\cr}
\nextexample
{\hsize=1.2in \parindent=0pt
\valign{(#)\strut&(#)\strut&(#)\strut&(#)\strut\cr
   bernaise&curry&hoisin&hollandaise\cr
   \multispan 3$$\left\{{{\rm ketchup}\atop{\rm marinara}}
      \right\}$$&mustard\cr
   rarebit&tartar\cr}}
|
\produces
{\hsize=1.2in \parindent=0pt \leftskip=0pt
\valign{(#)\strut&(#)\strut&(#)\strut&(#)\strut\cr
   bernaise&curry&hoisin&hollandaise\cr
   \multispan 3$$\left\{{{\rm ketchup}\atop{\rm marinara}}
      \right\}$$&mustard\cr
   rarebit&tartar\cr}}
\endexample

\eix^^{template}
\enddesc

\begindesc
\cts noalign {\rqbraces{\<vertical mode material>}}
\aux\cts noalign {\rqbraces{\<horizontal mode material>}}
\explain
This command inserts
\<vertical mode material>
after the current row of a horizontal \minref{alignment} or
\<horizontal mode material> after the current column of a vertical
\minref{alignment}.
The material can be text, glue, a rule, or anything else.

The most common use of |\noalign|
is to put extra space after a row or column.
If you want to put extra space after \emph{every\/} row of a horizontal
alignment, use ^|\openup| (\xref\openup).

\example
\halign{%
   \hfil\it#\hfil\tabskip=2em&\hfil#\hfil&#&
      \hfil\$#\tabskip=0em\cr
   % The \tabskip changes prevent the rule below
   % from sticking out.
   United States&Washington&dollar&1.00\cr
   France&Paris&franc&0.174\cr
   \noalign{\smallskip\hrule\smallskip}
   Israel&Jerusalem&shekel&0.507\cr
   Japan&Tokyo&yen&0.0829\cr}
|
\produces
\halign{%
   \hfil\it#\hfil\tabskip=2em&\hfil#\hfil&#&
      \hfil\$#\tabskip=0em\cr
   % The \tabskip changes prevent the rule below
   % from sticking out.
   United States&Washington&dollar&1.00\cr
   France&Paris&franc&0.174\cr
   \noalign{\smallskip\hrule\smallskip}
   Israel&Jerusalem&shekel&0.507\cr
   Japan&Tokyo&yen&0.0829\cr}
\nextexample
{\hsize=1in \parindent=0pt
\valign{#\strut&#\strut&#\strut&#\strut\cr
   \noalign{\vrule width 2pt\quad}
   bernaise&curry&hoisin&hollandaise\cr
   \noalign{\vrule width 2pt\quad}
   ketchup&marinara&mayonnaise&mustard\cr
   \noalign{\vrule width 2pt\quad}
   rarebit&tartar\cr
   \noalign{\vrule width 2pt\quad}}}
|
\produces
\medskip
{\hsize=1in \parindent=0pt
\valign{#\strut&#\strut&#\strut&#\strut\cr
   \noalign{\vrule width 2pt\quad}
   bernaise&curry&hoisin&hollandaise\cr
   \noalign{\vrule width 2pt\quad}
   ketchup&marinara&mayonnaise&mustard\cr
   \noalign{\vrule width 2pt\quad}
   rarebit&tartar\cr
   \noalign{\vrule width 2pt\quad}}}
\endexample
\enddesc

\begindesc
\cts tabskip {\param{glue}}
\explain
This parameter specifies the amount of horizontal or vertical glue 
that \TeX\ puts between the 
columns of a horizontal alignment or between the
rows of a vertical alignment.
\TeX\ also puts the |\tabskip| glue 
to the left of the first column and to the right of the last column
of a horizontal alignment, and
above the first row
and below the last row of a vertical alignment.
You can change |\tabskip| within a template---%
the change will affect the glue associated with all the following
|&|'s as well as the glue after the last row or column.
\example
\halign to 3.5in{%
   \hfil\it#\tabskip = 2em plus 8pt
      \hfil&\hfil#\hfil&#\tabskip = 1em
      &\hfil\$#\tabskip = 0em\cr
   United States&Washington&dollar&1.00\cr
   France&Paris&franc&0.174\cr
   Israel&Jerusalem&shekel&0.507\cr
   Japan&Tokyo&yen&0.0829\cr}
|
\produces
\halign to 3.5in{%
   \hfil\it#\tabskip = 2em plus 8pt
      \hfil&\hfil#\hfil&#\tabskip = 1em
      &\hfil\$#\tabskip = 0em\cr
   United States&Washington&dollar&1.00\cr
   France&Paris&franc&0.174\cr
   Israel&Jerusalem&shekel&0.507\cr
   Japan&Tokyo&yen&0.0829\cr}
\nextexample
{\hsize = 1in \parindent=0pt \tabskip=5pt
\valign{#\strut&#\strut\tabskip = 3pt
   &#\strut&#\strut\cr
   bernaise&curry&hoisin&hollandaise\cr
   ketchup&marinara&mayonnaise&mustard\cr
   rarebit&tartar\cr}}
|
\produces
{\hsize = 1in \parindent=0pt \tabskip=5pt
\valign{#\strut&#\strut\tabskip = 3pt
   &#\strut&#\strut\cr
   bernaise&curry&hoisin&hollandaise\cr
   ketchup&marinara&mayonnaise&mustard\cr
   rarebit&tartar\cr}}
\endexample
\enddesc

\begindesc
\cts hidewidth {}
\explain
This command tells \TeX\ to ignore the width of the next column entry in a
horizontal alignment.  It's useful when you have an entry that is longer
than most of the others in the same column,
and you'd rather have that entry stick out of the column than
make all the entries
in the column wider.  If the |\hidewidth| is at the left of the
entry, the entry sticks out to the left; if the |\hidewidth| is at the
right of the entry, the entry sticks out to the~right.
\example
\tabskip = 25pt\halign{%
   \hfil\it#\hfil&\hfil#\hfil&#&\hfil\$#\cr
   United States&\hidewidth Washington&
      dollar&1.00\cr
   France&Paris&franc&0.174\cr
   Israel&Jerusalem&shekel&0.507\cr
   Japan&Tokyo&yen&0.0829\cr}
|
\produces
\tabskip = 25pt\halign{%
   \hfil\it#\hfil&\hfil#\hfil&#&\hfil\$#\cr
   United States&\hidewidth Washington&
      dollar&1.00\cr
   France&Paris&franc&0.174\cr
   Israel&Jerusalem&shekel&0.507\cr
   Japan&Tokyo&yen&0.0829\cr}
\endexample
\enddesc

\begindesc
\cts everycr {\param{token list}}
\explain
\TeX\ expands \<token list> whenever it executes
a |\cr|---at the end of every preamble,
at the end of every row of a horizontal alignment,
and at the end of every column of a vertical alignment.
The |\everycr| commands are expanded just after the |\cr|.
Thus you can cause \TeX\ to
execute certain commands at the end of a preamble, row, or column by
assigning a list of those commands to |\everycr|.

The |\everycr| tokens shouldn't include any commands other than |\no!-align|.
That's because 
the |\everycr| tokens will reappear after the last
|\cr| of the alignment. A command other than
|\noalign| will then make \TeX\ think that it's starting a new
row or column.
\TeX\ will complain about a missing |\cr|, insert
a |\cr|, insert the |\everycr| tokens again, and repeat these actions
indefinitely. 
\example
\everycr={\noalign{\smallskip\hrule\smallskip}}
\halign{#\tabskip = 11pt&\hfil#\hfil&\hfil#\hfil
      \tabskip = 0pt\cr
   $1$&one&first\cr
   $2$&two&second\cr
   $3$&three&third\cr}
|
\produces
\medskip
\everycr={\noalign{\smallskip\hrule\smallskip}}
\halign{#\tabskip = 11pt&\hfil#\hfil&\hfil#\hfil
      \tabskip = 0pt\cr
   $1$&one&first\cr
   $2$&two&second\cr
   $3$&three&third\cr}
\endexample

\eix^^{alignments//commands for}
\enddesc

\enddescriptions


\endchapter
\byebye