summaryrefslogtreecommitdiff
path: root/macros/inrstex/inrsdoc/thbasbox.tex
blob: 86f7b6d2e9a37b351a32a3758199e1526ffafb17 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
%-*-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\<box name>| allocates an unused box number
and assigns it the symbolic name |\<box 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{<named box>}|
\nbr
This command takes the |<named box>|, whether a |\vbox| or
|\hbox|, and places it at that point in the present list. The resulting
|<named box>| is now empty.

\mbr
\ext\@|\boxit{<line thickness>}{<border separation>}{<box, vlist>}|
\nbr
|\boxit| takes the box, or vertical list and puts a box around it with a
border separated from the |<box>| by |<border separation>| and a having a
thickness of |<line thickness>|. For example

\centerline{\boxit{2pt}{3pt}{\hbox{Center}}}
is given by
\begintt
\centerline{\boxit{2pt}{3pt}{\hbox{Center}}}
\endtt

\mbr
\pri\@|\boxmaxdepth [=] <dimen>|
\nbr
This sets the maximum box depth to |<dimen>|. If the natural depth of the box
is greater than |<dimen>|, the box is raised (increasing its natural height)
until the depth does equal |<dimen>|. 

\mbr
\pri\@|\copy{<named box>}|
\nbr
This takes the |<named box>| and puts it in the present list. The box
contents are {\bf not} destroyed.


\mbr
\pla\@|\line{<horizontal list>}|
\nbr
\pla\@|\centerline{<horizontal list>}|
\nbr
\pla\@|\leftline{<horizontal list>}|
\nbr
\pla\@|\rightline{<horizontal list>}|
\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 |<horizontal list>| and force it to the left, middle,
and right parts of the box. 
|\line| is identical to |\hbox to \hsize{<horizontal list>}|. |\leftline| is 
|\line{<horizontal list>\hss}|, |\centerline| is |\line{\hss<horizontal
list>\hss}|, and |\rightline| is |\line{\hss<horizontal list>}|.

\mbr
\pri\@|\box dimensions ... \dp \ht \wd|
\nbr
\pri\@|\dp<named box> [=] <dimen> 
     \ht<named box> [=] <dimen> 
     \wd<named box> [=] <dimen>|
\nbr
The commands |\dp \ht \wd| refer to the depth, height, and depth of the
|<named box>|. The form above sets the |<named box>| to these dimensions.


\mbr
\pri\@|<scale factor>\dp<named box>
     <scale factor>\ht<named box>
     <scale factor>\wd<named box>|
\nbr
These forms are all valid |<dimen>| and can be used when ever a |<dimen>| 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 = {<token list>}|
\nbr
\pri\@|\everyvbox = {<token list>}|
\nbr
This command inserts the |<token list>| as the first set of commands whenever
an |\hbox| or |\vbox|, respectively is entered by \tex. 

\mbr
\pri\@|\hbox <box spec>{<horizontal list>}|
\nbr
\pri\@|\vbox <box spec>{<vertical list>}|
\nbr
These insert |\hbox| and |\vbox| respectively, according to the |<box spec>|
and containing the |<... list>|. The |<box spec>| is a specification sequence
for the box. 

\mbr
\pri\@|<box spec>|
\nbr
The |<box spec>| is one of the following: 
\nbr
\bshortcomlist
\noalign{\vskip -\lastskip}
| to <dimen>|&this sets a
|\hbox| to width |<dimen>| or a |\vbox| to height |<dimen>| ; if |<dimen>| is
|\hsize|, the box is the natural width of the surrounding box or page \cr
|<nothing>|&this lets the box take on its natural width or height\cr
\eshortcomlist

\pri\@|\vbox{\hsize [=] <dimen> <text>}|
\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 <dimen>{<...>}| in
\tex78.}

\mbr
\pri\@|\hrule [height <dimen>] [width <dimen>] [depth <dimen>]|
\nbr
\pri\@|\vrule [height <dimen>] [width <dimen>] [depth <dimen>]|
\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{<text>}|
\nbr
\pla\@|\rlap{<text>}|
\nbr
These commands allow  |<text>| to be superimposed on the text around it.
The |\rlap| creates a box of width 0pt and forces the |<text>| 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<dimen><box>|
\nbr
\pri\@|\raise<dimen><box>|
\nbr
These commands work only in {\it (internal) horizontal} mode. They lower or
raise the |<box>| by the |<dimen>|. An example of their use was illustrated
in the previous section.

\mbr
\pri\@|\setbox<named box> [=] <box>{<list>}|
\nbr
This is the basic command for putting contents in a |<named box>|. The
|<box>| is any valid |\hbox| or |\vbox| including a |<box spec>| if desired.
The |<list>| 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 <dimen> \strut <text> \strut}|. The two |\strut|s will
ensure correct spacing when boxes of this sort are stacked upon each other.


\mbr
\pri\@|\unhbox{<named hbox>}|
\nbr
\pri\@|\unhcopy{<named hbox>}|
\nbr
\pri\@|\unvbox{<named vbox>}|
\nbr
\pri\@|\unvcopy{<named vbox>}|
\nbr
These commands take the contents of the |<named box>|, 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{<vertical list>}|
\nbr
This command works in {\it math} or {\it display math} mode only. It creates
a |vbox| out of the |<vertical list>| and sets the reference baseline in the
center of the resultant box. It is used for centering expressions in display
mathematics.

\mbr
\pri\@|\vsplit<named box> to <dimen>|
\nbr
A new |vbox| with height |<dimen>| and maximum depth
\@|\splitmaxdepth| is created from the contents of |<named box>|. Any remains are left in
the |<named box>|. This is useful for some simple multicolumn forms.


\mbr
\pri|\vtop <box spec>{<vertical list>}|
\nbr
This command creates a |vbox| with the baseline reference of that box
being the baseline of the {\bf first box} in the |<vertical list>|. 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 {<text>}|
\nbr
This creates an |hbox| of zero height and depth with the width of the
|<text>|.  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