Source Browser ?

1% language=us runpath=texruns:manuals/evenmore
2
3\environment evenmore-style
4
5\startcomponent evenmore-inserts
6
7\startchapter[title=Inserts]
8
9{\em As in other chapters, this is mostly a wrapup of some developments and nota
10manual. What is described here might actually evolve. Normally \CONTEXT\ users
11will not notice these details, but it might help them to get an idea of what
12complications we're dealing with.}
13
14\startsection[title=Notes]
15
16Quite some \TEX\ users love footnotes. These typographical elements have two
17properties:
18
19\startitemize[n]
20\startitem
21    A blob of text, often placed at the bottom of a page or at the end of a
22    section, chapter or document. A note can be a short one|-|liner but also
23    a paragraph of text.
24\stopitem
25\startitem
26    A symbol in the running text that serves as reference to that blob. It can be
27    a number of just some unique symbol.
28\stopitem
29\stopitemize
30
31When such a note is placed at the bottom of a page, the page builder needs to
32take its dimensions into account when calculating an optimal page break. It might
33even have to split a note over pages. Preferably the reference and note are on
34the same page. In order to achieve this there is a special mechanism that deals
35with this: inserts. In this chapter we only discuss them in the perspective of
36notes but they can also be used for, for instance, top or bottom figures, tables,
37etc.
38
39\stopsection
40
41\startsection[title=Global and local]
42
43Normally notes are placed in the text flow. We call these global inserts. When
44they are attached to a specific typographical element we tend to call them local
45and there is a good reason for that. For instance, when used in a table, one
46might want to keep them with that table when it is moved to a place where it
47fits. When notes are packaged {\em with} the table they are flushed on demand and
48not handled by the page builder. Actually they don't use inserts then. One
49problem with global notes is that the \TEX\ engine has some limitations with
50respect to inserts. In traditional \TEX, the following example will only result
51in note \quote {a} being placed. The other two are buried too deeply.
52
53\startbuffer[insert]
54test \footnote {a} \hbox {test \footnote{b} \hbox {test \footnote {c}} test} test
55\stopbuffer
56
57\typebuffer[insert]
58
59There are a few places where \TEX\ will bubble up the notes: when it constructs
60lines during a breaking a paragraph into lines, and when constructing alignment
61cells. In all other cases they are simply discarded.
62
63In \CONTEXT\ \MKII\ there is a mechanism that can postpone such notes. Normally a
64user will not use boxes directly so when some mechanism is used that does box
65its content, \CONTEXT\ can collect the notes and flush them in a spot that
66exposes them. This works reasonable well be it that we loose some of the
67synchronization with the page builder: flushing can happen after a page break.
68
69Already early in the \CONTEXT\ \MKIV\ development a more advanced mechanism was
70introduced, using \LUA\ callbacks: auto migration. There (optionally) inserts are
71bubbled up to a level where they are visible but even that has its limitations. Users
72explicitly need to enable automigration in \MKIV.
73
74In \CONTEXT\ \LMTX\ we do it a bit different because the \LUAMETATEX\ engine has
75a feature that helps. More about that next.
76
77\stopsection
78
79\startsection[title=Pre and post migration]
80
81There is another mechanism that moves material from the spot: adjusts. Here is an
82example (watch the interline spacing):
83
84\startbuffer[adjust]
85\strut test \vadjust pre {\red \strut before} test \vadjust {\red \strut after}
86\stopbuffer
87
88\typebuffer[adjust]
89
90This gives:
91
92\blank {\bf\showstruts \getbuffer[adjust]} \blank
93
94The \type {pre} variant was introduced in \PDFTEX\ at a time that I actually has
95use for it (think of marginal notes) but in \MKIV\ we don't use this adjust
96mechanism.
97
98Inserts on the other hand always end up \quote {post} where they are injected.
99Some day I might think about what good there is in injecting them \quote {pre}
100where they are injected. It might become an option.
101
102\blank {\bf \showboxes \getbuffer[insert]} \blank
103
104In this already shown example the footnotes (that are implemented using inserts)
105result indeed in text showing up at the bottom of the page, even when they are
106wrapped in boxes. The reason is that we have enabled a mechanism that
107automatically bubble them up:
108
109\starttyping
110\automigrationmode = 3 % \numexpr 1 + 2 \relax
111\stoptyping
112
113Here bit~1 controls migration in lists and bit~2 controls migration in the main
114vertical list (the page flow). In \CONTEXT\ \LMTX\ we enable both.
115
116\startbuffer
117h: \setbox0\hbox{box    \footnote{h:     box}}\setbox2\hbox{\box    0}\box2\quad
118h: \setbox0\hbox{copy   \footnote{h:    copy}}\setbox2\hbox{\copy   0}\box2\quad
119h: \setbox0\hbox{unbox  \footnote{h:  unhbox}}\setbox2\hbox{\unhbox 0}\box2\quad
120h: \setbox0\hbox{uncopy \footnote{h: unhcopy}}\setbox2\hbox{\unhcopy0}\box2\quad
121v: \setbox0\hbox{box    \footnote{v:     box}}\setbox2\vbox{\box    0}\box2\quad
122v: \setbox0\hbox{copy   \footnote{v:    copy}}\setbox2\vbox{\copy   0}\box2\quad
123v: \setbox0\hbox{unbox  \footnote{v:  unhbox}}\setbox2\vbox{\unhbox 0}\box2\quad
124v: \setbox0\hbox{uncopy \footnote{v: unhcopy}}\setbox2\vbox{\unhcopy0}\box2\quad
125\stopbuffer
126
127\typebuffer
128
129This is a kind of torture test:
130
131\blank \hbox{\bf \getbuffer} \blank
132
133It might look kind of trivial to accomplish this but it actually took some
134experimenting to get it right. It also must be noted that because in \LUATEX\ and
135even more in \LUAMETATEX\ the nodes that store a box are much larger than in
136traditional \TEX\ and that the price for adding some additional overhead for
137dealing with pre- and post material had not that much impact on the performance
138of \LUAMETATEX.
139
140On the one hand we need to make sure that the inserts are kept with the box but
141on the other hand they should really migrate when the boxed material gets boxed
142itself. This has to be combined with unboxing and copying. It has to work in
143regular boxes but also in the main vertical list (the page flow).
144
145\stopsection
146
147\startsection[title=Playground]
148
149You can play a bit with this mechanism by getting and setting the pre and post
150material than relates to a box.
151
152\startbuffer
153\setbox0\ruledhbox{\strut content \footnote {footnote}}
154
155[flush  pre\prelistbox    0] % \prelistcopy  0
156[flush post\postlistbox   0] % \postlistcopy 0
157[set    pre\setprelistbox 0\ruledhbox{\strut before}]
158[set   post\setpostlistbox0\ruledhbox{\strut  after}]
159
160\blank \box0 \blank
161\stopbuffer
162
163\typebuffer
164
165\getbuffer
166
167Of course there can be side effects but so far this mechanism works reasonable
168well, given what it has to deal with.
169
170\stopsection
171
172\startsection[title=Marks]
173
174The low level marks mechanism can use the same pre and post mechanisms but I
175didn't test that yet. We have a different approach to marks but eventually might
176revert to using the build in mechanism, be it in adapted form.
177
178\stopsection
179
180% \startsection[title=Maybe]
181%
182% Inserts are implemented in a bit special way. A class of inserts needs a box,
183% dimen, count and skip register. So, the macro package has to allocate these
184% en|-|block. This puts some constraints on the register allocation macros. On the
185% agenda is to investigate if a dedicated compound register makes sense. However,
186% this means that the interfaces change, but because a \CONTEXT\ user doesn't use
187% the low level inserts directly this is not really a problem. Adapting the
188% implementation can have the side effect of using a different insert chaining
189% which can give a better interface to \LUA\ because the current interface is not
190% really useable.
191%
192% \stopsection
193
194\stopchapter
195
196\stopcomponent
197
198
199