Debian Codegraph @

texmf-dist/doc/luatex/base/luatex-enhancements.tex

raw
1 % language=uk
2
3 \environment luatex-style
4
5 \startcomponent luatex-enhancements
6
7 \startchapter[reference=enhancements,title={Basic \TEX\ enhancements}]
8
9 \startsection[title={Introduction}]
10
11 \startsubsection[title={Primitive behaviour}]
12
13 From day one, \LUATEX\ has offered extra features compared to the superset of
14 \PDFTEX, which includes \ETEX, and \ALEPH. This has not been limited to the
15 possibility to execute \LUA\ code via \prm {directlua}, but \LUATEX\ also adds
16 functionality via new \TEX|-|side primitives or extensions to existing ones.
17
18 When \LUATEX\ starts up in \quote {iniluatex} mode (\type {luatex -ini}), it
19 defines only the primitive commands known by \TEX82 and the one extra command
20 \prm {directlua}. As is fitting, a \LUA\ function has to be called to add the
21 extra primitives to the user environment. The simplest method to get access to
22 all of the new primitive commands is by adding this line to the format generation
23 file:
24
25 \starttyping
26 \directlua { tex.enableprimitives('',tex.extraprimitives()) }
27 \stoptyping
28
29 But be aware that the curly braces may not have the proper \prm {catcode}
30 assigned to them at this early time (giving a \quote {Missing number} error), so
31 it may be needed to put these assignments before the above line:
32
33 \starttyping
34 \catcode `\{=1
35 \catcode `\}=2
36 \stoptyping
37
38 More fine|-|grained primitives control is possible and you can look up the
39 details in \in {section} [luaprimitives]. For simplicity's sake, this manual
40 assumes that you have executed the \prm {directlua} command as given above.
41
42 The startup behaviour documented above is considered stable in the sense that
43 there will not be backward|-|incompatible changes any more. We have promoted some
44 rather generic \PDFTEX\ primitives to core \LUATEX\ ones, and the few that we
45 inherited from \ALEPH\ (\OMEGA) are also promoted. Effectively this means that we
46 now only have the \type {tex}, \type {etex} and \type {luatex} sets left.
47
48 In \in {Chapter} [modifications] we discuss several primitives that are derived
49 from \PDFTEX\ and \ALEPH\ (\OMEGA). Here we stick to real new ones. In the
50 chapters on fonts and math we discuss a few more new ones.
51
52 \stopsubsection
53
54 \startsubsection[title={Version information}]
55
56 \startsubsubsection[title={\lpr {luatexbanner}, \lpr {luatexversion} and \lpr {luatexrevision}}]
57
58 \topicindex{version}
59 \topicindex{banner}
60
61 There are three new primitives to test the version of \LUATEX:
62
63 \unexpanded\def\VersionHack#1% otherwise different luatex and luajittex runs
64 {\ctxlua{%
65 local banner = "\luatexbanner"
66 local banner = string.match(banner,"(.+)\letterpercent(") or banner
67 context(string.gsub(banner ,"jit",""))%
68 }}
69
70 \starttabulate[|l|l|pl|]
71 \DB primitive \BC value
72 \BC explanation \NC \NR
73 \TB
74 \NC \lpr {luatexbanner} \NC \VersionHack{\luatexbanner}
75 \NC the banner reported on the command line \NC \NR
76 \NC \lpr {luatexversion} \NC \the\luatexversion
77 \NC a combination of major and minor number \NC \NR
78 \NC \lpr {luatexrevision} \NC \luatexrevision
79 \NC the revision number, the current value is \NC \NR
80 \LL
81 \stoptabulate
82
83 The official \LUATEX\ version is defined as follows:
84
85 \startitemize
86 \startitem
87 The major version is the integer result of \lpr {luatexversion} divided by
88 100. The primitive is an \quote {internal variable}, so you may need to prefix
89 its use with \prm {the} depending on the context.
90 \stopitem
91 \startitem
92 The minor version is the two|-|digit result of \lpr {luatexversion} modulo 100.
93 \stopitem
94 \startitem
95 The revision is reported by \lpr {luatexrevision}. This primitive expands to
96 a positive integer.
97 \stopitem
98 \startitem
99 The full version number consists of the major version, minor version and
100 revision, separated by dots.
101 \stopitem
102 \stopitemize
103
104 \stopsubsubsection
105
106 \startsubsubsection[title={\lpr {formatname}}]
107
108 \topicindex{format}
109
110 The \lpr {formatname} syntax is identical to \prm {jobname}. In \INITEX, the
111 expansion is empty. Otherwise, the expansion is the value that \prm {jobname} had
112 during the \INITEX\ run that dumped the currently loaded format. You can use this
113 token list to provide your own version info.
114
115 \stopsubsubsection
116
117 \stopsubsection
118
119 \stopsection
120
121 \startsection[title={\UNICODE\ text support}]
122
123 \startsubsection[title={Extended ranges}]
124
125 \topicindex{\UNICODE}
126
127 Text input and output is now considered to be \UNICODE\ text, so input characters
128 can use the full range of \UNICODE\ ($2^{20}+2^{16}-1 = \hbox{0x10FFFF}$). Later
129 chapters will talk of characters and glyphs. Although these are not
130 interchangeable, they are closely related. During typesetting, a character is
131 always converted to a suitable graphic representation of that character in a
132 specific font. However, while processing a list of to|-|be|-|typeset nodes, its
133 contents may still be seen as a character. Inside \LUATEX\ there is no clear
134 separation between the two concepts. Because the subtype of a glyph node can be
135 changed in \LUA\ it is up to the user. Subtypes larger than 255 indicate that
136 font processing has happened.
137
138 A few primitives are affected by this, all in a similar fashion: each of them has
139 to accommodate for a larger range of acceptable numbers. For instance, \prm
140 {char} now accepts values between~0 and $1{,}114{,}111$. This should not be a
141 problem for well|-|behaved input files, but it could create incompatibilities for
142 input that would have generated an error when processed by older \TEX|-|based
143 engines. The affected commands with an altered initial (left of the equal sign)
144 or secondary (right of the equal sign) value are: \prm {char}, \prm {lccode},
145 \prm {uccode}, \lpr {hjcode}, \prm {catcode}, \prm {sfcode}, \lpr {efcode}, \lpr
146 {lpcode}, \lpr {rpcode}, \prm {chardef}.
147
148 As far as the core engine is concerned, all input and output to text files is
149 \UTF-8 encoded. Input files can be pre|-|processed using the \type {reader}
150 callback. This will be explained in \in {section} [iocallback]. Normalization of
151 the \UNICODE\ input is on purpose not built|-|in and can be handled by a macro
152 package during callback processing. We have made some practical choices and the
153 user has to live with those.
154
155 Output in byte|-|sized chunks can be achieved by using characters just outside of
156 the valid \UNICODE\ range, starting at the value $1{,}114{,}112$ (0x110000). When
157 the time comes to print a character $c>=1{,}114{,}112$, \LUATEX\ will actually
158 print the single byte corresponding to $c$ minus 1{,}114{,}112.
159
160 Output to the terminal uses \type {^^} notation for the lower control range
161 ($c<32$), with the exception of \type {^^I}, \type {^^J} and \type {^^M}. These
162 are considered \quote {safe} and therefore printed as|-|is. You can disable
163 escaping with \type {texio.setescape(false)} in which case you get the normal
164 characters on the console.
165
166 \stopsubsection
167
168 \startsubsection[title={\lpr {Uchar}}]
169
170 \topicindex{\UNICODE}
171
172 The expandable command \lpr {Uchar} reads a number between~0 and $1{,}114{,}111$
173 and expands to the associated \UNICODE\ character.
174
175 \stopsubsection
176
177 \startsubsection[title={Extended tables}]
178
179 All traditional \TEX\ and \ETEX\ registers can be 16-bit numbers. The affected
180 commands are:
181
182 \startfourcolumns
183 \startlines
184 \prm {count}
185 \prm {dimen}
186 \prm {skip}
187 \prm {muskip}
188 \prm {marks}
189 \prm {toks}
190 \prm {countdef}
191 \prm {dimendef}
192 \prm {skipdef}
193 \prm {muskipdef}
194 \prm {toksdef}
195 \prm {insert}
196 \prm {box}
197 \prm {unhbox}
198 \prm {unvbox}
199 \prm {copy}
200 \prm {unhcopy}
201 \prm {unvcopy}
202 \prm {wd}
203 \prm {ht}
204 \prm {dp}
205 \prm {setbox}
206 \prm {vsplit}
207 \stoplines
208 \stopfourcolumns
209
210 Because font memory management has been rewritten, character properties in fonts
211 are no longer shared among font instances that originate from the same metric
212 file. Of course we share fonts in the backend when possible so that the resulting
213 \PDF\ file is as efficient as possible, but for instance also expansion and
214 protrusion no longer use copies as in \PDFTEX.
215
216 \stopsubsection
217
218 \stopsection
219
220 \startsection[title={Attributes}]
221
222 \startsubsection[title={Nodes}]
223
224 \topicindex {nodes}
225
226 When \TEX\ reads input it will interpret the stream according to the properties
227 of the characters. Some signal a macro name and trigger expansion, others open
228 and close groups, trigger math mode, etc. What's left over becomes the typeset
229 text. Internally we get linked list of nodes. Characters become \nod {glyph}
230 nodes that have for instance a \type {font} and \type {char} property and \typ
231 {\kern 10pt} becomes a \nod {kern} node with a \type {width} property. Spaces are
232 alien to \TEX\ as they are turned into \nod {glue} nodes. So, a simple paragraph
233 is mostly a mix of sequences of \nod {glyph} nodes (words) and \nod {glue} nodes
234 (spaces).
235
236 The sequences of characters at some point are extended with \nod {disc} nodes
237 that relate to hyphenation. After that font logic can be applied and we get a
238 list where some characters can be replaced, for instance multiple characters can
239 become one ligature, and font kerns can be injected. This is driven by the
240 font properties.
241
242 Boxes (like \prm {hbox} and \prm {vbox}) become \nod {hlist} or \nod {vlist}
243 nodes with \type {width}, \type {height}, \type {depth} and \type {shift}
244 properties and a pointer \type {list} to its actual content. Boxes can be
245 constructed explicitly or can be the result of subprocesses. For instance, when
246 lines are broken into paragraphs, the lines are a linked list of \nod {hlist}
247 nodes.
248
249 So, to summarize: all that you enter as content eventually becomes a node, often
250 as part of a (nested) list structure. They have a relative small memory footprint
251 and carry only the minimal amount of information needed. In traditional \TEX\ a
252 character node only held the font and slot number, in \LUATEX\ we also store some
253 language related information, the expansion factor, etc. Now that we have access
254 to these nodes from \LUA\ it makes sense to be able to carry more information
255 with an node and this is where attributes kick in.
256
257 \stopsubsection
258
259 \startsubsection[title={Attribute registers}]
260
261 \topicindex {attributes}
262
263 Attributes are a completely new concept in \LUATEX. Syntactically, they behave a
264 lot like counters: attributes obey \TEX's nesting stack and can be used after
265 \prm {the} etc.\ just like the normal \prm {count} registers.
266
267 \startsyntax
268 \attribute <16-bit number> <optional equals> <32-bit number>!crlf
269 \attributedef <csname> <optional equals> <16-bit number>
270 \stopsyntax
271
272 Conceptually, an attribute is either \quote {set} or \quote {unset}. Unset
273 attributes have a special negative value to indicate that they are unset, that
274 value is the lowest legal value: \type {-"7FFFFFFF} in hexadecimal, a.k.a.
275 $-2147483647$ in decimal. It follows that the value \type {-"7FFFFFFF} cannot be
276 used as a legal attribute value, but you {\it can\/} assign \type {-"7FFFFFFF} to
277 \quote {unset} an attribute. All attributes start out in this \quote {unset}
278 state in \INITEX.
279
280 Attributes can be used as extra counter values, but their usefulness comes mostly
281 from the fact that the numbers and values of all \quote {set} attributes are
282 attached to all nodes created in their scope. These can then be queried from any
283 \LUA\ code that deals with node processing. Further information about how to use
284 attributes for node list processing from \LUA\ is given in~\in {chapter}[nodes].
285
286 Attributes are stored in a sorted (sparse) linked list that are shared when
287 possible. This permits efficient testing and updating. You can define many
288 thousands of attributes but normally such a large number makes no sense and is
289 also not that efficient because each node carries a (possibly shared) link to a
290 list of currently set attributes. But they are a convenient extension and one of
291 the first extensions we implemented in \LUATEX.
292
293 \stopsubsection
294
295 \startsubsection[title={Box attributes}]
296
297 \topicindex {attributes}
298 \topicindex {boxes}
299
300 Nodes typically receive the list of attributes that is in effect when they are
301 created. This moment can be quite asynchronous. For example: in paragraph
302 building, the individual line boxes are created after the \prm {par} command has
303 been processed, so they will receive the list of attributes that is in effect
304 then, not the attributes that were in effect in, say, the first or third line of
305 the paragraph.
306
307 Similar situations happen in \LUATEX\ regularly. A few of the more obvious
308 problematic cases are dealt with: the attributes for nodes that are created
309 during hyphenation, kerning and ligaturing borrow their attributes from their
310 surrounding glyphs, and it is possible to influence box attributes directly.
311
312 When you assemble a box in a register, the attributes of the nodes contained in
313 the box are unchanged when such a box is placed, unboxed, or copied. In this
314 respect attributes act the same as characters that have been converted to
315 references to glyphs in fonts. For instance, when you use attributes to implement
316 color support, each node carries information about its eventual color. In that
317 case, unless you implement mechanisms that deal with it, applying a color to
318 already boxed material will have no effect. Keep in mind that this
319 incompatibility is mostly due to the fact that separate specials and literals are
320 a more unnatural approach to colors than attributes.
321
322 It is possible to fine-tune the list of attributes that are applied to a \type
323 {hbox}, \type {vbox} or \type {vtop} by the use of the keyword \type {attr}. The
324 \type {attr} keyword(s) should come before a \type {to} or \type {spread}, if
325 that is also specified. An example is:
326
327 \startbuffer[tex]
328 \attribute997=123
329 \attribute998=456
330 \setbox0=\hbox {Hello}
331 \setbox2=\hbox attr 999 = 789 attr 998 = -"7FFFFFFF{Hello}
332 \stopbuffer
333
334 \startbuffer[lua]
335 for b=0,2,2 do
336 for a=997, 999 do
337 tex.sprint("box ", b, " : attr ",a," : ",tostring(tex.box[b] [a]))
338 tex.sprint("\\quad\\quad")
339 tex.sprint("list ",b, " : attr ",a," : ",tostring(tex.box[b].list[a]))
340 tex.sprint("\\par")
341 end
342 end
343 \stopbuffer
344
345 \typebuffer[tex]
346
347 Box 0 now has attributes 997 and 998 set while box 2 has attributes 997 and 999
348 set while the nodes inside that box will all have attributes 997 and 998 set.
349 Assigning the maximum negative value causes an attribute to be ignored.
350
351 To give you an idea of what this means at the \LUA\ end, take the following
352 code:
353
354 \typebuffer[lua]
355
356 Later we will see that you can access properties of a node. The boxes here are so
357 called \nod {hlist} nodes that have a field \type {list} that points to the
358 content. Because the attributes are a list themselves you can access them by
359 indexing the node (here we do that with \type {[a]}. Running this snippet gives:
360
361 \start
362 \getbuffer[tex]
363 \startpacked \tt
364 \ctxluabuffer[lua]
365 \stoppacked
366 \stop
367
368 Because some values are not set we need to apply the \type {tostring} function
369 here so that we get the word \type {nil}.
370
371 \stopsubsection
372
373 \stopsection
374
375 \startsection[title={\LUA\ related primitives}]
376
377 \startsubsection[title={\prm {directlua}}]
378
379 In order to merge \LUA\ code with \TEX\ input, a few new primitives are needed.
380 The primitive \prm {directlua} is used to execute \LUA\ code immediately. The
381 syntax is
382
383 \startsyntax
384 \directlua <general text>!crlf
385 \directlua <16-bit number> <general text>
386 \stopsyntax
387
388 The \syntax {<general text>} is expanded fully, and then fed into the \LUA\
389 interpreter. After reading and expansion has been applied to the \syntax
390 {<general text>}, the resulting token list is converted to a string as if it was
391 displayed using \type {\the\toks}. On the \LUA\ side, each \prm {directlua} block
392 is treated as a separate chunk. In such a chunk you can use the \type {local}
393 directive to keep your variables from interfering with those used by the macro
394 package.
395
396 The conversion to and from a token list means that you normally can not use \LUA\
397 line comments (starting with \type {--}) within the argument. As there typically
398 will be only one \quote {line} the first line comment will run on until the end
399 of the input. You will either need to use \TEX|-|style line comments (starting
400 with \%), or change the \TEX\ category codes locally. Another possibility is to
401 say:
402
403 \starttyping
404 \begingroup
405 \endlinechar=10
406 \directlua ...
407 \endgroup
408 \stoptyping
409
410 Then \LUA\ line comments can be used, since \TEX\ does not replace line endings
411 with spaces. Of course such an approach depends on the macro package that you
412 use.
413
414 The \syntax {<16-bit number>} designates a name of a \LUA\ chunk and is
415 taken from the \type {lua.name} array (see the documentation of the \type {lua}
416 table further in this manual). When a chunk name starts with a \type {@} it will
417 be displayed as a file name. This is a side effect of the way \LUA\ implements
418 error handling.
419
420 The \prm {directlua} command is expandable. Since it passes \LUA\ code to the
421 \LUA\ interpreter its expansion from the \TEX\ viewpoint is usually empty.
422 However, there are some \LUA\ functions that produce material to be read by \TEX,
423 the so called print functions. The most simple use of these is \type
424 {tex.print(<string> s)}. The characters of the string \type {s} will be placed on
425 the \TEX\ input buffer, that is, \quote {before \TEX's eyes} to be read by \TEX\
426 immediately. For example:
427
428 \startbuffer
429 \count10=20
430 a\directlua{tex.print(tex.count[10]+5)}b
431 \stopbuffer
432
433 \typebuffer
434
435 expands to
436
437 \getbuffer
438
439 Here is another example:
440
441 \startbuffer
442 $\pi = \directlua{tex.print(math.pi)}$
443 \stopbuffer
444
445 \typebuffer
446
447 will result in
448
449 \getbuffer
450
451 Note that the expansion of \prm {directlua} is a sequence of characters, not of
452 tokens, contrary to all \TEX\ commands. So formally speaking its expansion is
453 null, but it places material on a pseudo-file to be immediately read by \TEX, as
454 \ETEX's \prm {scantokens}. For a description of print functions look at \in
455 {section} [sec:luaprint].
456
457 Because the \syntax {<general text>} is a chunk, the normal \LUA\ error handling
458 is triggered if there is a problem in the included code. The \LUA\ error messages
459 should be clear enough, but the contextual information is still pretty bad.
460 Often, you will only see the line number of the right brace at the end of the
461 code.
462
463 While on the subject of errors: some of the things you can do inside \LUA\ code
464 can break up \LUATEX\ pretty bad. If you are not careful while working with the
465 node list interface, you may even end up with assertion errors from within the
466 \TEX\ portion of the executable.
467
468 \stopsubsection
469
470 \startsubsection[title={\lpr {latelua} and \lpr {lateluafunction}}]
471
472 Contrary to \prm {directlua}, \lpr {latelua} stores \LUA\ code in a whatsit
473 that will be processed at the time of shipping out. Its intended use is a cross
474 between \PDF\ literals (often available as \orm {pdfliteral}) and the
475 traditional \TEX\ extension \prm {write}. Within the \LUA\ code you can print
476 \PDF\ statements directly to the \PDF\ file via \type {pdf.print}, or you can
477 write to other output streams via \type {texio.write} or simply using \LUA\ \IO\
478 routines.
479
480 \startsyntax
481 \latelua <general text>!crlf
482 \latelua <16-bit number> <general text>
483 \stopsyntax
484
485 Expansion of macros in the final \type {<general text>} is delayed until just
486 before the whatsit is executed (like in \prm {write}). With regard to \PDF\
487 output stream \lpr {latelua} behaves as \PDF\ page literals. The \syntax
488 {name <general text>} and \syntax {<16-bit number>} behave in the same way as
489 they do for \prm {directlua}.
490
491 The \lpr {lateluafunction} primitive takes a number and is similar to \lpr
492 {luafunction} but gets delated to shipout time. It's just there for completeness.
493
494 \stopsubsection
495
496 \startsubsection[title={\lpr {luaescapestring}}]
497
498 \topicindex {escaping}
499
500 This primitive converts a \TEX\ token sequence so that it can be safely used as
501 the contents of a \LUA\ string: embedded backslashes, double and single quotes,
502 and newlines and carriage returns are escaped. This is done by prepending an
503 extra token consisting of a backslash with category code~12, and for the line
504 endings, converting them to \type {n} and \type {r} respectively. The token
505 sequence is fully expanded.
506
507 \startsyntax
508 \luaescapestring <general text>
509 \stopsyntax
510
511 Most often, this command is not actually the best way to deal with the
512 differences between \TEX\ and \LUA. In very short bits of \LUA\ code it is often
513 not needed, and for longer stretches of \LUA\ code it is easier to keep the code
514 in a separate file and load it using \LUA's \type {dofile}:
515
516 \starttyping
517 \directlua { dofile('mysetups.lua') }
518 \stoptyping
519
520 \stopsubsection
521
522 \startsubsection[title={\lpr {luafunction}, \lpr {luafunctioncall} and \lpr {luadef}}]
523
524 The \prm {directlua} commands involves tokenization of its argument (after
525 picking up an optional name or number specification). The tokenlist is then
526 converted into a string and given to \LUA\ to turn into a function that is
527 called. The overhead is rather small but when you have millions of calls it can
528 have some impact. For this reason there is a variant call available: \lpr
529 {luafunction}. This command is used as follows:
530
531 \starttyping
532 \directlua {
533 local t = lua.get_functions_table()
534 t[1] = function() tex.print("!") end
535 t[2] = function() tex.print("?") end
536 }
537
538 \luafunction1
539 \luafunction2
540 \stoptyping
541
542 Of course the functions can also be defined in a separate file. There is no limit
543 on the number of functions apart from normal \LUA\ limitations. Of course there
544 is the limitation of no arguments but that would involve parsing and thereby give
545 no gain. The function, when called in fact gets one argument, being the index, so
546 in the following example the number \type {8} gets typeset.
547
548 \starttyping
549 \directlua {
550 local t = lua.get_functions_table()
551 t[8] = function(slot) tex.print(slot) end
552 }
553 \stoptyping
554
555 The \lpr {luafunctioncall} primitive does the same but is unexpandable, for
556 instance in an \prm {edef}. In addition \LUATEX\ provides a definer:
557
558 \starttyping
559 \luadef\MyFunctionA 1
560 \global\luadef\MyFunctionB 2
561 \protected\global\luadef\MyFunctionC 3
562 \stoptyping
563
564 You should really use these commands with care. Some references get stored in
565 tokens and assume that the function is available when that token expands. On the
566 other hand, as we have tested this functionality in relative complex situations
567 normal usage should not give problems.
568
569 \stopsubsection
570
571 \startsubsection[title={\lpr {luabytecode} and \lpr {luabytecodecall}}]
572
573 Analogue to the function callers discussed in the previous section we have byte
574 code callers. Again the call variant is unexpandable.
575
576 \starttyping
577 \directlua {
578 lua.bytecode[9998] = function(s)
579 tex.sprint(s*token.scan_int())
580 end
581 lua.bytecode[5555] = function(s)
582 tex.sprint(s*token.scan_dimen())
583 end
584 }
585 \stoptyping
586
587 This works with:
588
589 \starttyping
590 \luabytecode 9998 5 \luabytecode 5555 5sp
591 \luabytecodecall9998 5 \luabytecodecall5555 5sp
592 \stoptyping
593
594 The variable \type {s} in the code is the number of the byte code register that
595 can be used for diagnostic purposes. The advantage of bytecode registers over
596 function calls is that they are stored in the format (but without upvalues).
597
598 \stopsubsection
599
600 \stopsection
601
602 \startsection[title={Catcode tables}]
603
604 \startsubsection[title={Catcodes}]
605
606 \topicindex {catcodes}
607
608 Catcode tables are a new feature that allows you to switch to a predefined
609 catcode regime in a single statement. You can have a practically unlimited number
610 of different tables. This subsystem is backward compatible: if you never use the
611 following commands, your document will not notice any difference in behaviour
612 compared to traditional \TEX. The contents of each catcode table is independent
613 from any other catcode table, and its contents is stored and retrieved from the
614 format file.
615
616 \stopsubsection
617
618 \startsubsection[title={\lpr {catcodetable}}]
619
620 \startsyntax
621 \catcodetable <15-bit number>
622 \stopsyntax
623
624 The primitive \lpr {catcodetable} switches to a different catcode table. Such a
625 table has to be previously created using one of the two primitives below, or it
626 has to be zero. Table zero is initialized by \INITEX.
627
628 \stopsubsection
629
630 \startsubsection[title={\lpr {initcatcodetable}}]
631
632 \startsyntax
633 \initcatcodetable <15-bit number>
634 \stopsyntax
635
636 The primitive \lpr {initcatcodetable} creates a new table with catcodes
637 identical to those defined by \INITEX. The new catcode table is allocated
638 globally: it will not go away after the current group has ended. If the supplied
639 number is identical to the currently active table, an error is raised. The
640 initial values are:
641
642 \starttabulate[|c|c|l|l|]
643 \DB catcode \BC character \BC equivalent \BC category \NC \NR
644 \TB
645 \NC 0 \NC \tttf \letterbackslash \NC \NC \type {escape} \NC \NR
646 \NC 5 \NC \tttf \letterhat\letterhat M \NC return \NC \type {car_ret} \NC \NR
647 \NC 9 \NC \tttf \letterhat\letterhat @ \NC null \NC \type {ignore} \NC \NR
648 \NC 10 \NC \tttf <space> \NC space \NC \type {spacer} \NC \NR
649 \NC 11 \NC {\tttf a} \endash\ {\tttf z} \NC \NC \type {letter} \NC \NR
650 \NC 11 \NC {\tttf A} \endash\ {\tttf Z} \NC \NC \type {letter} \NC \NR
651 \NC 12 \NC everything else \NC \NC \type {other} \NC \NR
652 \NC 14 \NC \tttf \letterpercent \NC \NC \type {comment} \NC \NR
653 \NC 15 \NC \tttf \letterhat\letterhat ? \NC delete \NC \type {invalid_char} \NC \NR
654 \LL
655 \stoptabulate
656
657 \stopsubsection
658
659 \startsubsection[title={\lpr {savecatcodetable}}]
660
661 \startsyntax
662 \savecatcodetable <15-bit number>
663 \stopsyntax
664
665 \lpr {savecatcodetable} copies the current set of catcodes to a new table with
666 the requested number. The definitions in this new table are all treated as if
667 they were made in the outermost level.
668
669 The new table is allocated globally: it will not go away after the current group
670 has ended. If the supplied number is the currently active table, an error is
671 raised.
672
673 \stopsubsection
674
675 \stopsection
676
677 \startsection[title={Suppressing errors}]
678
679 \startsubsection[title={\lpr {suppressfontnotfounderror}}]
680
681 \topicindex {errors}
682
683 If this integer parameter is non|-|zero, then \LUATEX\ will not complain about
684 font metrics that are not found. Instead it will silently skip the font
685 assignment, making the requested csname for the font \prm {ifx} equal to \prm
686 {nullfont}, so that it can be tested against that without bothering the user.
687
688 \startsyntax
689 \suppressfontnotfounderror = 1
690 \stopsyntax
691
692 \stopsubsection
693
694 \startsubsection[title={\lpr {suppresslongerror}}]
695
696 \topicindex {errors}
697
698 If this integer parameter is non|-|zero, then \LUATEX\ will not complain about
699 \prm {par} commands encountered in contexts where that is normally prohibited
700 (most prominently in the arguments of macros not defined as \prm {long}).
701
702 \startsyntax
703 \suppresslongerror = 1
704 \stopsyntax
705
706 \stopsubsection
707
708 \startsubsection[title={\lpr {suppressifcsnameerror}}]
709
710 \topicindex {errors}
711
712 If this integer parameter is non|-|zero, then \LUATEX\ will not complain about
713 non-expandable commands appearing in the middle of a \prm {ifcsname} expansion.
714 Instead, it will keep getting expanded tokens from the input until it encounters
715 an \prm {endcsname} command. If the input expansion is unbalanced with respect
716 to \prm {csname} \ldots \prm {endcsname} pairs, the \LUATEX\ process may hang
717 indefinitely.
718
719 \startsyntax
720 \suppressifcsnameerror = 1
721 \stopsyntax
722
723 \stopsubsection
724
725 \startsubsection[title={\lpr {suppressoutererror}}]
726
727 \topicindex {errors}
728
729 If this new integer parameter is non|-|zero, then \LUATEX\ will not complain
730 about \prm {outer} commands encountered in contexts where that is normally
731 prohibited.
732
733 \startsyntax
734 \suppressoutererror = 1
735 \stopsyntax
736
737 \stopsubsection
738
739 \startsubsection[title={\lpr {suppressmathparerror}}]
740
741 \topicindex {errors}
742 \topicindex {math}
743
744 The following setting will permit \prm {par} tokens in a math formula:
745
746 \startsyntax
747 \suppressmathparerror = 1
748 \stopsyntax
749
750 So, the next code is valid then:
751
752 \starttyping
753 $ x + 1 =
754
755 a $
756 \stoptyping
757
758 \stopsubsection
759
760 \startsubsection[title={\lpr {suppressprimitiveerror}}]
761
762 \topicindex {errors}
763 \topicindex {primitives}
764
765 When set to a non|-|zero value the following command will not issue an error:
766
767 \startsyntax
768 \suppressprimitiveerror = 1
769
770 \primitive\notaprimitive
771 \stopsyntax
772
773 \stopsubsection
774
775 \stopsection
776
777 \startsection[title={Fonts}]
778
779 \startsubsection[title={Font syntax}]
780
781 \topicindex {fonts}
782
783 \LUATEX\ will accept a braced argument as a font name:
784
785 \starttyping
786 \font\myfont = {cmr10}
787 \stoptyping
788
789 This allows for embedded spaces, without the need for double quotes. Macro
790 expansion takes place inside the argument.
791
792 \stopsubsection
793
794 \startsubsection[title={\lpr {fontid} and \lpr {setfontid}}]
795
796 \startsyntax
797 \fontid\font
798 \stopsyntax
799
800 This primitive expands into a number. It is not a register so there is no need to
801 prefix with \prm {number} (and using \prm {the} gives an error). The currently
802 used font id is \fontid\font. Here are some more:
803
804 \starttabulate[|l|c|c|]
805 \DB style \BC command \BC font id \NC \NR
806 \TB
807 \NC normal \NC \type {\tf} \NC \bf \fontid\font \NC \NR
808 \NC bold \NC \type {\bf} \NC \bf \fontid\font \NC \NR
809 \NC italic \NC \type {\it} \NC \it \fontid\font \NC \NR
810 \NC bold italic \NC \type {\bi} \NC \bi \fontid\font \NC \NR
811 \LL
812 \stoptabulate
813
814 These numbers depend on the macro package used because each one has its own way
815 of dealing with fonts. They can also differ per run, as they can depend on the
816 order of loading fonts. For instance, when in \CONTEXT\ virtual math \UNICODE\
817 fonts are used, we can easily get over a hundred ids in use. Not all ids have to
818 be bound to a real font, after all it's just a number.
819
820 The primitive \lpr {setfontid} can be used to enable a font with the given id,
821 which of course needs to be a valid one.
822
823 \stopsubsection
824
825 \startsubsection[title={\lpr {noligs} and \lpr {nokerns}}]
826
827 \topicindex {ligatures+suppress}
828 \topicindex {kerns+suppress}
829
830 These primitives prohibit ligature and kerning insertion at the time when the
831 initial node list is built by \LUATEX's main control loop. You can enable these
832 primitives when you want to do node list processing of \quote {characters}, where
833 \TEX's normal processing would get in the way.
834
835 \startsyntax
836 \noligs <integer>!crlf
837 \nokerns <integer>
838 \stopsyntax
839
840 These primitives can also be implemented by overloading the ligature building and
841 kerning functions, i.e.\ by assigning dummy functions to their associated
842 callbacks. Keep in mind that when you define a font (using \LUA) you can also
843 omit the kern and ligature tables, which has the same effect as the above.
844
845 \stopsubsection
846
847 \startsubsection[title={\type{\nospaces}}]
848
849 \topicindex {spaces+suppress}
850
851 This new primitive can be used to overrule the usual \prm {spaceskip} related
852 heuristics when a space character is seen in a text flow. The value~\type{1}
853 triggers no injection while \type{2} results in injection of a zero skip. In \in
854 {figure} [fig:nospaces] we see the results for four characters separated by a
855 space.
856
857 \startplacefigure[reference=fig:nospaces,title={The \lpr {nospaces} options.}]
858 \startcombination[3*2]
859 {\ruledhbox to 5cm{\vtop{\hsize 10mm\nospaces=0\relax x x x x \par}\hss}} {\type {0 / hsize 10mm}}
860 {\ruledhbox to 5cm{\vtop{\hsize 10mm\nospaces=1\relax x x x x \par}\hss}} {\type {1 / hsize 10mm}}
861 {\ruledhbox to 5cm{\vtop{\hsize 10mm\nospaces=2\relax x x x x \par}\hss}} {\type {2 / hsize 10mm}}
862 {\ruledhbox to 5cm{\vtop{\hsize 1mm\nospaces=0\relax x x x x \par}\hss}} {\type {0 / hsize 1mm}}
863 {\ruledhbox to 5cm{\vtop{\hsize 1mm\nospaces=1\relax x x x x \par}\hss}} {\type {1 / hsize 1mm}}
864 {\ruledhbox to 5cm{\vtop{\hsize 1mm\nospaces=2\relax x x x x \par}\hss}} {\type {2 / hsize 1mm}}
865 \stopcombination
866 \stopplacefigure
867
868 \stopsubsection
869
870 \stopsection
871
872 \startsection[title={Tokens, commands and strings}]
873
874 \startsubsection[title={\lpr {scantextokens}}]
875
876 \topicindex {tokens+scanning}
877
878 The syntax of \lpr {scantextokens} is identical to \prm {scantokens}. This
879 primitive is a slightly adapted version of \ETEX's \prm {scantokens}. The
880 differences are:
881
882 \startitemize
883 \startitem
884 The last (and usually only) line does not have a \prm {endlinechar}
885 appended.
886 \stopitem
887 \startitem
888 \lpr {scantextokens} never raises an EOF error, and it does not execute
889 \prm {everyeof} tokens.
890 \stopitem
891 \startitem
892 There are no \quote {\unknown\ while end of file \unknown} error tests
893 executed. This allows the expansion to end on a different grouping level or
894 while a conditional is still incomplete.
895 \stopitem
896 \stopitemize
897
898 \stopsubsection
899
900 \startsubsection[title={\lpr {toksapp}, \lpr {tokspre}, \lpr {etoksapp}, \lpr {etokspre},
901 \lpr {gtoksapp}, \lpr {gtokspre}, \lpr {xtoksapp}, \lpr {xtokspre}}]
902
903 Instead of:
904
905 \starttyping
906 \toks0\expandafter{\the\toks0 foo}
907 \stoptyping
908
909 you can use:
910
911 \starttyping
912 \etoksapp0{foo}
913 \stoptyping
914
915 The \type {pre} variants prepend instead of append, and the \type {e} variants
916 expand the passed general text. The \type {g} and \type {x} variants are global.
917
918 \stopsubsection
919
920 \startsubsection[title={\prm {csstring}, \lpr {begincsname} and \lpr {lastnamedcs}}]
921
922 These are somewhat special. The \prm {csstring} primitive is like
923 \prm {string} but it omits the leading escape character. This can be
924 somewhat more efficient than stripping it afterwards.
925
926 The \lpr {begincsname} primitive is like \prm {csname} but doesn't create
927 a relaxed equivalent when there is no such name. It is equivalent to
928
929 \starttyping
930 \ifcsname foo\endcsname
931 \csname foo\endcsname
932 \fi
933 \stoptyping
934
935 The advantage is that it saves a lookup (don't expect much speedup) but more
936 important is that it avoids using the \prm {if} test. The \lpr {lastnamedcs}
937 is one that should be used with care. The above example could be written as:
938
939 \starttyping
940 \ifcsname foo\endcsname
941 \lastnamedcs
942 \fi
943 \stoptyping
944
945 This is slightly more efficient than constructing the string twice (deep down in
946 \LUATEX\ this also involves some \UTF8 juggling), but probably more relevant is
947 that it saves a few tokens and can make code a bit more readable.
948
949 \stopsubsection
950
951 \startsubsection[title={\lpr {clearmarks}}]
952
953 \topicindex {marks}
954
955 This primitive complements the \ETEX\ mark primitives and clears a mark class
956 completely, resetting all three connected mark texts to empty. It is an
957 immediate command.
958
959 \startsyntax
960 \clearmarks <16-bit number>
961 \stopsyntax
962
963 \stopsubsection
964
965 \startsubsection[title={\lpr {alignmark} and \lpr {aligntab}}]
966
967 The primitive \lpr {alignmark} duplicates the functionality of \type {#} inside
968 alignment preambles, while \lpr {aligntab} duplicates the functionality of \type
969 {&}.
970
971 \stopsubsection
972
973 \startsubsection[title={\lpr {letcharcode}}]
974
975 This primitive can be used to assign a meaning to an active character, as in:
976
977 \starttyping
978 \def\foo{bar} \letcharcode123=\foo
979 \stoptyping
980
981 This can be a bit nicer than using the uppercase tricks (using the property of
982 \prm {uppercase} that it treats active characters special).
983
984 \stopsubsection
985
986 \startsubsection[title={\lpr {glet}}]
987
988 This primitive is similar to:
989
990 \starttyping
991 \protected\def\glet{\global\let}
992 \stoptyping
993
994 but faster (only measurable with millions of calls) and probably more convenient
995 (after all we also have \type {\gdef}).
996
997 \stopsubsection
998
999 \startsubsection[title={\lpr {expanded}, \lpr {immediateassignment} and \lpr {immediateassigned}}]
1000
1001 \topicindex {expansion}
1002
1003 The \lpr {expanded} primitive takes a token list and expands it content which can
1004 come in handy: it avoids a tricky mix of \prm {expandafter} and \prm {noexpand}.
1005 You can compare it with what happens inside the body of an \prm {edef}. But this
1006 kind of expansion it still doesn't expand some primitive operations.
1007
1008 \startbuffer
1009 \newcount\NumberOfCalls
1010
1011 \def\TestMe{\advance\NumberOfCalls1 }
1012
1013 \edef\Tested{\TestMe foo:\the\NumberOfCalls}
1014 \edef\Tested{\TestMe foo:\the\NumberOfCalls}
1015 \edef\Tested{\TestMe foo:\the\NumberOfCalls}
1016
1017 \meaning\Tested
1018 \stopbuffer
1019
1020 \typebuffer
1021
1022 The result is a macro that has the not expanded code in its body:
1023
1024 \getbuffer
1025
1026 Instead we can define \tex {TestMe} in a way that expands the assignment
1027 immediately. You need of course to be aware of preventing look ahead interference
1028 by using a space or \tex {relax} (often an expression works better as it doesn't
1029 leave an \tex {relax}).
1030
1031 \startbuffer
1032 \def\TestMe{\immediateassignment\advance\NumberOfCalls1 }
1033
1034 \edef\Tested{\TestMe foo:\the\NumberOfCalls}
1035 \edef\Tested{\TestMe foo:\the\NumberOfCalls}
1036 \edef\Tested{\TestMe foo:\the\NumberOfCalls}
1037
1038 \meaning\Tested
1039 \stopbuffer
1040
1041 \typebuffer
1042
1043 This time the counter gets updates and we don't see interference in the
1044 resulting \tex {Tested} macro:
1045
1046 \getbuffer
1047
1048 Here is a somewhat silly example of expanded comparison:
1049
1050 \startbuffer
1051 \def\expandeddoifelse#1#2#3#4%
1052 {\immediateassignment\edef\tempa{#1}%
1053 \immediateassignment\edef\tempb{#2}%
1054 \ifx\tempa\tempb
1055 \immediateassignment\def\next{#3}%
1056 \else
1057 \immediateassignment\def\next{#4}%
1058 \fi
1059 \next}
1060
1061 \edef\Tested
1062 {(\expandeddoifelse{abc}{def}{yes}{nop}/%
1063 \expandeddoifelse{abc}{abc}{yes}{nop})}
1064
1065 \meaning\Tested
1066 \stopbuffer
1067
1068 \typebuffer
1069
1070 It gives:
1071
1072 \getbuffer
1073
1074 A variant is:
1075
1076 \starttyping
1077 \def\expandeddoifelse#1#2#3#4%
1078 {\immediateassigned{
1079 \edef\tempa{#1}%
1080 \edef\tempb{#2}%
1081 }%
1082 \ifx\tempa\tempb
1083 \immediateassignment\def\next{#3}%
1084 \else
1085 \immediateassignment\def\next{#4}%
1086 \fi
1087 \next}
1088 \stoptyping
1089
1090 The possible error messages are the same as using assignments in preambles of
1091 alignments and after the \prm {accent} command. The supported assignments are the
1092 so called prefixed commands (except box assignments).
1093
1094 \stopsubsection
1095
1096 \startsubsection[title={\lpr {ifcondition}}]
1097
1098 \topicindex {conditions}
1099
1100 This is a somewhat special one. When you write macros conditions need to be
1101 properly balanced in order to let \TEX's fast branch skipping work well. This new
1102 primitive is basically a no||op flagged as a condition so that the scanner can
1103 recognize it as an if|-|test. However, when a real test takes place the work is
1104 done by what follows, in the next example \tex {something}.
1105
1106 \starttyping
1107 \unexpanded\def\something#1#2%
1108 {\edef\tempa{#1}%
1109 \edef\tempb{#2}
1110 \ifx\tempa\tempb}
1111
1112 \ifcondition\something{a}{b}%
1113 \ifcondition\something{a}{a}%
1114 true 1
1115 \else
1116 false 1
1117 \fi
1118 \else
1119 \ifcondition\something{a}{a}%
1120 true 2
1121 \else
1122 false 2
1123 \fi
1124 \fi
1125 \stoptyping
1126
1127 If you are familiar with \METAPOST, this is a bit like \type {vardef} where the macro
1128 has a return value. Here the return value is a test.
1129
1130 \stopsubsection
1131
1132 \stopsection
1133
1134 \startsection[title={Boxes, rules and leaders}]
1135
1136 \startsubsection[title={\lpr {outputbox}}]
1137
1138 \topicindex {output}
1139
1140 This integer parameter allows you to alter the number of the box that will be
1141 used to store the page sent to the output routine. Its default value is 255, and
1142 the acceptable range is from 0 to 65535.
1143
1144 \startsyntax
1145 \outputbox = 12345
1146 \stopsyntax
1147
1148 \stopsubsection
1149
1150 \startsubsection[title={\prm {vpack}, \prm {hpack} and \prm {tpack}}]
1151
1152 These three primitives are like \prm {vbox}, \prm {hbox} and \prm {vtop}
1153 but don't apply the related callbacks.
1154
1155 \stopsubsection
1156
1157 \startsubsection[title={\prm {vsplit}}]
1158
1159 \topicindex {splitting}
1160
1161 The \prm {vsplit} primitive has to be followed by a specification of the required
1162 height. As alternative for the \type {to} keyword you can use \type {upto} to get
1163 a split of the given size but result has the natural dimensions then.
1164 If \prm {ignoreprimitiveerror} = 1 , the error
1165 "Infinite glue shrinkage found in box being split" that occurs
1166 when vsplit-ting a box containing infinite negative glue is turned into a warning.
1167
1168 \stopsubsection
1169
1170 \startsubsection[title={Images and reused box objects},reference=sec:imagedandforms]
1171
1172 These two concepts are now core concepts and no longer whatsits. They are in fact
1173 now implemented as rules with special properties. Normal rules have subtype~0,
1174 saved boxes have subtype~1 and images have subtype~2. This has the positive side
1175 effect that whenever we need to take content with dimensions into account, when
1176 we look at rule nodes, we automatically also deal with these two types.
1177
1178 The syntax of the \type {\save...resource} is the same as in \PDFTEX\ but you
1179 should consider them to be backend specific. This means that a macro package
1180 should treat them as such and check for the current output mode if applicable.
1181
1182 \starttabulate[|l|p|]
1183 \DB command \BC explanation \NC \NR
1184 \TB
1185 \NC \lpr {saveboxresource} \NC save the box as an object to be included later \NC \NR
1186 \NC \lpr {saveimageresource} \NC save the image as an object to be included later \NC \NR
1187 \NC \lpr {useboxresource} \NC include the saved box object here (by index) \NC \NR
1188 \NC \lpr {useimageresource} \NC include the saved image object here (by index) \NC \NR
1189 \NC \lpr {lastsavedboxresourceindex} \NC the index of the last saved box object \NC \NR
1190 \NC \lpr {lastsavedimageresourceindex} \NC the index of the last saved image object \NC \NR
1191 \NC \lpr {lastsavedimageresourcepages} \NC the number of pages in the last saved image object \NC \NR
1192 \LL
1193 \stoptabulate
1194
1195 \LUATEX\ accepts optional dimension parameters for \type {\use...resource} in the
1196 same format as for rules. With images, these dimensions are then used instead of
1197 the ones given to \lpr {useimageresource} but the original dimensions are not
1198 overwritten, so that a \lpr {useimageresource} without dimensions still
1199 provides the image with dimensions defined by \lpr {saveimageresource}. These
1200 optional parameters are not implemented for \lpr {saveboxresource}.
1201
1202 \starttyping
1203 \useimageresource width 20mm height 10mm depth 5mm \lastsavedimageresourceindex
1204 \useboxresource width 20mm height 10mm depth 5mm \lastsavedboxresourceindex
1205 \stoptyping
1206
1207 The box resources are of course implemented in the backend and therefore we do
1208 support the \type {attr} and \type {resources} keys that accept a token list. New
1209 is the \type {type} key. When set to non|-|zero the \type {/Type} entry is
1210 omitted. A value of 1 or 3 still writes a \type {/BBox}, while 2 or 3 will write
1211 a \type {/Matrix}.
1212
1213 \stopsubsection
1214
1215 \startsubsection[title={\lpr {nohrule} and \lpr {novrule}}]
1216
1217 \topicindex {rules}
1218
1219 Because introducing a new keyword can cause incompatibilities, two new primitives
1220 were introduced: \lpr {nohrule} and \lpr {novrule}. These can be used to
1221 reserve space. This is often more efficient than creating an empty box with fake
1222 dimensions.
1223
1224 \stopsubsection
1225
1226 \startsubsection[title={\lpr {gleaders}}]
1227
1228 \topicindex {leaders}
1229
1230 This type of leaders is anchored to the origin of the box to be shipped out. So
1231 they are like normal \prm {leaders} in that they align nicely, except that the
1232 alignment is based on the {\it largest\/} enclosing box instead of the {\it
1233 smallest\/}. The \type {g} stresses this global nature.
1234
1235 \stopsubsection
1236
1237 \stopsection
1238
1239 \startsection[title={Languages}]
1240
1241 \startsubsection[title={\lpr {hyphenationmin}}]
1242
1243 \topicindex {languages}
1244 \topicindex {hyphenation}
1245
1246 This primitive can be used to set the minimal word length, so setting it to a value
1247 of~$5$ means that only words of 6 characters and more will be hyphenated, of course
1248 within the constraints of the \prm {lefthyphenmin} and \prm {righthyphenmin}
1249 values (as stored in the glyph node). This primitive accepts a number and stores
1250 the value with the language.
1251
1252 \stopsubsection
1253
1254 \startsubsection[title={\prm {boundary}, \prm {noboundary}, \prm {protrusionboundary} and \prm {wordboundary}}]
1255
1256 The \prm {noboundary} command is used to inject a whatsit node but now injects a normal
1257 node with type \nod {boundary} and subtype~0. In addition you can say:
1258
1259 \starttyping
1260 x\boundary 123\relax y
1261 \stoptyping
1262
1263 This has the same effect but the subtype is now~1 and the value~123 is stored.
1264 The traditional ligature builder still sees this as a cancel boundary directive
1265 but at the \LUA\ end you can implement different behaviour. The added benefit of
1266 passing this value is a side effect of the generalization. The subtypes~2 and~3
1267 are used to control protrusion and word boundaries in hyphenation and have
1268 related primitives.
1269
1270 \stopsubsection
1271
1272 \startsubsection[title={\prm {glyphdimensionsmode}}]
1273
1274 Already in the early days of \LUATEX\ the decision was made to calculate the
1275 effective height and depth of glyphs in a way that reflected the applied vertical
1276 offset. The height got that offset added, the depth only when the offset was
1277 larger than zero. We can now control this in more detail with this mode
1278 parameter. An offset is added to the height and|/|or subtracted from the depth.
1279 The effective values are never negative. The zero mode is the default.
1280
1281 \starttabulate[|l|pl|]
1282 \DB value \BC effect \NC\NR
1283 \TB
1284 \NC \type {0} \NC the old behaviour: add the offset to the height and only subtract
1285 the offset only from the depth when it is positive \NC \NR
1286 \NC \type {1} \NC add the offset to the height and subtract it from the depth \NC \NR
1287 \NC \type {2} \NC add the offset to the height and subtract it from the depth but
1288 keep the maxima of the current and previous results \NC \NR
1289 \NC \type {3} \NC use the height and depth of the glyph, so no offset is applied \NC \NR
1290 \LL
1291 \stoptabulate
1292
1293 \stopsubsection
1294
1295 \stopsection
1296
1297 \startsection[title={Control and debugging}]
1298
1299 \startsubsection[title={Tracing}]
1300
1301 \topicindex {tracing}
1302
1303 If \prm {tracingonline} is larger than~2, the node list display will also print
1304 the node number of the nodes.
1305
1306 \stopsubsection
1307
1308 \startsubsection[title={\lpr {outputmode}}]
1309
1310 \topicindex {output}
1311 \topicindex {backend}
1312
1313 The \lpr {outputmode} variable tells \LUATEX\ what it has to produce:
1314
1315 \starttabulate[|l|l|]
1316 \DB value \BC output \NC \NR
1317 \TB
1318 \NC \type {0} \NC \DVI\ code \NC \NR
1319 \NC \type {1} \NC \PDF\ code \NC \NR
1320 \LL
1321 \stoptabulate
1322
1323 \stopsubsection
1324
1325 \startsubsection[title={\lpr {draftmode}}]
1326
1327 The value of the \lpr {draftmode} counter signals the backend if it should output
1328 less. The \PDF\ backend accepts a value of~1, while the \DVI\ backend ignores the
1329 value. This is no critical feature so we can remove it in future versions when it
1330 can make the backend cleaner.
1331
1332 \stopsubsection
1333
1334 \stopsection
1335
1336 \startsection[title={Files}]
1337
1338 \startsubsection[title={File syntax}]
1339
1340 \topicindex {files+names}
1341
1342 \LUATEX\ will accept a braced argument as a file name:
1343
1344 \starttyping
1345 \input {plain}
1346 \openin 0 {plain}
1347 \stoptyping
1348
1349 This allows for embedded spaces, without the need for double quotes. Macro
1350 expansion takes place inside the argument.
1351
1352 The \lpr {tracingfonts} primitive that has been inherited from \PDFTEX\ has
1353 been adapted to support variants in reporting the font. The reason for this
1354 extension is that a csname not always makes sense. The zero case is the default.
1355
1356 \starttabulate[|l|l|]
1357 \DB value \BC reported \NC \NR
1358 \TB
1359 \NC \type{0} \NC \type{\foo xyz} \NC \NR
1360 \NC \type{1} \NC \type{\foo (bar)} \NC \NR
1361 \NC \type{2} \NC \type{<bar> xyz} \NC \NR
1362 \NC \type{3} \NC \type{<bar @ ..pt> xyz} \NC \NR
1363 \NC \type{4} \NC \type{<id>} \NC \NR
1364 \NC \type{5} \NC \type{<id: bar>} \NC \NR
1365 \NC \type{6} \NC \type{<id: bar @ ..pt> xyz} \NC \NR
1366 \LL
1367 \stoptabulate
1368
1369 \stopsubsection
1370
1371 \startsubsection[title={Writing to file}]
1372
1373 \topicindex {files+writing}
1374
1375 You can now open upto 127 files with \prm {openout}. When no file is open
1376 writes will go to the console and log. As a consequence a system command is
1377 no longer possible but one can use \type {os.execute} to do the same.
1378
1379 \stopsubsection
1380
1381 \stopsection
1382
1383 \startsection[title={Math}]
1384
1385 \topicindex {math}
1386
1387 We will cover math extensions in its own chapter because not only the font
1388 subsystem and spacing model have been enhanced (thereby introducing many new
1389 primitives) but also because some more control has been added to existing
1390 functionality. Much of this relates to the different approaches of traditional
1391 \TEX\ fonts and \OPENTYPE\ math.
1392
1393 \stopsection
1394
1395 \stopchapter
1396
1397 \stopcomponent