diff options
Diffstat (limited to 'doc/context/sources/general/manuals/luatex/luatex-nodes.tex')
| -rw-r--r-- | doc/context/sources/general/manuals/luatex/luatex-nodes.tex | 1884 |
1 files changed, 1175 insertions, 709 deletions
diff --git a/doc/context/sources/general/manuals/luatex/luatex-nodes.tex b/doc/context/sources/general/manuals/luatex/luatex-nodes.tex index 440568be5..8e6c59af6 100644 --- a/doc/context/sources/general/manuals/luatex/luatex-nodes.tex +++ b/doc/context/sources/general/manuals/luatex/luatex-nodes.tex @@ -33,46 +33,38 @@ than~15. You can ask for a list of fields with the \type {node.fields} (which takes an id) and for valid subtypes with \type {node.subtypes} (which takes a string because -eventually we might support more used enumerations) . +eventually we might support more used enumerations). -\subsection{Auxiliary items} - -A few node|-|typed userdata objects do not occur in the \quote {normal} list of -nodes, but can be pointed to from within that list. They are not quite the same -as regular nodes, but it is easier for the library routines to treat them as if -they were. - -\subsubsection{attribute_list and attribute items} +\subsection{Attributes} The newly introduced attribute registers are non|-|trivial, because the value -that is attached to a node is essentially a sparse array of key|-|value pairs. - -It is generally easiest to deal with attribute lists and attributes by using the +that is attached to a node is essentially a sparse array of key|-|value pairs. It +is generally easiest to deal with attribute lists and attributes by using the dedicated functions in the \type {node} library, but for completeness, here is the low|-|level interface. +\subsubsection{attribute_list nodes} + An \type {attribute_list} item is used as a head pointer for a list of attribute items. It has only one user-visible field: \starttabulate[|lT|l|p|] -\NC \ssbf field \NC \bf type \NC \bf explanation \NC \NR -\NC next \NC \syntax{<node>} \NC - pointer to the first attribute -\NC \NR +\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR +\NC next \NC node \NC pointer to the first attribute \NC \NR \stoptabulate +\subsubsection{attribute nodes} + A normal node's attribute field will point to an item of type \type {attribute_list}, and the \type {next} field in that item will point to the first defined \quote {attribute} item, whose \type {next} will point to the second \quote {attribute} item, etc. -Valid fields in \type {attribute} items: - \starttabulate[|lT|l|p|] -\NC \ssbf field \NC \bf type \NC \bf explanation \NC \NR -\NC next \NC \syntax{<node>} \NC pointer to the next attribute \NC \NR -\NC number \NC number \NC the attribute type id \NC \NR -\NC value \NC number \NC the attribute value \NC \NR +\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR +\NC next \NC node \NC pointer to the next attribute \NC \NR +\NC number \NC number \NC the attribute type id \NC \NR +\NC value \NC number \NC the attribute value \NC \NR \stoptabulate As mentioned it's better to use the official helpers rather than edit these @@ -81,15 +73,14 @@ and there is no double linked list. \subsection{Main text nodes} -These are the nodes that comprise actual typesetting commands. - -A few fields are present in all nodes regardless of their type, these are: +These are the nodes that comprise actual typesetting commands. A few fields are +present in all nodes regardless of their type, these are: \starttabulate[|lT|l|p|] -\NC \ssbf field \NC \bf type \NC \bf explanation \NC \NR -\NC next \NC \syntax{<node>} \NC the next node in a list, or nil \NC \NR -\NC id \NC number \NC the node's type (\type {id}) number \NC \NR -\NC subtype \NC number \NC the node \type {subtype} identifier \NC \NR +\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR +\NC next \NC node \NC the next node in a list, or nil \NC \NR +\NC id \NC number \NC the node's type (\type {id}) number \NC \NR +\NC subtype \NC number \NC the node \type {subtype} identifier \NC \NR \stoptabulate The \type {subtype} is sometimes just a stub entry. Not all nodes actually use @@ -101,40 +92,25 @@ Besides these three fields, almost all nodes also have an \type {attr} field, an there is a also a field called \type {prev}. That last field is always present, but only initialized on explicit request: when the function \type {node.slide()} is called, it will set up the \type {prev} fields to be a backwards pointer in -the argument node list. +the argument node list. By now most of \TEX's node processing makes sure that the +\type {prev} nodes are valid but there can be exceptions, especially when the +internal magic uses a leading \type {temp} nodes to temporarily store a state. \subsubsection{hlist nodes} -Valid fields: \showfields{hlist}\crlf -Id: \showid{hlist} - \starttabulate[|lT|l|p|] -\NC \ssbf field \NC \bf type \NC \bf explanation \NC \NR -\NC subtype \NC number \NC \type {0} = unknown origin, - \type {1} = created by linebreaking, - \type {2} = explicit box command, - \type {3} = paragraph indentation box, - \type {4} = alignment column or row, - \type {5} = alignment cell - \type {6} = equation - \type {7} = equation number \NC \NR -\NC attr \NC \syntax{<node>} \NC The head of the associated attribute - list \NC \NR -\NC width \NC number \NC \NC \NR -\NC height \NC number \NC \NC \NR -\NC depth \NC number \NC \NC \NR -\NC shift \NC number \NC a displacement perpendicular to the - character progression direction \NC \NR -\NC glue_order \NC number \NC a number in the range $[0,4]$, indicating - the glue order \NC \NR -\NC glue_set \NC number \NC the calculated glue ratio \NC \NR -\NC glue_sign \NC number \NC \type {0} = normal, - \type {1} = stretching, - \type {2} = shrinking \NC \NR -\NC head \NC \syntax{<node>} \NC the first node of the body of this - list \NC \NR -\NC dir \NC string \NC the direction of this box, - see~\in[dirnodes] \NC \NR +\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR +\NC subtype \NC number \NC \showsubtypes{list} \NC \NR +\NC attr \NC node \NC list of attributes \NC \NR +\NC width \NC number \NC the width of the box \NC \NR +\NC height \NC number \NC the height of the box \NC \NR +\NC depth \NC number \NC the depth of the box \NC \NR +\NC shift \NC number \NC a displacement perpendicular to the character progression direction \NC \NR +\NC glue_order \NC number \NC a number in the range $[0,4]$, indicating the glue order \NC \NR +\NC glue_set \NC number \NC the calculated glue ratio \NC \NR +\NC glue_sign \NC number \NC 0 = \type {normal}, 1 = \type {stretching}, 2 = \type {shrinking} \NC \NR +\NC head/list \NC node \NC the first node of the body of this list \NC \NR +\NC dir \NC string \NC the direction of this box, see~\in[dirnodes] \NC \NR \stoptabulate A warning: never assign a node list to the \type {head} field unless you are sure @@ -146,60 +122,37 @@ more sense. \subsubsection{vlist nodes} -Valid fields: As for hlist, except that \quote {shift} is a displacement +This node is similar to \type {hlist}, except that \quote {shift} is a displacement perpendicular to the line progression direction, and \quote {subtype} only has -subtypes~0, 4, and~5. +the values 0, 4, and~5. \subsubsection{rule nodes} -\subsubsubsection{normal rules} - -Valid fields: \showfields{rule}\crlf -Id: \showid{rule} - -We have three subtypes. Subtype~0 is just a normal rule, a rectangle -filled with ink. Subtype~1 is a reusable box, while subtype_2 is an -image. +Contrary to traditional \TEX, \LUATEX\ has more subtypes because we also use +rules to store reuseable objects and images. User nodes are invisible and can be +intercepted by a callback. \starttabulate[|lT|l|p|] -\NC \ssbf field \NC \bf type \NC \bf explanation \NC \NR -\NC subtype \NC number \NC 0 upto 3 \NC \NR -\NC attr \NC \syntax{<node>} \NC \NC \NR -\NC width \NC number \NC the width of the rule; the special value - $-1073741824$ is used for \quote - {running} glue dimensions \NC \NR -\NC height \NC number \NC the height of the rule (can be - negative) \NC \NR -\NC depth \NC number \NC the depth of the rule (can be - negative) \NC \NR -\NC dir \NC string \NC the direction of this rule, - see~\in[dirnodes] \NC \NR -\NC index \NC number \NC an optional index that can be referred - to (only for subtypes 1 and~2 and - backend specific). \NC \NR +\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR +\NC subtype \NC number \NC \showsubtypes{rule} \NC \NR +\NC attr \NC node \NC list of attributes \NC \NR +\NC width \NC number \NC the width of the rule where the special value $-1073741824$ is used for \quote {running} glue dimensions \NC \NR +\NC height \NC number \NC the height of the rule (can be negative) \NC \NR +\NC depth \NC number \NC the depth of the rule (can be negative) \NC \NR +\NC dir \NC string \NC the direction of this rule, see~\in[dirnodes] \NC \NR +\NC index \NC number \NC an optional index that can be referred to \NC \NR \stoptabulate -The subtypes 1 and~2 replace the xform and ximage whatsits and in node lists they -behave like rules of subtype_0 when it comes to dimensions. Subtype~3 only has -dimensions. - \subsubsection{ins nodes} -Valid fields: \showfields{ins}\crlf -Id: \showid{ins} - \starttabulate[|lT|l|p|] -\NC \ssbf field \NC \bf type \NC \bf explanation \NC \NR -\NC subtype \NC number \NC the insertion class \NC \NR -\NC attr \NC \syntax{<node>} \NC \NC \NR -\NC cost \NC number \NC the penalty associated with this - insert \NC \NR -\NC height \NC number \NC \NC \NR -\NC depth \NC number \NC \NC \NR -\NC head/list \NC \syntax{<node>} \NC the first node of the body of this - insert \NC \NR -%NC spec \NC \syntax{<node>} \NC a pointer to the \type {\splittopskip} -% glue spec \NC \NR +\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR +\NC subtype \NC number \NC the insertion class \NC \NR +\NC attr \NC node \NC list of attributes \NC \NR +\NC cost \NC number \NC the penalty associated with this insert \NC \NR +\NC height \NC number \NC height of the insert \NC \NR +\NC depth \NC number \NC depth of the insert \NC \NR +\NC head/list \NC node \NC the first node of the body of this insert \NC \NR \stoptabulate There is a set of extra fields that concern the associated glue: \type {width}, @@ -213,28 +166,21 @@ names and both names are equally sensible). \subsubsection{mark nodes} -Valid fields: \showfields{mark}\crlf -Id: \showid{mark} - \starttabulate[|lT|l|p|] -\NC \ssbf field \NC \bf type \NC \bf explanation \NC \NR -\NC subtype \NC number \NC unused \NC \NR -\NC attr \NC \syntax{<node>} \NC \NC \NR -\NC class \NC number \NC the mark class \NC \NR -\NC mark \NC table \NC a table representing a token list \NC \NR +\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR +\NC subtype \NC number \NC unused \NC \NR +\NC attr \NC node \NC list of attributes \NC \NR +\NC class \NC number \NC the mark class \NC \NR +\NC mark \NC table \NC a table representing a token list \NC \NR \stoptabulate \subsubsection{adjust nodes} -Valid fields: \showfields{adjust}\crlf -Id: \showid{adjust} - \starttabulate[|lT|l|p|] -\NC \ssbf field \NC \bf type \NC \bf explanation \NC \NR -\NC subtype \NC number \NC \type {0} = normal, - \type {1} = \quote{pre} \NC \NR -\NC attr \NC \syntax{<node>} \NC \NC \NR -\NC head/list \NC \syntax{<node>} \NC adjusted material \NC \NR +\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR +\NC subtype \NC number \NC \showsubtypes{adjust} \NC \NR +\NC attr \NC node \NC list of attributes \NC \NR +\NC head/list \NC node \NC adjusted material \NC \NR \stoptabulate A warning: never assign a node list to the \type {head} field unless you are sure @@ -242,45 +188,26 @@ its internal link structure is correct, otherwise an error may be result. \subsubsection{disc nodes} -Valid fields: \showfields{disc}\crlf -Id: \showid{disc} - \starttabulate[|lT|l|p|] -\NC \ssbf field \NC \bf type \NC \bf explanation \NC \NR -\NC subtype \NC number \NC indicates the source of a discretionary: - \type {0} = the \type {\discretionary} command, - \type {1} = the \type {\-} command, - \type {2} = added automatically following a \type {-}, - \type {3} = added by the hyphenation algorithm (simple), - \type {4} = added by the hyphenation algorithm (hard, first item), - \type {5} = added by the hyphenation algorithm (hard, second item) \NC \NR -\NC attr \NC \syntax{<node>} \NC \NC \NR -\NC pre \NC \syntax{<node>} \NC pointer to the pre|-|break text \NC \NR -\NC post \NC \syntax{<node>} \NC pointer to the post|-|break text \NC \NR -\NC replace \NC \syntax{<node>} \NC pointer to the no|-|break text \NC \NR -\NC penalty \NC number \NC the penalty associated with the break, - normally \type {\hyphenpenalty} or \type - {\exhyphenpenalty} \NC \NR +\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR +\NC subtype \NC number \NC \showsubtypes{disc} \NC \NR +\NC attr \NC node \NC list of attributes \NC \NR +\NC pre \NC node \NC pointer to the pre|-|break text \NC \NR +\NC post \NC node \NC pointer to the post|-|break text \NC \NR +\NC replace \NC node \NC pointer to the no|-|break text \NC \NR +\NC penalty \NC number \NC the penalty associated with the break, normally \type {\hyphenpenalty} or \type {\exhyphenpenalty} \NC \NR \stoptabulate The subtype numbers~4 and~5 belong to the \quote {of-f-ice} explanation given elsewhere. -Warning: never assign a node list to the \type {pre}, \type {post} or \type -{replace} field unless you are sure its internal link structure is correct, -otherwise an error may be result. This limnitation will disappear in the future, - \subsubsection{math nodes} -Valid fields: \showfields{math}\crlf -Id: \showid{math} - \starttabulate[|lT|l|p|] -\NC \ssbf field \NC \bf type \NC \bf explanation \NC \NR -\NC subtype \NC number \NC \type {0} = on, - \type {1} = off \NC \NR -\NC attr \NC \syntax{<node>} \NC \NC \NR -\NC surround \NC number \NC width of the \type {\mathsurround} kern \NC \NR +\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR +\NC subtype \NC number \NC \showsubtypes{math} \NC \NR +\NC attr \NC node \NC list of attributes \NC \NR +\NC surround \NC number \NC width of the \type {\mathsurround} kern \NC \NR \stoptabulate There is a set of extra fields that concern the associated glue: \type {width}, @@ -294,19 +221,14 @@ simple value. The structure that represents the glue components of a skip is called a \type {glue_spec}, and it has the following accessible fields: \starttabulate[|lT|l|p|] -\NC \ssbf key \NC \bf type \NC \bf explanation \NC \NR -\NC width \NC number \NC \NC \NR -\NC stretch \NC number \NC \NC \NR -\NC stretch_order \NC number \NC \NC \NR -\NC shrink \NC number \NC \NC \NR -\NC shrink_order \NC number \NC \NC \NR +\NC \rmbf key \NC \bf type \NC \bf explanation \NC \NR +\NC width \NC number \NC the horizontal or vertical displacement \NC \NR +\NC stretch \NC number \NC extra (positive) displacement or stretch amount \NC \NR +\NC stretch_order \NC number \NC factor applied to stretch amount \NC \NR +\NC shrink \NC number \NC extra (negative) displacement or shrink amount\NC \NR +\NC shrink_order \NC number \NC factor applied to shrink amount \NC \NR \stoptabulate -% These objects are reference counted, so there is actually an extra read|-|only -% field named \type {ref_count} as well. This item type will likely disappear in -% the future, and the glue fields themselves will become part of the nodes -% referencing glue items. - The effective width of some glue subtypes depends on the stretch or shrink needed to make the encapsulating box fit its dimensions. For instance, in a paragraph lines normally have glue representing spaces and these stretch of shrink to make @@ -331,144 +253,75 @@ a field can result in a new copy). So in the end the advantages of sharing are not that high (and nowadays memory is less an issue, also given that a glue node is only a few memory words larger than a spec). -Valid fields: \showfields{glue}\crlf -Id: \showid{glue} - \starttabulate[|lT|l|p|] -\NC \ssbf field \NC \bf type \NC \bf explanation \NC \NR -\NC subtype \NC number \NC \type {0} = \type {\skip}, - \type {1-18} = internal glue parameters, - \type {98-99} = \quote {math glue} subtypes - \type {100-103} = \quote {leader} subtypes \NC \NR -\NC attr \NC \syntax{<node>} \NC \NC \NR -\NC leader \NC \syntax{<node>} \NC pointer to a box or rule for leaders \NC \NR -\NC width \NC number \NC \NC \NR -\NC stretch \NC number \NC \NC \NR -\NC stretch_order \NC number \NC \NC \NR -\NC shrink \NC number \NC \NC \NR -\NC shrink_order \NC number \NC \NC \NR +\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR +\NC subtype \NC number \NC \showsubtypes{glue} \NC \NR +\NC attr \NC node \NC list of attributes \NC \NR +\NC leader \NC node \NC pointer to a box or rule for leaders \NC \NR \stoptabulate -Note that we use the key \type {width} in both horizontal and vertical glue. This -suits the \TEX\ internals well so we decided to stick to that naming. - -The exact meanings of the subtypes are as follows: - -\starttabulate[|rT|l|] -\NC 1 \NC \type {\lineskip} \NC \NR -\NC 2 \NC \type {\baselineskip} \NC \NR -\NC 3 \NC \type {\parskip} \NC \NR -\NC 4 \NC \type {\abovedisplayskip} \NC \NR -\NC 5 \NC \type {\belowdisplayskip} \NC \NR -\NC 6 \NC \type {\abovedisplayshortskip} \NC \NR -\NC 7 \NC \type {\belowdisplayshortskip} \NC \NR -\NC 8 \NC \type {\leftskip} \NC \NR -\NC 9 \NC \type {\rightskip} \NC \NR -\NC 10 \NC \type {\topskip} \NC \NR -\NC 11 \NC \type {\splittopskip} \NC \NR -\NC 12 \NC \type {\tabskip} \NC \NR -\NC 13 \NC \type {\spaceskip} \NC \NR -\NC 14 \NC \type {\xspaceskip} \NC \NR -\NC 15 \NC \type {\parfillskip} \NC \NR -\NC 16 \NC \type {\mathsurroundskip} \NC \NR -\NC 17 \NC \type {\thinmuskip} \NC \NR -\NC 18 \NC \type {\medmuskip} \NC \NR -\NC 19 \NC \type {\thickmuskip} \NC \NR -\NC 98 \NC \type {conditional math skip} \NC \NR -\NC 99 \NC \type {muglue} \NC \NR -\NC 100 \NC \type {\leaders} \NC \NR -\NC 101 \NC \type {\cleaders} \NC \NR -\NC 102 \NC \type {\xleaders} \NC \NR -\NC 103 \NC \type {\gleaders} \NC \NR -\stoptabulate +In addition there are the \type {width}, \type {stretch} \type {stretch_order}, +\type {shrink}, and \type {shrink_order} fields. Note that we use the key \type +{width} in both horizontal and vertical glue. This suits the \TEX\ internals well +so we decided to stick to that naming. A regular word space also results in a \type {spaceskip} subtype (this used to be a \type {userskip} with subtype zero). -For convenience we provide access to the spec fields directly so that you can -avoid the spec lookup. So, the following fields can also be queried or set. When -you set a field and no spec is set, a spec will automatically be created. - -\starttabulate[|lT|l|p|] -\NC \ssbf key \NC \bf type \NC \bf explanation \NC \NR -\NC width \NC number \NC \NC \NR -\NC stretch \NC number \NC \NC \NR -\NC stretch_order \NC number \NC \NC \NR -\NC shrink \NC number \NC \NC \NR -\NC shrink_order \NC number \NC \NC \NR -\stoptabulate - -When you assign the properties to a spec using the above keys the advantage is -that when needed a new spec is allocated. if you access the spec node directly -you can get an error message with respect to a non|-|writable spec node. - -By using the accessors in the glue node you are more future proof as we might -decide at some point to carry all information in the glue nodes themselves. Of -course we can then also decide to make the spec field kind of virtual to keep -compatibility (for a while). - \subsubsection{kern nodes} -Valid fields: \showfields{kern}\crlf -Id: \showid{kern} - \starttabulate[|lT|l|p|] -\NC \ssbf field \NC \bf type \NC \bf explanation \NC \NR -\NC subtype \NC number \NC \type {0} = from font, - \type {1} = from \type {\kern}, - \type {2} = from \type {\accent}, - \type {3} = from \type {\/} \NC \NR -\NC attr \NC \syntax{<node>} \NC \NC \NR -\NC kern \NC number \NC \NC \NR +\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR +\NC subtype \NC number \NC \showsubtypes{kern} \NC \NR +\NC attr \NC node \NC list of attributes \NC \NR +\NC kern \NC number \NC fixed horizontal or vertical advance \NC \NR \stoptabulate \subsubsection{penalty nodes} -Valid fields: \showfields{penalty}\crlf -Id: \showid{penalty} - \starttabulate[|lT|l|p|] -\NC \ssbf field \NC \bf type \NC \bf explanation \NC \NR -\NC subtype \NC number \NC not used \NC \NR -\NC attr \NC \syntax{<node>} \NC \NC \NR -\NC penalty \NC number \NC \NC \NR +\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR +\NC subtype \NC number \NC not used \NC \NR +\NC attr \NC node \NC list of attributes \NC \NR +\NC penalty \NC number \NC the penalty value \NC \NR \stoptabulate \subsubsection[glyphnodes]{glyph nodes} -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 \NC \NR -\NC height \NC number \NC \NC \NR -\NC depth \NC number \NC \NC \NR -\NC expansion_factor \NC number \NC \NC \NR +\NC \rmbf field \NC \rmbf type \NC \rmbf explanation \NC \NR +\NC subtype \NC number \NC bitfield \NC \NR +\NC attr \NC node \NC list of attributes \NC \NR +\NC char \NC number \NC the chatacter index in the font \NC \NR +\NC font \NC number \NC the font identifier \NC \NR +\NC lang \NC number \NC the language identifier \NC \NR +\NC left \NC number \NC the frozen \type {\lefthyphenmnin} value \NC \NR +\NC right \NC number \NC the frozen \type {\righthyphenmnin} value \NC \NR +\NC uchyph \NC boolean \NC the frozen \type {\uchyph} value \NC \NR +\NC components \NC node \NC pointer to ligature components \NC \NR +\NC xoffset \NC number \NC a virtual displacement in horizontal direction \NC \NR +\NC yoffset \NC number \NC a virtual displacement in vertical direction \NC \NR +\NC xadvance \NC number \NC an additional advance after the glyph (experimental) \NC \NR +\NC width \NC number \NC the (original) width of the character \NC \NR +\NC height \NC number \NC the (original) height of the character\NC \NR +\NC depth \NC number \NC the (original) depth of the character\NC \NR +\NC expansion_factor \NC number \NC the to be applied expansion_factor \NC \NR \stoptabulate +The \type {width}, \type {height} and \type {depth} values are read|-|only. The +\type {expansion_factor} is assigned in the parbuilder and used in the backend. + A warning: never assign a node list to the components field unless you are sure its internal link structure is correct, otherwise an error may be result. Valid bits for the \type {subtype} field are: \starttabulate[|c|l|] -\NC \ssbf bit \NC \bf meaning \NC \NR -\NC 0 \NC character \NC \NR -\NC 1 \NC ligature \NC \NR -\NC 2 \NC ghost \NC \NR -\NC 3 \NC left \NC \NR -\NC 4 \NC right \NC \NR +\NC \rmbf bit \NC \bf meaning \NC \NR +\NC 0 \NC character \NC \NR +\NC 1 \NC ligature \NC \NR +\NC 2 \NC ghost \NC \NR +\NC 3 \NC left \NC \NR +\NC 4 \NC right \NC \NR \stoptabulate See \in {section} [charsandglyphs] for a detailed description of the \type @@ -493,18 +346,78 @@ than 256, so it returns either the character value or nil plus the id. These helpers are not always faster than separate calls but they sometimes permit making more readable tests. -\subsubsection{margin_kern nodes} +\subsubsection{boundary nodes} + +\starttabulate[|lT|l|p|] +\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR +\NC subtype \NC number \NC \showsubtypes{boundary} \NC \NR +\NC attr \NC node \NC list of attributes \NC \NR +\NC value \NC number \NC values 0--255 are reserved \NC \NR +\stoptabulate + +This node relates to the \type {\noboundary}, \type {\boundary}, \type +{\protrusionboundary} and \type {\wordboundary} primitives. + +\subsubsection{local_par nodes} + +\starttabulate[|lT|l|p|] +\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR +\NC attr \NC node \NC list of attributes \NC \NR +\NC pen_inter \NC number \NC local interline penalty (from \type {\localinterlinepenalty}) \NC \NR +\NC pen_broken \NC number \NC local broken penalty (from \type {\localbrokenpenalty}) \NC \NR +\NC dir \NC string \NC the direction of this par. see~\in [dirnodes] \NC \NR +\NC box_left \NC node \NC the \type {\localleftbox} \NC \NR +\NC box_left_width \NC number \NC width of the \type {\localleftbox} \NC \NR +\NC box_right \NC node \NC the \type {\localrightbox} \NC \NR +\NC box_right_width \NC number \NC width of the \type {\localrightbox} \NC \NR +\stoptabulate + +A warning: never assign a node list to the \type {box_left} or \type {box_right} +field unless you are sure its internal link structure is correct, otherwise an +error may be result. -Valid fields: \showfields{margin_kern}\crlf -Id: \showid{margin_kern} +\subsubsection[dirnodes]{dir nodes} \starttabulate[|lT|l|p|] -\NC \ssbf field \NC \bf type \NC \bf explanation \NC \NR -\NC subtype \NC number \NC \type {0} = left side, - \type {1} = right side \NC \NR -\NC attr \NC \syntax{<node>} \NC \NC \NR -\NC width \NC number \NC \NC \NR -\NC glyph \NC \syntax{<node>} \NC \NC \NR +\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR +\NC attr \NC node \NC list of attributes \NC \NR +\NC dir \NC string \NC the direction (but see below) \NC \NR +\NC level \NC number \NC nesting level of this direction whatsit \NC \NR +\stoptabulate + +A note on \type {dir} strings. Direction specifiers are three|-|letter +combinations of \type {T}, \type {B}, \type {R}, and \type {L}. + +These are built up out of three separate items: + +\startitemize[packed] +\startitem + the first is the direction of the \quote{top} of paragraphs. +\stopitem +\startitem + the second is the direction of the \quote{start} of lines. +\stopitem +\startitem + the third is the direction of the \quote{top} of glyphs. +\stopitem +\stopitemize + +However, only four combinations are accepted: \type {TLT}, \type {TRT}, \type +{RTT}, and \type {LTL}. + +Inside actual \type {dir} whatsit nodes, the representation of \type {dir} is not +a three-letter but a four|-|letter combination. The first character in this case +is always either \type {+} or \type {-}, indicating whether the value is pushed +or popped from the direction stack. + +\subsubsection{margin_kern nodes} + +\starttabulate[|lT|l|p|] +\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR +\NC subtype \NC number \NC \showsubtypes{margin_kern} \NC \NR +\NC attr \NC node \NC list of attributes \NC \NR +\NC width \NC number \NC the advance of the kern \NC \NR +\NC glyph \NC node \NC the glyph to be used \NC \NR \stoptabulate \subsection{Math nodes} @@ -524,14 +437,11 @@ The \type {next} and \type {prev} fields for these subnodes are unused. \subsubsubsection{math_char and math_text_char subnodes} -Valid fields: \showfields{math_char}\crlf -Id: \showid{math_char} - \starttabulate[|lT|l|p|] -\NC \ssbf field \NC \bf type \NC \bf explanation \NC \NR -\NC attr \NC \syntax{<node>} \NC \NC \NR -\NC char \NC number \NC \NC \NR -\NC fam \NC number \NC \NC \NR +\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR +\NC attr \NC node \NC list of attributes \NC \NR +\NC char \NC number \NC the character index \NC \NR +\NC fam \NC number \NC the family number \NC \NR \stoptabulate The \type {math_char} is the simplest subnode field, it contains the character @@ -541,13 +451,10 @@ conversion (its sole function is to suppress a following italic correction). \subsubsubsection{sub_box and sub_mlist subnodes} -Valid fields: \showfields{sub_box}\crlf -Id: \showid{sub_box} - \starttabulate[|lT|l|p|] -\NC \ssbf field \NC \bf type \NC \bf explanation \NC \NR -\NC attr \NC \syntax{<node>}\NC \NC \NR -\NC head \NC \syntax{<node>}\NC \NC \NR +\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR +\NC attr \NC node \NC list of attributes \NC \NR +\NC head/list \NC node \NC list of nodes \NC \NR \stoptabulate These two subnode types are used for subsidiary list items. For \type {sub_box}, @@ -564,16 +471,13 @@ before, the \type {next} and \type {prev} fields are unused. \subsubsubsection{delim subnodes} -Valid fields: \showfields{delim}\crlf -Id: \showid{delim} - \starttabulate[|lT|l|p|] -\NC \ssbf field \NC \bf type \NC\bf explanation \NC \NR -\NC attr \NC \syntax{<node>} \NC \NC \NR -\NC small_char \NC number \NC \NC \NR -\NC small_fam \NC number \NC \NC \NR -\NC large_char \NC number \NC \NC \NR -\NC large_fam \NC number \NC \NC \NR +\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR +\NC attr \NC node \NC list of attributes \NC \NR +\NC small_char \NC number \NC character index of base character \NC \NR +\NC small_fam \NC number \NC family number of base character \NC \NR +\NC large_char \NC number \NC character index of next larger character \NC \NR +\NC large_fam \NC number \NC family number of next larger character \NC \NR \stoptabulate The fields \type {large_char} and \type {large_fam} can be zero, in that case the @@ -589,66 +493,31 @@ into a single node type with separate subtypes for differentiation. \subsubsubsection{simple nodes} -Valid fields: \showfields{noad}\crlf -Id: \showid{noad} - \starttabulate[|lT|l|p|] -\NC \ssbf field \NC \bf type \NC \bf explanation \NC \NR -\NC subtype \NC number \NC see below \NC \NR -\NC attr \NC \syntax{<node>} \NC \NC \NR -\NC nucleus \NC \syntax{<kernel>} \NC \NC \NR -\NC sub \NC \syntax{<kernel>} \NC \NC \NR -\NC sup \NC \syntax{<kernel>} \NC \NC \NR -\stoptabulate - -Operators are a bit special because they occupy three subtypes. \type {subtype}. - -\starttabulate[|lT|p|] -\NC \ssbf number \NC \bf node subtype \NC \NR -\NC 0 \NC Ord \NC \NR -\NC 1 \NC Op: \type {\displaylimits} \NC \NR -\NC 2 \NC Op: \type {\limits} \NC \NR -\NC 3 \NC Op: \type {\nolimits} \NC \NR -\NC 4 \NC Bin \NC \NR -\NC 5 \NC Rel \NC \NR -\NC 6 \NC Open \NC \NR -\NC 7 \NC Close \NC \NR -\NC 8 \NC Punct \NC \NR -\NC 9 \NC Inner \NC \NR -\NC 10 \NC Under \NC \NR -\NC 11 \NC Over \NC \NR -\NC 12 \NC Vcent \NC \NR +\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR +\NC subtype \NC number \NC \showsubtypes{noad} \NC \NR +\NC attr \NC node \NC list of attributes \NC \NR +\NC nucleus \NC kernel node \NC base \NC \NR +\NC sub \NC kernel node \NC subscript \NC \NR +\NC sup \NC kernel node \NC superscript \NC \NR \stoptabulate \subsubsubsection{accent nodes} -Valid fields: \showfields{accent}\crlf -Id: \showid{accent} - \starttabulate[|lT|l|p|] -\NC \ssbf field \NC \bf type \NC \bf explanation \NC \NR -\NC subtype \NC number \NC the first bit is used for a fixed top - accent flag (if the \type {accent} - field is present), the second bit for a - fixed bottom accent flag (if the \type - {bot_accent} field is present); example: - the actual value \type {3} means: do - not stretch either accent \NC \NR -\NC attr \NC \syntax{<node>} \NC \NC \NR -\NC nucleus \NC \syntax{<kernel>} \NC \NC \NR -\NC sub \NC \syntax{<kernel>} \NC \NC \NR -\NC sup \NC \syntax{<kernel>} \NC \NC \NR -\NC accent \NC \syntax{<kernel>} \NC \NC \NR -\NC bot_accent \NC \syntax{<kernel>} \NC \NC \NR +\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR +\NC subtype \NC number \NC \showsubtypes{accent} \NC \NR +\NC nucleus \NC kernel node \NC base \NC \NR +\NC sub \NC kernel node \NC subscript \NC \NR +\NC sup \NC kernel node \NC superscript \NC \NR +\NC accent \NC kernel node \NC top accent \NC \NR +\NC bot_accent \NC kernel node \NC bottom accent \NC \NR \stoptabulate \subsubsubsection{style nodes} -Valid fields: \showfields{style}\crlf -Id: \showid{style} - \starttabulate[|lT|l|p|] -\NC \ssbf field \NC \bf type \NC \bf explanation \NC \NR +\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR \NC style \NC string \NC contains the style \NC \NR \stoptabulate @@ -658,16 +527,13 @@ a trailing \type {'} to signify \quote {cramped} styles. \subsubsubsection{choice nodes} -Valid fields: \showfields{choice}\crlf -Id: \showid{choice} - \starttabulate[|lT|l|p|] -\NC \ssbf field \NC \bf type \NC \bf explanation \NC \NR -\NC attr \NC \syntax{<node>} \NC \NC \NR -\NC display \NC \syntax{<node>} \NC \NC \NR -\NC text \NC \syntax{<node>} \NC \NC \NR -\NC script \NC \syntax{<node>} \NC \NC \NR -\NC scriptscript \NC \syntax{<node>} \NC \NC \NR +\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR +\NC attr \NC node \NC list of attributes \NC \NR +\NC display \NC node \NC list of display size alternatives \NC \NR +\NC text \NC node \NC list of text size alternatives \NC \NR +\NC script \NC node \NC list of scriptsize alternatives \NC \NR +\NC scriptscript \NC node \NC list of scriptscriptsize alternatives \NC \NR \stoptabulate A warning: never assign a node list to the display, text, script, or @@ -676,51 +542,31 @@ correct, otherwise an error may be result. \subsubsubsection{radical nodes} -Valid fields: \showfields{radical}\crlf -Id: \showid{radical} - \starttabulate[|lT|l|p|] -\NC \ssbf field \NC \bf type \NC \bf explanation \NC \NR -\NC attr \NC \syntax{<node>} \NC \NC \NR -\NC nucleus \NC \syntax{<kernel>} \NC \NC \NR -\NC sub \NC \syntax{<kernel>} \NC \NC \NR -\NC sup \NC \syntax{<kernel>} \NC \NC \NR -\NC left \NC \syntax{<delim>} \NC \NC \NR -\NC degree \NC \syntax{<kernel>} \NC - Only set by \type {\Uroot} -\NC \NR +\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR +\NC subtype \NC number \NC \showsubtypes{radical} \NC \NR +\NC attr \NC node \NC list of attributes \NC \NR +\NC nucleus \NC kernel node \NC base \NC \NR +\NC sub \NC kernel node \NC subscript \NC \NR +\NC sup \NC kernel node \NC superscript \NC \NR +\NC left \NC delimiter node \NC \NC \NR +\NC degree \NC kernel node \NC only set by \type {\Uroot} \NC \NR \stoptabulate A warning: never assign a node list to the nucleus, sub, sup, left, or degree field unless you are sure its internal link structure is correct, otherwise an error may be result. -The radical noad is also used for under- and overdelimiters, which is indicated -by the subtypes: - -\starttabulate[|lT|l|] -\NC 0 \NC \type {\radical} \NC \NR -\NC 1 \NC \type {\Uradical} \NC \NR -\NC 2 \NC \type {\Uroot} \NC \NR -\NC 3 \NC \type {\Uunderdelimiter} \NC \NR -\NC 4 \NC \type {\Uoverdelimiter} \NC \NR -\NC 5 \NC \type {\Udelimiterunder} \NC \NR -\NC 6 \NC \type {\Udelimiterover} \NC \NR -\stoptabulate - \subsubsubsection{fraction nodes} -Valid fields: \showfields{fraction}\crlf -Id: \showid{fraction} - \starttabulate[|lT|l|p|] -\NC \ssbf field \NC \bf type \NC \bf explanation \NC \NR -\NC attr \NC \syntax{<node>} \NC \NC \NR -\NC width \NC number \NC \NC \NR -\NC num \NC \syntax{<kernel>} \NC \NC \NR -\NC denom \NC \syntax{<kernel>} \NC \NC \NR -\NC left \NC \syntax{<delim>} \NC \NC \NR -\NC right \NC \syntax{<delim>} \NC \NC \NR +\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR +\NC attr \NC node \NC list of attributes \NC \NR +\NC width \NC number \NC (optional) width of the fraction \NC \NR +\NC num \NC kernel node \NC numerator \NC \NR +\NC denom \NC kernel node \NC denominator \NC \NR +\NC left \NC delimiter node \NC left side symbol \NC \NR +\NC right \NC delimiter node \NC right side symbol\NC \NR \stoptabulate A warning: never assign a node list to the num, or denom field unless you are @@ -728,18 +574,11 @@ sure its internal link structure is correct, otherwise an error may be result. \subsubsubsection{fence nodes} -Valid fields: \showfields{fence}\crlf -Id: \showid{fence} - \starttabulate[|lT|l|p|] -\NC \ssbf field \NC \bf type \NC \bf explanation \NC \NR -\NC subtype \NC number \NC - \type {1} = \type {\left}, - \type {2} = \type {\middle}, - \type {3} = \type {\right} -\NC \NR -\NC attr \NC \syntax{<node>} \NC \NC \NR -\NC delim \NC \syntax{<delim>} \NC \NC \NR +\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR +\NC subtype \NC number \NC \showsubtypes{fence} \NC \NR +\NC attr \NC node \NC list of attributes \NC \NR +\NC delim \NC delimiter node \NC delimiter specification \NC \NR \stoptabulate \subsection{whatsit nodes} @@ -756,410 +595,302 @@ Whatsit nodes come in many subtypes that you can ask for by running \stopluacode . % period -\subsubsection{open nodes} +\subsubsection{front|-|end whatits} -Valid fields: \showfields{whatsit,open}\crlf -Id: \showid{whatsit,open} +\subsubsubsection{open whatsits} \starttabulate[|lT|l|p|] -\NC \ssbf field \NC \bf type \NC \bf explanation \NC \NR -\NC attr \NC \syntax{<node>} \NC \NC \NR -\NC stream \NC number \NC \TEX's stream id number \NC \NR -\NC name \NC string \NC file name \NC \NR -\NC ext \NC string \NC file extension \NC \NR -\NC area \NC string \NC file area (this may become obsolete) \NC \NR +\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR +\NC attr \NC node \NC list of attributes \NC \NR +\NC stream \NC number \NC \TEX's stream id number \NC \NR +\NC name \NC string \NC file name \NC \NR +\NC ext \NC string \NC file extension \NC \NR +\NC area \NC string \NC file area (this may become obsolete) \NC \NR \stoptabulate -\subsubsection{write nodes} - -Valid fields: \showfields{whatsit,write}\crlf -Id: \showid{whatsit,write} +\subsubsubsection{write whatsits} \starttabulate[|lT|l|p|] -\NC \ssbf field \NC \bf type \NC \bf explanation \NC \NR -\NC attr \NC \syntax{<node>} \NC \NC \NR -\NC stream \NC number \NC \TEX's stream id number \NC \NR -\NC data \NC table \NC a table representing the token list - to be written \NC \NR +\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR +\NC attr \NC node \NC list of attributes \NC \NR +\NC stream \NC number \NC \TEX's stream id number \NC \NR +\NC data \NC table \NC a table representing the token list to be written \NC \NR \stoptabulate -\subsubsection{close nodes} - -Valid fields: \showfields{whatsit,close}\crlf -Id: \showid{whatsit,close} +\subsubsubsection{close whatsits} \starttabulate[|lT|l|p|] -\NC \ssbf field \NC \bf type \NC \bf explanation \NC \NR -\NC attr \NC \syntax{<node>} \NC \NC \NR -\NC stream \NC number \NC \TEX's stream id number \NC \NR +\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR +\NC attr \NC node \NC list of attributes \NC \NR +\NC stream \NC number \NC \TEX's stream id number \NC \NR \stoptabulate -\subsubsection{special nodes} +\subsubsubsection{user_defined whatits} -Valid fields: \showfields{whatsit,special}\crlf -Id: \showid{whatsit,special} +User|-|defined whatsit nodes can only be created and handled from \LUA\ code. In +effect, they are an extension to the extension mechanism. The \LUATEX\ engine +will simply step over such whatsits without ever looking at the contents. \starttabulate[|lT|l|p|] -\NC \ssbf field \NC \bf type \NC \bf explanation \NC \NR -\NC attr \NC \syntax{<node>} \NC \NC \NR -\NC data \NC string \NC the \type {\special} information \NC \NR +\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR +\NC attr \NC node \NC list of attributes \NC \NR +\NC user_id \NC number \NC id number \NC \NR +\NC type \NC number \NC type of the value \NC \NR +\NC value \NC number \NC a \LUA\ number \NC \NR +\NC \NC node \NC a node list \NC \NR +\NC \NC string \NC a \LUA\ string \NC \NR +\NC \NC table \NC a \LUA\ table \NC \NR \stoptabulate -\subsubsection{boundary nodes} - -Valid fields: \showfields{boundary}\crlf -Id: \showid{boundary} - -This node relates to the \type {\noboundary} primitive but you can use it for -your own purpose too, in which case \type {\boundary} can come in handy. - -\subsubsection{language nodes} - -\LUATEX\ does not have language whatsits any more. All language information is -already present inside the glyph nodes themselves. This whatsit subtype will be -removed in the next release. +The \type {type} can have one of five distinct values: -\subsubsection{local_par nodes} +\starttabulate[|lT|p|] +\NC \rmbf value \NC \bf explanation \NC \NR +\NC 97 \NC list of attributes \NC \NR +\NC 100 \NC a \LUA\ number \NC \NR +\NC 110 \NC a node list \NC \NR +\NC 115 \NC a \LUA\ string \NC \NR +\NC 116 \NC a \LUA\ token list in \LUA\ table form \NC \NR +\stoptabulate -Valid fields: \showfields{local_par}\crlf -Id: \showid{local_par} +\subsubsubsection{save_pos whatsits} \starttabulate[|lT|l|p|] -\NC \ssbf field \NC \bf type \NC \bf explanation \NC \NR -\NC attr \NC \syntax{<node>} \NC \NC \NR -\NC pen_inter \NC number \NC local interline penalty (from \type - {\localinterlinepenalty}) \NC \NR -\NC pen_broken \NC number \NC local broken penalty (from \type - {\localbrokenpenalty}) \NC \NR -\NC dir \NC string \NC the direction of this par. see~\in - [dirnodes] \NC \NR -\NC box_left \NC \syntax{<node>} \NC the \type {\localleftbox} \NC \NR -\NC box_left_width \NC number \NC width of the \type {\localleftbox} \NC \NR -\NC box_right \NC \syntax{<node>} \NC the \type {\localrightbox} -\NC \NR -\NC box_right_width \NC number \NC width of the \type {\localrightbox} \NC \NR +\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR +\NC attr \NC node \NC list of attributes \NC \NR \stoptabulate -A warning: never assign a node list to the \type {box_left} or \type {box_right} -field unless you are sure its internal link structure is correct, otherwise an -error may be result. - -\subsubsection[dirnodes]{dir nodes} - -Valid fields: \showfields{dir}\crlf -Id: \showid{dir} +\subsubsubsection{late_lua whatsits} \starttabulate[|lT|l|p|] -\NC \ssbf field \NC \bf type \NC \bf explanation \NC \NR -\NC attr \NC \syntax{<node>} \NC \NC \NR -\NC dir \NC string \NC the direction (but see below) \NC \NR -\NC level \NC number \NC nesting level of this direction whatsit \NC \NR -\NC dvi_ptr \NC number \NC a saved \DVI\ buffer byte offset \NC \NR -\NC dir_h \NC number \NC a saved \DVI\ position \NC \NR +\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR +\NC attr \NC node \NC list of attributes \NC \NR +\NC data \NC string \NC data to execute \NC \NR +\NC string \NC string \NC data to execute \NC \NR +\NC name \NC string \NC the name to use for \LUA\ error reporting \NC \NR \stoptabulate -A note on \type {dir} strings. Direction specifiers are three|-|letter -combinations of \type {T}, \type {B}, \type {R}, and \type {L}. - -These are built up out of three separate items: +The difference between \type {data} and \type {string} is that on assignment, the +\type {data} field is converted to a token list, cf. use as \type {\latelua}. The +\type {string} version is treated as a literal string. -\startitemize[packed] -\startitem - the first is the direction of the \quote{top} of paragraphs. -\stopitem -\startitem - the second is the direction of the \quote{start} of lines. -\stopitem -\startitem - the third is the direction of the \quote{top} of glyphs. -\stopitem -\stopitemize +\subsubsection{\DVI\ backend whatits} -However, only four combinations are accepted: \type {TLT}, \type {TRT}, \type -{RTT}, and \type {LTL}. +\subsubsection{special whatits} -Inside actual \type {dir} whatsit nodes, the representation of \type {dir} is not -a three-letter but a four|-|letter combination. The first character in this case -is always either \type {+} or \type {-}, indicating whether the value is pushed -or popped from the direction stack. +\starttabulate[|lT|l|p|] +\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR +\NC attr \NC node \NC list of attributes \NC \NR +\NC data \NC string \NC the \type {\special} information \NC \NR +\stoptabulate -\subsubsection{pdf_literal nodes} +\subsubsection{\PDF\ backend whatits} -Valid fields: \showfields{whatsit,pdf_literal}\crlf -Id: \showid{whatsit,pdf_literal} +\subsubsubsection{pdf_literal whatits} \starttabulate[|lT|l|p|] -\NC \ssbf field \NC \bf type \NC \bf explanation \NC \NR -\NC attr \NC \syntax{<node>} \NC \NC \NR -\NC mode \NC number \NC the \quote {mode} setting of this - literal \NC \NR -\NC data \NC string \NC the \type {\pdfliteral} information \NC \NR +\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR +\NC attr \NC node \NC list of attributes \NC \NR +\NC mode \NC number \NC the \quote {mode} setting of this literal \NC \NR +\NC data \NC string \NC the \type {\pdfliteral} information \NC \NR \stoptabulate -Mode values: +Possible mode values are: \starttabulate[|lT|p|] -\NC \ssbf value \NC \ssbf corresponding \type {\pdftex} keyword \NC \NR -\NC 0 \NC setorigin \NC \NR -\NC 1 \NC page \NC \NR -\NC 2 \NC direct \NC \NR +\NC \rmbf value \NC \rmbf \PDFTEX\ keyword \NC \NR +\NC 0 \NC setorigin \NC \NR +\NC 1 \NC page \NC \NR +\NC 2 \NC direct \NC \NR \stoptabulate -\subsubsection{pdf_refobj nodes} - -Valid fields: \showfields{whatsit,pdf_refobj}\crlf -Id: \showid{whatsit,pdf_refobj} +\subsubsubsection{pdf_refobj whatits} \starttabulate[|lT|l|p|] -\NC \ssbf field \NC \bf type \NC \bf explanation \NC \NR -\NC attr \NC \syntax{<node>} \NC \NC \NR -\NC objnum \NC number \NC the referenced \PDF\ object number \NC \NR +\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR +\NC attr \NC node \NC list of attributes \NC \NR +\NC objnum \NC number \NC the referenced \PDF\ object number \NC \NR \stoptabulate -\subsubsection{pdf_annot nodes} - -Valid fields: \showfields{whatsit,pdf_annot}\crlf -Id: \showid{whatsit,pdf_annot} +\subsubsubsection{pdf_annot whatits} \starttabulate[|lT|l|p|] -\NC \ssbf field \NC \bf type \NC \bf explanation \NC \NR -\NC attr \NC \syntax{<node>} \NC \NC \NR -\NC width \NC number \NC \NC \NR -\NC height \NC number \NC \NC \NR -\NC depth \NC number \NC \NC \NR -\NC objnum \NC number \NC the referenced \PDF\ object number \NC \NR -\NC data \NC string \NC the annotation data \NC \NR +\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR +\NC attr \NC node \NC list of attributes \NC \NR +\NC width \NC number \NC the width (not used in calculations) \NC \NR +\NC height \NC number \NC the height (not used in calculations) \NC \NR +\NC depth \NC number \NC the depth (not used in calculations) \NC \NR +\NC objnum \NC number \NC the referenced \PDF\ object number \NC \NR +\NC data \NC string \NC the annotation data \NC \NR \stoptabulate -\subsubsection{pdf_start_link nodes} - -Valid fields: \showfields{whatsit,pdf_start_link}\crlf -Id: \showid{whatsit,pdf_start_link} +\subsubsubsection{pdf_start_link whatits} \starttabulate[|lT|l|p|] -\NC \ssbf field \NC \bf type \NC \bf explanation \NC \NR -\NC attr \NC \syntax{<node>} \NC \NC \NR -\NC width \NC number \NC \NC \NR -\NC height \NC number \NC \NC \NR -\NC depth \NC number \NC \NC \NR -\NC objnum \NC number \NC the referenced \PDF\ object number \NC \NR -\NC link_attr \NC table \NC the link attribute token list \NC \NR -\NC action \NC \syntax{<node>} \NC the action to perform \NC \NR +\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR +\NC attr \NC node \NC list of attributes \NC \NR +\NC width \NC number \NC the width (not used in calculations) \NC \NR +\NC height \NC number \NC the height (not used in calculations) \NC \NR +\NC depth \NC number \NC the depth (not used in calculations) \NC \NR +\NC objnum \NC number \NC the referenced \PDF\ object number \NC \NR +\NC link_attr \NC table \NC the link attribute token list \NC \NR +\NC action \NC node \NC the action to perform \NC \NR \stoptabulate -\subsubsection{pdf_end_link nodes} - -Valid fields: \showfields{whatsit,pdf_end_link}\crlf -Id: \showid{whatsit,pdf_end_link} +\subsubsubsection{pdf_end_link whatits} \starttabulate[|lT|l|p|] -\NC \ssbf field \NC \bf type \NC \bf explanation \NC \NR -\NC attr \NC \syntax{<node>} \NC \NC \NR +\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR +\NC attr \NC node \NC \NC \NR \stoptabulate -\subsubsection{pdf_dest nodes} - -Valid fields: \showfields{whatsit,pdf_dest}\crlf -Id: \showid{whatsit,pdf_dest} +\subsubsubsection{pdf_dest whatits} \starttabulate[|lT|l|p|] -\NC \ssbf field \NC \bf type \NC \bf explanation \NC \NR -\NC attr \NC \syntax{<node>} \NC \NC \NR -\NC width \NC number \NC \NC \NR -\NC height \NC number \NC \NC \NR -\NC depth \NC number \NC \NC \NR -\NC named_id \NC number \NC is the \type {dest_id} a string value? \NC \NR -\NC dest_id \NC number \NC the destination id \NC \NR -\NC \NC string \NC the destination name \NC \NR -\NC dest_type \NC number \NC type of destination \NC \NR -\NC xyz_zoom \NC number \NC \NC \NR -\NC objnum \NC number \NC the \PDF\ object number \NC \NR +\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR +\NC attr \NC node \NC list of attributes \NC \NR +\NC width \NC number \NC the width (not used in calculations) \NC \NR +\NC height \NC number \NC the height (not used in calculations) \NC \NR +\NC depth \NC number \NC the depth (not used in calculations) \NC \NR +\NC named_id \NC number \NC is the \type {dest_id} a string value? \NC \NR +\NC dest_id \NC number \NC the destination id \NC \NR +\NC \NC string \NC the destination name \NC \NR +\NC dest_type \NC number \NC type of destination \NC \NR +\NC xyz_zoom \NC number \NC the zoom factor (times 1000) \NC \NR +\NC objnum \NC number \NC the \PDF\ object number \NC \NR \stoptabulate -\subsubsection{pdf_action nodes} - -Valid fields: \showfields{whatsit,pdf_action}\crlf -Id: \showid{whatsit,pdf_action} +\subsubsubsection{pdf_action whatits} These are a special kind of item that only appears inside \PDF\ start link objects. \starttabulate[|lT|l|p|] -\NC \ssbf field \NC \bf type \NC \bf explanation \NC \NR -\NC action_type \NC number \NC \NC \NR -\NC action_id \NC number or string \NC \NC \NR -\NC named_id \NC number \NC \NC \NR -\NC file \NC string \NC \NC \NR -\NC new_window \NC number \NC \NC \NR -\NC data \NC string \NC \NC \NR -\NC ref_count \NC number \NC read-only \NC \NR +\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR +\NC action_type \NC number \NC the kind of action involved \NC \NR +\NC action_id \NC number or string \NC token list reference or string \NC \NR +\NC named_id \NC number \NC the index of the destination \NC \NR +\NC file \NC string \NC the target filename \NC \NR +\NC new_window \NC number \NC the window state of the target \NC \NR +\NC data \NC string \NC the name of the destination \NC \NR \stoptabulate -\subsubsection{pdf_thread nodes} +Valid action types are: -Valid fields: \showfields{whatsit,pdf_thread}\crlf -Id: \showid{whatsit,pdf_thread} - -\starttabulate[|lT|l|p|] -\NC \ssbf field \NC \bf type \NC \bf explanation \NC \NR -\NC attr \NC \syntax{<node>} \NC \NC \NR -\NC width \NC number \NC \NC \NR -\NC height \NC number \NC \NC \NR -\NC depth \NC number \NC \NC \NR -\NC named_id \NC number \NC is \type {tread_id} a string value? \NC \NR -\NC tread_id \NC number \NC the thread id \NC \NR -\NC \NC string \NC the thread name \NC \NR -\NC thread_attr \NC number \NC extra thread information \NC \NR +\starttabulate[|lT|lT|] +\NC 0 \NC page \NC \NR +\NC 1 \NC goto \NC \NR +\NC 2 \NC thread \NC \NR +\NC 3 \NC user \NC \NR \stoptabulate -\subsubsection{pdf_start_thread nodes} - -Valid fields: \showfields{whatsit,pdf_start_thread}\crlf -Id: \showid{whatsit,pdf_start_thread} +Valid window types are: -\starttabulate[|lT|l|p|] -\NC \ssbf field \NC \bf type \NC \bf explanation \NC \NR -\NC attr \NC \syntax{<node>} \NC \NC \NR -\NC width \NC number \NC \NC \NR -\NC height \NC number \NC \NC \NR -\NC depth \NC number \NC \NC \NR -\NC named_id \NC number \NC is \type {tread_id} a string value? \NC \NR -\NC tread_id \NC number \NC the thread id \NC \NR -\NC \NC string \NC the thread name \NC \NR -\NC thread_attr \NC number \NC extra thread information \NC \NR +\starttabulate[|lT|lT|] +\NC 0 \NC notset \NC \NR +\NC 1 \NC new \NC \NR +\NC 2 \NC nonew \NC \NR \stoptabulate -\subsubsection{pdf_end_thread nodes} - -Valid fields: \showfields{whatsit,pdf_end_thread}\crlf -Id: \showid{whatsit,pdf_end_thread} +\subsubsubsection{pdf_thread whatits} \starttabulate[|lT|l|p|] -\NC \ssbf field \NC \bf type \NC \bf explanation \NC \NR -\NC attr \NC \syntax{<node>} \NC \NC \NR +\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR +\NC attr \NC node \NC list of attributes \NC \NR +\NC width \NC number \NC the width (not used in calculations) \NC \NR +\NC height \NC number \NC the height (not used in calculations) \NC \NR +\NC depth \NC number \NC the depth (not used in calculations) \NC \NR +\NC named_id \NC number \NC is \type {tread_id} a string value? \NC \NR +\NC tread_id \NC number \NC the thread id \NC \NR +\NC \NC string \NC the thread name \NC \NR +\NC thread_attr \NC number \NC extra thread information \NC \NR \stoptabulate -\subsubsection{save_pos nodes} - -Valid fields: \showfields{whatsit,save_pos}\crlf -Id: \showid{whatsit,save_pos} +\subsubsubsection{pdf_start_thread whatits} \starttabulate[|lT|l|p|] -\NC \ssbf field \NC \bf type \NC \bf explanation \NC \NR -\NC attr \NC \syntax{<node>} \NC \NC \NR +\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR +\NC attr \NC node \NC list of attributes \NC \NR +\NC width \NC number \NC the width (not used in calculations) \NC \NR +\NC height \NC number \NC the height (not used in calculations) \NC \NR +\NC depth \NC number \NC the depth (not used in calculations) \NC \NR +\NC named_id \NC number \NC is \type {tread_id} a string value? \NC \NR +\NC tread_id \NC number \NC the thread id \NC \NR +\NC \NC string \NC the thread name \NC \NR +\NC thread_attr \NC number \NC extra thread information \NC \NR \stoptabulate -\subsubsection{late_lua nodes} - -Valid fields: \showfields{whatsit,late_lua}\crlf -Id: \showid{whatsit,late_lua} +\subsubsubsection{pdf_end_thread whatits} \starttabulate[|lT|l|p|] -\NC \ssbf field \NC \bf type \NC \bf explanation \NC \NR -\NC attr \NC \syntax{<node>} \NC \NC \NR -\NC data \NC string \NC data to execute \NC \NR -\NC string \NC string \NC data to execute \NC \NR -\NC name \NC string \NC the name to use for \LUA\ error reporting \NC \NR +\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR +\NC attr \NC node \NC \NC \NR \stoptabulate -The difference between \type {data} and \type {string} is that on assignment, the -\type {data} field is converted to a token list, cf. use as \type {\latelua}. The -\type {string} version is treated as a literal string. - -\subsubsection{pdf_colorstack nodes} - -Valid fields: \showfields{whatsit,pdf_colorstack}\crlf -Id: \showid{whatsit,pdf_colorstack} +\subsubsubsection{pdf_colorstack whatits} \starttabulate[|lT|l|p|] -\NC \ssbf field \NC \bf type \NC \bf explanation \NC \NR -\NC attr \NC \syntax{<node>} \NC \NC \NR -\NC stack \NC number \NC colorstack id number \NC \NR -\NC command \NC number \NC command to execute \NC \NR -\NC data \NC string \NC data \NC \NR +\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR +\NC attr \NC node \NC list of attributes \NC \NR +\NC stack \NC number \NC colorstack id number \NC \NR +\NC command \NC number \NC command to execute \NC \NR +\NC data \NC string \NC data \NC \NR \stoptabulate -\subsubsection{pdf_setmatrix nodes} - -Valid fields: \showfields{whatsit,pdf_setmatrix}\crlf -Id: \showid{whatsit,pdf_setmatrix} +\subsubsubsection{pdf_setmatrix whatits} \starttabulate[|lT|l|p|] -\NC \ssbf field \NC \bf type \NC \bf explanation \NC \NR -\NC attr \NC \syntax{<node>} \NC \NC \NR -\NC data \NC string \NC data \NC \NR +\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR +\NC attr \NC node \NC list of attributes \NC \NR +\NC data \NC string \NC data \NC \NR \stoptabulate -\subsubsection{pdf_save nodes} - -Valid fields: \showfields{whatsit,pdf_save}\crlf -Id: \showid{whatsit,pdf_save} +\subsubsubsection{pdf_save whatits} \starttabulate[|lT|l|p|] -\NC \ssbf field \NC \bf type \NC \bf explanation \NC \NR -\NC attr \NC \syntax{<node>} \NC \NC \NR +\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR +\NC attr \NC node \NC list of attributes \NC \NR \stoptabulate -\subsubsection{pdf_restore nodes} - -Valid fields: \showfields{whatsit,pdf_restore}\crlf -Id: \showid{whatsit,pdf_restore} +\subsubsubsection{pdf_restore whatits} \starttabulate[|lT|l|p|] -\NC \ssbf field \NC \bf type \NC \bf explanation \NC \NR -\NC attr \NC \syntax{<node>} \NC \NC \NR -\stoptabulate - -\subsubsection{user_defined nodes} - -User|-|defined whatsit nodes can only be created and handled from \LUA\ code. In -effect, they are an extension to the extension mechanism. The \LUATEX\ engine -will simply step over such whatsits without ever looking at the contents. - -Valid fields: \showfields{whatsit,user_defined}\crlf -Id: \showid{whatsit,user_defined} - -\starttabulate[|lT|l|p|] -\NC \ssbf field \NC \bf type \NC \bf explanation \NC \NR -\NC attr \NC \syntax{<node>} \NC \NC \NR -\NC user_id \NC number \NC id number \NC \NR -\NC type \NC number \NC type of the value \NC \NR -\NC value \NC number \NC \NC \NR -\NC \NC string \NC \NC \NR -\NC \NC \syntax{<node>} \NC \NC \NR -\NC \NC table \NC \NC \NR -\stoptabulate - -The \type {type} can have one of five distinct values: - -\starttabulate[|lT|p|] -\NC \ssbf value \NC \bf explanation \NC \NR -\NC 97 \NC the value is an attribute node list \NC \NR -\NC 100 \NC the value is a number \NC \NR -\NC 110 \NC the value is a node list \NC \NR -\NC 115 \NC the value is a string \NC \NR -\NC 116 \NC the value is a token list in \LUA\ table form \NC \NR +\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR +\NC attr \NC node \NC list of attributes \NC \NR \stoptabulate \section{Two access models} Deep down in \TEX\ a node has a number which is an numeric 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. So, if -you use the direct model, even if you know that you 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. +the reasons why plugging in callbacks that operate on nodes is quite fast too. +Each node gets a number that is in fact an index in the memory table and that +number often gets reported when you print node related information. + +There are two access models, a robust one using a so called user data object that +provides a virtual interface to the internal nodes, and a more direct access which +uses the node numbers directly. The first model provide key based access while +the second always accesses fields via functions: + +\starttyping +nodeobject.char +getfield(nodenumber,"char") +\stoptyping + +If you use the direct model, even if you know that you 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, multiplying a node number makes no sense. So our advice is: use the indexed (table) 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). +the direct one when speed might be an real 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 @@ -1217,14 +948,17 @@ If performance matters you can use an function instead: The direct variants also have setters, where the discretionary setter takes three (optional) arguments plus an optional fourth indicating the subtype. -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: +It doesn't make sense to add getters for all fields, also because some are not +unique to one node type. 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{$-$} +% \startcolumns[balance=yes] + +\def\yes{$+$} \def\nop{$-$} \starttabulate[|T|c|c|] \HL @@ -1313,7 +1047,7 @@ summarized this: \NC \type {glue_is_zero} \NC \yes \NC \yes \NC \NR \stoptabulate -\stop +% \stopcolumns 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 @@ -1329,6 +1063,738 @@ true for the \type {width}, \type {height} and \type {depth} of glue nodes. Thes actually access the spec node properties, and here we can set as well as get the values. +\section{The \type {node} library} + +The \type {node} library contains functions that facilitate dealing with (lists +of) nodes and their values. They allow you to create, alter, copy, delete, and +insert \LUATEX\ node objects, the core objects within the typesetter. + +\LUATEX\ nodes are represented in \LUA\ as userdata with the metadata type +\type {luatex.node}. The various parts within a node can be accessed using +named fields. + +Each node has at least the three fields \type {next}, \type {id}, and \type +{subtype}: + +\startitemize[intro] + +\startitem + The \type {next} field returns the userdata object for the next node in a + linked list of nodes, or \type {nil}, if there is no next node. +\stopitem + +\startitem + The \type {id} indicates \TEX's \quote{node type}. The field \type {id} has a + numeric value for efficiency reasons, but some of the library functions also + accept a string value instead of \type {id}. +\stopitem + +\startitem + The \type {subtype} is another number. It often gives further information + about a node of a particular \type {id}, but it is most important when + dealing with \quote {whatsits}, because they are differentiated solely based + on their \type {subtype}. +\stopitem + +\stopitemize + +The other available fields depend on the \type {id} (and for \quote {whatsits}, +the \type {subtype}) of the node. Further details on the various fields and their +meanings are given in~\in{chapter}[nodes]. + +Support for \type {unset} (alignment) nodes is partial: they can be queried and +modified from \LUA\ code, but not created. + +Nodes can be compared to each other, but: you are actually comparing indices into +the node memory. This means that equality tests can only be trusted under very +limited conditions. It will not work correctly in any situation where one of the +two nodes has been freed and|/|or reallocated: in that case, there will be false +positives. + +At the moment, memory management of nodes should still be done explicitly by the +user. Nodes are not \quote {seen} by the \LUA\ garbage collector, so you have to +call the node freeing functions yourself when you are no longer in need of a node +(list). Nodes form linked lists without reference counting, so you have to be +careful that when control returns back to \LUATEX\ itself, you have not deleted +nodes that are still referenced from a \type {next} pointer elsewhere, and that +you did not create nodes that are referenced more than once. + +There are statistics available with regards to the allocated node memory, which +can be handy for tracing. + +\subsection{Node handling functions} + +\subsubsection{\type {node.is_node}} + +\startfunctioncall +<boolean> t = + node.is_node(<any> item) +\stopfunctioncall + +This function returns true if the argument is a userdata object of +type \type {<node>}. + +\subsubsection{\type {node.types}} + +\startfunctioncall +<table> t = + node.types() +\stopfunctioncall + +This function returns an array that maps node id numbers to node type strings, +providing an overview of the possible top|-|level \type {id} types. + +\subsubsection{\type {node.whatsits}} + +\startfunctioncall +<table> t = + node.whatsits() +\stopfunctioncall + +\TEX's \quote{whatsits} all have the same \type {id}. The various subtypes are +defined by their \type {subtype} fields. The function is much like \type +{node.types}, except that it provides an array of \type {subtype} mappings. + +\subsubsection{\type {node.id}} + +\startfunctioncall +<number> id = + node.id(<string> type) +\stopfunctioncall + +This converts a single type name to its internal numeric representation. + +\subsubsection{\type {node.subtype}} + +\startfunctioncall +<number> subtype = + node.subtype(<string> type) +\stopfunctioncall + +This converts a single whatsit name to its internal numeric representation (\type +{subtype}). + +\subsubsection{\type {node.type}} + +\startfunctioncall +<string> type = + node.type(<any> n) +\stopfunctioncall + +In the argument is a number, then this function converts an internal numeric +representation to an external string representation. Otherwise, it will return +the string \type {node} if the object represents a node, and \type {nil} +otherwise. + +\subsubsection{\type {node.fields}} + +\startfunctioncall +<table> t = + node.fields(<number> id) +<table> t = + node.fields(<number> id, <number> subtype) +\stopfunctioncall + +This function returns an array of valid field names for a particular type of +node. If you want to get the valid fields for a \quote {whatsit}, you have to +supply the second argument also. In other cases, any given second argument will +be silently ignored. + +This function accepts string \type {id} and \type {subtype} values as well. + +\subsubsection{\type {node.has_field}} + +\startfunctioncall +<boolean> t = + node.has_field(<node> n, <string> field) +\stopfunctioncall + +This function returns a boolean that is only true if \type {n} is +actually a node, and it has the field. + +\subsubsection{\type {node.new}} + +\startfunctioncall +<node> n = + node.new(<number> id) +<node> n = + node.new(<number> id, <number> subtype) +\stopfunctioncall + +Creates a new node. All of the new node's fields are initialized to either zero +or \type {nil} except for \type {id} and \type {subtype} (if supplied). If you +want to create a new whatsit, then the second argument is required, otherwise it +need not be present. As with all node functions, this function creates a node on +the \TEX\ level. + +This function accepts string \type {id} and \type {subtype} values as well. + +\subsubsection{\type {node.free}} + +\startfunctioncall +node.free(<node> n) +\stopfunctioncall + +Removes the node \type {n} from \TEX's memory. Be careful: no checks are done on +whether this node is still pointed to from a register or some \type {next} field: +it is up to you to make sure that the internal data structures remain correct. + +\subsubsection{\type {node.flush_list}} + +\startfunctioncall +node.flush_list(<node> n) +\stopfunctioncall + +Removes the node list \type {n} and the complete node list following \type {n} +from \TEX's memory. Be careful: no checks are done on whether any of these nodes +is still pointed to from a register or some \type {next} field: it is up to you +to make sure that the internal data structures remain correct. + +\subsubsection{\type {node.copy}} + +\startfunctioncall +<node> m = + node.copy(<node> n) +\stopfunctioncall + +Creates a deep copy of node \type {n}, including all nested lists as in the case +of a hlist or vlist node. Only the \type {next} field is not copied. + +\subsubsection{\type {node.copy_list}} + +\startfunctioncall +<node> m = + node.copy_list(<node> n) +<node> m = + node.copy_list(<node> n, <node> m) +\stopfunctioncall + +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. +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 +needed copying and freeing takes place automatically. + +\subsubsection{\type {node.next}} + +\startfunctioncall +<node> m = + node.next(<node> n) +\stopfunctioncall + +Returns the node following this node, or \type {nil} if there is no such node. + +\subsubsection{\type {node.prev}} + +\startfunctioncall +<node> m = + node.prev(<node> n) +\stopfunctioncall + +Returns the node preceding this node, or \type {nil} if there is no such node. + +\subsubsection{\type {node.current_attr}} + +\startfunctioncall +<node> m = + node.current_attr() +\stopfunctioncall + +Returns the currently active list of attributes, if there is one. + +The intended usage of \type {current_attr} is as follows: + +\starttyping +local x1 = node.new("glyph") +x1.attr = node.current_attr() +local x2 = node.new("glyph") +x2.attr = node.current_attr() +\stoptyping + +or: + +\starttyping +local x1 = node.new("glyph") +local x2 = node.new("glyph") +local ca = node.current_attr() +x1.attr = ca +x2.attr = ca +\stoptyping + +The attribute lists are ref counted and the assignment takes care of incrementing +the refcount. You cannot expect the value \type {ca} to be valid any more when +you assign attributes (using \type {tex.setattribute}) or when control has been +passed back to \TEX. + +Note: this function is somewhat experimental, and it returns the {\it 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. + +\subsubsection{\type {node.hpack}} + +\startfunctioncall +<node> h, <number> b = + node.hpack(<node> n) +<node> h, <number> b = + node.hpack(<node> n, <number> w, <string> info) +<node> h, <number> b = + node.hpack(<node> n, <number> w, <string> info, <string> dir) +\stopfunctioncall + +This function creates a new hlist by packaging the list that begins at node \type +{n} into a horizontal box. With only a single argument, this box is created using +the natural width of its components. In the three argument form, \type {info} +must be either \type {additional} or \type {exactly}, and \type {w} is the +additional (\type {\hbox spread}) or exact (\type {\hbox to}) width to be used. The +second return value is the badness of the generated box. + +Caveat: at this moment, there can be unexpected side|-|effects to this function, +like updating some of the \type {\marks} and \type {\inserts}. Also note that the +content of \type {h} is the original node list \type {n}: if you call \type +{node.free(h)} you will also free the node list itself, unless you explicitly set +the \type {list} field to \type {nil} beforehand. And in a similar way, calling +\type {node.free(n)} will invalidate \type {h} as well! + +\subsubsection{\type {node.vpack}} + +\startfunctioncall +<node> h, <number> b = + node.vpack(<node> n) +<node> h, <number> b = + node.vpack(<node> n, <number> w, <string> info) +<node> h, <number> b = + node.vpack(<node> n, <number> w, <string> info, <string> dir) +\stopfunctioncall + +This function creates a new vlist by packaging the list that begins at node \type +{n} into a vertical box. With only a single argument, this box is created using +the natural height of its components. In the three argument form, \type {info} +must be either \type {additional} or \type {exactly}, and \type {w} is the +additional (\type {\vbox spread}) or exact (\type {\vbox to}) height to be used. + +The second return value is the badness of the generated box. + +See the description of \type {node.hpack()} for a few memory allocation caveats. + +\subsubsection{\type {node.dimensions}} + +\startfunctioncall +<number> w, <number> h, <number> d = + node.dimensions(<node> n) +<number> w, <number> h, <number> d = + node.dimensions(<node> n, <string> dir) +<number> w, <number> h, <number> d = + node.dimensions(<node> n, <node> t) +<number> w, <number> h, <number> d = + node.dimensions(<node> n, <node> t, <string> dir) +\stopfunctioncall + +This function calculates the natural in-line dimensions of the node list starting +at node \type {n} and terminating just before node \type {t} (or the end of the +list, if there is no second argument). The return values are scaled points. An +alternative format that starts with glue parameters as the first three arguments +is also possible: + +\startfunctioncall +<number> w, <number> h, <number> d = + node.dimensions(<number> glue_set, <number> glue_sign, <number> glue_order, + <node> n) +<number> w, <number> h, <number> d = + node.dimensions(<number> glue_set, <number> glue_sign, <number> glue_order, + <node> n, <string> dir) +<number> w, <number> h, <number> d = + node.dimensions(<number> glue_set, <number> glue_sign, <number> glue_order, + <node> n, <node> t) +<number> w, <number> h, <number> d = + node.dimensions(<number> glue_set, <number> glue_sign, <number> glue_order, + <node> n, <node> t, <string> dir) +\stopfunctioncall + +This calling method takes glue settings into account and is especially useful for +finding the actual width of a sublist of nodes that are already boxed, for +example in code like this, which prints the width of the space in between the +\type {a} and \type {b} as it would be if \type {\box0} was used as-is: + +\starttyping +\setbox0 = \hbox to 20pt {a b} + +\directlua{print (node.dimensions( + tex.box[0].glue_set, + tex.box[0].glue_sign, + tex.box[0].glue_order, + tex.box[0].head.next, + node.tail(tex.box[0].head) +)) } +\stoptyping + +\subsubsection{\type {node.mlist_to_hlist}} + +\startfunctioncall +<node> h = + node.mlist_to_hlist(<node> n, <string> display_type, <boolean> penalties) +\stopfunctioncall + +This runs the internal mlist to hlist conversion, converting the math list in +\type {n} into the horizontal list \type {h}. The interface is exactly the same +as for the callback \type {mlist_to_hlist}. + +\subsubsection{\type {node.slide}} + +\startfunctioncall +<node> m = + node.slide(<node> n) +\stopfunctioncall + +Returns the last node of the node list that starts at \type {n}. As a +side|-|effect, it also creates a reverse chain of \type {prev} pointers between +nodes. + +\subsubsection{\type {node.tail}} + +\startfunctioncall +<node> m = + node.tail(<node> n) +\stopfunctioncall + +Returns the last node of the node list that starts at \type {n}. + +\subsubsection{\type {node.length}} + +\startfunctioncall +<number> i = + node.length(<node> n) +<number> i = + node.length(<node> n, <node> m) +\stopfunctioncall + +Returns the number of nodes contained in the node list that starts at \type {n}. +If \type {m} is also supplied it stops at \type {m} instead of at the end of the +list. The node \type {m} is not counted. + +\subsubsection{\type {node.count}} + +\startfunctioncall +<number> i = + node.count(<number> id, <node> n) +<number> i = + node.count(<number> id, <node> n, <node> m) +\stopfunctioncall + +Returns the number of nodes contained in the node list that starts at \type {n} +that have a matching \type {id} field. If \type {m} is also supplied, counting +stops at \type {m} instead of at the end of the list. The node \type {m} is not +counted. + +This function also accept string \type {id}'s. + +\subsubsection{\type {node.traverse}} + +\startfunctioncall +<node> t = + node.traverse(<node> n) +\stopfunctioncall + +This is a \LUA\ iterator that loops over the node list that starts at \type {n}. +Typically code looks like this: + +\starttyping +for n in node.traverse(head) do + ... +end +\stoptyping + +is functionally equivalent to: + +\starttyping +do + local n + local function f (head,var) + local t + if var == nil then + t = head + else + t = var.next + end + return t + end + while true do + n = f (head, n) + if n == nil then break end + ... + end +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 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. + +\subsubsection{\type {node.traverse_id}} + +\startfunctioncall +<node> t = + node.traverse_id(<number> id, <node> n) +\stopfunctioncall + +This is an iterator that loops over all the nodes in the list that starts at +\type {n} that have a matching \type {id} field. + +See the previous section for details. The change is in the local function \type +{f}, which now does an extra while loop checking against the upvalue \type {id}: + +\starttyping + local function f(head,var) + local t + if var == nil then + t = head + else + t = var.next + end + while not t.id == id do + t = t.next + end + return t + end +\stoptyping + +\subsubsection{\type {node.end_of_math}} + +\startfunctioncall +<node> t = + node.end_of_math(<node> start) +\stopfunctioncall + +Looks for and returns the next \type {math_node} following the \type {start}. If +the given node is a math endnode this helper return that node, else it follows +the list and return the next math endnote. If no such node is found nil is +returned. + +\subsubsection{\type {node.remove}} + +\startfunctioncall +<node> head, current = + node.remove(<node> head, <node> current) +\stopfunctioncall + +This function removes the node \type {current} from the list following \type +{head}. It is your responsibility to make sure it is really part of that list. +The return values are the new \type {head} and \type {current} nodes. The +returned \type {current} is the node following the \type {current} in the calling +argument, and is only passed back as a convenience (or \type {nil}, if there is +no such node). The returned \type {head} is more important, because if the +function is called with \type {current} equal to \type {head}, it will be +changed. + +\subsubsection{\type {node.insert_before}} + +\startfunctioncall +<node> head, new = + node.insert_before(<node> head, <node> current, <node> new) +\stopfunctioncall + +This function inserts the node \type {new} before \type {current} into the list +following \type {head}. It is your responsibility to make sure that \type +{current} is really part of that list. The return values are the (potentially +mutated) \type {head} and the node \type {new}, set up to be part of the list +(with correct \type {next} field). If \type {head} is initially \type {nil}, it +will become \type {new}. + +\subsubsection{\type {node.insert_after}} + +\startfunctioncall +<node> head, new = + node.insert_after(<node> head, <node> current, <node> new) +\stopfunctioncall + +This function inserts the node \type {new} after \type {current} into the list +following \type {head}. It is your responsibility to make sure that \type +{current} is really part of that list. The return values are the \type {head} and +the node \type {new}, set up to be part of the list (with correct \type {next} +field). If \type {head} is initially \type {nil}, it will become \type {new}. + +\subsubsection{\type {node.first_glyph}} + +\startfunctioncall +<node> n = + node.first_glyph(<node> n) +<node> n = + node.first_glyph(<node> n, <node> m) +\stopfunctioncall + +Returns the first node in the list starting at \type {n} that is a glyph node +with a subtype indicating it is a glyph, or \type {nil}. If \type {m} is given, +processing stops at (but including) that node, otherwise processing stops at the +end of the list. + +\subsubsection{\type {node.ligaturing}} + +\startfunctioncall +<node> h, <node> t, <boolean> success = + node.ligaturing(<node> n) +<node> h, <node> t, <boolean> success = + node.ligaturing(<node> n, <node> m) +\stopfunctioncall + +Apply \TEX-style ligaturing to the specified nodelist. The tail node \type {m} is +optional. The two returned nodes \type {h} and \type {t} are the new head and +tail (both \type {n} and \type {m} can change into a new ligature). + +\subsubsection{\type {node.kerning}} + +\startfunctioncall +<node> h, <node> t, <boolean> success = + node.kerning(<node> n) +<node> h, <node> t, <boolean> success = + node.kerning(<node> n, <node> m) +\stopfunctioncall + +Apply \TEX|-|style kerning to the specified node list. The tail node \type {m} is +optional. The two returned nodes \type {h} and \type {t} are the head and tail +(either one of these can be an inserted kern node, because special kernings with +word boundaries are possible). + +\subsubsection{\type {node.unprotect_glyphs}} + +\startfunctioncall +node.unprotect_glyphs(<node> n) +\stopfunctioncall + +Subtracts 256 from all glyph node subtypes. This and the next function are +helpers to convert from \type {characters} to \type {glyphs} during node +processing. + +\subsubsection{\type {node.protect_glyphs}} + +\startfunctioncall +node.protect_glyphs(<node> n) +\stopfunctioncall + +Adds 256 to all glyph node subtypes in the node list starting at \type {n}, +except that if the value is 1, it adds only 255. The special handling of 1 means +that \type {characters} will become \type {glyphs} after subtraction of 256. + +\subsubsection{\type {node.last_node}} + +\startfunctioncall +<node> n = + node.last_node() +\stopfunctioncall + +This function pops the last node from \TEX's \quote{current list}. It returns +that node, or \type {nil} if the current list is empty. + +\subsubsection{\type {node.write}} + +\startfunctioncall +node.write(<node> n) +\stopfunctioncall + +This is an experimental function that will append a node list to \TEX's \quote +{current list} The node list is not deep|-|copied! There is no error checking +either! + +\subsubsection{\type {node.protrusion_skippable}} + +\startfunctioncall +<boolean> skippable = + node.protrusion_skippable(<node> n) +\stopfunctioncall + +Returns \type {true} if, for the purpose of line boundary discovery when +character protrusion is active, this node can be skipped. + +\subsection{Glue handling} + +\subsubsection{\type {node.setglue}} + +You can set the properties of a glue in one go. If you pass no values, the glue +will become a zero glue. + +\startfunctioncall +node.setglue(<node> n) +node.setglue(<node> n,width,stretch,shrink,stretch_order,shrink_order) +\stopfunctioncall + +When you pass values, only arguments that are numbers +are assigned so + +\starttyping +node.setglue(n,655360,false,65536) +\stoptyping + +will only adapt the width and shrink. + +\subsubsection{\type {node.getglue}} + +The next call will return 5 values (or northing when no glue is passed). + +\startfunctioncall +<integer> width, <integer> stretch, <integer> shrink, <integer> stretch_order, + <integer> shrink_order = node.getglue(<node> n) +\stopfunctioncall + +\subsubsection{\type {node.is_zero_glue}} + +This function returns \type {true} when the width, stretch and shrink properties +are zero. + +\startfunctioncall +<boolean> isglue = + node.is_zero_glue(<node> n) +\stopfunctioncall + +\subsection{Attribute handling} + +Attributes appear as linked list of userdata objects in the \type {attr} field of +individual nodes. They can be handled individually, but it is much safer and more +efficient to use the dedicated functions associated with them. + +\subsubsection{\type {node.has_attribute}} + +\startfunctioncall +<number> v = + node.has_attribute(<node> n, <number> id) +<number> v = + node.has_attribute(<node> n, <number> id, <number> val) +\stopfunctioncall + +Tests if a node has the attribute with number \type {id} set. If \type {val} is +also supplied, also tests if the value matches \type {val}. It returns the value, +or, if no match is found, \type {nil}. + +\subsubsection{\type {node.set_attribute}} + +\startfunctioncall +node.set_attribute(<node> n, <number> id, <number> val) +\stopfunctioncall + +Sets the attribute with number \type {id} to the value \type {val}. Duplicate +assignments are ignored. {\em [needs explanation]} + +\subsubsection{\type {node.unset_attribute}} + +\startfunctioncall +<number> v = + node.unset_attribute(<node> n, <number> id) +<number> v = + node.unset_attribute(<node> n, <number> id, <number> val) +\stopfunctioncall + +Unsets the attribute with number \type {id}. If \type {val} is also supplied, it +will only perform this operation if the value matches \type {val}. Missing +attributes or attribute|-|value pairs are ignored. + +If the attribute was actually deleted, returns its old value. Otherwise, returns +\type {nil}. + \stopchapter \stopcomponent |