manual/luatex-modifications.tex

   1 % language=uk
   2
   3 \environment luatex-style
   4 \environment luatex-logos
   5
   6 \startcomponent luatex-modifications
   7
   8 \startchapter[reference=modifications,title={Modifications}]
   9
  10 \startsection[title=The merged engines]
  11
  12 \startsubsection[title=The need for change]
  13
  14 The first version of \LUATEX\ only had a few extra primitives and it was largely
  15 the same as \PDFTEX. Then we merged substantial parts of \ALEPH\ into the code
  16 and got more primitives. When we got more stable the decision was made to clean
  17 up the rather hybrid nature of the program. This means that some primitives have
  18 been promoted to core primitives, often with a different name, and that others
  19 were removed. This made it possible to start cleaning up the code base. In \in
  20 {chapter} [enhancements] we discussed some new primitives, here we will cover
  21 most of the adapted ones.
  22
  23 Besides the expected changes caused by new functionality, there are a number of
  24 not|-|so|-|expected changes. These are sometimes a side|-|effect of a new
  25 (conflicting) feature, or, more often than not, a change neccessary to clean up
  26 the internal interfaces. These will also be mentioned.
  27
  28 \stopsubsection
  29
  30 \startsubsection[title=Changes from \TEX\ 3.1415926]
  31
  32 Of course it all starts with traditional \TEX. Even if we started with \PDFTEX,
  33 most still comes from the original. But we divert a bit.
  34
  35 \startitemize
  36
  37 \startitem
  38     The current code base is written in \CCODE, not \PASCAL. We use \CWEB\ when
  39     possible. As a consequence instead of one large file plus change files, we
  40     now have multiple files organized in categories like \type {tex}, \type
  41     {pdf}, \type {lang}, \type {font}, \type {lua}, etc. There are some artefacts
  42     of the conversion to \CCODE, but in due time we will clean up the source code
  43     and make sure that the documentation is done right. Many files are in the
  44     \CWEB\ format, but others, like those interfacing to \LUA, are \CCODE\ files.
  45     Of course we want to stay as close as possible to the original so that the
  46     documentation of the fundamentals behind \TEX\ by Don Knuth still applies.
  47 \stopitem
  48
  49 \startitem
  50     See \in {chapter} [languages] for many small changes related to paragraph
  51     building, language handling and hyphenation. The most important change is
  52     that adding a brace group in the middle of a word (like in \type {of{}fice})
  53     does not prevent ligature creation.
  54 \stopitem
  55
  56 \startitem
  57     There is no pool file, all strings are embedded during compilation.
  58 \stopitem
  59
  60 \startitem
  61     The specifier \type {plus 1 fillll} does not generate an error. The extra
  62     \quote{l} is simply typeset.
  63 \stopitem
  64
  65 \startitem
  66     The upper limit to \type {\endlinechar} and \type {\newlinechar} is 127.
  67 \stopitem
  68
  69 \startitem
  70     Magnification (\type {\mag}) is only supported in \DVI\ output mode. You can
  71     set this parameter and it even works with \type {true} units till you switch
  72     to \PDF\ output mode. When you use \PDF\ output you can best not touch the
  73     \type {\mag} variable. This fuzzy behaviour is not much different from using
  74     \PDF\ backend related functionality while eventually \DVI\ output is
  75     required.
  76
  77     After the output mode has been frozen (normally that happens when the first
  78     page is shipped out) or when \PDF\ output is enabled, the \type {true}
  79     specification is ignored. When you preload a plain format adapted to
  80     \LUATEX\ it can be that the \type {\mag} parameter already has been set.
  81 \stopitem
  82
  83 \stopitemize
  84
  85 \stopsubsection
  86
  87 \startsubsection[title=Changes from \ETEX\ 2.2]
  88
  89 Being the de factor standard extension of course we provide the \ETEX\
  90 functionality, but with a few small adaptations.
  91
  92 \startitemize
  93
  94 \startitem
  95     The \ETEX\ functionality is always present and enabled so the prepended
  96     asterisk or \type {-etex} switch for \INITEX\ is not needed.
  97 \stopitem
  98
  99 \startitem
 100     The \TEXXET\ extension is not present, so the primitives \type
 101     {\TeXXeTstate}, \type {\beginR}, \type {\beginL}, \type {\endR} and \type
 102     {\endL} are missing. Instead we use the \OMEGA\ approach to directionality.
 103 \stopitem
 104
 105 \startitem
 106     Some of the tracing information that is output by \ETEX's \type
 107     {\tracingassigns} and \type {\tracingrestores} is not there.
 108 \stopitem
 109
 110 \startitem
 111     Register management in \LUATEX\ uses the \ALEPH\ model, so the maximum value
 112     is 65535 and the implementation uses a flat array instead of the mixed
 113     flat|\&|sparse model from \ETEX.
 114 \stopitem
 115
 116 \startitem
 117     When kpathsea is used to find files, \LUATEX\ uses the \type {ofm} file
 118     format to search for font metrics. In turn, this means that \LUATEX\ looks at
 119     the \type {OFMFONTS} configuration variable (like \OMEGA\ and \ALEPH) instead
 120     of \type {TFMFONTS} (like \TEX\ and \PDFTEX). Likewise for virtual fonts
 121     (\LUATEX\ uses the variable \type {OVFFONTS} instead of \type {VFFONTS}).
 122 \stopitem
 123
 124 \stopitemize
 125
 126 \stopsubsection
 127
 128 \startsubsection[title=Changes from \PDFTEX\ 1.40]
 129
 130 Because we want to produce \PDF\ the most natural starting point was the popular
 131 \PDFTEX\ program. We inherit the stable features, dropped most of the
 132 experimental code and promoted some functionality to core \LUATEX\ functionality
 133 which in turn triggered renaming primitives.
 134
 135 For compatibility reasons we still refer to \type {\pdf...} commands but \LUATEX\
 136 has a different backend interface. Instead of these primitives there are three
 137 interfacing primitives: \type {\pdfextension}, \type {\pdfvariable} and
 138 \type {\pdffeedback} that take keywords and optional further arguments. This way
 139 we can extend the features when needed but don't need to adapt the core engine.
 140 The front- and backend are decoupled as much as possible.
 141
 142 \startitemize
 143
 144 \startitem
 145     The (experimental) support for snap nodes has been removed, because it is
 146     much more natural to build this functionality on top of node processing and
 147     attributes. The associated primitives that are now gone are: \type
 148     {\pdfsnaprefpoint}, \type {\pdfsnapy}, and \type {\pdfsnapycomp}.
 149 \stopitem
 150
 151 \startitem
 152     The (experimental) support for specialized spacing around nodes has also been
 153     removed. The associated primitives that are now gone are: \type
 154     {\pdfadjustinterwordglue}, \type {\pdfprependkern}, and \type
 155     {\pdfappendkern}, as well as the five supporting primitives \type
 156     {\knbscode}, \type {\stbscode}, \type {\shbscode}, \type {\knbccode}, and
 157     \type {\knaccode}.
 158 \stopitem
 159
 160 \startitem
 161     A number of \quote {\PDFTEX\ primitives} have been removed as they can be
 162     implemented using \LUA:
 163
 164     \start \raggedright
 165     \type {\pdfelapsedtime}, \type {\pdfescapehex}, \type {\pdfescapename}, \type
 166     {\pdfescapestring}, \type {\pdffiledump}, \type {\pdffilemoddate}, \type
 167     {\pdffilesize}, \type {\pdfforcepagebox}, \type {\pdflastmatch}, \type
 168     {\pdfmatch}, \type {\pdfmdfivesum}, \type {\pdfmovechars}, \type
 169     {\pdfoptionalwaysusepdfpagebox}, \type {\pdfoptionpdfinclusionerrorlevel},
 170     \type {\pdfresettimer}, \type {\pdfshellescape}, \type {\pdfstrcmp} and \type
 171     {\pdfunescapehex}
 172     \par \stop
 173 \stopitem
 174
 175 \startitem
 176     The version related primitives \type {\pdftexbanner}, \type {\pdftexversion}
 177     and \type {\pdftexrevision} are no longer present as there is no longer a
 178     relationship with \PDFTEX\ development.
 179 \stopitem
 180
 181 \startitem
 182     The experimental snapper mechanism has been removed and therefore also the
 183     primitives:
 184
 185     \start \raggedright
 186     \type {\pdfignoreddimen}, \type {\pdffirstlineheight}, \type
 187     {\pdfeachlineheight}, \type {\pdfeachlinedepth} and \type
 188     {\pdflastlinedepth}
 189     \par \stop
 190 \stopitem
 191
 192 \startitem
 193     The experimental primitives \type {\primitive}, \type {\ifprimitive}, \type
 194     {\ifabsnum} and \type {\ifabsdim} are promoted to core primitives. The \type
 195     {\pdf*} prefixed originals are not available.
 196 \stopitem
 197
 198 \startitem
 199     The \PNG\ transparency fix from 1.40.6 is not applied as high|-|level support
 200     is pending. Because \LUATEX\ has a different subsystem for managing images,
 201     more diversion from its ancestor happened in the meantime.
 202 \stopitem
 203
 204 \startitem
 205     Two extra token lists are provides, \type {\pdfxformresources} and \type
 206     {\pdfxformattr}, as an alternative to \type {\pdfxform} keywords.
 207 \stopitem
 208
 209 \startitem
 210     The current version of \LUATEX\ no longer replaces and|/|or merges fonts in
 211     embedded \PDF\ files with fonts of the enveloping \PDF\ document. This
 212     regression may be temporary, depending on how the rewritten font backend will
 213     look like.
 214 \stopitem
 215
 216 \startitem
 217     The primitives \type {\pdfpagewidth} and \type {\pdfpageheight} have been removed
 218     because \type {\pagewidth} and \type {\pageheight} have that purpose.
 219 \stopitem
 220
 221 \startitem
 222     The primitives \type {\pdfnormaldeviate}, \type {\pdfuniformdeviate}, \type
 223     {\pdfsetrandomseed} and \type {\pdfrandomseed} have been promoted to core
 224     primitives without \type {pdf} prefix so the original commands are no longer
 225     recognized.
 226 \stopitem
 227
 228 \startitem
 229     The primitives \type {\ifincsname}, \type {\expanded} and \type {\quitvmode}
 230     are now core primitives.
 231 \stopitem
 232
 233 \startitem
 234     As the hz and protrusion mechanism are part of the core the related
 235     primitives \type {\lpcode}, \type {\rpcode}, \type {\efcode}, \type
 236     {\leftmarginkern}, \type {\rightmarginkern} are promoted to core primitives. The
 237     two commands \type {\protrudechars} and \type {\adjustspacing} replace their
 238     prefixed with \type {\pdf} originals.
 239 \stopitem
 240
 241 \startitem
 242     The hz optimization code has been partially redone so that we no longer need
 243     to create extra font instances. The front- and backend have been decoupled
 244     and more efficient (\PDF) code is generated.
 245 \stopitem
 246
 247 \startitem
 248     When \type {\adjustspacing} has value~2, hz optimization will be applied to
 249     glyphs and kerns. When the value is~3, only glyphs will be treated. A value
 250     smaller than~2 disables this feature.
 251 \stopitem
 252
 253 \startitem
 254     The \type {\tagcode} primitive is promoted to core primitive.
 255 \stopitem
 256
 257 \startitem
 258     The \type {\letterspacefont} feature is now part of the core but will not be
 259     changed (improved). We just provide it for legacy use.
 260 \stopitem
 261
 262 \startitem
 263     The \type {\pdfnoligatures} primitive is now \type {\ignoreligaturesinfont}.
 264 \stopitem
 265
 266 \startitem
 267     The \type {\pdfcopyfont} primitive is now \type {\copyfont}.
 268 \stopitem
 269
 270 \startitem
 271     The \type {\pdffontexpand} primitive is now \type {\expandglyphsinfont}.
 272 \stopitem
 273
 274 \startitem
 275     Because position tracking is also available in \DVI\ mode the \type
 276     {\savepos}, \type {\lastxpos} and \type {\lastypos} commands now replace
 277     their \type {pdf} prefixed originals.
 278 \stopitem
 279
 280 \startitem
 281     The introspective primitives \type {\pdflastximagecolordepth} and \type
 282     {\pdfximagebbox} have been removed. One can use external applications to
 283     determine these properties or use the built|-|in \type {img} library.
 284 \stopitem
 285
 286 \startitem
 287     The initializers \type {\pdfoutput} has been replaced by \type {\outputmode} and
 288     \type {\pdfdraftmode} is now \type {\draftmode}.
 289 \stopitem
 290
 291 \startitem
 292     The pixel multiplier dimension \type {\pdfpxdimen} lots its prefix and is now calles
 293     \type {\pxdimen}.
 294 \stopitem
 295
 296 \startitem
 297     An extra \type {\pdfimageaddfilename} option has been added that can be used to block
 298     writing the filename to the \PDF\ file.
 299 \stopitem
 300
 301 \startitem
 302     The primitive \type {\pdftracingfonts} is now \type {\tracingfonts} as it
 303     doesn't relate to the backend.
 304 \stopitem
 305
 306 \startitem
 307     The experimental primitive \type {\pdfinsertht} is kept as \type {\insertht}.
 308 \stopitem
 309
 310 \startitem
 311     The promotion of primitives to core primitives as well as the separation of
 312     font- and backend means that the initialization namespace \type {pdftex} is
 313     gone.
 314 \stopitem
 315
 316 \stopitemize
 317
 318 One change involves the so called xforms and ximages. In \PDFTEX\ these are
 319 implemented as so called whatsits. But contrary to other whatsits they have
 320 dimensions that need to be taken into account when for instance calculating
 321 optimal line breaks. In \LUATEX\ these are now promoted to normal nodes, which
 322 simplifies code that needs those dimensions.
 323
 324 Another reason for promotion is that these are useful concepts. Backends can
 325 provide the ability to use content that has been rendered in several places,
 326 and images are also common. For that reason we also changed the names:
 327
 328 \starttabulate[|l|l|]
 329 \NC \bf new name                         \NC \bf old name \NC \NR
 330 \NC \type {\saveboxresource}             \NC \type {\pdfxform}           \NC \NR
 331 \NC \type {\saveimageresource}           \NC \type {\pdfximage}          \NC \NR
 332 \NC \type {\useboxresource}              \NC \type {\pdfrefxform}        \NC \NR
 333 \NC \type {\useimageresource}            \NC \type {\pdfrefximage}       \NC \NR
 334 \NC \type {\lastsavedboxresourceindex}   \NC \type {\pdflastxform}       \NC \NR
 335 \NC \type {\lastsavedimageresourceindex} \NC \type {\pdflastximage}      \NC \NR
 336 \NC \type {\lastsavedimageresourcepages} \NC \type {\pdflastximagepages} \NC \NR
 337 \stoptabulate
 338
 339 There are a few \type {\pdffeedback} features that relate to this but these are
 340 typical backend specific ones. The index that gets returned is to be considered
 341 as \quote {just a number} and although it still has the same meaning (object
 342 related) as before, you should not depend on that.
 343
 344 The protrusion detection mechanism is enhanced a bit to enable a bit more complex
 345 situations. When protrusion characters are identified some nodes are skipped:
 346
 347 \startitemize[packed]
 348 \startitem zero glue \stopitem
 349 \startitem penalties \stopitem
 350 \startitem empty discretionaries \stopitem
 351 \startitem normal zero kerns \stopitem
 352 \startitem rules with zero dimensions \stopitem
 353 \startitem math nodes with a surround of zero \stopitem
 354 \startitem dir nodes \stopitem
 355 \startitem empty horizontal lists \stopitem
 356 \startitem local par nodes \stopitem
 357 \startitem inserts, marks and adjusts \stopitem
 358 \startitem boundaries \stopitem
 359 \startitem whatsits \stopitem
 360 \stopitemize
 361
 362 Because this can not be enough, you can also use a protrusion boundary node to
 363 make the next node being ignored. When the value is~1 or~3, the next node will be
 364 ignored in the test when locating a left boundary condition. When the value is~2
 365 or~3, the previous node will be ignored when locating a right boundary condition
 366 (the search goes from right to left). This permits protrusion combined with for
 367 instance content moved into the margin:
 368
 369 \starttyping
 370 \protrusionboundary1\llap{!\quad}«Who needs protrusion?»
 371 \stoptyping
 372
 373 \stopsubsection
 374
 375 \startsubsection[title=Changes from \ALEPH\ RC4]
 376
 377 Because we wanted proper directional typesetting the \ALEPH\ mechanisms looked
 378 most attractive. These are rather close to the ones provided by \OMEGA, so what
 379 we say next applies to both these programs.
 380
 381 \startitemize
 382
 383 \startitem
 384     The extended 16-bit math primitives (\type {\omathcode} etc.) have been
 385     removed.
 386 \stopitem
 387
 388 \startitem
 389     The \OCP\ processing has been removed completely and as a consequence, the
 390     following primitives have been removed:
 391
 392     \start \raggedright
 393     \type {\ocp}, \type {\externalocp}, \type {\ocplist}, \type {\pushocplist},
 394     \type {\popocplist}, \type {\clearocplists}, \type {\addbeforeocplist}, \type
 395     {\addafterocplist}, \type {\removebeforeocplist}, \type {\removeafterocplist}
 396     and \type {\ocptracelevel}
 397     \par \stop
 398 \stopitem
 399
 400 \startitem
 401     \LUATEX\ only understands 4~of the 16~direction specifiers of \ALEPH: \type
 402     {TLT} (latin), \type {TRT} (arabic), \type {RTT} (cjk), \type {LTL}
 403     (mongolian). All other direction specifiers generate an error.
 404 \stopitem
 405
 406 \startitem
 407     The input translations from \ALEPH\ are not implemented, the related
 408     primitives are not available:
 409
 410     \start \raggedright
 411     \type {\DefaultInputMode}, \type {\noDefaultInputMode}, \type {\noInputMode},
 412     \type {\InputMode}, \type {\DefaultOutputMode}, \type {\noDefaultOutputMode},
 413     \type {\noOutputMode}, \type {\OutputMode}, \type {\DefaultInputTranslation},
 414     \type {\noDefaultInputTranslation}, \type {\noInputTranslation}, \type
 415     {\InputTranslation}, \type {\DefaultOutputTranslation}, \type
 416     {\noDefaultOutputTranslation}, \type {\noOutputTranslation} and \type
 417     {\OutputTranslation}
 418     \par \stop
 419 \stopitem
 420
 421 \startitem
 422     Several bugs have been fixed an confusing implementation details have been sorted
 423     out.
 424 \stopitem
 425
 426 \startitem
 427     The scanner for direction specifications now allows an optional space after
 428     the direction is completely parsed.
 429 \stopitem
 430
 431 \startitem
 432     The \type {^^} notation has been extended: after \type {^^^^} four hexadecimal
 433     characters are expected and after \type {^^^^^^} six hexadecimal characters
 434     have to be given. The original \TEX\ interpretation is still valid for the
 435     \type {^^} case but the four and six variants do no backtracking, i.e.\ when
 436     they are not followed by the right number of hexadecimal digits they issue an
 437     error message. Because \type{^^^} is a normal \TEX\ case, we don't support the
 438     odd number of \type {^^^^^} either.
 439 \stopitem
 440
 441 \startitem
 442     Glues {\it immediately after} direction change commands are not legal
 443     breakpoints.
 444 \stopitem
 445
 446 \startitem
 447     Several mechanisms that need to be right|-|to|-|left aware have been
 448     improved. For instance placement of formula numbers.
 449 \stopitem
 450
 451 \startitem
 452     The page dimension related primitives \type {\pagewidth} and \type
 453     {\pageheight} have been promoted to core primitives. The \type {\hoffset} and
 454     \type {\voffset} primitives have been fixed.
 455 \stopitem
 456
 457 \startitem
 458     The primitives \type {\charwd}, \type {\charht}, \type {\chardp} and \type
 459     {\charit} have been removed as we have the \ETEX\ variants \type
 460     {\fontchar*}.
 461 \stopitem
 462
 463 \startitem
 464     The two dimension registers \type {\pagerightoffset} and \type
 465     {\pagebottomoffset} are now core primitives.
 466 \stopitem
 467
 468 \startitem
 469     The direction related primitives \type {\pagedir}, \type {\bodydir}, \type
 470     {\pardir}, \type {\textdir}, \type {\mathdir} and \type {\boxdir} are now
 471     core primitives.
 472 \stopitem
 473
 474 \startitem
 475     The promotion of primitives to core primitives as well as the removed of all
 476     others means that the initialization namespace \type {aleph} is gone.
 477 \stopitem
 478
 479 \stopitemize
 480
 481 The above let's itself summarize as: we took the 32 bit aspects and much of the
 482 directional mechanisms.
 483
 484 \stopsubsection
 485
 486 \startsubsection[title=Changes from standard \WEBC]
 487
 488 The compilation framework is \WEBC\ and we keep using that but without the
 489 \PASCAL\ to \CCODE\ step. This framework also provides some common features that
 490 deal with reading bytes from files and locating files in \TDS. This is what we do
 491 different:
 492
 493 \startitemize
 494
 495 \startitem
 496     There is no mltex support.
 497 \stopitem
 498
 499 \startitem
 500     There is no enctex support.
 501 \stopitem
 502
 503 \startitem
 504     The following encoding related command line switches are silently ignored,
 505     even in non|-|\LUA\ mode: \type {-8bit}, \type {-translate-file}, \type
 506     {-mltex}, \type {-enc} and \type {-etex}.
 507 \stopitem
 508
 509 \startitem
 510     The \type {\openout} whatsits are not written to the log file.
 511 \stopitem
 512
 513 \startitem
 514     Some of the so|-|called \WEBC\ extensions are hard to set up in non|-|\KPSE\
 515     mode because \type {texmf.cnf} is not read: \type {shell-escape} is off (but
 516     that is not a problem because of \LUA's \type {os.execute}), and the paranoia
 517     checks on \type {openin} and \type {openout} do not happen. However, it is
 518     easy for a \LUA\ script to do this itself by overloading \type {io.open}.
 519 \stopitem
 520
 521 \startitem
 522     The \quote{E} option does not do anything useful.
 523 \stopitem
 524
 525 \stopitemize
 526
 527 \stopsubsection
 528
 529 \stopsection
 530
 531 \startsection[reference=backendprimitives,title=The backend primitives \type {\pdf*}]
 532
 533 In a previous section we mentioned that some \PDFTEX\ primitives were removed and
 534 others promoted to core \LUATEX\ primitives. That is only part of the story. In
 535 order to separate the backend specific primitives in de code these commands are
 536 now replaced by only a few. In traditional \TEX\ we only had the \DVI\ backend
 537 but now we have two: \DVI\ and \PDF. Additional functionality is implemented as
 538 \quote {extensions} in \TEX speak. By separating more strickly we are able to
 539 keep the core (fontend) clean and stable. If for some reason an extra backend
 540 option is needed, it can be implemented without touching the core. The three
 541 \PDF\ backend related primitives are
 542
 543 \starttyping
 544 \pdfextension command [specification]
 545 \pdfvariable  name
 546 \pdffeedback  name
 547 \stoptyping
 548
 549 An extension triggers further parsing, depending on the command given. A variable is
 550 a (kind of) register and can be read and written, while a feedback is reporting
 551 something (as it comes from the backend it's normally a sequence of tokens).
 552
 553 In order for \LUATEX\ to be more than just \TEX\ you need to enable primitives. That
 554 has already be the case right from the start. If you want the traditional \PDFTEX\
 555 primitives (for as far their functionality is still around) you now can do this:
 556
 557 \starttyping
 558 \protected\def\pdfliteral             {\pdfextension literal}
 559 \protected\def\pdfcolorstack          {\pdfextension colorstack}
 560 \protected\def\pdfsetmatrix           {\pdfextension setmatrix}
 561 \protected\def\pdfsave                {\pdfextension save\relax}
 562 \protected\def\pdfrestore             {\pdfextension restore\relax}
 563 \protected\def\pdfobj                 {\pdfextension obj }
 564 \protected\def\pdfrefobj              {\pdfextension refobj }
 565 \protected\def\pdfannot               {\pdfextension annot }
 566 \protected\def\pdfstartlink           {\pdfextension startlink }
 567 \protected\def\pdfendlink             {\pdfextension endlink\relax}
 568 \protected\def\pdfoutline             {\pdfextension outline }
 569 \protected\def\pdfdest                {\pdfextension dest }
 570 \protected\def\pdfthread              {\pdfextension thread }
 571 \protected\def\pdfstartthread         {\pdfextension startthread }
 572 \protected\def\pdfendthread           {\pdfextension endthread\relax}
 573 \protected\def\pdfinfo                {\pdfextension info }
 574 \protected\def\pdfcatalog             {\pdfextension catalog }
 575 \protected\def\pdfnames               {\pdfextension names }
 576 \protected\def\pdfincludechars        {\pdfextension includechars }
 577 \protected\def\pdffontattr            {\pdfextension fontattr }
 578 \protected\def\pdfmapfile             {\pdfextension mapfile }
 579 \protected\def\pdfmapline             {\pdfextension mapline }
 580 \protected\def\pdftrailer             {\pdfextension trailer }
 581 \protected\def\pdfglyphtounicode      {\pdfextension glyphtounicode }
 582 \stoptyping
 583
 584 The introspective primitives can be defined as:
 585
 586 \starttyping
 587 \def\pdftexversion    {\numexpr\pdffeedback version\relax}
 588 \def\pdftexrevision           {\pdffeedback revision}
 589 \def\pdflastlink      {\numexpr\pdffeedback lastlink\relax}
 590 \def\pdfretval        {\numexpr\pdffeedback retval\relax}
 591 \def\pdflastobj       {\numexpr\pdffeedback lastobj\relax}
 592 \def\pdflastannot     {\numexpr\pdffeedback lastannot\relax}
 593 \def\pdfxformname     {\numexpr\pdffeedback xformname\relax}
 594 \def\pdfcreationdate          {\pdffeedback creationdate}
 595 \def\pdffontname      {\numexpr\pdffeedback fontname\relax}
 596 \def\pdffontobjnum    {\numexpr\pdffeedback fontobjnum\relax}
 597 \def\pdffontsize      {\dimexpr\pdffeedback fontsize\relax}
 598 \def\pdfpageref       {\numexpr\pdffeedback pageref\relax}
 599 \def\pdfcolorstackinit        {\pdffeedback colorstackinit}
 600 \stoptyping
 601
 602 The configuration related registers have become:
 603
 604 \starttyping
 605 \edef\pdfcompresslevel            {\pdfvariable compresslevel}
 606 \edef\pdfobjcompresslevel         {\pdfvariable objcompresslevel}
 607 \edef\pdfdecimaldigits            {\pdfvariable decimaldigits}
 608 \edef\pdfgamma                    {\pdfvariable gamma}
 609 \edef\pdfimageresolution          {\pdfvariable imageresolution}
 610 \edef\pdfimageapplygamma          {\pdfvariable imageapplygamma}
 611 \edef\pdfimagegamma               {\pdfvariable imagegamma}
 612 \edef\pdfimagehicolor             {\pdfvariable imagehicolor}
 613 \edef\pdfimageaddfilename         {\pdfvariable imageaddfilename}
 614 \edef\pdfpkresolution             {\pdfvariable pkresolution}
 615 \edef\pdfpkfixeddpi               {\pdfvariable pkfixeddpi}
 616 \edef\pdfinclusioncopyfonts       {\pdfvariable inclusioncopyfonts}
 617 \edef\pdfinclusionerrorlevel      {\pdfvariable inclusionerrorlevel}
 618 \edef\pdfignoreunknownimages      {\pdfvariable ignoreunknownimages}
 619 \edef\pdfgentounicode             {\pdfvariable gentounicode}
 620 \edef\pdfomitcidset               {\pdfvariable omitcidset}
 621 \edef\pdfpagebox                  {\pdfvariable pagebox}
 622 \edef\pdfminorversion             {\pdfvariable minorversion}
 623 \edef\pdfuniqueresname            {\pdfvariable uniqueresname}
 624
 625 \edef\pdfhorigin                  {\pdfvariable horigin}
 626 \edef\pdfvorigin                  {\pdfvariable vorigin}
 627 \edef\pdflinkmargin               {\pdfvariable linkmargin}
 628 \edef\pdfdestmargin               {\pdfvariable destmargin}
 629 \edef\pdfthreadmargin             {\pdfvariable threadmargin}
 630 \edef\pdfxformmargin              {\pdfvariable xformmargin}
 631
 632 \edef\pdfpagesattr                {\pdfvariable pagesattr}
 633 \edef\pdfpageattr                 {\pdfvariable pageattr}
 634 \edef\pdfpageresources            {\pdfvariable pageresources}
 635 \edef\pdfxformattr                {\pdfvariable xformattr}
 636 \edef\pdfxformresources           {\pdfvariable xformresources}
 637 \edef\pdfpkmode                   {\pdfvariable pkmode}
 638
 639 \edef\pdfsuppressoptionalinfo     {\pdfvariable suppressoptionalinfo }
 640 \edef\pdftrailerid                {\pdfvariable trailerid }
 641 \stoptyping
 642
 643 The variables are internal ones, so they are anonymous. When you ask for the
 644 meaning of a few previously defined ones:
 645
 646 \starttyping
 647 \meaning\pdfhorigin
 648 \meaning\pdfcompresslevel
 649 \meaning\pdfpageattr
 650 \stoptyping
 651
 652 you will get:
 653
 654 \starttyping
 655 macro:->[internal backend dimension]
 656 macro:->[internal backend integer]
 657 macro:->[internal backend tokenlist]
 658 \stoptyping
 659
 660 The \type {\edef} can also be an \type {\def} but it's a bit more efficient
 661 to expand the lookup related register beforehand. After that you can adapt
 662 the defaults; these are:
 663
 664 \starttyping
 665 \pdfcompresslevel         9
 666 \pdfobjcompresslevel      1 % used: (0,9)
 667 \pdfdecimaldigits         4 % used: (3,6)
 668 \pdfgamma              1000
 669 \pdfimageresolution      71
 670 \pdfimageapplygamma       0
 671 \pdfimagegamma         2200
 672 \pdfimagehicolor          1
 673 \pdfimageaddfilename      1
 674 \pdfpkresolution         72
 675 \pdfpkfixeddpi            0
 676 \pdfinclusioncopyfonts    0
 677 \pdfinclusionerrorlevel   0
 678 \pdfignoreunknownimages   0
 679 \pdfgentounicode          0
 680 \pdfomitcidset            0
 681 \pdfpagebox               0
 682 \pdfminorversion          4
 683 \pdfuniqueresname         0
 684
 685 \pdfhorigin             1in
 686 \pdfvorigin             1in
 687 \pdflinkmargin          0pt
 688 \pdfdestmargin          0pt
 689 \pdfthreadmargin        0pt
 690 \pdfxformmargin         0pt
 691 \stoptyping
 692
 693 If you also want some backward compatibility, you can add:
 694
 695 \starttyping
 696 \let\pdfpagewidth      \pagewidth
 697 \let\pdfpageheight     \pageheight
 698
 699 \let\pdfadjustspacing  \adjustspacing
 700 \let\pdfprotrudechars  \protrudechars
 701 \let\pdfnoligatures    \ignoreligaturesinfont
 702 \let\pdffontexpand     \expandglyphsinfont
 703 \let\pdfcopyfont       \copyfont
 704
 705 \let\pdfxform          \saveboxresource
 706 \let\pdflastxform      \lastsavedboxresourceindex
 707 \let\pdfrefxform       \useboxresource
 708
 709 \let\pdfximage         \saveimageresource
 710 \let\pdflastximage     \lastsavedimageresourceindex
 711 \let\pdflastximagepages\lastsavedimageresourcepages
 712 \let\pdfrefximage      \useimageresource
 713
 714 \let\pdfsavepos        \savepos
 715 \let\pdflastxpos       \lastxpos
 716 \let\pdflastypos       \lastypos
 717
 718 \let\pdfoutput         \outputmode
 719 \let\pdfdraftmode      \draftmode
 720
 721 \let\pdfpxdimen        \pxdimen
 722
 723 \let\pdfinsertht       \insertht
 724
 725 \let\pdfnormaldeviate  \normaldeviate
 726 \let\pdfuniformdeviate \uniformdeviate
 727 \let\pdfsetrandomseed  \setrandomseed
 728 \let\pdfrandomseed     \randomseed
 729
 730 \let\pdfprimitive      \primitive
 731 \let\ifpdfprimitive    \ifprimitive
 732
 733 \let\ifpdfabsnum       \ifabsnum
 734 \let\ifpdfabsdim       \ifabsdim
 735 \stoptyping
 736
 737 And even:
 738
 739 \starttyping
 740 \newdimen\pdfeachlineheight
 741 \newdimen\pdfeachlinedepth
 742 \newdimen\pdflastlinedepth
 743 \newdimen\pdffirstlineheight
 744 \newdimen\pdfignoreddimen
 745 \stoptyping
 746
 747 The backend is derived from \PDFTEX\ so the same syntax applies. However, the
 748 \type {outline} command accepts a \type {objnum} followed by a number. No
 749 checking takes place so when this is used it had better be a valid (flushed)
 750 object.
 751
 752 In order to be (more or less) compatible with \PDFTEX\ we also support the
 753 option to suppress some info:
 754
 755 \starttyping
 756 \pdfvariable suppressoptionalinfo \numexpr
 757         0
 758     +   1   % PTEX.FullBanner
 759     +   2   % PTEX.FileName
 760     +   4   % PTEX.PageNumber
 761     +   8   % PTEX.InfoDict
 762     +  16   % Creator
 763     +  32   % CreationDate
 764     +  64   % ModDate
 765     + 128   % Producer
 766     + 256   % Trapped
 767     + 512   % ID
 768 \relax
 769 \stoptyping
 770
 771 In addition you can overload the trailer id, but we don't do any checking on
 772 validity, so you have to pass a valid array. The following is like the ones
 773 normally generated by the engine:
 774
 775 \starttyping
 776 \pdfvariable trailerid {[
 777     <FA052949448907805BA83C1E78896398>
 778     <FA052949448907805BA83C1E78896398>
 779 ]}
 780 \stoptyping
 781
 782 So, you even need to include the brackets!
 783
 784 Although we started from a merge of \PDFTEX\ and \ALEPH, by now the code base as
 785 well as functionality has diverted from those parents. Here we show the options
 786 that can be passed to the extensions.
 787
 788 \starttexsyntax
 789 \pdfextension literal
 790     [ direct | page | raw ] { tokens }
 791 \stoptexsyntax
 792
 793 \starttexsyntax
 794 \pdfextension dest
 795     num integer | name { tokens }!crlf
 796     [ fitbh | fitbv | fitb | fith| fitv | fit |
 797       fitr <rule spec> | xyz [ zoom <integer> ]
 798 \stoptexsyntax
 799
 800 \starttexsyntax
 801 \pdfextension annot
 802     reserveobjnum | useobjnum <integer>
 803     { tokens }
 804 \stoptexsyntax
 805
 806 \starttexsyntax
 807 \pdfextension save
 808 \stoptexsyntax
 809
 810 \starttexsyntax
 811 \pdfextension restore
 812 \stoptexsyntax
 813
 814 \starttexsyntax
 815 \pdfextension setmatrix
 816     { tokens }
 817 \stoptexsyntax
 818
 819 \starttexsyntax
 820 [ \immediate ] \pdfextension obj
 821     reserveobjnum
 822 \stoptexsyntax
 823
 824 \starttexsyntax
 825 [ \immediate ] \pdfextension obj
 826     [ useobjnum <integer> ]
 827     [ uncompressed ]
 828     [ stream  [ attr { tokens } ] ]
 829     [ file ]
 830     { tokens }
 831 \stoptexsyntax
 832
 833 \starttexsyntax
 834 \pdfextension refobj
 835     <integer>
 836 \stoptexsyntax
 837
 838 \starttexsyntax
 839 \pdfextension colorstack
 840     <integer>
 841     set { tokens } | push { tokens } | pop | current
 842 \stoptexsyntax
 843
 844 \starttexsyntax
 845 \pdfextension startlink
 846     [ attr { tokens } ]
 847     user { tokens } | goto | thread
 848     [ file { tokens } ]
 849     [ page <integer> { tokens } | name { tokens } | num  integer ]
 850     [ newwindow  | nonewwindow ]
 851 \stoptexsyntax
 852
 853 \starttexsyntax
 854 \pdfextension endlink
 855 \stoptexsyntax
 856
 857 \starttexsyntax
 858 \pdfextension startthread
 859     num <integer> | name { tokens }
 860 \stoptexsyntax
 861
 862 \starttexsyntax
 863 \pdfextension endthread
 864 \stoptexsyntax
 865
 866 \starttexsyntax
 867 \pdfextension thread
 868     num <integer> | name { tokens }
 869 \stoptexsyntax
 870
 871 \starttexsyntax
 872 \pdfextension outline
 873     [ attr { tokens } ]
 874     [ useobjnum <integer> ]
 875     [ count <integer> ]
 876     { tokens }
 877 \stoptexsyntax
 878
 879 \starttexsyntax
 880 \pdfextension glyphtounicode
 881     { tokens }
 882     { tokens }
 883 \stoptexsyntax
 884
 885 \starttexsyntax
 886 \pdfextension catalog
 887     { tokens }
 888     [ openaction
 889       user { tokens } | goto | thread
 890       [ file { tokens } ]
 891       [ page <integer> { tokens } | name { tokens } | num <integer> ]
 892       [ newwindow  | nonewwindow ] ]
 893 \stoptexsyntax
 894
 895 \starttexsyntax
 896 \pdfextension fontattr
 897     <integer>
 898     {tokens}
 899 \stoptexsyntax
 900
 901 \starttexsyntax
 902 \pdfextension mapfile
 903     {tokens}
 904 \stoptexsyntax
 905
 906 \starttexsyntax
 907 \pdfextension mapline
 908     {tokens}
 909 \stoptexsyntax
 910
 911 \starttexsyntax
 912 \pdfextension includechars
 913     {tokens}
 914 \stoptexsyntax
 915
 916 \starttexsyntax
 917 \pdfextension info
 918     {tokens}
 919 \stoptexsyntax
 920
 921 \starttexsyntax
 922 \pdfextension names
 923     {tokens}
 924 \stoptexsyntax
 925
 926 \starttexsyntax
 927 \pdfextension trailer
 928     {tokens}
 929 \stoptexsyntax
 930
 931 \stopsection
 932
 933 \startsection[title=Directions]
 934
 935 The directional model in \LUATEX\ is inherited from \OMEGA|/|\ALEPH\ but we tried
 936 to improve it a bit. At some point we played with recovery of modes but that was
 937 disabled later on when we found that it interfered with nested directions. That
 938 itself had as side effect that the node list was no longer balanced with respect
 939 to directional nodes which in turn can give side effects when a series of dir
 940 changes happens without grouping.
 941
 942 The current (0.97 onward) approach is that we again make the list balanced but
 943 try to avoid some side effects. What happens is quite intuitive if we forget
 944 about spaces (turned into glue) but even there what happens makes sense if you
 945 look at it in detail. However that logic makes in|-|group switching kind of
 946 useless when no proper nested grouping is used: switching from right to left
 947 several times nested, results in spacing ending up after each other due to nested
 948 mirroring. Of course a sane macro package will manage this for the user but here
 949 we are discussing the low level dir injection.
 950
 951 This is what happens:
 952
 953 \starttyping
 954 \textdir TRT nur {\textdir TLT run \textdir TRT NUR} nur
 955 \stoptyping
 956
 957 This becomes stepwise:
 958
 959 \startnarrower
 960 \starttyping
 961 injected: [+TRT]nur {[+TLT]run [+TRT]NUR} nur
 962 balanced: [+TRT]nur {[+TLT]run [-TLT][+TRT]NUR[-TRT]} nur[-TRT]
 963 result  : run {RUNrun } run
 964 \stoptyping
 965 \stopnarrower
 966
 967 And this:
 968
 969 \starttyping
 970 \textdir TRT nur {nur \textdir TLT run \textdir TRT NUR} nur
 971 \stoptyping
 972
 973 becomes:
 974
 975 \startnarrower
 976 \starttyping
 977 injected: [+TRT]nur {nur [+TLT]run [+TRT]NUR} nur
 978 balanced: [+TRT]nur {nur [+TLT]run [-TLT][+TRT]NUR[-TRT]} nur[-TRT]
 979 result  : run {run RUNrun } run
 980 \stoptyping
 981 \stopnarrower
 982
 983 Now, in the following examples watch where we put the braces:
 984
 985 \startbuffer
 986 \textdir TRT nur {{\textdir TLT run} {\textdir TRT NUR}} nur
 987 \stopbuffer
 988
 989 \typebuffer
 990
 991 This becomes:
 992
 993 \startnarrower
 994 \getbuffer
 995 \stopnarrower
 996
 997 Compare this to:
 998
 999 \startbuffer
1000 \textdir TRT nur {{\textdir TLT run }{\textdir TRT NUR}} nur
1001 \stopbuffer
1002
1003 \typebuffer
1004
1005 Which renders as:
1006
1007 \startnarrower
1008 \getbuffer
1009 \stopnarrower
1010
1011 So how do we deal with the next?
1012
1013 \startbuffer
1014 \def\ltr{\textdir TLT\relax}
1015 \def\rtl{\textdir TRT\relax}
1016
1017 run {\rtl nur {\ltr run \rtl NUR \ltr run \rtl NUR} nur}
1018 run {\ltr run {\rtl nur \ltr RUN \rtl nur \ltr RUN} run}
1019 \stopbuffer
1020
1021 \typebuffer
1022
1023 It gets typeset as:
1024
1025 \startnarrower
1026 \startlines
1027 \getbuffer
1028 \stoplines
1029 \stopnarrower
1030
1031 We could define the two helpers to look back, pick up a skip, remove it and
1032 inject it after the dir node. But that way we loose the subtype information that
1033 for some applications can be handy to be kept as|-|is. This is why we now have a
1034 variant of \type {\textdir} which injects the balanced node before the skip.
1035 Instead of the previous definition we can use:
1036
1037 \startbuffer[def]
1038 \def\ltr{\linedir TLT\relax}
1039 \def\rtl{\linedir TRT\relax}
1040 \stopbuffer
1041
1042 \typebuffer[def]
1043
1044 and this time:
1045
1046 \startbuffer[txt]
1047 run {\rtl nur {\ltr run \rtl NUR \ltr run \rtl NUR} nur}
1048 run {\ltr run {\rtl nur \ltr RUN \rtl nur \ltr RUN} run}
1049 \stopbuffer
1050
1051 \typebuffer[txt]
1052
1053 comes out as a properly spaced:
1054
1055 \startnarrower
1056 \startlines
1057 \getbuffer[def,txt]
1058 \stoplines
1059 \stopnarrower
1060
1061 Anything more complex that this, like combination of skips and penalties, or
1062 kerns, should be handled in the input or macro package because there is no way we
1063 can predict the expected behaviour. In fact, the \type {\linedir} is just a
1064 convenience extra which could also have been implemented using node list parsing.
1065
1066 Another adaptation to the \ALEPH\ directional model is control over shapes driven
1067 by \type {\hangindent} and \type {\parshape}. This is controlled by a new parameter
1068 \type {\shapemode}:
1069
1070 \starttabulate[|cTB|c|]
1071 \NC   \NC \bf \type {\hangindent} \NC \bf \type {\parshape} \NC \NR
1072 \NC 0 \NC  normal                 \NC normal                \NC \NR
1073 \NC 1 \NC  mirrored               \NC normal                \NC \NR
1074 \NC 2 \NC  normal                 \NC mirrored              \NC \NR
1075 \NC 3 \NC  mirrored               \NC mirrored              \NC \NR
1076 \stoptabulate
1077
1078 The value is reset to zero (like \type {\hangindent} and \type {\parshape})
1079 after the paragraph is done with. You can use negative values to preven t
1080 this.
1081
1082 In \in {figure} [fig:shapemode] a few examples are given.
1083
1084 \startplacefigure[reference=fig:shapemode,title={The effect of \type {shapemode}.}]
1085     \startcombination[2*3]
1086         {\ruledvbox \bgroup \setuptolerance[verytolerant]
1087             \hsize .45\textwidth \switchtobodyfont[6pt]
1088                 \pardir TLT \textdir TLT
1089                 \hangindent 40pt \hangafter -3
1090                 \leftskip10pt \input tufte \par
1091          \egroup} {TLT: hangindent}
1092         {\ruledvbox \bgroup \setuptolerance[verytolerant]
1093             \hsize .45\textwidth \switchtobodyfont[6pt]
1094             \pardir TLT \textdir TLT
1095             \parshape 4 0pt .8\hsize 10pt .8\hsize 20pt .8\hsize 0pt \hsize
1096             \input tufte \par
1097          \egroup} {TLT: parshape}
1098         {\ruledvbox \bgroup \setuptolerance[verytolerant]
1099             \hsize .45\textwidth \switchtobodyfont[6pt]
1100             \pardir TRT \textdir TRT
1101             \hangindent 40pt \hangafter -3
1102             \leftskip10pt \input tufte \par
1103          \egroup} {TRT: hangindent mode 0}
1104         {\ruledvbox \bgroup \setuptolerance[verytolerant]
1105             \hsize .45\textwidth \switchtobodyfont[6pt]
1106             \pardir TRT \textdir TRT
1107             \parshape 4 0pt .8\hsize 10pt .8\hsize 20pt .8\hsize 0pt \hsize
1108             \input tufte \par
1109          \egroup} {TRT: parshape mode 0}
1110         {\ruledvbox \bgroup \setuptolerance[verytolerant]
1111             \hsize .45\textwidth \switchtobodyfont[6pt]
1112             \shapemode=3
1113             \pardir TRT \textdir TRT
1114             \hangindent 40pt \hangafter -3
1115             \leftskip10pt \input tufte \par
1116          \egroup} {TRT: hangindent mode 1 & 3}
1117         {\ruledvbox \bgroup \setuptolerance[verytolerant]
1118             \hsize .45\textwidth \switchtobodyfont[6pt]
1119             \shapemode=3
1120             \pardir TRT \textdir TRT
1121             \parshape 4 0pt .8\hsize 10pt .8\hsize 20pt .8\hsize 0pt \hsize
1122             \input tufte \par
1123          \egroup} {TRT: parshape mode 2 & 3}
1124     \stopcombination
1125 \stopplacefigure
1126
1127 \stopsection
1128
1129 \startsection[title=Implementation notes]
1130
1131 \startsubsection[title=Memory allocation]
1132
1133 The single internal memory heap that traditional \TEX\ used for tokens and nodes
1134 is split into two separate arrays. Each of these will grow dynamically when
1135 needed.
1136
1137 The \type {texmf.cnf} settings related to main memory are no longer used (these
1138 are: \type {main_memory}, \type {mem_bot}, \type {extra_mem_top} and \type
1139 {extra_mem_bot}). \quote {Out of main memory} errors can still occur, but the
1140 limiting factor is now the amount of RAM in your system, not a predefined limit.
1141
1142 Also, the memory (de)allocation routines for nodes are completely rewritten. The
1143 relevant code now lives in the C file \type {texnode.c}, and basically uses a
1144 dozen or so \quote {avail} lists instead of a doubly|-|linked model. An extra
1145 function layer is added so that the code can ask for nodes by type instead of
1146 directly requisitioning a certain amount of memory words.
1147
1148 Because of the split into two arrays and the resulting differences in the data
1149 structures, some of the macros have been duplicated. For instance, there are now
1150 \type {vlink} and \type {vinfo} as well as \type {token_link} and \type
1151 {token_info}. All access to the variable memory array is now hidden behind a
1152 macro called \type {vmem}. We mention this because using the \TEX book as
1153 reference is still quite valid but not for memory related details. Another
1154 significate detail is that we have double linked node lists and that some nodes
1155 carry more data.
1156
1157 The implementation of the growth of two arrays (via reallocation) introduces a
1158 potential pitfall: the memory arrays should never be used as the left hand side
1159 of a statement that can modify the array in question. Details like this are
1160 of no concern to users.
1161
1162 The input line buffer and pool size are now also reallocated when needed, and the
1163 \type {texmf.cnf} settings \type {buf_size} and \type {pool_size} are silently
1164 ignored.
1165
1166 \stopsubsection
1167
1168 \startsubsection[title=Sparse arrays]
1169
1170 The \type {\mathcode}, \type {\delcode}, \type {\catcode}, \type {\sfcode}, \type
1171 {\lccode} and \type {\uccode} (and the new \type {\hjcode}) tables are now sparse
1172 arrays that are implemented in~\CCODE. They are no longer part of the \TEX\
1173 \quote {equivalence table} and because each had 1.1 million entries with a few
1174 memory words each, this makes a major difference in memory usage.
1175
1176 The \type {\catcode}, \type {\sfcode}, \type {\lccode}, \type {\uccode} and \type
1177 {\hjcode} assignments do not yet show up when using the \ETEX\ tracing routines
1178 \type {\tracingassigns} and \type {\tracingrestores}.
1179
1180 A side|-|effect of the current implementation is that \type {\global} is now more
1181 expensive in terms of processing than non|-|global assignments.
1182
1183 The glyph ids within a font are also managed by means of a sparse array as glyph
1184 ids can go up to index $2^{21}-1$.
1185
1186 \stopsubsection
1187
1188 \startsubsection[title=Simple single-character csnames]
1189
1190 Single|-|character commands are no longer treated specially in the internals,
1191 they are stored in the hash just like the multiletter csnames.
1192
1193 The code that displays control sequences explicitly checks if the length is one
1194 when it has to decide whether or not to add a trailing space.
1195
1196 Active characters are internally implemented as a special type of multi|-|letter
1197 control sequences that uses a prefix that is otherwise impossible to obtain.
1198
1199 \stopsubsection
1200
1201 \startsubsection[title=Compressed format]
1202
1203 The format is passed through \type {zlib}, allowing it to shrink to roughly half
1204 of the size it would have had in uncompressed form. This takes a bit more \CPU\
1205 cycles but much less disk \IO, so it should still be faster.
1206
1207 \stopsubsection
1208
1209 \startsubsection[title=Binary file reading]
1210
1211 All of the internal code is changed in such a way that if one of the \type
1212 {read_xxx_file} callbacks is not set, then the file is read by a \CCODE\ function
1213 using basically the same convention as the callback: a single read into a buffer
1214 big enough to hold the entire file contents. While this uses more memory than the
1215 previous code (that mostly used \type {getc} calls), it can be quite a bit faster
1216 (depending on your \IO\ subsystem).
1217
1218 \stopsubsection
1219
1220 \stopsection
1221
1222 \stopchapter
1223
1224 \stopcomponent