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 | 520 |
1 files changed, 341 insertions, 179 deletions
diff --git a/doc/context/sources/general/manuals/luatex/luatex-nodes.tex b/doc/context/sources/general/manuals/luatex/luatex-nodes.tex index e0d93d7c3..4a36151a6 100644 --- a/doc/context/sources/general/manuals/luatex/luatex-nodes.tex +++ b/doc/context/sources/general/manuals/luatex/luatex-nodes.tex @@ -8,6 +8,8 @@ \section{\LUA\ node representation} +\topicindex {nodes} + \TEX's nodes are represented in \LUA\ as userdata object with a variable set of fields. In the following syntax tables, such the type of such a userdata object is represented as \syntax {<node>}. @@ -23,7 +25,7 @@ The current return value of \type {node.types()} is: \stopluacode . % period -The \type {\lastnodetype} primitive is \ETEX\ compliant. The valid range is still +The \prm {lastnodetype} primitive is \ETEX\ compliant. The valid range is still $[-1,15]$ and glyph nodes (formerly known as char nodes) have number~0 while ligature nodes are mapped to~7. That way macro packages can use the same symbolic names as in traditional \ETEX. Keep in mind that these \ETEX\ node numbers are @@ -35,14 +37,16 @@ and for valid subtypes with \type {node.subtypes} (which takes a string because eventually we might support more used enumerations). The \type {node.values} function reports some used values. Valid arguments are -\type {dir}, \type {direction}, \type {glue}, \type {pdf_literal}, \type -{pdf_action}, \type {pdf_window} and \type {color_stack}. Keep in mind that the +\nod {dir}, \type {direction}, \nod {glue}, \whs {pdf_literal}, \whs +{pdf_action}, \whs {pdf_window} and \whs {color_stack}. Keep in mind that the setters normally expect a number, but this helper gives you a list of what numbers matter. For practical reason the \type {pagestate} values are also reported with this helper. \subsection{Attributes} +\topicindex {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 @@ -51,28 +55,32 @@ the low|-|level interface. \subsubsection{attribute_list nodes} -An \type {attribute_list} item is used as a head pointer for a list of attribute +\topicindex {nodes+attributes} + +An \nod {attribute_list} item is used as a head pointer for a list of attribute items. It has only one user-visible field: \starttabulate[|l|l|p|] \DB field \BC type \BC explanation \NC \NR -\TB[small,samepage] +\TB \NC \type{next} \NC node \NC pointer to the first attribute \NC \NR +\LL \stoptabulate -\subsubsection{attribute nodes} +\subsubsection{\nod {attr} nodes} -A normal node's attribute field will point to an item of type \type +A normal node's attribute field will point to an item of type \nod {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. \starttabulate[|l|l|p|] \DB field \BC type \BC explanation \NC \NR -\TB[small,samepage] +\TB \NC \type{next} \NC node \NC pointer to the next attribute \NC \NR \NC \type{number} \NC number \NC the attribute type id \NC \NR \NC \type{value} \NC number \NC the attribute value \NC \NR +\LL \stoptabulate As mentioned it's better to use the official helpers rather than edit these @@ -81,15 +89,18 @@ and there is no double linked list. \subsection{Main text nodes} +\topicindex {nodes+text} + These are the nodes that comprise actual typesetting commands. A few fields are present in all nodes regardless of their type, these are: \starttabulate[|l|l|p|] \DB field \BC type \BC explanation \NC \NR -\TB[small,samepage] +\TB \NC \type{next} \NC node \NC the next node in a list, or nil \NC \NR \NC \type{id} \NC number \NC the node's type (\type {id}) number \NC \NR \NC \type{subtype} \NC number \NC the node \type {subtype} identifier \NC \NR +\LL \stoptabulate The \type {subtype} is sometimes just a stub entry. Not all nodes actually use @@ -103,26 +114,33 @@ 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. 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. +internal magic uses a leading \nod {temp} nodes to temporarily store a state. -\subsubsection{hlist nodes} +\subsubsection{\nod {hlist} nodes} \starttabulate[|l|l|p|] \DB field \BC type \BC explanation \NC \NR -\TB[small,samepage] +\TB \NC \type{subtype} \NC number \NC \showsubtypes{list} \NC \NR \NC \type{attr} \NC node \NC list of attributes \NC \NR \NC \type{width} \NC number \NC the width of the box \NC \NR \NC \type{height} \NC number \NC the height of the box \NC \NR \NC \type{depth} \NC number \NC the depth of the box \NC \NR -\NC \type{shift} \NC number \NC a displacement perpendicular to the character progression direction \NC \NR -\NC \type{glue_order} \NC number \NC a number in the range $[0,4]$, indicating the glue order \NC \NR +\NC \type{shift} \NC number \NC a displacement perpendicular to the character + progression direction \NC \NR +\NC \type{glue_order} \NC number \NC a number in the range $[0,4]$, indicating the + glue order \NC \NR \NC \type{glue_set} \NC number \NC the calculated glue ratio \NC \NR -\NC \type{glue_sign} \NC number \NC 0 = \type {normal}, 1 = \type {stretching}, 2 = \type {shrinking} \NC \NR +\NC \type{glue_sign} \NC number \NC 0 = \type {normal}, 1 = \type {stretching}, 2 = + \type {shrinking} \NC \NR \NC \type{head/list} \NC node \NC the first node of the body of this list \NC \NR -\NC \type{dir} \NC string \NC the direction of this box, see~\in[dirnodes] \NC \NR +\NC \type{dir} \NC string \NC the direction of this box, see~\in [dirnodes] \NC \NR +\LL \stoptabulate +\topicindex {nodes+lists} +\topicindex {lists} + A warning: never assign a node list to the \type {head} field unless you are sure its internal link structure is correct, otherwise an error may result. @@ -130,41 +148,69 @@ Note: the field name \type {head} and \type {list} are both valid. Sometimes it makes more sense to refer to a list by \type {head}, sometimes \type {list} makes more sense. -\subsubsection{vlist nodes} +\subsubsection{\nod {vlist} nodes} -This node is similar to \type {hlist}, except that \quote {shift} is a displacement +\topicindex {nodes+lists} +\topicindex {lists} + +This node is similar to \nod {hlist}, except that \quote {shift} is a displacement perpendicular to the line progression direction, and \quote {subtype} only has the values 0, 4, and~5. -\subsubsection{rule nodes} +\subsubsection{\nod {rule} nodes} + +\topicindex {nodes+rules} +\topicindex {rules} -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. +Contrary to traditional \TEX, \LUATEX\ has more \prm {rule} subtypes because we +also use rules to store reuseable objects and images. User nodes are invisible +and can be intercepted by a callback. \starttabulate[|l|l|p|] \DB field \BC type \BC explanation \NC \NR -\TB[small,samepage] -\NC \type{subtype} \NC number \NC \showsubtypes{rule} \NC \NR +\TB +\NC \type{subtype} \NC number \NC \showsubtypes {rule} \NC \NR \NC \type{attr} \NC node \NC list of attributes \NC \NR -\NC \type{width} \NC number \NC the width of the rule where the special value $-1073741824$ is used for \quote {running} glue dimensions \NC \NR +\NC \type{width} \NC number \NC the width of the rule where the special value + $-1073741824$ is used for \quote {running} glue dimensions \NC \NR \NC \type{height} \NC number \NC the height of the rule (can be negative) \NC \NR \NC \type{depth} \NC number \NC the depth of the rule (can be negative) \NC \NR +\NC \type{left} \NC number \NC shift at the left end (also subtracted from width) \NC \NR +\NC \type{right} \NC number \NC (subtracted from width) \NC \NR \NC \type{dir} \NC string \NC the direction of this rule, see~\in[dirnodes] \NC \NR \NC \type{index} \NC number \NC an optional index that can be referred to \NC \NR +\LL \stoptabulate -\subsubsection{ins nodes} +The \type {left} and type {right} keys are somewhat special (and experimental). +When rules are auto adapting to the surrounding box width you can enforce a shift +to the right by setting \type {left}. The value is also subtracted from the width +which can be a value set by the engine itself and is not entirely under user +control. The \type {right} is also subtracted from the width. It all happens in +the backend so these are not affecting the calculations in the frontend (actually +the auto settings also happen in the backend). For a vertical rule \type {left} +affects the height and \type {right} affects the depth. There is no matching +interface at the \TEX\ end (although we can have more keywords for rules it would +complicate matters and introduce a speed penalty.) However, you can just +construct a rule node with \LUA\ and write it to the \TEX\ input. + +\subsubsection{\nod {ins} nodes} + +\topicindex {nodes+insertions} +\topicindex {insertions} + +This node relates to the \prm {insert} primitive. \starttabulate[|l|l|p|] \DB field \BC type \BC explanation \NC \NR -\TB[small,samepage] +\TB \NC \type{subtype} \NC number \NC the insertion class \NC \NR \NC \type{attr} \NC node \NC list of attributes \NC \NR \NC \type{cost} \NC number \NC the penalty associated with this insert \NC \NR \NC \type{height} \NC number \NC height of the insert \NC \NR \NC \type{depth} \NC number \NC depth of the insert \NC \NR \NC \type{head/list} \NC node \NC the first node of the body of this insert \NC \NR +\LL \stoptabulate There is a set of extra fields that concern the associated glue: \type {width}, @@ -176,52 +222,72 @@ its internal link structure is correct, otherwise an error may be result. You ca \type {list} instead (often in functions you want to use local variable swith similar names and both names are equally sensible). -\subsubsection{mark nodes} +\subsubsection{\nod {mark} nodes} + +\topicindex {nodes+marks} +\topicindex {marks} + +This one relates to the \prm {mark} primitive. \starttabulate[|l|l|p|] \DB field \BC type \BC explanation \NC \NR -\TB[small,samepage] +\TB \NC \type{subtype} \NC number \NC unused \NC \NR \NC \type{attr} \NC node \NC list of attributes \NC \NR \NC \type{class} \NC number \NC the mark class \NC \NR \NC \type{mark} \NC table \NC a table representing a token list \NC \NR +\LL \stoptabulate -\subsubsection{adjust nodes} +\subsubsection{\nod {adjust} nodes} + +\topicindex {nodes+adjust} +\topicindex {adjust} + +This node comes from \prm {vadjust} primitive. \starttabulate[|l|l|p|] \DB field \BC type \BC explanation \NC \NR -\TB[small,samepage] +\TB \NC \type{subtype} \NC number \NC \showsubtypes{adjust} \NC \NR \NC \type{attr} \NC node \NC list of attributes \NC \NR \NC \type{head/list} \NC node \NC adjusted material \NC \NR +\LL \stoptabulate A warning: never assign a node list to the \type {head} field unless you are sure its internal link structure is correct, otherwise an error may be result. -\subsubsection{disc nodes} +\subsubsection{\nod {disc} nodes} + +\topicindex {nodes+discretionaries} +\topicindex {discretionaries} + +The \prm {discretionary} and \prm {-}, the \type {-} character but also the +hyphenation mechanism produces these nodes. \starttabulate[|l|l|p|] \DB field \BC type \BC explanation \NC \NR -\TB[small,samepage] +\TB \NC \type{subtype} \NC number \NC \showsubtypes{disc} \NC \NR \NC \type{attr} \NC node \NC list of attributes \NC \NR \NC \type{pre} \NC node \NC pointer to the pre|-|break text \NC \NR \NC \type{post} \NC node \NC pointer to the post|-|break text \NC \NR \NC \type{replace} \NC node \NC pointer to the no|-|break text \NC \NR -\NC \type{penalty} \NC number \NC the penalty associated with the break, normally \type {\hyphenpenalty} or \type {\exhyphenpenalty} \NC \NR +\NC \type{penalty} \NC number \NC the penalty associated with the break, normally + \prm {hyphenpenalty} or \prm {exhyphenpenalty} \NC \NR +\LL \stoptabulate The subtype numbers~4 and~5 belong to the \quote {of-f-ice} explanation given -elsewhere. +elsewhere. These disc nodes are kind of special as at some point they also keep +information about breakpoints and nested ligatures. -These disc nodes are kind of special as at some point they also keep information -about breakpoints and nested ligatures. The \type {pre}, \type {post} and \type -{replace} fields at the \LUA\ end are in fact indirectly accessed and have a -\type {prev} pointer that is not \type {nil}. This means that when you mess -around with the head of these (three) lists, you also need to reassign them -because that will restore the proper \type {prev} pointer, so: +The \type {pre}, \type {post} and \type {replace} fields at the \LUA\ end are in +fact indirectly accessed and have a \type {prev} pointer that is not \type {nil}. +This means that when you mess around with the head of these (three) lists, you +also need to reassign them because that will restore the proper \type {prev} +pointer, so: \starttyping pre = d.pre @@ -236,34 +302,47 @@ And you definitely must not mess with the node that \type {prev} points to, if only because it is not really an node but part of the disc data structure (so freeing it again might crash \LUATEX). -\subsubsection{math nodes} +\subsubsection{\nod {math} nodes} + +\topicindex {nodes+math} +\topicindex {math+nodes} + +Math nodes represent the boundaries of a math formula, normally wrapped into +\type {$} signs. \starttabulate[|l|l|p|] \DB field \BC type \BC explanation \NC \NR -\TB[small,samepage] +\TB \NC \type{subtype} \NC number \NC \showsubtypes{math} \NC \NR \NC \type{attr} \NC node \NC list of attributes \NC \NR -\NC \type{surround} \NC number \NC width of the \type {\mathsurround} kern \NC \NR +\NC \type{surround} \NC number \NC width of the \prm {mathsurround} kern \NC \NR +\LL \stoptabulate There is a set of extra fields that concern the associated glue: \type {width}, \type {stretch}, \type {stretch_order}, \type {shrink} and \type {shrink_order}. These are all numbers. -\subsubsection{glue nodes} +\subsubsection{\nod {glue} nodes} + +\topicindex {nodes+glue} +\topicindex {glue} Skips are about the only type of data objects in traditional \TEX\ that are not a -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: +simple value. They are inserted when \TEX\ sees a space in the text flow but also +by \prm {hskip} and \prm {vskip}. The structure that represents the glue +components of a skip is called a \nod {glue_spec}, and it has the following +accessible fields: \starttabulate[|l|l|p|] \DB field \BC type \BC explanation \NC \NR -\TB[small,samepage] +\TB \NC \type{width} \NC number \NC the horizontal or vertical displacement \NC \NR \NC \type{stretch} \NC number \NC extra (positive) displacement or stretch amount \NC \NR \NC \type{stretch_order} \NC number \NC factor applied to stretch amount \NC \NR \NC \type{shrink} \NC number \NC extra (negative) displacement or shrink amount\NC \NR \NC \type{shrink_order} \NC number \NC factor applied to shrink amount \NC \NR +\LL \stoptabulate The effective width of some glue subtypes depends on the stretch or shrink needed @@ -273,10 +352,10 @@ the content fit in the available space. The \type {effective_glue} function that takes a glue node and a parent (hlist or vlist) returns the effective width of that glue item. -A gluespec node is a special kind of node that is used for storing a set of glue -values in registers. Originally they were also used to store properties of glue -nodes (using a system of reference counts) but we now keep these properties in -the glue nodes themselves, which gives a cleaner interface to \LUA. +A \nod {glue_spec} node is a special kind of node that is used for storing a set +of glue values in registers. Originally they were also used to store properties +of glue nodes (using a system of reference counts) but we now keep these +properties in the glue nodes themselves, which gives a cleaner interface to \LUA. The indirect spec approach was in fact an optimization in the original \TEX\ code. First of all it can save quite some memory because all these spaces that @@ -292,10 +371,11 @@ is only a few memory words larger than a spec). \starttabulate[|l|l|p|] \DB field \BC type \BC explanation \NC \NR -\TB[small,samepage] +\TB \NC \type{subtype} \NC number \NC \showsubtypes{glue} \NC \NR \NC \type{attr} \NC node \NC list of attributes \NC \NR \NC \type{leader} \NC node \NC pointer to a box or rule for leaders \NC \NR +\LL \stoptabulate In addition there are the \type {width}, \type {stretch} \type {stretch_order}, @@ -306,35 +386,55 @@ 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). -\subsubsection{kern nodes} +\subsubsection{\nod {kern} nodes} + +\topicindex {nodes+kerns} +\topicindex {kerns} + +The \prm {kern} command creates such nodes but for instance the font and math +machinery can also add them. \starttabulate[|l|l|p|] \DB field \BC type \BC explanation \NC \NR -\TB[small,samepage] +\TB \NC \type{subtype} \NC number \NC \showsubtypes{kern} \NC \NR \NC \type{attr} \NC node \NC list of attributes \NC \NR \NC \type{kern} \NC number \NC fixed horizontal or vertical advance \NC \NR +\LL \stoptabulate -\subsubsection{penalty nodes} +\subsubsection{\nod {penalty} nodes} + +\topicindex {nodes+penalty} +\topicindex {penalty} + +The \prm {penalty} command is one that generates these nodes. \starttabulate[|l|l|p|] \DB field \BC type \BC explanation \NC \NR -\TB[small,samepage] +\TB \NC \type{subtype} \NC number \NC \showsubtypes{penalty} \NC \NR \NC \type{attr} \NC node \NC list of attributes \NC \NR \NC \type{penalty} \NC number \NC the penalty value \NC \NR +\LL \stoptabulate The subtypes are just informative and \TEX\ itself doesn't use them. When you run into an \type {linebreakpenalty} you need to keep in mind that it's a accumulation of \type {club}, \type{widow} and other relevant penalties. -\subsubsection[glyphnodes]{glyph nodes} +\subsubsection[glyphnodes]{\nod {glyph} nodes} + +\topicindex {nodes+glyph} +\topicindex {glyph} + +These are probably the mostly used nodes and although you can push on tin the +list with for instance \prm {char} \TEX\ will normally do it for you when it +considers some input to be text. \starttabulate[|l|l|p|] \DB field \BC type \BC explanation \NC \NR -\TB[small,samepage] +\TB \NC \type{subtype} \NC number \NC bitfield \NC \NR \NC \type{attr} \NC node \NC list of attributes \NC \NR \NC \type{char} \NC number \NC the chatacter index in the font \NC \NR @@ -342,7 +442,7 @@ accumulation of \type {club}, \type{widow} and other relevant penalties. \NC \type{lang} \NC number \NC the language identifier \NC \NR \NC \type{left} \NC number \NC the frozen \type {\lefthyphenmnin} value \NC \NR \NC \type{right} \NC number \NC the frozen \type {\righthyphenmnin} value \NC \NR -\NC \type{uchyph} \NC boolean \NC the frozen \type {\uchyph} value \NC \NR +\NC \type{uchyph} \NC boolean \NC the frozen \prm {uchyph} value \NC \NR \NC \type{components} \NC node \NC pointer to ligature components \NC \NR \NC \type{xoffset} \NC number \NC a virtual displacement in horizontal direction \NC \NR \NC \type{yoffset} \NC number \NC a virtual displacement in vertical direction \NC \NR @@ -351,6 +451,7 @@ accumulation of \type {club}, \type{widow} and other relevant penalties. \NC \type{height} \NC number \NC the (original) height of the character\NC \NR \NC \type{depth} \NC number \NC the (original) depth of the character\NC \NR \NC \type{expansion_factor} \NC number \NC the to be applied expansion_factor \NC \NR +\LL \stoptabulate The \type {width}, \type {height} and \type {depth} values are read|-|only. The @@ -362,12 +463,13 @@ bits for the \type {subtype} field are: \starttabulate[|c|l|] \DB bit \BC meaning \NC \NR -\TB[small,samepage] +\TB \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 +\LL \stoptabulate See \in {section} [charsandglyphs] for a detailed description of the \type @@ -393,52 +495,68 @@ helpers are not always faster than separate calls but they sometimes permit making more readable tests. The \type {uses_font} helpers takes a node and font id and returns true when a glyph or disc node references that font. -\subsubsection{boundary nodes} +\subsubsection{\nod {boundary} nodes} + +\topicindex {nodes+boundary} +\topicindex {boundary} + +This node relates to the \prm {noboundary}, \prm {boundary}, \prm +{protrusionboundary} and \prm {wordboundary} primitives. \starttabulate[|l|l|p|] \DB field \BC type \BC explanation \NC \NR -\TB[small,samepage] +\TB \NC \type{subtype} \NC number \NC \showsubtypes{boundary} \NC \NR \NC \type{attr} \NC node \NC list of attributes \NC \NR \NC \type{value} \NC number \NC values 0--255 are reserved \NC \NR +\LL \stoptabulate -This node relates to the \type {\noboundary}, \type {\boundary}, \type -{\protrusionboundary} and \type {\wordboundary} primitives. +\subsubsection{\nod {local_par} nodes} + +\topicindex {nodes+paragraphs} +\topicindex {paragraphs} -\subsubsection{local_par nodes} +This node in inserted a the start of a paragraph. You should not mess +too much with this one. \starttabulate[|l|l|p|] \DB field \BC type \BC explanation \NC \NR -\TB[small,samepage] +\TB \NC \type{attr} \NC node \NC list of attributes \NC \NR -\NC \type{pen_inter} \NC number \NC local interline penalty (from \type {\localinterlinepenalty}) \NC \NR -\NC \type{pen_broken} \NC number \NC local broken penalty (from \type {\localbrokenpenalty}) \NC \NR +\NC \type{pen_inter} \NC number \NC local interline penalty (from \lpr {localinterlinepenalty}) \NC \NR +\NC \type{pen_broken} \NC number \NC local broken penalty (from \lpr {localbrokenpenalty}) \NC \NR \NC \type{dir} \NC string \NC the direction of this par. see~\in [dirnodes] \NC \NR -\NC \type{box_left} \NC node \NC the \type {\localleftbox} \NC \NR -\NC \type{box_left_width} \NC number \NC width of the \type {\localleftbox} \NC \NR -\NC \type{box_right} \NC node \NC the \type {\localrightbox} \NC \NR -\NC \type{box_right_width} \NC number \NC width of the \type {\localrightbox} \NC \NR +\NC \type{box_left} \NC node \NC the \lpr {localleftbox} \NC \NR +\NC \type{box_left_width} \NC number \NC width of the \lpr {localleftbox} \NC \NR +\NC \type{box_right} \NC node \NC the \lpr {localrightbox} \NC \NR +\NC \type{box_right_width} \NC number \NC width of the \lpr {localrightbox} \NC \NR +\LL \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} +\subsubsection[dirnodes]{\nod {dir} nodes} + +\topicindex {nodes+direction} +\topicindex {directions} + +Direction nodes mark parts of the running text that need a change of direction and \ +the \prm {textdir} command generates them. \starttabulate[|l|l|p|] \DB field \BC type \BC explanation \NC \NR -\TB[small,samepage] +\TB \NC \type{attr} \NC node \NC list of attributes \NC \NR \NC \type{dir} \NC string \NC the direction (but see below) \NC \NR \NC \type{level} \NC number \NC nesting level of this direction whatsit \NC \NR +\LL \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: +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 @@ -453,25 +571,33 @@ These are built up out of three separate items: \stopitemize However, only four combinations are accepted: \type {TLT}, \type {TRT}, \type -{RTT}, and \type {LTL}. +{RTT}, and \type {LTL}. Inside actual \nod {dir} nodes, the representation of +\nod {dir} is not a three|-|letter but a combination of numbers. When printed the +direction is indicated by a \type {+} or \type {-}, indicating whether the value +is pushed or popped from the direction stack. + +\subsubsection{\nod {margin_kern} nodes} -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. +\topicindex {nodes+paragraphs} +\topicindex {paragraphs} +\topicindex {protrusion} -\subsubsection{margin_kern nodes} +Margin kerns result from protrusion. \starttabulate[|l|l|p|] \DB field \BC type \BC explanation \NC \NR -\TB[small,samepage] +\TB \NC \type{subtype} \NC number \NC \showsubtypes{margin_kern} \NC \NR \NC \type{attr} \NC node \NC list of attributes \NC \NR \NC \type{width} \NC number \NC the advance of the kern \NC \NR \NC \type{glyph} \NC node \NC the glyph to be used \NC \NR +\LL \stoptabulate -\subsection{Math nodes} +\subsection{Math noads} + +\topicindex {nodes+math} +\topicindex {math+nodes} These are the so||called \quote {noad}s and the nodes that are specifically associated with math processing. Most of these nodes contain subnodes so that the @@ -486,52 +612,53 @@ these cases (in the following node descriptions these are indicated by the word The \type {next} and \type {prev} fields for these subnodes are unused. -\subsubsubsection{math_char and math_text_char subnodes} +\subsubsubsection{\nod {math_char} and \nod {math_text_char} subnodes} \starttabulate[|l|l|p|] \DB field \BC type \BC explanation \NC \NR -\TB[small,samepage] +\TB \NC \type{attr} \NC node \NC list of attributes \NC \NR \NC \type{char} \NC number \NC the character index \NC \NR \NC \type{fam} \NC number \NC the family number \NC \NR +\LL \stoptabulate -The \type {math_char} is the simplest subnode field, it contains the character -and family for a single glyph object. The \type {math_text_char} is a special +The \nod {math_char} is the simplest subnode field, it contains the character +and family for a single glyph object. The \nod {math_text_char} is a special case that you will not normally encounter, it arises temporarily during math list conversion (its sole function is to suppress a following italic correction). -\subsubsubsection{sub_box and sub_mlist subnodes} +\subsubsubsection{\nod {sub_box} and \nod {sub_mlist} subnodes} \starttabulate[|l|l|p|] \DB field \BC type \BC explanation \NC \NR -\TB[small,samepage] +\TB \NC \type{attr} \NC node \NC list of attributes \NC \NR \NC \type{head/list} \NC node \NC list of nodes \NC \NR +\LL \stoptabulate -These two subnode types are used for subsidiary list items. For \type {sub_box}, -the \type {head} points to a \quote {normal} vbox or hbox. For \type {sub_mlist}, +These two subnode types are used for subsidiary list items. For \nod {sub_box}, +the \type {head} points to a \quote {normal} vbox or hbox. For \nod {sub_mlist}, the \type {head} points to a math list that is yet to be converted. A warning: never assign a node list to the \type {head} field unless you are sure its internal link structure is correct, otherwise an error may be result. -\subsubsection{Math delimiter subnode} +\subsubsubsection{\nod {delim} subnodes} There is a fifth subnode type that is used exclusively for delimiter fields. As before, the \type {next} and \type {prev} fields are unused. -\subsubsubsection{delim subnodes} - \starttabulate[|l|l|p|] \DB field \BC type \BC explanation \NC \NR -\TB[small,samepage] +\TB \NC \type{attr} \NC node \NC list of attributes \NC \NR \NC \type{small_char} \NC number \NC character index of base character \NC \NR \NC \type{small_fam} \NC number \NC family number of base character \NC \NR \NC \type{large_char} \NC number \NC character index of next larger character \NC \NR \NC \type{large_fam} \NC number \NC family number of next larger character \NC \NR +\LL \stoptabulate The fields \type {large_char} and \type {large_fam} can be zero, in that case the @@ -549,7 +676,7 @@ Some noads have an option field. The values in this bitset are common: \starttabulate[|l|r|] \DB meaning \BC bits \NC \NR -\TB[small,samepage] +\TB \NC set \NC \type{0x08} \NC \NR \NC internal \NC \type{0x00} + \type{0x08} \NC \NR \NC internal \NC \type{0x01} + \type{0x08} \NC \NR @@ -562,26 +689,28 @@ Some noads have an option field. The values in this bitset are common: \NC no sub script \NC \type{0x21} + \type{0x08} \NC \NR \NC no super script \NC \type{0x22} + \type{0x08} \NC \NR \NC no script \NC \type{0x23} + \type{0x08} \NC \NR +\LL \stoptabulate -\subsubsubsection{simple nodes} +\subsubsubsection{simple \nod {noad} nodes} \starttabulate[|l|l|p|] \DB field \BC type \BC explanation \NC \NR -\TB[small,samepage] +\TB \NC \type{subtype} \NC number \NC \showsubtypes{noad} \NC \NR \NC \type{attr} \NC node \NC list of attributes \NC \NR \NC \type{nucleus} \NC kernel node \NC base \NC \NR \NC \type{sub} \NC kernel node \NC subscript \NC \NR \NC \type{sup} \NC kernel node \NC superscript \NC \NR \NC \type{options} \NC number \NC bitset of rendering options \NC \NR +\LL \stoptabulate -\subsubsubsection{accent nodes} +\subsubsubsection{\nod {accent} nodes} \starttabulate[|l|l|p|] \DB field \BC type \BC explanation \NC \NR -\TB[small,samepage] +\TB \NC \type{subtype} \NC number \NC \showsubtypes{accent} \NC \NR \NC \type{nucleus} \NC kernel node \NC base \NC \NR \NC \type{sub} \NC kernel node \NC subscript \NC \NR @@ -589,61 +718,65 @@ Some noads have an option field. The values in this bitset are common: \NC \type{accent} \NC kernel node \NC top accent \NC \NR \NC \type{bot_accent} \NC kernel node \NC bottom accent \NC \NR \NC \type{fraction} \NC number \NC larger step criterium (divided by 1000) \NC \NR +\LL \stoptabulate -\subsubsubsection{style nodes} +\subsubsubsection{\nod {style} nodes} \starttabulate[|l|l|p|] \DB field \BC type \BC explanation \NC \NR -\TB[small,samepage] +\TB \NC \type{style} \NC string \NC contains the style \NC \NR +\LL \stoptabulate There are eight possibilities for the string value: one of \type {display}, \type {text}, \type {script}, or \type {scriptscript}. Each of these can have be prefixed by \type {cramped}. -\subsubsubsection{choice nodes} +\subsubsubsection{\nod {choice} nodes} \starttabulate[|l|l|p|] \DB field \BC type \BC explanation \NC \NR -\TB[small,samepage] +\TB \NC \type{attr} \NC node \NC list of attributes \NC \NR \NC \type{display} \NC node \NC list of display size alternatives \NC \NR \NC \type{text} \NC node \NC list of text size alternatives \NC \NR \NC \type{script} \NC node \NC list of scriptsize alternatives \NC \NR \NC \type{scriptscript} \NC node \NC list of scriptscriptsize alternatives \NC \NR +\LL \stoptabulate Warning: never assign a node list to the \type {display}, \type {text}, \type {script}, or \type {scriptscript} field unless you are sure its internal link structure is correct, otherwise an error may be result. -\subsubsubsection{radical nodes} +\subsubsubsection{\nod {radical} nodes} \starttabulate[|l|l|p|] \DB field \BC type \BC explanation \NC \NR -\TB[small,samepage] +\TB \NC \type{subtype} \NC number \NC \showsubtypes{radical} \NC \NR \NC \type{attr} \NC node \NC list of attributes \NC \NR \NC \type{nucleus} \NC kernel node \NC base \NC \NR \NC \type{sub} \NC kernel node \NC subscript \NC \NR \NC \type{sup} \NC kernel node \NC superscript \NC \NR \NC \type{left} \NC delimiter node \NC \NC \NR -\NC \type{degree} \NC kernel node \NC only set by \type {\Uroot} \NC \NR +\NC \type{degree} \NC kernel node \NC only set by \lpr {Uroot} \NC \NR \NC \type{width} \NC number \NC required width \NC \NR \NC \type{options} \NC number \NC bitset of rendering options \NC \NR +\LL \stoptabulate Warning: never assign a node list to the \type {nucleus}, \type {sub}, \type {sup}, \type {left}, or \type {degree} field unless you are sure its internal link structure is correct, otherwise an error may be result. -\subsubsubsection{fraction nodes} +\subsubsubsection{\nod {fraction} nodes} \starttabulate[|l|l|p|] \DB field \BC type \BC explanation \NC \NR -\TB[small,samepage] +\TB \NC \type{attr} \NC node \NC list of attributes \NC \NR \NC \type{width} \NC number \NC (optional) width of the fraction \NC \NR \NC \type{num} \NC kernel node \NC numerator \NC \NR @@ -652,17 +785,18 @@ link structure is correct, otherwise an error may be result. \NC \type{right} \NC delimiter node \NC right side symbol \NC \NR \NC \type{middle} \NC delimiter node \NC middle symbol \NC \NR \NC \type{options} \NC number \NC bitset of rendering options \NC \NR +\LL \stoptabulate Warning: never assign a node list to the \type {num}, or \type {denom} field unless you are sure its internal link structure is correct, otherwise an error may be result. -\subsubsubsection{fence nodes} +\subsubsubsection{\nod {fence} nodes} \starttabulate[|l|l|p|] \DB field \BC type \BC explanation \NC \NR -\TB[small,samepage] +\TB \NC \type{subtype} \NC number \NC \showsubtypes{fence} \NC \NR \NC \type{attr} \NC node \NC list of attributes \NC \NR \NC \type{delim} \NC delimiter node \NC delimiter specification \NC \NR @@ -671,6 +805,7 @@ may be result. \NC \type{depth} \NC number \NC required depth \NC \NR \NC \type{options} \NC number \NC bitset of rendering options \NC \NR \NC \type{class} \NC number \NC spacing related class \NC \NR +\LL \stoptabulate Warning: some of these fields are used by the renderer and might get adapted in @@ -692,38 +827,41 @@ Whatsit nodes come in many subtypes that you can ask for by running \subsubsection{front|-|end whatsits} -\subsubsubsection{open whatsits} +\subsubsubsection{\whs {open}} \starttabulate[|l|l|p|] \DB field \BC type \BC explanation \NC \NR -\TB[small,samepage] +\TB \NC \type{attr} \NC node \NC list of attributes \NC \NR \NC \type{stream} \NC number \NC \TEX's stream id number \NC \NR \NC \type{name} \NC string \NC file name \NC \NR \NC \type{ext} \NC string \NC file extension \NC \NR \NC \type{area} \NC string \NC file area (this may become obsolete) \NC \NR +\LL \stoptabulate -\subsubsubsection{write whatsits} +\subsubsubsection{\whs {write}} \starttabulate[|l|l|p|] \DB field \BC type \BC explanation \NC \NR -\TB[small,samepage] +\TB \NC \type{attr} \NC node \NC list of attributes \NC \NR \NC \type{stream} \NC number \NC \TEX's stream id number \NC \NR \NC \type{data} \NC table \NC a table representing the token list to be written \NC \NR +\LL \stoptabulate -\subsubsubsection{close whatsits} +\subsubsubsection{\whs {close}} \starttabulate[|l|l|p|] \DB field \BC type \BC explanation \NC \NR -\TB[small,samepage] +\TB \NC \type{attr} \NC node \NC list of attributes \NC \NR \NC \type{stream} \NC number \NC \TEX's stream id number \NC \NR +\LL \stoptabulate -\subsubsubsection{user_defined whatsits} +\subsubsubsection{\whs {user_defined}} 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 @@ -731,7 +869,7 @@ will simply step over such whatsits without ever looking at the contents. \starttabulate[|l|l|p|] \DB field \BC type \BC explanation \NC \NR -\TB[small,samepage] +\TB \NC \type{attr} \NC node \NC list of attributes \NC \NR \NC \type{user_id} \NC number \NC id number \NC \NR \NC \type{type} \NC number \NC type of the value \NC \NR @@ -739,6 +877,7 @@ will simply step over such whatsits without ever looking at the contents. \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 +\LL \stoptabulate The \type {type} can have one of six distinct values. The number is the \ASCII\ @@ -747,104 +886,112 @@ instead of \type {108}). \starttabulate[|r|c|p|] \DB value \BC meaning \BC explanation \NC \NR -\TB[small,samepage] +\TB \NC 97 \NC a \NC list of attributes (a node list) \NC \NR \NC 100 \NC d \NC a \LUA\ number \NC \NR \NC 108 \NC l \NC a \LUA\ value (table, number, boolean, etc) \NC \NR \NC 110 \NC n \NC a node list \NC \NR \NC 115 \NC s \NC a \LUA\ string \NC \NR \NC 116 \NC t \NC a \LUA\ token list in \LUA\ table form (a list of triplets) \NC \NR +\LL \stoptabulate -\subsubsubsection{save_pos whatsits} +\subsubsubsection{\whs {save_pos}} \starttabulate[|l|l|p|] \DB field \BC type \BC explanation \NC \NR -\TB[small,samepage] +\TB \NC \type{attr} \NC node \NC list of attributes \NC \NR +\LL \stoptabulate -\subsubsubsection{late_lua whatsits} +\subsubsubsection{\whs {late_lua}} \starttabulate[|l|l|p|] \DB field \BC type \BC explanation \NC \NR -\TB[small,samepage] +\TB \NC \type{attr} \NC node \NC list of attributes \NC \NR \NC \type{data} \NC string \NC data to execute \NC \NR \NC \type{string} \NC string \NC data to execute \NC \NR \NC \type{name} \NC string \NC the name to use for \LUA\ error reporting \NC \NR +\LL \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 {data} field is converted to a token list, cf.\ use as \lpr {latelua}. The \type {string} version is treated as a literal string. \subsubsection{\DVI\ backend whatsits} -\subsubsection{special whatsits} +\subsubsection{\whs {special}} \starttabulate[|l|l|p|] \DB field \BC type \BC explanation \NC \NR -\TB[small,samepage] +\TB \NC \type{attr} \NC node \NC list of attributes \NC \NR -\NC \type{data} \NC string \NC the \type {\special} information \NC \NR +\NC \type{data} \NC string \NC the \prm {special} information \NC \NR +\LL \stoptabulate \subsubsection{\PDF\ backend whatsits} -\subsubsubsection{pdf_literal whatsits} +\subsubsubsection{\whs {pdf_literal}} \starttabulate[|l|l|p|] \DB field \BC type \BC explanation \NC \NR -\TB[small,samepage] +\TB \NC \type{attr} \NC node \NC list of attributes \NC \NR \NC \type{mode} \NC number \NC the \quote {mode} setting of this literal \NC \NR -\NC \type{data} \NC string \NC the \type {\pdfliteral} information \NC \NR +\NC \type{data} \NC string \NC the \orm {pdfliteral} information \NC \NR +\LL \stoptabulate Possible mode values are: -\starttabulate[|l|p|] +\starttabulate[|c|p|] \DB value \BC keyword \NC \NR -\TB[small,samepage] +\TB \NC 0 \NC \type{origin} \NC \NR \NC 1 \NC \type{page} \NC \NR \NC 2 \NC \type{direct} \NC \NR \NC 3 \NC \type{raw} \NC \NR \NC 4 \NC \type{text} \NC \NR +\LL \stoptabulate The higher the number, the less checking and the more you can run into troubles. Especially the \type {raw} variant can produce bad \PDF\ so you can best check what you generate. -\subsubsubsection{pdf_refobj whatsits} +\subsubsubsection{\whs {pdf_refobj}} \starttabulate[|l|l|p|] \DB field \BC type \BC explanation \NC \NR -\TB[small,samepage] +\TB \NC \type{attr} \NC node \NC list of attributes \NC \NR \NC \type{objnum} \NC number \NC the referenced \PDF\ object number \NC \NR +\LL \stoptabulate -\subsubsubsection{pdf_annot whatsits} +\subsubsubsection{\whs {pdf_annot}} \starttabulate[|l|l|p|] \DB field \BC type \BC explanation \NC \NR -\TB[small,samepage] +\TB \NC \type{attr} \NC node \NC list of attributes \NC \NR \NC \type{width} \NC number \NC the width (not used in calculations) \NC \NR \NC \type{height} \NC number \NC the height (not used in calculations) \NC \NR \NC \type{depth} \NC number \NC the depth (not used in calculations) \NC \NR \NC \type{objnum} \NC number \NC the referenced \PDF\ object number \NC \NR \NC \type{data} \NC string \NC the annotation data \NC \NR +\LL \stoptabulate -\subsubsubsection{pdf_start_link whatsits} +\subsubsubsection{\whs {pdf_start_link}} \starttabulate[|l|l|p|] \DB field \BC type \BC explanation \NC \NR -\TB[small,samepage] +\TB \NC \type{attr} \NC node \NC list of attributes \NC \NR \NC \type{width} \NC number \NC the width (not used in calculations) \NC \NR \NC \type{height} \NC number \NC the height (not used in calculations) \NC \NR @@ -852,21 +999,23 @@ what you generate. \NC \type{objnum} \NC number \NC the referenced \PDF\ object number \NC \NR \NC \type{link_attr} \NC table \NC the link attribute token list \NC \NR \NC \type{action} \NC node \NC the action to perform \NC \NR +\LL \stoptabulate -\subsubsubsection{pdf_end_link whatsits} +\subsubsubsection{\whs {pdf_end_link}} \starttabulate[|l|l|p|] \DB field \BC type \BC explanation \NC \NR -\TB[small,samepage] +\TB \NC \type{attr} \NC node \NC \NC \NR +\LL \stoptabulate -\subsubsubsection{pdf_dest whatsits} +\subsubsubsection{\whs {pdf_dest}} \starttabulate[|l|l|p|] \DB field \BC type \BC explanation \NC \NR -\TB[small,samepage] +\TB \NC \type{attr} \NC node \NC list of attributes \NC \NR \NC \type{width} \NC number \NC the width (not used in calculations) \NC \NR \NC \type{height} \NC number \NC the height (not used in calculations) \NC \NR @@ -877,50 +1026,54 @@ what you generate. \NC \type{dest_type} \NC number \NC type of destination \NC \NR \NC \type{xyz_zoom} \NC number \NC the zoom factor (times 1000) \NC \NR \NC \type{objnum} \NC number \NC the \PDF\ object number \NC \NR +\LL \stoptabulate -\subsubsubsection{pdf_action whatsits} +\subsubsubsection{\whs {pdf_action}} These are a special kind of item that only appears inside \PDF\ start link objects. \starttabulate[|l|l|p|] \DB field \BC type \BC explanation \NC \NR -\TB[small,samepage] +\TB \NC \type{action_type} \NC number \NC the kind of action involved \NC \NR \NC \type{action_id} \NC number or string \NC token list reference or string \NC \NR \NC \type{named_id} \NC number \NC the index of the destination \NC \NR \NC \type{file} \NC string \NC the target filename \NC \NR \NC \type{new_window} \NC number \NC the window state of the target \NC \NR \NC \type{data} \NC string \NC the name of the destination \NC \NR +\LL \stoptabulate Valid action types are: \starttabulate[|l|l|] \DB value \BC meaning \NC \NR -\TB[small,samepage] +\TB \NC 0 \NC \type{page} \NC \NR \NC 1 \NC \type{goto} \NC \NR \NC 2 \NC \type{thread} \NC \NR \NC 3 \NC \type{user} \NC \NR +\LL \stoptabulate Valid window types are: \starttabulate[|l|l|] \DB value \BC meaning \NC \NR -\TB[small,samepage] +\TB \NC 0 \NC \type{notset} \NC \NR \NC 1 \NC \type{new} \NC \NR \NC 2 \NC \type{nonew} \NC \NR +\LL \stoptabulate -\subsubsubsection{pdf_thread whatsits} +\subsubsubsection{\whs {pdf_thread}} \starttabulate[|l|l|p|] \DB field \BC type \BC explanation \NC \NR -\TB[small,samepage] +\TB \NC \type{attr} \NC node \NC list of attributes \NC \NR \NC \type{width} \NC number \NC the width (not used in calculations) \NC \NR \NC \type{height} \NC number \NC the height (not used in calculations) \NC \NR @@ -929,13 +1082,14 @@ Valid window types are: \NC \type{tread_id} \NC number \NC the thread id \NC \NR \NC \NC string \NC the thread name \NC \NR \NC \type{thread_attr} \NC number \NC extra thread information \NC \NR +\LL \stoptabulate -\subsubsubsection{pdf_start_thread whatsits} +\subsubsubsection{\whs {pdf_start_thread}} \starttabulate[|l|l|p|] \DB field \BC type \BC explanation \NC \NR -\TB[small,samepage] +\TB \NC \type{attr} \NC node \NC list of attributes \NC \NR \NC \type{width} \NC number \NC the width (not used in calculations) \NC \NR \NC \type{height} \NC number \NC the height (not used in calculations) \NC \NR @@ -944,50 +1098,56 @@ Valid window types are: \NC \type{tread_id} \NC number \NC the thread id \NC \NR \NC \NC string \NC the thread name \NC \NR \NC \type{thread_attr} \NC number \NC extra thread information \NC \NR +\LL \stoptabulate -\subsubsubsection{pdf_end_thread whatsits} +\subsubsubsection{\whs {pdf_end_thread}} \starttabulate[|l|l|p|] \DB field \BC type \BC explanation \NC \NR -\TB[small,samepage] +\TB \NC \type{attr} \NC node \NC \NC \NR +\LL \stoptabulate -\subsubsubsection{pdf_colorstack whatsits} +\subsubsubsection{\whs {pdf_colorstack}} \starttabulate[|l|l|p|] \DB field \BC type \BC explanation \NC \NR -\TB[small,samepage] +\TB \NC \type{attr} \NC node \NC list of attributes \NC \NR \NC \type{stack} \NC number \NC colorstack id number \NC \NR \NC \type{command} \NC number \NC command to execute \NC \NR \NC \type{data} \NC string \NC data \NC \NR +\LL \stoptabulate -\subsubsubsection{pdf_setmatrix whatsits} +\subsubsubsection{\whs {pdf_setmatrix}} \starttabulate[|l|l|p|] \DB field \BC type \BC explanation \NC \NR -\TB[small,samepage] +\TB \NC \type{attr} \NC node \NC list of attributes \NC \NR \NC \type{data} \NC string \NC data \NC \NR +\LL \stoptabulate -\subsubsubsection{pdf_save whatsits} +\subsubsubsection{\whs {pdf_save}} \starttabulate[|l|l|p|] \DB field \BC type \BC explanation \NC \NR -\TB[small,samepage] +\TB \NC \type{attr} \NC node \NC list of attributes \NC \NR +\LL \stoptabulate -\subsubsubsection{pdf_restore whatsits} +\subsubsubsection{\whs {pdf_restore}} \starttabulate[|l|l|p|] \DB field \BC type \BC explanation \NC \NR -\TB[small,samepage] +\TB \NC \type{attr} \NC node \NC list of attributes \NC \NR +\LL \stoptabulate \section{The \type {node} library} @@ -1000,8 +1160,7 @@ insert \LUATEX\ node objects, the core objects within the typesetter. \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}: +Each node has at least the three fields \type {next}, \type {id}, and \type {subtype}: \startitemize[intro] @@ -1029,7 +1188,7 @@ 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 +Support for \nod {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 @@ -1053,6 +1212,8 @@ can be handy for tracing. \subsubsection{\type {node.is_node}} +\topicindex {nodes+functions} + \startfunctioncall <boolean> t = node.is_node(<any> item) @@ -1078,7 +1239,7 @@ providing an overview of the possible top|-|level \type {id} types. node.whatsits() \stopfunctioncall -\TEX's \quote{whatsits} all have the same \type {id}. The various subtypes are +\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. @@ -1281,11 +1442,11 @@ This function creates a new hlist by packaging the list that begins at node \typ {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. +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 +like updating some of the \prm {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 @@ -1386,7 +1547,7 @@ cases: 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}. +as for the callback \cbk {mlist_to_hlist}. \subsubsection{\type {node.slide}} @@ -1863,6 +2024,9 @@ some assumptions (heuristics). \section{Two access models} +\topicindex{nodes+direct} +\topicindex{direct nodes} + 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 too. @@ -1931,7 +2095,7 @@ Some accessors are used frequently and for these we provide more efficient helpe \starttabulate[|l|p|] \DB function \BC explanation \NC \NR -\TB[small,samepage] +\TB \NC \type{getnext} \NC parsing nodelist always involves this one \NC \NR \NC \type{getprev} \NC used less but is logical companion to \type {getnext} \NC \NR \NC \type{getboth} \NC returns the next and prev pointer of a node \NC \NR @@ -1949,6 +2113,7 @@ Some accessors are used frequently and for these we provide more efficient helpe \NC \type{getfield} \NC generic getter, sufficient for the rest (other field names are often shared so a specific getter makes no sense then) \NC \NR \NC \type{getbox} \NC gets the given box (a list node) \NC \NR +\LL \stoptabulate In the direct namespace there are more such helpers and most of them are @@ -1972,13 +2137,11 @@ provided and there are a few that probably are used seldom too but were added fo consistency. You can of course always define additional accessor using \type {getfield} and \type {setfield} with little overhead. -% \startcolumns[balance=yes] - \def\yes{$+$} \def\nop{$-$} \starttabulate[|l|c|c|] \DB function \BC node \BC direct \NC \NR -\TB[small,samepage] +\TB %NC \type {do_ligature_n} \NC \yes \NC \yes \NC \NR % was never documented and experimental \NC \type {check_discretionaries}\NC \yes \NC \yes \NC \NR \NC \type {copy_list} \NC \yes \NC \yes \NC \NR @@ -2103,10 +2266,9 @@ consistency. You can of course always define additional accessor using \type \NC \type {write} \NC \yes \NC \yes \NC \NR \NC \type {set_synctex_fields} \NC \yes \NC \yes \NC \NR \NC \type {get_synctex_fields} \NC \yes \NC \yes \NC \NR +\LL \stoptabulate -% \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 to use \type {get} because \type {node.id} and \type {node.subtype} are already |