summaryrefslogtreecommitdiff
path: root/info/impatient/modes.tex
blob: 1adce6a950a6ec27ea96bcd660360d3a58d2f5d6 (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
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
1807
1808
1809
1810
1811
1812
1813
1814
1815
1816
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
1833
1834
1835
1836
1837
1838
1839
1840
1841
1842
1843
1844
1845
1846
1847
1848
1849
1850
1851
1852
1853
1854
1855
1856
1857
1858
1859
1860
1861
1862
1863
1864
1865
1866
1867
1868
1869
1870
1871
1872
1873
1874
1875
1876
1877
1878
1879
1880
1881
1882
1883
1884
1885
1886
1887
1888
1889
1890
1891
1892
1893
1894
1895
1896
1897
1898
1899
1900
1901
1902
1903
1904
1905
1906
1907
1908
1909
1910
1911
1912
1913
1914
1915
1916
1917
1918
1919
1920
1921
1922
1923
1924
1925
1926
1927
1928
1929
1930
1931
1932
1933
1934
1935
1936
1937
1938
1939
1940
1941
1942
1943
1944
1945
1946
1947
1948
1949
1950
1951
1952
1953
1954
1955
1956
1957
1958
1959
1960
1961
1962
1963
1964
1965
1966
1967
1968
1969
1970
1971
1972
1973
1974
1975
1976
1977
1978
1979
1980
1981
1982
1983
1984
1985
1986
1987
1988
1989
1990
1991
1992
1993
1994
1995
1996
1997
1998
1999
2000
2001
2002
2003
2004
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
2027
2028
2029
2030
2031
2032
2033
2034
2035
2036
2037
2038
2039
2040
2041
2042
2043
2044
2045
2046
2047
2048
2049
2050
2051
2052
2053
2054
2055
2056
2057
2058
2059
2060
2061
2062
2063
2064
2065
2066
2067
2068
2069
2070
2071
2072
2073
2074
2075
2076
2077
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&yen&0.0829\cr}
|
\produces
\tabskip = 1em \halign{%
   \hfil\it#\hfil&\hfil#\hfil&#&\hfil\$#\cr
   United States&Washington&dollar&1.00\cr
   France&Paris&franc&0.174\cr
   Israel&Jerusalem&shekel&0.507\cr
   Japan&Tokyo&yen&0.0829\cr}
\endexample
\enddesc

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

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

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

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

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

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

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

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

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

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

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

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

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


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

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

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

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

\eix^^{template}
\enddesc

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

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

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

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

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

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

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

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

\enddescriptions


\endchapter
\byebye