| 1 |
% language=uk |
| 2 |
|
| 3 |
\environment luatex-style |
| 4 |
|
| 5 |
\startcomponent luatex-introduction |
| 6 |
|
| 7 |
\startchapter[title=Introduction] |
| 8 |
|
| 9 |
This is the reference manual of \LUATEX. We don't claim it is complete and we |
| 10 |
assume that the reader knows about \TEX\ as described in \quotation {The \TEX\ |
| 11 |
Book}, the \quotation {\ETEX\ manual}, the \quotation {\PDFTEX\ manual}, etc. |
| 12 |
Additional reference material is published in journals of user groups and |
| 13 |
\CONTEXT\ related documentation. |
| 14 |
|
| 15 |
It took about a decade to reach stable version 1.0, but for good reason. |
| 16 |
Successive versions brought new functionality, more control, some cleanup of |
| 17 |
internals. Experimental features evolved into stable ones or were dropped. |
| 18 |
Already quite early \LUATEX\ could be used for production and it was used on a |
| 19 |
daily basis by the authors. Successive versions sometimes demanded an adaption to |
| 20 |
the \LUA\ interfacing, but the concepts were unchanged. The current version can |
| 21 |
be considered stable in functionality and there will be no fundamental changes. |
| 22 |
Of course we then can decide to move towards version 2.00 with different |
| 23 |
properties. |
| 24 |
|
| 25 |
Don't expect \LUATEX\ to behave the same as \PDFTEX ! Although the core |
| 26 |
functionality of that 8 bit engine was starting point, it has been combined with |
| 27 |
the directional support of \OMEGA\ (\ALEPH). But, \LUATEX\ can behave different |
| 28 |
due to its wide (32 bit) characters, many registers and large memory support. The |
| 29 |
\PDF\ code produced differs from \PDFTEX\ but users will normally not notice |
| 30 |
that. There is native \UTF\ input, support for large (more than 8 bit) fonts, and |
| 31 |
the math machinery is tuned for \OPENTYPE\ math. There is support for directional |
| 32 |
typesetting too. The log output can differ from other engines and will likely |
| 33 |
differ more as we move forward. When you run plain \TEX\ for sure \LUATEX\ runs |
| 34 |
slower than \PDFTEX\ but when you run for instance \CONTEXT\ \MKIV\ in many cases |
| 35 |
it runs faster, especially when you have a bit more complex documents or input. |
| 36 |
Anyway, 32 bit all||over combined with more features has a price, but on a modern |
| 37 |
machine this is no real problem. |
| 38 |
|
| 39 |
Testing is done with \CONTEXT, but \LUATEX\ should work fine with other macro |
| 40 |
packages too. For that purpose we provide generic font handlers that are mostly |
| 41 |
the same as used in \CONTEXT. Discussing specific implementations is beyond this |
| 42 |
manual. Even when we keep \LUATEX\ lean and mean, we already have enough to |
| 43 |
discuss here. |
| 44 |
|
| 45 |
\LUATEX\ consists of a number of interrelated but (still) distinguishable parts. |
| 46 |
The organization of the source code is adapted so that it can glue all these |
| 47 |
components together. We continue cleaning up side effects of the accumulated |
| 48 |
code in \TEX\ engines (especially code that is not needed any longer). |
| 49 |
|
| 50 |
\startitemize [unpacked] |
| 51 |
\startitem |
| 52 |
We started out with most of \PDFTEX\ version 1.40.9. The code base was |
| 53 |
converted to \CCODE\ and split in modules. Experimental features were |
| 54 |
removed and utility macros are not inherited because their functionality |
| 55 |
can be programmed in \LUA. The number of backend interface commands has |
| 56 |
been reduced to a few. The so called extensions are separated from the |
| 57 |
core (which we try to keep close to the original \TEX\ core). Some |
| 58 |
mechanisms like expansion and protrusion can behave different from the |
| 59 |
original due to some cleanup and optimization. Some whatsit based |
| 60 |
functionality (image support and reusable content) is now core |
| 61 |
functionality. We don't stay in sync with \PDFTEX\ development. |
| 62 |
\stopitem |
| 63 |
\startitem |
| 64 |
The direction model from \ALEPH\ RC4 (which is derived from \OMEGA) is |
| 65 |
included. The related primitives are part of core \LUATEX\ but at the |
| 66 |
node level directional support is no longer based on so called whatsits |
| 67 |
but on real nodes with relevant properties. The number of directions is |
| 68 |
limited to the useful set and the backend has been made direction aware. |
| 69 |
\stopitem |
| 70 |
\startitem |
| 71 |
Neither \ALEPH's I/O translation processes, nor tcx files, nor \ENCTEX\ |
| 72 |
are available. These encoding|-|related functions are superseded by a |
| 73 |
\LUA|-|based solution (reader callbacks). In a similar fashion all file |
| 74 |
\IO\ can be intercepted. |
| 75 |
\stopitem |
| 76 |
\startitem |
| 77 |
We currently use \LUA\ 5.3.*. There are few \LUA\ libraries that we |
| 78 |
consider part of the core \LUA\ machinery, for instance \type {lpeg}. |
| 79 |
There are additional \LUA\ libraries that interface to the internals of |
| 80 |
\TEX. We also keep the \LUA\ 5.2 \type {bit32} library around. |
| 81 |
\stopitem |
| 82 |
\startitem |
| 83 |
There are various \TEX\ extensions but only those that cannot be done |
| 84 |
using the \LUA\ interfaces. The math machinery often has two code paths: |
| 85 |
one traditional and the other more suitable for wide \OPENTYPE\ fonts. Here |
| 86 |
we follow the \MICROSOFT\ specifications as much as possible. Some math |
| 87 |
functionality has been opened up a bit so that users have more control. |
| 88 |
\stopitem |
| 89 |
\startitem |
| 90 |
The fontloader uses parts of \FONTFORGE\ 2008.11.17 combined with |
| 91 |
additional code specific for usage in a \TEX\ engine. We try to minimize |
| 92 |
specific font support to what \TEX\ needs: character references and |
| 93 |
dimensions and delegate everything else to \LUA. That way we keep \TEX\ |
| 94 |
open for extensions without touching the core. In order to minimize |
| 95 |
dependencies at some point we may decide to make this an optional |
| 96 |
library. |
| 97 |
\stopitem |
| 98 |
\startitem |
| 99 |
The \METAPOST\ library is integral part of \LUATEX. This gives \TEX\ some |
| 100 |
graphical capabilities using a relative high speed graphical subsystem. |
| 101 |
Again \LUA\ is used as glue between the frontend and backend. Further |
| 102 |
development of \METAPOST\ is closely related to \LUATEX. |
| 103 |
\stopitem |
| 104 |
\startitem |
| 105 |
The virtual font technology that comes with \TEX\ has been integrated |
| 106 |
into the font machinery in a way that permits creating virtual fonts |
| 107 |
at runtime. Because \LUATEX\ can also act as a \LUA\ interpreter this |
| 108 |
means that a complete \TEX\ workflow can be built without the need for |
| 109 |
additional programs. |
| 110 |
\stopitem |
| 111 |
\startitem |
| 112 |
The versions starting from 1.09 no longer use the poppler library for |
| 113 |
inclusion but a lightweight dedicated one. This removes a dependency but |
| 114 |
also makes the inclusion code of \LUATEX\ different from \PDFTEX. In fact |
| 115 |
it was already much different due to the \LUA\ image interfacing. |
| 116 |
\stopitem |
| 117 |
\stopitemize |
| 118 |
|
| 119 |
We try to keep upcoming versions compatible but intermediate releases can contain |
| 120 |
experimental features. A general rule is that versions that end up on \TEXLIVE\ |
| 121 |
and|/|or are released around \CONTEXT\ meetings are stable. Any version between |
| 122 |
the yearly \TEXLIVE\ releases are to be considered beta and in the repository end |
| 123 |
up as trunk releases. We have an experimental branch that we use for development |
| 124 |
but there is no support for any of its experimental features. Intermediate |
| 125 |
releases (from trunk) are normally available via the \CONTEXT\ distribution |
| 126 |
channels (the garden and so called minimals). |
| 127 |
|
| 128 |
Version 1.10 is more or less an endpoint in development: this is what you get. |
| 129 |
Because not only \CONTEXT, that we can adapt rather easily, uses \LUATEX, we |
| 130 |
cannot change fundamentals without unforeseen consequences. By now it has been |
| 131 |
proven that \LUA\ can be used to extend the core functionality so there is no |
| 132 |
need to add more, and definitely no hard coded solutions for (not so) common |
| 133 |
problems. Of course there will be bug fixes, maybe some optimization, and there |
| 134 |
might even be some additions or non|-|intrusive improvements, but only after |
| 135 |
testing outside the stable release. After all, the binary is already more than |
| 136 |
large enough and there is not that much to gain. |
| 137 |
|
| 138 |
You might find \LUA\ helpers that are not yet documented. These are considered |
| 139 |
experimental, although when you encounter them in a \CONTEXT\ version that has |
| 140 |
been around for a while you can assume that they will stay. Of course it can just |
| 141 |
be that we forgot to document them yet. |
| 142 |
|
| 143 |
A manual like this is not really meant as tutorial, for that we refer to |
| 144 |
documents that ship with \CONTEXT, articles, etc. It is also never complete |
| 145 |
enough for all readers. We try to keep up but the reader needs to realize that |
| 146 |
it's all volunteer work done in spare time. And for sure, complaining about a bad |
| 147 |
manual or crappy documentation will not really motivate us to spend more time on |
| 148 |
it. That being said, we hope that this document is useful. |
| 149 |
|
| 150 |
\blank[big] |
| 151 |
|
| 152 |
\testpage[5] |
| 153 |
|
| 154 |
\startlines |
| 155 |
Hans Hagen |
| 156 |
Harmut Henkel |
| 157 |
Taco Hoekwater |
| 158 |
Luigi Scarso |
| 159 |
\stoplines |
| 160 |
|
| 161 |
\blank[3*big] |
| 162 |
|
| 163 |
\starttabulate[|||] |
| 164 |
\NC Version \EQ \currentdate \NC \NR |
| 165 |
\NC \LUATEX \EQ \cldcontext{LUATEXENGINE} % |
| 166 |
\cldcontext{"\letterpercent 0.2f",LUATEXVERSION} / % |
| 167 |
\cldcontext{LUATEXFUNCTIONALITY} |
| 168 |
\NC \NR |
| 169 |
\NC \CONTEXT \EQ MkIV \contextversion \NC \NR |
| 170 |
\stoptabulate |
| 171 |
|
| 172 |
\stopchapter |
| 173 |
|
| 174 |
\stopcomponent |