diff options
| author | Luigi Scarso <luigi.scarso@gmail.com> | 2017-04-16 09:10:05 +0000 |
|---|---|---|
| committer | Luigi Scarso <luigi.scarso@gmail.com> | 2017-04-16 09:10:05 +0000 |
| commit | e9b0196e322c6698e646707c3ca475ed71e5e4c7 (patch) | |
| tree | ff9476e9bcae6b1ab3a62849030751d35ffcb3cc /Master | |
| parent | bf116d0aa38e0248d454de32e3954855a8323752 (diff) | |
updated luatex 1.0.4 manual
git-svn-id: svn://tug.org/texlive/trunk@43839 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master')
16 files changed, 1943 insertions, 794 deletions
diff --git a/Master/texmf-dist/doc/luatex/base/luatex-backend.tex b/Master/texmf-dist/doc/luatex/base/luatex-backend.tex index 5189ed01d8e..40b64721188 100644 --- a/Master/texmf-dist/doc/luatex/base/luatex-backend.tex +++ b/Master/texmf-dist/doc/luatex/base/luatex-backend.tex @@ -52,6 +52,11 @@ The version is frozen in the binary but you can set the minor version. What mino version you set depends on what \PDF\ features you use. This is out of control of \LUATEX. +\subsection{\type {getcreationdate}} + +This function returns a string with the date in the format that ends up in the +\PDF\ file, in this case it's: {\tttf \cldcontext{pdf.getcreationdate()}}. + \subsection{\type {[set|get]inclusionerrorlevel}, \type {[set|get]ignoreunknownimages}} These variable control how error in included image are treated. They are modeled @@ -76,6 +81,15 @@ the maximum is~9. These two functions set the level of compression. The minimum value is~0, the maximum is~9. +\subsection{\type {[set|get]gentounicode}} + +This flag enables tounicode generation (like in \PDFTEX). + +\subsection{\type {[set|get]omitcidset}} + +This flag disables inclusion of a so called CIDSet which can be handy when aiming +at some of the many \PDF\ substandards. + \subsection{\type {[set|get]decimaldigits}} These two functions set the accuracy of floats written to the \PDF file. You can @@ -112,6 +126,11 @@ pdf.setorigin(tex.sp("1in"),tex.sp("1in")) The counterpart of this function returns two values. +\subsection{\type {[set|get]imageresolution}} + +These two functions relate to the imageresolution that is used when the image +itself doesn't provide a non|-|zero x or y resolution. + \subsection {\type {[set|get][link|dest|thread|xform]margin}} These functions can be used to set and retrieve the margins that are added to the @@ -297,6 +316,15 @@ are the same as for the similar backend extension primitive. pdf.newcolorstack("0 g","page",true) -- page|direct|origin \stopfunctioncall +\subsection {\type {setfontattributes}} + +This function will force some additional code into the font resource. It can for +instance be used to add a custom \type {ToUnicode} vector to a bitmap file. + +\startfunctioncall +pdf.setfontattributes(<number> font id, <string> pdf code) +\stopfunctioncall + \section {The \type {pdfscanner} library} The \type {pdfscanner} library allows interpretation of \PDF\ content streams and @@ -923,20 +951,24 @@ arguments: \NC \type {stream} \NC this is a (in low level \LUA\ speak) light userdata object, i.e.\ a pointer to a sequence of bytes \NC \NR \NC \type {length} \NC this is the length of the stream in bytes \NC \NR -\NC \type {name} \NC this is a unique identifier that us used for hashing the - stream, so that mulltiple doesn't use more memory \NC \NR +\NC \type {name} \NC this is a unique identifier that is used for hashing the + stream, so that multiple doesn't use more memory \NC \NR \stoptabulate Instead of a light userdata stream you can also pass a \LUA\ string, in which case the given length is (at most) the string length. -The returned object can be used in the \type {img} library instead of a filename. +The function returns a \type{epdf} object and a string. The string can be used in +the \type {img} library instead of a filename. You need to prevent garbage +collection of the object when you use it as image (for instance by storing it +somewhere). + Both the memory stream and it's use in the image library is experimental and can change. In case you wonder where this can be used: when you use the swiglib library for \type {graphicmagick}, it can return such a userdata object. This permits conversion in memory and passing the result directly to the backend. This might save some runtime in one|-|pass workflows. This feature is currently not -meant for production. +meant for production and we might come up with a better implementation. \stopchapter diff --git a/Master/texmf-dist/doc/luatex/base/luatex-callbacks.tex b/Master/texmf-dist/doc/luatex/base/luatex-callbacks.tex index aa6f9ed8a2d..37213eb7343 100644 --- a/Master/texmf-dist/doc/luatex/base/luatex-callbacks.tex +++ b/Master/texmf-dist/doc/luatex/base/luatex-callbacks.tex @@ -397,16 +397,15 @@ end The string reports the group code. From this you can deduce from what list you can give a treat. -\starttabulate -\NC \bf group codes \NC \bf pointer \NC \NR -\HL -\NC\type {pre_box} \NC \type {contrib_head} \NC \NR -\NC\type {pre_adjust_tail} \NC \type {pre_adjust_head} \NC \NR -\NC\type {just} \NC \type {just_box} \NC \NR -\NC\type {adjust_tail} \NC \type {adjust_head} \NC \NR +\starttabulate[|lT|p|] +\NC \rmbf value \NC \bf explanation \NC \NR +\NC pre_box \NC interline material is being added \NC \NR +\NC pre_adjust \NC \type {\vadjust} material is being added \NC \NR +\NC box \NC a typeset box is being added (always called) \NC \NR +\NC adjust \NC \type {\vadjust} material is being added \NC \NR \stoptabulate -\subsection{\type {buildpage_filter} and \type {contribute_filter}} +\subsection{\type {buildpage_filter}} This callback is called whenever \LUATEX\ is ready to move stuff to the main vertical list. You can use this callback to do specialized manipulation of the @@ -422,7 +421,7 @@ state is with respect to the \quote {current page}. The possible values for the \type {buildpage_filter} callback are: \starttabulate[|lT|p|] -\NC \ssbf value \NC \bf explanation \NC \NR +\NC \rmbf value \NC \bf explanation \NC \NR \NC alignment \NC a (partial) alignment is being added \NC \NR \NC after_output \NC an output routine has just finished \NC \NR \NC new_graf \NC the beginning of a new paragraph \NC \NR @@ -435,19 +434,32 @@ state is with respect to the \quote {current page}. The possible values for the \NC end \NC \LUATEX\ is terminating (it's all over) \NC \NR \stoptabulate -And for the \type {contribute_filter} called in the post line break handler -we have four cases (three are only called when there is a need for it). +\subsection{\type {build_page_insert}} + +This callback is called when the pagebuilder adds an insert. There is not much +control over this mechanism but this callback permits some last minute +manipulations of the spacing before an insert, something that might be handy when +for instance multiple inserts (types) are appended in a row. + +\startfunctioncall +function(<number> n, <number> i) + return <number> register +end +\stopfunctioncall + +with \starttabulate[|lT|p|] -\NC \ssbf value \NC \bf explanation \NC \NR -\NC pre_box \NC interline material is being added \NC \NR -\NC pre_adjust \NC \type {\vadjust} material is being added \NC \NR -\NC box \NC a typeset box is being added (always called) \NC \NR -\NC adjust \NC \type {\vadjust} material is being added \NC \NR +\NC \rmbf value \NC \bf explanation \NC \NR +\NC n \NC the insert class \NC \NR +\NC i \NC the order of the insert \NC \NR \stoptabulate -Just before the \type {box} related call we have a callout to the \type -{append_to_vlist_filter}. These callbacks do not replace any internal code. +The return value is a number indicating the skip register to use for the +prepended spacing. This permits for instance a different top space (when \type +{i} equals one) and intermediate space (when \type {i} is larger than one). Of course +you can mess with the insert box but you need to make sure that \LUATEX\ is happy +afterwards. \subsection{\type {pre_linebreak_filter}} @@ -467,7 +479,7 @@ for the \type {hpack_filter} and \type {vpack_filter} callbacks that will be explained in the next two paragraphs. \starttabulate[|lT|p|] -\NC \ssbf value \NC \bf explanation \NC \NR +\NC \rmbf value \NC \bf explanation \NC \NR \NC <empty> \NC main vertical list \NC \NR \NC hbox \NC \type {\hbox} in horizontal mode \NC \NR \NC adjusted_hbox \NC \type {\hbox} in vertical mode \NC \NR @@ -852,6 +864,17 @@ end This callback replaces the code that prints \LUATEX's when a file is closed like the \type {)} for regular files. +\subsection{\type {call_edit}} + +\startfunctioncall +function(filename,linenumber) +end +\stopfunctioncall + +This callback replaces the call to an external editor when \quote{E} is pressed +in reply to an error message. Processing will end immediately after the callback +returns control to the main program. + \section{PDF-related callbacks} \subsection{\type {finish_pdffile}} diff --git a/Master/texmf-dist/doc/luatex/base/luatex-enhancements.tex b/Master/texmf-dist/doc/luatex/base/luatex-enhancements.tex index 35c27cfb601..19f88234a53 100644 --- a/Master/texmf-dist/doc/luatex/base/luatex-enhancements.tex +++ b/Master/texmf-dist/doc/luatex/base/luatex-enhancements.tex @@ -736,7 +736,7 @@ This primitive is still experimental but can be used to assign a meaning to an a character, as in: \starttyping -\def\foo{bar} \letcharcode123\foo +\def\foo{bar} \letcharcode123=\foo \stoptyping This can be a bit nicer that using the uppercase tricks (using the property of @@ -759,6 +759,13 @@ the acceptable range is from 0 to 65535. These three primitives are like \type {\vbox}, \type {\hbox} and \type {\vtop} but don't apply the related callbacks. +\subsection{\type {\vsplit}} + +The \type {\vsplit} primitive has to be followed by a specification of the +required 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{Images and Forms} These two concepts are now core concepts and no longer whatsits. They are in fact @@ -794,6 +801,12 @@ optional parameters are not implemented for \type {\saveboxresource}. \useboxresource width 20mm height 10mm depth 5mm \lastsavedboxresourceindex \stoptyping +The box resources are of course implemented in the backend and therefore we do +support the \type {attr} and \type {resources} keys that accept a token list. New +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{\type {\nohrule} and \type {\novrule}} Because introducing a new keyword can cause incompatibilities, two new primitives diff --git a/Master/texmf-dist/doc/luatex/base/luatex-fontloader.tex b/Master/texmf-dist/doc/luatex/base/luatex-fontloader.tex index 43a4f4a46c0..7f7a6fc493a 100644 --- a/Master/texmf-dist/doc/luatex/base/luatex-fontloader.tex +++ b/Master/texmf-dist/doc/luatex/base/luatex-fontloader.tex @@ -1063,4 +1063,6 @@ reversecoverage: \NC replacements \NC string \NC \NC \NR \stoptabulate +\stopchapter + \stopcomponent diff --git a/Master/texmf-dist/doc/luatex/base/luatex-fonts.tex b/Master/texmf-dist/doc/luatex/base/luatex-fonts.tex index 7384f3b3ecc..221c0ce852c 100644 --- a/Master/texmf-dist/doc/luatex/base/luatex-fonts.tex +++ b/Master/texmf-dist/doc/luatex/base/luatex-fonts.tex @@ -36,7 +36,9 @@ The top|-|level keys in the table are as follows: \NC fonts \NC yes \NC no \NC yes \NC table \NC locally used fonts \NC \NR \NC psname \NC no \NC no \NC yes \NC string \NC This is the \POSTSCRIPT\ fontname in the incoming font source, and it's used as fontname identifier in the \PDF\ - output. \NC \NR + output. This has to be a valid string, e.g.\ no spaces + and such, as the backend will not do a cleanup. This gives + complete control to the loader. \NC \NR \NC fullname \NC no \NC no \NC yes \NC string \NC output font name, used as a fallback in the \PDF\ output if the \type {psname} is not set \NC \NR \NC header \NC yes \NC no \NC no \NC string \NC header comments, if any \NC \NR @@ -75,6 +77,8 @@ The top|-|level keys in the table are as follows: \NC nomath \NC no \NC no \NC yes \NC boolean\NC This key allows a minor speedup for text fonts. If it is present and true, then \LUATEX\ will not check the character entries for math|-|specific keys. \NC \NR +\NC oldmath \NC no \NC no \NC yes \NC boolean\NC This key flags a font as representing an old school \TEX\ + math font and disables the \OPENTYPE\ code path. \NC \NR \NC slant \NC no \NC no \NC yes \NC number \NC This has the same semantics as the \type {SlantFont} operator in font map files. \NC \NR \NC extent \NC no \NC no \NC yes \NC number \NC This has the same semantics as the \type {ExtendFont} diff --git a/Master/texmf-dist/doc/luatex/base/luatex-graphics.tex b/Master/texmf-dist/doc/luatex/base/luatex-graphics.tex index 91feaaff8ec..916d962b2ac 100644 --- a/Master/texmf-dist/doc/luatex/base/luatex-graphics.tex +++ b/Master/texmf-dist/doc/luatex/base/luatex-graphics.tex @@ -109,7 +109,8 @@ user-supplied and automatic ones. in multiples of 90~deg. \NC \NR \NC stream \NC string \NC the raw stream data for an \type {/Xobject} \type {/Form} object\NC \NR -\NC transform \NC number \NC the image transform, integer number 0..7\NC \NR +\NC transform \NC number \NC the image transform, integer number 0..7 \NC \NR +\NC orientation \NC number \NC the (jpeg) image orientation, integer number 1..8 (0 for unset) \NC \NR \NC width \NC number \NC the image width for \LUATEX \NC \NR \NC xres \NC number \NC the horizontal natural image resolution (in \DPI) \NC \NR @@ -316,11 +317,15 @@ of different fields, as follows: \NC error_line \NC number \NC error line width \NC 79 \NC \NR \NC print_line \NC number \NC line length in ps output \NC 100 \NC \NR \NC random_seed \NC number \NC the initial random seed \NC variable \NC \NR -\NC interaction \NC string \NC the interaction mode, - one of +\NC math_mode \NC string \NC the number system to use: + \type {double}, + \type {scaled}, + \type {binary} or + \type {decimal} \NC \type {scaled} \NC \NR +\NC interaction \NC string \NC the interaction mode: \type {batch}, \type {nonstop}, - \type {scroll}, + \type {scroll} or \type {errorstop} \NC \type {errorstop} \NC \NR \NC job_name \NC string \NC \type {--jobname} \NC \type {mpout} \NC \NR \NC find_file \NC function \NC a function to find files \NC only local files \NC \NR diff --git a/Master/texmf-dist/doc/luatex/base/luatex-introduction.tex b/Master/texmf-dist/doc/luatex/base/luatex-introduction.tex index 8ab8b4463df..196a9af4ffa 100644 --- a/Master/texmf-dist/doc/luatex/base/luatex-introduction.tex +++ b/Master/texmf-dist/doc/luatex/base/luatex-introduction.tex @@ -98,6 +98,14 @@ code in \TEX\ engines (especially code that is not needed any longer). \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 \TEX live +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. + The \TEXLIVE\ version is to be considered the current stable version. Any version between the yearly \TEXLIVE\ releases are to be considered beta. The beta releases are normally available via the \CONTEXT\ distribution channels (the @@ -112,8 +120,10 @@ Taco Hoekwater \& Luigi Scarso \starttabulate \NC Version \EQ \currentdate \NC \NR -\NC \LUATEX \EQ Snapshot \number\luatexversion.\luatexrevision \NC \NR -\NC \CONTEXT \EQ \contextversion \NC \NR +\NC \LUATEX \EQ version \cldcontext{status.luatex_version/100}, + revision \cldcontext{status.luatex_revision}, + number \cldcontext{environment.luatexversion} \NC \NR +\NC \CONTEXT \EQ MkIV \contextversion \NC \NR \stoptabulate \stopchapter diff --git a/Master/texmf-dist/doc/luatex/base/luatex-languages.tex b/Master/texmf-dist/doc/luatex/base/luatex-languages.tex index 19e3f7b1458..990a8dcc038 100644 --- a/Master/texmf-dist/doc/luatex/base/luatex-languages.tex +++ b/Master/texmf-dist/doc/luatex/base/luatex-languages.tex @@ -147,6 +147,38 @@ hyphenation happens is (normally) when the paragraph or a horizontal box is constructed. When \type {\savinghyphcodes} was zero when the language got initialized you start out with nothing, otherwise you already have a set. +When a \type {\hjcode} is larger than $0$ but smaller than $32$ is indicates the +to be used length. In the following example we map a character (\type {x}) onto +another one in the patterns and tell the engine that \type {œ} counts as one +character. Because traditionally zero itself is reserved for inhibiting +hyphenation, a value of $32$ counts as zero. + +\starttyping +% assuming french patterns: +foobar % foo-bar + +\hjcode`x=`o + +fxxbar % fxx-bar + +\lefthyphenmin3 + +œdipus % œdi-pus + +\lefthyphenmin4 + +œdipus % œdipus + +\hjcode`œ=2 + +œdipus % œdi-pus + +\hjcode`i=32 +\hjcode`d=32 + +œdipus % œdipus +\stoptyping + Carrying all this information with each glyph would give too much overhead and also make the process of setting up thee codes more complex. A solution with \type {hjcode} sets was considered but rejected because in practice the current @@ -180,6 +212,59 @@ as trigger. Here are a few examples of usage: \stopbuffer \typebuffer \start \dontcomplain \hsize 1pt \getbuffer \par \stop +We only accept an explicit hyphen when there is a preceding glyph and we skip a +sequence of explicit hyphens as that normally indicates a \type {--} or \type +{---} ligature in which case we can in a worse case usage get bad node lists +later on due to messed up ligature building as these dashes are ligatures in base +fonts. This is a side effect of the separating the hyphenation, ligaturing and +kerning steps. + +The start and end of a characters is signalled by a glue, penalty, kern or boundary +node. But by default also a hlist, vlist, rule, dir, whatsit, ins, and adjust node +indicate a start or end. You can omit the last set from the test by setting +\type {\hyphenationbounds} to a non|-|zero value: + +\starttabulate[|Tl|l|] +\NC 0 \NC not strict \NC \NR +\NC 1 \NC strict start \NC \NR +\NC 2 \NC strict end \NC \NR +\NC 3 \NC strict start and strict end \NC \NR +\stoptabulate + +The word start is determined as follows: + +\starttabulate[|Bl|l|] +\NC boundary \NC yes when wordboundary \NC \NR +\NC hlist \NC when hyphenationbounds 1 or 3 \NC \NR +\NC vlist \NC when hyphenationbounds 1 or 3 \NC \NR +\NC rule \NC when hyphenationbounds 1 or 3 \NC \NR +\NC dir \NC when hyphenationbounds 1 or 3 \NC \NR +\NC whatsit \NC when hyphenationbounds 1 or 3 \NC \NR +\NC glue \NC yes \NC \NR +\NC math \NC skipped \NC \NR +\NC glyph \NC exhyphenchar (one only) : yes (so no -- ---) \NC \NR +\NC otherwise \NC yes \NC \NR +\stoptabulate + +The word end is determined as follows: + +\starttabulate[|Bl|l|] +\NC boundary \NC yes \NC \NR +\NC glyph \NC yes when different language \NC \NR +\NC glue \NC yes \NC \NR +\NC penalty \NC yes \NC \NR +\NC kern \NC yes when not italic (for some historic reason) \NC \NR +\NC hlist \NC when hyphenationbounds 2 or 3 \NC \NR +\NC vlist \NC when hyphenationbounds 2 or 3 \NC \NR +\NC rule \NC when hyphenationbounds 2 or 3 \NC \NR +\NC dir \NC when hyphenationbounds 2 or 3 \NC \NR +\NC whatsit \NC when hyphenationbounds 2 or 3 \NC \NR +\NC ins \NC when hyphenationbounds 2 or 3 \NC \NR +\NC adjust \NC when hyphenationbounds 2 or 3 \NC \NR +\stoptabulate + +(Future versions of \LUATEX\ might provide more granularity.) + \section{The main control loop} In \LUATEX's main loop, almost all input characters that are to be typeset are @@ -260,6 +345,34 @@ character|-|handling code have been moved back inline. When \type {\tracingcommands} is on, this is visible because the full word is reported, instead of just the initial character. +Because we tend to make hard codes behaviour configurable a few new primitives +have been added: + +\starttyping +\hyphenpenaltymode +\automatichyphenpenalty +\explicithyphenpenalty +\stoptyping + +The first parameter has the following consequences for automatic discs (the ones +resulting from an \type {\exhyphenchar}: + +\starttabulate[|Tc|l|l|] +\BC mode \BC automatic disc \type{-} \BC explicit disc \type{\-} \NC \NR +\HL +\NC 0 \NC \type {\exhyphenpenalty} \NC \type {\exhyphenpenalty} \NC \NR +\NC 1 \NC \type {\hyphenpenalty} \NC \type {\hyphenpenalty} \NC \NR +\NC 2 \NC \type {\exhyphenpenalty} \NC \type {\hyphenpenalty} \NC \NR +\NC 3 \NC \type {\hyphenpenalty} \NC \type {\exhyphenpenalty} \NC \NR +\NC 4 \NC \type {\automatichyphenpenalty} \NC \type {\explicithyphenpenalty} \NC \NR +\NC 5 \NC \type {\exhyphenpenalty} \NC \type {\explicithyphenpenalty} \NC \NR +\NC 6 \NC \type {\hyphenpenalty} \NC \type {\explicithyphenpenalty} \NC \NR +\NC 7 \NC \type {\automatichyphenpenalty} \NC \type {\exhyphenpenalty} \NC \NR +\NC 8 \NC \type {\automatichyphenpenalty} \NC \type {\hyphenpenalty} \NC \NR +\stoptabulate + +other values do what we always did in \LUATEX: insert \type {\exhyphenpenalty}. + \section[patternsexceptions]{Loading patterns and exceptions} The hyphenation algorithm in \LUATEX\ is quite different from the one in \TEX82, @@ -703,3 +816,17 @@ initialized due to \type {\savinghyphcodes} being larger than zero. \stopchapter \stopcomponent + +% \parindent0pt \hsize=1.1cm +% 12-34-56 \par +% 12-34-\hbox{56} \par +% 12-34-\vrule width 1em height 1.5ex \par +% 12-\hbox{34}-56 \par +% 12-\vrule width 1em height 1.5ex-56 \par +% \hjcode`\1=`\1 \hjcode`\2=`\2 \hjcode`\3=`\3 \hjcode`\4=`\4 \vskip.5cm +% 12-34-56 \par +% 12-34-\hbox{56} \par +% 12-34-\vrule width 1em height 1.5ex \par +% 12-\hbox{34}-56 \par +% 12-\vrule width 1em height 1.5ex-56 \par + diff --git a/Master/texmf-dist/doc/luatex/base/luatex-lua.tex b/Master/texmf-dist/doc/luatex/base/luatex-lua.tex index 79c4e08ed6b..0960f803206 100644 --- a/Master/texmf-dist/doc/luatex/base/luatex-lua.tex +++ b/Master/texmf-dist/doc/luatex/base/luatex-lua.tex @@ -56,44 +56,32 @@ similar fashion as the other \TEX\ engines. Some options are accepted but have n consequence. The following command|-|line options are understood: \starttabulate[|lT|p|] +\NC --credits \NC display credits and exit \NC \NR +\NC --debug-format \NC enable format debugging \NC \NR +\NC --draftmode \NC switch on draft mode i.e.\ generate no output in \PDF\ mode \NC \NR +\NC --[no-]file-line-error \NC disable/enable \type {file:line:error} style messages \NC \NR +\NC --[no-]file-line-error-style \NC aliases of \type {--[no-]file-line-error} \NC \NR \NC --fmt=FORMAT \NC load the format file \type {FORMAT} \NC\NR -\NC --lua=FILE \NC load and execute a \LUA\ initialization script\NC\NR -\NC --safer \NC disable easily exploitable \LUA\ commands \NC\NR -\NC --nosocket \NC disable the \LUA\ socket library \NC\NR +\NC --halt-on-error \NC stop processing at the first error\NC \NR \NC --help \NC display help and exit \NC\NR \NC --ini \NC be \type {iniluatex}, for dumping formats \NC\NR -\NC --interaction=STRING \NC set interaction mode: \type {batchmode}, \type {nonstopmode}, - \type {scrollmode} or \type {errorstopmode} \NC \NR -\NC --halt-on-error \NC stop processing at the first error\NC \NR -\NC --kpathsea-debug=NUMBER \NC set path searching debugging flags according to - the bits of \type {NUMBER} \NC \NR +\NC --interaction=STRING \NC set interaction mode: \type {batchmode}, \type {nonstopmode}, \type {scrollmode} or \type {errorstopmode} \NC \NR +\NC --jobname=STRING \NC set the job name to \type {STRING} \NC \NR +\NC --kpathsea-debug=NUMBER \NC set path searching debugging flags according to the bits of \type {NUMBER} \NC \NR +\NC --lua=FILE \NC load and execute a \LUA\ initialization script \NC\NR +\NC --[no-]mktex=FMT \NC disable/enable \type {mktexFMT} generation with \type {FMT} is \type {tex} or \type {tfm} \NC \NR +\NC --nosocket \NC disable the \LUA\ socket library \NC\NR +\NC --output-comment=STRING \NC use \type {STRING} for \DVI\ file comment instead of date (no effect for \PDF) \NC \NR +\NC --output-directory=DIR \NC use \type {DIR} as the directory to write files to \NC \NR +\NC --output-format=FORMAT \NC use \type {FORMAT} for job output; \type {FORMAT} is \type {dvi} or \type {pdf} \NC \NR \NC --progname=STRING \NC set the program name to \type {STRING} \NC \NR -\NC --version \NC display version and exit \NC \NR -\NC --credits \NC display credits and exit \NC \NR \NC --recorder \NC enable filename recorder \NC \NR -\NC --output-comment=STRING \NC use \type {STRING} for \DVI\ file comment - instead of date (no effect for \PDF) \NC \NR -\NC --output-directory=DIR \NC use \type {DIR} as the directory to write - files to \NC \NR -\NC --draftmode \NC switch on draft mode i.e.\ generate no - output in \PDF\ mode \NC \NR -\NC --output-format=FORMAT \NC use \type {FORMAT} for job output; \type - {FORMAT} is \type {dvi} or \type {pdf} \NC - \NR +\NC --safer \NC disable easily exploitable \LUA\ commands \NC\NR \NC --[no-]shell-escape \NC disable/enable system calls \NC \NR -\NC --enable-write18 \NC enable system calls \NC \NR -\NC --disable-write18 \NC disable system calls \NC \NR -\NC --shell-restricted \NC restrict system calls to a list of commands - given in \type {texmf.cnf} \NC \NR -\NC --debug-format \NC enable format debugging \NC \NR -\NC --[no-]file-line-error \NC disable/enable \type {file:line:error} style - messages \NC \NR -\NC --[no-]file-line-error-style \NC aliases of \type {--[no-]file-line-error} \NC \NR -\NC --jobname=STRING \NC set the job name to \type {STRING} \NC \NR -\NC --[no-]mktex=FMT \NC disable/enable \type {mktexFMT} generation - with \type {FMT} is \type {tex} or \type - {tfm} \NC \NR +\NC --shell-restricted \NC restrict system calls to a list of commands given in \type {texmf.cnf} \NC \NR \NC --synctex=NUMBER \NC enable \type {synctex} \NC \NR +\NC --utc \NC use utc times when applicable \NC \NR +\NC --version \NC display version and exit \NC \NR \stoptabulate Some of the traditional flags are just ignored: \type {--etex}, \type @@ -543,6 +531,42 @@ At some point (this also depends on distributions) \LUATEX\ might have these libraries loaded on demand. For this reason you can best use \type {require} to make sure they are loaded. +\section{Testing} + +For development reasons you can influence the used startup date and time. This can +be done in two ways. + +\startitemize[n] + +\startitem + By setting the environmment variable \type {SOURCE_DATE_EPOCH}. This will + influence the \TEX\ parameters \type {time} and \type {date}, the random seed, + the \PDF\ timestamp and the \PDF\ id that is derived from the time as well. This + variable is consulted when the \KPSE\ library is enabled. Resolving is + delegated to this library. +\stopitem + +\startitem + By setting the \type {start_time} variable in the \type {texconfig} table; as + with other variables we use the internal name there. For compatibility + reasons we also honour a \type {SOURCE_DATE_EPOCH} entry. It should be noted + that there are no such variables in other engines and this method is only + relevant in case the while setup happens in \LUA. +\stopitem + +\stopitemize + +When Universal Time is needed, you can pass the flag \type {utc} to the engine. This +property also works when the date and time are set by \LUATEX\ itself. It has a +complementary entry \type {use_utc_time} in the \type {texconfig} table. + +{\em To some extend a cleaner solution would be to have a flag that disables all +variable data in one go (like filenames and so) but we just follow the method +implemented in \PDFTEX\ where primitives are used to influence other properties.} + +{\em In \CONTEXT\ we provide the command line argument \type {--nodates} that +does bit more disabling of dates.} + \stopchapter \stopcomponent diff --git a/Master/texmf-dist/doc/luatex/base/luatex-math.tex b/Master/texmf-dist/doc/luatex/base/luatex-math.tex index cb8d198b1fc..3c29d960975 100644 --- a/Master/texmf-dist/doc/luatex/base/luatex-math.tex +++ b/Master/texmf-dist/doc/luatex/base/luatex-math.tex @@ -38,6 +38,99 @@ be used as numeric values, so you can write code like this: \fi \fi \stoptyping +Sometimes you won't get what you expect so a bit of explanation might help to +understand what happens. When math is parsed and expanded it gets turned into a +linked list. In a second pass the formula will be build. This has to do with the +fact that in order to determine the automatically chosen sizes (in for instance +fractions) following content can influence preceding sizes. A side effect of this +is for instance that one cannot change the definition of a font family (and +thereby reusing numbers) because the number that got used is stored and used in +the second pass (so changing \type {\fam 12} mid|-|formula spoils over to +preceding use of that family). + +The style switching primitives like \type {\textstyle} are turned into nodes so +the styles set there are frozen. The \type {\mathchoice} primitive results in +four lists being constructed of which one is used in the second pass. The fact +that some automatic styles are not yet known also means that the \type +{\mathstyle} primitive expands to the current style which can of course be +different from the one really used. It's a snapshot of the first pass state. As a +consequence in the following example you get a style number (first pass) typeset +that can actually differ from the used style (second pass). In the case of a math +choice used ungrouped, the chosen style is used after the choice too, unless you +group. + +\startbuffer[1] + [a:\mathstyle]\quad + \bgroup + \mathchoice + {\bf \scriptstyle (x:d :\mathstyle)} + {\bf \scriptscriptstyle (x:t :\mathstyle)} + {\bf \scriptscriptstyle (x:s :\mathstyle)} + {\bf \scriptscriptstyle (x:ss:\mathstyle)} + \egroup + \quad[b:\mathstyle]\quad + \mathchoice + {\bf \scriptstyle (y:d :\mathstyle)} + {\bf \scriptscriptstyle (y:t :\mathstyle)} + {\bf \scriptscriptstyle (y:s :\mathstyle)} + {\bf \scriptscriptstyle (y:ss:\mathstyle)} + \quad[c:\mathstyle]\quad + \bgroup + \mathchoice + {\bf \scriptstyle (z:d :\mathstyle)} + {\bf \scriptscriptstyle (z:t :\mathstyle)} + {\bf \scriptscriptstyle (z:s :\mathstyle)} + {\bf \scriptscriptstyle (z:ss:\mathstyle)} + \egroup + \quad[d:\mathstyle] +\stopbuffer + +\startbuffer[2] + [a:\mathstyle]\quad + \begingroup + \mathchoice + {\bf \scriptstyle (x:d :\mathstyle)} + {\bf \scriptscriptstyle (x:t :\mathstyle)} + {\bf \scriptscriptstyle (x:s :\mathstyle)} + {\bf \scriptscriptstyle (x:ss:\mathstyle)} + \endgroup + \quad[b:\mathstyle]\quad + \mathchoice + {\bf \scriptstyle (y:d :\mathstyle)} + {\bf \scriptscriptstyle (y:t :\mathstyle)} + {\bf \scriptscriptstyle (y:s :\mathstyle)} + {\bf \scriptscriptstyle (y:ss:\mathstyle)} + \quad[c:\mathstyle]\quad + \begingroup + \mathchoice + {\bf \scriptstyle (z:d :\mathstyle)} + {\bf \scriptscriptstyle (z:t :\mathstyle)} + {\bf \scriptscriptstyle (z:s :\mathstyle)} + {\bf \scriptscriptstyle (z:ss:\mathstyle)} + \endgroup + \quad[d:\mathstyle] +\stopbuffer + +\typebuffer[1] + +% \typebuffer[2] + +This gives: + +\blank $\displaystyle \getbuffer[1]$ \blank +\blank $\textstyle \getbuffer[1]$ \blank + +Using \type {\begingroup} \unknown\ \type {\endgroup} instead gives: + +\blank $\displaystyle \getbuffer[2]$ \blank +\blank $\textstyle \getbuffer[2]$ \blank + +This might look wrong but it's just a side effect of \type {\mathstyle} expanding +to the current (first pass) style and the number being injected in the list that +gets converted in the second pass. It all makes sense and it illustrates the +importance of grouping. In fact, the math choice style being effective afterwards +has advantages. It would be hard to get it otherwise. + \subsection{\type {\Ustack}} There are a few math commands in \TEX\ where the style that will be used is not @@ -174,7 +267,7 @@ are described as follows: \startitemize \startitem In any style superscripts and subscripts are taken from the next smaller style. - Exception: in display style they are taken in script style. + Exception: in display style they are in script style. \stopitem \startitem Subscripts are always in the cramped variant of the style; superscripts are only @@ -314,7 +407,7 @@ needed. The injection of \type {\abovedisplayskip} and \type {\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 later mkes it sometimes hard +only inserted when larger than zero. Especially the later makes it sometimes hard to fully control spacing. Therefore \LUATEX\ comes with a new directive: \type {\mathdisplayskipmode}. The following values apply: @@ -464,6 +557,86 @@ 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} + +There are two extra math parameters \type {\Umathnolimitsupfactor} and \type +{\Umathnolimitsubfactor} that were added to provide some control over how limits +are spaced (for example the position of super and subscripts after integral +operators). They relate to an extra parameter \type {\mathnolimitsmode}. The half +corrections are what happens when scripts are placed on above and below. The +problem with italic corrections is that officially that correction italic is used +for above|/|below placement while advanced kerns are used for placement at the +right end. The question is: how often is this implemented, and if so, does the +kerns assume correction too. Anyway, with this parameter one can control it. + +\starttabulate[|l|ck1|ck1|ck1|ck1|ck1|ck1|] + \NC + \NC \mathnolimitsmode0 $\displaystyle\int\nolimits^0_1$ + \NC \mathnolimitsmode1 $\displaystyle\int\nolimits^0_1$ + \NC \mathnolimitsmode2 $\displaystyle\int\nolimits^0_1$ + \NC \mathnolimitsmode3 $\displaystyle\int\nolimits^0_1$ + \NC \mathnolimitsmode4 $\displaystyle\int\nolimits^0_1$ + \NC \mathnolimitsmode8000 $\displaystyle\int\nolimits^0_1$ + \NC \NR + \TB + \NC \bf mode + \NC \tttf 0 + \NC \tttf 1 + \NC \tttf 2 + \NC \tttf 3 + \NC \tttf 4 + \NC \tttf 8000 + \NC \NR + \NC \bf superscript + \NC 0 + \NC font + \NC 0 + \NC 0 + \NC +ic/2 + \NC 0 + \NC \NR + \NC \bf subscript + \NC -ic + \NC font + \NC 0 + \NC -ic/2 + \NC -ic/2 + \NC 8000ic/1000 + \NC \NR +\stoptabulate + +When the mode is set to one, the math parameters are used. This way a macro +package writer can decide what looks best. Given the current state of fonts in +\CONTEXT\ we currently use mode 1 with factor 0 for the superscript and 750 for +the subscripts. Positive values are used for both parameters but the subscript +shifts to the left. A \type {\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} + +The \type {\mathitalicsmode} parameter can be set to~1 to force italic correction +before noads that represent some more complex structure (read: everything +that is not an ord, bin, rel, open, close, punct or inner). + +\starttexdefinition Whatever #1 + \NC \type{\mathitalicsmode=#1} + \NC \mathitalicsmode#1\ruledhbox{$\left|T^1\right|$} + \NC \mathitalicsmode#1\ruledhbox{$\left|T\right|$} + \NC \mathitalicsmode#1\ruledhbox{$T+1$} + \NC \mathitalicsmode#1\ruledhbox{$T{1\over2}$} + \NC \mathitalicsmode#1\ruledhbox{$T\sqrt{1}$} + \NR \NR +\stoptexdefinition + +\starttabulate[|c|c|c|c|c|c|] + \Whatever0 + \Whatever1 +\stoptabulate + +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{Math spacing setting} Besides the parameters mentioned in the previous sections, there are also 64 new @@ -603,7 +776,7 @@ correction takes place. Possible locations are \type {top}, \type {bottom}, \type {both} and \type {center}. When no location is given \type {top} is assumed. An additional parameter \type {fraction} can be specified followed by a number; a value of for -instance 1200 means that the criterium is 1.2 times the width of the nuclues. The +instance 1200 means that the criterium is 1.2 times the width of the nucleus. The fraction only applies to the stepwise selected shapes and is mostly meant for the \type {overlay} location. It also works for the other locations but then it concerns the width. @@ -831,12 +1004,34 @@ For Latin Modern The result looks as follows: \stoptabulate \stop +\section {Last lines} + +There is a new primitive to control the overshoot in the calculation of the +previous line in mid|-|paragraph display math. The default value is 2 times +the em width of the current font: + +\starttyping +\predisplaygapfactor=2000 +\stoptyping + +If you want to have the length of the last line independent of math i.e.\ you don't +want to revert to a hack where you insert a fake display math formula in order to +get the length of the last line, the following will often work too: + +\starttyping +\def\lastlinelength{\dimexpr + \directlua {tex.sprint ( + (nodes.dimensions(node.tail(tex.lists.page_head).list)) + )}sp +\relax} +\stoptyping + \section {Other Math changes} \subsection {Verbose versions of single-character math commands} \LUATEX\ defines six new primitives that have the same function as -\type {^}, \type {_}, \type {$}, and \type {$$}: %$ +\type {^}, \type {_}, \type {$}, and \type {$$}: \starttabulate[|l|l|l|l|] \NC \bf primitive \NC \bf explanation \NC \NR @@ -869,7 +1064,57 @@ Inline math is surrounded by (optional) \type {\mathsurround} spacing but that i dimension. There is now an additional parameter \type {\mathsurroundskip}. When set to a non|-|zero value (or zero with some stretch or shrink) this parameter will replace \type {\mathsurround}. By using an additional parameter instead of changing the nature -of \type {\mathsurround}, we can remain compatible. +of \type {\mathsurround}, we can remain compatible. In the meantime a bit more +control has been added via \type {\mathsurroundmode}. This directive can take 6 values +with zero being the default behaviour. + +\start + +\def\OneLiner#1#2% + {\NC #1 +% \NC \ruledhbox{\mathsurroundmode#1\relax\hsize 100pt x$x$x} +% \NC \ruledhbox{\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 \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[|Tc|c|c|pl|] +\HL +\BC mode \BC \type {x$x$x} \BC \type {x $x$ x} \BC effect \NC \NR +\HL +\OneLiner{0}{obey \type {\mathsurround} when \type {\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 \type {\mathsurround}} +\OneLiner{5}{disable all spacing around math} +\OneLiner{6}{only apply \type {\mathsurroundskip} when also spacing} +\OneLiner{7}{only apply \type {\mathsurroundskip} when no spacing} +\HL +\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 fance, 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} % @@ -980,6 +1225,21 @@ primitive \type {\mathoption} has been introduced (so that we don't end up with many new commands). The approach of options also permits us to see what effect a specific solution has. +\subsubsection {\type {\mathoption old}} + +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 seens as bugs as they relate to font +properties. + +\startbuffer +\mathoption old 1 +\stopbuffer + +The \type {oldmath} boolean flag in the \LUA\ font table is the official way to +force old treatment as it's bound to fonts. + \subsubsection {\type {\mathoption noitaliccompensation}} This option compensates placement for characters with a built|-|in italic diff --git a/Master/texmf-dist/doc/luatex/base/luatex-modifications.tex b/Master/texmf-dist/doc/luatex/base/luatex-modifications.tex index 0507a56e0fa..2857603ea0f 100644 --- a/Master/texmf-dist/doc/luatex/base/luatex-modifications.tex +++ b/Master/texmf-dist/doc/luatex/base/luatex-modifications.tex @@ -67,7 +67,19 @@ most still comes from the original. But we divert a bit. \stopitem \startitem - Magnification (\type {\mag}) is only supported in \DVI\ output mode. + Magnification (\type {\mag}) is only supported in \DVI\ output mode. You can + set this parameter and it even works with \type {true} units till you switch + to \PDF\ output mode. When you use \PDF\ output you can best not touch the + \type {\mag} variable. This fuzzy behaviour is not much different from using + \PDF\ backend related functionality while eventually \DVI\ output is + required. + + After the output mode has been frozen (normally that happens when the first + page is shipped out) or when \PDF\ output is enabled, the \type {true} + specification is ignored. When you preload a plain format adapted to + \LUATEX\ it can be that the \type {\mag} parameter already has been set. +\stopitem + \stopitemize \stopsubsection @@ -514,7 +526,9 @@ different: \stopsubsection -\startsubsection[reference=backendprimitives,title=The backend primitives \type {\pdf*}] +\stopsection + +\startsection[reference=backendprimitives,title=The backend primitives \type {\pdf*}] In a previous section we mentioned that some \PDFTEX\ primitives were removed and others promoted to core \LUATEX\ primitives. That is only part of the story. In @@ -603,6 +617,7 @@ The configuration related registers have become: \edef\pdfinclusionerrorlevel {\pdfvariable inclusionerrorlevel} \edef\pdfignoreunknownimages {\pdfvariable ignoreunknownimages} \edef\pdfgentounicode {\pdfvariable gentounicode} +\edef\pdfomitcidset {\pdfvariable omitcidset} \edef\pdfpagebox {\pdfvariable pagebox} \edef\pdfminorversion {\pdfvariable minorversion} \edef\pdfuniqueresname {\pdfvariable uniqueresname} @@ -662,6 +677,7 @@ the defaults; these are: \pdfinclusionerrorlevel 0 \pdfignoreunknownimages 0 \pdfgentounicode 0 +\pdfomitcidset 0 \pdfpagebox 0 \pdfminorversion 4 \pdfuniqueresname 0 @@ -765,7 +781,348 @@ normally generated by the engine: So, you even need to include the brackets! -\stopsubsection +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. + +\starttexsyntax +\pdfextension literal + [ direct | page | raw ] { tokens } +\stoptexsyntax + +\starttexsyntax +\pdfextension dest + num integer | name { tokens }!crlf + [ fitbh | fitbv | fitb | fith| fitv | fit | + fitr <rule spec> | xyz [ zoom <integer> ] +\stoptexsyntax + +\starttexsyntax +\pdfextension annot + reserveobjnum | useobjnum <integer> + { tokens } +\stoptexsyntax + +\starttexsyntax +\pdfextension save +\stoptexsyntax + +\starttexsyntax +\pdfextension restore +\stoptexsyntax + +\starttexsyntax +\pdfextension setmatrix + { tokens } +\stoptexsyntax + +\starttexsyntax +[ \immediate ] \pdfextension obj + reserveobjnum +\stoptexsyntax + +\starttexsyntax +[ \immediate ] \pdfextension obj + [ useobjnum <integer> ] + [ uncompressed ] + [ stream [ attr { tokens } ] ] + [ file ] + { tokens } +\stoptexsyntax + +\starttexsyntax +\pdfextension refobj + <integer> +\stoptexsyntax + +\starttexsyntax +\pdfextension colorstack + <integer> + set { tokens } | push { tokens } | pop | current +\stoptexsyntax + +\starttexsyntax +\pdfextension startlink + [ attr { tokens } ] + user { tokens } | goto | thread + [ file { tokens } ] + [ page <integer> { tokens } | name { tokens } | num integer ] + [ newwindow | nonewwindow ] +\stoptexsyntax + +\starttexsyntax +\pdfextension endlink +\stoptexsyntax + +\starttexsyntax +\pdfextension startthread + num <integer> | name { tokens } +\stoptexsyntax + +\starttexsyntax +\pdfextension endthread +\stoptexsyntax + +\starttexsyntax +\pdfextension thread + num <integer> | name { tokens } +\stoptexsyntax + +\starttexsyntax +\pdfextension outline + [ attr { tokens } ] + [ useobjnum <integer> ] + [ count <integer> ] + { tokens } +\stoptexsyntax + +\starttexsyntax +\pdfextension glyphtounicode + { tokens } + { tokens } +\stoptexsyntax + +\starttexsyntax +\pdfextension catalog + { tokens } + [ openaction + user { tokens } | goto | thread + [ file { tokens } ] + [ page <integer> { tokens } | name { tokens } | num <integer> ] + [ newwindow | nonewwindow ] ] +\stoptexsyntax + +\starttexsyntax +\pdfextension fontattr + <integer> + {tokens} +\stoptexsyntax + +\starttexsyntax +\pdfextension mapfile + {tokens} +\stoptexsyntax + +\starttexsyntax +\pdfextension mapline + {tokens} +\stoptexsyntax + +\starttexsyntax +\pdfextension includechars + {tokens} +\stoptexsyntax + +\starttexsyntax +\pdfextension info + {tokens} +\stoptexsyntax + +\starttexsyntax +\pdfextension names + {tokens} +\stoptexsyntax + +\starttexsyntax +\pdfextension trailer + {tokens} +\stoptexsyntax + +\stopsection + +\startsection[title=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 +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. + +This is what happens: + +\starttyping +\textdir TRT nur {\textdir TLT run \textdir TRT NUR} nur +\stoptyping + +This becomes stepwise: + +\startnarrower +\starttyping +injected: [+TRT]nur {[+TLT]run [+TRT]NUR} nur +balanced: [+TRT]nur {[+TLT]run [-TLT][+TRT]NUR[-TRT]} nur[-TRT] +result : run {RUNrun } run +\stoptyping +\stopnarrower + +And this: + +\starttyping +\textdir TRT nur {nur \textdir TLT run \textdir TRT NUR} nur +\stoptyping + +becomes: + +\startnarrower +\starttyping +injected: [+TRT]nur {nur [+TLT]run [+TRT]NUR} nur +balanced: [+TRT]nur {nur [+TLT]run [-TLT][+TRT]NUR[-TRT]} nur[-TRT] +result : run {run RUNrun } run +\stoptyping +\stopnarrower + +Now, in the following examples watch where we put the braces: + +\startbuffer +\textdir TRT nur {{\textdir TLT run} {\textdir TRT NUR}} nur +\stopbuffer + +\typebuffer + +This becomes: + +\startnarrower +\getbuffer +\stopnarrower + +Compare this to: + +\startbuffer +\textdir TRT nur {{\textdir TLT run }{\textdir TRT NUR}} nur +\stopbuffer + +\typebuffer + +Which renders as: + +\startnarrower +\getbuffer +\stopnarrower + +So how do we deal with the next? + +\startbuffer +\def\ltr{\textdir TLT\relax} +\def\rtl{\textdir TRT\relax} + +run {\rtl nur {\ltr run \rtl NUR \ltr run \rtl NUR} nur} +run {\ltr run {\rtl nur \ltr RUN \rtl nur \ltr RUN} run} +\stopbuffer + +\typebuffer + +It gets typeset as: + +\startnarrower +\startlines +\getbuffer +\stoplines +\stopnarrower + +We could define the two helpers to look back, pick up a skip, remove it and +inject it after the dir node. But that way we loose the subtype information that +for some applications can be handy to be kept as|-|is. This is why we now have a +variant of \type {\textdir} which injects the balanced node before the skip. +Instead of the previous definition we can use: + +\startbuffer[def] +\def\ltr{\linedir TLT\relax} +\def\rtl{\linedir TRT\relax} +\stopbuffer + +\typebuffer[def] + +and this time: + +\startbuffer[txt] +run {\rtl nur {\ltr run \rtl NUR \ltr run \rtl NUR} nur} +run {\ltr run {\rtl nur \ltr RUN \rtl nur \ltr RUN} run} +\stopbuffer + +\typebuffer[txt] + +comes out as a properly spaced: + +\startnarrower +\startlines +\getbuffer[def,txt] +\stoplines +\stopnarrower + +Anything more complex that this, like combination of skips and penalties, or +kerns, should be handled in the input or macro package because there is no way we +can predict the expected behaviour. In fact, the \type {\linedir} is just a +convenience extra which could also have been implemented using node list parsing. + +Another adaptation to the \ALEPH\ directional model is control over shapes driven +by \type {\hangindent} and \type {\parshape}. This is controlled by a new parameter +\type {\shapemode}: + +\starttabulate[|cTB|c|] +\NC \NC \bf \type {\hangindent} \NC \bf \type {\parshape} \NC \NR +\NC 0 \NC normal \NC normal \NC \NR +\NC 1 \NC mirrored \NC normal \NC \NR +\NC 2 \NC normal \NC mirrored \NC \NR +\NC 3 \NC mirrored \NC mirrored \NC \NR +\stoptabulate + +The value is reset to zero (like \type {\hangindent} and \type {\parshape}) +after the paragraph is done with. You can use negative values to preven t +this. + +In \in {figure} [fig:shapemode] a few examples are given. + +\startplacefigure[reference=fig:shapemode,title={The effect of \type {shapemode}.}] + \startcombination[2*3] + {\ruledvbox \bgroup \setuptolerance[verytolerant] + \hsize .45\textwidth \switchtobodyfont[6pt] + \pardir TLT \textdir TLT + \hangindent 40pt \hangafter -3 + \leftskip10pt \input tufte \par + \egroup} {TLT: hangindent} + {\ruledvbox \bgroup \setuptolerance[verytolerant] + \hsize .45\textwidth \switchtobodyfont[6pt] + \pardir TLT \textdir TLT + \parshape 4 0pt .8\hsize 10pt .8\hsize 20pt .8\hsize 0pt \hsize + \input tufte \par + \egroup} {TLT: parshape} + {\ruledvbox \bgroup \setuptolerance[verytolerant] + \hsize .45\textwidth \switchtobodyfont[6pt] + \pardir TRT \textdir TRT + \hangindent 40pt \hangafter -3 + \leftskip10pt \input tufte \par + \egroup} {TRT: hangindent mode 0} + {\ruledvbox \bgroup \setuptolerance[verytolerant] + \hsize .45\textwidth \switchtobodyfont[6pt] + \pardir TRT \textdir TRT + \parshape 4 0pt .8\hsize 10pt .8\hsize 20pt .8\hsize 0pt \hsize + \input tufte \par + \egroup} {TRT: parshape mode 0} + {\ruledvbox \bgroup \setuptolerance[verytolerant] + \hsize .45\textwidth \switchtobodyfont[6pt] + \shapemode=3 + \pardir TRT \textdir TRT + \hangindent 40pt \hangafter -3 + \leftskip10pt \input tufte \par + \egroup} {TRT: hangindent mode 1 & 3} + {\ruledvbox \bgroup \setuptolerance[verytolerant] + \hsize .45\textwidth \switchtobodyfont[6pt] + \shapemode=3 + \pardir TRT \textdir TRT + \parshape 4 0pt .8\hsize 10pt .8\hsize 20pt .8\hsize 0pt \hsize + \input tufte \par + \egroup} {TRT: parshape mode 2 & 3} + \stopcombination +\stopplacefigure \stopsection diff --git a/Master/texmf-dist/doc/luatex/base/luatex-nodes.tex b/Master/texmf-dist/doc/luatex/base/luatex-nodes.tex index 372aca1e58b..21f1789e5a9 100644 --- a/Master/texmf-dist/doc/luatex/base/luatex-nodes.tex +++ b/Master/texmf-dist/doc/luatex/base/luatex-nodes.tex @@ -201,6 +201,26 @@ its internal link structure is correct, otherwise an error may be result. The subtype numbers~4 and~5 belong to the \quote {of-f-ice} explanation given elsewhere. +These disc nodes are kind of special as at some point they also keep information +about breakpoints and nested ligatures. The \type {pre}, \type {post} and \type +{replace} fields at the \LUA\ end are in fact indirectly accessed and have a +\type {prev} pointer that is not \type {nil}. This means that when you mess +around with the head of these (three) lists, you also need to reassign them +because that will restore the proper \type {prev} pointer, so: + +\starttyping +pre = d.pre +-- change the list starting with pre +d.pre = pre +\stoptyping + +Otherwise you can end up with an invalid internal perception of reality and +\LUATEX\ might even decide to crash on you. It also means that running forward +over for instance \type {pre} is ok but backward you need to stop at \type {pre}. +And you definitely must not mess with the node that \type {prev} points to, if +only because it is not really an node but part of the disc data structure (so +freeing it again might crash \LUATEX). + \subsubsection{math nodes} \starttabulate[|lT|l|p|] @@ -512,6 +532,7 @@ into a single node type with separate subtypes for differentiation. \NC sup \NC kernel node \NC superscript \NC \NR \NC accent \NC kernel node \NC top accent \NC \NR \NC bot_accent \NC kernel node \NC bottom accent \NC \NR +\NC fraction \NC number \NC larger step criterium (divided by 1000) \NC \NR \stoptabulate \subsubsubsection{style nodes} @@ -536,9 +557,9 @@ a trailing \type {'} to signify \quote {cramped} styles. \NC scriptscript \NC node \NC list of scriptscriptsize alternatives \NC \NR \stoptabulate -A warning: never assign a node list to the display, text, script, or -scriptscript field unless you are sure its internal link structure is -correct, otherwise an error may be result. +Warning: never assign a node list to the \type {display}, \type {text}, \type +{script}, or \type {scriptscript} field unless you are sure its internal link +structure is correct, otherwise an error may be result. \subsubsubsection{radical nodes} @@ -551,11 +572,13 @@ correct, otherwise an error may be result. \NC sup \NC kernel node \NC superscript \NC \NR \NC left \NC delimiter node \NC \NC \NR \NC degree \NC kernel node \NC only set by \type {\Uroot} \NC \NR +\NC width \NC number \NC required width \NC \NR +\NC options \NC number \NC bitset of rendering options \NC \NR \stoptabulate -A warning: never assign a node list to the nucleus, sub, sup, left, or degree -field unless you are sure its internal link structure is correct, otherwise an -error may be result. +Warning: never assign a node list to the \type {nucleus}, \type {sub}, \type +{sup}, \type {left}, or \type {degree} field unless you are sure its internal +link structure is correct, otherwise an error may be result. \subsubsubsection{fraction nodes} @@ -566,11 +589,14 @@ error may be result. \NC num \NC kernel node \NC numerator \NC \NR \NC denom \NC kernel node \NC denominator \NC \NR \NC left \NC delimiter node \NC left side symbol \NC \NR -\NC right \NC delimiter node \NC right side symbol\NC \NR +\NC right \NC delimiter node \NC right side symbol \NC \NR +\NC middle \NC delimiter node \NC middle symbol \NC \NR +\NC options \NC number \NC bitset of rendering options \NC \NR \stoptabulate -A warning: never assign a node list to the num, or denom field unless you are -sure its internal link structure is correct, otherwise an error may be result. +Warning: never assign a node list to the \type {num}, or \type {denom} field +unless you are sure its internal link structure is correct, otherwise an error +may be result. \subsubsubsection{fence nodes} @@ -579,8 +605,16 @@ sure its internal link structure is correct, otherwise an error may be result. \NC subtype \NC number \NC \showsubtypes{fence} \NC \NR \NC attr \NC node \NC list of attributes \NC \NR \NC delim \NC delimiter node \NC delimiter specification \NC \NR +\NC italic \NC number \NC italic correction \NC \NR +\NC height \NC number \NC required height \NC \NR +\NC depth \NC number \NC required depth \NC \NR +\NC options \NC number \NC bitset of rendering options \NC \NR +\NC class \NC number \NC spacing related class \NC \NR \stoptabulate +Warning: some of these fields are used by the renderer and might get adapted in +the process. + \subsection{whatsit nodes} Whatsit nodes come in many subtypes that you can ask for by running @@ -595,7 +629,7 @@ Whatsit nodes come in many subtypes that you can ask for by running \stopluacode . % period -\subsubsection{front|-|end whatits} +\subsubsection{front|-|end whatsits} \subsubsubsection{open whatsits} @@ -625,7 +659,7 @@ Whatsit nodes come in many subtypes that you can ask for by running \NC stream \NC number \NC \TEX's stream id number \NC \NR \stoptabulate -\subsubsubsection{user_defined whatits} +\subsubsubsection{user_defined whatsits} 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 @@ -642,15 +676,18 @@ will simply step over such whatsits without ever looking at the contents. \NC \NC table \NC a \LUA\ table \NC \NR \stoptabulate -The \type {type} can have one of five distinct values: - -\starttabulate[|lT|p|] -\NC \rmbf value \NC \bf explanation \NC \NR -\NC 97 \NC list of attributes \NC \NR -\NC 100 \NC a \LUA\ number \NC \NR -\NC 110 \NC a node list \NC \NR -\NC 115 \NC a \LUA\ string \NC \NR -\NC 116 \NC a \LUA\ token list in \LUA\ table form \NC \NR +The \type {type} can have one of six distinct values. The number is the \ASCII\ +value if the first character if the type name (so you can use string.byte("l") +instead of \type {108}). + +\starttabulate[|lT|lT|p|] +\NC \rmbf value \NC \bf meaning \NC \bf explanation \NC \NR +\NC 97 \NC a \NC list of attributes (a node list) \NC \NR +\NC 100 \NC d \NC a \LUA\ number \NC \NR +\NC 108 \NC l \NC a \LUA\ value (table, number, boolean, etc) \NC \NR +\NC 110 \NC n \NC a node list \NC \NR +\NC 115 \NC s \NC a \LUA\ string \NC \NR +\NC 116 \NC t \NC a \LUA\ token list in \LUA\ table form (a list of triplets) \NC \NR \stoptabulate \subsubsubsection{save_pos whatsits} @@ -674,9 +711,9 @@ 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 \type {\latelua}. The \type {string} version is treated as a literal string. -\subsubsection{\DVI\ backend whatits} +\subsubsection{\DVI\ backend whatsits} -\subsubsection{special whatits} +\subsubsection{special whatsits} \starttabulate[|lT|l|p|] \NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR @@ -684,9 +721,9 @@ The difference between \type {data} and \type {string} is that on assignment, th \NC data \NC string \NC the \type {\special} information \NC \NR \stoptabulate -\subsubsection{\PDF\ backend whatits} +\subsubsection{\PDF\ backend whatsits} -\subsubsubsection{pdf_literal whatits} +\subsubsubsection{pdf_literal whatsits} \starttabulate[|lT|l|p|] \NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR @@ -702,9 +739,14 @@ Possible mode values are: \NC 0 \NC setorigin \NC \NR \NC 1 \NC page \NC \NR \NC 2 \NC direct \NC \NR +\NC 3 \NC raw \NC \NR \stoptabulate -\subsubsubsection{pdf_refobj whatits} +The higher the number, the less checking and the more you can run into troubles. +Especially the \type {raw} variant can produce bad \PDF\ so you can best check +what you generate. + +\subsubsubsection{pdf_refobj whatsits} \starttabulate[|lT|l|p|] \NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR @@ -712,7 +754,7 @@ Possible mode values are: \NC objnum \NC number \NC the referenced \PDF\ object number \NC \NR \stoptabulate -\subsubsubsection{pdf_annot whatits} +\subsubsubsection{pdf_annot whatsits} \starttabulate[|lT|l|p|] \NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR @@ -724,7 +766,7 @@ Possible mode values are: \NC data \NC string \NC the annotation data \NC \NR \stoptabulate -\subsubsubsection{pdf_start_link whatits} +\subsubsubsection{pdf_start_link whatsits} \starttabulate[|lT|l|p|] \NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR @@ -737,14 +779,14 @@ Possible mode values are: \NC action \NC node \NC the action to perform \NC \NR \stoptabulate -\subsubsubsection{pdf_end_link whatits} +\subsubsubsection{pdf_end_link whatsits} \starttabulate[|lT|l|p|] \NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR \NC attr \NC node \NC \NC \NR \stoptabulate -\subsubsubsection{pdf_dest whatits} +\subsubsubsection{pdf_dest whatsits} \starttabulate[|lT|l|p|] \NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR @@ -760,7 +802,7 @@ Possible mode values are: \NC objnum \NC number \NC the \PDF\ object number \NC \NR \stoptabulate -\subsubsubsection{pdf_action whatits} +\subsubsubsection{pdf_action whatsits} These are a special kind of item that only appears inside \PDF\ start link objects. @@ -792,7 +834,7 @@ Valid window types are: \NC 2 \NC nonew \NC \NR \stoptabulate -\subsubsubsection{pdf_thread whatits} +\subsubsubsection{pdf_thread whatsits} \starttabulate[|lT|l|p|] \NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR @@ -806,7 +848,7 @@ Valid window types are: \NC thread_attr \NC number \NC extra thread information \NC \NR \stoptabulate -\subsubsubsection{pdf_start_thread whatits} +\subsubsubsection{pdf_start_thread whatsits} \starttabulate[|lT|l|p|] \NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR @@ -820,14 +862,14 @@ Valid window types are: \NC thread_attr \NC number \NC extra thread information \NC \NR \stoptabulate -\subsubsubsection{pdf_end_thread whatits} +\subsubsubsection{pdf_end_thread whatsits} \starttabulate[|lT|l|p|] \NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR \NC attr \NC node \NC \NC \NR \stoptabulate -\subsubsubsection{pdf_colorstack whatits} +\subsubsubsection{pdf_colorstack whatsits} \starttabulate[|lT|l|p|] \NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR @@ -837,7 +879,7 @@ Valid window types are: \NC data \NC string \NC data \NC \NR \stoptabulate -\subsubsubsection{pdf_setmatrix whatits} +\subsubsubsection{pdf_setmatrix whatsits} \starttabulate[|lT|l|p|] \NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR @@ -845,224 +887,20 @@ Valid window types are: \NC data \NC string \NC data \NC \NR \stoptabulate -\subsubsubsection{pdf_save whatits} +\subsubsubsection{pdf_save whatsits} \starttabulate[|lT|l|p|] \NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR \NC attr \NC node \NC list of attributes \NC \NR \stoptabulate -\subsubsubsection{pdf_restore whatits} +\subsubsubsection{pdf_restore whatsits} \starttabulate[|lT|l|p|] \NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR \NC attr \NC node \NC list of attributes \NC \NR \stoptabulate -\section{Two access models} - -Deep down in \TEX\ a node has a number which is an numeric entry in a memory -table. In fact, this model, where \TEX\ manages memory is real fast and one of -the reasons why plugging in callbacks that operate on nodes is quite fast too. -Each node gets a number that is in fact an index in the memory table and that -number often gets reported when you print node related information. - -There are two access models, a robust one using a so called user data object that -provides a virtual interface to the internal nodes, and a more direct access which -uses the node numbers directly. The first model provide key based access while -the second always accesses fields via functions: - -\starttyping -nodeobject.char -getfield(nodenumber,"char") -\stoptyping - -If you use the direct model, even if you know that you deal with numbers, you -should not depend on that property but treat it an abstraction just like -traditional nodes. In fact, the fact that we use a simple basic datatype has the -penalty that less checking can be done, but less checking is also the reason why -it's somewhat faster. An important aspect is that one cannot mix both methods, -but you can cast both models. So, multiplying a node number makes no sense. - -So our advice is: use the indexed (table) approach when possible and investigate -the direct one when speed might be an real issue. For that reason we also provide -the \type {get*} and \type {set*} functions in the top level node namespace. -There is a limited set of getters. When implementing this direct approach the -regular index by key variant was also optimized, so direct access only makes -sense when we're accessing nodes millions of times (which happens in some font -processing for instance). - -We're talking mostly of getters because setters are less important. Documents -have not that many content related nodes and setting many thousands of properties -is hardly a burden contrary to millions of consultations. - -Normally you will access nodes like this: - -\starttyping -local next = current.next -if next then - -- do something -end -\stoptyping - -Here \type {next} is not a real field, but a virtual one. Accessing it results in -a metatable method being called. In practice it boils down to looking up the node -type and based on the node type checking for the field name. In a worst case you -have a node type that sits at the end of the lookup list and a field that is last -in the lookup chain. However, in successive versions of \LUATEX\ these lookups -have been optimized and the most frequently accessed nodes and fields have a -higher priority. - -Because in practice the \type {next} accessor results in a function call, there -is some overhead involved. The next code does the same and performs a tiny bit -faster (but not that much because it is still a function call but one that knows -what to look up). - -\starttyping -local next = node.next(current) -if next then - -- do something -end -\stoptyping - -If performance matters you can use an function instead: - -\starttabulate[|T|p|] -\NC getnext \NC parsing nodelist always involves this one \NC \NR -\NC getprev \NC used less but is logical companion to \type {getnext} \NC \NR -\NC getboth \NC returns the next and prev pointer of a node \NC \NR -\NC getid \NC consulted a lot \NC \NR -\NC getsubtype \NC consulted less but also a topper \NC \NR -\NC getfont \NC used a lot in \OPENTYPE\ handling (glyph nodes are consulted a lot) \NC \NR -\NC getchar \NC idem and also in other places \NC \NR -\NC getdisc \NC returns the \type {pre}, \type {post} and \type {replace} fields and - optionally when true is passed also the tail fields. \NC \NR -\NC getlist \NC we often parse nested lists so this is a convenient one too - (only works for hlist and vlist!) \NC \NR -\NC getleader \NC comparable to list, seldom used in \TEX\ (but needs frequent consulting - like lists; leaders could have been made a dedicated node type) \NC \NR -\NC getfield \NC generic getter, sufficient for the rest (other field names are - often shared so a specific getter makes no sense then) \NC \NR -\stoptabulate - -The direct variants also have setters, where the discretionary setter takes three -(optional) arguments plus an optional fourth indicating the subtype. - -It doesn't make sense to add getters for all fields, also because some are not -unique to one node type. Profiling demonstrated that these fields can get -accesses way more times than other fields. Even in complex documents, many node -and fields types never get seen, or seen only a few times. Most functions in the -\type {node} namespace have a companion in \type {node.direct}, but of course not -the ones that don't deal with nodes themselves. The following table summarized -this: - -% \startcolumns[balance=yes] - -\def\yes{$+$} \def\nop{$-$} - -\starttabulate[|T|c|c|] -\HL -\NC \bf function \NC \bf node \NC \bf direct \NC \NR -\HL -\NC \type {copy_list} \NC \yes \NC \yes \NC \NR -\NC \type {copy} \NC \yes \NC \yes \NC \NR -\NC \type {count} \NC \yes \NC \yes \NC \NR -\NC \type {current_attr} \NC \yes \NC \yes \NC \NR -\NC \type {dimensions} \NC \yes \NC \yes \NC \NR -\NC \type {do_ligature_n} \NC \yes \NC \yes \NC \NR -\NC \type {effective_glue} \NC \yes \NC \yes \NC \NR -\NC \type {end_of_math} \NC \yes \NC \yes \NC \NR -\NC \type {family_font} \NC \yes \NC \nop \NC \NR -\NC \type {fields} \NC \yes \NC \nop \NC \NR -\NC \type {first_character} \NC \yes \NC \nop \NC \NR -\NC \type {first_glyph} \NC \yes \NC \yes \NC \NR -\NC \type {flush_list} \NC \yes \NC \yes \NC \NR -\NC \type {flush_node} \NC \yes \NC \yes \NC \NR -\NC \type {free} \NC \yes \NC \yes \NC \NR -\NC \type {getboth} \NC \yes \NC \yes \NC \NR -\NC \type {getbox} \NC \nop \NC \yes \NC \NR -\NC \type {getchar} \NC \yes \NC \yes \NC \NR -\NC \type {getdisc} \NC \yes \NC \yes \NC \NR -\NC \type {getfield} \NC \yes \NC \yes \NC \NR -\NC \type {getfont} \NC \yes \NC \yes \NC \NR -\NC \type {getid} \NC \yes \NC \yes \NC \NR -\NC \type {getleader} \NC \yes \NC \yes \NC \NR -\NC \type {getlist} \NC \yes \NC \yes \NC \NR -\NC \type {getnext} \NC \yes \NC \yes \NC \NR -\NC \type {getprev} \NC \yes \NC \yes \NC \NR -\NC \type {getsubtype} \NC \yes \NC \yes \NC \NR -\NC \type {has_attribute} \NC \yes \NC \yes \NC \NR -\NC \type {has_field} \NC \yes \NC \yes \NC \NR -\NC \type {has_glyph} \NC \yes \NC \yes \NC \NR -\NC \type {hpack} \NC \yes \NC \yes \NC \NR -\NC \type {id} \NC \yes \NC \nop \NC \NR -\NC \type {insert_after} \NC \yes \NC \yes \NC \NR -\NC \type {insert_before} \NC \yes \NC \yes \NC \NR -\NC \type {is_char} \NC \yes \NC \yes \NC \NR -\NC \type {is_glyph} \NC \yes \NC \yes \NC \NR -\NC \type {is_direct} \NC \nop \NC \yes \NC \NR -\NC \type {is_node} \NC \yes \NC \yes \NC \NR -\NC \type {kerning} \NC \yes \NC \yes \NC \NR -\NC \type {last_node} \NC \yes \NC \yes \NC \NR -\NC \type {length} \NC \yes \NC \yes \NC \NR -\NC \type {ligaturing} \NC \yes \NC \yes \NC \NR -\NC \type {mlist_to_hlist} \NC \yes \NC \nop \NC \NR -\NC \type {new} \NC \yes \NC \yes \NC \NR -\NC \type {next} \NC \yes \NC \nop \NC \NR -\NC \type {prev} \NC \yes \NC \nop \NC \NR -\NC \type {protect_glyph} \NC \yes \NC \yes \NC \NR -\NC \type {protect_glyphs} \NC \yes \NC \yes \NC \NR -\NC \type {protrusion_skippable} \NC \yes \NC \yes \NC \NR -\NC \type {remove} \NC \yes \NC \yes \NC \NR -\NC \type {set_attribute} \NC \yes \NC \yes \NC \NR -\NC \type {setboth} \NC \yes \NC \yes \NC \NR -\NC \type {setbox} \NC \yes \NC \yes \NC \NR -\NC \type {setchar} \NC \yes \NC \yes \NC \NR -\NC \type {setdisc} \NC \yes \NC \yes \NC \NR -\NC \type {setfield} \NC \yes \NC \yes \NC \NR -\NC \type {setlink} \NC \yes \NC \yes \NC \NR -\NC \type {setnext} \NC \yes \NC \yes \NC \NR -\NC \type {setprev} \NC \yes \NC \yes \NC \NR -\NC \type {slide} \NC \yes \NC \yes \NC \NR -\NC \type {subtype} \NC \yes \NC \nop \NC \NR -\NC \type {subtypes} \NC \yes \NC \nop \NC \NR -\NC \type {tail} \NC \yes \NC \yes \NC \NR -\NC \type {todirect} \NC \yes \NC \yes \NC \NR -\NC \type {tonode} \NC \yes \NC \yes \NC \NR -\NC \type {tostring} \NC \yes \NC \yes \NC \NR -\NC \type {traverse_id} \NC \yes \NC \yes \NC \NR -\NC \type {traverse_char} \NC \yes \NC \yes \NC \NR -\NC \type {traverse} \NC \yes \NC \yes \NC \NR -\NC \type {types} \NC \yes \NC \nop \NC \NR -\NC \type {type} \NC \yes \NC \nop \NC \NR -\NC \type {unprotect_glyphs} \NC \yes \NC \yes \NC \NR -\NC \type {unset_attribute} \NC \yes \NC \yes \NC \NR -\NC \type {usedlist} \NC \yes \NC \yes \NC \NR -\NC \type {vpack} \NC \yes \NC \yes \NC \NR -\NC \type {whatsits} \NC \yes \NC \nop \NC \NR -\NC \type {whatsitsubtypes} \NC \yes \NC \nop \NC \NR -\NC \type {write} \NC \yes \NC \yes \NC \NR -\NC \type {setglue} \NC \yes \NC \yes \NC \NR -\NC \type {getglue} \NC \yes \NC \yes \NC \NR -\NC \type {glue_is_zero} \NC \yes \NC \yes \NC \NR -\stoptabulate - -% \stopcolumns - -The \type {node.next} and \type {node.prev} functions will stay but for -consistency there are variants called \type {getnext} and \type {getprev}. We had -to use \type {get} because \type {node.id} and \type {node.subtype} are already -taken for providing meta information about nodes. Note: The getters do only basic -checking for valid keys. You should just stick to the keys mentioned in the -sections that describe node properties. - -Some nodes have indirect references. For instance a math character refers to a -family instead of a font. In that case we provide a virtual font field as -accessor. So, \type {getfont} and \type {.font} can be used on them. The same is -true for the \type {width}, \type {height} and \type {depth} of glue nodes. These -actually access the spec node properties, and here we can set as well as get the -values. - \section{The \type {node} library} The \type {node} library contains functions that facilitate dealing with (lists @@ -1229,16 +1067,21 @@ the \TEX\ level. This function accepts string \type {id} and \type {subtype} values as well. -\subsubsection{\type {node.free}} +\subsubsection{\type {node.free} and \type {node.flush_node}} \startfunctioncall -node.free(<node> n) +<node> next = + node.free(<node> n) +flush_node(<node> n) \stopfunctioncall Removes the node \type {n} from \TEX's memory. Be careful: no checks are done on whether this node is still pointed to from a register or some \type {next} field: it is up to you to make sure that the internal data structures remain correct. +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}} \startfunctioncall @@ -1380,7 +1223,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}} +\subsubsection{\type {node.dimensions}, \type {node.rangedimensions}} \startfunctioncall <number> w, <number> h, <number> d = @@ -1433,7 +1276,17 @@ example in code like this, which prints the width of the space in between the You need to keep in mind that this is one of the few places in \TEX\ where floats are used, which means that you can get small differences in rounding when you -compare the width repported by \type {hpack} with \type {dimensions}. +compare the width reported by \type {hpack} with \type {dimensions}. + +The second alternative saves a few lookups and can be more convenient in some +cases: + +\startfunctioncall +<number> w, <number> h, <number> d = + node.rangedimensions(<node> parent, <node> first) +<number> w, <number> h, <number> d = + node.rangedimensions(<node> parent, <node> first, <node> last) +\stopfunctioncall \subsubsection{\type {node.mlist_to_hlist}} @@ -1569,6 +1422,25 @@ See the previous section for details. The change is in the local function \type end \stoptyping +\subsubsection{\type {node.traverse_char}} + +This iterators loops over the glyph nodes in a list. Only nodes with a subtype +less than 256 are seen. + +\startfunctioncall +<node> n = + node.traverse_char(<node> n) +\stopfunctioncall + +\subsubsection{\type {node.has_glyph}} + +This function returns the first glyph or disc node in the given list: + +\startfunctioncall +<node> n = + node.has_glyph(<node> n) +\stopfunctioncall + \subsubsection{\type {node.end_of_math}} \startfunctioncall @@ -1675,7 +1547,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. -\subsubsection{\type {node.protect_glyphs}} +\subsubsection{\type {node.protect_glyphs} and \type {node.protect_glyph}} \startfunctioncall node.protect_glyphs(<node> n) @@ -1683,7 +1555,8 @@ node.protect_glyphs(<node> n) Adds 256 to all glyph node subtypes in the node list starting at \type {n}, except that if the value is 1, it adds only 255. The special handling of 1 means -that \type {characters} will become \type {glyphs} after subtraction of 256. +that \type {characters} will become \type {glyphs} after subtraction of 256. A +single character can be marked by the singular call. \subsubsection{\type {node.last_node}} @@ -1745,6 +1618,9 @@ The next call will return 5 values (or northing when no glue is passed). <integer> shrink_order = node.getglue(<node> n) \stopfunctioncall +When the second argument is false, only the width is returned (this is consistent +with \type {tex.get}). + \subsubsection{\type {node.is_zero_glue}} This function returns \type {true} when the width, stretch and shrink properties @@ -1774,6 +1650,26 @@ 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}} + +\startfunctioncall +<number> v = + node.get_attribute(<node> n, <number> id) +\stopfunctioncall + +Tests if a node has an attribute with number \type {id} set. It returns the +value, or, if no match is found, \type {nil}. + +\subsubsection{\type {node.find_attribute}} + +\startfunctioncall +<number> v, <node> n = + node.find_attribute(<node> n, <number> id) +\stopfunctioncall + +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}} \startfunctioncall @@ -1799,6 +1695,299 @@ 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}} + +This helper makes sure that the node lists is double linked and returns the found +tail node. + +\startfunctioncall +<node> tail = + node.slide(<node> n) +\stopfunctioncall + +\subsubsection{\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 +you have extended the lists it's ok because then the tail pointers get updated, +but when you add to list without reassigning you might end up in troubles when +the linebreak routien kicks in. You can call this function to check the list for +issues with disc nodes. + +\startfunctioncall +node.check_discretionary(<node> n) +node.check_discretionaries(<node> head) +\stopfunctioncall + +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.family_font}} + +When you pass it a proper family identifier the next helper will return the font +currently associated with it. You can normally also access the font with the normal +font field or getter because it will resolve the family automatically for noads. + +\startfunctioncall +<integer> id = + node.family_font(<integer> fam) +\stopfunctioncall + +\section{Two access models} + +Deep down in \TEX\ a node has a number which is an numeric entry in a memory +table. In fact, this model, where \TEX\ manages memory is real fast and one of +the reasons why plugging in callbacks that operate on nodes is quite fast too. +Each node gets a number that is in fact an index in the memory table and that +number often gets reported when you print node related information. + +There are two access models, a robust one using a so called user data object that +provides a virtual interface to the internal nodes, and a more direct access which +uses the node numbers directly. The first model provide key based access while +the second always accesses fields via functions: + +\starttyping +nodeobject.char +getfield(nodenumber,"char") +\stoptyping + +If you use the direct model, even if you know that you deal with numbers, you +should not depend on that property but treat it an abstraction just like +traditional nodes. In fact, the fact that we use a simple basic datatype has the +penalty that less checking can be done, but less checking is also the reason why +it's somewhat faster. An important aspect is that one cannot mix both methods, +but you can cast both models. So, multiplying a node number makes no sense. + +So our advice is: use the indexed (table) approach when possible and investigate +the direct one when speed might be an real issue. For that reason we also provide +the \type {get*} and \type {set*} functions in the top level node namespace. +There is a limited set of getters. When implementing this direct approach the +regular index by key variant was also optimized, so direct access only makes +sense when we're accessing nodes millions of times (which happens in some font +processing for instance). + +We're talking mostly of getters because setters are less important. Documents +have not that many content related nodes and setting many thousands of properties +is hardly a burden contrary to millions of consultations. + +Normally you will access nodes like this: + +\starttyping +local next = current.next +if next then + -- do something +end +\stoptyping + +Here \type {next} is not a real field, but a virtual one. Accessing it results in +a metatable method being called. In practice it boils down to looking up the node +type and based on the node type checking for the field name. In a worst case you +have a node type that sits at the end of the lookup list and a field that is last +in the lookup chain. However, in successive versions of \LUATEX\ these lookups +have been optimized and the most frequently accessed nodes and fields have a +higher priority. + +Because in practice the \type {next} accessor results in a function call, there +is some overhead involved. The next code does the same and performs a tiny bit +faster (but not that much because it is still a function call but one that knows +what to look up). + +\starttyping +local next = node.next(current) +if next then + -- do something +end +\stoptyping + +Some accessors are used frequently and for these we provide more efficient helpers: + +\starttabulate[|T|p|] +\NC getnext \NC parsing nodelist always involves this one \NC \NR +\NC getprev \NC used less but is logical companion to \type {getnext} \NC \NR +\NC getboth \NC returns the next and prev pointer of a node \NC \NR +\NC getid \NC consulted a lot \NC \NR +\NC getsubtype \NC consulted less but also a topper \NC \NR +\NC getfont \NC used a lot in \OPENTYPE\ handling (glyph nodes are consulted a lot) \NC \NR +\NC getchar \NC idem and also in other places \NC \NR +\NC getwhd \NC returns the \type {width}, \type {height} and \type {depth} of a list, rule or + (unexpanded) glyph as well as glue (its spec is looked at) and unset nodes\NC \NR +\NC getdisc \NC returns the \type {pre}, \type {post} and \type {replace} fields and + optionally when true is passed also the tail fields. \NC \NR +\NC getlist \NC we often parse nested lists so this is a convenient one too \NC \NR +\NC getleader \NC comparable to list, seldom used in \TEX\ (but needs frequent consulting + like lists; leaders could have been made a dedicated node type) \NC \NR +\NC getfield \NC generic getter, sufficient for the rest (other field names are + often shared so a specific getter makes no sense then) \NC \NR +\NC getbox \NC gets the given box (a list node) \NC \NR +\stoptabulate + +In the direct namespace there are more such helpers and most of them are +accompanied by setters. The getters and setters are clever enough to see what +node is meant. We don't deal with whatsit nodes: their fields are always accessed +by name. It doesn't make sense to add getters for all fields, we just identifier +the most likely candidates. In complex documents, many node and fields types +never get seen, or seen only a few times, but for instance glyphs are candidates +for such optimization. The \type {node.direct} interface has some more helpers. +\footnote {We can define the helpers in the node namespace with \type {getfield} +which is about as efficient, so at some point we might provide that as module.} + +The \type {setdisc} helper takes three (optional) arguments plus an optional +fourth indicating the subtype. Its \type {getdisc} takes an optional boolean; +when its value is \type {true} the tail nodes will also be returned. The \type +{setfont} helper takes an optional second argument, it being the character. The +directmode setter \type {setlink} takes a list of nodes and will link them, +thereby ignoring \type {nil} entries. The first valid node is returned (beware: +for good reason it assumes single nodes). For rarely used fields no helpers are +provided and there are a few that probably are used seldom too but were added for +consistency. You can of course always define additional accessor using \type +{getfield} and \type {setfield} with little overhead. + +% \startcolumns[balance=yes] + +\def\yes{$+$} \def\nop{$-$} + +\starttabulate[|T|c|c|] +\HL +\NC \bf function \NC \bf node \NC \bf direct \NC \NR +\HL +%NC \type {do_ligature_n} \NC \yes \NC \yes \NC \NR % was never documented and experimental +\NC \type {check_discretionaries}\NC \yes \NC \yes \NC \NR +\NC \type {copy_list} \NC \yes \NC \yes \NC \NR +\NC \type {copy} \NC \yes \NC \yes \NC \NR +\NC \type {count} \NC \yes \NC \yes \NC \NR +\NC \type {current_attr} \NC \yes \NC \yes \NC \NR +\NC \type {dimensions} \NC \yes \NC \yes \NC \NR +\NC \type {effective_glue} \NC \yes \NC \yes \NC \NR +\NC \type {end_of_math} \NC \yes \NC \yes \NC \NR +\NC \type {family_font} \NC \yes \NC \nop \NC \NR +\NC \type {fields} \NC \yes \NC \nop \NC \NR +\NC \type {find_attribute} \NC \yes \NC \yes \NC \NR +\NC \type {first_glyph} \NC \yes \NC \yes \NC \NR +\NC \type {flush_list} \NC \yes \NC \yes \NC \NR +\NC \type {flush_node} \NC \yes \NC \yes \NC \NR +\NC \type {free} \NC \yes \NC \yes \NC \NR +\NC \type {get_attribute} \NC \yes \NC \yes \NC \NR +\NC \type {getattributelist} \NC \nop \NC \yes \NC \NR +\NC \type {getboth} \NC \yes \NC \yes \NC \NR +\NC \type {getbox} \NC \nop \NC \yes \NC \NR +\NC \type {getchar} \NC \yes \NC \yes \NC \NR +\NC \type {getcomponents} \NC \nop \NC \yes \NC \NR +\NC \type {getdepth} \NC \nop \NC \yes \NC \NR +\NC \type {getdir} \NC \nop \NC \yes \NC \NR +\NC \type {getdisc} \NC \yes \NC \yes \NC \NR +\NC \type {getfield} \NC \yes \NC \yes \NC \NR +\NC \type {getfont} \NC \yes \NC \yes \NC \NR +\NC \type {getglue} \NC \yes \NC \yes \NC \NR +\NC \type {getheight} \NC \nop \NC \yes \NC \NR +\NC \type {getid} \NC \yes \NC \yes \NC \NR +\NC \type {getkern} \NC \nop \NC \yes \NC \NR +\NC \type {getlang} \NC \nop \NC \yes \NC \NR +\NC \type {getleader} \NC \yes \NC \yes \NC \NR +\NC \type {getlist} \NC \yes \NC \yes \NC \NR +\NC \type {getnext} \NC \yes \NC \yes \NC \NR +\NC \type {getnucleus} \NC \nop \NC \yes \NC \NR +\NC \type {getoffsets} \NC \nop \NC \yes \NC \NR +\NC \type {getpenalty} \NC \nop \NC \yes \NC \NR +\NC \type {getprev} \NC \yes \NC \yes \NC \NR +\NC \type {getproperty} \NC \yes \NC \yes \NC \NR +\NC \type {getshift} \NC \nop \NC \yes \NC \NR +\NC \type {getwidth} \NC \nop \NC \yes \NC \NR +\NC \type {getwhd} \NC \nop \NC \yes \NC \NR +\NC \type {getsub} \NC \nop \NC \yes \NC \NR +\NC \type {getsubtype} \NC \yes \NC \yes \NC \NR +\NC \type {getsup} \NC \nop \NC \yes \NC \NR +\NC \type {has_attribute} \NC \yes \NC \yes \NC \NR +\NC \type {has_field} \NC \yes \NC \yes \NC \NR +\NC \type {has_glyph} \NC \yes \NC \yes \NC \NR +\NC \type {hpack} \NC \yes \NC \yes \NC \NR +\NC \type {id} \NC \yes \NC \nop \NC \NR +\NC \type {insert_after} \NC \yes \NC \yes \NC \NR +\NC \type {insert_before} \NC \yes \NC \yes \NC \NR +\NC \type {is_char} \NC \yes \NC \yes \NC \NR +\NC \type {is_direct} \NC \nop \NC \yes \NC \NR +\NC \type {is_glue_zero} \NC \yes \NC \yes \NC \NR +\NC \type {is_glyph} \NC \yes \NC \yes \NC \NR +\NC \type {is_node} \NC \yes \NC \yes \NC \NR +\NC \type {kerning} \NC \yes \NC \yes \NC \NR +\NC \type {last_node} \NC \yes \NC \yes \NC \NR +\NC \type {length} \NC \yes \NC \yes \NC \NR +\NC \type {ligaturing} \NC \yes \NC \yes \NC \NR +\NC \type {mlist_to_hlist} \NC \yes \NC \nop \NC \NR +\NC \type {new} \NC \yes \NC \yes \NC \NR +\NC \type {next} \NC \yes \NC \nop \NC \NR +\NC \type {prev} \NC \yes \NC \nop \NC \NR +\NC \type {protect_glyphs} \NC \yes \NC \yes \NC \NR +\NC \type {protect_glyph} \NC \yes \NC \yes \NC \NR +\NC \type {protrusion_skippable} \NC \yes \NC \yes \NC \NR +\NC \type {rangedimensions} \NC \yes \NC \yes \NC \NR +\NC \type {remove} \NC \yes \NC \yes \NC \NR +\NC \type {set_attribute} \NC \nop \NC \yes \NC \NR +\NC \type {setattributelist} \NC \nop \NC \yes \NC \NR +\NC \type {setboth} \NC \nop \NC \yes \NC \NR +\NC \type {setbox} \NC \nop \NC \yes \NC \NR +\NC \type {setchar} \NC \nop \NC \yes \NC \NR +\NC \type {setcomponents} \NC \nop \NC \yes \NC \NR +\NC \type {setdepth} \NC \nop \NC \yes \NC \NR +\NC \type {setdir} \NC \nop \NC \yes \NC \NR +\NC \type {setdisc} \NC \nop \NC \yes \NC \NR +\NC \type {setfield} \NC \yes \NC \yes \NC \NR +\NC \type {setfont} \NC \nop \NC \yes \NC \NR +\NC \type {setglue} \NC \yes \NC \yes \NC \NR +\NC \type {setheight} \NC \nop \NC \yes \NC \NR +\NC \type {setid} \NC \nop \NC \yes \NC \NR +\NC \type {setkern} \NC \nop \NC \yes \NC \NR +\NC \type {setlang} \NC \nop \NC \yes \NC \NR +\NC \type {setleader} \NC \nop \NC \yes \NC \NR +\NC \type {setlist} \NC \nop \NC \yes \NC \NR +\NC \type {setnext} \NC \nop \NC \yes \NC \NR +\NC \type {setnucleus} \NC \nop \NC \yes \NC \NR +\NC \type {setoffsets} \NC \nop \NC \yes \NC \NR +\NC \type {setpenalty} \NC \nop \NC \yes \NC \NR +\NC \type {setprev} \NC \nop \NC \yes \NC \NR +\NC \type {setproperty} \NC \nop \NC \yes \NC \NR +\NC \type {setshift} \NC \nop \NC \yes \NC \NR +\NC \type {setwidth} \NC \nop \NC \yes \NC \NR +\NC \type {setwhd} \NC \nop \NC \yes \NC \NR +\NC \type {setsub} \NC \nop \NC \yes \NC \NR +\NC \type {setsubtype} \NC \nop \NC \yes \NC \NR +\NC \type {setsup} \NC \nop \NC \yes \NC \NR +\NC \type {slide} \NC \yes \NC \yes \NC \NR +\NC \type {subtypes} \NC \yes \NC \nop \NC \NR +\NC \type {subtype} \NC \yes \NC \nop \NC \NR +\NC \type {tail} \NC \yes \NC \yes \NC \NR +\NC \type {todirect} \NC \yes \NC \yes \NC \NR +\NC \type {tonode} \NC \yes \NC \yes \NC \NR +\NC \type {tostring} \NC \yes \NC \yes \NC \NR +\NC \type {traverse_char} \NC \yes \NC \yes \NC \NR +\NC \type {traverse_id} \NC \yes \NC \yes \NC \NR +\NC \type {traverse} \NC \yes \NC \yes \NC \NR +\NC \type {types} \NC \yes \NC \nop \NC \NR +\NC \type {type} \NC \yes \NC \nop \NC \NR +\NC \type {unprotect_glyphs} \NC \yes \NC \yes \NC \NR +\NC \type {unset_attribute} \NC \yes \NC \yes \NC \NR +\NC \type {usedlist} \NC \yes \NC \yes \NC \NR +\NC \type {vpack} \NC \yes \NC \yes \NC \NR +\NC \type {whatsitsubtypes} \NC \yes \NC \nop \NC \NR +\NC \type {whatsits} \NC \yes \NC \nop \NC \NR +\NC \type {write} \NC \yes \NC \yes \NC \NR +\stoptabulate + +% \stopcolumns + +The \type {node.next} and \type {node.prev} functions will stay but for +consistency there are variants called \type {getnext} and \type {getprev}. We had +to use \type {get} because \type {node.id} and \type {node.subtype} are already +taken for providing meta information about nodes. Note: The getters do only basic +checking for valid keys. You should just stick to the keys mentioned in the +sections that describe node properties. + +Some nodes have indirect references. For instance a math character refers to a +family instead of a font. In that case we provide a virtual font field as +accessor. So, \type {getfont} and \type {.font} can be used on them. The same is +true for the \type {width}, \type {height} and \type {depth} of glue nodes. These +actually access the spec node properties, and here we can set as well as get the +values. + \stopchapter \stopcomponent diff --git a/Master/texmf-dist/doc/luatex/base/luatex-style.tex b/Master/texmf-dist/doc/luatex/base/luatex-style.tex index feca120eddb..20e19510a8d 100644 --- a/Master/texmf-dist/doc/luatex/base/luatex-style.tex +++ b/Master/texmf-dist/doc/luatex/base/luatex-style.tex @@ -1,355 +1,362 @@ -\startenvironment luatex-style - -\usemodule[abr-02] - -\setuplayout - [height=middle, - width=middle, - backspace=2cm, - topspace=10mm, - bottomspace=10mm, - header=10mm, - footer=10mm, - footerdistance=10mm, - headerdistance=10mm] - -\setuppagenumbering - [alternative=doublesided] - -\setuptolerance - [stretch,tolerant] - -\setuptype - [lines=hyphenated] - -\setuptyping - [lines=hyphenated] - -\setupitemize - [each] - [packed] - -\setupwhitespace - [medium] - -\startluacode - local skipped = table.tohash { 'id', 'subtype', 'next', 'prev' } - - function document.functions.showfields(s) - local t = string.split(s,',') - local f = node.fields(t[1],t[2]) - if f then - local d = false - for i=1,#f do - local fi = f[i] - if skipped[fi] then - -- okay - elseif d then - context(', {\tttf %s}', fi) - else - context('{\tttf %s}', fi) - d = true - end - end - end - end - - function document.functions.showid(s) - local t = string.split(s,',') - context('{tttf %s}',node.id(t[1])) - if t[2] then - context(', {tttf %s}',node.subtype(t[2])) - end - end - - function document.functions.showsubtypes(s) - local s = node.subtypes(s) - local d = false - for k, v in table.sortedhash(s) do - if d then - context(', %s = {\\tttf %s}',k,v) - else - context('%s = {\\tttf %s}',k,v) - d = true - end - end - end -\stopluacode - -\unexpanded\def\showfields #1{\ctxlua{document.functions.showfields("#1")}} -\unexpanded\def\showid #1{\ctxlua{document.functions.showid("#1")}} -\unexpanded\def\showsubtypes#1{\ctxlua{document.functions.showsubtypes("#1")}} - -\definecolor[blue] [b=.5] -\definecolor[red] [r=.5] -\definecolor[green] [g=.5] -\definecolor[maincolor] [b=.5] -\definecolor[keptcolor] [b=.5] -\definecolor[othercolor][r=.5,g=.5] - -\setupbodyfont[modern] % we need this in examples so we predefine - -% \doifmodeelse {atpragma} { -% -% % \setupbodyfont -% % [lucidaot,10pt] -% -% \setupbodyfont -% [dejavu,10pt] -% -% \setuphead [chapter] [style=\bfd] -% \setuphead [section] [style=\bfb] -% \setuphead [subsection] [style=\bfa] -% \setuphead [subsubsection][style=\bf] -% -% } { -% -% \definetypeface[mainfacenormal] [ss][sans] [iwona] [default] -% \definetypeface[mainfacenormal] [rm][serif][palatino] [default] -% \definetypeface[mainfacenormal] [tt][mono] [modern] [default][rscale=1.1] -% \definetypeface[mainfacenormal] [mm][math] [iwona] [default] -% -% \definetypeface[mainfacemedium] [ss][sans] [iwona-medium][default] -% \definetypeface[mainfacemedium] [rm][serif][palatino] [default] -% \definetypeface[mainfacemedium] [tt][mono] [modern] [default][rscale=1.1] -% \definetypeface[mainfacemedium] [mm][math] [iwona-medium][default] -% -% \setupbodyfont -% [mainfacenormal,10pt] -% -% \setuphead [chapter] [style=\mainfacemedium\bfd] -% \setuphead [section] [style=\mainfacemedium\bfb] -% \setuphead [subsection] [style=\mainfacemedium\bfa] -% \setuphead [subsubsection][style=\mainfacemedium\bf] -% -% } - -\writestatus{luatex manual}{we assume that dejavu math is available} - -\setupbodyfont % assumes dejavu-math - [dejavu,10pt] - -\setuphead [chapter] [align={flushleft,broad},style=\bfd] -\setuphead [section] [align={flushleft,broad},style=\bfb] -\setuphead [subsection] [align={flushleft,broad},style=\bfa] -\setuphead [subsubsection][align={flushleft,broad},style=\bf] - -\setuphead [chapter] [color=maincolor] -\setuphead [section] [color=maincolor] -\setuphead [subsection] [color=maincolor] -\setuphead [subsubsection][color=maincolor] - -\definehead - [remark] - [subsubsubject] - -\setupheadertexts - [] - -\definemixedcolumns - [twocolumns] - [n=2, - balance=yes, - before=\blank, - after=\blank] - -\definemixedcolumns - [threecolumns] - [twocolumns] - [n=3] - -\definemixedcolumns - [fourcolumns] - [threecolumns] - [n=4] - -% if we do this we also need to do it in table cells -% -% \setuptyping -% [color=maincolor] -% -% \setuptype -% [color=maincolor] - -\definetyping - [functioncall] - -\startMPdefinitions - - color luaplanetcolor ; luaplanetcolor := \MPcolor{maincolor} ; - color luaholecolor ; luaholecolor := white ; - numeric luaextraangle ; luaextraangle := 0 ; - numeric luaorbitfactor ; luaorbitfactor := .25 ; - - vardef lualogo = image ( - - % Graphic design by A. Nakonechnyj. Copyright (c) 1998, All rights reserved. - - save d, r, p ; numeric d, r, p ; - - d := sqrt(2)/4 ; r := 1/4 ; p := r/8 ; - - fill fullcircle scaled 1 - withcolor luaplanetcolor ; - draw fullcircle rotated 40.5 scaled (1+r) - dashed evenly scaled p - withpen pencircle scaled (p/2) - withcolor (luaorbitfactor * luaholecolor) ; - fill fullcircle scaled r shifted (d+1/8,d+1/8) - rotated luaextraangle - withcolor luaplanetcolor ; - fill fullcircle scaled r shifted (d-1/8,d-1/8) - withcolor luaholecolor ; - luaorbitfactor := .25 ; - ) enddef ; - -\stopMPdefinitions - -\startuseMPgraphic{luapage} - StartPage ; - - fill Page withcolor \MPcolor{othercolor} ; - - luaorbitfactor := 1 ; - picture p ; p := lualogo xsized (3PaperWidth/5) ; - draw p shifted center Page shifted (0,-.5ypart center ulcorner p) ; - - StopPage ; -\stopuseMPgraphic - -\starttexdefinition luaextraangle - % we can also just access the last page and so in mp directly - \ctxlua { - context(\lastpage == 0 and 0 or \realfolio*360/\lastpage) - } -\stoptexdefinition - -\startuseMPgraphic{luanumber} - luaextraangle := \luaextraangle; - luaorbitfactor := 0.25 ; - picture p ; p := lualogo ; - setbounds p to boundingbox fullcircle ; - draw p ysized 1cm ; -\stopuseMPgraphic - -\definelayer - [page] - [width=\paperwidth, - height=\paperheight] - -\setupbackgrounds - [leftpage] - [background=page] - -\setupbackgrounds - [rightpage] - [background=page] - -\startsetups pagenumber:right - \setlayerframed - [page] - [preset=rightbottom,offset=1cm] - [frame=off,height=1cm,offset=overlay] - {\useMPgraphic{luanumber}} - \setlayerframed - [page] - [preset=rightbottom,offset=1cm,x=1.5cm] - [frame=off,height=1cm,width=1cm,offset=overlay] - {\pagenumber} - \setlayerframed - [page] - [preset=rightbottom,offset=1cm,x=2.5cm] - [frame=off,height=1cm,offset=overlay] - {\getmarking[chapter]} -\stopsetups - -\startsetups pagenumber:left - \setlayerframed - [page] - [preset=leftbottom,offset=1cm,x=2.5cm] - [frame=off,height=1cm,offset=overlay] - {\getmarking[chapter]} - \setlayerframed - [page] - [preset=leftbottom,offset=1cm,x=1.5cm] - [frame=off,height=1cm,width=1cm,offset=overlay] - {\pagenumber} - \setlayerframed - [page] - [preset=leftbottom,offset=1cm] - [frame=off,height=1cm,offset=overlay] - {\useMPgraphic{luanumber}} -\stopsetups - -\unexpanded\def\nonterminal#1>{\mathematics{\langle\hbox{\rm #1}\rangle}} - -% taco's brainwave -) - -\newcatcodetable\syntaxcodetable - -\unexpanded\def\makesyntaxcodetable - {\begingroup - \catcode`\<=13 \catcode`\|=12 - \catcode`\!= 0 \catcode`\\=12 - \savecatcodetable\syntaxcodetable - \endgroup} - -\makesyntaxcodetable - -\unexpanded\def\startsyntax {\begingroup\catcodetable\syntaxcodetable \dostartsyntax} -\unexpanded\def\syntax {\begingroup\catcodetable\syntaxcodetable \dosyntax} - \let\stopsyntax \relax - -\unexpanded\def\syntaxenvbody#1% - {\par - \tt - \startnarrower - \maincolor #1 - \stopnarrower - \par} - -\unexpanded\def\syntaxbody#1% - {\begingroup - \maincolor \tt #1% - \endgroup} - -\bgroup \catcodetable\syntaxcodetable - -!gdef!dostartsyntax#1\stopsyntax{!let<!nonterminal!syntaxenvbody{#1}!endgroup} -!gdef!dosyntax #1{!let<!nonterminal!syntaxbody{#1}!endgroup} - -!egroup - -% end of wave - -\setupinteraction - [state=start, - focus=standard, - style=, - color=, - contrastcolor=] - -\placebookmarks - [chapter,section,subsection] - -\setuplist - [chapter,section,subsection,subsubsection] - [interaction=all, - width=3em] - -\setuplist - [chapter] - [style=bold, - color=keptcolor] - -\setuplist - [subsection,subsubsection] - [margin=3em, - width=5em] - -% Hans doesn't like the bookmarks opening by default so we comment this: -% -% \setupinteractionscreen -% [option=bookmark] - -\stopenvironment +\startenvironment luatex-style
+
+% todo: use \useMPlibrary[lua]
+
+\usemodule[abr-02]
+
+\setuplayout
+ [height=middle,
+ width=middle,
+ backspace=2cm,
+ topspace=10mm,
+ bottomspace=10mm,
+ header=10mm,
+ footer=10mm,
+ footerdistance=10mm,
+ headerdistance=10mm]
+
+\setuppagenumbering
+ [alternative=doublesided]
+
+\setuptolerance
+ [stretch,tolerant]
+
+\setuptype
+ [lines=hyphenated]
+
+\setuptyping
+ [lines=hyphenated]
+
+\setupitemize
+ [each]
+ [packed]
+
+\setupwhitespace
+ [medium]
+
+\startluacode
+ local skipped = table.tohash { 'id', 'subtype', 'next', 'prev' }
+
+ function document.functions.showfields(s)
+ local t = string.split(s,',')
+ local f = node.fields(t[1],t[2])
+ if f then
+ local d = false
+ for i=1,#f do
+ local fi = f[i]
+ if skipped[fi] then
+ -- okay
+ elseif d then
+ context(', {\tttf %s}', fi)
+ else
+ context('{\tttf %s}', fi)
+ d = true
+ end
+ end
+ end
+ end
+
+ function document.functions.showid(s)
+ local t = string.split(s,',')
+ context('{tttf %s}',node.id(t[1]))
+ if t[2] then
+ context(', {tttf %s}',node.subtype(t[2]))
+ end
+ end
+
+ function document.functions.showsubtypes(s)
+ local s = node.subtypes(s)
+ local d = false
+ for k, v in table.sortedhash(s) do
+ if d then
+ context(', %s = {\\tttf %s}',k,v)
+ else
+ context('%s = {\\tttf %s}',k,v)
+ d = true
+ end
+ end
+ end
+\stopluacode
+
+\unexpanded\def\showfields #1{\ctxlua{document.functions.showfields("#1")}}
+\unexpanded\def\showid #1{\ctxlua{document.functions.showid("#1")}}
+\unexpanded\def\showsubtypes#1{\ctxlua{document.functions.showsubtypes("#1")}}
+
+\definecolor[blue] [b=.5]
+\definecolor[red] [r=.5]
+\definecolor[green] [g=.5]
+\definecolor[maincolor] [b=.5]
+\definecolor[keptcolor] [b=.5]
+\definecolor[othercolor][r=.5,g=.5]
+
+\setupbodyfont[modern] % we need this in examples so we predefine
+
+% \doifmodeelse {atpragma} {
+%
+% % \setupbodyfont
+% % [lucidaot,10pt]
+%
+% \setupbodyfont
+% [dejavu,10pt]
+%
+% \setuphead [chapter] [style=\bfd]
+% \setuphead [section] [style=\bfb]
+% \setuphead [subsection] [style=\bfa]
+% \setuphead [subsubsection][style=\bf]
+%
+% } {
+%
+% \definetypeface[mainfacenormal] [ss][sans] [iwona] [default]
+% \definetypeface[mainfacenormal] [rm][serif][palatino] [default]
+% \definetypeface[mainfacenormal] [tt][mono] [modern] [default][rscale=1.1]
+% \definetypeface[mainfacenormal] [mm][math] [iwona] [default]
+%
+% \definetypeface[mainfacemedium] [ss][sans] [iwona-medium][default]
+% \definetypeface[mainfacemedium] [rm][serif][palatino] [default]
+% \definetypeface[mainfacemedium] [tt][mono] [modern] [default][rscale=1.1]
+% \definetypeface[mainfacemedium] [mm][math] [iwona-medium][default]
+%
+% \setupbodyfont
+% [mainfacenormal,10pt]
+%
+% \setuphead [chapter] [style=\mainfacemedium\bfd]
+% \setuphead [section] [style=\mainfacemedium\bfb]
+% \setuphead [subsection] [style=\mainfacemedium\bfa]
+% \setuphead [subsubsection][style=\mainfacemedium\bf]
+%
+% }
+
+\writestatus{luatex manual}{we assume that dejavu math is available}
+
+\setupbodyfont % assumes dejavu-math
+ [dejavu,10pt]
+
+\setuphead [chapter] [align={flushleft,broad},style=\bfd]
+\setuphead [section] [align={flushleft,broad},style=\bfb]
+\setuphead [subsection] [align={flushleft,broad},style=\bfa]
+\setuphead [subsubsection][align={flushleft,broad},style=\bf]
+
+\setuphead [chapter] [color=maincolor]
+\setuphead [section] [color=maincolor]
+\setuphead [subsection] [color=maincolor]
+\setuphead [subsubsection][color=maincolor]
+
+\definehead
+ [remark]
+ [subsubsubject]
+
+\setupheadertexts
+ []
+
+\definemixedcolumns
+ [twocolumns]
+ [n=2,
+ balance=yes,
+ before=\blank,
+ after=\blank]
+
+\definemixedcolumns
+ [threecolumns]
+ [twocolumns]
+ [n=3]
+
+\definemixedcolumns
+ [fourcolumns]
+ [threecolumns]
+ [n=4]
+
+% if we do this we also need to do it in table cells
+%
+% \setuptyping
+% [color=maincolor]
+%
+% \setuptype
+% [color=maincolor]
+
+\definetyping
+ [functioncall]
+
+\startMPdefinitions
+
+ color luaplanetcolor ; luaplanetcolor := \MPcolor{maincolor} ;
+ color luaholecolor ; luaholecolor := white ;
+ numeric luaextraangle ; luaextraangle := 0 ;
+ numeric luaorbitfactor ; luaorbitfactor := .25 ;
+
+ vardef lualogo = image (
+
+ % Graphic design by A. Nakonechnyj. Copyright (c) 1998, All rights reserved.
+
+ save d, r, p ; numeric d, r, p ;
+
+ d := sqrt(2)/4 ; r := 1/4 ; p := r/8 ;
+
+ fill fullcircle scaled 1
+ withcolor luaplanetcolor ;
+ draw fullcircle rotated 40.5 scaled (1+r)
+ dashed evenly scaled p
+ withpen pencircle scaled (p/2)
+ withcolor (luaorbitfactor * luaholecolor) ;
+ fill fullcircle scaled r shifted (d+1/8,d+1/8)
+ rotated - luaextraangle
+ withcolor luaplanetcolor ;
+ fill fullcircle scaled r shifted (d-1/8,d-1/8)
+ withcolor luaholecolor ;
+ luaorbitfactor := .25 ;
+ ) enddef ;
+
+\stopMPdefinitions
+
+\startuseMPgraphic{luapage}
+ StartPage ;
+
+ fill Page withcolor \MPcolor{othercolor} ;
+
+ luaorbitfactor := 1 ;
+ picture p ; p := lualogo xsized (3PaperWidth/5) ;
+ draw p shifted center Page shifted (0,-.5ypart center ulcorner p) ;
+
+ StopPage ;
+\stopuseMPgraphic
+
+% \starttexdefinition luaextraangle
+% % we can also just access the last page and so in mp directly
+% \ctxlua {
+% context(\lastpage == 0 and 0 or \realfolio*360/\lastpage)
+% }
+% \stoptexdefinition
+
+\startuseMPgraphic{luanumber}
+ % luaextraangle := \luaextraangle;
+ luaextraangle := if (LastPageNumber == 0) : 0 else : (RealPageNumber / LastPageNumber) * 360 fi;
+ luaorbitfactor := 0.25 ;
+ picture p ; p := lualogo ;
+ setbounds p to boundingbox fullcircle ;
+ draw p ysized 1cm ;
+\stopuseMPgraphic
+
+\definelayer
+ [page]
+ [width=\paperwidth,
+ height=\paperheight]
+
+\setupbackgrounds
+ [leftpage]
+ [background=page]
+
+\setupbackgrounds
+ [rightpage]
+ [background=page]
+
+\startsetups pagenumber:right
+ \setlayerframed
+ [page]
+ [preset=rightbottom,offset=1cm]
+ [frame=off,height=1cm,offset=overlay]
+ {\useMPgraphic{luanumber}}
+ \setlayerframed
+ [page]
+ [preset=rightbottom,offset=1cm,x=1.5cm]
+ [frame=off,height=1cm,width=1cm,offset=overlay]
+ {\pagenumber}
+ \setlayerframed
+ [page]
+ [preset=rightbottom,offset=1cm,x=2.5cm]
+ [frame=off,height=1cm,offset=overlay]
+ {\getmarking[chapter]}
+\stopsetups
+
+\startsetups pagenumber:left
+ \setlayerframed
+ [page]
+ [preset=leftbottom,offset=1cm,x=2.5cm]
+ [frame=off,height=1cm,offset=overlay]
+ {\getmarking[chapter]}
+ \setlayerframed
+ [page]
+ [preset=leftbottom,offset=1cm,x=1.5cm]
+ [frame=off,height=1cm,width=1cm,offset=overlay]
+ {\pagenumber}
+ \setlayerframed
+ [page]
+ [preset=leftbottom,offset=1cm]
+ [frame=off,height=1cm,offset=overlay]
+ {\useMPgraphic{luanumber}}
+\stopsetups
+
+\unexpanded\def\nonterminal#1>{\mathematics{\langle\hbox{\rm #1}\rangle}}
+
+% taco's brainwave -) .. todo: create a typing variant so that we can avoid the !crlf
+
+\newcatcodetable\syntaxcodetable
+
+\unexpanded\def\makesyntaxcodetable
+ {\begingroup
+ \catcode`\<=13 \catcode`\|=12
+ \catcode`\!= 0 \catcode`\\=12
+ \savecatcodetable\syntaxcodetable
+ \endgroup}
+
+\makesyntaxcodetable
+
+\unexpanded\def\startsyntax {\begingroup\catcodetable\syntaxcodetable \dostartsyntax}
+\unexpanded\def\syntax {\begingroup\catcodetable\syntaxcodetable \dosyntax}
+ \let\stopsyntax \relax
+
+\unexpanded\def\syntaxenvbody#1%
+ {\par
+ \tt
+ \startnarrower
+ \maincolor #1
+ \stopnarrower
+ \par}
+
+\unexpanded\def\syntaxbody#1%
+ {\begingroup
+ \maincolor \tt #1%
+ \endgroup}
+
+\bgroup \catcodetable\syntaxcodetable
+
+!gdef!dostartsyntax#1\stopsyntax{!let<!nonterminal!syntaxenvbody{#1}!endgroup}
+!gdef!dosyntax #1{!let<!nonterminal!syntaxbody{#1}!endgroup}
+
+!egroup
+
+\definetyping
+ [texsyntax]
+ [color=maincolor]
+
+% end of wave
+
+\setupinteraction
+ [state=start,
+ focus=standard,
+ style=,
+ color=,
+ contrastcolor=]
+
+\placebookmarks
+ [chapter,section,subsection]
+
+\setuplist
+ [chapter,section,subsection,subsubsection]
+ [interaction=all,
+ width=3em]
+
+\setuplist
+ [chapter]
+ [style=bold,
+ color=keptcolor]
+
+\setuplist
+ [subsection,subsubsection]
+ [margin=3em,
+ width=5em]
+
+% Hans doesn't like the bookmarks opening by default so we comment this:
+%
+% \setupinteractionscreen
+% [option=bookmark]
+
+\stopenvironment
diff --git a/Master/texmf-dist/doc/luatex/base/luatex-tex.tex b/Master/texmf-dist/doc/luatex/base/luatex-tex.tex index edf86870c6a..6096b1e77ec 100644 --- a/Master/texmf-dist/doc/luatex/base/luatex-tex.tex +++ b/Master/texmf-dist/doc/luatex/base/luatex-tex.tex @@ -99,70 +99,81 @@ The current list is: \starttabulate[|lT|p|] \NC \rmbf key \NC \bf explanation \NC \NR -\NC pdf_gone \NC written \PDF\ bytes \NC \NR -\NC pdf_ptr \NC not yet written \PDF\ bytes \NC \NR +\NC banner \NC terminal display banner \NC \NR +\NC best_page_break \NC the current best break (a node) \NR \NR +\NC buf_size \NC current allocated size of the line buffer \NC \NR +\NC callbacks \NC total number of executed callbacks so far \NC \NR +\NC cs_count \NC number of control sequences \NC \NR +\NC dest_names_size \NC \PDF\ destination table size \NC \NR \NC dvi_gone \NC written \DVI\ bytes \NC \NR \NC dvi_ptr \NC not yet written \DVI\ bytes \NC \NR -\NC total_pages \NC number of written pages \NC \NR -\NC output_file_name \NC name of the \PDF\ or \DVI\ file \NC \NR -\NC log_name \NC name of the log file \NC \NR -\NC banner \NC terminal display banner \NC \NR -\NC var_used \NC variable (one|-|word) memory in use \NC \NR \NC dyn_used \NC token (multi|-|word) memory in use \NC \NR -\NC str_ptr \NC number of strings \NC \NR -\NC init_str_ptr \NC number of \INITEX\ strings \NC \NR -\NC max_strings \NC maximum allowed strings \NC \NR -\NC pool_ptr \NC string pool index \NC \NR -\NC init_pool_ptr \NC \INITEX\ string pool index \NC \NR -\NC pool_size \NC current size allocated for string characters \NC \NR -\NC node_mem_usage \NC a string giving insight into currently used nodes \NC \NR -\NC var_mem_max \NC number of allocated words for nodes \NC \NR -\NC fix_mem_max \NC number of allocated words for tokens \NC \NR +\NC filename \NC name of the current input file \NC \NR \NC fix_mem_end \NC maximum number of used tokens \NC \NR -\NC cs_count \NC number of control sequences \NC \NR -\NC hash_size \NC size of hash \NC \NR -\NC hash_extra \NC extra allowed hash \NC \NR +\NC fix_mem_min \NC minimum number of allocated words for tokens \NC \NR +\NC fix_mem_max \NC maximum number of allocated words for tokens \NC \NR \NC font_ptr \NC number of active fonts \NC \NR +\NC hash_extra \NC extra allowed hash \NC \NR +\NC hash_size \NC size of hash \NC \NR +\NC indirect_callbacks \NC number of those that were themselves a result of other callbacks (e.g. file readers) \NC \NR +\NC ini_version \NC \type {true} if this is an \INITEX\ run \NC \NR +\NC init_pool_ptr \NC \INITEX\ string pool index \NC \NR +\NC init_str_ptr \NC number of \INITEX\ strings \NC \NR \NC input_ptr \NC th elevel of input we're at \NC \NR +\NC inputid \NC numeric id of the current input \NC \NR +\NC largest_used_mark \NC max referenced marks class \NC \NR +\NC lasterrorcontext \NC last error context string (with newlines) \NC \NR +\NC lasterrorstring \NC last \TEX\ error string \NC \NR +\NC lastluaerrorstring \NC last \LUA\ error string \NC \NR +\NC lastwarningstring \NC last warning tag, normally an indication of in what part\NC \NR +\NC lastwarningtag \NC last warning string\NC \NR +\NC linenumber \NC location in the current input file \NC \NR +\NC log_name \NC name of the log file \NC \NR +\NC luabytecode_bytes \NC number of bytes in \LUA\ bytecode registers \NC \NR +\NC luabytecodes \NC number of active \LUA\ bytecode registers \NC \NR +\NC luastate_bytes \NC number of bytes in use by \LUA\ interpreters \NC \NR +\NC luatex_engine \NC the \LUATEX\ engine identifier \NC \NR +\NC luatex_hashchars \NC length to which \LUA\ hashes strings ($2^n$) \NC \NR +\NC luatex_hashtype \NC the hash method used (in \LUAJITTEX) \NC \NR +\NC luatex_revision \NC the \LUATEX\ revision string \NC \NR +\NC luatex_revision \NC the \LUATEX\ revision string \NC \NR +\NC luatex_version \NC the \LUATEX\ version number \NC \NR +\NC max_buf_stack \NC max used buffer position \NC \NR \NC max_in_stack \NC max used input stack entries \NC \NR \NC max_nest_stack \NC max used nesting stack entries \NC \NR \NC max_param_stack \NC max used parameter stack entries \NC \NR -\NC max_buf_stack \NC max used buffer position \NC \NR \NC max_save_stack \NC max used save stack entries \NC \NR -\NC stack_size \NC input stack size \NC \NR +\NC max_strings \NC maximum allowed strings \NC \NR \NC nest_size \NC nesting stack size \NC \NR -\NC param_size \NC parameter stack size \NC \NR -\NC buf_size \NC current allocated size of the line buffer \NC \NR -\NC save_size \NC save stack size \NC \NR +\NC node_mem_usage \NC a string giving insight into currently used nodes \NC \NR \NC obj_ptr \NC max \PDF\ object pointer \NC \NR \NC obj_tab_size \NC \PDF\ object table size \NC \NR -\NC pdf_os_cntr \NC max \PDF\ object stream pointer \NC \NR -\NC pdf_os_objidx \NC \PDF\ object stream index \NC \NR +\NC output_active \NC \type {true} if the \type {\output} routine is active \NC \NR +\NC output_file_name \NC name of the \PDF\ or \DVI\ file \NC \NR +\NC param_size \NC parameter stack size \NC \NR \NC pdf_dest_names_ptr \NC max \PDF\ destination pointer \NC \NR -\NC dest_names_size \NC \PDF\ destination table size \NC \NR +\NC pdf_gone \NC written \PDF\ bytes \NC \NR \NC pdf_mem_ptr \NC max \PDF\ memory used \NC \NR \NC pdf_mem_size \NC \PDF\ memory size \NC \NR -\NC largest_used_mark \NC max referenced marks class \NC \NR -\NC filename \NC name of the current input file \NC \NR -\NC inputid \NC numeric id of the current input \NC \NR -\NC linenumber \NC location in the current input file \NC \NR -\NC lasterrorstring \NC last \TEX\ error string \NC \NR -\NC lastluaerrorstring \NC last \LUA\ error string \NC \NR -\NC lastwarningtag \NC last warning string\NC \NR -\NC lastwarningstring \NC last warning tag, normally an indication of in what part\NC \NR -\NC lasterrorcontext \NC last error context string (with newlines) \NC \NR -\NC luabytecodes \NC number of active \LUA\ bytecode registers \NC \NR -\NC luabytecode_bytes \NC number of bytes in \LUA\ bytecode registers \NC \NR -\NC luastate_bytes \NC number of bytes in use by \LUA\ interpreters \NC \NR -\NC output_active \NC \type {true} if the \type {\output} routine is active \NC \NR -\NC callbacks \NC total number of executed callbacks so far \NC \NR -\NC indirect_callbacks \NC number of those that were themselves - a result of other callbacks (e.g. file readers) \NC \NR -\NC luatex_version \NC the \LUATEX\ version number \NC \NR -\NC luatex_revision \NC the \LUATEX\ revision string \NC \NR -\NC ini_version \NC \type {true} if this is an \INITEX\ run \NC \NR -\NC shell_escape \NC \type {0} means disabled, \type {1} is restricted and - \type {2} means anything is permitted \NC \NR +\NC pdf_os_cntr \NC max \PDF\ object stream pointer \NC \NR +\NC pdf_os_objidx \NC \PDF\ object stream index \NC \NR +\NC pdf_ptr \NC not yet written \PDF\ bytes \NC \NR +\NC pool_ptr \NC string pool index \NC \NR +\NC pool_size \NC current size allocated for string characters \NC \NR +\NC save_size \NC save stack size \NC \NR +\NC shell_escape \NC \type {0} means disabled, \type {1} is restricted and \type {2} means anything is permitted \NC \NR +\NC safer_option \NC \type {1} means safer is enforced \NC \NR +\NC kpse_used \NC \type {1} means that kpse is used \NC \NR +\NC stack_size \NC input stack size \NC \NR +\NC str_ptr \NC number of strings \NC \NR +\NC total_pages \NC number of written pages \NC \NR +\NC var_mem_max \NC number of allocated words for nodes \NC \NR +\NC var_used \NC variable (one|-|word) memory in use \NC \NR +\NC lc_collate \NC the value of \type {LC_COLLATE} at startup time (becomes \type {C} at startup) \NC \NR +\NC lc_ctype \NC the value of \type {LC_CTYPE} at startup time (becomes \type {C} at startup) \NC \NR +%NC lc_monetary \NC the value of \type {LC_MONETARY} at startup time \NC \NR +\NC lc_numeric \NC the value of \type {LC_NUMERIC} at startup time \NC \NR +%NC lc_time \NC the value of \type {LC_TIME} at startup time (becomes \type {C} at startup) \NC \NR \stoptabulate The error and warning messages can be wiped with the \type {resetmessages} @@ -197,9 +208,7 @@ writable as well as readable (stuff like \type {\tracingcommands} and For all the parameters in this section, it is possible to access them directly using their names as index in the \type {tex} table, or by using one of the -functions \type {tex.get} and \type {tex.set}. If you created aliasses, -you can use accessors like \type {tex.getdimen} as these also understand -names of built|-|in variables. +functions \type {tex.get} and \type {tex.set}. The exact parameters and return values differ depending on the actual parameter, and so does whether \type {tex.set} has any effect. For the parameters that {\it @@ -211,6 +220,16 @@ tex.set (["global",] <string> n, ...) ... = tex.get (<string> n) \stopfunctioncall +Glue is kind of special because there are five values involved. The return value +is a \type {glue_spec} node btu when you pass \type {false} as last argument to +\type {tex.get} you get the width of the glue and when you pass \type {true} you +get all five values. Otherwise you get a node which is a copy of the internal +value so you are responsible for its freeing at the \LUA\ end. When you set a +glue quantity you can either pass a \type {glue_spec} or upto five numbers. + +For the registers you can use \type {getskip} (node), \type {getglue} (numbers) +\type {setskip} (node) and \type {setglue} (numbers). + There are also dedicated setters, getters and checkers: \startfunctioncall @@ -474,10 +493,6 @@ tex.everymath tex.everypar tex.everyvbox tex.output -tex.pdfpageattr -tex.pdfpageresources -tex.pdfpagesattr -tex.pdfpkmode \stoptyping \stopthreecolumns @@ -494,16 +509,10 @@ tex.formatname tex.jobname tex.luatexbanner tex.luatexrevision -tex.pdfnormaldeviate tex.fontname(number) -tex.pdffontname(number) -tex.pdffontobjnum(number) -tex.pdffontsize(number) tex.uniformdeviate(number) tex.number(number) tex.romannumeral(number) -tex.pdfpageref(number) -tex.pdfxformname(number) tex.fontidentifier(number) \stoptyping \stoptwocolumns @@ -530,15 +539,9 @@ tex.lastkern tex.lastskip tex.lastnodetype tex.inputlineno -tex.pdflastobj -tex.pdflastxform -tex.pdflastximage -tex.pdflastximagepages -tex.pdflastannot -tex.pdflastxpos -tex.pdflastypos -tex.pdfrandomseed -tex.pdflastlink +tex.lastxpos +tex.lastypos +tex.randomseed tex.luatexversion tex.eTeXminorversion tex.eTeXversion @@ -547,7 +550,6 @@ tex.currentgrouptype tex.currentiflevel tex.currentiftype tex.currentifbranch -tex.pdflastximagecolordepth \stoptyping \stopthreecolumns @@ -697,7 +699,7 @@ Where the table for \type {mathcode} is an array of 3 numbers, like this: \starttyping { - <number> mathclass, + <number> class, <number> family, <number> character } @@ -717,8 +719,12 @@ And the table for \type {delcode} is an array with 4 numbers, like this: You can also avoid the table: \startfunctioncall +tex.setmathcode (["global"], <number> n, <number> class, + <number> family, <number> character) class, family, char = tex.getmathcodes (<number> n) +tex.setdelcode (["global"], <number> n, <number> smallfam, + <number> smallchar, <number> largefam, <number> largechar) smallfam, smallchar, largefam, largechar = tex.getdelcodes (<number> n) \stopfunctioncall @@ -770,10 +776,13 @@ called xforms in \PDF). You can (re)use the box with \type {\useboxresource} or by creating a rule node with subtype~2. \starttyping -local index = tex.saveboxresource(n,attributes,resources,immediate) +local index = tex.saveboxresource(n,attributes,resources,immediate,type) \stoptyping -The optional second and third arguments are strings, the fourth is a boolean. +The optional second and third arguments are strings, the fourth is a boolean. The +fifth argument is a type. 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}. You can generate the reference (a rule type) with: @@ -912,8 +921,7 @@ The known fields are: \NC head \NC node \NC all \NC the head of the current list \NC \NR \NC tail \NC node \NC all \NC the tail of the current list \NC \NR \NC prevgraf \NC number \NC vmode \NC number of lines in the previous paragraph \NC \NR -\NC prevdepth \NC number \NC vmode \NC depth of the previous paragraph (equal to \type {\pdfignoreddimen} - when it is to be ignored) \NC \NR +\NC prevdepth \NC number \NC vmode \NC depth of the previous paragraph \NC \NR \NC spacefactor \NC number \NC hmode \NC the current space factor \NC \NR \NC dirs \NC node \NC hmode \NC used for temporary storage by the line break algorithm\NC \NR \NC noad \NC node \NC mmode \NC used for temporary storage of a pending fraction numerator, @@ -1157,11 +1165,12 @@ line of error help. for i,v in pairs (tex.hashtokens()) do ... end \stopfunctioncall -Returns a name and token table pair (see~\in {section} [luatokens] about token -tables) iterator for every non-zero entry in the hash table. This can be useful -for debugging, but note that this also reports control sequences that may be -unreachable at this moment due to local redefinitions: it is strictly a dump of -the hash table. +Returns a list of names. This can be useful for debugging, but note that this +also reports control sequences that may be unreachable at this moment due to +local redefinitions: it is strictly a dump of the hash table. You can use \type +{token.create} to inspect properties, for instance when the \type {command} key +in a created table equals \type {123}, you have the \type {cmdname} value \type +{undefined_cs}. \subsection[luaprimitives]{Functions for dealing with primitives } @@ -1250,7 +1259,7 @@ end \NC luatex \NC \ctxlua{document.showprimitives('luatex') } \NC \NR \stoptabulate -Note that \type {'luatex'} does not contain \type {directlua}, as that is +Note that \type {luatex} does not contain \type {directlua}, as that is considered to be a core primitive, along with all the \TEX82 primitives, so it is part of the list that is returned from \type {'core'}. @@ -1260,7 +1269,7 @@ part of the list that is returned from \type {'core'}. Running \type {tex.extraprimitives()} will give you the complete list of primitives \type {-ini} startup. It is exactly equivalent to \type -{tex.extraprimitives('etex' and 'luatex')}. +{tex.extraprimitives("etex","luatex")}. \subsubsection{\type {tex.primitives}} @@ -1268,16 +1277,7 @@ primitives \type {-ini} startup. It is exactly equivalent to \type <table> t = tex.primitives() \stopfunctioncall -This function returns a hash table listing all primitives that \LUATEX\ knows -about. The keys in the hash are primitives names, the values are tables -representing tokens (see~\in{section }[luatokens]). The third value is always -zero. - -{\em In the beginning we had \type {omega} and \type {pdftex} subsets but in the -meantime relevant primitives ave been promoted (either or not adapted) to the -\type {luatex} set when found useful, or removed when considered to be of no use. -Originally we had two sets of math definition primitives but the \OMEGA\ ones -have been removed, so we no longer have a subset for math either.} +This function returns a list of all primitives that \LUATEX\ knows about. \subsection{Core functionality interfaces} @@ -1468,11 +1468,10 @@ values from \type {texmf.cnf} are used. \section{The \type {texio} library} -This library takes care of the low|-|level I/O interface. +This library takes care of the low|-|level I/O interface: writing to the log file +and|/|or console. -\subsection{Printing functions} - -\subsubsection{\type {texio.write}} +\subsection{\type {texio.write}} \startfunctioncall texio.write(<string> target, <string> s, ...) @@ -1489,7 +1488,7 @@ Note: If several strings are given, and if the first of these strings is or migh be one of the targets above, the \type {target} must be specified explicitly to prevent \LUA\ from interpreting the first string as the target. -\subsubsection{\type {texio.write_nl}} +\subsection{\type {texio.write_nl}} \startfunctioncall texio.write_nl(<string> target, <string> s, ...) @@ -1500,32 +1499,23 @@ This function behaves like \type {texio.write}, but make sure that the given strings will appear at the beginning of a new line. You can pass a single empty string if you only want to move to the next line. -\subsubsection{\type {texio.setescape}} +\subsection{\type {texio.setescape}} You can disable \type {^^} escaping of control characters by passing a value of zero. -\section{The \type {token} libray} +\section{The \type {token} library} -The current \type {token} library will be replaced by a new one that is more -flexible and powerful. The transition takes place in steps. In version 0.80 we -have \type {token} and in version 0.85 the old lib will be replaced -completely. So if you use this new mechanism in production code you need to be -aware of incompatible updates between 0.80 and 0.90. Because the related in- and -output code will also be cleaned up and rewritten you should be aware of -incompatible logging and error reporting too. +\subsection{The scanner} -The old library presents tokens as triplets or numbers, the new library presents -a userdata object. The old library used a callback to intercept tokens in the -input but the new library provides a basic scanner infrastructure that can be -used to write macros that accept a wide range of arguments. This interface is on +The token library provides means to intercept the input and deal with it at the +\LUA\ level. The library provides a basic scanner infrastructure that can be used +to write macros that accept a wide range of arguments. This interface is on purpose kept general and as performance is quite ok one can build additional parsers without too much overhead. It's up to macro package writers to see how they can benefit from this as the main principle behind \LUATEX\ is to provide a -minimal set of tools and no solutions. - -The current functions in the \type {token} namespace are given in the next -table: +minimal set of tools and no solutions. The functions provided in the \type +{token} namespace are given in the next table: \starttabulate[|lT|lT|p|] \NC \bf function \NC \bf argument \NC \bf result \NC \NR @@ -1673,11 +1663,7 @@ do) this effect should not be overestimated. For numbers and dimensions it saves bit but for passing strings conversion to and from tokens has to be done anyway (although we can probably speed up the process in later versions if needed). -When the interface is stable and has replaced the old one completely we will add -some more information here. By that time the internals have been cleaned up a bit -more so we know then what will stay and go. A positive side effect of this -transition is that we can simplify the input part because we no longer need to -intercept using callbacks. +\subsection{Macros} The \type {set_macro} function can get upto 4 arguments: @@ -1703,6 +1689,8 @@ The results are like: \def\csname{} \stoptyping +\subsection{Pushing back} + There is a (for now) experimental putter: \starttyping @@ -1719,6 +1707,94 @@ token.put_next ( t3, t4 ) When we scan \type {wxyz!} we get \type {yzwx!} back. The argument is either a table with tokens or a list of tokens. +\subsection{Nota bene} + +When scanning for the next token you need to keep in mind that we're not scanning +like \TEX\ does: expanding, changing modes and doing things as it goes. When we +scan with \LUA\ we just pick up tokens. Say that we have: + +\starttyping +\bar +\stoptyping + +but \type {\bar} is undefined. Normally \TEX\ will then issue an error message. +However, when we have: + +\starttyping +\def\foo{\bar} +\stoptyping + +We get no error, unless we expand \type {\foo} while \type {\bar} is still +undefined. What happens is that as soon as \TEX\ sees an undefined macro it will +create a hash entry and when later it gets defined that entry will be reused. So, +\type {\bar} really exists but can be in an undefined state. + +\startbuffer[demo] +bar : \directlua{tex.print(token.scan_csname())}\bar +foo : \directlua{tex.print(token.scan_csname())}\foo +myfirstbar : \directlua{tex.print(token.scan_csname())}\myfirstbar +\stopbuffer + +\startlines +\getbuffer[demo] +\stoplines + +This was entered as: + +\typebuffer[demo] + +The reason that you see \type {bar} reported and not \type {myfirstbar} is that +\type {\bar} was already used in a previous paragraph. + +If we now say: + +\startbuffer +\def\foo{} +\stopbuffer + +\typebuffer \getbuffer + +we get: + +\startlines +\getbuffer[demo] +\stoplines + +And if we say + +\startbuffer +\def\foo{\bar} +\stopbuffer + +\typebuffer \getbuffer + +we get: + +\startlines +\getbuffer[demo] +\stoplines + +When scanning from \LUA\ we are not in a mode that defines (undefined) macros at +all. There we just get the real primitive undefined macro token. + +\startbuffer +\directlua{local t = token.get_next() tex.print(t.id.." "..t.tok)}\myfirstbar +\directlua{local t = token.get_next() tex.print(t.id.." "..t.tok)}\mysecondbar +\directlua{local t = token.get_next() tex.print(t.id.." "..t.tok)}\mythirdbar +\stopbuffer + +\startlines +\getbuffer +\stoplines + +This was generated with: + +\typebuffer + +So, we do get a unique token because after all we need some kind of \LUA\ object +that can be used and garbage collected, but it is basically the same one, +representing an undefined control sequence. + \section{The \type {kpse} library} This library provides two separate, but nearly identical interfaces to the diff --git a/Master/texmf-dist/doc/luatex/base/luatex.pdf b/Master/texmf-dist/doc/luatex/base/luatex.pdf Binary files differindex 16a6dfe6d81..371478ae4aa 100644 --- a/Master/texmf-dist/doc/luatex/base/luatex.pdf +++ b/Master/texmf-dist/doc/luatex/base/luatex.pdf diff --git a/Master/texmf-dist/doc/luatex/base/luatex.tex b/Master/texmf-dist/doc/luatex/base/luatex.tex index a9524246b9c..1ccc9b7a59a 100644 --- a/Master/texmf-dist/doc/luatex/base/luatex.tex +++ b/Master/texmf-dist/doc/luatex/base/luatex.tex @@ -1,16 +1,36 @@ % macros=mkvi +% author : Hans Hagen +% copyright : PRAGMA ADE & ConTeXt Development Team +% license : Creative Commons Attribution ShareAlike 4.0 International +% reference : pragma-ade.nl | contextgarden.net | texlive (related) distributions +% origin : the ConTeXt distribution +% +% comment : Because this manual is distributed with TeX distributions it comes with a rather +% liberal license. We try to adapt these documents to upgrades in the (sub)systems +% that they describe. Using parts of the content otherwise can therefore conflict +% with existing functionality and we cannot be held responsible for that. Many of +% the manuals contain characteristic graphics and personal notes or examples that +% make no sense when used out-of-context. +% +% comment : Some chapters might have been published in TugBoat, the NTG Maps, the ConTeXt +% Group journal or otherwise. Thanks to the editors for corrections. Also thanks +% to users for testing, feedback and corrections. + % \tex vs \type vs \syntax vs. \luatex % \em \it \/ +% "context --nodates --nocompression luatex" can be used for comparison +% runs, not that we do it + \environment luatex-style \environment luatex-logos \dontcomplain \startdocument - [version=0.95.0, - status=Pre-release] + [status=intermediate release, + version=1.0.4] \component luatex-titlepage |