%-*-tex-*- \ifundefined{writestatus} \input status \relax \fi % \chcode{basbox} \def\cqu{} \chapterhead{basbox}{BASIC\cr BOX\cr COMMANDS} \TeX 's major preoccupation is to make boxes. This chapter discusses the basic commands that create and use boxes. Boxes can be acquired, measured, split, copied, and squashed. \tex\ allows almost anything that can be done on a page to be done inside a box. \shead{boxcom}{Command List} \beginthreecolumn \pri|\box| \ext|\boxit| \pri|\boxmaxdepth| \pri|\copy| \pla|\centerline| \pri|\dp| \pri|\everyhbox| \pri|\everyvbox| \pri|\hbox| \pri|\ht| \pri|\hrule| \pla|\leftline| \pla|\line| \pla|\llap| \pri|\lower| \pla|\newbox| \pri|\raise| \pla|\rightline| \pla|\rlap| \pri|\setbox| \ext|\strut| \pri|\unhbox| \pri|\unhcopy| \pri|\unvbox| \pri|\unvcopy| \pri|\vbox| \pri|\vcenter| \pri|\vrule| \pri|\vsplit| \pri|\vtop| \pri|\wd| \ext|\zerocenteredbox| \endthreecolumn \shead{boxtype}{Vertical and Horizontal Boxes} There are two kinds of boxes, horizontal and vertical. This differentiation is only one of {\it use}, not of quality. All boxes have a height |\ht|, width |\wd|, and depth |\dp|, and reference point. The reference point is at the left hand end of the {\it baseline} of the box. \boxexample \noindent Horizontal lists of boxes are lined up along their baselines. Vertical lists of boxes are lined up along their reference points. The major difference is that an |\hbox| contains a {\it horizontal} list of commands and boxes and assembles these on a horizontal line while a |\vbox| contains vertical list of commands and boxes and assembles them on top of each other in a vertical list. While inside a horizontal box, \tex\ is said to be in {\it internal} horizontal mode. This is the mode that is wanted when there is some centering or other coercive placement of text on a line required. The inside of a vertical box is known as {\it internal vertical mode}. Almost anything that can be done on a page can also be done inside a vertical box. The {\bf width} of a |\vbox| is determined in the following way: if the mode inside the box is never changed from vertical, the box width is the {\it natural} width of the material inside; if the mode in the box changes to either horizontal or mathematics, the width of the box is the current value of |\hsize|. If it has not been changed, |\hsize| will probably be the width of a page. The mode in the box will be changed to horizontal if there is either mathematics or ordinary text placed in the box without first being enclosed in an |\hbox| such as a |\centerline|. One box is very special, namely box 255. This box is the page building box and only material in this box is acted upon by the page builder and breaker. When \tex\ is in this box, it is said to be in (non-internal) {\it vertical} mode. Although only box 255 can be worked upon by the page builder, other boxes can be split, using rules similar to the page builder by the |\vsplit| command. It is possible then to accumulate text in a long vertical box for future splitting when the length of the box is known. A newbox is acquired by |\newbox|. Text is placed in a box using the |\setbox| command and removed using any one of a number of |\box|, |\copy| or |\unvbox| commands, with various effects on the box contents. Boxes may be superimposed by forcing their height, depth, and width to be zero, making sure there is appropriate internal glue to allow the contents to spill out and prevent overfull boxes. The commands |\rlap| and |\llap| allow for horizontal superposition of |\hboxes|. As might be expected, the effects can be interesting. Box registers are numbered from 0 to 255. |\newbox\| allocates an unused box number and assigns it the symbolic name |\| which now can be used wherever there is a need for a box number. The following example does not result in an overfull box and illustrates a number of the commands in this section. The intent is to acquire a box, put a character into it, coerce its size down to a point, and then to move it around so that the result is an overlapping pattern of the character. The result is \newbox\testbox \setbox\testbox = \vbox{\hbox{$\bigodot$\hss}\vss} \dp\testbox=0pt \ht\testbox=0pt \wd\testbox=0pt \centerline{.\copy\testbox \lower1ex\copy\testbox \hskip .5em \lower1ex\copy\testbox} \vskip .25in It is obtained, with accompanying explanation, by \begintt \newbox\testbox %allocates a newbox called \testbox \setbox\testbox = \vbox{\hbox{$\bigodot$\hss}\vss} % sets the box \testbox to be a \vbox -- the \vss % and \hss prevent the overfull box \dp\testbox=0pt \ht\testbox=0pt \wd\testbox=0pt % the size of \testbox is now 0 -- the \vss and % \hss above leave the reference point in the upper % lefthand corner \centerline{.\copy\testbox \lower1ex\copy\testbox \hskip .5em \lower1ex\copy\testbox} % the . is for reference --- the centerline puts it % in the middle of the page \endtt \shead{boxcomforms}{Command Forms} \beginblockmode \pri\@|\box{}| \nbr This command takes the ||, whether a |\vbox| or |\hbox|, and places it at that point in the present list. The resulting || is now empty. \mbr \ext\@|\boxit{}{}{}| \nbr |\boxit| takes the box, or vertical list and puts a box around it with a border separated from the || by || and a having a thickness of ||. For example \centerline{\boxit{2pt}{3pt}{\hbox{Center}}} is given by \begintt \centerline{\boxit{2pt}{3pt}{\hbox{Center}}} \endtt \mbr \pri\@|\boxmaxdepth [=] | \nbr This sets the maximum box depth to ||. If the natural depth of the box is greater than ||, the box is raised (increasing its natural height) until the depth does equal ||. \mbr \pri\@|\copy{}| \nbr This takes the || and puts it in the present list. The box contents are {\bf not} destroyed. \mbr \pla\@|\line{}| \nbr \pla\@|\centerline{}| \nbr \pla\@|\leftline{}| \nbr \pla\@|\rightline{}| \nbr |\line| is an |\hbox| the same size as |\hsize|, the natural size of the enclosing box such as a page. |\leftline|, |\centerline|, |\rightline| respectively take the || and force it to the left, middle, and right parts of the box. |\line| is identical to |\hbox to \hsize{}|. |\leftline| is |\line{\hss}|, |\centerline| is |\line{\hss\hss}|, and |\rightline| is |\line{\hss}|. \mbr \pri\@|\box dimensions ... \dp \ht \wd| \nbr \pri\@|\dp [=] \ht [=] \wd [=] | \nbr The commands |\dp \ht \wd| refer to the depth, height, and depth of the ||. The form above sets the || to these dimensions. \mbr \pri\@|\dp \ht \wd| \nbr These forms are all valid || and can be used when ever a || is valid. For instance |\hsize = .378\wd\testbox| is a valid assignment for |\hsize| as long as |\testbox| is a valid box number. These forms are useful for some types of arithmetic. \mbr \pri\@|\everyhbox = {}| \nbr \pri\@|\everyvbox = {}| \nbr This command inserts the || as the first set of commands whenever an |\hbox| or |\vbox|, respectively is entered by \tex. \mbr \pri\@|\hbox {}| \nbr \pri\@|\vbox {}| \nbr These insert |\hbox| and |\vbox| respectively, according to the || and containing the |<... list>|. The || is a specification sequence for the box. \mbr \pri\@|| \nbr The || is one of the following: \nbr \bshortcomlist \noalign{\vskip -\lastskip} | to |&this sets a |\hbox| to width || or a |\vbox| to height || ; if || is |\hsize|, the box is the natural width of the surrounding box or page \cr ||&this lets the box take on its natural width or height\cr \eshortcomlist \pri\@|\vbox{\hsize [=] }| \nbr This creates a |\vbox| with a specified horizontal dimension. {\bf This box will accept almost anything that can be put on a page including display mathematics, |\centerline|, and ordinary text.} It is the basic mechanism for creating boxes that look like pages for future pasting up into a page.\footnote{\dagger}{This replaces the |\hbox par {<...>}| in \tex78.} \mbr \pri\@|\hrule [height ] [width ] [depth ]| \nbr \pri\@|\vrule [height ] [width ] [depth ]| \nbr These commands create lines of the specified height, width, and depth. Any or all of the parameters may be omitted. The |\vrule| is used in {\it horizontal} mode and the |\hrule| is used in {\it vertical} mode. If there is no dimension given the {\it rule} is the natural size of the enclosing box. For instance, on a page the enclosing box is the page itself. Thus \begintt \par \hrule \endtt gives \par \hrule a line across the entire page. Rules are used to make the lines in the |\boxit| macro earlier in this section. \mbr \pla\@|\llap{}| \nbr \pla\@|\rlap{}| \nbr These commands allow || to be superimposed on the text around it. The |\rlap| creates a box of width 0pt and forces the || out to the right. |\llap| does the same thing but to the left. Thus |\rlap{A}$\odot$| and |A\llap{$\odot$}| give the same result namely \rlap{A}$\odot$, and A\llap{$\odot$} respectively. This is a way to put text into either margin. \mbr \pri\@|\lower| \nbr \pri\@|\raise| \nbr These commands work only in {\it (internal) horizontal} mode. They lower or raise the || by the ||. An example of their use was illustrated in the previous section. \mbr \pri\@|\setbox [=] {}| \nbr This is the basic command for putting contents in a ||. The || is any valid |\hbox| or |\vbox| including a || if desired. The || is either vertical or horizontal depending upon the box type. \mbr \ext\@|\strut| \nbr |\strut| is a |\vrule| of zero width, with height and depth for normal baseline spacing in the current font point size family. It is useful in |\vbox{\hsize \strut \strut}|. The two |\strut|s will ensure correct spacing when boxes of this sort are stacked upon each other. \mbr \pri\@|\unhbox{}| \nbr \pri\@|\unhcopy{}| \nbr \pri\@|\unvbox{}| \nbr \pri\@|\unvcopy{}| \nbr These commands take the contents of the ||, remove the outer box, unset the internal glue, and put it in the list at this point. The |..box| forms destroy the contents of the box and leave it |void|, while the |..copy| forms do not. \mbr \pri\@|\vcenter{}| \nbr This command works in {\it math} or {\it display math} mode only. It creates a |vbox| out of the || and sets the reference baseline in the center of the resultant box. It is used for centering expressions in display mathematics. \mbr \pri\@|\vsplit to | \nbr A new |vbox| with height || and maximum depth \@|\splitmaxdepth| is created from the contents of ||. Any remains are left in the ||. This is useful for some simple multicolumn forms. \mbr \pri|\vtop {}| \nbr This command creates a |vbox| with the baseline reference of that box being the baseline of the {\bf first box} in the ||. This is useful in the following way. This quotation \centerline{\veryraggedright \vtop{\hsize 1.8in The plans of the diligent lead surely to abundance, but every one that is hasty comes only to want.} \hss \vtop{\hsize 1.8in This quotation comes from {\it Proverbs 21, Verse 5}. It suggests care.} } is given by \begintt \centerline{\veryraggedright \vtop{\hsize 1.8in The plans of the diligent lead surely to abundance, but every one that is hasty comes only to want.} \hss \vtop{\hsize 1.8in This quotation comes from {\it Proverbs 21, Verse 5}. It suggests care.} } \endtt Note that these are lined up on the first rows. \mbr \ext|\zerocenteredbox {}| \nbr This creates an |hbox| of zero height and depth with the width of the ||. Thus a |\zerocenteredbox{\bf point}| gives \zerocenteredbox{\bf point}\ with the placement as shown. The reference point of the box is at the center of the text which effectively lowers it to the baseline. This command is intended for use in making tables. See Chapter~{\ref{align}} for more details. \endblockmode \ejectpage \done