diff options
author | Norbert Preining <norbert@preining.info> | 2019-09-02 13:46:59 +0900 |
---|---|---|
committer | Norbert Preining <norbert@preining.info> | 2019-09-02 13:46:59 +0900 |
commit | e0c6872cf40896c7be36b11dcc744620f10adf1d (patch) | |
tree | 60335e10d2f4354b0674ec22d7b53f0f8abee672 /info/impatient/modes.tex |
Initial commit
Diffstat (limited to 'info/impatient/modes.tex')
-rw-r--r-- | info/impatient/modes.tex | 2078 |
1 files changed, 2078 insertions, 0 deletions
diff --git a/info/impatient/modes.tex b/info/impatient/modes.tex new file mode 100644 index 0000000000..1adce6a950 --- /dev/null +++ b/info/impatient/modes.tex @@ -0,0 +1,2078 @@ +% 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¥&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¥&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¥&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¥&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¥&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¥&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¥&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¥&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¥&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¥&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¥&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¥&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 |