summaryrefslogtreecommitdiff
path: root/info/impatient/pages.tex
blob: 230802e9b5f3e6f7cec712b9b25ac4f00531d65f (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
% 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 composing pages}

\chapterdef{pages}

This section covers commands that deal with
pages, their components, and the output routine.
For an explanation of the conventions used in this section,
see \headcit{Descriptions of the commands}{cmddesc}.

\begindescriptions

%==========================================================================
\section {Interline and interparagraph spaces}

\begindesc
\cts baselineskip {\param{glue}}
\cts lineskiplimit {\param{dimen}}
\cts lineskip {\param{glue}}
\explain
^^{line spacing}
\bix^^{interline glue}
\bix^^|\baselineskip|
\bix^^|\lineskip|
\bix^^|\lineskiplimit|
These three parameters jointly determine how much space \TeX\ leaves between
consecutive \minref{box}es of an ordinary \minref{vertical list},
e.g., the lines of a paragraph.  
This space is called ``\minref{interline glue}''.
It is also inserted between the component boxes of a vbox constructed in
internal vertical mode.
^^{vboxes//interline glue for}

In the usual case, when the boxes aren't abnormally high or deep, \TeX\
makes the distance from the baseline of one box to the baseline of the
next one equal to |\baselineskip|.  It does this by inserting interline
glue equal to |\baselineskip| minus the depth of the upper box (as given
by ^|\prevdepth|) and the height of the lower box.  But if this
interline glue would be less than |\lineskiplimit|, indicating that the
two boxes are too close together, \TeX\ inserts the |\lineskip| glue
instead.\footnote
{\TeX\ actually accounts for the beginning of a
vertical list by setting |\prevdepth| to $-1000$\pt\ and testing
|\prevdepth| before \emph{every} box.  If |\prevdepth|$\>\le-1000$\pt\
it does not insert any interline glue.} See \knuth{pages~79--80} for a
precise description.

Note that |\baselineskip| and |\lineskip| measure \emph{different
things}: the distance between baselines on the one hand and the distance
between the bottom of one box and the top of the next box on the other
hand.  See \knuth{page~78} for further details.  The first example below
shows the effects of |\lineskiplimit|.

You can obtain the effect of ^{double spacing} by doubling the value
of |\baselineskip| as illustrated in the second example below.
A change to |\baselineskip| at any point before the end of a paragraph affects
the entire paragraph.

\example
\baselineskip = 11pt \lineskiplimit = 1pt
\lineskip = 2pt plus .5pt
Sometimes you'll need to typeset a paragraph that has
tall material, such as a mathematical formula,  embedded
within it.  An example of such a formula is $n \choose k$.
Note the extra space above and below this line as
compared with the other lines.
(If the formula didn't project below the line,
we'd only get extra space above the line.)
|
\produces
\baselineskip = 11pt \lineskiplimit = 1pt
\lineskip = 2pt plus .5pt
Sometimes you'll need to typeset a paragraph that has
tall material, such as a mathematical formula,  embedded
within it.  An example of such a formula is $n \choose k$.
Note the extra space above and below this line as
compared with the other lines.
(If the formula didn't project below the line,
we'd only get extra space above the line.)
\endexample

\example
\baselineskip = 2\baselineskip % Start double spacing.
|
\endexample

\eix^^{interline glue}
\eix^^|\baselineskip|
\eix^^|\lineskip|
\eix^^|\lineskiplimit|
\enddesc

\begindesc
\cts prevdepth {\param{dimen}}
\explain
When \TeX\ adds a box to a vertical list, it sets |\prevdepth| to the
depth of that box.  \TeX\ sets |\prevdepth| to $-1000$\pt\ at the start
of a vertical list, indicating that the usual interline glue should be
suppressed.
\enddesc

\begindesc
\cts normalbaselineskip {\param{glue}}
\cts normallineskiplimit {\param{dimen}}
\cts normallineskip {\param{glue}}
\cts normalbaselines {}
\explain
The three parameters contain values for |\base!-line!-skip|,
|\line!-skip|, and |\line!-skip!-limit| respectively.
^^|\baselineskip| ^^|\lineskip| ^^|\lineskiplimit|
The |\normalbaselines| command sets |\base!-line!-skip|,
|\line!-skip|, and |\line!-skip!-limit| to the values contained in the
three parameters.
\enddesc

\begindesc
\cts offinterlineskip {}
\explain
This command tells \TeX\ to stop inserting interline glue from
now on.  Unless you want it to be in effect for the rest of the document
(which you probably don't), you should enclose it in a group
together with the text you want it to affect.
Its main purpose is to let you do interline spacing yourself,
e.g., using ^{struts},
without interference from \TeX's normal interline glue.
|\offinterlineskip| is often useful when
you're constructing a horizontal \minref{alignment}.
^^{alignments//using \b\tt\\offinterlineskip\e\ in}
\example
\def\entry#1:#2 {\strut\quad#1\quad&\quad#2\quad\cr}
\offinterlineskip \tabskip = 0pt \halign{%
\vrule\quad\hfil#\hfil\quad\vrule&
   \quad\hfil#\hfil\quad\vrule\cr
\noalign{\hrule}
\vphantom{\vrule height 2pt}&\cr \noalign{\hrule}
\entry \it Opera:\it Composer
\vphantom{\vrule height 2pt}&\cr \noalign{\hrule}
\vphantom{\vrule height 2pt}&\cr
\entry Fidelio:Beethoven
\entry Peter Grimes:Britten
\entry Don Giovanni:Mozart
\vphantom{\vrule height 2pt}&\cr \noalign{\hrule}}
|
\produces
\medskip
\def\entry#1:#2 {\strut\quad#1\quad&\quad#2\quad\cr}
\offinterlineskip \tabskip = 0pt \halign{%
\vrule\quad\hfil#\hfil\quad\vrule&
   \quad\hfil#\hfil\quad\vrule\cr
\noalign{\hrule}
\vphantom{\vrule height 2pt}&\cr \noalign{\hrule}
\entry \it Opera:\it Composer
\vphantom{\vrule height 2pt}&\cr \noalign{\hrule}
\vphantom{\vrule height 2pt}&\cr
\entry Fidelio:Beethoven
\entry Peter Grimes:Britten
\entry Don Giovanni:Mozart
\vphantom{\vrule height 2pt}&\cr \noalign{\hrule}}
\endexample
\enddesc

\begindesc
\cts nointerlineskip {}
\explain
This command tells \TeX\ not to insert interline glue in front of the
next line.
It has no effect on subsequent lines.
\enddesc

\begindesc
\cts openup {\<dimen>}
\explain
This command increases ^|\baselineskip| by \<dimen>.
An |\openup| command before the end of a paragraph affects
the entire paragraph, so you shouldn't use |\openup| to
change |\baseline!-skip| within a paragraph.  |\openup| is
most useful for typesetting tables and math displays---a
little extra space between rows often makes them more readable.
^^{alignments//space between rows of}
\example
Alice picked up the White King very gently, and lifted him 
across more slowly than she had lifted the Queen; but before
she put him on the table, she thought she might well dust
him a little, he was so covered with ashes.
\openup .5\baselineskip % 1.5 linespacing.
|
\produces
Alice picked up the White King very gently, and lifted him 
across more slowly than she had lifted the Queen; but before
she put him on the table, she thought she might well dust
him a little, he was so covered with ashes.
\openup .5\baselineskip %1.5 linespacing
\endexample\enddesc

%==========================================================================
\section {Page breaks}

%==========================================================================
\subsection {Encouraging or discouraging page breaks}

\begindesc
\bix^^{page breaks}
\bix^^{page breaks//encouraging or discouraging}
\ctspecial break {} \xrdef{vbreak}
\explain
%
\margin{Four commands identical to ones for line breaks (\xref{hbreak})
have been added to correct an omission. The descriptions are exactly parallel.}
%
This command forces a page break.
Unless you do something to fill out the page, you're likely to
get an underfull vbox.
|\break| can also be used in horizontal mode.
\enddesc

\begindesc
\ctspecial nobreak {} \xrdef{vnobreak}
\explain
This command prevents a page break where it
otherwise might occur.
|\nobreak| can also be used in horizontal mode.
\enddesc

\begindesc
\ctspecial allowbreak {} \xrdef{vallowbreak}
\explain
This command tells \TeX\ to 
allow a page break where one could not ordinarily occur.
|\allowbreak| can also be used in horizontal mode.
\enddesc

\begindesc
\ctspecial penalty {\<number>} \xrdef{vpenalty}
\explain
This command produces a \minref{penalty} item.
The penalty item makes \TeX\ more or less willing to break a page
at the point where that item occurs.
A negative penalty, i.e., a bonus, encourages a page break;
a positive penalty discourages a page break.  
A penalty of $10000$ or more prevents a break altogether,
while a penalty of $-10000$ or less forces a break.
|\penalty| can also be used in horizontal mode.
\example
\def\break{\penalty-10000 } % as in plain TeX
\def\nobreak{\penalty10000 } % as in plain TeX
\def\allowbreak{\penalty0 } % as in plain TeX
|
\endexample
\enddesc

\begindesc
\cts goodbreak {}
\explain
This command ends a paragraph and also indicates to \TeX\ that
this is a good place to break the page.
\enddesc

\begindesc
\cts smallbreak {}
\cts medbreak {}
\cts bigbreak {}
\explain
These commands indicate increasingly desirable places for \TeX\ to
break a page.  They also cause \TeX\ to 
insert a ^|\smallskip|, ^|\medskip|, or
^|\bigskip| (\xref \smallskip) if the page break doesn't actually
happen.  \TeX\ suppresses this skip if it occurs just after an
equal or larger skip.
\enddesc

\begindesc
\easy\cts eject {}
\cts supereject {}
\explain
These commands force a page break at the current position
and end the current paragraph.
If you don't precede them with |\vfil| (\xref \vfil),
^^|\vfil//needed with {\tt\\eject}|
\TeX\ will try to stretch out the page contents
(and will probably complain about an underfull vbox).
The |\supereject| command, in addition,
instructs the \plainTeX\ output routine to
force out any leftover insertions,
^^{insertions//forced out by \b\tt\\supereject\e}
such as long footnotes,
so that they are produced before any more input
is processed. Thus |\supereject| is a good command to use at the end of each
chapter or other major unit of your document.
\enddesc

\begindesc
\cts filbreak {}
\explain
This command provides a kind of conditional page break.
It tells \TeX\ to
break the page---but not if the text up to a later |\filbreak| also 
fits on the same page.
By enclosing a paragraph in a pair of |\filbreak|s,
you can ensure that \TeX\ will keep a paragraph on a single page if it can.
You should not use |\filbreak| within a paragraph, since it 
forces \TeX\ into vertical mode and thus ends the paragraph.
See \xrefpg{filbreak} for more advice on this subject.
\enddesc

\begindesc
\cts raggedbottom {}
\cts normalbottom {}
\explain
Normally \TeX\ tries hard to ensure that all pages have the same depth,
i.e., that their bottom margins are equal.
The |\raggedbottom| command tells \TeX\ to
allow some variability among the bottom margins on different pages.
It's often appropriate to use |\raggedbottom| when you have material that
contains large blocks of material that should not be split across pages.
The |\normalbottom| command cancels the effect of |\raggedbottom|.

\eix^^{page breaks//encouraging or discouraging}
\enddesc

%==========================================================================
\subsection {Page breaking parameters}

\bix^^{page breaks//parameters for}
\begindesc
\cts interlinepenalty {\param{number}}
\explain
This parameter specifies the \minref{penalty} for 
breaking a page between the lines of a paragraph.
By setting it to $10000$ you can force all page breaks to occur
between paragraphs, provided that the pages have enough stretch so
that \TeX\ can still compose them decently.
\PlainTeX\ leaves |\inter!-linepenalty| at~$0$.
\enddesc

\begindesc
\cts clubpenalty {\param{number}}
\explain
^^{club line}
This parameter specifies the \minref{penalty} for 
breaking a page just after the first line of a paragraph.
A line by itself at the bottom of a page is called a ``club line''.
\PlainTeX\ sets |\clubpenalty| to $150$.
\enddesc

\begindesc
\cts widowpenalty {\param{number}}
\explain
^^{widow line}
This parameter specifies the \minref{penalty} for 
breaking a page just before the last line of a paragraph.
A line by itself at the top of a page is called a ``widow line''.
\PlainTeX\ sets |\widowpenalty| to $150$.
\enddesc

\begindesc
\cts displaywidowpenalty {\param{number}}
\explain
^^{widow line}^^{math display}
This parameter specifies the \minref{penalty} for 
breaking a page just before the last line of a partial paragraph
that immediately precedes a math display.
\PlainTeX\ sets |\displaywidowpenalty| to $50$.

\enddesc

\begindesc
\cts predisplaypenalty {\param{number}}
\explain
^^{math display}
This parameter specifies the \minref{penalty} for 
breaking a page just before a math display.
\PlainTeX\ sets |\predisplaypenalty| to $10000$.
\enddesc

\begindesc
\cts postdisplaypenalty {\param{number}}
\explain
^^{math display}
This parameter specifies the \minref{penalty} for 
breaking a page just after a math display.
\PlainTeX\ leaves |\postdisplaypenalty| at $0$.
\enddesc

\begindesc
\cts brokenpenalty {\param{number}}
\explain
This parameter specifies the \minref{penalty} for 
breaking a page just after a line  that ends in
a discretionary item (usually a hyphen).
^^{hyphenation}
|\brokenpenalty| applies to page breaking, while
^|\hyphenpenalty| \ctsref{\hyphenpenalty} applies to line breaking.
\PlainTeX\ sets |\brokenpenalty| to $100$.
\enddesc

\begindesc
\cts insertpenalties {\param{number}}
\explain
\bix^^{insertions//penalties for}
\bix^^{floating material}
This parameter contains the sum of certain penalties \minrefs{penalty}
that \TeX\ accumulates as it is placing insertions onto the
current page.
These penalties are incurred when \TeX\ is processing an |\insert|
command 
and discovers that a previous insertion  of the same kind on this page has
been split, leaving part of it for subsequent pages.
See \knuth{pages~123--125} for the details of this
calculation.

\margin{Material moved from a footnote to the main text.}
|\insertpenalties| has an entirely different meaning during an
^^{output routine//meaning of \b\tt\\insertpenalties\e\ in}
output routine---it's the number of insertions that have been seen
but that don't fit on the current page (see \knuth{page~125}).
\enddesc

\begindesc
\cts floatingpenalty {\param{number}}
\explain
This parameter specifies the \minref{penalty} that
\TeX\ adds to |\insertpenalties|
^^|\insertpenalties|
when the page builder is adding an insertion to the current page
and discovers that a previous insertion  of the same kind on this page has
been split, leaving part of it for subsequent pages.
\PlainTeX\ leaves |\floatingpenalty| at~$0$.
\eix^^{insertions//penalties for}
\eix^^{floating material}

\enddesc

\begindesc
\cts pagegoal {\param{dimen}}
\explain
This parameter specifies the
desired height for the current page.
\TeX\  sets
|\pagegoal| to the current value of |\vsize|
when it first puts a box or an insertion on the current page.
You can shorten a page while \TeX\ is working on it by
changing the value of |\pagegoal|---even if the new value is
less than the height of the material already on that page.
\TeX\ will just put the extra material on the next page.
But remember---|\pagegoal| is reset to |\vsize| again when \TeX\
starts the next page.
\enddesc

\begindesc
\cts pagetotal {\param{dimen}}
\explain
This parameter specifies the
accumulated natural height of the current page.
\TeX\ updates |\pagetotal| as it adds
items to the main \minref{vertical list}.


\enddesc

\begindesc
\cts pagedepth {\param{dimen}}
\explain
This parameter specifies the depth of the current page.
\TeX\ updates |\pagedepth| as it adds
items to the main \minref{vertical list}.
\enddesc

\begindesc
\cts pageshrink {\param{dimen}}
\explain
This parameter specifies the amount of \minref{shrink}
in the accumulated \minref{glue} on the current page.
\TeX\ updates |\pageshrink| as it adds
items to the main \minref{vertical list}.
\enddesc

\begindesc
\cts pagestretch {\param{dimen}}
\cts pagefilstretch {\param{dimen}}
\cts pagefillstretch {\param{dimen}}
\cts pagefilllstretch {\param{dimen}}
\explain
These four parameters together specify the amount of \minref{stretch}
in the \minref{glue} on the current page.  The amount of stretch has
the form
{\def\f#1{\hbox{\tt fi#1}}%
$n_0 + n_1\f{l} + n_2\f{ll} + n_3\f{lll}$}, with the four parameters
giving the values of the four $n_i$.
\TeX\ updates these parameters as it adds
items to the main \minref{vertical list}.

\eix^^{page breaks//parameters for}
\eix^^{page breaks}
\enddesc

%==========================================================================
\section{Page layout}

\subsection {Page description parameters}

\begindesc
\bix^^{page dimensions}
\margin{This command was also described in the `Paragraphs' section.
The combined description now appears there.}
\aux\cts hsize {\param{dimen}}
\explain
This parameter specifies the current line length.
See \xrefpg{\hsize} for a more complete explanation.
\enddesc

\begindesc
\cts vsize {\param{dimen}}
\explain
This parameter specifies the current vertical extent of a page.  
\TeX\ examines it only when it is starting a page.  Thus if you change
|\vsize| in the
middle of a page, your change won't affect anything until the following page.
If you want to change the vertical extent of a page when
you're in the middle of it, you  should assign the new
height to ^|\pagegoal| (\xref \pagegoal) instead.  (If you
want the change to affect the following pages too, you should
change \emph{both} |\vsize| and |\pagegoal|.)
\PlainTeX\ sets |\vsize| to |8.9in|.
\eix^^{page dimensions}
\enddesc

\begindesc
\cts hoffset {\param{dimen}}
\cts voffset {\param{dimen}}
\margin{These commands were moved up from later in the subsection.}
^^{page origin}
\idxsee{origin}{page origin}
\explain
\TeX\ normally takes the ``origin'' of a page, that is, the point where
it starts printing, as being one inch down from the top of the page and one 
inch to the right of the left end of the page.\footnote{
\TeX\ itself is indifferent to where the origin of the page is,
but this information has to be built into the device drivers
^^{device drivers//page origin known to}
that convert \dvifile s into printable form so that different devices
will yield the same results.}
The values of |\hoffset| and
|\voffset| give the horizontal and vertical offset of the actual origin
from this point.  Thus if |\hoffset| and |\voffset| are both
zero, \TeX\ uses its normal origin.
\example
\hoffset = -.3in
   % Start printing .7 inches from left edge of paper.
\voffset = 1in
   % Start printing 2 inches from top edge of paper.
|
\endexample
\enddesc

\begindesc
\cts topskip {\param{glue}}
\explain
\TeX\ inserts glue at the top of each
page in order to ensure that the baseline of the first box on the page
always is the same distance $d$ from the top of the page.
|\topskip| determines the amount of that glue,
called the ``|\topskip| glue'', by specifying
what $d$ should be (provided that the first box
on the page isn't too tall).
$d$ is given by the natural size of the |\topskip| glue.
If the height of the first box on the page exceeds $d$,
so that the glue would be negative, \TeX\ simply inserts no 
|\topskip| glue at all on that page.

To understand better the effect of these rules, assume that |\topskip|
has no stretch or shrink and that the first item on the page is indeed a box.
Then if the height of that box is no greater than |\topskip|,
its baseline will be |\topskip|
from the top of the page independently of its height.  On the other hand,
if the height of the box is $e$ greater than |\topskip|, its baseline will be
|\topskip|\tplus$e$ from the top of the page.
See \knuth{pages~113--114} for the remaining details of how
|\topskip| works.
\PlainTeX\ sets |\topskip| to |10pt|.
\enddesc


\begindesc
\cts parskip {\param{glue}}
\explain
This parameter specifies the ``^{paragraph skip}'', i.e., the
vertical glue that \TeX\ inserts at the start of a paragraph.
^^{paragraphs//glue between}
See |\par| (\xref{\@par}) for more information about what happens
when \TeX\ starts a paragraph.
\PlainTeX\ sets |\parskip| to |0pt plus 0.1pt|.
\enddesc

\begindesc
\cts maxdepth {\param{dimen}}
\explain
This parameter specifies the maximum depth of the bottom \minref{box} on
a page.  It is related to |\boxmaxdepth| (\xref \boxmaxdepth).  If the
depth of the bottom box on a page exceeds |\maxdepth|, \TeX\ moves the
box's reference point down so that it's
|\maxdepth| from the bottom of that box.
Without this adjustment, the bottom box on
a page could extend well into the bottom margin or even off
the page entirely.  \PlainTeX\ sets |\maxdepth| to |4pt|.
\enddesc

%==========================================================================
\subsection{Page numbers}

\begindesc
\bix^^{page numbering}
\cts pageno {\param{number}}
\explain
This parameter contains the current page number as an integer.  The page
number is normally negative for front-matter pages that are numbered
with small roman numerals instead of arabic numerals.  If you change the
page number within a page,
the changed number will be used in any headers or footers that
appear on that page.
The actual
printing of page numbers is handled by \TeX's \minref{output routine},
which you can modify.

\PlainTeX\ keeps the page number in the \minref{register} ^|\count0|.
(|\pageno| is, in fact, a synonym for |\count0|.)  
Whenever it ships out a page to the \dvifile,
^^|\shipout//{\tt\\count} registers displayed at|
\TeX\ displays the current value of |\count0| on your
terminal so that you can tell which page it is working on.
It's possible to use registers |\count1|--|\count9| for nested
levels of page numbers (you must program this yourself).
If any of these registers are nonzero, \TeX\ displays them on your
terminal also.\footnote{
More precisely, it displays all registers in sequence from
|\count0| to |\count9|, but omits trailing zero registers.
For instance, if the values of |\count0|--|\count3|
are $(17, 0 , 0, 7)$ and the others are $0$,
\TeX\ displays the page number as {\tt [17.0.0.7]}.}
\example
This explanation appears on page \number\pageno\
of our book.
|
\produces
This explanation appears on page \number\pageno\
of our book.

\nextexample
\pageno = 30 % Number the next page as 30.
Don't look for this explanation on page \number\pageno.
|
\produces
Don't look for this explanation on page 30.
\endexample
\enddesc

\begindesc
\cts advancepageno {}
\explain
This command adds $1$ to the page number
$n$ in |\pageno| if $n\ge0$
and subtracts $1$ from it if $n<0$.
\enddesc

\begindesc
\easy\cts nopagenumbers {}
\explain
By default, \plainTeX\ produces a footer containing a centered page number.
This command tells \TeX\ to produce a blank footer instead.
\enddesc

\begindesc
\cts folio {}
\explain
This command produces the current page number, whose value is the number
$n$ contained in ^|\pageno|.
If  $n\ge0$,
\TeX\ produces $n$ as a decimal number,
while if $n<0$,
\TeX\ produces $-n$ in lowercase roman numerals.
\example
This explanation appears on page \folio\ of the book.
|
\produces
This explanation appears on page \folio\ of the book.
\endexample

\eix^^{page numbering}
\enddesc


%==========================================================================
\subsection{Header and footer lines}

\begindesc\secondprinting{\vglue-.75\baselineskip\vskip0pt}
\cts headline {\param{token list}}
\cts footline {\param{token list}}
\explain
These parameters
contain, respectively, the current headline (header) and the current
footline (footer).
The \plainTeX\ output routine
places the headline at the top of each page and the footline
at the bottom of each page.
The default headline is empty and the default footline is a centered
page number.

The headline and footline should both
be as wide as |\hsize| (use |\hfil|, \xref{\hfil}, for this
if necessary).
You should always include a font-setting command in these lines, since
the current font is unpredictable when \TeX\ is calling the
output routine.  If you don't set the font explicitly,
you'll get whatever font \TeX\ was using when it broke the page.

You shouldn't try to use |\headline| or |\footline|
to produce multiline headers or footers.
Although \TeX\ won't complain, it will give you something that's very ugly.
See \xrefpg{bighead} for a method of creating multiline headers or
footers.
\example
\headline = {\tenrm My First Reader\hfil Page \folio}
|
\produces
\pageno = 10
\line{\tenrm \noindent My First Reader\hfil Page \folio}
\par ({\it at the top of page \folio}\/)
\nextexample
\footline = {\tenit\ifodd\pageno\hfil\folio
           \else\folio\hfil\fi}
% Produce the page number in ten-point italic at 
% the outside bottom corner of each page.
|
\endexample\enddesc

\secondprinting{\vfill\eject}


%==========================================================================
\subsection {Marks}

\begindesc
\cts mark {\rqbraces{\<text>}}
\explain
\bix^^{marks}
This command causes \TeX\ to append a mark
containing \<mark text>
to whatever list it is currently constructing.
Generally you shouldn't use |\mark| within an
``inner'' construct such as a math formula or a \minref{box}
you've built with an |\hbox|, |\vbox|, or |\vtop| command, because
\TeX\ won't see the mark when it's constructing the main box of the page.  But
if you use |\mark| in ordinary horizontal \minref{mode}
or directly in an hbox that's part of the main vertical list,
the mark migrates out
to the main \minref{vertical list}.
See \knuth{pages~259--260} for examples showing how |\mark| can be used.
\enddesc

\begindesc
\cts firstmark {}
\cts botmark {}
\cts topmark {}
\explain
These commands expand to the mark text in an item generated by an earlier
^|\mark| command.  
The mark text has the form of a token list.
\TeX\ sets the values of these commands when it
finishes placing the contents of a page into ^|\box255|, 
just before calling the \minref{output routine}
as part of its \minref{page break}ing actions.  \TeX\ determines
these values as follows:
\ulist\compact
\li |\firstmark| contains the tokens of the first mark on the page.
\li |\botmark| contains the tokens of the last mark on the page.
\li |\topmark| contains the tokens of the mark that is in effect at
the very top of the page.
That mark is the last mark
that \emph{preceded} the page,
i.e., the |\botmark| of the previous page.
It is empty if no marks preceded the page.
\endulist
\noindent
If a page has no marks on it, \TeX\ will set |\firstmark| and |\botmark| to
the same mark as |\topmark|, i.e., the most recent preceding mark.
The table at the bottom of \knuth{page~258} illustrates the relation among
|\firstmark|, |\botmark|, and |\topmark|.
\enddesc

\begindesc
\cts splitfirstmark {}
\cts splitbotmark {}
\explain
^^{marks//for split lists}
These commands expand to the ^{mark text} generated by an earlier
^|\mark| command that produced an item in the item list of a vbox $V$.
The mark text has the form of a token list.
When \TeX\ 
splits $V$ in response to a ^|\vsplit| command (\xref \vsplit),
it sets the values of these commands as follows:
\ulist\compact
\li |\splitfirstmark| contains the tokens of the first mark in 
the item list of $V$.
\li |\splitbotmark| contains the tokens of the last mark in
the item list of $V$.
\endulist
These commands produce no tokens if there was no preceding |\vsplit|,
or if the most recent preceding |\vsplit| didn't contain any marks.
\eix^^{marks}
\enddesc

%==========================================================================
\section {Insertions}

\subsection {Footnotes}

\begindesc
\easy\cts footnote {\<argument$_1$> \<argument$_2$>}
\cts vfootnote {\<argument$_1$> \<argument$_2$>}
\explain
These commands produce footnotes.
\<argument$_1$> is the ``^{reference mark}''
for the footnote and \<argument$_2$> is its text.
The text can be several paragraphs long if necessary and can contain
constructs such as math displays, but it shouldn't contain any 
\minref{insertion}s (such as other footnotes).

You shouldn't use these commands inside a subformula of a math formula,
in a box within a box being contributed to a page,
or in an insertion of any kind. 
If you're unsure whether these restrictions apply, you can be safe by
only using |\footnote| and |\vfootnote| directly within a paragraph or
between paragraphs.

These restrictions aren't as severe as they seem because you can use
|\vfootnote| to footnote most anything.
Both |\foot!-note| and |\vfoot!-note| insert the reference mark in front of the
footnote itself, but |\vfoot!-note| doesn't insert the reference mark into the
text.
Thus, when you use |\vfoot!-note| you can
explicitly insert the reference mark
wherever it belongs without concern about the context
and place the |\vfootnote| in the next paragraph.
If you find that the footnote lands on
the page following the one where it belongs, move the |\vfootnote| back
to the previous paragraph.
There are rare circumstances where you'll need to
alter the text of your document in order to get a footnote to appear on
the same page as its reference mark.
\example
To quote the mathematician P\'olya is a ploy.\footnote
*{This is an example of an anagram, but not a strict one.}
|
\produces
To quote the mathematician P\'olya is a ploy.*
\par\line{\hskip .5in \vdots\hfil}
\nointerlineskip \bigskip
\footnoterule\par\parindent = 12pt
\textindent{*}This is
an example of an anagram, but not a strict one.
\endexample
\example
$$f(t)=\sigma\sigma t\;\raise 1ex \hbox{\dag}$$
\vfootnote \dag{The $\sigma\sigma$ notation was explained in
the previous section.}
|
\produces
$$f(t)=\sigma\sigma t\>\raise 1ex \hbox{\dag}$$
\par\line{\hskip .5in \vdots\hfil}
\nointerlineskip \bigskip
\footnoterule\par\parindent = 12pt
\textindent{\dag}{The $\sigma\sigma$ notation was explained in
the previous section.}
\endexample
\enddesc

%==========================================================================
\subsection {General insertions}

\begindesc
\bix^^{insertions//commands for}
\cts topinsert {\<vertical mode material> {\bt \\endinsert}}
\cts midinsert {\<vertical mode material> {\bt \\endinsert}}
\cts pageinsert {\<vertical mode material> {\bt \\endinsert}}
\explain
These commands produce different forms of insertions that
instruct
(or allow) \TeX\ to relocate the \<vertical mode material>:
\ulist
\li |\topinsert| attempts to put the material at the top of the current page.
If it won't fit there, |\topinsert|
will move the material to the next available top of page.
\li |\midinsert| attempts to put the material at the current position.
If it won't fit there, |\midinsert|
will move the material to the next available top of page.
\li |\pageinsert| puts the material by itself on the next page.
To avoid an underfull page, be sure to end the inserted material with
|\vfil| or fill out the excess space some other way.
% Knuth doesn't say this, but I tried an experiment that verified it.
% Nor does he say explicitly that an insertion does a \par.
\endulist
\noindent
The \<vertical mode material>
is said to be ``floating'' ^^{floating material} because \TeX\
can move it from one place to another.
Insertions are very useful for material such as figures and tables because
you can position such material where you want it without knowing where the
page breaks will fall.

Each of these commands implicitly ends the current paragraph, so 
you should use them only between paragraphs.
You should not use them within a box or within another insertion.  
If you have several insertions competing for
the same space, \TeX\ will retain their relative order.
\example
\pageinsert
% This text will appear on the following page, by itself.
This page is reserved for a picture of the Queen of Hearts
sharing a plate of oysters with the Walrus and
the Carpenter.
\endinsert
|
\endexample
\enddesc

\begindesc
\cts endinsert {}
\explain
This command ends an insertion started by
|\topinsert|, |\midinsert|, or |\pageinsert|.
\enddesc

\begindesc
\cts insert {\<number> \rqbraces{\<vertical mode material>}}
\explain
\minrefs{insertion}
This primitive command provides the 
underlying mechanism for constructing insertions, but
it is hardly ever used outside of a \minref{macro} definition.
The definitions of the
|\foot!-note|, |\vfoot!-note|,
|\top!-insert|, |\mid!-insert|, and |\page!-insert| commands are 
all built around |\insert|.
^^|\topinsert|
^^|\midinsert| ^^|\pageinsert| ^^|\footnote| ^^|\vfootnote|

When you design insertions for a document, you should assign a different
integer code\footnote
{\texbook{} uses the term ``class'' for a code.
We use a different term to avoid confusion with the other meaning of
``class'' (\xref{class}).}
$n$ to each kind of insertion,
using the ^|\newinsert| command (\xref{\@newinsert}) to obtain the
integer codes.
The |\insert| command itself appends the \<vertical mode material>
to the current horizontal or \minref{vertical list}.
Your \minref{output routine} is responsible for
moving the inserted material from where it resides in |\box|$\,n$
to an output page.
^^{output routine}

\TeX\ groups together all insertions having the same code
number.  Each insertion
code $n$ has four \minref{register}s associated with it:
\ulist
\li |\box|$\,n$ is where \TeX\ accumulates the material for insertions
with code $n$.  When \TeX\ breaks a page, it puts into |\box|$\,n$
as much insertion $n$ material as will fit on the page.
Your output routine should then move this material to the actual page.
You can use ^|\ifvoid| \ctsref{\@ifvoid}
to test if there is any material in |\box|$\,n$.
If not all the material fits, \TeX\ saves the leftovers for the next page.
\li |\count|$\,n$ is a magnification factor $f.$  When \TeX\ is computing
the vertical space occupied on the page
by insertion $n$ material, it multiplies the
vertical extent of this material by $f/1000$.
Thus you would ordinarily set $f$ to $500$ for a double-column insertion
and to $0$ for a marginal~note.
\li |\dimen|$\,n$ specifies the maximum amount
of insertion $n$ material that \TeX\ will put on a single page.
\li |\skip|$\,n$ specifies extra space that \TeX\ allocates on the page
if the page contains any insertion $n$ material.
This space is in addition to the space occupied by the insertion itself.
For example, it would account for the space on a page above the footnotes
(if there are~any).
\endulist
\noindent
\TeX\ sets |\box|$\,n$, and you should set the other three registers
so that \TeX\ can correctly compute the vertical space required by the
insertion.
See \knuth{pages~122--125} for further details of how \TeX\ processes this
command and of how insertions interact with page breaking.
\xrdef{endofinsert}
\enddesc

\see |\floatingpenalty| (\xref \floatingpenalty).
\eix^^{insertions//commands for}


%==========================================================================
\section{Modifying the output routine}

\bix^^{output routine}
\begindesc
\cts output {\param{token list}}
\explain
This parameter contains the current \minref{output routine}, i.e., 
the token list that \TeX\ expands when it finds a page break.
\TeX\ puts the page into ^|\box255|, so |\output| is responsible
for doing something with |\box255|---either shipping it out or
putting it somewhere else.
The output routine is also responsible for attaching things such as
headers and footers.
\enddesc

\begindesc
\cts plainoutput {}
\explain
This command invokes \plainTeX's output routine.
^^{output routine//default in \plainTeX}
\PlainTeX\ defines ^|\output| as
a token list containing the single token |\plainoutput|.
\enddesc

\begindesc
\cts shipout {\<box>}
\explain
This command instructs \TeX\ to send \<box> to the \dvifile.
^^{\dvifile//receives boxes from \b\tt\\shipout\e}
\TeX\ expands any |\write| command in \<box> as part of |\shipout|.
^^|\write//expanded during {\tt\\shipout}|
The principal use of |\shipout| is in the output routine, but you can
use it anywhere.
\enddesc

\begindesc
\cts deadcycles {\param{number}}
\explain
This parameter contains the number of times that \TeX\ has initiated
the \minref{output routine} since the last time it did a
^^|\shipout| |\ship!-out|.\footnote{
More precisely, \TeX\ sets |\dead!-cyles| to $0$ whenever it executes
|\ship!-out|
and increments it by $1$ whenever it executes |\output|.}
If |\deadcycles| gets too big, you've probably gotten
\TeX\ into a loop, e.g., one where the page builder is trying the same page
break over and over again.
\enddesc

\begindesc
\cts maxdeadcycles {\param{number}}
\explain
If the value of |\deadcycles| exceeds the value of |\maxdeadcycles|,
\TeX\ assumes that the output routine has gotten into a loop.
\TeX\ then complains and runs its own simple output routine,
equivalent to |\shipout!allowbreak\box255|, 
that is likely to break the loop.
\PlainTeX\ sets |\maxdeadcycles| \hbox{to $25$}.
\enddesc

\begindesc
\cts outputpenalty {\param{number}}
\explain
\TeX\ sets this parameter when it breaks a page.  If the breakpoint was at a
\minref{penalty} item, \TeX\ removes the penalty item and
sets |\outputpenalty| to the penalty value at
the breakpoint; otherwise it sets |\outputpenalty| \hbox{to $0$}.

Suppose that you are undoing a page break
in order to break the page at a different place than the one that \TeX\
has just chosen.  In order to reconstruct the page, you need to recreate
the penalty at \TeX's chosen breakpoint.
You can accomplish this with the command
|\penalty!allowbreak\outputpenalty|.
\enddesc

\begindesc
\cts holdinginserts {\param{number}}
\explain
If this parameter is greater than $0$ when \TeX\ 
is processing a page break, \TeX\ will refrain from processing insertions.
Setting this parameter to $1$
can be useful when you're writing an output routine
that needs to reprocess the contents of the page, e.g.,
an output routine that uses a value of |\vsize| (\xref \vsize) different from
the one used by the page builder.

\eix^^{output routine}
\enddesc

%==========================================================================
\section {Splitting vertical lists}

\begindesc
\cts vsplit {\<number> {\bt to} \<dimen>}
\explain
This command causes \TeX\ to split the \minref{box} numbered
\<number>, which we'll call $B_2$, into two parts.
It uses the same algorithm that it would use if $B_2$ was a page
and it was breaking that page;
the division point then corresponds to the page break that it would find.
The box $B_2$ must be a vbox, not an hbox.
% we avoid starting the previous sentence with a symbol, a copyediting no-no.
\TeX\ puts the material preceding the division point into
another box $B_1$ and leaves the material after the division point in $B_2$.
The |\vsplit| command then produces $B_1$.
Normally you'd assign $B_1$ to a different
box register, as in the example below.
If the division point is at the end of $B_2$,
$B_2$ will be empty after the |\vsplit|.

\TeX\ employs its usual page-breaking algorithm
^^{page breaks//in split lists}
for the split.
It uses \<dimen> for ^|\pagegoal|, the desired height of $B_1$.
The vertical extent of $B_1$ may not be exactly
\<dimen> because \TeX\ may not be able to achieve its page goal perfectly.
\TeX\ does not consider insertions in calculating the split,
so insertions in the original vertical list of $B_2$ will be retained
but won't affect the split point.

\example
\setbox 20 = \vsplit 30 to 7in
% Split off the first seven inches or so of material from
% box 30 and place that material in box 20.
|
\endexample
\enddesc

\begindesc
\cts splitmaxdepth {\param{dimen}}
\explain
This parameter specifies the 
maximum allowable depth of a box resulting from a |\vsplit|.
|\splitmaxdepth| plays the
same role that ^|\maxdepth| (\xref \maxdepth) plays for a page.
\enddesc

\begindesc
\cts splittopskip {\param{glue}}
\explain
This parameter specifies the glue that \TeX\ inserts at the top of 
a box resulting from a |\vsplit|.
|\splittopskip| plays the
same role that ^|\topskip| (\xref \topskip) plays for a page.
\enddesc

\see |\splitbotmark|, |\splitfirstmark| (\xref \splitfirstmark).

\enddescriptions \endchapter \byebye