summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/luatex/base/luatexref-t.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/luatex/base/luatexref-t.tex')
-rw-r--r--Master/texmf-dist/doc/luatex/base/luatexref-t.tex540
1 files changed, 376 insertions, 164 deletions
diff --git a/Master/texmf-dist/doc/luatex/base/luatexref-t.tex b/Master/texmf-dist/doc/luatex/base/luatexref-t.tex
index fab5bc3bbcd..3857585c8cb 100644
--- a/Master/texmf-dist/doc/luatex/base/luatexref-t.tex
+++ b/Master/texmf-dist/doc/luatex/base/luatexref-t.tex
@@ -23,7 +23,7 @@
\setvariables
[document]
- [beta=0.76.0]
+ [beta=0.79.0]
\starttext
@@ -138,7 +138,8 @@ There are three new primitives to test the version of \LUATEX:
the current current value is {\bf\the\luatexversion} \NC\NR
\NC \tex{luatexrevision} \NC the revision number, as in \PDFTEX;
the current value is {\bf\luatexrevision} \NC\NR
-\NC \tex{luatexdatestamp} \NC a combination of the local date and hour when
+\NC \tex{luatexdatestamp} \NC (deprecated in 0.78.1, will be gone in 0.80.0)
+ a combination of the local date and hour when
the current executable was compiled,
the syntax is identical to \tex{luatexrevision};
the value for the executable that generated this
@@ -158,13 +159,6 @@ The official \LUATEX\ version is defined as follows:
minor version and revision, separated by dots.
\stopitemize
-
-Note that the \tex{luatexdatestamp} depends on both the compilation
-time and compilation place of the current executable; it is defined in
-terms of the local time. The purpose of this primitive is solely to be
-an aid in the development process, do not use it for anything besides
-debugging.
-
\section{\UNICODE\ text support}
Text input and output is now considered to be \UNICODE\ text, so
@@ -446,6 +440,43 @@ The behavior documented in the above subsection is considered stable
in the sense that there will not be backward-incompatible changes any
more.
+\subsection{\tex{luafunction}}
+
+The \type {\directlua} commands involves tokenization of its argument (after picking up
+an optional name or number specification). The tokenlist is then converted into a string and
+given to \LUA\ to turn into a function that is called. The overhead is rather small but when
+you use this primitive hundreds or thousands of times, it can become noticeable. For this
+reason there is a variant call available: \type {\luafunction}. This command is used as
+follows:
+
+\starttyping
+\directlua {
+ local t = lua.get_functions_table()
+ t[1] = function() tex.print("!") end
+ t[2] = function() tex.print("?") end
+}
+
+\luafunction1
+\luafunction2
+\stoptyping
+
+Of course the functions can also be defined in a separate file. There is no
+limit on the number of functions apart from normal \LUA\ limitations. Of course there
+is the limitation of no arguments but that would involve parsing and thereby
+give no gain. The function, when called in fact gets one argument, being the index,
+so in:
+
+\starttyping
+\directlua {
+ local t = lua.get_functions_table()
+ t[8] = function(slot) tex.print(slot) end
+}
+\stoptyping
+
+the number \type {8} gets typeset.
+
+
+
\subsection{\tex{latelua}}
\tex{latelua} stores \LUA\ code in a whatsit that will be processed
@@ -493,6 +524,7 @@ is easier to keep the code in a separate file and load it using \LUA's
\directlua { dofile('mysetups.lua')}
\stoptyping
+
\section{New \ETEX\ primitives}
\subsection{\tex{clearmarks}}
@@ -957,7 +989,7 @@ this is used without any patches to the core, which has some side
effects. In particular, Lua's \type{tonumber()} may return values in
scientific notation, thereby confusing the \TEX\ end of things when it
is used as the right-hand side of an assignment to a \type{\dimen}
-or \type{\count}.
+or \type{\count}.
{\bf NOTE:} Also in \LUATEX\ 0.74.0 (this is a change in Lua 5.2),
loading dynamic Lua libraries will fail if there are two Lua libraries
@@ -1027,7 +1059,7 @@ function as normal. This change is new in 0.37.0.
-The \lua{f:read("*line")} and \lua{f:lines()} functions from the io library have
+The \lua{f:read("*line")} and \lua{f:lines()} functions from the io library have
been adjusted so that they are line|-|ending neutral: any of \type{LF}, \type
{CR} or \type{CR+LF} are acceptable line endings.
@@ -1429,10 +1461,6 @@ both \ALEPH's \OVF\ files and traditional Knuthian \VF\ files.
Like \luatex{find_font_file}, but for map files.
-\subsubsection{\luatex{find_cidmap_file} (new in 0.73)}
-
-Like \luatex{find_font_file}, but for cidmap files.
-
\subsubsection{\luatex{find_enc_file}}
Like \luatex{find_font_file}, but for enc files.
@@ -1598,7 +1626,6 @@ The list of functions is as follows:
\NC \luatex{read_font_file} \NC ofm or tfm files \NC\NR
\NC \luatex{read_vf_file} \NC virtual fonts \NC\NR
\NC \luatex{read_map_file} \NC map files \NC\NR
-\NC \luatex{read_cidmap_file} \NC cidmap files \NC\NR
\NC \luatex{read_enc_file} \NC encoding files \NC\NR
\NC \luatex{read_sfd_file} \NC subfont definition files \NC\NR
\NC \luatex{read_pk_file} \NC pk bitmap files \NC\NR
@@ -2051,6 +2078,55 @@ routines, but that needs lots of adjustments in the web source because
exact definition of \type{indicator} is not given here.
\fi
+
+\subsubsection{\luatex{show_error_message}}
+
+\startfunctioncall
+function()
+end
+\stopfunctioncall
+
+This callback replaces the code that prints the error message. The usual
+interaction after the message is not affected.
+
+\subsubsection{\luatex{show_lua_error_hook}}
+
+\startfunctioncall
+function()
+end
+\stopfunctioncall
+
+This callback replaces the code that prints the extra lua error message.
+
+
+\subsubsection{\luatex{start_file}}
+
+\startfunctioncall
+function(category,filename)
+end
+\stopfunctioncall
+
+This callback replaces the code that prints \LUATEX's when a file is opened
+like \type {(filename} for regular files. The category is a number:
+
+\starttabulate[|||]
+\NC 1 \NC a normal data file, like a \TEX\ source \NC \NR
+\NC 2 \NC a font map coupling font names to resources \NC \NR
+\NC 3 \NC an image file (\type {png}, \type {pdf}, etc) \NC \NR
+\NC 4 \NC an embedded font subset \NC \NR
+\NC 5 \NC a fully embedded font \NC \NR
+\stoptabulate
+
+\subsubsection{\luatex{stop_file}}
+
+\startfunctioncall
+function(category)
+end
+\stopfunctioncall
+
+This callback replaces the code that prints \LUATEX's when a file is closed
+like the \type{)} for regular files.
+
\subsection{PDF-related callbacks}
\subsubsection{\luatex{finish_pdffile}}
@@ -2066,6 +2142,19 @@ use is final update of \PDF\ dictionaries such as \type{/Catalog} or
\type{/Info}. The callback does not replace any code. There are neither
arguments nor return values.
+
+\subsubsection{\luatex{finish_pdfpage}}
+
+
+\startfunctioncall
+function(shippingout)
+end
+\stopfunctioncall
+
+This callback is called after the pdf page stream has been assembled and before the
+page object gets finalized. This callback is available in \LUATEX\ 0.78.4 and later.
+
+
\subsection{Font-related callbacks}
\subsubsection{\luatex{define_font}}
@@ -2657,7 +2746,7 @@ there can be holes in the sequence.
This function returns either \type{nil}, or a \type{table}, or an
array of small tables (in the case of a TrueType collection). The
-returned table(s) will contain six fairly interesting information
+returned table(s) will contain some fairly interesting information
items from the font(s) defined by the file:
\starttabulate[|lT|l|p|]
@@ -2668,6 +2757,8 @@ items from the font(s) defined by the file:
\NC weight \NC string \NC a string indicating the color value of the font\NC\NR
\NC version \NC string \NC the internal font version\NC\NR
\NC italicangle \NC float \NC the slant angle\NC\NR
+\NC units_per_em \NC number \NC (since 0.78.2) 1000 for \POSTSCRIPT-based fonts, usually 2048 for \TRUETYPE\NC\NR
+\NC pfminfo \NC table \NC (since 0.78.2) (see \in{section}[fontloaderpfminfotable])\NC\NR
\stoptabulate
Getting information through this function is (sometimes much) more
@@ -2938,17 +3029,15 @@ this part of the documentation are not yet finished):
\NC lookups \NC table \NC \NC\NR
\NC gpos \NC table \NC \NC\NR
\NC gsub \NC table \NC \NC\NR
-\NC sm \NC table \NC \NC\NR
-\NC features \NC table \NC \NC\NR
\NC mm \NC table \NC \NC\NR
\NC chosenname \NC string \NC \NC\NR
\NC macstyle \NC number \NC \NC\NR
\NC fondname \NC string \NC \NC\NR
-\NC design_size \NC number \NC \NC\NR
+%\NC design_size \NC number \NC \NC\NR
\NC fontstyle_id \NC number \NC \NC\NR
\NC fontstyle_name \NC table \NC \NC\NR
-\NC design_range_bottom \NC number \NC \NC\NR
-\NC design_range_top \NC number \NC \NC\NR
+%\NC design_range_bottom \NC number \NC \NC\NR
+%\NC design_range_top \NC number \NC \NC\NR
\NC strokewidth \NC float \NC \NC\NR
\NC mark_classes \NC table \NC \NC\NR
\NC creationtime \NC number \NC \NC\NR
@@ -2974,6 +3063,7 @@ information (quite a few of these are only present if nonzero).
\NC boundingbox \NC array \NC array of four numbers, see note below\NC\NR
\NC width \NC number \NC only for horizontal fonts\NC\NR
\NC vwidth \NC number \NC only for vertical fonts\NC\NR
+\NC tsidebearing \NC number \NC only for vertical ttf/otf fonts, and only if nonzero (0.79.0)\NC\NR
\NC lsidebearing \NC number \NC only if nonzero and not equal to boundingbox[1]\NC\NR
\NC class \NC string \NC one of "none", "base", "ligature", "mark", "component"
(if not present, the glyph class is \quote{automatic})\NC\NR
@@ -3170,7 +3260,7 @@ values are both strings.
\NC version \NC number \NC \NC\NR
\stoptabulate
-\subsubsubsection{pfminfo table}
+\subsubsubsection[fontloaderpfminfotable]{pfminfo table}
The \type{pfminfo} table contains most of the OS/2 information:
@@ -3243,7 +3333,7 @@ The \type{panose} subtable has exactly 10 string keys:
\NC xheight \NC string \NC id. \NC\NR
\stoptabulate
-\subsubsubsection{names table}
+\subsubsubsection[fontloadernamestable]{names table}
Each item has two top|-|level keys:
@@ -3333,7 +3423,6 @@ The features subtable items of gpos have:
\NC \ssbf key \NC \bf type \NC \bf explanation \NC\NR
\NC tag \NC string \NC \NC\NR
\NC scripts \NC table \NC \NC\NR
-\NC ismac \NC number \NC (only if true)\NC\NR
\stoptabulate
The scripts table within features has:
@@ -3391,61 +3480,6 @@ type:
\NC data \NC number \NC \NC\NR
\stoptabulate
-\subsubsubsection{sm table}
-
-\starttabulate[|lT|l|p|]
-\NC \ssbf key \NC \bf type \NC \bf explanation \NC\NR
-\NC type \NC string \NC one of "indic", "context", "lig", "simple", "insert", "kern"\NC\NR
-\NC lookup \NC string \NC \NC\NR
-\NC flags \NC table \NC a set of boolean values with
- the keys : "vert", "descending", "always"\NC\NR
-\NC classes \NC table \NC an array of named classes \NC\NR
-\NC state \NC table \NC \NC\NR
-\stoptabulate
-
-The \type{state} table has:
-
-\starttabulate[|lT|l|p|]
-\NC \ssbf key \NC \bf type \NC \bf explanation \NC\NR
-\NC next \NC number \NC \NC \NR
-\NC flags \NC number \NC \NC \NR
-\NC context \NC table \NC A small table that has 'mark' and
-'cur' as possible keys, with the values being lookup names. Only
-applies if the \type{sm.type} = \type{context}.\NC\NR
-\NC insert \NC table \NC A small table that has 'mark' and
-'cur' as possible keys, with the values strings. Only
-applies if the \type{sm.type} = \type{insert}.\NC\NR
-\NC kern \NC table \NC A small array with kern data. Only
-applies if the \type{sm.type} = \type{kern}.\NC\NR
-\stoptabulate
-
-
-\subsubsubsection{features table}
-
-% handle_macfeat
-
-\starttabulate[|lT|l|p|]
-\NC \ssbf key \NC \bf type \NC \bf explanation \NC\NR
-\NC feature \NC number \NC \NC \NR
-\NC ismutex \NC number \NC \NC \NR
-\NC default_setting \NC number \NC \NC \NR
-\NC strid \NC number \NC \NC \NR
-\NC featname \NC table \NC A set of mac names.
-macnames are like otfnames except that they also have an 'enc' field \NC \NR
-\NC settings \NC table \NC \NC \NR
-\stoptabulate
-
-The \type{settings} are:
-
-\starttabulate[|lT|l|p|]
-\NC \ssbf key \NC \bf type \NC \bf explanation \NC\NR
-\NC setting \NC number \NC \NC \NR
-\NC strid \NC number \NC \NC \NR
-\NC initially_enabled \NC number \NC \NC \NR
-\NC setname \NC table \NC A set of mac names.
-macnames are like otfnames except that they also have an 'enc' field \NC \NR
-\stoptabulate
-
\subsubsubsection{mm table}
\starttabulate[|lT|l|p|]
@@ -3458,9 +3492,6 @@ macnames are like otfnames except that they also have an 'enc' field \NC \NR
\NC cdv \NC string \NC \NC \NR
\NC ndv \NC string \NC \NC \NR
\NC axismaps \NC table \NC \NC \NR
-\NC named_instance_count \NC number \NC \NC \NR
-\NC named_instances \NC table \NC \NC \NR
-\NC apple \NC number \NC \NC \NR
\stoptabulate
The \type{axismaps}:
@@ -3472,16 +3503,6 @@ The \type{axismaps}:
\NC min \NC number \NC \NC \NR
\NC def \NC number \NC \NC \NR
\NC max \NC number \NC \NC \NR
-\NC axisnames \NC table \NC a set of mac names \NC \NR
-\stoptabulate
-
-
-The \type{named_instances} is an array of instances:
-
-\starttabulate[|lT|l|p|]
-\NC \ssbf key \NC \bf type \NC \bf explanation \NC\NR
-\NC names \NC table \NC a set of mac names \NC \NR
-\NC coords \NC table \NC an array of coordinates \NC \NR
\stoptabulate
@@ -5005,10 +5026,10 @@ copied.
Creates a deep copy of the node list that starts at \type{n}. If
\type{m} is also given, the copy stops just before node \type{m}.
-Note that you cannot copy attribute lists this way, specialized functions for
-dealing with attribute lists will be provided later but are not there yet.
+Note that you cannot copy attribute lists this way, specialized functions for
+dealing with attribute lists will be provided later but are not there yet.
However, there is normally no need to copy attribute lists as when you do
-assignments to the \type{attr} field or make changes to specific attributes, the
+assignments to the \type{attr} field or make changes to specific attributes, the
needed copying and freeing takes place automatically.
\subsubsection{\luatex{node.next} (0.65)}
@@ -5039,7 +5060,7 @@ such node.
Returns the currently active list of attributes, if there is one.
Note: this function is somewhat experimental, and it returns the {\it
- actual} attribute list, not a copy thereof.
+ actual} attribute list, not a copy thereof.
Therefore, changing any of the attributes in the list will change
these values for all nodes that have the current attribute list
assigned to them.
@@ -5205,12 +5226,12 @@ This function also accept string \type{id}'s.
\stopfunctioncall
This is a lua iterator that loops over the node list that starts at \type{n}.
-Typical input code like this
+Typical input code like this
\starttyping
for n in node.traverse(head) do
...
-end
+end
\stoptyping
is functionally equivalent to:
@@ -5236,12 +5257,12 @@ end
\stoptyping
It should be clear from the definition of the function \type{f} that
-even though it is possible to add or remove nodes from the node list while
+even though it is possible to add or remove nodes from the node list while
traversing, you have to take great care to make sure all the \type{next}
(and \type{prev}) pointers remain valid.
If the above is unclear to you, see the section \quote{For Statement}
-in the Lua Reference Manual.
+in the Lua Reference Manual.
\subsubsection{\luatex{node.traverse_id}}
@@ -5469,61 +5490,79 @@ The also functions replace the former variables
\luatex{pdf.pdfmapfile} and \luatex{pdf.pdfmapline}.
%***********************************************************************
-
\subsection{\luatex{pdf.catalog}, \luatex{pdf.info},
\luatex{pdf.names}, \luatex{pdf.trailer} (new in 0.53.0)}
-These variables offer a read-write interface to the corresponding
-\PDFTEX\ token lists. The value types are strings.
+These variables offer a read|-|write interface to the corresponding
+\PDFTEX\ token lists. The value types are strings and they are
+written out to the \PDF\ file directly after the \PDFTEX\ token registers.
-The corresponding \quote{\type{pdf}} parameter names
-\luatex{pdf.pdfcatalog}, \luatex{pdf.pdfinfo}, \luatex{pdf.pdfnames},
-and \luatex{pdf.pdftrailer} (all new in 0.47.0)
-still work, but are obsolescent (since 0.53.0).
+The preferred interface is now \luatex {pdf.setcatalog}, \luatex {pdf.setinfo}
+\luatex {pdf.setnames} and \luatex {pdf.settrailer} for setting these properties
+and \luatex {pdf.getcatalog}, \luatex {pdf.getinfo} \luatex {pdf.getnames} and
+\luatex {pdf.gettrailer} for querying them,
-Note: this interface will almost certainly change in the future.
+The corresponding \quote {\type{pdf}} parameter names \luatex {pdf.pdfcatalog},
+\luatex {pdf.pdfinfo}, \luatex {pdf.pdfnames}, and \luatex {pdf.pdftrailer} are
+removed in 0.79.0.
%***********************************************************************
-
\subsection{\luatex{pdf.pageattributes}, \luatex{pdf.pageresources},
- \luatex{pdf.pagesattributes} (new in 0.53.0)}
+ \luatex{pdf.pagesattributes}}
-These variables offer a read-write interface to related
+These variables offer a read|-|write interface to related
token lists. The value types are strings. The variables have no
interaction with the corresponding \PDFTEX\ token registers
-\tex{pdfpageattr}, \tex{pdfpageresources}, and \tex{pdfpagesattr},
-but they are written out to the \PDF\ file directly after
+\tex{pdfpageattr}, \tex{pdfpageresources}, and \tex{pdfpagesattr}.
+They are written out to the \PDF\ file directly after
the \PDFTEX\ token registers.
+The preferred interface is now \luatex {pdf.pageattributes}, \luatex
+{pdf.pagesattributes} and \luatex {pdf.setpageresources} for setting these
+properties and \luatex {pdf.pageattributes}, \luatex {pdf.getpageattributes} and
+\luatex {pdf.getpageresources} for querying them.
+
%***********************************************************************
\subsection{\luatex{pdf.h}, \luatex{pdf.v}}
-These are the \type{h} and \type{v} values
-that define the current location on the output page,
-measured from its lower left corner.
-The values can be queried % and set
+
+These are the \type{h} and \type{v} values that define the current location
+on the output page, measured from its lower left corner. The values can be queried
using scaled points as units.
-%\starttyping
-%pdf.h
-%pdf.v
-%\stoptyping
+\starttyping
+local h = pdf.h
+local v = pdf.v
+\stoptyping
+
+\subsection{\luatex{pdf.getpos}, \luatex{pdf.gethpos}, \luatex{pdf.getvpos}}
+
+These are the function variants of \type {pdf.h} and \type {pdf.v}. Sometimes
+using a function is preferred over a key so this saves wrapping. Also, these
+functions are faster then the key based access, as \type {h} and \type {v}
+keys are not real variables but looked up using a metatable call. The
+\type {getpos} function returns two values, the other return one.
+
+\starttyping
+local h, v = pdf.getpos()
+\stoptyping
+
+\subsection{\luatex{pdf.hasmatrix}, \luatex{pdf.getmatrix}}
+
+The current matrix transformation is available via the \type {getmatrix} command,
+which returns 6 values: \type {sx}, \type {rx}, \type {ry}, \type {sy}, \type {tx},
+and \type {ty}. The \type {hasmatrix} function returns \type {true} when a matrix is
+applied.
+
+\starttyping
+if pdf.hasmatrix() then
+ local sx, rx, ry, sy, tx, ty = pdf.getmatrix()
+ -- do something useful or not
+end
+\stoptyping
-Note: this interface will almost certainly change in the future.
-% not implemented yet:
-% \subsection{\luatex{pdf.seth()}, \luatex{pdf.setv()}}
-%
-% The function calls for position setting,
-% associated with \type{pdf.h} and \type{pdf.v} are
-%
-% \startfunctioncall
-% pdf.seth(<number> n)
-% <number> n = pdf.h
-% pdf.setv(<number> n)
-% <number> n = pdf.v
-% \stopfunctioncall
\subsection{\luatex{pdf.print}}
@@ -5685,7 +5724,7 @@ pdfscanner.scan (<Object> stream, <table> operatortable, <table> info)
\stopfunctioncall
The first argument, \type{stream}, should be either a PDF stream
-object, or a PDF array of PDF stream objects (those options comprise
+object, or a PDF array of PDF stream objects (those options comprise
the possible return values of \type{<Page>:getContents()}
and \type{<Object>:getStream()} in the \type{epdf} library).
@@ -5708,10 +5747,10 @@ next operator, and processing continues.
The \type{scanner} argument to the processing functions is needed
because it offers various methods to get the actual operands from the
-internal operand stack. The most important of those functions is
+internal operand stack. The most important of those functions is
\type{}
-A simple example of processing a PDF's document stream
+A simple example of processing a PDF's document stream
could look like this:
\starttyping
@@ -5731,7 +5770,7 @@ function Do (scanner, info)
pdfscanner.scan(xobject, operatortable, newinfo)
end
end
- end
+ end
end
operatortable = {Do = Do}
@@ -5747,17 +5786,17 @@ end
\stoptyping
This example iterates over all the actual content in the PDF, and
-prints out the found XObject names. While the code demonstrates quite
+prints out the found XObject names. While the code demonstrates quite
some of the \type{epdf} functions, let's focus on the type
-\type{pdfscanner} specific code instead.
+\type{pdfscanner} specific code instead.
-From the bottom up, the line
+From the bottom up, the line
\starttyping
pdfscanner.scan(page:getContents(), operatortable, info)
\stoptyping
-runs the scanner with the PDF page's top-level content.
+runs the scanner with the PDF page's top-level content.
The third argument, \type{info}, contains two entries: \type{space} is
used to indent the printed output, and \type{resources} is needed so
@@ -5778,7 +5817,7 @@ Of course, this is not a very useful example in practise, but for the
purpose of demonstrating \type{pdfscanner}, it is just long enough.
It makes use of only one \type{scanner} method: \type{scanner:pop()}.
That function pops the top operand of the internal stack, and returns
-a lua table where the object at index one is a string representing
+a lua table where the object at index one is a string representing
the type of the operand, and object two is its value.
The list of possible operand types and associated lua value types is:
@@ -5809,10 +5848,10 @@ decoded), and it treats the stream data for inline images as a string
that is the single operand for \type{EI}.
In case of \type{array}, the table content is a list of \type{pop}
-return values.
+return values.
In case of \type{dict}, the table keys are PDF name strings
-and the values are \type{pop} return values.
+and the values are \type{pop} return values.
\blank
@@ -5837,7 +5876,7 @@ to the \type{Do} operator is always a PDF name object.
The \type{done} function allows you to abort processing of a stream
once you have learned everything you want to learn. This comes in handy
-while parsing \type{/ToUnicode}, because there usually is trailing
+while parsing \type{/ToUnicode}, because there usually is trailing
garbage that you are not interested in. Without \type{done}, processing
only end at the end of the stream, possibly wasting CPU cycles.
@@ -6237,7 +6276,6 @@ tex.eTeXrevision
tex.formatname
tex.jobname
tex.luatexrevision
-tex.luatexdatestamp
tex.pdfnormaldeviate
tex.pdftexbanner
tex.pdftexrevision
@@ -9315,21 +9353,22 @@ Valid fields: \showfields{glyph}\crlf
Id: \showid{glyph}
\starttabulate[|lT|l|p|]
-\NC \ssbf field\NC \ssbf type \NC \ssbf explanation \NC\NR
-\NC subtype \NC number \NC bitfield\NC\NR
-\NC attr \NC \syntax{<node>} \NC \NC\NR
-\NC char \NC number \NC \NC\NR
-\NC font \NC number \NC \NC\NR
-\NC lang \NC number \NC \NC\NR
-\NC left \NC number \NC \NC\NR
-\NC right \NC number \NC \NC\NR
-\NC uchyph \NC boolean \NC \NC\NR
-\NC components \NC \syntax{<node>} \NC pointer to ligature components\NC\NR
-\NC xoffset \NC number \NC \NC\NR
-\NC yoffset \NC number \NC \NC\NR
-\NC width \NC number \NC (new in 0.53)\NC\NR
-\NC height \NC number \NC (new in 0.53)\NC\NR
-\NC depth \NC number \NC (new in 0.53)\NC\NR
+\NC \ssbf field \NC \ssbf type \NC \ssbf explanation \NC \NR
+\NC subtype \NC number \NC bitfield \NC \NR
+\NC attr \NC \syntax{<node>} \NC \NC \NR
+\NC char \NC number \NC \NC \NR
+\NC font \NC number \NC \NC \NR
+\NC lang \NC number \NC \NC \NR
+\NC left \NC number \NC \NC \NR
+\NC right \NC number \NC \NC \NR
+\NC uchyph \NC boolean \NC \NC \NR
+\NC components \NC \syntax{<node>} \NC pointer to ligature components \NC \NR
+\NC xoffset \NC number \NC \NC \NR
+\NC yoffset \NC number \NC \NC \NR
+\NC width \NC number \NC (new in 0.53) \NC \NR
+\NC height \NC number \NC (new in 0.53) \NC \NR
+\NC depth \NC number \NC (new in 0.53) \NC \NR
+\NC expansion_factor \NC number \NC (new in 0.78) \NC \NR
\stoptabulate
A warning: never assign a node list to the components field
@@ -9350,7 +9389,13 @@ Valid bits for the \type{subtype} field are:
See \in{section}[charsandglyphs] for a detailed description of the
\type{subtype} field.
-
+The \type {expansion_factor} is relatively new and the result of extensive
+experiments with a more efficient implementation of expansion. Early versions of
+\LUATEX\ already replaced multiple instances of fonts in the backend by scaling
+but contrary to \PDFTEX\ in \LUATEX\ we now also got rid of font copies in the
+frontend and replaced them by expansion factors that travel with glyph nodes. Apart
+from a cleaner approach this is also a step towards a better separation between
+front- and backend.
\subsubsection{margin{\_}kern nodes}
@@ -9984,6 +10029,173 @@ The \type{type} can have one of five distinct values:
\NC 116 \NC the value is a token list in \LUA\ table form\NC\NR
\stoptabulate
+\section{Two access models}
+
+After doing lots of tests with \LUATEX\ and \LUAJITTEX\, with and without just in
+time compilation enabled, and with and without using ffi, we came to the
+conclusion that userdata prevents a speedup. We also found that the checking of
+metatables as well as assignment comes with overhead that can't be neglected.
+This is normally not really a problem but when processing fonts for more complex
+scripts it could have quite some overhead.
+
+Because the userdata approach has some benefits, this remains the recommended way
+to access nodes. We did several experiments with faster access using this model,
+but eventually settled for the \quote {direct} approach. For code that is proven
+to be okay, one can use this access model that operates on nodes more directly.
+
+Deep down in \TEX\ a node has a number which is an entry in a memory table. In
+fact, this model, where \TEX\ manages memory is real fast and one of the reasons
+why plugging in callbacks that operate on nodes is quite fast. No matter what
+future memory model \LUATEX\ has, an internal reference will always be a simple data
+type (like a number or light userdata in \LUA\ speak). So, if you use the direct
+model, even if you know that you currently deal with numbers, you should not depend
+on that property but treat it an abstraction just like traditional nodes. In fact,
+the fact that we use a simple basic datatype has the penalty that less checking can
+be done, but less checking is also the reason why it's somewhat faster. An
+important aspect is that one cannot mix both methods, but you can cast both
+models.
+
+So our advice is: use the indexed approach when possible and investigate the
+direct one when speed might be an issue. For that reason we also provide the
+\type {get*} and \type {set*} functions in the top level node namespace. There is
+a limited set of getters. When implementing this direct approach the regular
+index by key variant was also optimized, so direct access only makes sense when
+we're accessing nodes millions of times (which happens in some font processing
+for instance).
+
+We're talking mostly of getters because setters are less important. Documents
+have not that many content related nodes and setting many thousands of properties
+is hardly a burden contrary to millions of consultations.
+
+Normally you will access nodes like this:
+
+\starttyping
+local next = current.next
+if next then
+ -- do something
+end
+\stoptyping
+
+Here \type {next} is not a real field, but a virtual one. Accessing it results in
+a metatable method being called. In practice it boils down to looking up the
+node type and based on the node type checking for the field name. In a worst case
+you have a node type that sits at the end of the lookup list and a field that is
+last in the lookup chain. However, in successive versions of \LUATEX\ these lookups
+have been optimized and the most frequently accessed nodes and fields have a higher
+priority.
+
+Because in practice the \type {next} accessor results in a function call, there
+is some overhead involved. The next code does the same and performs a tiny bit
+faster (but not that much because it is still a function call but one that
+knows what to look up).
+
+\starttyping
+local next = node.next(current)
+if next then
+ -- do something
+end
+\stoptyping
+
+There are several such function based accessors now:
+
+\starttabulate[|T|p|]
+\NC getnext \NC parsing nodelist always involves this one \NC \NR
+\NC getprev \NC used less but is logical companion to getnext \NC \NR
+\NC getid \NC consulted a lot \NC \NR
+\NC getsubtype \NC consulted less but also a topper \NC \NR
+\NC getfont \NC used a lot in otf handling (glyph nodes are consulted a lot) \NC \NR
+\NC getchar \NC idem and also in other places \NC \NR
+\NC getlist \NC we often parse nested lists so this is a convenient one too
+ (only works for hlist and vlist!) \NC \NR
+\NC getleader \NC comparable to list, seldom used in \TEX\ (but needs frequent consulting
+ like lists; leaders could have been made a dedicated node type) \NC \NR
+\NC getfield \NC generic getter, sufficient for the rest (other field names are
+ often shared so a specific getter makes no sense then) \NC \NR
+\stoptabulate
+
+It doesn't make sense to add more. Profiling demonstrated that these fields can
+get accesses way more times than other fields. Even in complex documents, many
+node and fields types never get seen, or seen only a few times. Most functions in the
+\type {node} namespace have a companion in \type {node.direct}, but of course not the
+ones that don't deal with nodes themselves. The following table summarized this:
+
+\start \def\yes{$+$} \def\nop{$-$}
+
+\starttabulate[|T|c|c|]
+\HL
+\NC \bf function \NC \bf node \NC \bf direct \NC \NR
+\HL
+\NC copy \NC \yes \NC \yes \NC \NR
+\NC copy_list \NC \yes \NC \yes \NC \NR
+\NC count \NC \yes \NC \yes \NC \NR
+\NC current_attr \NC \yes \NC \yes \NC \NR
+\NC dimensions \NC \yes \NC \yes \NC \NR
+\NC do_ligature_n \NC \yes \NC \yes \NC \NR
+\NC end_of_math \NC \yes \NC \yes \NC \NR
+\NC family_font \NC \yes \NC \nop \NC \NR
+\NC fields \NC \yes \NC \nop \NC \NR
+\NC first_character \NC \yes \NC \nop \NC \NR
+\NC first_glyph \NC \yes \NC \yes \NC \NR
+\NC flush_list \NC \yes \NC \yes \NC \NR
+\NC flush_node \NC \yes \NC \yes \NC \NR
+\NC free \NC \yes \NC \yes \NC \NR
+\NC getbox \NC \nop \NC \yes \NC \NR
+\NC getchar \NC \yes \NC \yes \NC \NR
+\NC getfield \NC \yes \NC \yes \NC \NR
+\NC getfont \NC \yes \NC \yes \NC \NR
+\NC getid \NC \yes \NC \yes \NC \NR
+\NC getnext \NC \yes \NC \yes \NC \NR
+\NC getprev \NC \yes \NC \yes \NC \NR
+\NC getlist \NC \yes \NC \yes \NC \NR
+\NC getleader \NC \yes \NC \yes \NC \NR
+\NC getsubtype \NC \yes \NC \yes \NC \NR
+\NC has_glyph \NC \yes \NC \yes \NC \NR
+\NC has_attribute \NC \yes \NC \yes \NC \NR
+\NC has_field \NC \yes \NC \yes \NC \NR
+\NC hpack \NC \yes \NC \yes \NC \NR
+\NC id \NC \yes \NC \nop \NC \NR
+\NC insert_after \NC \yes \NC \yes \NC \NR
+\NC insert_before \NC \yes \NC \yes \NC \NR
+\NC is_direct \NC \nop \NC \yes \NC \NR
+\NC is_node \NC \yes \NC \yes \NC \NR
+\NC kerning \NC \yes \NC \nop \NC \NR
+\NC last_node \NC \yes \NC \yes \NC \NR
+\NC length \NC \yes \NC \yes \NC \NR
+\NC ligaturing \NC \yes \NC \nop \NC \NR
+\NC mlist_to_hlist \NC \yes \NC \nop \NC \NR
+\NC new \NC \yes \NC \yes \NC \NR
+\NC next \NC \yes \NC \nop \NC \NR
+\NC prev \NC \yes \NC \nop \NC \NR
+\NC tostring \NC \yes \NC \yes \NC \NR
+\NC protect_glyphs \NC \yes \NC \yes \NC \NR
+\NC protrusion_skippable \NC \yes \NC \yes \NC \NR
+\NC remove \NC \yes \NC \yes \NC \NR
+\NC set_attribute \NC \yes \NC \yes \NC \NR
+\NC setbox \NC \yes \NC \yes \NC \NR
+\NC setfield \NC \yes \NC \yes \NC \NR
+\NC slide \NC \yes \NC \yes \NC \NR
+\NC subtype \NC \yes \NC \nop \NC \NR
+\NC tail \NC \yes \NC \yes \NC \NR
+\NC todirect \NC \yes \NC \yes \NC \NR
+\NC tonode \NC \yes \NC \yes \NC \NR
+\NC traverse \NC \yes \NC \yes \NC \NR
+\NC traverse_id \NC \yes \NC \yes \NC \NR
+\NC type \NC \yes \NC \nop \NC \NR
+\NC types \NC \yes \NC \nop \NC \NR
+\NC unprotect_glyphs \NC \yes \NC \yes \NC \NR
+\NC unset_attribute \NC \yes \NC \yes \NC \NR
+\NC usedlist \NC \yes \NC \yes \NC \NR
+\NC vpack \NC \yes \NC \yes \NC \NR
+\NC whatsits \NC \yes \NC \nop \NC \NR
+\NC write \NC \yes \NC \yes \NC \NR
+\stoptabulate
+
+\stop
+
+The \type {node.next} and \type {node.prev} functions will stay but for
+consistency there are variants called \type {getnext} and \type {getprev}.
+We had to use \type{get} because \type {node.id} and \type {node.subtype} are
+already taken for providing meta information about nodes.
\chapter{Modifications}