updated reference manual for luatex 1.09.2

git-svn-id: svn://tug.org/texlive/trunk@49615 c570f23f-e606-0410-a88d-b1316a301751

1 files changed, 110 insertions, 0 deletions

diff --git a/Master/texmf-dist/doc/luatex/base/luatex-preamble.tex b/Master/texmf-dist/doc/luatex/base/luatex-preamble.tex
new file mode 100644
index 00000000000..635ff4134ba
--- /dev/null
+++ b/Master/texmf-dist/doc/luatex/base/luatex-preamble.tex
@@ -0,0 +1,110 @@
+% language=uk

+

+\environment luatex-style

+

+\startcomponent luatex-preamble

+

+\startchapter[reference=preamble,title={Preamble}]

+

+\topicindex{nodes}

+\topicindex{boxes}

+\topicindex{\LUA}

+

+This is a reference manual, not a tutorial. This means that we discuss changes

+relative to traditonal \TEX\ and also present new functionality. As a consequence

+we will refer to concepts that we assume to be known or that might be explained

+later.

+

+The average user doesn't need to know much about what is in this manual. For

+instance fonts and languages are normally dealt with in the macro package that

+you use. Messing around with node lists is also often not really needed at the

+user level. If you do mess around, you'd better know what you're dealing with.

+Reading \quotation {The \TEX\ Book} by Donald Knuth is a good investment of time

+then also because it's good to know where it all started. A more summarizing

+overview is given by \quotation {\TEX\ by Topic} by Victor Eijkhout. You might

+want to peek in \quotation {The \ETEX\ manual} and documentation about \PDFTEX.

+

+But \unknown\ if you're here because of \LUA, then all you need to know is that

+you can call it from within a run. The macro package that you use probably will

+provide a few wrapper mechanisms but the basic \lpr {directlua} command that

+does the job is:

+

+\starttyping

+\directlua{tex.print("Hi there")}

+\stoptyping

+

+You can put code between curly braces but if it's a lot you can also put it in a

+file and load that file with the usual \LUA\ commands.

+

+If you still decide to read on, then it's good to know what nodes are, so we do a

+quick introduction here. If you input this text:

+

+\starttyping

+Hi There

+\stoptyping

+

+eventually we will get a linked lists of nodes, which in \ASCII\ art looks like:

+

+\starttyping

+H <=> i <=> [glue] <=> T <=> h <=> e <=> r <=> e

+\stoptyping

+

+When we have a paragraph, we actually get something:

+

+\starttyping

+[localpar] <=> H <=> i <=> [glue] <=> T <=> h <=> e <=> r <=> e <=> [glue]

+\stoptyping

+

+Each character becomes a so called glyph node, a record with properties like the

+current font, the character code and the current language. Spaces become glue

+nodes. There are many node types that we will discuss later. Each node points

+back to a previous node or next node, given that these exist.

+

+It's also good to know beforehand that \TEX\ is basically centered around

+creating paragraphs and pages. The par builder takes a list and breaks it into

+lines. We turn horizontal material into vertical. Lines are so called boxes and

+can be separated by glue, penalties and more. The page builder accumulates lines

+and when feasible triggers an output routine that will take the list so far.

+Constructing the actual page is not part of \TEX\ but done using primitives that

+permit manipulation of boxes. The result is handled back to \TEX\ and flushed to

+a (often \PDF) file.

+

+The \LUATEX\ engine provides hooks for \LUA\ code at nearly every reasonable

+point in the process: collecting content, hyphenating, applying font features,

+breaking into lines, etc. This means that you can overload \TEX's natural

+behaviour, which still is the benchmark. When we refer to \quote {callbacks} we

+means these hooks.

+

+Where plain \TEX\ is basically a basic framework for writing a specific style,

+macro packages like \CONTEXT\ and \LATEX\ provide the user a whole lot of

+additional tools to make documents look good. They hide the dirty details of font

+management, language demands, turning structure into typeset results, wrapping

+pages, including images, and so on. You should be aware of the fact that when you

+hook in your own code to manipulate lists, this can interfere with the macro

+package that you use.

+

+When you read about nodes in the following chapters it's good to keep in mind their

+commands that relate to then. Here are a few:

+

+\starttabulate[|l|l|p|]

+\DB command                \BC node          \BC explanation \NC \NR

+\TB

+\NC \prm {hbox}            \NC \nod {hlist} \NC horizontal box \NC \NR

+\NC \prm {vbox}            \NC \nod {vlist} \NC vertical box with the baseline at the bottom \NC \NR

+\NC \prm {vtop}            \NC \nod {vlist} \NC vertical box with the baseline at the top \NC \NR

+\NC \prm {hskip}           \NC \nod {glue}  \NC horizontal skip with optional stretch and shrink \NC \NR

+\NC \prm {vskip}           \NC \nod {glue}  \NC vertical skip with optional stretch and shrink \NC \NR

+\NC \prm {kern}            \NC \nod {kern}  \NC horizontal or vertical fixed skip \NC \NR

+\NC \prm {discretionary}   \NC \nod {disc}  \NC hyphenation point (pre, post, replace) \NC \NR

+\NC \prm {char}            \NC \nod {glyph} \NC a character \NC \NR

+\NC \prm {hrule}           \NC \nod {rule}  \NC a horizontal rule \NC \NR

+\NC \prm {vrule}           \NC \nod {rule}  \NC a vertical rule \NC \NR

+\NC \prm {textdir(ection)} \NC \nod {dir}   \NC a change in text direction \NC \NR

+\LL

+\stoptabulate

+

+For now this should be enough to enable you to understand the next chapters.

+

+\stopchapter

+

+\stopcomponent