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 | 319 |
1 files changed, 161 insertions, 158 deletions
diff --git a/doc/context/sources/general/manuals/luatex/luatex-nodes.tex b/doc/context/sources/general/manuals/luatex/luatex-nodes.tex index 8b8668b3e..a34008a1c 100644 --- a/doc/context/sources/general/manuals/luatex/luatex-nodes.tex +++ b/doc/context/sources/general/manuals/luatex/luatex-nodes.tex @@ -42,51 +42,7 @@ 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 -dedicated functions in the \type {node} library, but for completeness, here is -the low|-|level interface. - -\subsubsection{attribute_list nodes} - -\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 -\NC \type{next} \NC node \NC pointer to the first attribute \NC \NR -\LL -\stoptabulate - -\subsubsection{\nod {attr} nodes} - -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 -\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 -fields directly. For instance the \type {prev} field is used for other purposes -and there is no double linked list. - -\subsection{Main text nodes} +\section{Main text nodes} \topicindex {nodes+text} @@ -115,7 +71,7 @@ the argument node list. By now most of \TEX's node processing makes sure that th \type {prev} nodes are valid but there can be exceptions, especially when the internal magic uses a leading \nod {temp} nodes to temporarily store a state. -\subsubsection{\nod {hlist} nodes} +\subsection{\nod {hlist} nodes} \starttabulate[|l|l|p|] \DB field \BC type \BC explanation \NC \NR @@ -147,7 +103,7 @@ 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{\nod {vlist} nodes} +\subsection{\nod {vlist} nodes} \topicindex {nodes+lists} \topicindex {lists} @@ -156,7 +112,7 @@ This node is similar to \nod {hlist}, except that \quote {shift} is a displaceme perpendicular to the line progression direction, and \quote {subtype} only has the values 0, 4, and~5. -\subsubsection{\nod {rule} nodes} +\subsection{\nod {rule} nodes} \topicindex {nodes+rules} \topicindex {rules} @@ -196,7 +152,7 @@ construct a rule node with \LUA\ and write it to the \TEX\ input. The \type {outline} subtype is just a convenient variant and the \type {transform} field specifies the width of the outline. -\subsubsection{\nod {ins} nodes} +\subsection{\nod {ins} nodes} \topicindex {nodes+insertions} \topicindex {insertions} @@ -224,7 +180,7 @@ its internal link structure is correct, otherwise an error may result. You can u \type {list} instead (often in functions you want to use local variable with similar names and both names are equally sensible). -\subsubsection{\nod {mark} nodes} +\subsection{\nod {mark} nodes} \topicindex {nodes+marks} \topicindex {marks} @@ -241,7 +197,7 @@ This one relates to the \prm {mark} primitive. \LL \stoptabulate -\subsubsection{\nod {adjust} nodes} +\subsection{\nod {adjust} nodes} \topicindex {nodes+adjust} \topicindex {adjust} @@ -260,7 +216,7 @@ This node comes from \prm {vadjust} primitive. 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 the result. -\subsubsection{\nod {disc} nodes} +\subsection{\nod {disc} nodes} \topicindex {nodes+discretionaries} \topicindex {discretionaries} @@ -304,7 +260,7 @@ And you definitely must not mess with the node that \type {prev} points to, if only because it is not really a node but part of the disc data structure (so freeing it again might crash \LUATEX). -\subsubsection{\nod {math} nodes} +\subsection{\nod {math} nodes} \topicindex {nodes+math} \topicindex {math+nodes} @@ -325,7 +281,7 @@ 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{\nod {glue} nodes} +\subsection{\nod {glue} nodes} \topicindex {nodes+glue} \topicindex {glue} @@ -388,7 +344,7 @@ 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{\nod {kern} nodes} +\subsection{\nod {kern} nodes} \topicindex {nodes+kerns} \topicindex {kerns} @@ -405,7 +361,7 @@ machinery can also add them. \LL \stoptabulate -\subsubsection{\nod {penalty} nodes} +\subsection{\nod {penalty} nodes} \topicindex {nodes+penalty} \topicindex {penalty} @@ -425,7 +381,7 @@ 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]{\nod {glyph} nodes} +\subsection[glyphnodes]{\nod {glyph} nodes} \topicindex {nodes+glyph} \topicindex {glyphs} @@ -497,7 +453,7 @@ 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{\nod {boundary} nodes} +\subsection{\nod {boundary} nodes} \topicindex {nodes+boundary} \topicindex {boundary} @@ -514,7 +470,7 @@ This node relates to the \prm {noboundary}, \prm {boundary}, \prm \LL \stoptabulate -\subsubsection{\nod {local_par} nodes} +\subsection{\nod {local_par} nodes} \topicindex {nodes+paragraphs} \topicindex {paragraphs} @@ -540,7 +496,7 @@ 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 result. -\subsubsection[dirnodes]{\nod {dir} nodes} +\subsection[dirnodes]{\nod {dir} nodes} \topicindex {nodes+direction} \topicindex {directions} @@ -578,7 +534,7 @@ However, only four combinations are accepted: \type {TLT}, \type {TRT}, \type direction is indicated by a \type {+} or \type {-}, indicating whether the value is pushed or popped from the direction stack. -\subsubsection{\nod {marginkern} nodes} +\subsection{\nod {marginkern} nodes} \topicindex {nodes+paragraphs} \topicindex {paragraphs} @@ -596,7 +552,7 @@ Margin kerns result from protrusion. \LL \stoptabulate -\subsection{Math noads} +\section{Math noads} \topicindex {nodes+math} \topicindex {math+nodes} @@ -605,7 +561,7 @@ 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 list of possible fields is actually quite small. First, the subnodes: -\subsubsection{Math kernel subnodes} +\subsection{Math kernel subnodes} Many object fields in math mode are either simple characters in a specific family or math lists or node lists. There are four associated subnodes that represent @@ -614,7 +570,7 @@ 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{\nod {math_char} and \nod {math_text_char} subnodes} +\subsection{\nod {math_char} and \nod {math_text_char} subnodes} \starttabulate[|l|l|p|] \DB field \BC type \BC explanation \NC \NR @@ -630,7 +586,7 @@ 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{\nod {sub_box} and \nod {sub_mlist} subnodes} +\subsection{\nod {sub_box} and \nod {sub_mlist} subnodes} \starttabulate[|l|l|p|] \DB field \BC type \BC explanation \NC \NR @@ -647,7 +603,7 @@ 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 is triggered. -\subsubsubsection{\nod {delim} subnodes} +\subsection{\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. @@ -667,7 +623,7 @@ The fields \type {large_char} and \type {large_fam} can be zero, in that case th font that is set for the \type {small_fam} is expected to provide the large version as an extension to the \type {small_char}. -\subsubsection{Math core nodes} +\subsection{Math core nodes} First, there are the objects (the \TEX book calls them \quote {atoms}) that are associated with the simple math objects: ord, op, bin, rel, open, close, punct, @@ -694,7 +650,7 @@ Some noads have an option field. The values in this bitset are common: \LL \stoptabulate -\subsubsubsection{simple \nod {noad} nodes} +\subsection{simple \nod {noad} nodes} \starttabulate[|l|l|p|] \DB field \BC type \BC explanation \NC \NR @@ -708,7 +664,7 @@ Some noads have an option field. The values in this bitset are common: \LL \stoptabulate -\subsubsubsection{\nod {accent} nodes} +\subsection{\nod {accent} nodes} \starttabulate[|l|l|p|] \DB field \BC type \BC explanation \NC \NR @@ -723,7 +679,7 @@ Some noads have an option field. The values in this bitset are common: \LL \stoptabulate -\subsubsubsection{\nod {style} nodes} +\subsection{\nod {style} nodes} \starttabulate[|l|l|p|] \DB field \BC type \BC explanation \NC \NR @@ -736,7 +692,7 @@ 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{\nod {choice} nodes} +\subsection{\nod {choice} nodes} \starttabulate[|l|l|p|] \DB field \BC type \BC explanation \NC \NR @@ -753,7 +709,7 @@ 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 can occur. -\subsubsubsection{\nod {radical} nodes} +\subsection{\nod {radical} nodes} \starttabulate[|l|l|p|] \DB field \BC type \BC explanation \NC \NR @@ -774,7 +730,7 @@ 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 can be triggered. -\subsubsubsection{\nod {fraction} nodes} +\subsection{\nod {fraction} nodes} \starttabulate[|l|l|p|] \DB field \BC type \BC explanation \NC \NR @@ -794,7 +750,7 @@ 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 can result. -\subsubsubsection{\nod {fence} nodes} +\subsection{\nod {fence} nodes} \starttabulate[|l|l|p|] \DB field \BC type \BC explanation \NC \NR @@ -813,7 +769,7 @@ can result. Warning: some of these fields are used by the renderer and might get adapted in the process. -\subsection{whatsit nodes} +\section{whatsit nodes} Whatsit nodes come in many subtypes that you can ask for them by running \type {node.whatsits()}: @@ -827,9 +783,9 @@ Whatsit nodes come in many subtypes that you can ask for them by running \stopluacode . % period -\subsubsection{front|-|end whatsits} +\section{Front|-|end whatsits} -\subsubsubsection{\whs {open}} +\subsection{\whs {open}} \starttabulate[|l|l|p|] \DB field \BC type \BC explanation \NC \NR @@ -842,7 +798,7 @@ Whatsit nodes come in many subtypes that you can ask for them by running \LL \stoptabulate -\subsubsubsection{\whs {write}} +\subsection{\whs {write}} \starttabulate[|l|l|p|] \DB field \BC type \BC explanation \NC \NR @@ -853,7 +809,7 @@ Whatsit nodes come in many subtypes that you can ask for them by running \LL \stoptabulate -\subsubsubsection{\whs {close}} +\subsection{\whs {close}} \starttabulate[|l|l|p|] \DB field \BC type \BC explanation \NC \NR @@ -863,7 +819,7 @@ Whatsit nodes come in many subtypes that you can ask for them by running \LL \stoptabulate -\subsubsubsection{\whs {user_defined}} +\subsection{\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 @@ -898,7 +854,7 @@ instead of \type {108}). \LL \stoptabulate -\subsubsubsection{\whs {save_pos}} +\subsection{\whs {save_pos}} \starttabulate[|l|l|p|] \DB field \BC type \BC explanation \NC \NR @@ -907,7 +863,7 @@ instead of \type {108}). \LL \stoptabulate -\subsubsubsection{\whs {late_lua}} +\subsection{\whs {late_lua}} \starttabulate[|l|l|p|] \DB field \BC type \BC explanation \NC \NR @@ -923,9 +879,12 @@ The difference between \type {data} and \type {string} is that on assignment, th \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} +\section{\DVI\ backend whatsits} -\subsubsubsection{\whs {special}} +\subsection{\whs {special}} + +There is only one \DVI\ backend whatsit, and it just flushes its content to the +output file. \starttabulate[|l|l|p|] \DB field \BC type \BC explanation \NC \NR @@ -935,9 +894,9 @@ The difference between \type {data} and \type {string} is that on assignment, th \LL \stoptabulate -\subsubsection{\PDF\ backend whatsits} +\section{\PDF\ backend whatsits} -\subsubsubsection{\whs {pdf_literal}} +\subsection{\whs {pdf_literal}} \starttabulate[|l|l|p|] \DB field \BC type \BC explanation \NC \NR @@ -965,7 +924,7 @@ The higher the number, the less checking and the more you can run into trouble. Especially the \type {raw} variant can produce bad \PDF\ so you can best check what you generate. -\subsubsubsection{\whs {pdf_refobj}} +\subsection{\whs {pdf_refobj}} \starttabulate[|l|l|p|] \DB field \BC type \BC explanation \NC \NR @@ -975,7 +934,7 @@ what you generate. \LL \stoptabulate -\subsubsubsection{\whs {pdf_annot}} +\subsection{\whs {pdf_annot}} \starttabulate[|l|l|p|] \DB field \BC type \BC explanation \NC \NR @@ -989,7 +948,7 @@ what you generate. \LL \stoptabulate -\subsubsubsection{\whs {pdf_start_link}} +\subsection{\whs {pdf_start_link}} \starttabulate[|l|l|p|] \DB field \BC type \BC explanation \NC \NR @@ -1004,7 +963,7 @@ what you generate. \LL \stoptabulate -\subsubsubsection{\whs {pdf_end_link}} +\subsection{\whs {pdf_end_link}} \starttabulate[|l|l|p|] \DB field \BC type \BC explanation \NC \NR @@ -1013,7 +972,7 @@ what you generate. \LL \stoptabulate -\subsubsubsection{\whs {pdf_dest}} +\subsection{\whs {pdf_dest}} \starttabulate[|l|l|p|] \DB field \BC type \BC explanation \NC \NR @@ -1031,7 +990,7 @@ what you generate. \LL \stoptabulate -\subsubsubsection{\whs {pdf_action}} +\subsection{\whs {pdf_action}} These are a special kind of items that only appear inside \PDF\ start link objects. @@ -1071,7 +1030,7 @@ Valid window types are: \LL \stoptabulate -\subsubsubsection{\whs {pdf_thread}} +\subsection{\whs {pdf_thread}} \starttabulate[|l|l|p|] \DB field \BC type \BC explanation \NC \NR @@ -1087,7 +1046,7 @@ Valid window types are: \LL \stoptabulate -\subsubsubsection{\whs {pdf_start_thread}} +\subsection{\whs {pdf_start_thread}} \starttabulate[|l|l|p|] \DB field \BC type \BC explanation \NC \NR @@ -1103,7 +1062,7 @@ Valid window types are: \LL \stoptabulate -\subsubsubsection{\whs {pdf_end_thread}} +\subsection{\whs {pdf_end_thread}} \starttabulate[|l|l|p|] \DB field \BC type \BC explanation \NC \NR @@ -1112,7 +1071,7 @@ Valid window types are: \LL \stoptabulate -\subsubsubsection{\whs {pdf_colorstack}} +\subsection{\whs {pdf_colorstack}} \starttabulate[|l|l|p|] \DB field \BC type \BC explanation \NC \NR @@ -1124,7 +1083,7 @@ Valid window types are: \LL \stoptabulate -\subsubsubsection{\whs {pdf_setmatrix}} +\subsection{\whs {pdf_setmatrix}} \starttabulate[|l|l|p|] \DB field \BC type \BC explanation \NC \NR @@ -1134,7 +1093,7 @@ Valid window types are: \LL \stoptabulate -\subsubsubsection{\whs {pdf_save}} +\subsection{\whs {pdf_save}} \starttabulate[|l|l|p|] \DB field \BC type \BC explanation \NC \NR @@ -1143,7 +1102,7 @@ Valid window types are: \LL \stoptabulate -\subsubsubsection{\whs {pdf_restore}} +\subsection{\whs {pdf_restore}} \starttabulate[|l|l|p|] \DB field \BC type \BC explanation \NC \NR @@ -1154,6 +1113,8 @@ Valid window types are: \section{The \type {node} library} +\subsection {Introduction} + 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. @@ -1210,9 +1171,7 @@ and getters handle this for you. 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}} +\subsection{\type {node.is_node}} \topicindex {nodes+functions} @@ -1224,7 +1183,7 @@ can be handy for tracing. This function returns a number (the internal index of the node) if the argument is a userdata object of type \type {<node>} and false when no node is passed. -\subsubsection{\type {node.types}} +\subsection{\type {node.types}} \startfunctioncall <table> t = @@ -1234,7 +1193,7 @@ is a userdata object of type \type {<node>} and false when no node is passed. 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}} +\subsection{\type {node.whatsits}} \startfunctioncall <table> t = @@ -1245,7 +1204,7 @@ providing an overview of the possible top|-|level \type {id} types. 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}} +\subsection{\type {node.id}} \startfunctioncall <number> id = @@ -1254,7 +1213,7 @@ defined by their \type {subtype} fields. The function is much like \type This converts a single type name to its internal numeric representation. -\subsubsection{\type {node.subtype}} +\subsection{\type {node.subtype}} \startfunctioncall <number> subtype = @@ -1264,7 +1223,7 @@ This converts a single type name to its internal numeric representation. This converts a single whatsit name to its internal numeric representation (\type {subtype}). -\subsubsection{\type {node.type}} +\subsection{\type {node.type}} \startfunctioncall <string> type = @@ -1276,7 +1235,7 @@ 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}} +\subsection{\type {node.fields}} \startfunctioncall <table> t = @@ -1292,7 +1251,7 @@ be silently ignored. This function accepts string \type {id} and \type {subtype} values as well. -\subsubsection{\type {node.has_field}} +\subsection{\type {node.has_field}} \startfunctioncall <boolean> t = @@ -1302,7 +1261,7 @@ This function accepts string \type {id} and \type {subtype} values as well. 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}} +\subsection{\type {node.new}} \startfunctioncall <node> n = @@ -1317,7 +1276,7 @@ numbers you can also use strings (names). If you create a new \nod {whatsit} nod the second argument is required. As with all node functions, this function creates a node at the \TEX\ level. -\subsubsection{\type {node.free} and \type {node.flush_node}} +\subsection{\type {node.free} and \type {node.flush_node}} \startfunctioncall <node> next = @@ -1332,7 +1291,7 @@ it is up to you to make sure that the internal data structures remain correct. The \type {free} function returns the next field of the freed node, while the \type {flush_node} alternative returns nothing. -\subsubsection{\type {node.flush_list}} +\subsection{\type {node.flush_list}} \startfunctioncall node.flush_list(<node> n) @@ -1343,7 +1302,7 @@ 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}} +\subsection{\type {node.copy}} \startfunctioncall <node> m = @@ -1353,7 +1312,7 @@ to make sure that the internal data structures remain correct. 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}} +\subsection{\type {node.copy_list}} \startfunctioncall <node> m = @@ -1371,7 +1330,7 @@ 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}} +\subsection{\type {node.next}} \startfunctioncall <node> m = @@ -1380,7 +1339,7 @@ needed copying and freeing takes place automatically. Returns the node following this node, or \type {nil} if there is no such node. -\subsubsection{\type {node.prev}} +\subsection{\type {node.prev}} \startfunctioncall <node> m = @@ -1389,7 +1348,7 @@ Returns the node following this node, or \type {nil} if there is no such node. Returns the node preceding this node, or \type {nil} if there is no such node. -\subsubsection{\type {node.current_attr}} +\subsection{\type {node.current_attr}} \startfunctioncall <node> m = @@ -1427,7 +1386,7 @@ 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}} +\subsection{\type {node.hpack}} \startfunctioncall <node> h, <number> b = @@ -1452,7 +1411,7 @@ content of \type {h} is the original node list \type {n}: if you call \type 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}} +\subsection{\type {node.vpack}} \startfunctioncall <node> h, <number> b = @@ -1473,7 +1432,7 @@ 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}, \type {node.rangedimensions}} +\subsection{\type {node.dimensions}, \type {node.rangedimensions}} \startfunctioncall <number> w, <number> h, <number> d = @@ -1538,7 +1497,7 @@ cases: node.rangedimensions(<node> parent, <node> first, <node> last) \stopfunctioncall -\subsubsection{\type {node.mlist_to_hlist}} +\subsection{\type {node.mlist_to_hlist}} \startfunctioncall <node> h = @@ -1549,7 +1508,7 @@ 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 \cbk {mlist_to_hlist}. -\subsubsection{\type {node.slide}} +\subsection{\type {node.slide}} \startfunctioncall <node> m = @@ -1560,7 +1519,7 @@ 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}} +\subsection{\type {node.tail}} \startfunctioncall <node> m = @@ -1569,7 +1528,7 @@ nodes. Returns the last node of the node list that starts at \type {n}. -\subsubsection{\type {node.length}} +\subsection{\type {node.length}} \startfunctioncall <number> i = @@ -1582,7 +1541,7 @@ 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}} +\subsection{\type {node.count}} \startfunctioncall <number> i = @@ -1598,7 +1557,7 @@ counted. This function also accept string \type {id}'s. -\subsubsection{\type {node.traverse}} +\subsection{\type {node.traverse}} \startfunctioncall <node> t, id, subtype = @@ -1644,7 +1603,7 @@ 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}} +\subsection{\type {node.traverse_id}} \startfunctioncall <node> t, subtype = @@ -1672,7 +1631,7 @@ See the previous section for details. The change is in the local function \type end \stoptyping -\subsubsection{\type {node.traverse_char}} +\subsection{\type {node.traverse_char}} This iterator loops over the \nod {glyph} nodes in a list. Only nodes with a subtype less than 256 are seen. @@ -1682,7 +1641,7 @@ subtype less than 256 are seen. node.traverse_char(<node> n) \stopfunctioncall -\subsubsection{\type {node.traverse_glyph}} +\subsection{\type {node.traverse_glyph}} This iterator loops over a list and returns the list and filters all glyphs: @@ -1691,7 +1650,7 @@ This iterator loops over a list and returns the list and filters all glyphs: node.traverse_glyph(<node> n) \stopfunctioncall -\subsubsection{\type {node.traverse_list}} +\subsection{\type {node.traverse_list}} This iterator loops over the \nod {hlist} and \nod {vlist} nodes in a list. @@ -1704,7 +1663,7 @@ The four return values can save some time compared to fetching these fields but in practice you seldom need them all. So consider it a (side effect of experimental) convenience. -\subsubsection{\type {node.has_glyph}} +\subsection{\type {node.has_glyph}} This function returns the first glyph or disc node in the given list: @@ -1713,7 +1672,7 @@ This function returns the first glyph or disc node in the given list: node.has_glyph(<node> n) \stopfunctioncall -\subsubsection{\type {node.end_of_math}} +\subsection{\type {node.end_of_math}} \startfunctioncall <node> t = @@ -1725,7 +1684,7 @@ the given node is a math end node this helper returns that node, else it follows the list and returns the next math endnote. If no such node is found nil is returned. -\subsubsection{\type {node.remove}} +\subsection{\type {node.remove}} \startfunctioncall <node> head, current = @@ -1741,7 +1700,7 @@ 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}} +\subsection{\type {node.insert_before}} \startfunctioncall <node> head, new = @@ -1755,7 +1714,7 @@ 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}} +\subsection{\type {node.insert_after}} \startfunctioncall <node> head, new = @@ -1768,7 +1727,7 @@ following \type {head}. It is your responsibility to make sure that \type 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}} +\subsection{\type {node.first_glyph}} \startfunctioncall <node> n = @@ -1782,7 +1741,7 @@ 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}} +\subsection{\type {node.ligaturing}} \startfunctioncall <node> h, <node> t, <boolean> success = @@ -1795,7 +1754,7 @@ Apply \TEX-style ligaturing to the specified nodelist. The tail node \type {m} i 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}} +\subsection{\type {node.kerning}} \startfunctioncall <node> h, <node> t, <boolean> success = @@ -1809,7 +1768,7 @@ 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} and \type {node.unprotect_glyph}} +\subsection{\type {node.unprotect_glyphs} and \type {node.unprotect_glyph}} \startfunctioncall node.unprotect_glyph(<node> n) @@ -1820,7 +1779,7 @@ 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. The second argument is optional and indicates the end of a range. -\subsubsection{\type {node.protect_glyphs} and \type {node.protect_glyph}} +\subsection{\type {node.protect_glyphs} and \type {node.protect_glyph}} \startfunctioncall node.protect_glyph(<node> n) @@ -1833,7 +1792,7 @@ that \type {characters} will become \type {glyphs} after subtraction of 256. A single character can be marked by the singular call. The second argument is optional and indicates the end of a range. -\subsubsection{\type {node.last_node}} +\subsection{\type {node.last_node}} \startfunctioncall <node> n = @@ -1843,7 +1802,7 @@ optional and indicates the end of a range. 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}} +\subsection{\type {node.write}} \startfunctioncall node.write(<node> n) @@ -1853,7 +1812,7 @@ This 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! You mignt need to enforce horizontal mode in order for this to work as expected. -\subsubsection{\type {node.protrusion_skippable}} +\subsection{\type {node.protrusion_skippable}} \startfunctioncall <boolean> skippable = @@ -1863,9 +1822,9 @@ to enforce horizontal mode in order for this to work as expected. Returns \type {true} if, for the purpose of line boundary discovery when character protrusion is active, this node can be skipped. -\subsection{Glue handling} +\section{Glue handling} -\subsubsection{\type {node.setglue}} +\subsection{\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. @@ -1885,7 +1844,7 @@ will only adapt the width and shrink. When a list node is passed, you set the glue, order and sign instead. -\subsubsection{\type {node.getglue}} +\subsection{\type {node.getglue}} The next call will return 5 values or nothing when no glue is passed. @@ -1900,7 +1859,7 @@ with \type {tex.get}). When a list node is passed, you get back the glue that is set, the order of that glue and the sign. -\subsubsection{\type {node.is_zero_glue}} +\subsection{\type {node.is_zero_glue}} This function returns \type {true} when the width, stretch and shrink properties are zero. @@ -1910,13 +1869,57 @@ are zero. node.is_zero_glue(<node> n) \stopfunctioncall -\subsection{Attribute handling} +\section{Attribute handling} + +\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 +dedicated functions in the \type {node} library, but for completeness, here is +the low|-|level interface. 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}} +\subsection{attribute_list nodes} + +\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 +\NC \type{next} \NC node \NC pointer to the first attribute \NC \NR +\LL +\stoptabulate + +\subsection{\nod {attr} nodes} + +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 +\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 +fields directly. For instance the \type {prev} field is used for other purposes +and there is no double linked list. + +\subsection{\type {node.has_attribute}} \startfunctioncall <number> v = @@ -1929,7 +1932,7 @@ 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.get_attribute}} +\subsection{\type {node.get_attribute}} \startfunctioncall <number> v = @@ -1940,7 +1943,7 @@ Tests if a node has an attribute with number \type {id} set. It returns the value, or, if no match is found, \type {nil}. If no \type {id} is given then the zero attributes is assumed. -\subsubsection{\type {node.find_attribute}} +\subsection{\type {node.find_attribute}} \startfunctioncall <number> v, <node> n = @@ -1950,7 +1953,7 @@ zero attributes is assumed. Finds the first node that has attribute with number \type {id} set. It returns the value and the node if there is a match and otherwise nothing. -\subsubsection{\type {node.set_attribute}} +\subsection{\type {node.set_attribute}} \startfunctioncall node.set_attribute(<node> n, <number> id, <number> val) @@ -1959,7 +1962,7 @@ node.set_attribute(<node> n, <number> id, <number> val) Sets the attribute with number \type {id} to the value \type {val}. Duplicate assignments are ignored. -\subsubsection{\type {node.unset_attribute}} +\subsection{\type {node.unset_attribute}} \startfunctioncall <number> v = @@ -1975,7 +1978,7 @@ attributes or attribute|-|value pairs are ignored. If the attribute was actually deleted, returns its old value. Otherwise, returns \type {nil}. -\subsubsection{\type {node.slide}} +\subsection{\type {node.slide}} This helper makes sure that the node lists is double linked and returns the found tail node. @@ -1992,7 +1995,7 @@ pointers but your other callbacks might expect proper \type {prev} pointers too. Future versions of \LUATEX\ can add more checking but this will not influence usage. -\subsubsection{\type {node.check_discretionary} and \type {node.check_discretionaries}} +\subsection{\type {node.check_discretionary} and \type {node.check_discretionaries}} When you fool around with disc nodes you need to be aware of the fact that they have a special internal data structure. As long as you reassign the fields when @@ -2009,7 +2012,7 @@ node.check_discretionaries(<node> head) The plural variant runs over all disc nodes in a list, the singular variant checks one node only (it also checks if the node is a disc node). -\subsubsection{\type {node.flatten_discretionaries}} +\subsection{\type {node.flatten_discretionaries}} This function will remove the discretionaries in the list and inject the replace field when set. @@ -2018,7 +2021,7 @@ field when set. <node> head, count = node.flatten_discretionaries(<node> n) \stopfunctioncall -\subsubsection{\type {node.family_font}} +\subsection{\type {node.family_font}} When you pass a proper family identifier the next helper will return the font currently associated with it. You can normally also access the font with the @@ -2030,7 +2033,7 @@ noads. node.family_font(<integer> fam) \stopfunctioncall -\subsubsection{\type {node.set_synctex_fields} and \type {node.get_synctex_fields}} +\subsection{\type {node.set_synctex_fields} and \type {node.get_synctex_fields}} You can set and query the synctex fields, a file number aka tag and a line number, for a glue, kern, hlist, vlist, rule and math nodes as well as glyph |