Source Browser ?

1% language=us engine=luatex runpath=texruns:manuals/luatex
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
13This is a reference manual, not a tutorial. This means that we discuss changes
14relative to traditional \TEX\ and also present new functionality. As a consequence
15we will refer to concepts that we assume to be known or that might be explained
16later.
17
18The average user doesn't need to know much about what is in this manual. For
19instance fonts and languages are normally dealt with in the macro package that
20you use. Messing around with node lists is also often not really needed at the
21user level. If you do mess around, you'd better know what you're dealing with.
22Reading \quotation {The \TEX\ Book} by Donald Knuth is a good investment of time
23then also because it's good to know where it all started. A more summarizing
24overview is given by \quotation {\TEX\ by Topic} by Victor Eijkhout. You might
25want to peek in \quotation {The \ETEX\ manual} and documentation about \PDFTEX.
26
27But \unknown\ if you're here because of \LUA, then all you need to know is that
28you can call it from within a run. The macro package that you use probably will
29provide a few wrapper mechanisms but the basic \lpr {directlua} command that
30does the job is:
31
32\starttyping
33\directlua{tex.print("Hi there")}
34\stoptyping
35
36You can put code between curly braces but if it's a lot you can also put it in a
37file and load that file with the usual \LUA\ commands.
38
39If you still decide to read on, then it's good to know what nodes are, so we do a
40quick introduction here. If you input this text:
41
42\starttyping
43Hi There
44\stoptyping
45
46eventually we will get a linked lists of nodes, which in \ASCII\ art looks like:
47
48\starttyping
49H <=> i <=> [glue] <=> T <=> h <=> e <=> r <=> e
50\stoptyping
51
52When 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
58Each character becomes a so called glyph node, a record with properties like the
59current font, the character code and the current language. Spaces become glue
60nodes. There are many node types that we will discuss later. Each node points
61back to a previous node or next node, given that these exist.
62
63It's also good to know beforehand that \TEX\ is basically centered around
64creating paragraphs and pages. The par builder takes a list and breaks it into
65lines. We turn horizontal material into vertical. Lines are so called boxes and
66can be separated by glue, penalties and more. The page builder accumulates lines
67and when feasible triggers an output routine that will take the list so far.
68Constructing the actual page is not part of \TEX\ but done using primitives that
69permit manipulation of boxes. The result is handled back to \TEX\ and flushed to
70a (often \PDF) file.
71
72The \LUATEX\ engine provides hooks for \LUA\ code at nearly every reasonable
73point in the process: collecting content, hyphenating, applying font features,
74breaking into lines, etc. This means that you can overload \TEX's natural
75behaviour, which still is the benchmark. When we refer to \quote {callbacks} we
76means these hooks.
77
78Where plain \TEX\ is basically a basic framework for writing a specific style,
79macro packages like \CONTEXT\ and \LATEX\ provide the user a whole lot of
80additional tools to make documents look good. They hide the dirty details of font
81management, language demands, turning structure into typeset results, wrapping
82pages, including images, and so on. You should be aware of the fact that when you
83hook in your own code to manipulate lists, this can interfere with the macro
84package that you use.
85
86When you read about nodes in the following chapters it's good to keep in mind their
87commands 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
106For now this should be enough to enable you to understand the next chapters.
107
108\stopchapter
109
110\stopcomponent
111