Debian Codegraph @

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

raw
1 % language=uk
2
3 \environment luatex-style
4
5 \startcomponent luatex-preamble
6
7 \startchapter[reference=preamble,title={Preamble}]
8
9 \topicindex{nodes}
10 \topicindex{boxes}
11 \topicindex{\LUA}
12
13 This is a reference manual, not a tutorial. This means that we discuss changes
14 relative to traditional \TEX\ and also present new functionality. As a consequence
15 we will refer to concepts that we assume to be known or that might be explained
16 later.
17
18 The average user doesn't need to know much about what is in this manual. For
19 instance fonts and languages are normally dealt with in the macro package that
20 you use. Messing around with node lists is also often not really needed at the
21 user level. If you do mess around, you'd better know what you're dealing with.
22 Reading \quotation {The \TEX\ Book} by Donald Knuth is a good investment of time
23 then also because it's good to know where it all started. A more summarizing
24 overview is given by \quotation {\TEX\ by Topic} by Victor Eijkhout. You might
25 want to peek in \quotation {The \ETEX\ manual} and documentation about \PDFTEX.
26
27 But \unknown\ if you're here because of \LUA, then all you need to know is that
28 you can call it from within a run. The macro package that you use probably will
29 provide a few wrapper mechanisms but the basic \lpr {directlua} command that
30 does the job is:
31
32 \starttyping
33 \directlua{tex.print("Hi there")}
34 \stoptyping
35
36 You can put code between curly braces but if it's a lot you can also put it in a
37 file and load that file with the usual \LUA\ commands.
38
39 If you still decide to read on, then it's good to know what nodes are, so we do a
40 quick introduction here. If you input this text:
41
42 \starttyping
43 Hi There
44 \stoptyping
45
46 eventually we will get a linked lists of nodes, which in \ASCII\ art looks like:
47
48 \starttyping
49 H <=> i <=> [glue] <=> T <=> h <=> e <=> r <=> e
50 \stoptyping
51
52 When we have a paragraph, we actually get something:
53
54 \starttyping
55 [localpar] <=> H <=> i <=> [glue] <=> T <=> h <=> e <=> r <=> e <=> [glue]
56 \stoptyping
57
58 Each character becomes a so called glyph node, a record with properties like the
59 current font, the character code and the current language. Spaces become glue
60 nodes. There are many node types that we will discuss later. Each node points
61 back to a previous node or next node, given that these exist.
62
63 It's also good to know beforehand that \TEX\ is basically centered around
64 creating paragraphs and pages. The par builder takes a list and breaks it into
65 lines. We turn horizontal material into vertical. Lines are so called boxes and
66 can be separated by glue, penalties and more. The page builder accumulates lines
67 and when feasible triggers an output routine that will take the list so far.
68 Constructing the actual page is not part of \TEX\ but done using primitives that
69 permit manipulation of boxes. The result is handled back to \TEX\ and flushed to
70 a (often \PDF) file.
71
72 The \LUATEX\ engine provides hooks for \LUA\ code at nearly every reasonable
73 point in the process: collecting content, hyphenating, applying font features,
74 breaking into lines, etc. This means that you can overload \TEX's natural
75 behaviour, which still is the benchmark. When we refer to \quote {callbacks} we
76 means these hooks.
77
78 Where plain \TEX\ is basically a basic framework for writing a specific style,
79 macro packages like \CONTEXT\ and \LATEX\ provide the user a whole lot of
80 additional tools to make documents look good. They hide the dirty details of font
81 management, language demands, turning structure into typeset results, wrapping
82 pages, including images, and so on. You should be aware of the fact that when you
83 hook in your own code to manipulate lists, this can interfere with the macro
84 package that you use.
85
86 When you read about nodes in the following chapters it's good to keep in mind their
87 commands that relate to then. Here are a few:
88
89 \starttabulate[|l|l|p|]
90 \DB command \BC node \BC explanation \NC \NR
91 \TB
92 \NC \prm {hbox} \NC \nod {hlist} \NC horizontal box \NC \NR
93 \NC \prm {vbox} \NC \nod {vlist} \NC vertical box with the baseline at the bottom \NC \NR
94 \NC \prm {vtop} \NC \nod {vlist} \NC vertical box with the baseline at the top \NC \NR
95 \NC \prm {hskip} \NC \nod {glue} \NC horizontal skip with optional stretch and shrink \NC \NR
96 \NC \prm {vskip} \NC \nod {glue} \NC vertical skip with optional stretch and shrink \NC \NR
97 \NC \prm {kern} \NC \nod {kern} \NC horizontal or vertical fixed skip \NC \NR
98 \NC \prm {discretionary} \NC \nod {disc} \NC hyphenation point (pre, post, replace) \NC \NR
99 \NC \prm {char} \NC \nod {glyph} \NC a character \NC \NR
100 \NC \prm {hrule} \NC \nod {rule} \NC a horizontal rule \NC \NR
101 \NC \prm {vrule} \NC \nod {rule} \NC a vertical rule \NC \NR
102 \NC \prm {textdir(ection)} \NC \nod {dir} \NC a change in text direction \NC \NR
103 \LL
104 \stoptabulate
105
106 For now this should be enough to enable you to understand the next chapters.
107
108 \stopchapter
109
110 \stopcomponent