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
|
% language=us runpath=texruns:manuals/luametatex
\environment luametatex-style
\startcomponent luametatex-building
\startchapter[reference=building,title={Building paragraphs and pages}]
\startsection[title={Introduction}]
\topicindex {building}
\topicindex {pages}
\topicindex {paragraphs}
\topicindex {marks}
\topicindex {inserts}
There are some enhancements that relate to the way paragraphs and pages are
built. In this chapter we will cover those. There can be a bit of overlap with
other chapters. These enhancements are still somewhat experimental.
\stopsection
\startsection[title={Paragraphs}]
{\em This section will describe \prm {autoparagraphmode}, \prm
{shapingpenaltiesmode}, \prm {shapingpenaltymode}, \prm {everybeforepar}, \prm
{snapshotpar}, \prm {wrapuppar}, \prm {orphanpenalties}, \prm {orphanpenalty},
enz. For the moment the manuals that come with \CONTEXT\ have to do.}
\stopsection
\startsection[title={Inserts}]
Inserts are tightly integrated into the page builder. Depending on penalties and
available space they end up on the same page as were they got injected or they
move to following pages, either or not split.
In traditional \TEX\ inserts are controlled by registers. A quadruple of box,
skip, dimen and count registers with the same number acts as an insert class.
Details can be found in the \TEX book. A side effect of this is that we only have
these four properties bound to class, other properties of inserts are driven by
shared parameters. Another side effect is that register management has to make
sure that these foursome get \quote {allocates} as set and not clashes with other
register allocations.
In \LUAMETATEX\ you can set the \prm {insertmode} to a non zero value in which case
inserts are not using the register pool but have their own (global) resources. For
now this is mode driven (for compatibility reasons) and once set or when an
insert has been accessed, this mode is frozen, so this parameter can be set
very early in the macro package loading process.
\starttabulate[|l|l|p|]
\DB primitive \BC traditional \BC explanation \NC \NR
\TB
\NC \prm {insertdistance} \NC skip \NC the space before the first instance (on a page) \NC \NR
\NC \prm {insertmultiplier} \NC count \NC a factor that is used to calculate the height used \NC \NR
\NC \prm {insertlimit} \NC dimen \NC the maximum amount of space on a page to be taken \NC \NR
\NC \prm {insertpenalty} \NC \prm {insertpenalties} \NC the floating penalty (used when set) \NC \NR
\NC \prm {insertmaxdepth} \NC \prm {maxdepth} \NC the maximum split depth (used when set) \NC \NR
\NC \prm {insertstorage} \NC \NC signals that the insert has to be stored for later \NC \NR
\NC \prm {insertheight} \NC \prm {ht} box \NC the accumulated height of the inserts so far \NC \NR
\NC \prm {insertdepth} \NC \prm {dp} box \NC the current depth of the inserts so far \NC \NR
\NC \prm {insertwidth} \NC \prm {wd} box \NC the width of the inserts \NC \NR
\LL
\stoptabulate
These primitives takes an insert class number. The \prm {insertpenalties}
primitives is unchanged, as is the \LUATEX\ \prm {insertheights} one. When \prm
{insertstoring} is set 1, all inserts that have their storage flag set will be
saved. Think of a multi column setup where inserts have to end up in the last
column. If there are three columns, the first two will store inserts. Then when
the last column is dealt with \prm {insertstoring} can be set to 2 and that will
signal the builder that we will inject the inserts. In both cases, the value of
this register will be set to zero so that it doesn't influence further
processing. You can use \prm {ifinsert} to check if am insert box is void. More
details about these (probably experimental for a while) features can be found in
documents that come with \CONTEXT.
A limitation of inserts is that when they are buried too deep, a property they
share with inserts, they become invisible This can be dealt with by the migration
feature described in an upcoming section.
The \LUAMETATEX\ engine has some tracing built in that is enabled by setting \prm
{tracinginserts} to a positive value.
\stopsection
\startsection[title={Marks}]
Marks are kind of signal nodes in the list that refer to stored token lists. When
a page has been split off and is handed over to the output routine these signals
are resolved into first, top and bottom mark references that can (for instance)
be used for running headers.
In \ETEX\ the standard \TEX\ primitives \prm {mark}, \prm {firstmark}, \prm
{topmark}, \prm {botmark}, \prm {splitfirstmark} and \prm {splitbotmark} have
been extended with plural forms that accent a number before the token list. That
number indicates a mark class.
A problem with marks is that one cannot really reset them. Mark states are kept
in the node lists and only periodically the state is snapshot into the global
state variables. The \LUATEX\ engine can reset these global states with \prm
{clearmarks} but that's only half a solution. In \LUAMETATEX\ we have \prm
{flushmarks} which, like \prm {marks}, puts a node in the list that does a reset.
This permits implementing controlled resets of specific marks at the cost of a
possible interfering mode, but that can normally be dealt with rather well.
Another problem with marks is that when they are buried too deep, a property they
share with inserts, they become invisible. This can be dealt with by the
migration feature described in the next section.
The \LUAMETATEX\ engine has some tracing built in that is enabled by setting \prm
{tracingmarks} to a positive value.
\stopsection
\startsection[title={Adjusts}]
The \prm {vadjust} primitive injects something in the vertical list after the
lien where it ends up. In \PDFTEX\ the \type {pre} keyword was added so that one
could force something before a previous line (actually this was something that we
needed in \CONTEXT\ \MKII). The \LUAMETATEX\ engine also supports the \type {post}
keyword.
We support a few more keywords: \type {before} will prepend the adjustment to the
already given one, and \type {after} will append it. The \type {index} keyword
expects an integer and relate that to the current adjustment. This index is
passed to an (optional) callback when the adjustment is finally moved to the
vertical list. That move is actually delayed because like inserts and marks these
(vertical) adjustments can migrate to the \quote {outer} vertical level.
The main reason for the index having no influence on the order is that this
primitive already could be used multiple times and order is determined by usage.
\footnote {Under consideration is to let the callback mess with the flushing
order.}
The \LUAMETATEX\ engine has some tracing built in that is enabled by setting \prm
{tracingadjusts} to a positive value. Currently there is not that much tracing
which is why the value has to be at least 2 in order to be compatible with other
(detailed) tracers.
\stopsection
\startsection[title={Migration}]
A new primitive \prm {automigrationmode} can be used to let deeply burried marks
and inserts bubble up to the outer level.
\starttabulate[|c|p|]
\DB value \BC explanation \NC \NR
\TB
\NC \the\markautomigrationcode \NC migrate marks in the par builder \NC \NR
\NC \the\insertautomigrationcode \NC migrate inserts in the par builder \NC \NR
\NC \the\adjustautomigrationcode \NC migrate adjusts in the par builder \NC \NR
\NC \the\preautomigrationcode \NC migrate prebox material in the page builder \NC \NR
\NC \the\postautomigrationcode \NC migrate postbox material in the page builder \NC \NR
\LL
\stoptabulate
If you want to migrate marks and inserts you need to set al these flags. Migrated
marks and inserts end up as post|-|box properties and will be handled in the page
builder as such. At the \LUA\ end you can add pre- and post|-|box material too.
\stopsection
\startsection[title={Pages}]
The page builder can triggered by (for instance) a penalty but you can also use
\prm {pageboundary}. This will trigger the page builder but not leave anything
behind.
\stopsection
\startsection[title={Local boxes}]
As far as I know the \OMEGA/\ALEPH\ local box mechanism is mostly in those
engines in order to support repetitive quotes. In \LUATEX\ this mechanism has
been made more robust and in \LUAMETATEX\ it became more tightly integrated in
the paragraph properties. In order for it to be a more generic useful feature it
got more features. For instance it is a bit painful to manage with respect to
grouping (which is a reason why it's not that much used). The most interesting
property is that the dimensions are taking into account when a paragraph is
broken into lines.
There are three commands: \prm {localleftbox}, \prm {localrightbox} and the
\LUAMETATEX\ specific \prm {localmiddlebox} which is basically a right box but
when we pass these boxes to a callback they can be distinguished (we could have
used the index but this was a cheap extra signal so we keep it).
These commands take optional keywords. The \type {index} keyword has to be
followed by an integer. This index determines the order which doesn't introduce a
significant compatibility issue: local boxes are hardly used and originally have
only one instance.
The \type {par} keyword forces the box to be added to the current paragraph head.
This permits setting them when a paragraph has already started. The
implementation of these boxes is done via so called (local) paragraph nodes and
there is one at the start of each paragraph.
The \type {local} keyword tells this mechanism not to update the registers that
keep these boxes. In that case a next paragraph will start fresh. The \type
{keep} option will do the opposite and retain the box after a group ends.
There commands: \prm {localleftboxbox}, \prm {localrightboxbox} and \prm
{localmiddleboxbox} return a copy of the current related register content.
\stopsection
\stopchapter
\stopcomponent
|
