1
2
3\environment lowlevelstyle
4
5\startdocument
6 [title=inserts,
7 color=middlecyan]
8
9\startsectionlevel[title=Introduction]
10
11This document is a mixed bag. We do discuss inserts but also touch elements of
12the page builder because inserts and regular page content are handled there.
13Examples of mechanisms that use inserts are footnotes. These have an anchor in
14the running text and some content that ends up (normally) at the bottom of the
15page. When considering a page break the engine tries to make sure that the anchor
16(reference) and the content end up on the same page. When there is too much, it
17will distribute (split) the content over pages.
18
19We can discuss page breaks in a (pseudo) scientific way and explore how to
20optimize this process, taking into accounts also inserts that contain images but
21it doesnt make much sense to do that because in practice we can encounter all
22kind of interferences. Theory and practice are too different because a document
23can contain a wild mix of text, figures, formulas, notes, have backgrounds and
24location dependent processing. It get seven more complex when we are dealing with
25columns because \TEX\ doesnt really know that concept.
26
27I will therefore stick to some practical aspects and the main reason for this
28document is that I sort of document engine features and at the same time give an
29impression of what we deal with. I will do that in the perspective of
30\LUAMETATEX, which has a few more options and tracing than other engines.
31
32{\em Currently this document is mostly for myself to keep track of the state of
33inserts and the page builder in \LUAMETATEX\ and \CONTEXT\ \LMTX. The text is not
34yet corrected and can have errors.}
35
36\stopsectionlevel
37
38\startsectionlevel[title=The page builder]
39
40When your document is processed content eventually gets added to the so called
41main vertical list (mvl). Content first get appended to the list of contributions
42and at specific moments it will be handed over to the mvl. This process is called
43page building. There we can encounter the following elements (nodes):
44
45\starttabulate
46\NC \type {glue} \NC a vertical skip \NC \NR
47\NC \type {penalty} \NC a vertical penalty \NC \NR
48\NC \type {kern} \NC a vertical kern \NC \NR
49\NC \type {vlist} \NC a a vertical box \NC \NR
50\NC \type {hlist} \NC a horizontal box (often a line) \NC \NR
51\NC \type {rule} \NC a horizontal rule \NC \NR
52\NC \type {boundary} \NC a boundary node \NC \NR
53\NC \type {whatsit} \NC a node that is used by user code (often some extension) \NC \NR
54\NC \type {mark} \NC a token list (as used for running headers) \NC \NR
55\NC \type {insert} \NC a node list (as used for notes) \NC \NR
56\stoptabulate
57
58The engine itself will not insert anything other than this but \LUA\ code can
59mess up the contribution list and the mvl and that can trigger an error. Handing
60over the contributions is done by the page builder and that one kicks in in
61several places:
62
63\startitemize[packed]
64\startitem
65 When a penalty gets inserted it is part of evaluating if the output routine
66 should be triggered. This triggering can be enforced by values equal or below
67 10.000 that then can be checked in the set routine.
68\stopitem
69\startitem
70 The builder is {\em not} exercised when a glue or kern is injected so there can
71 be multiple of them before another element triggers the builder.
72\stopitem
73\startitem
74 Adding a box triggers the builder as does the result of an alignment which can
75 be a list of boxes.
76\stopitem
77\startitem
78 When the output routine is finished the builder is executed because the
79 routine can have pushed back content.
80\stopitem
81\startitem
82 When a new paragraph is triggered by the \type {\par} command the builder kicks in
83 but only when the engine was able to enter vertical mode.
84\stopitem
85\startitem
86 When the job is finished the builder will make sure that pending content is handled.
87\stopitem
88\startitem
89 An insert and vadjust {\em can} trigger the builder but only at the nesting level zero
90 which normally is not the case (I need an example).
91\stopitem
92\startitem
93 At the beginning of a paragraph (like text), before display math is entered,
94 and when display math ends the builder is also activated.
95\stopitem
96\stopitemize
97
98At the \TEX\ the builder is triggered automatically in the mentioned cases but at
99the \LUA\ end you can use \type {tex.triggerbuildpage()} to flush the pending
100contributions.
101
102The properties that relate to the page look like counter and dimension registers
103but they are not. These variables are global and managed differently.
104
105\starttabulate
106\NC \type {\pagegoal} \NC the available space \NC \NR
107\NC \type {\pagetotal} \NC the accumulated space \NC \NR
108\NC \type {\pagestretch} \NC the possible zero order stretch \NC \NR
109\NC \type {\pagefilstretch} \NC the possible one order stretch \NC \NR
110\NC \type {\pagefillstretch} \NC the possible second order stretch \NC \NR
111\NC \type {\pagefilllstretch} \NC the possible third order stretch \NC \NR
112\NC \type {\pageshrink} \NC the possible shrink \NC \NR
113\NC \type {\pagedepth} \NC the current page depth \NC \NR
114\NC \type {\pagevsize} \NC the initial page goal \NC \NR
115\stoptabulate
116
117When the first content is added to an empty page the \type {\pagegoal} gets the
118value of \type {\vsize} and gets frozen but the value is diminished by the space
119needed by left over inserts. These inserts are managed via a separate list so
120they dont interfere with the page that itself of course can have additional
121inserts. The \type {\pagevsize} is just a (\LUAMETATEX) status variable that hold
122the initial \type {\pagegoal} but it might play a role in future extensions.
123
124Another variable is \type {\deadcycles} that registers the number of times the
125output routine is called without returning result.
126
127\stopsectionlevel
128
129\startsectionlevel[title=Inserts]
130
131We now come to inserts. In traditional \TEX\ an insert is a data structure that
132runs on top of registers: a box, count, dimension and skip. An insert is accessed
133by a number so for instance insert 123 will use the four registers of that
134number. Because \TEX\ only offers a command alias mechanism for registers (like
135\type {\countdef}) a macro package will implement some allocator management
136subsystem (like \type {\newcount}). A \type {\newinsert} has to be defined in a
137way that the four registers are not clashing with other allocators. When you
138start with \TEX\ seeing code that deals with in (in plain \TEX) can be puzzling
139but it follows from the way \TEX\ is set up. But inserts are probably not what
140you start exploring right away away.
141
142In \LUAMETATEX\ you can set \type {\insertmode} to 1 and that is what we do in
143\CONTEXT. In that mode inserts are taken from a pool instead of registers. A side
144effect is that like the page properties the insert properties are global too but
145that is normally no problem and can be managed well by a macro package (that
146probably would assign register the values globally too). The insert pool will
147grow dynamically on demand so one can just start at 1; in \CONTEXT\ \MKIV\ we use
148the range 127 upto 255 in order to avoid a clash with registers. In \LMTX\ we start
149at 1 because there are no clashes.
150
151A consequence of this approach is that we use dedicated commands to set the insert
152properties:
153
154\starttabulate[llp]
155\NC \type {\insertdistance} \NC glue \NC the space before the first instance (on a page) \NC \NR
156\NC \type {\insertmultiplier} \NC count \NC a factor that is used to calculate the height used \NC \NR
157\NC \type {\insertlimit} \NC dimen \NC the maximum amount of space on a page to be taken \NC \NR
158\NC \type {\insertpenalty} \NC count \NC the floating penalty (used when set) \NC \NR
159\NC \type {\insertmaxdepth} \NC dimen \NC the maximum split depth (used when set) \NC \NR
160\NC \type {\insertstorage} \NC count \NC signals that the insert has to be stored for later \NC \NR
161\NC \type {\insertheight} \NC dimen \NC the accumulated height of the inserts so far \NC \NR
162\NC \type {\insertdepth} \NC dimen \NC the current depth of the inserts so far \NC \NR
163\NC \type {\insertwidth} \NC dimen \NC the width of the inserts \NC \NR
164\stoptabulate
165
166These commands take a number and an integer, dimension or glue specification.
167They can be set and queried but setting the dimensions can have side effects. The
168accumulated height of the inserts is available in \type {\insertheights} (which
169can be set too). The \type {\floatingpenalty} variable determines the penalty
170applied when a split is needed.
171
172In the output routine the original \TEX\ variable \type {\insertpenalties} is a
173counter that keeps the number of insertions that didnt fit on the page while
174otherwise if has the accumulated penalties of the split insertions. When \type
175{\holdinginserts} is non zero the inserts in the list are not collected for
176output, which permits the list to be fed back for reprocessing.
177
178The \LUAMETATEX\ specific storage mode \type {\insertstoring} variable is
179explained in the next section.
180
181\stopsectionlevel
182
183\startsectionlevel[title=Storing]
184
185This feature is kind of special and still experimental. When \type
186{\insertstoring} is set 1, all inserts that have their storage flag set will be
187saved. Think of a multi column setup where inserts have to end up in the last
188column. If there are three columns, the first two will store inserts. Then when
189the last column is dealt with \type {\insertstoring} can be set to 2 and that
190will signal the builder that we will inject the inserts. In both cases, the value
191of this register will be set to zero so that it doesnt influence further
192processing.
193
194\stopsectionlevel
195
196\startsectionlevel[title=Synchronizing]
197
198The page builder can triggered by (for instance) a penalty but you can also use
199\type {\pageboundary}. This will trigger the page builder but not leave anything
200behind. (This is experimental.)
201
202\stopsectionlevel
203
204\startsectionlevel[title=Migration]
205
206{\em Todo, nothing new there, so no hurry.}
207
208\stopsectionlevel
209
210\startsectionlevel[title=Callbacks]
211
212{\em Todo, nothing new there, so no hurry.}
213
214\stopsectionlevel
215
216\stopdocument
217 |