diff options
| author | Hans Hagen <pragma@wxs.nl> | 2018-07-02 16:09:16 +0200 |
|---|---|---|
| committer | Context Git Mirror Bot <phg42.2a@gmail.com> | 2018-07-02 16:09:16 +0200 |
| commit | 847821faaecf92833f1e1564e1ef9377758d4d45 (patch) | |
| tree | 7a033668d823e231478c055daeb47c4582883059 /doc/context/sources/general/manuals | |
| parent | 052a096e160508ddbbbfcbf1522eb8ddbfc3b1cd (diff) | |
| download | context-847821faaecf92833f1e1564e1ef9377758d4d45.tar.gz | |
2018-07-02 14:46:00
Diffstat (limited to 'doc/context/sources/general/manuals')
9 files changed, 1302 insertions, 997 deletions
diff --git a/doc/context/sources/general/manuals/luatex/luatex-enhancements.tex b/doc/context/sources/general/manuals/luatex/luatex-enhancements.tex index 243dc6985..5a2764f68 100644 --- a/doc/context/sources/general/manuals/luatex/luatex-enhancements.tex +++ b/doc/context/sources/general/manuals/luatex/luatex-enhancements.tex @@ -6,12 +6,14 @@ \startchapter[reference=enhancements,title={Basic \TEX\ enhancements}] -\section{Introduction} +\startsection[title={Introduction}] + +\startsubsection[title={Primitive behaviour}] From day one, \LUATEX\ has offered extra features compared to the superset of -\PDFTEX\ and \ALEPH. This has not been limited to the possibility to execute -\LUA\ code via \prm {directlua}, but \LUATEX\ also adds functionality via new -\TEX|-|side primitives or extensions to existing ones. +\PDFTEX, which includes \ETEX, and \ALEPH. This has not been limited to the +possibility to execute \LUA\ code via \prm {directlua}, but \LUATEX\ also adds +functionality via new \TEX|-|side primitives or extensions to existing ones. When \LUATEX\ starts up in \quote {iniluatex} mode (\type {luatex -ini}), it defines only the primitive commands known by \TEX82 and the one extra command @@ -39,17 +41,19 @@ assumes that you have executed the \prm {directlua} command as given above. The startup behaviour documented above is considered stable in the sense that there will not be backward|-|incompatible changes any more. We have promoted some -rather generic \PDFTEX\ primitives to core \LUATEX\ ones, and the ones inherited -from \ALEPH\ (\OMEGA) are also promoted. Effectively this means that we now only -have the \type {tex}, \type {etex} and \type {luatex} sets left. +rather generic \PDFTEX\ primitives to core \LUATEX\ ones, and the few that we +inherited from \ALEPH\ (\OMEGA) are also promoted. Effectively this means that we +now only have the \type {tex}, \type {etex} and \type {luatex} sets left. In \in {Chapter} [modifications] we discuss several primitives that are derived from \PDFTEX\ and \ALEPH\ (\OMEGA). Here we stick to real new ones. In the chapters on fonts and math we discuss a few more new ones. -\section{Version information} +\stopsubsection + +\startsubsection[title={Version information}] -\subsection {\lpr {luatexbanner}, \lpr {luatexversion} and \lpr {luatexrevision}} +\startsubsubsection {\lpr {luatexbanner}, \lpr {luatexversion} and \lpr {luatexrevision}} \topicindex{version} \topicindex{banner} @@ -93,7 +97,9 @@ The official \LUATEX\ version is defined as follows: \stopitem \stopitemize -\subsection{\lpr {formatname}} +\stopsubsubsection + +\startsubsubsection{\lpr {formatname}} \topicindex{format} @@ -102,9 +108,15 @@ expansion is empty. Otherwise, the expansion is the value that \prm {jobname} ha during the \INITEX\ run that dumped the currently loaded format. You can use this token list to provide your own version info. -\section{\UNICODE\ text support} +\stopsubsubsection + +\stopsubsection + +\stopsection + +\startsection[title={\UNICODE\ text support}] -\subsection {Extended ranges} +\startsubsection[title={Extended ranges}] \topicindex{\UNICODE} @@ -133,7 +145,8 @@ As far as the core engine is concerned, all input and output to text files is \UTF-8 encoded. Input files can be pre|-|processed using the \type {reader} callback. This will be explained in \in {section} [iocallback]. Normalization of the \UNICODE\ input is on purpose not built|-|in and can be handled by a macro -package during callback processing. +package during callback processing. We have made some practical choices and the +user has to live with those. Output in byte|-|sized chunks can be achieved by using characters just outside of the valid \UNICODE\ range, starting at the value $1{,}114{,}112$ (0x110000). When @@ -146,14 +159,18 @@ are considered \quote {safe} and therefore printed as|-|is. You can disable escaping with \type {texio.setescape(false)} in which case you get the normal characters on the console. -\subsection{\lpr {Uchar}} +\stopsubsection + +\startsubsection[title={\lpr {Uchar}}] \topicindex{\UNICODE} The expandable command \lpr {Uchar} reads a number between~0 and $1{,}114{,}111$ and expands to the associated \UNICODE\ character. -\section{Extended tables} +\stopsubsection + +\startsubsection[title={Extended tables}] All traditional \TEX\ and \ETEX\ registers can be 16-bit numbers. The affected commands are: @@ -188,41 +205,17 @@ commands are: Because font memory management has been rewritten, character properties in fonts are no longer shared among font instances that originate from the same metric -file. - -\section{Attributes} +file. Of course we share fonts in the backend when possible so that the resulting +\PDF\ file is as efficient as possible, but for instance also expansion and +protrusion no longer use copies as in \PDFTEX. -\subsection{Attribute registers} +\stopsubsection -\topicindex {attributes} - -Attributes are a completely new concept in \LUATEX. Syntactically, they behave a -lot like counters: attributes obey \TEX's nesting stack and can be used after -\prm {the} etc.\ just like the normal \prm {count} registers. - -\startsyntax -\attribute <16-bit number> <optional equals> <32-bit number>!crlf -\attributedef <csname> <optional equals> <16-bit number> -\stopsyntax - -Conceptually, an attribute is either \quote {set} or \quote {unset}. Unset -attributes have a special negative value to indicate that they are unset, that -value is the lowest legal value: \type {-"7FFFFFFF} in hexadecimal, a.k.a. -$-2147483647$ in decimal. It follows that the value \type {-"7FFFFFFF} cannot be -used as a legal attribute value, but you {\it can\/} assign \type {-"7FFFFFFF} to -\quote {unset} an attribute. All attributes start out in this \quote {unset} -state in \INITEX. - -Attributes can be used as extra counter values, but their usefulness comes mostly -from the fact that the numbers and values of all \quote {set} attributes are -attached to all nodes created in their scope. These can then be queried from any -\LUA\ code that deals with node processing. Further information about how to use -attributes for node list processing from \LUA\ is given in~\in {chapter}[nodes]. +\stopsection -Attributes are stored in a sorted (sparse) linked list that are shared when -possible. This permits efficient testing and updating. +\startsection[title={Attributes}] -\subsection{Nodes} +\startsubsection[title={Nodes}] \topicindex {nodes} @@ -249,10 +242,53 @@ constructed explicitly or can be the result of subprocesses. For instance, when lines are broken into paragraphs, the lines are a linked list of \nod {hlist} nodes. -We will see more of these nodes later on but for now that should be enough to be -able to follow the rest of this chapter. +So, to summarize: all that you enter as content eventually becomes a node, often +as part of a (nested) list structure. They have a relative small memory footprint +and carry only the minimal amount of information needed. In traditional \TEX\ a +character node only held the font and slot number, in \LUATEX\ we also store some +language related information, the expansion factor, etc. Now that we have access +to these nodes from \LUA\ it makes sense to be able to carry more information +with an node and this is where attributes kick in. + +\stopsubsection + +\startsubsection[title={Attribute registers}] + +\topicindex {attributes} + +Attributes are a completely new concept in \LUATEX. Syntactically, they behave a +lot like counters: attributes obey \TEX's nesting stack and can be used after +\prm {the} etc.\ just like the normal \prm {count} registers. + +\startsyntax +\attribute <16-bit number> <optional equals> <32-bit number>!crlf +\attributedef <csname> <optional equals> <16-bit number> +\stopsyntax + +Conceptually, an attribute is either \quote {set} or \quote {unset}. Unset +attributes have a special negative value to indicate that they are unset, that +value is the lowest legal value: \type {-"7FFFFFFF} in hexadecimal, a.k.a. +$-2147483647$ in decimal. It follows that the value \type {-"7FFFFFFF} cannot be +used as a legal attribute value, but you {\it can\/} assign \type {-"7FFFFFFF} to +\quote {unset} an attribute. All attributes start out in this \quote {unset} +state in \INITEX. -\subsection{Box attributes} +Attributes can be used as extra counter values, but their usefulness comes mostly +from the fact that the numbers and values of all \quote {set} attributes are +attached to all nodes created in their scope. These can then be queried from any +\LUA\ code that deals with node processing. Further information about how to use +attributes for node list processing from \LUA\ is given in~\in {chapter}[nodes]. + +Attributes are stored in a sorted (sparse) linked list that are shared when +possible. This permits efficient testing and updating. You can define many +thousands of attributes but normally such a large number makes no sense and is +also not that efficient because each node carries a (possibly shared) link to a +list of currently set attributes. But they are a convenient extension and one of +the first extensions we implemented in \LUATEX. + +\stopsubsection + +\startsubsection[title={Box attributes}] \topicindex {attributes} \topicindex {boxes} @@ -328,9 +364,13 @@ indexing the node (here we do that with \type {[a]}. Running this snippet gives: Because some values are not set we need to apply the \type {tostring} function here so that we get the word \type {nil}. -\section{\LUA\ related primitives} +\stopsubsection + +\stopsection + +\startsection[title={\LUA\ related primitives}] -\subsection{\prm {directlua}} +\startsubsection[title={\prm {directlua}}] In order to merge \LUA\ code with \TEX\ input, a few new primitives are needed. The primitive \prm {directlua} is used to execute \LUA\ code immediately. The @@ -421,7 +461,9 @@ can break up \LUATEX\ pretty bad. If you are not careful while working with the node list interface, you may even end up with assertion errors from within the \TEX\ portion of the executable. -\subsection{\lpr {latelua}} +\stopsubsection + +\startsubsection[title={\lpr {latelua}}] Contrary to \prm {directlua}, \lpr {latelua} stores \LUA\ code in a whatsit that will be processed at the time of shipping out. Its intended use is a cross @@ -442,7 +484,9 @@ output stream \lpr {latelua} behaves as \PDF\ page literals. The \syntax {name <general text>} and \syntax {<16-bit number>} behave in the same way as they do for \prm {directlua} -\subsection{\lpr {luaescapestring}} +\stopsubsection + +\startsubsection[title={\lpr {luaescapestring}}] \topicindex {escaping} @@ -466,7 +510,9 @@ in a separate file and load it using \LUA's \type {dofile}: \directlua { dofile('mysetups.lua') } \stoptyping -\subsection{\lpr {luafunction}, \lpr {luafunctioncall} and \lpr {luadef}} +\stopsubsection + +\startsubsection[title={\lpr {luafunction}, \lpr {luafunctioncall} and \lpr {luadef}}] The \prm {directlua} commands involves tokenization of its argument (after picking up an optional name or number specification). The tokenlist is then @@ -508,9 +554,14 @@ instance in an \prm {edef}. In addition \LUATEX\ provides a definer: \protected\global\luadef\MyFunctionC 3 \stoptyping +You should really use these commands with care. Some references get stored in +tokens and assume that the function is available when that token expands. On the +other hand, as we have tested this functionality in relative complex situations +normal usage should not give problems. +\stopsubsection -\subsection{\lpr {luabytecode} and \lpr {luabytecodecall}} +\startsubsection[title={\lpr {luabytecode} and \lpr {luabytecodecall}}] Analogue to the function callers discussed in the previous section we have byte code callers. Again the call variant is unexpandable. @@ -537,15 +588,13 @@ The variable \type {s} in the code is the number of the byte code register that can be used for diagnostic purposes. The advantage of bytecode registers over function calls is that they are stored in the format (but without upvalues). -\section {Alignments} +\stopsubsection -\subsection{\lpr {alignmark} and \lpr {aligntab}} +\stopsection -The primitive \lpr {alignmark} duplicates the functionality of \type {#} inside -alignment preambles, while \lpr {aligntab} duplicates the functionality of \type -{&}. +\startsection[title={Catcode tables}] -\section{Catcode tables} +\startsubsection[title={Catcodes}] \topicindex {catcodes} @@ -557,7 +606,9 @@ compared to traditional \TEX. The contents of each catcode table is independent from any other catcode table, and its contents is stored and retrieved from the format file. -\subsection{\lpr {catcodetable}} +\stopsubsection + +\startsubsection[title={\lpr {catcodetable}}] \startsyntax \catcodetable <15-bit number> @@ -567,7 +618,9 @@ The primitive \lpr {catcodetable} switches to a different catcode table. Such a table has to be previously created using one of the two primitives below, or it has to be zero. Table zero is initialized by \INITEX. -\subsection{\lpr {initcatcodetable}} +\stopsubsection + +\startsubsection[title={\lpr {initcatcodetable}}] \startsyntax \initcatcodetable <15-bit number> @@ -594,7 +647,9 @@ initial values are: \LL \stoptabulate -\subsection{\lpr {savecatcodetable}} +\stopsubsection + +\startsubsection[title={\lpr {savecatcodetable}}] \startsyntax \savecatcodetable <15-bit number> @@ -608,9 +663,13 @@ The new table is allocated globally: it will not go away after the current group has ended. If the supplied number is the currently active table, an error is raised. -\section{Suppressing errors} +\stopsubsection + +\stopsection + +\startsection[title={Suppressing errors}] -\subsection{\lpr {suppressfontnotfounderror}} +\startsubsection[title={\lpr {suppressfontnotfounderror}}] \topicindex {errors} @@ -623,7 +682,9 @@ assignment, making the requested csname for the font \prm {ifx} equal to \prm \suppressfontnotfounderror = 1 \stopsyntax -\subsection{\lpr {suppresslongerror}} +\stopsubsection + +\startsubsection[title={\lpr {suppresslongerror}}] \topicindex {errors} @@ -635,7 +696,9 @@ If this integer parameter is non|-|zero, then \LUATEX\ will not complain about \suppresslongerror = 1 \stopsyntax -\subsection{\lpr {suppressifcsnameerror}} +\stopsubsection + +\startsubsection[title={\lpr {suppressifcsnameerror}}] \topicindex {errors} @@ -650,7 +713,9 @@ indefinitely. \suppressifcsnameerror = 1 \stopsyntax -\subsection{\lpr {suppressoutererror}} +\stopsubsection + +\startsubsection[title={\lpr {suppressoutererror}}] \topicindex {errors} @@ -662,7 +727,9 @@ prohibited. \suppressoutererror = 1 \stopsyntax -\subsection{\lpr {suppressmathparerror}} +\stopsubsection + +\startsubsection[title={\lpr {suppressmathparerror}}] \topicindex {errors} \topicindex {math} @@ -681,7 +748,9 @@ $ x + 1 = a $ \stoptyping -\subsection{\lpr {suppressprimitiveerror}} +\stopsubsection + +\startsubsection[title={\lpr {suppressprimitiveerror}}] \topicindex {errors} \topicindex {primitives} @@ -694,19 +763,13 @@ When set to a non|-|zero value the following command will not issue an error: \primitive\notaprimitive \stopsyntax -\section {Math} - -\topicindex {math} +\stopsubsection -We will cover math extensions in its own chapter because not only the font -subsystem and spacing model have been enhanced (thereby introducing many new -primitives) but also because some more control has been added to existing -functionality. Much of this relates to the different approaches of traditional -\TEX\ fonts and \OPENTYPE\ math. +\stopsection -\section{Fonts} +\startsection[title={Fonts}] -\subsection{Font syntax} +\startsubsection[title={Font syntax}] \topicindex {fonts} @@ -719,7 +782,9 @@ functionality. Much of this relates to the different approaches of traditional This allows for embedded spaces, without the need for double quotes. Macro expansion takes place inside the argument. -\subsection{\lpr {fontid} and \lpr {setfontid}} +\stopsubsection + +\startsubsection[title={\lpr {fontid} and \lpr {setfontid}}] \startsyntax \fontid\font @@ -748,7 +813,9 @@ be bound to a real font, after all it's just a number. The primitive \lpr {setfontid} can be used to enable a font with the given id, which of course needs to be a valid one. -\subsection{\lpr {noligs} and \lpr {nokerns}} +\stopsubsection + +\startsubsection[title={\lpr {noligs} and \lpr {nokerns}}] \topicindex {ligatures+suppress} \topicindex {kerns+suppress} @@ -768,7 +835,9 @@ kerning functions, i.e.\ by assigning dummy functions to their associated callbacks. Keep in mind that when you define a font (using \LUA) you can also omit the kern and ligature tables, which has the same effect as the above. -\subsection{\type{\nospaces}} +\stopsubsection + +\startsubsection[title={\type{\nospaces}}] \topicindex {spaces+suppress} @@ -789,9 +858,13 @@ space. \stopcombination \stopplacefigure -\section{Tokens, commands and strings} +\stopsubsection -\subsection{\lpr {scantextokens}} +\stopsection + +\startsection[title={Tokens, commands and strings}] + +\startsubsection[title={\lpr {scantextokens}}] \topicindex {tokens+scanning} @@ -815,7 +888,9 @@ differences are: \stopitem \stopitemize -\subsection{\lpr {toksapp}, \lpr {tokspre}, \lpr {etoksapp} and \lpr {etokspre}} +\stopsubsection + +\startsubsection[title={\lpr {toksapp}, \lpr {tokspre}, \lpr {etoksapp} and \lpr {etokspre}}] Instead of: @@ -832,7 +907,9 @@ you can use: The \type {pre} variants prepend instead of append, and the \type {e} variants expand the passed general text. -\subsection{\prm {csstring}, \lpr {begincsname} and \lpr {lastnamedcs}} +\stopsubsection + +\startsubsection[title={\prm {csstring}, \lpr {begincsname} and \lpr {lastnamedcs}}] These are somewhat special. The \prm {csstring} primitive is like \prm {string} but it omits the leading escape character. This can be @@ -861,7 +938,9 @@ This is slightly more efficient than constructing the string twice (deep down in \LUATEX\ this also involves some \UTF8 juggling), but probably more relevant is that it saves a few tokens and can make code a bit more readable. -\subsection{\lpr {clearmarks}} +\stopsubsection + +\startsubsection[title={\lpr {clearmarks}}] \topicindex {marks} @@ -873,7 +952,17 @@ immediate command. \clearmarks <16-bit number> \stopsyntax -\subsection{\lpr {letcharcode}} +\stopsubsection + +\startsubsection[title={\lpr {alignmark} and \lpr {aligntab}}] + +The primitive \lpr {alignmark} duplicates the functionality of \type {#} inside +alignment preambles, while \lpr {aligntab} duplicates the functionality of \type +{&}. + +\stopsubsection + +\startsubsection[title={\lpr {letcharcode}}] This primitive can be used to assign a meaning to an active character, as in: @@ -884,7 +973,9 @@ This primitive can be used to assign a meaning to an active character, as in: This can be a bit nicer than using the uppercase tricks (using the property of \prm {uppercase} that it treats active characters special). -\subsection{\lpr {glet}} +\stopsubsection + +\startsubsection[title={\lpr {glet}}] This primitive is similar to: @@ -895,9 +986,142 @@ This primitive is similar to: but faster (only measurable with millions of calls) and probably more convenient (after all we also have \type {\gdef}). -\section{Boxes, rules and leaders} +\subsubsection{\lpr {expanded}, \lpr {immediateassignment} and \lpr {immediateassigned}} + +\topicindex {expansion} + +The \lpr {expanded} primitive takes a token list and expands it content which can +come in handy: it avoids a tricky mix of \prm {expandafter} and \prm {noexpand}. +You can compare it with what happens inside the body of an \prm {edef}. But this +kind of expansion it still doesn't expand some primitive operations. + +\startbuffer +\newcount\NumberOfCalls -\subsection{\lpr {outputbox}} +\def\TestMe{\advance\NumberOfCalls1 } + +\edef\Tested{\TestMe foo:\the\NumberOfCalls} +\edef\Tested{\TestMe foo:\the\NumberOfCalls} +\edef\Tested{\TestMe foo:\the\NumberOfCalls} + +\meaning\Tested +\stopbuffer + +\typebuffer + +The result is a macro that has the not expanded code in its body: + +\getbuffer + +Instead we can define \tex {TestMe} in a way that expands the assignment +immediately. You need of course to be aware of preventing look ahead interference +by using a space or \tex {relax} (often an expression works better as it doesn't +leave an \tex {relax}). + +\startbuffer +\def\TestMe{\immediateassignment\advance\NumberOfCalls1 } + +\edef\Tested{\TestMe foo:\the\NumberOfCalls} +\edef\Tested{\TestMe foo:\the\NumberOfCalls} +\edef\Tested{\TestMe foo:\the\NumberOfCalls} + +\meaning\Tested +\stopbuffer + +\typebuffer + +This time the counter gets updates and we don't see interference in the +resulting \tex {Tested} macro: + +\getbuffer + +Here is a somewhat silly example of expanded comparison: + +\startbuffer +\def\expandeddoifelse#1#2#3#4% + {\immediateassignment\edef\tempa{#1}% + \immediateassignment\edef\tempb{#2}% + \ifx\tempa\tempb + \immediateassignment\def\next{#3}% + \else + \immediateassignment\def\next{#4}% + \fi + \next} + +\edef\Tested + {(\expandeddoifelse{abc}{def}{yes}{nop}/% + \expandeddoifelse{abc}{abc}{yes}{nop})} + +\meaning\Tested +\stopbuffer + +\typebuffer + +It gives: + +\getbuffer + +A variant is: + +\starttyping +\def\expandeddoifelse#1#2#3#4% + {\immediateassigned{ + \edef\tempa{#1}% + \edef\tempb{#2}% + }% + \ifx\tempa\tempb + \immediateassignment\def\next{#3}% + \else + \immediateassignment\def\next{#4}% + \fi + \next} +\stoptyping + +The possible error messages are the same as using assignments in preambles of +alignments and after the \prm {accent} command. The supported assignments are the +so called prefixed commands (except box assignments). + +\subsubsection{\lpr {ifcondition}} + +\topicindex {conditions} + +This is a somewhat special one. When you write macros conditions need to be +properly balanced in order to let \TEX's fast branch skipping work well. This new +primitive is basically a no||op flagged as a condition so that the scanner can +recognize it as an if|-|test. However, when a real test takes place the work is +done by what follows, in the next example \tex {something}. + +\starttyping +\unexpanded\def\something#1#2% + {\edef\tempa{#1}% + \edef\tempb{#2} + \ifx\tempa\tempb} + +\ifcondition\something{a}{b}% + \ifcondition\something{a}{a}% + true 1 + \else + false 1 + \fi +\else + \ifcondition\something{a}{a}% + true 2 + \else + false 2 + \fi +\fi +\stoptyping + +If you are familiar with \METAPOST, this is a bit like \type {vardef} where the macro +has a return value. Here the return value is a test. + +\stopsubsection + +\stopsection + +\startsection[title={Boxes, rules and leaders}] + +\startsubsection[title={\lpr {outputbox}}] \topicindex {output} @@ -909,12 +1133,16 @@ the acceptable range is from 0 to 65535. \outputbox = 12345 \stopsyntax -\subsection{\prm {vpack}, \prm {hpack} and \prm {tpack}} +\stopsubsection + +\startsubsection[title={\prm {vpack}, \prm {hpack} and \prm {tpack}}] These three primitives are like \prm {vbox}, \prm {hbox} and \prm {vtop} but don't apply the related callbacks. -\subsection{\prm {vsplit}} +\stopsubsection + +\startsubsection[title={\prm {vsplit}}] \topicindex {splitting} @@ -922,7 +1150,9 @@ The \prm {vsplit} primitive has to be followed by a specification of the require height. As alternative for the \type {to} keyword you can use \type {upto} to get a split of the given size but result has the natural dimensions then. -\subsection[sec:imagedandforms]{Images and reused box objects} +\stopsubsection + +\startsubsection[title={Images and reused box objects},reference=sec:imagedandforms] These two concepts are now core concepts and no longer whatsits. They are in fact now implemented as rules with special properties. Normal rules have subtype~0, @@ -965,7 +1195,9 @@ is the \type {type} key. When set to non|-|zero the \type {/Type} entry is omitted. A value of 1 or 3 still writes a \type {/BBox}, while 2 or 3 will write a \type {/Matrix}. -\subsection{\lpr {nohrule} and \lpr {novrule}} +\stopsubsection + +\startsubsection[title={\lpr {nohrule} and \lpr {novrule}}] \topicindex {rules} @@ -974,7 +1206,9 @@ were introduced: \lpr {nohrule} and \lpr {novrule}. These can be used to reserve space. This is often more efficient than creating an empty box with fake dimensions. -\subsection{\lpr {gleaders}} +\stopsubsection + +\startsubsection[title={\lpr {gleaders}}] \topicindex {leaders} @@ -983,9 +1217,13 @@ they are like normal \prm {leaders} in that they align nicely, except that the alignment is based on the {\it largest\/} enclosing box instead of the {\it smallest\/}. The \type {g} stresses this global nature. -\section {Languages} +\stopsubsection + +\stopsection + +\startsection[title={Languages}] -\subsection{\lpr {hyphenationmin}} +\startsubsection[title={\lpr {hyphenationmin}}] \topicindex {languages} \topicindex {hyphenation} @@ -996,7 +1234,9 @@ within the constraints of the \prm {lefthyphenmin} and \prm {righthyphenmin} values (as stored in the glyph node). This primitive accepts a number and stores the value with the language. -\subsection{\prm {boundary}, \prm {noboundary}, \prm {protrusionboundary} and \prm {wordboundary}} +\stopsubsection + +\startsubsection[title={\prm {boundary}, \prm {noboundary}, \prm {protrusionboundary} and \prm {wordboundary}}] The \prm {noboundary} command is used to inject a whatsit node but now injects a normal node with type \nod {boundary} and subtype~0. In addition you can say: @@ -1012,16 +1252,22 @@ passing this value is a side effect of the generalization. The subtypes~2 and~3 are used to control protrusion and word boundaries in hyphenation and have related primitives. -\section{Control and debugging} +\stopsubsection + +\stopsection + +\startsection[title={Control and debugging}] -\subsection {Tracing} +\startsubsection[title={Tracing}] \topicindex {tracing} If \prm {tracingonline} is larger than~2, the node list display will also print the node number of the nodes. -\subsection{\lpr {outputmode}} +\stopsubsection + +\startsubsection[title={\lpr {outputmode}}] \topicindex {output} \topicindex {backend} @@ -1036,15 +1282,22 @@ The \lpr {outputmode} variable tells \LUATEX\ what it has to produce: \LL \stoptabulate -\subsection{\lpr {draftmode}} +\stopsubsection + +\startsubsection[title={\lpr {draftmode}}] -The value of the \lpr {draftmode} counter signals the backend if it should -output less. The \PDF\ backend accepts a value of~1, while the \DVI\ backend -ignores the value. +The value of the \lpr {draftmode} counter signals the backend if it should output +less. The \PDF\ backend accepts a value of~1, while the \DVI\ backend ignores the +value. This is no critical feature so we can remove it in future versions when it +can make the backend cleaner. -\section {Files} +\stopsubsection -\subsection{File syntax} +\stopsection + +\startsection[title={Files}] + +\startsubsection[title={File syntax}] \topicindex {files+names} @@ -1075,7 +1328,9 @@ extension is that a csname not always makes sense. The zero case is the default. \LL \stoptabulate -\subsection{Writing to file} +\stopsubsection + +\startsubsection[title={Writing to file}] \topicindex {files+writing} @@ -1083,134 +1338,19 @@ You can now open upto 127 files with \prm {openout}. When no file is open writes will go to the console and log. As a consequence a system command is no longer possible but one can use \type {os.execute} to do the same. -\subsection{\lpr {expanded}, \lpr {immediateassignment}, \lpr {immediateassigned}} - -\topicindex {expansion} - -The \lpr {expanded} primitive takes a token list and expands it content which can -come in handy: it avoids a tricky mix of \prm {expandafter} and \prm {noexpand}. -You can compare it with what happens inside the body of an \prm {edef}. But this -kind of expansion it still doesn't expand some primitive operations. - -\startbuffer -\newcount\NumberOfCalls - -\def\TestMe{\advance\NumberOfCalls1 } - -\edef\Tested{\TestMe foo:\the\NumberOfCalls} -\edef\Tested{\TestMe foo:\the\NumberOfCalls} -\edef\Tested{\TestMe foo:\the\NumberOfCalls} - -\meaning\Tested -\stopbuffer - -\typebuffer - -The result is a macro that has the not expanded code in its body: - -\getbuffer - -Instead we can define \tex {TestMe} in a way that expands the assignment -immediately. You need of course to be aware of preventing look ahead interference -by using a space or \tex {relax} (often an expression works better as it doesn't -leave an \tex {relax}). - -\startbuffer -\def\TestMe{\immediateassignment\advance\NumberOfCalls1 } - -\edef\Tested{\TestMe foo:\the\NumberOfCalls} -\edef\Tested{\TestMe foo:\the\NumberOfCalls} -\edef\Tested{\TestMe foo:\the\NumberOfCalls} - -\meaning\Tested -\stopbuffer - -\typebuffer - -This time the counter gets updates and we don't see interference in the -resulting \tex {Tested} macro: +\stopsubsection -\getbuffer - -Here is a somewhat silly example of expanded comparison: - -\startbuffer -\def\expandeddoifelse#1#2#3#4% - {\immediateassignment\edef\tempa{#1}% - \immediateassignment\edef\tempb{#2}% - \ifx\tempa\tempb - \immediateassignment\def\next{#3}% - \else - \immediateassignment\def\next{#4}% - \fi - \next} - -\edef\Tested - {(\expandeddoifelse{abc}{def}{yes}{nop}/% - \expandeddoifelse{abc}{abc}{yes}{nop})} - -\meaning\Tested -\stopbuffer - -\typebuffer - -It gives: - -\getbuffer - -A variant is: - -\starttyping -\def\expandeddoifelse#1#2#3#4% - {\immediateassigned{ - \edef\tempa{#1}% - \edef\tempb{#2}% - }% - \ifx\tempa\tempb - \immediateassignment\def\next{#3}% - \else - \immediateassignment\def\next{#4}% - \fi - \next} -\stoptyping - -The possible error messages are the same as using assignments in preambles of -alignments and after the \prm {accent} command. The supported assignments are the -so called prefixed commands (except box assignments). - -\subsection{\lpr {ifcondition}} - -\topicindex {conditions} - -This is a somewhat special one. When you write macros conditions need to be -properly balanced in order to let \TEX's fast branch skipping work well. This new -primitive is basically a no||op flagged as a condition so that the scanner can -recognize it as an if|-|test. However, when a real test takes place the work is -done by what follows, in the next example \tex {something}. +\stopsection -\starttyping -\unexpanded\def\something#1#2% - {\edef\tempa{#1}% - \edef\tempb{#2} - \ifx\tempa\tempb} +\startsection[title={Math}] -\ifcondition\something{a}{b}% - \ifcondition\something{a}{a}% - true 1 - \else - false 1 - \fi -\else - \ifcondition\something{a}{a}% - true 2 - \else - false 2 - \fi -\fi -\stoptyping +\topicindex {math} -If you are familiar with \METAPOST, this is a bit like \type {vardef} where the macro -has a return value. Here the return value is a test. +We will cover math extensions in its own chapter because not only the font +subsystem and spacing model have been enhanced (thereby introducing many new +primitives) but also because some more control has been added to existing +functionality. Much of this relates to the different approaches of traditional +\TEX\ fonts and \OPENTYPE\ math. \stopsection diff --git a/doc/context/sources/general/manuals/luatex/luatex-introduction.tex b/doc/context/sources/general/manuals/luatex/luatex-introduction.tex index b931cfcf6..1f997e250 100644 --- a/doc/context/sources/general/manuals/luatex/luatex-introduction.tex +++ b/doc/context/sources/general/manuals/luatex/luatex-introduction.tex @@ -47,7 +47,7 @@ The organization of the source code is adapted so that it can glue all these components together. We continue cleaning up side effects of the accumulated code in \TEX\ engines (especially code that is not needed any longer). -\startitemize % [packed] +\startitemize [unpacked] \startitem We started out with most of \PDFTEX\ version 1.40.9. The code base was converted to \CCODE\ and split in modules. Experimental features were @@ -108,30 +108,44 @@ code in \TEX\ engines (especially code that is not needed any longer). means that a complete \TEX\ workflow can be built without the need for additional programs. \stopitem + \startitem + The versions starting from 1.09 no longer use the poppler library for + inclusion but a lightweight dedicated one. This removes a dependency but + also makes the inclusion code of \LUATEX\ different from \PDFTEX. In fact + it was already much different due to the \LUA\ image interfacing. + \stopitem \stopitemize We try to keep upcoming versions compatible but intermediate releases can contain experimental features. A general rule is that versions that end up on \TEXLIVE\ -and|/|or are released around \CONTEXT\ meetings are stable. Future versions will -probably become a bit leaner and meaner. Some libraries might become external as -we don't want to bloat the binary and also don't want to add more hard coded -solutions. After all, with \LUA\ you can extend the core functionality. The less -dependencies, the better. +and|/|or are released around \CONTEXT\ meetings are stable. Any version between +the yearly \TEXLIVE\ releases are to be considered beta and in the repository end +up as trunk releases. We have an experimental branch that we use for development +but there is no support for any of its experimental features. Intermediate +releases (from trunk) are normally available via the \CONTEXT\ distribution +channels (the garden and so called minimals). + +Future versions will probably become a bit leaner and meaner. Some libraries +might become external as we don't want to bloat the binary and also don't want to +add more hard coded solutions. After all, with \LUA\ you can extend the core +functionality. The less dependencies, the better. You might find \LUA\ helpers that are not yet documented. These are considered experimental, although when you encounter them in a \CONTEXT\ version that has been around for a while you can assume that they will stay. Of course it can just be that we forgot to document them yet. -The \TEXLIVE\ version is to be considered the current stable version. Any version -between the yearly \TEXLIVE\ releases are to be considered beta and in the -repository end up as trunk releases. We have an experimental branch that we use -for development but there is no support for any of its experimental features. -Intermediate releases (from trunk) are normally available via the \CONTEXT\ -distribution channels (the garden and so called minimals). +A manual like this is not really meant as tutorial, for that we refer to +documents that ship with \CONTEXT, articles, etc. It is also never complete +enough for all readers. We try to keep up but the reader needs to realize that +it's all volunteer work done in spare time. And for sure, complaining about a bad +manual or crappy documentation will not really motivate us to spend more time on +it. That being said, we hope that this document is useful. \blank[big] +\testpage[5] + \startlines Hans Hagen Harmut Henkel diff --git a/doc/context/sources/general/manuals/luatex/luatex-languages.tex b/doc/context/sources/general/manuals/luatex/luatex-languages.tex index 10ccc335f..6ec75e375 100644 --- a/doc/context/sources/general/manuals/luatex/luatex-languages.tex +++ b/doc/context/sources/general/manuals/luatex/luatex-languages.tex @@ -6,6 +6,8 @@ \startchapter[reference=languages,title={Languages, characters, fonts and glyphs}] +\section {Introduction} + \topicindex {languages} \LUATEX's internal handling of the characters and glyphs that eventually become @@ -49,7 +51,7 @@ font information in the whole list (creating ligatures and adjusting kerning), and finally it adjusts all the subtype identifiers so that the records are \quote {glyph nodes} from now on. -\section[charsandglyphs]{Characters and glyphs} +\section[charsandglyphs]{Characters, glyphs and discretionaries} \topicindex {characters} \topicindex {glyphs} @@ -274,6 +276,7 @@ min values to 1 and make sure that the words hyphenate at each character. {\SomeTest{3}{one}} {\type{3}} \stopcombination \stopplacefigure + \startplacefigure[reference=hb:2,title={\type{one\null two}}] \startcombination[4*1] {\SomeTest{0}{one\null two}} {\type{0}} @@ -282,6 +285,7 @@ min values to 1 and make sure that the words hyphenate at each character. {\SomeTest{3}{one\null two}} {\type{3}} \stopcombination \stopplacefigure + \startplacefigure[reference=hb:3,title={\type{\null one\null two}}] \startcombination[4*1] {\SomeTest{0}{\null one\null two}} {\type{0}} @@ -290,6 +294,7 @@ min values to 1 and make sure that the words hyphenate at each character. {\SomeTest{3}{\null one\null two}} {\type{3}} \stopcombination \stopplacefigure + \startplacefigure[reference=hb:4,title={\type{one\null two\null}}] \startcombination[4*1] {\SomeTest{0}{one\null two\null}} {\type{0}} @@ -298,6 +303,7 @@ min values to 1 and make sure that the words hyphenate at each character. {\SomeTest{3}{one\null two\null}} {\type{3}} \stopcombination \stopplacefigure + \startplacefigure[reference=hb:5,title={\type{\null one\null two\null}}] \startcombination[4*1] {\SomeTest{0}{\null one\null two\null}} {\type{0}} @@ -344,18 +350,6 @@ before--after \par before---after \par \stopbuffer -In \in {figure} [automatichyphenmode:1] \in {and} [automatichyphenmode:2] we show -what happens with three samples: - -Input A: \typebuffer[a] -Input B: \typebuffer[b] -Input C: \typebuffer[c] - -As with primitive companions of other single character commands, the \prm {-} -command has a more verbose primitive version in \lpr {explicitdiscretionary} -and the normally intercepted in the hyphenator character \type {-} (or whatever -is configured) is available as \lpr {automaticdiscretionary}. - \startbuffer[demo] \startcombination[nx=4,ny=3,location=top] {\framed[align=normal,strut=no,top=\vskip.5ex,bottom=\vskip.5ex]{\automatichyphenmode\zerocount \hsize6em \getbuffer[a]}} {A~0~6em} @@ -373,7 +367,7 @@ is configured) is available as \lpr {automaticdiscretionary}. \stopcombination \stopbuffer -\startplacefigure[reference=automatichyphenmode:1,title={The automatic modes \type {0} (default), \type {1} and \type {2}, with a \prm {hsize} +\startplacefigure[locationreference=automatichyphenmode:1,title={The automatic modes \type {0} (default), \type {1} and \type {2}, with a \prm {hsize} of 6em and 2pt (which triggers a linebreak).}] \dontcomplain \tt \getbuffer[demo] \stopplacefigure @@ -384,6 +378,18 @@ of 6em and 2pt (which triggers a linebreak).}] \dontcomplain \tt \getbuffer[demo] \stopplacefigure +In \in {figure} [automatichyphenmode:1] \in {and} [automatichyphenmode:2] we show +what happens with three samples: + +Input A: \typebuffer[a] +Input B: \typebuffer[b] +Input C: \typebuffer[c] + +As with primitive companions of other single character commands, the \prm {-} +command has a more verbose primitive version in \lpr {explicitdiscretionary} +and the normally intercepted in the hyphenator character \type {-} (or whatever +is configured) is available as \lpr {automaticdiscretionary}. + \section{The main control loop} \topicindex {main loop} @@ -911,10 +917,12 @@ ligatures are used. Of course kerning also complicates matters here. \section{The \type {lang} library} +\subsection {\type {lang.new} and \type {lang.id}} + \topicindex {languages+library} -This library provides the interface to \LUATEX's structure -representing a language, and the associated functions. +This library provides the interface to \LUATEX's structure representing a +language, and the associated functions. \startfunctioncall <language> l = lang.new() @@ -934,11 +942,17 @@ the internal language with that id number. The number returned is the internal \prm {language} id number this object refers to. +\subsection {\type {lang.hyphenation}} + +You can hyphenate a string directly with: + \startfunctioncall <string> n = lang.hyphenation(<language> l) lang.hyphenation(<language> l, <string> n) \stopfunctioncall +\subsection {\type {lang.clear_hyphenation} and \type {lang.clean}} + This either returns the current hyphenation exceptions for this language, or adds new ones. The syntax of the string is explained in~\in {section} [patternsexceptions]. @@ -959,6 +973,8 @@ syntax of the argument string is explained in \in {section} [patternsexceptions] This function is useful if you want to do something else based on the words in a dictionary file, like spell|-|checking. +\subsection {\type {lang.patterns} and \type {lang.clear_patterns}} + \startfunctioncall <string> n = lang.patterns(<language> l) lang.patterns(<language> l, <string> n) @@ -974,6 +990,8 @@ lang.clear_patterns(<language> l) This can be used to clear the pattern dictionary for a language. +\subsection {\type {lang.[pre|post]hyphenchar}} + \startfunctioncall <number> n = lang.prehyphenchar(<language> l) lang.prehyphenchar(<language> l, <number> n) @@ -998,21 +1016,25 @@ These gets or set the \quote {pre|-|break} and \quote {post|-|break} hyphen characters for explicit hyphenation in this language. Both are initially decimal~0 (indicating emptiness). -\startfunctioncall -<boolean> success = lang.hyphenate(<node> head) -<boolean> success = lang.hyphenate(<node> head, <node> tail) -\stopfunctioncall +\subsection {\type {lang.hyphenate}} -This call inserts hyphenation points (discretionary nodes) in a node list. If +The next call inserts hyphenation points (discretionary nodes) in a node list. If \type {tail} is given as argument, processing stops on that node. Currently, \type {success} is always true if \type {head} (and \type {tail}, if specified) are proper nodes, regardless of possible other errors. +\startfunctioncall +<boolean> success = lang.hyphenate(<node> head) +<boolean> success = lang.hyphenate(<node> head, <node> tail) +\stopfunctioncall + Hyphenation works only on \quote {characters}, a special subtype of all the glyph nodes with the node subtype having the value \type {1}. Glyph modes with different subtypes are not processed. See \in {section} [charsandglyphs] for more details. +\subsection {\type {lang.[set|get]hjcode}} + The following two commands can be used to set or query hj codes: \startfunctioncall diff --git a/doc/context/sources/general/manuals/luatex/luatex-lua.tex b/doc/context/sources/general/manuals/luatex/luatex-lua.tex index 165bdb614..f4d0c770c 100644 --- a/doc/context/sources/general/manuals/luatex/luatex-lua.tex +++ b/doc/context/sources/general/manuals/luatex/luatex-lua.tex @@ -4,11 +4,11 @@ \startcomponent luatex-lua -\startchapter[reference=lua,title={\LUA\ general}] +\startchapter[reference=lua,title={Using \LUATEX}] -\section[init]{Initialization} +\startsection[title={Initialization},reference=init] -\subsection{\LUATEX\ as a \LUA\ interpreter} +\startsubsection[title={\LUATEX\ as a \LUA\ interpreter}] \topicindex {initialization} \topicindex {\LUA+interpreter} @@ -37,7 +37,9 @@ positive values, just like the \LUA\ interpreter. in effect, a somewhat bulky stand alone \LUA\ interpreter with a bunch of extra preloaded libraries. -\subsection{\LUATEX\ as a \LUA\ byte compiler} +\stopsubsection + +\startsubsection[title={\LUATEX\ as a \LUA\ byte compiler}] \topicindex {\LUA+byte code} @@ -54,7 +56,9 @@ accepts (but ignores) the \type {--luaconly} switch. The current version of \LUA can dump bytecode using \type {string.dump} so we might decide to drop this version of \LUATEX. -\subsection{Other commandline processing} +\stopsubsection + +\startsubsection[title={Other commandline processing}] \topicindex {command line} @@ -240,17 +244,34 @@ finished: in order to initialize the built|-|in \KPATHSEA\ library properly, check \type {--progname}, or \type {--ini} and \type {--fmt}, if \type {--progname} is missing. -\section{\LUA\ behaviour} +\stopsubsection + +\stopsection + +\startsection{\LUA\ behaviour} + +\startsubsection[title={The \LUA\ version}] \topicindex {\LUA+libraries} \topicindex {\LUA+extensions} +We currently use \LUA\ 5.3 and will follow developments of the language but +normally with some delay. Therefore the user needs to keep an eye on (subtle) +differences in successive versions of the language. Also, \LUAJITTEX\ lags behind +in the sense that \LUAJIT\ is not in sync with regular \LUA\ development. Here is +an example of one aspect. + \LUA s \type {tostring} function (and \type {string.format} may return values in scientific notation, thereby confusing the \TEX\ end of things when it is used as the right|-|hand side of an assignment to a \prm {dimen} or \prm {count}. The output of these serializers also depend on the \LUA\ version, so in \LUA\ 5.3 you can get different output than from 5.2. +\stopsubsection + +\startsubsection[title={Integration in the \TDS\ ecosystem}] + +The main \TEX\ distributions follow the \TEX\ directory structure (\TDS). \LUATEX\ is able to use the kpathsea library to find \type {require()}d modules. For this purpose, \type {package.searchers[2]} is replaced by a different loader function, that decides at runtime whether to use kpathsea or the built|-|in core @@ -261,6 +282,10 @@ Initialization of \KPATHSEA\ can happen either implicitly (when \LUATEX\ starts up and the startup script has not set \type {texconfig.kpse_init} to false), or explicitly by calling the \LUA\ function \type {kpse.set_program_name()}. +\stopsubsection + +\startsubsection[title={Loading libraries}] + \LUATEX\ is able to use dynamically loadable \LUA\ libraries, unless \type {--safer} was given as an option on the command line. For this purpose, \type {package.searchers[3]} is replaced by a different loader function, that @@ -290,6 +315,10 @@ at the same time (which will typically happen on \type {win32}, because there is one \LUA\ 5.3 inside \LUATEX, and another will likely be linked to the \DLL\ file of the module itself). +\stopsubsection + +\startsubsection[title={Executing programs}] + In keeping with the other \TEX|-|like programs in \TEXLIVE, the two \LUA\ functions \type {os.execute} and \type {io.popen}, as well as the two new functions \type {os.exec} and \type {os.spawn} that are explained below, take the value of \type @@ -314,6 +343,10 @@ name. However, the \type library evolved so we have dropped these in favour of pure \LUA\ variants. The \type {shortname} helper is obsolete and now just returns the name. +\stopsubsection + +\startsubsection[title={Multibyte \type {string} functions}] + The \type {string} library has a few extra functions like \type {string.explode(s[,m])}. This function returns an array containing the string argument \type {s} split into sub-strings based on the value of the string @@ -392,7 +425,9 @@ These three functions are relative fast and don't do much checking. They can be as building blocks for other helpers. So, eventually we can decide to drop the \type {sln} library, just that you know. -\blank +\stopsubsection + +\startsubsection[title={Extra \type {os} library functions}] The \type {os} library has a few extra functions and variables: @@ -524,6 +559,10 @@ The \type {os} library has a few extra functions and variables: \stopitemize +\stopsubsection + +\startsubsection[title={Locales}] + In stock \LUA, many things depend on the current locale. In \LUATEX, we can't do that, because it makes documents unportable. While \LUATEX\ is running if forces the following locale settings: @@ -534,7 +573,11 @@ LC_COLLATE=C LC_NUMERIC=C \stoptyping -\section {\LUA\ modules} +\stopsubsection + +\stopsection + +\startsection[title={\LUA\ modules}] \topicindex {\LUA+libraries} \topicindex {\LUA+modules} @@ -597,7 +640,9 @@ Some modules that are normally external to \LUA\ are statically linked in with \stopitemize -\section{Testing} +\stopsection + +\startsection[title={Testing}] \topicindex {testing} \topicindex {\PDF+date} @@ -633,6 +678,8 @@ There is some control possible, for instance prevent filename to be written to the \PDF\ file. This is discussed elsewhere. In \CONTEXT\ we provide the command line argument \type {--nodates} that does a bit more disabling of dates. +\stopsection + \stopchapter \stopcomponent diff --git a/doc/context/sources/general/manuals/luatex/luatex-math.tex b/doc/context/sources/general/manuals/luatex/luatex-math.tex index 821ef010d..ad3ce2db3 100644 --- a/doc/context/sources/general/manuals/luatex/luatex-math.tex +++ b/doc/context/sources/general/manuals/luatex/luatex-math.tex @@ -6,6 +6,8 @@ \startchapter[reference=math,title={Math}] +\section {Traditional alongside \OPENTYPE} + \topicindex {math} The handling of mathematics in \LUATEX\ differs quite a bit from how \TEX82 (and @@ -17,6 +19,115 @@ make it easier to use \OPENTYPE\ math fonts. And finally, there are some extensions that have been proposed or considered in the past that are now added to the engine. +\section{Unicode math characters} + +\topicindex {math+\UNICODE} +\topicindex {\UNICODE+math} + +Character handling is now extended up to the full \UNICODE\ range (the \type {\U} +prefix), which is compatible with \XETEX. + +The math primitives from \TEX\ are kept as they are, except for the ones that +convert from input to math commands: \type {mathcode}, and \type {delcode}. These +two now allow for a 21-bit character argument on the left hand side of the equals +sign. + +Some of the new \LUATEX\ primitives read more than one separate value. This is +shown in the tables below by a plus sign. + +The input for such primitives would look like this: + +\starttyping +\def\overbrace{\Umathaccent 0 1 "23DE } +\stoptyping + +The altered \TEX82 primitives are: + +\starttabulate[|l|l|r|c|l|r|] +\DB primitive \BC min \BC max \BC \kern 2em \BC min \BC max \NC \NR +\TB +\NC \prm {mathcode} \NC 0 \NC 10FFFF \NC = \NC 0 \NC 8000 \NC \NR +\NC \prm {delcode} \NC 0 \NC 10FFFF \NC = \NC 0 \NC FFFFFF \NC \NR +\LL +\stoptabulate + +The unaltered ones are: + +\starttabulate[|l|l|r|] +\DB primitive \BC min \BC max \NC \NR +\TB +\NC \prm {mathchardef} \NC 0 \NC 8000 \NC \NR +\NC \prm {mathchar} \NC 0 \NC 7FFF \NC \NR +\NC \prm {mathaccent} \NC 0 \NC 7FFF \NC \NR +\NC \prm {delimiter} \NC 0 \NC 7FFFFFF \NC \NR +\NC \prm {radical} \NC 0 \NC 7FFFFFF \NC \NR +\LL +\stoptabulate + +For practical reasons \prm {mathchardef} will silently accept values larger +that \type {0x8000} and interpret it as \lpr {Umathcharnumdef}. This is needed +to satisfy older macro packages. + +The following new primitives are compatible with \XETEX: + +% somewhat fuzzy: + +\starttabulate[|l|l|r|c|l|r|] +\DB primitive \BC min \BC max \BC \kern 2em \BC min \BC max \NC \NR +\TB +\NC \lpr {Umathchardef} \NC 0+0+0 \NC 7+FF+10FFFF \NC \NC \NC \NC \NR +\NC \lpr {Umathcharnumdef}\rlap{\high{5}} \NC -80000000 \NC 7FFFFFFF \NC \NC \NC \NC \NR +\NC \lpr {Umathcode} \NC 0 \NC 10FFFF \NC = \NC 0+0+0 \NC 7+FF+10FFFF \NC \NR +\NC \lpr {Udelcode} \NC 0 \NC 10FFFF \NC = \NC 0+0 \NC FF+10FFFF \NC \NR +\NC \lpr {Umathchar} \NC 0+0+0 \NC 7+FF+10FFFF \NC \NC \NC \NC \NR +\NC \lpr {Umathaccent} \NC 0+0+0 \NC 7+FF+10FFFF \NC \NC \NC \NC \NR +\NC \lpr {Udelimiter} \NC 0+0+0 \NC 7+FF+10FFFF \NC \NC \NC \NC \NR +\NC \lpr {Uradical} \NC 0+0 \NC FF+10FFFF \NC \NC \NC \NC \NR +\NC \lpr {Umathcharnum} \NC -80000000 \NC 7FFFFFFF \NC \NC \NC \NC \NR +\NC \lpr {Umathcodenum} \NC 0 \NC 10FFFF \NC = \NC -80000000 \NC 7FFFFFFF \NC \NR +\NC \lpr {Udelcodenum} \NC 0 \NC 10FFFF \NC = \NC -80000000 \NC 7FFFFFFF \NC \NR +\LL +\stoptabulate + +Specifications typically look like: + +\starttyping +\Umathchardef\xx="1"0"456 +\Umathcode 123="1"0"789 +\stoptyping + +The new primitives that deal with delimiter|-|style objects do not set up a +\quote {large family}. Selecting a suitable size for display purposes is expected +to be dealt with by the font via the \lpr {Umathoperatorsize} parameter. + +For some of these primitives, all information is packed into a single signed +integer. For the first two (\lpr {Umathcharnum} and \lpr {Umathcodenum}), the +lowest 21 bits are the character code, the 3 bits above that represent the math +class, and the family data is kept in the topmost bits. This means that the values +for math families 128--255 are actually negative. For \lpr {Udelcodenum} there +is no math class. The math family information is stored in the bits directly on +top of the character code. Using these three commands is not as natural as using +the two- and three|-|value commands, so unless you know exactly what you are +doing and absolutely require the speedup resulting from the faster input +scanning, it is better to use the verbose commands instead. + +The \lpr {Umathaccent} command accepts optional keywords to control various +details regarding math accents. See \in {section} [mathacc] below for details. + +There are more new primitives and all of these will be explained in following +sections: + +\starttabulate[|l|l|] +\DB primitive \BC value range (in hex) \NC \NR +\TB +\NC \lpr {Uroot} \NC 0 + 0--FF + 10FFFF \NC \NR +\NC \lpr {Uoverdelimiter} \NC 0 + 0--FF + 10FFFF \NC \NR +\NC \lpr {Uunderdelimiter} \NC 0 + 0--FF + 10FFFF \NC \NR +\NC \lpr {Udelimiterover} \NC 0 + 0--FF + 10FFFF \NC \NR +\NC \lpr {Udelimiterunder} \NC 0 + 0--FF + 10FFFF \NC \NR +\LL +\stoptabulate + \section{Math styles} \subsection{\lpr {mathstyle}} @@ -150,116 +261,7 @@ $\Ustack {a \over b}$ The \lpr {Ustack} command will scan the next brace and start a new math group with the correct (numerator) math style. -\section{Unicode math characters} - -\topicindex {math+\UNICODE} -\topicindex {\UNICODE+math} - -Character handling is now extended up to the full \UNICODE\ range (the \type {\U} -prefix), which is compatible with \XETEX. - -The math primitives from \TEX\ are kept as they are, except for the ones that -convert from input to math commands: \type {mathcode}, and \type {delcode}. These -two now allow for a 21-bit character argument on the left hand side of the equals -sign. - -Some of the new \LUATEX\ primitives read more than one separate value. This is -shown in the tables below by a plus sign. - -The input for such primitives would look like this: - -\starttyping -\def\overbrace{\Umathaccent 0 1 "23DE } -\stoptyping - -The altered \TEX82 primitives are: - -\starttabulate[|l|l|r|c|l|r|] -\DB primitive \BC min \BC max \BC \kern 2em \BC min \BC max \NC \NR -\TB -\NC \prm {mathcode} \NC 0 \NC 10FFFF \NC = \NC 0 \NC 8000 \NC \NR -\NC \prm {delcode} \NC 0 \NC 10FFFF \NC = \NC 0 \NC FFFFFF \NC \NR -\LL -\stoptabulate - -The unaltered ones are: - -\starttabulate[|l|l|r|] -\DB primitive \BC min \BC max \NC \NR -\TB -\NC \prm {mathchardef} \NC 0 \NC 8000 \NC \NR -\NC \prm {mathchar} \NC 0 \NC 7FFF \NC \NR -\NC \prm {mathaccent} \NC 0 \NC 7FFF \NC \NR -\NC \prm {delimiter} \NC 0 \NC 7FFFFFF \NC \NR -\NC \prm {radical} \NC 0 \NC 7FFFFFF \NC \NR -\LL -\stoptabulate - -For practical reasons \prm {mathchardef} will silently accept values larger -that \type {0x8000} and interpret it as \lpr {Umathcharnumdef}. This is needed -to satisfy older macro packages. - -The following new primitives are compatible with \XETEX: - -% somewhat fuzzy: - -\starttabulate[|l|l|r|c|l|r|] -\DB primitive \BC min \BC max \BC \kern 2em \BC min \BC max \NC \NR -\TB -\NC \lpr {Umathchardef} \NC 0+0+0 \NC 7+FF+10FFFF \NC \NC \NC \NC \NR -\NC \lpr {Umathcharnumdef}\rlap{\high{5}} \NC -80000000 \NC 7FFFFFFF \NC \NC \NC \NC \NR -\NC \lpr {Umathcode} \NC 0 \NC 10FFFF \NC = \NC 0+0+0 \NC 7+FF+10FFFF \NC \NR -\NC \lpr {Udelcode} \NC 0 \NC 10FFFF \NC = \NC 0+0 \NC FF+10FFFF \NC \NR -\NC \lpr {Umathchar} \NC 0+0+0 \NC 7+FF+10FFFF \NC \NC \NC \NC \NR -\NC \lpr {Umathaccent} \NC 0+0+0 \NC 7+FF+10FFFF \NC \NC \NC \NC \NR -\NC \lpr {Udelimiter} \NC 0+0+0 \NC 7+FF+10FFFF \NC \NC \NC \NC \NR -\NC \lpr {Uradical} \NC 0+0 \NC FF+10FFFF \NC \NC \NC \NC \NR -\NC \lpr {Umathcharnum} \NC -80000000 \NC 7FFFFFFF \NC \NC \NC \NC \NR -\NC \lpr {Umathcodenum} \NC 0 \NC 10FFFF \NC = \NC -80000000 \NC 7FFFFFFF \NC \NR -\NC \lpr {Udelcodenum} \NC 0 \NC 10FFFF \NC = \NC -80000000 \NC 7FFFFFFF \NC \NR -\LL -\stoptabulate - -Specifications typically look like: - -\starttyping -\Umathchardef\xx="1"0"456 -\Umathcode 123="1"0"789 -\stoptyping - -The new primitives that deal with delimiter|-|style objects do not set up a -\quote {large family}. Selecting a suitable size for display purposes is expected -to be dealt with by the font via the \lpr {Umathoperatorsize} parameter. - -For some of these primitives, all information is packed into a single signed -integer. For the first two (\lpr {Umathcharnum} and \lpr {Umathcodenum}), the -lowest 21 bits are the character code, the 3 bits above that represent the math -class, and the family data is kept in the topmost bits. This means that the values -for math families 128--255 are actually negative. For \lpr {Udelcodenum} there -is no math class. The math family information is stored in the bits directly on -top of the character code. Using these three commands is not as natural as using -the two- and three|-|value commands, so unless you know exactly what you are -doing and absolutely require the speedup resulting from the faster input -scanning, it is better to use the verbose commands instead. - -The \lpr {Umathaccent} command accepts optional keywords to control various -details regarding math accents. See \in {section} [mathacc] below for details. - -There are more new primitives and all of these will be explained in following -sections: - -\starttabulate[|l|l|] -\DB primitive \BC value range (in hex) \NC \NR -\TB -\NC \lpr {Uroot} \NC 0 + 0--FF + 10FFFF \NC \NR -\NC \lpr {Uoverdelimiter} \NC 0 + 0--FF + 10FFFF \NC \NR -\NC \lpr {Uunderdelimiter} \NC 0 + 0--FF + 10FFFF \NC \NR -\NC \lpr {Udelimiterover} \NC 0 + 0--FF + 10FFFF \NC \NR -\NC \lpr {Udelimiterunder} \NC 0 + 0--FF + 10FFFF \NC \NR -\LL -\stoptabulate - -\section{Cramped math styles} +\subsection{Cramped math styles} \topicindex {math+styles} \topicindex {math+spacing} @@ -350,6 +352,8 @@ Now we get: \section{Math parameter settings} +\subsection {Many new \lpr {Umath*} primitives} + \topicindex {math+parameters} In \LUATEX, the font dimension parameters that \TEX\ used in math typesetting are @@ -426,27 +430,7 @@ Each of the parameters in this section can be set by a command like this: they obey grouping, and you can use \type {\the\Umathquad\displaystyle} if needed. -\section{Skips around display math} - -\topicindex {math+spacing} - -The injection of \prm {abovedisplayskip} and \prm {belowdisplayskip} is not -symmetrical. An above one is always inserted, also when zero, but the below is -only inserted when larger than zero. Especially the latter makes it sometimes hard -to fully control spacing. Therefore \LUATEX\ comes with a new directive: \lpr -{mathdisplayskipmode}. The following values apply: - -\starttabulate[|c|l|] -\DB value \BC meaning \NC \NR -\TB -\NC 0 \NC normal \TEX\ behaviour \NC \NR -\NC 1 \NC always (same as 0) \NC \NR -\NC 2 \NC only when not zero \NC \NR -\NC 3 \NC never, not even when not zero \NC \NR -\LL -\stoptabulate - -\section{Font|-|based Math Parameters} +\subsection{Font|-|based math parameters} \topicindex {math+parameters} @@ -584,7 +568,185 @@ Note 9: \type {FractionDelimiterDisplayStyleSize} and \type {FractionDelimiterSize} do not actually exist in the \quote {standard} \OPENTYPE\ math font Cambria, but were useful enough to be added. -\section {Nolimit correction} +\section {Math spacing} + +\subsection{Inline surrounding space} + +\topicindex {math+spacing} + +Inline math is surrounded by (optional) \prm {mathsurround} spacing but that is a fixed +dimension. There is now an additional parameter \lpr {mathsurroundskip}. When set to a +non|-|zero value (or zero with some stretch or shrink) this parameter will replace +\prm {mathsurround}. By using an additional parameter instead of changing the nature +of \prm {mathsurround}, we can remain compatible. In the meantime a bit more +control has been added via \lpr {mathsurroundmode}. This directive can take 6 values +with zero being the default behaviour. + +\start + +\def\OneLiner#1#2% + {\NC \type{#1} + \NC \dontleavehmode\inframed[align=normal,offset=0pt,frame=off]{\mathsurroundmode#1\relax\hsize 100pt x$x$x} + \NC \dontleavehmode\inframed[align=normal,offset=0pt,frame=off]{\mathsurroundmode#1\relax\hsize 100pt x $x$ x} + \NC #2 + \NC \NR} + +\startbuffer +\mathsurround 10pt +\mathsurroundskip20pt +\stopbuffer + +\typebuffer \getbuffer + +\starttabulate[|c|c|c|pl|] +\DB mode \BC x\$x\$x \BC x \$x\$ x \BC effect \NC \NR +\TB +\OneLiner{0}{obey \prm {mathsurround} when \lpr {mathsurroundskip} is 0pt} +\OneLiner{1}{only add skip to the left} +\OneLiner{2}{only add skip to the right} +\OneLiner{3}{add skip to the left and right} +\OneLiner{4}{ignore the skip setting, obey \prm {mathsurround}} +\OneLiner{5}{disable all spacing around math} +\OneLiner{6}{only apply \lpr {mathsurroundskip} when also spacing} +\OneLiner{7}{only apply \lpr {mathsurroundskip} when no spacing} +\LL +\stoptabulate + +\stop + +Method six omits the surround glue when there is (x)spacing glue present while +method seven does the opposite, the glue is only applied when there is (x)space +glue present too. Anything more fancy, like checking the begining or end of a +paragraph (or edges of a box) would not be robust anyway. If you want that you +can write a callback that runs over a list and analyzes a paragraph. Actually, in +that case you could also inject glue (or set the properties of a math node) +explicitly. So, these modes are in practice mostly useful for special purposes +and experiments (they originate in a tracker item). Keep in mind that this glue +is part of the math node and not always treated as normal glue: it travels with +the begin and end math nodes. Also, method 6 and 7 will zero the skip related +fields in a node when applicable in the first occasion that checks them +(linebreaking or packaging). + +\subsection{Pairwise spacing} + +\topicindex {math+spacing} + +Besides the parameters mentioned in the previous sections, there are also 64 new +primitives to control the math spacing table (as explained in Chapter~18 of the +\TEX book). The primitive names are a simple matter of combining two math atom +types, but for completeness' sake, here is the whole list: + +\starttwocolumns +\startlines +\lpr {Umathordordspacing} +\lpr {Umathordopspacing} +\lpr {Umathordbinspacing} +\lpr {Umathordrelspacing} +\lpr {Umathordopenspacing} +\lpr {Umathordclosespacing} +\lpr {Umathordpunctspacing} +\lpr {Umathordinnerspacing} +\lpr {Umathopordspacing} +\lpr {Umathopopspacing} +\lpr {Umathopbinspacing} +\lpr {Umathoprelspacing} +\lpr {Umathopopenspacing} +\lpr {Umathopclosespacing} +\lpr {Umathoppunctspacing} +\lpr {Umathopinnerspacing} +\lpr {Umathbinordspacing} +\lpr {Umathbinopspacing} +\lpr {Umathbinbinspacing} +\lpr {Umathbinrelspacing} +\lpr {Umathbinopenspacing} +\lpr {Umathbinclosespacing} +\lpr {Umathbinpunctspacing} +\lpr {Umathbininnerspacing} +\lpr {Umathrelordspacing} +\lpr {Umathrelopspacing} +\lpr {Umathrelbinspacing} +\lpr {Umathrelrelspacing} +\lpr {Umathrelopenspacing} +\lpr {Umathrelclosespacing} +\lpr {Umathrelpunctspacing} +\lpr {Umathrelinnerspacing} +\lpr {Umathopenordspacing} +\lpr {Umathopenopspacing} +\lpr {Umathopenbinspacing} +\lpr {Umathopenrelspacing} +\lpr {Umathopenopenspacing} +\lpr {Umathopenclosespacing} +\lpr {Umathopenpunctspacing} +\lpr {Umathopeninnerspacing} +\lpr {Umathcloseordspacing} +\lpr {Umathcloseopspacing} +\lpr {Umathclosebinspacing} +\lpr {Umathcloserelspacing} +\lpr {Umathcloseopenspacing} +\lpr {Umathcloseclosespacing} +\lpr {Umathclosepunctspacing} +\lpr {Umathcloseinnerspacing} +\lpr {Umathpunctordspacing} +\lpr {Umathpunctopspacing} +\lpr {Umathpunctbinspacing} +\lpr {Umathpunctrelspacing} +\lpr {Umathpunctopenspacing} +\lpr {Umathpunctclosespacing} +\lpr {Umathpunctpunctspacing} +\lpr {Umathpunctinnerspacing} +\lpr {Umathinnerordspacing} +\lpr {Umathinneropspacing} +\lpr {Umathinnerbinspacing} +\lpr {Umathinnerrelspacing} +\lpr {Umathinneropenspacing} +\lpr {Umathinnerclosespacing} +\lpr {Umathinnerpunctspacing} +\lpr {Umathinnerinnerspacing} +\stoplines +\stoptwocolumns + +These parameters are of type \prm {muskip}, so setting a parameter can be done +like this: + +\starttyping +\Umathopordspacing\displaystyle=4mu plus 2mu +\stoptyping + +They are all initialized by \type {initex} to the values mentioned in the table +in Chapter~18 of the \TEX book. + +Note 1: for ease of use as well as for backward compatibility, \prm {thinmuskip}, +\prm {medmuskip} and \prm {thickmuskip} are treated specially. In their case a +pointer to the corresponding internal parameter is saved, not the actual \prm +{muskip} value. This means that any later changes to one of these three +parameters will be taken into account. + +Note 2: Careful readers will realise that there are also primitives for the items +marked \type {*} in the \TEX book. These will not actually be used as those +combinations of atoms cannot actually happen, but it seemed better not to break +orthogonality. They are initialized to zero. + +\subsection{Skips around display math} + +\topicindex {math+spacing} + +The injection of \prm {abovedisplayskip} and \prm {belowdisplayskip} is not +symmetrical. An above one is always inserted, also when zero, but the below is +only inserted when larger than zero. Especially the latter makes it sometimes hard +to fully control spacing. Therefore \LUATEX\ comes with a new directive: \lpr +{mathdisplayskipmode}. The following values apply: + +\starttabulate[|c|l|] +\DB value \BC meaning \NC \NR +\TB +\NC 0 \NC normal \TEX\ behaviour \NC \NR +\NC 1 \NC always (same as 0) \NC \NR +\NC 2 \NC only when not zero \NC \NR +\NC 3 \NC never, not even when not zero \NC \NR +\LL +\stoptabulate + +\subsection {Nolimit correction} \topicindex {math+limits} @@ -642,7 +804,7 @@ shifts to the left. A \lpr {mathnolimitsmode} larger that 15 is considered to be a factor for the subscript correction. This feature can be handy when experimenting. -\section {Math italic mess} +\subsection {Math italic mess} \topicindex {math+italics} @@ -672,7 +834,7 @@ example. This kind of parameters relate to the fact that italic correction in \OPENTYPE\ math is bound to fuzzy rules. So, control is the solution. -\section {Script and kerning} +\subsection {Script and kerning} \topicindex {math+kerning} \topicindex {math+scripts} @@ -760,7 +922,84 @@ control over what one can turn on and off. \LL \stoptabulate -\section {Unscaled fences} +\subsection{Fixed scripts} + +We have three parameters that are used for this fixed anchoring: + +\starttabulate[|c|l|] +\DB parameter \BC register \NC \NR +\NC $d$ \NC \lpr {Umathsubshiftdown} \NC \NR +\NC $u$ \NC \lpr {Umathsupshiftup} \NC \NR +\NC $s$ \NC \lpr {Umathsubsupshiftdown} \NC \NR +\LL +\stoptabulate + +When we set \lpr {mathscriptsmode} to a value other than zero these are used +for calculating fixed positions. This is something that is needed for instance +for chemistry. You can manipulate the mentioned variables to achieve different +effects. + +\def\SampleMath#1% + {$\mathscriptsmode#1\mathupright CH_2 + CH^+_2 + CH^2_2$} + +\starttabulate[|c|c|c|p|] +\DB mode \BC down \BC up \BC example \NC \NR +\TB +\NC 0 \NC dynamic \NC dynamic \NC \SampleMath{0} \NC \NR +\NC 1 \NC $d$ \NC $u$ \NC \SampleMath{1} \NC \NR +\NC 2 \NC $s$ \NC $u$ \NC \SampleMath{2} \NC \NR +\NC 3 \NC $s$ \NC $u + s - d$ \NC \SampleMath{3} \NC \NR +\NC 4 \NC $d + (s-d)/2$ \NC $u + (s-d)/2$ \NC \SampleMath{4} \NC \NR +\NC 5 \NC $d$ \NC $u + s - d$ \NC \SampleMath{5} \NC \NR +\LL +\stoptabulate + +The value of this parameter obeys grouping but applies to the whole current +formula. + +% if needed we can put the value in stylenodes but maybe more should go there + +\subsection{Penalties: \lpr {mathpenaltiesmode}} + +\topicindex {math+penalties} + +Only in inline math penalties will be added in a math list. You can force +penalties (also in display math) by setting: + +\starttyping +\mathpenaltiesmode = 1 +\stoptyping + +This primnitive is not really needed in \LUATEX\ because you can use the callback +\cbk {mlist_to_hlist} to force penalties by just calling the regular routine +with forced penalties. However, as part of opening up and control this primitive +makes sense. As a bonus we also provide two extra penalties: + +\starttyping +\prebinoppenalty = -100 % example value +\prerelpenalty = 900 % example value +\stoptyping + +They default to inifinite which signals that they don't need to be inserted. When +set they are injected before a binop or rel noad. This is an experimental feature. + +\subsection{Equation spacing: \lpr {matheqnogapstep}} + +By default \TEX\ will add one quad between the equation and the number. This is +hard coded. A new primitive can control this: + +\startsyntax +\matheqnogapstep = 1000 +\stopsyntax + +Because a math quad from the math text font is used instead of a dimension, we +use a step to control the size. A value of zero will suppress the gap. The step +is divided by 1000 which is the usual way to mimmick floating point factors in +\TEX. + +\section {Math constructs} + +\subsection {Unscaled fences} \topicindex {math+fences} @@ -806,106 +1045,7 @@ with in the engine). The full list of flags is given in the next table: The effect can depend on the font (and for Cambria one can use for instance \type {"16}). -\section {Math spacing setting} - -\topicindex {math+spacing} - -Besides the parameters mentioned in the previous sections, there are also 64 new -primitives to control the math spacing table (as explained in Chapter~18 of the -\TEX book). The primitive names are a simple matter of combining two math atom -types, but for completeness' sake, here is the whole list: - -\starttwocolumns -\startlines -\lpr {Umathordordspacing} -\lpr {Umathordopspacing} -\lpr {Umathordbinspacing} -\lpr {Umathordrelspacing} -\lpr {Umathordopenspacing} -\lpr {Umathordclosespacing} -\lpr {Umathordpunctspacing} -\lpr {Umathordinnerspacing} -\lpr {Umathopordspacing} -\lpr {Umathopopspacing} -\lpr {Umathopbinspacing} -\lpr {Umathoprelspacing} -\lpr {Umathopopenspacing} -\lpr {Umathopclosespacing} -\lpr {Umathoppunctspacing} -\lpr {Umathopinnerspacing} -\lpr {Umathbinordspacing} -\lpr {Umathbinopspacing} -\lpr {Umathbinbinspacing} -\lpr {Umathbinrelspacing} -\lpr {Umathbinopenspacing} -\lpr {Umathbinclosespacing} -\lpr {Umathbinpunctspacing} -\lpr {Umathbininnerspacing} -\lpr {Umathrelordspacing} -\lpr {Umathrelopspacing} -\lpr {Umathrelbinspacing} -\lpr {Umathrelrelspacing} -\lpr {Umathrelopenspacing} -\lpr {Umathrelclosespacing} -\lpr {Umathrelpunctspacing} -\lpr {Umathrelinnerspacing} -\lpr {Umathopenordspacing} -\lpr {Umathopenopspacing} -\lpr {Umathopenbinspacing} -\lpr {Umathopenrelspacing} -\lpr {Umathopenopenspacing} -\lpr {Umathopenclosespacing} -\lpr {Umathopenpunctspacing} -\lpr {Umathopeninnerspacing} -\lpr {Umathcloseordspacing} -\lpr {Umathcloseopspacing} -\lpr {Umathclosebinspacing} -\lpr {Umathcloserelspacing} -\lpr {Umathcloseopenspacing} -\lpr {Umathcloseclosespacing} -\lpr {Umathclosepunctspacing} -\lpr {Umathcloseinnerspacing} -\lpr {Umathpunctordspacing} -\lpr {Umathpunctopspacing} -\lpr {Umathpunctbinspacing} -\lpr {Umathpunctrelspacing} -\lpr {Umathpunctopenspacing} -\lpr {Umathpunctclosespacing} -\lpr {Umathpunctpunctspacing} -\lpr {Umathpunctinnerspacing} -\lpr {Umathinnerordspacing} -\lpr {Umathinneropspacing} -\lpr {Umathinnerbinspacing} -\lpr {Umathinnerrelspacing} -\lpr {Umathinneropenspacing} -\lpr {Umathinnerclosespacing} -\lpr {Umathinnerpunctspacing} -\lpr {Umathinnerinnerspacing} -\stoplines -\stoptwocolumns - -These parameters are of type \prm {muskip}, so setting a parameter can be done -like this: - -\starttyping -\Umathopordspacing\displaystyle=4mu plus 2mu -\stoptyping - -They are all initialized by \type {initex} to the values mentioned in the table -in Chapter~18 of the \TEX book. - -Note 1: for ease of use as well as for backward compatibility, \prm {thinmuskip}, -\prm {medmuskip} and \prm {thickmuskip} are treated specially. In their case a -pointer to the corresponding internal parameter is saved, not the actual \prm -{muskip} value. This means that any later changes to one of these three -parameters will be taken into account. - -Note 2: Careful readers will realise that there are also primitives for the items -marked \type {*} in the \TEX book. These will not actually be used as those -combinations of atoms cannot actually happen, but it seemed better not to break -orthogonality. They are initialized to zero. - -\section[mathacc]{Math accent handling} +\subsection[mathacc]{Accent handling} \topicindex {math+accents} @@ -954,7 +1094,7 @@ fraction only applies to the stepwise selected shapes and is mostly meant for th \type {overlay} location. It also works for the other locations but then it concerns the width. -\section{Math root extension} +\subsection{Radical extensions} \topicindex {math+radicals} @@ -971,7 +1111,7 @@ The placement of the degree is controlled by the math parameters \lpr {Umathradicaldegreeraise}. The degree will be typeset in \prm {scriptscriptstyle}. -\section{Math kerning in super- and subscripts} +\subsection{Super- and subscripts} The character fields in a \LUA|-|loaded \OPENTYPE\ math font can have a \quote {mathkern} table. The format of this table is the same as the \quote {mathkern} @@ -1030,7 +1170,7 @@ next higher height and kern pair, or the highest one in the character (if there value high enough in the character), or simply zero (if the character has no math kern pairs at all). -\section{Scripts on horizontally extensible items like arrows} +\subsection{Scripts on extensibles} \topicindex {math+scripts} \topicindex {math+delimiters} @@ -1092,38 +1232,7 @@ $\Uhextensible width 1pt middle 0 "2194$ font metrics are involved we have a different code path for traditional fonts end \OPENTYPE\ fonts. -\section {Extracting values} - -\topicindex {math+codes} - -You can extract the components of a math character. Say that we have defined: - -\starttyping -\Umathcode 1 2 3 4 -\stoptyping - -then - -\starttyping -[\Umathcharclass1] [\Umathcharfam1] [\Umathcharslot1] -\stoptyping - -will return: - -\starttyping -[2] [3] [4] -\stoptyping - -These commands are provides as convenience. Before they come available you could -do the following: - -\starttyping -\def\Umathcharclass{\directlua{tex.print(tex.getmathcode(token.scan_int())[1])}} -\def\Umathcharfam {\directlua{tex.print(tex.getmathcode(token.scan_int())[2])}} -\def\Umathcharslot {\directlua{tex.print(tex.getmathcode(token.scan_int())[3])}} -\stoptyping - -\section{fractions} +\subsection{Fractions} \topicindex {math+fractions} @@ -1187,7 +1296,81 @@ For Latin Modern the result looks as follows: \stoptabulate \stop -\section {Last lines} +\subsection {Delimiters: \type{\Uleft}, \prm {Umiddle} and \prm {Uright}} + +\topicindex {math+delimiters} + +Normally you will force delimiters to certain sizes by putting an empty box or +rule next to it. The resulting delimiter will either be a character from the +stepwise size range or an extensible. The latter can be quite differently +positioned than the characters as it depends on the fit as well as the fact if +the used characters in the font have depth or height. Commands like (plain \TEX +s) \type {\big} need use this feature. In \LUATEX\ we provide a bit more control +by three variants that support optional parameters \type {height}, \type {depth} +and \type {axis}. The following example uses this: + +\startbuffer +\Uleft height 30pt depth 10pt \Udelimiter "0 "0 "000028 +\quad x\quad +\Umiddle height 40pt depth 15pt \Udelimiter "0 "0 "002016 +\quad x\quad +\Uright height 30pt depth 10pt \Udelimiter "0 "0 "000029 +\quad \quad \quad +\Uleft height 30pt depth 10pt axis \Udelimiter "0 "0 "000028 +\quad x\quad +\Umiddle height 40pt depth 15pt axis \Udelimiter "0 "0 "002016 +\quad x\quad +\Uright height 30pt depth 10pt axis \Udelimiter "0 "0 "000029 +\stopbuffer + +\typebuffer + +\startlinecorrection +\ruledhbox{\mathematics{\getbuffer}} +\stoplinecorrection + +The keyword \type {exact} can be used as directive that the real dimensions +should be applied when the criteria can't be met which can happen when we're +still stepping through the successively larger variants. When no dimensions are +given the \type {noaxis} command can be used to prevent shifting over the axis. + +You can influence the final class with the keyword \type {class} which will +influence the spacing. The numbers are the same as for character classes. + +\section {Extracting values} + +\subsection{Codes} + +\topicindex {math+codes} + +You can extract the components of a math character. Say that we have defined: + +\starttyping +\Umathcode 1 2 3 4 +\stoptyping + +then + +\starttyping +[\Umathcharclass1] [\Umathcharfam1] [\Umathcharslot1] +\stoptyping + +will return: + +\starttyping +[2] [3] [4] +\stoptyping + +These commands are provides as convenience. Before they come available you could +do the following: + +\starttyping +\def\Umathcharclass{\directlua{tex.print(tex.getmathcode(token.scan_int())[1])}} +\def\Umathcharfam {\directlua{tex.print(tex.getmathcode(token.scan_int())[2])}} +\def\Umathcharslot {\directlua{tex.print(tex.getmathcode(token.scan_int())[3])}} +\stoptyping + +\subsection {Last lines} \topicindex {math+last line} @@ -1211,7 +1394,7 @@ get the length of the last line, the following will often work too: \relax} \stoptyping -\section {Other Math changes} +\section {Math mode} \subsection {Verbose versions of single|-|character math commands} @@ -1271,63 +1454,6 @@ the result of \prm {mathchardef} or \lpr {Umathchardef} are also acceptable in the horizontal and vertical modes. In those cases, the \prm {textfont} from the requested math family is used. -\section{Math surrounding skips} - -\topicindex {math+spacing} - -Inline math is surrounded by (optional) \prm {mathsurround} spacing but that is a fixed -dimension. There is now an additional parameter \lpr {mathsurroundskip}. When set to a -non|-|zero value (or zero with some stretch or shrink) this parameter will replace -\prm {mathsurround}. By using an additional parameter instead of changing the nature -of \prm {mathsurround}, we can remain compatible. In the meantime a bit more -control has been added via \lpr {mathsurroundmode}. This directive can take 6 values -with zero being the default behaviour. - -\start - -\def\OneLiner#1#2% - {\NC \type{#1} - \NC \dontleavehmode\inframed[align=normal,offset=0pt,frame=off]{\mathsurroundmode#1\relax\hsize 100pt x$x$x} - \NC \dontleavehmode\inframed[align=normal,offset=0pt,frame=off]{\mathsurroundmode#1\relax\hsize 100pt x $x$ x} - \NC #2 - \NC \NR} - -\startbuffer -\mathsurround 10pt -\mathsurroundskip20pt -\stopbuffer - -\typebuffer \getbuffer - -\starttabulate[|c|c|c|pl|] -\DB mode \BC x\$x\$x \BC x \$x\$ x \BC effect \NC \NR -\TB -\OneLiner{0}{obey \prm {mathsurround} when \lpr {mathsurroundskip} is 0pt} -\OneLiner{1}{only add skip to the left} -\OneLiner{2}{only add skip to the right} -\OneLiner{3}{add skip to the left and right} -\OneLiner{4}{ignore the skip setting, obey \prm {mathsurround}} -\OneLiner{5}{disable all spacing around math} -\OneLiner{6}{only apply \lpr {mathsurroundskip} when also spacing} -\OneLiner{7}{only apply \lpr {mathsurroundskip} when no spacing} -\LL -\stoptabulate - -\stop - -Method six omits the surround glue when there is (x)spacing glue present while -method seven does the opposite, the glue is only applied when there is (x)space -glue present too. Anything more fancy, like checking the begining or end of a -paragraph (or edges of a box) would not be robust anyway. If you want that you -can write a callback that runs over a list and analyzes a paragraph. Actually, in -that case you could also inject glue (or set the properties of a math node) -explicitly. So, these modes are in practice mostly useful for special purposes -and experiments (they originate in a tracker item). Keep in mind that this glue -is part of the math node and not always treated as normal glue: it travels with -the begin and end math nodes. Also, method 6 and 7 will zero the skip related -fields in a node when applicable in the first occasion that checks them -(linebreaking or packaging). - % \section{Math todo} % % The following items are still todo. @@ -1350,121 +1476,7 @@ fields in a node when applicable in the first occasion that checks them % \stopitem % \stopitemize -\subsection {Delimiters: \type{\Uleft}, \prm {Umiddle} and \prm {Uright}} - -\topicindex {math+delimiters} - -Normally you will force delimiters to certain sizes by putting an empty box or -rule next to it. The resulting delimiter will either be a character from the -stepwise size range or an extensible. The latter can be quite differently -positioned than the characters as it depends on the fit as well as the fact if -the used characters in the font have depth or height. Commands like (plain \TEX -s) \type {\big} need use this feature. In \LUATEX\ we provide a bit more control -by three variants that support optional parameters \type {height}, \type {depth} -and \type {axis}. The following example uses this: - -\startbuffer -\Uleft height 30pt depth 10pt \Udelimiter "0 "0 "000028 -\quad x\quad -\Umiddle height 40pt depth 15pt \Udelimiter "0 "0 "002016 -\quad x\quad -\Uright height 30pt depth 10pt \Udelimiter "0 "0 "000029 -\quad \quad \quad -\Uleft height 30pt depth 10pt axis \Udelimiter "0 "0 "000028 -\quad x\quad -\Umiddle height 40pt depth 15pt axis \Udelimiter "0 "0 "002016 -\quad x\quad -\Uright height 30pt depth 10pt axis \Udelimiter "0 "0 "000029 -\stopbuffer - -\typebuffer - -\startlinecorrection -\ruledhbox{\mathematics{\getbuffer}} -\stoplinecorrection - -The keyword \type {exact} can be used as directive that the real dimensions -should be applied when the criteria can't be met which can happen when we're -still stepping through the successively larger variants. When no dimensions are -given the \type {noaxis} command can be used to prevent shifting over the axis. - -You can influence the final class with the keyword \type {class} which will -influence the spacing. The numbers are the same as for character classes. - -\subsection{Fixed scripts} - -We have three parameters that are used for this fixed anchoring: - -\starttabulate[|c|l|] -\DB parameter \BC register \NC \NR -\NC $d$ \NC \lpr {Umathsubshiftdown} \NC \NR -\NC $u$ \NC \lpr {Umathsupshiftup} \NC \NR -\NC $s$ \NC \lpr {Umathsubsupshiftdown} \NC \NR -\LL -\stoptabulate - -When we set \lpr {mathscriptsmode} to a value other than zero these are used -for calculating fixed positions. This is something that is needed for instance -for chemistry. You can manipulate the mentioned variables to achieve different -effects. - -\def\SampleMath#1% - {$\mathscriptsmode#1\mathupright CH_2 + CH^+_2 + CH^2_2$} - -\starttabulate[|c|c|c|p|] -\DB mode \BC down \BC up \BC example \NC \NR -\TB -\NC 0 \NC dynamic \NC dynamic \NC \SampleMath{0} \NC \NR -\NC 1 \NC $d$ \NC $u$ \NC \SampleMath{1} \NC \NR -\NC 2 \NC $s$ \NC $u$ \NC \SampleMath{2} \NC \NR -\NC 3 \NC $s$ \NC $u + s - d$ \NC \SampleMath{3} \NC \NR -\NC 4 \NC $d + (s-d)/2$ \NC $u + (s-d)/2$ \NC \SampleMath{4} \NC \NR -\NC 5 \NC $d$ \NC $u + s - d$ \NC \SampleMath{5} \NC \NR -\LL -\stoptabulate - -The value of this parameter obeys grouping but applies to the whole current -formula. - -% if needed we can put the value in stylenodes but maybe more should go there - -\subsection{Penalties: \lpr {mathpenaltiesmode}} - -\topicindex {math+penalties} - -Only in inline math penalties will be added in a math list. You can force -penalties (also in display math) by setting: - -\starttyping -\mathpenaltiesmode = 1 -\stoptyping - -This primnitive is not really needed in \LUATEX\ because you can use the callback -\cbk {mlist_to_hlist} to force penalties by just calling the regular routine -with forced penalties. However, as part of opening up and control this primitive -makes sense. As a bonus we also provide two extra penalties: - -\starttyping -\prebinoppenalty = -100 % example value -\prerelpenalty = 900 % example value -\stoptyping - -They default to inifinite which signals that they don't need to be inserted. When -set they are injected before a binop or rel noad. This is an experimental feature. - -\subsection{Equation spacing: \lpr {matheqnogapstep}} - -By default \TEX\ will add one quad between the equation and the number. This is -hard coded. A new primitive can control this: - -\startsyntax -\matheqnogapstep = 1000 -\stopsyntax - -Because a math quad from the math text font is used instead of a dimension, we -use a step to control the size. A value of zero will suppress the gap. The step -is divided by 1000 which is the usual way to mimmick floating point factors in -\TEX. +\section {Goodies} \subsection {Flattening: \lpr {mathflattenmode}} @@ -1509,7 +1521,7 @@ mode parameter. The default value is~1. \LL \stoptabulate -\subsection {Tracing} +\subsection {Less Tracing} \topicindex {math+tracing} @@ -1517,20 +1529,20 @@ Because there are quite some math related parameters and values, it is possible to limit tracing. Only when \type {tracingassigns} and|/|or \type {tracingrestores} are set to~2 or more they will be traced. -\subsection {Math options} +\subsection {Math options with \lpr {mathoption}} The logic in the math engine is rather complex and there are often no universal solutions (read: what works out well for one font, fails for another). Therefore -some variations in the implementation are driven by parameters (modes). In addition -there is a new primitive \lpr {mathoption} which will be used for testing. - -\subsubsection {\type {\mathoption old}} +some variations in the implementation are driven by parameters (modes). In +addition there is a new primitive \lpr {mathoption} which will be used for +testing. Don't rely on any option to be there in a production version as they are +meant for development. This option was introduced for testing purposes when the math engine got split code paths and it forces the engine to treat new fonts as old ones with respect to italic correction etc. There are no guarantees given with respect to the final result and unexpected side effects are not seen as bugs as they relate to font -properties. +properties. Ther eis currently only one option: \startbuffer \mathoption old 1 @@ -1540,11 +1552,6 @@ The \type {oldmath} boolean flag in the \LUA\ font table is the official way to force old treatment as it's bound to fonts. Like with all options we may temporarily introduce with this command this feature is not meant for production. -\subsubsection {Obsolete options} - -The following options are gone: \typ {noitaliccompensation}, \typ {nocharitalic}, -\typ {useoldfractionscaling}, and \typ {umathcodemeaning}. - % % obsolete: % % \subsubsection {\type {\mathoption noitaliccompensation}} diff --git a/doc/context/sources/general/manuals/luatex/luatex-modifications.tex b/doc/context/sources/general/manuals/luatex/luatex-modifications.tex index 72c4e72d7..b1b803d48 100644 --- a/doc/context/sources/general/manuals/luatex/luatex-modifications.tex +++ b/doc/context/sources/general/manuals/luatex/luatex-modifications.tex @@ -1,4 +1,4 @@ -4% language=uk +% language=uk \environment luatex-style @@ -409,8 +409,8 @@ we say next applies to both these programs. \stopitem \startitem - \LUATEX\ only understands 4~of the 16~direction specifiers of \ALEPH: \orm - {TLT} (latin), \orm {TRT} (arabic), \orm {RTT} (cjk), \orm {LTL} (mongolian). + \LUATEX\ only understands 4~of the 16~direction specifiers of \ALEPH: \type + {TLT} (latin), \type {TRT} (arabic), \type {RTT} (cjk), \type {LTL} (mongolian). All other direction specifiers generate an error. In addition to a keyword driven model we also provide an integer driven one. \stopitem @@ -543,7 +543,9 @@ different: \stopsection -\startsection[reference=backendprimitives,title=The backend primitives \type {\pdf*}] +\startsection[reference=backendprimitives,title=The backend primitives] + +\startsubsection[title={Less primitives}] \topicindex {backend} \topicindex {\PDF+backend} @@ -568,6 +570,10 @@ An extension triggers further parsing, depending on the command given. A variabl a (kind of) register and can be read and written, while a feedback is reporting something (as it comes from the backend it's normally a sequence of tokens). +\stopsubsection + +\startsubsection[title={\lpr{pdfextension}, \lpr {pdfvariable} and \lpr {pdffeedback}}] + In order for \LUATEX\ to be more than just \TEX\ you need to enable primitives. That has already been the case right from the start. If you want the traditional \PDFTEX\ primitives (for as far their functionality is still around) you now can do this: @@ -676,101 +682,16 @@ macro:->[internal backend integer] macro:->[internal backend tokenlist] \stoptyping -The \prm {edef} can also be a \prm {def} but it's a bit more efficient -to expand the lookup related register beforehand. After that you can adapt -the defaults; these are: - -\starttyping -\pdfcompresslevel 9 -\pdfobjcompresslevel 1 % used: (0,9) -\pdfrecompress 0 % mostly for debugging -\pdfdecimaldigits 4 % used: (3,6) -\pdfgamma 1000 -\pdfimageresolution 71 -\pdfimageapplygamma 0 -\pdfimagegamma 2200 -\pdfimagehicolor 1 -\pdfimageaddfilename 1 -\pdfpkresolution 72 -\pdfpkfixeddpi 0 -\pdfinclusioncopyfonts 0 -\pdfinclusionerrorlevel 0 -\pdfignoreunknownimages 0 -\pdfgentounicode 0 -\pdfomitcidset 0 -\pdfpagebox 0 -\pdfminorversion 4 -\pdfuniqueresname 0 - -\pdfhorigin 1in -\pdfvorigin 1in -\pdflinkmargin 0pt -\pdfdestmargin 0pt -\pdfthreadmargin 0pt -\pdfxformmargin 0pt -\stoptyping - -If you also want some backward compatibility, you can add: - -\starttyping -\let\pdfpagewidth \pagewidth -\let\pdfpageheight \pageheight - -\let\pdfadjustspacing \adjustspacing -\let\pdfprotrudechars \protrudechars -\let\pdfnoligatures \ignoreligaturesinfont -\let\pdffontexpand \expandglyphsinfont -\let\pdfcopyfont \copyfont - -\let\pdfxform \saveboxresource -\let\pdflastxform \lastsavedboxresourceindex -\let\pdfrefxform \useboxresource - -\let\pdfximage \saveimageresource -\let\pdflastximage \lastsavedimageresourceindex -\let\pdflastximagepages\lastsavedimageresourcepages -\let\pdfrefximage \useimageresource - -\let\pdfsavepos \savepos -\let\pdflastxpos \lastxpos -\let\pdflastypos \lastypos - -\let\pdfoutput \outputmode -\let\pdfdraftmode \draftmode - -\let\pdfpxdimen \pxdimen - -\let\pdfinsertht \insertht - -\let\pdfnormaldeviate \normaldeviate -\let\pdfuniformdeviate \uniformdeviate -\let\pdfsetrandomseed \setrandomseed -\let\pdfrandomseed \randomseed - -\let\pdfprimitive \primitive -\let\ifpdfprimitive \ifprimitive - -\let\ifpdfabsnum \ifabsnum -\let\ifpdfabsdim \ifabsdim -\stoptyping - -And even: - -\starttyping -\newdimen\pdfeachlineheight -\newdimen\pdfeachlinedepth -\newdimen\pdflastlinedepth -\newdimen\pdffirstlineheight -\newdimen\pdfignoreddimen -\stoptyping +The \prm {edef} can also be a \prm {def} but it's a bit more efficient to expand +the lookup related register beforehand. The backend is derived from \PDFTEX\ so the same syntax applies. However, the \type {outline} command accepts a \type {objnum} followed by a number. No checking takes place so when this is used it had better be a valid (flushed) object. -In order to be (more or less) compatible with \PDFTEX\ we also support the -option to suppress some info: +In order to be (more or less) compatible with \PDFTEX\ we also support the option +to suppress some info but we do so via a bitset: \starttyping \pdfvariable suppressoptionalinfo \numexpr @@ -790,7 +711,7 @@ option to suppress some info: In addition you can overload the trailer id, but we don't do any checking on validity, so you have to pass a valid array. The following is like the ones -normally generated by the engine: +normally generated by the engine. You even need to include the brackets here! \starttyping \pdfvariable trailerid {[ @@ -799,8 +720,6 @@ normally generated by the engine: ]} \stoptyping -So, you even need to include the brackets! - Although we started from a merge of \PDFTEX\ and \ALEPH, by now the code base as well as functionality has diverted from those parents. Here we show the options that can be passed to the extensions. @@ -948,6 +867,102 @@ that can be passed to the extensions. {tokens} \stoptexsyntax +\stopsubsection + +\startsubsection[title={Defaults}] + +The engine sets the following defaults. + +\starttyping +\pdfcompresslevel 9 +\pdfobjcompresslevel 1 % used: (0,9) +\pdfrecompress 0 % mostly for debugging +\pdfdecimaldigits 4 % used: (3,6) +\pdfgamma 1000 +\pdfimageresolution 71 +\pdfimageapplygamma 0 +\pdfimagegamma 2200 +\pdfimagehicolor 1 +\pdfimageaddfilename 1 +\pdfpkresolution 72 +\pdfpkfixeddpi 0 +\pdfinclusioncopyfonts 0 +\pdfinclusionerrorlevel 0 +\pdfignoreunknownimages 0 +\pdfgentounicode 0 +\pdfomitcidset 0 +\pdfpagebox 0 +\pdfminorversion 4 +\pdfuniqueresname 0 + +\pdfhorigin 1in +\pdfvorigin 1in +\pdflinkmargin 0pt +\pdfdestmargin 0pt +\pdfthreadmargin 0pt +\pdfxformmargin 0pt +\stoptyping + +\stopsubsection + +\startsubsection[title={Backward compatibility}] + +If you also want some backward compatibility, you can add: + +\starttyping +\let\pdfpagewidth \pagewidth +\let\pdfpageheight \pageheight + +\let\pdfadjustspacing \adjustspacing +\let\pdfprotrudechars \protrudechars +\let\pdfnoligatures \ignoreligaturesinfont +\let\pdffontexpand \expandglyphsinfont +\let\pdfcopyfont \copyfont + +\let\pdfxform \saveboxresource +\let\pdflastxform \lastsavedboxresourceindex +\let\pdfrefxform \useboxresource + +\let\pdfximage \saveimageresource +\let\pdflastximage \lastsavedimageresourceindex +\let\pdflastximagepages\lastsavedimageresourcepages +\let\pdfrefximage \useimageresource + +\let\pdfsavepos \savepos +\let\pdflastxpos \lastxpos +\let\pdflastypos \lastypos + +\let\pdfoutput \outputmode +\let\pdfdraftmode \draftmode + +\let\pdfpxdimen \pxdimen + +\let\pdfinsertht \insertht + +\let\pdfnormaldeviate \normaldeviate +\let\pdfuniformdeviate \uniformdeviate +\let\pdfsetrandomseed \setrandomseed +\let\pdfrandomseed \randomseed + +\let\pdfprimitive \primitive +\let\ifpdfprimitive \ifprimitive + +\let\ifpdfabsnum \ifabsnum +\let\ifpdfabsdim \ifabsdim +\stoptyping + +And even: + +\starttyping +\newdimen\pdfeachlineheight +\newdimen\pdfeachlinedepth +\newdimen\pdflastlinedepth +\newdimen\pdffirstlineheight +\newdimen\pdfignoreddimen +\stoptyping + +\stopsubsection + \stopsection \startsection[title=Directions] @@ -956,6 +971,8 @@ that can be passed to the extensions. \topicindex {\ALEPH} \topicindex {directions} +\startsubsection[title={Four directions}] + The directional model in \LUATEX\ is inherited from \OMEGA|/|\ALEPH\ but we tried to improve it a bit. At some point we played with recovery of modes but that was disabled later on when we found that it interfered with nested directions. That @@ -963,14 +980,23 @@ itself had as side effect that the node list was no longer balanced with respect to directional nodes which in turn can give side effects when a series of dir changes happens without grouping. -The current (0.97 onward) approach is that we again make the list balanced but -try to avoid some side effects. What happens is quite intuitive if we forget -about spaces (turned into glue) but even there what happens makes sense if you -look at it in detail. However that logic makes in|-|group switching kind of -useless when no proper nested grouping is used: switching from right to left -several times nested, results in spacing ending up after each other due to nested -mirroring. Of course a sane macro package will manage this for the user but here -we are discussing the low level dir injection. +When extending the \PDF\ backend to support directions some inconsistencies were +found and as a result we decided to support only the four models that make sense +\type {TLT} (latin), \type {TRT} (arabic), \type {RTT} (cjk) and \type {LTL} +(mongolian). + +\stopsubsection + +\startsubsection[title={How it works}] + +The approach is that we again make the list balanced but try to avoid some side +effects. What happens is quite intuitive if we forget about spaces (turned into +glue) but even there what happens makes sense if you look at it in detail. +However that logic makes in|-|group switching kind of useless when no proper +nested grouping is used: switching from right to left several times nested, +results in spacing ending up after each other due to nested mirroring. Of course +a sane macro package will manage this for the user but here we are discussing the +low level dir injection. This is what happens: @@ -1087,6 +1113,10 @@ kerns, should be handled in the input or macro package because there is no way w can predict the expected behaviour. In fact, the \lpr {linedir} is just a convenience extra which could also have been implemented using node list parsing. +\stopsubsection + +\startsubsection[title={Controlling glue with \lpr {breakafterdirmode}}] + Glue after a dir node is ignored in the linebreak decision but you can bypass that by setting \lpr {breakafterdirmode} to~\type {1}. The following table shows the difference. Watch your spaces. @@ -1117,6 +1147,10 @@ difference. Watch your spaces. \LL \stoptabulate +\stopsubsection + +\startsubsection[title={Controling parshapes with \lpr {shapemode}}] + Another adaptation to the \ALEPH\ directional model is control over shapes driven by \prm {hangindent} and \prm {parshape}. This is controlled by a new parameter \lpr {shapemode}: @@ -1178,6 +1212,38 @@ this. In \in {figure} [fig:shapemode] a few examples are given. \stopcombination \stopplacefigure +\stopsubsection + +\startsubsection[title={Symbols or numbers}] + +Internally the implementation is different from \ALEPH. First of all we use no +whatsits but dedicated nodes, but also we have only 4 directions that are mapped +onto 4 numbers. A text direction node can mark the start or end of a sequence of +nodes, and therefore has two states. At the \TEX\ end we don't see these states +because \TEX\ itself will add proper end state nodes if needed. + +The symbolic names \type {TLT}, \type {TRT}, etc.\ originate in \OMEGA. In +\LUATEX\ we also have a number based model which sometimes makes more sense. + +\starttabulate[|c|l|l|] +\DB value \BC equivalent \NC \NR +\TB +\BC \type {0} \NC TLT \NC \NR +\BC \type {1} \NC TRT \NC \NR +\BC \type {2} \NC LTL \NC \NR +\BC \type {3} \NC RTT \NC \NR +\LL +\stoptabulate + +We support the \OMEGA\ primitives \orm {textdir}, \orm {pardir}, \orm {pagedir}, +\orm {pardir} and \orm {mathdir}. These accept three character keywords. The +primitives that set the direction by number are: \lpr {textdirection}, \lpr +{pardirection}, \lpr {pagedirection} and \lpr {bodydirection} and \lpr +{mathdirection}. When specifying a direction for a box you can use \type {bdir} +instead of \type {dir}. + +\stopsubsection + \stopsection \startsection[title=Implementation notes] @@ -1255,13 +1321,15 @@ control sequences that uses a prefix that is otherwise impossible to obtain. \stopsubsection -\startsubsection[title=Compressed format] +\startsubsection[title=The compressed format file] \topicindex {format} The format is passed through \type {zlib}, allowing it to shrink to roughly half of the size it would have had in uncompressed form. This takes a bit more \CPU\ -cycles but much less disk \IO, so it should still be faster. +cycles but much less disk \IO, so it should still be faster. We use a level~3 +compression which we found to be the optimal trade|-|off between filesize and +decompression speed. \stopsubsection 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 diff --git a/doc/context/sources/general/manuals/luatex/luatex-style.tex b/doc/context/sources/general/manuals/luatex/luatex-style.tex index c588763a6..45129f845 100644 --- a/doc/context/sources/general/manuals/luatex/luatex-style.tex +++ b/doc/context/sources/general/manuals/luatex/luatex-style.tex @@ -131,6 +131,9 @@ \setuphead [subsection] [color=maincolor] \setuphead [subsubsection][color=maincolor] +\setupfloats + [ntop=4] + \definehead [remark] [subsubsubject] diff --git a/doc/context/sources/general/manuals/luatex/luatex.tex b/doc/context/sources/general/manuals/luatex/luatex.tex index b9df4f202..6ee2c72e3 100644 --- a/doc/context/sources/general/manuals/luatex/luatex.tex +++ b/doc/context/sources/general/manuals/luatex/luatex.tex @@ -53,6 +53,7 @@ \startdocument [status=experimental, version=1.09] +% [version=1.10] \startnotmode[*export] \component luatex-titlepage |