diff options
| author | Hans Hagen <pragma@wxs.nl> | 2020-03-10 15:42:39 +0100 |
|---|---|---|
| committer | Context Git Mirror Bot <phg@phi-gamma.net> | 2020-03-10 15:42:39 +0100 |
| commit | 0b0256403b7e111df0ecdb8ca589f20df787dacd (patch) | |
| tree | 49b02d80ccbb26aa235351ae3dfd2d099635ea72 /doc | |
| parent | 631a40d69d7fb4e5beff90039d21da5472dd1020 (diff) | |
| download | context-0b0256403b7e111df0ecdb8ca589f20df787dacd.tar.gz | |
2020-03-10 14:47:00
Diffstat (limited to 'doc')
14 files changed, 206 insertions, 160 deletions
diff --git a/doc/context/documents/general/manuals/luametatex.pdf b/doc/context/documents/general/manuals/luametatex.pdf Binary files differindex 95e7786fe..fd83dfb5a 100644 --- a/doc/context/documents/general/manuals/luametatex.pdf +++ b/doc/context/documents/general/manuals/luametatex.pdf diff --git a/doc/context/documents/general/manuals/tools-mkiv.pdf b/doc/context/documents/general/manuals/tools-mkiv.pdf Binary files differindex 6cde31552..81260e3c1 100644 --- a/doc/context/documents/general/manuals/tools-mkiv.pdf +++ b/doc/context/documents/general/manuals/tools-mkiv.pdf diff --git a/doc/context/sources/general/manuals/luametatex/luametatex-callbacks.tex b/doc/context/sources/general/manuals/luametatex/luametatex-callbacks.tex index e3e2a91e1..244c06c2a 100644 --- a/doc/context/sources/general/manuals/luametatex/luametatex-callbacks.tex +++ b/doc/context/sources/general/manuals/luametatex/luametatex-callbacks.tex @@ -16,7 +16,7 @@ \libindex{known} This library has functions that register, find and list callbacks. Callbacks are -\LUA\ functions that are called in well defined places. There are two kind of +\LUA\ functions that are called in well defined places. There are two kinds of callbacks: those that mix with existing functionality, and those that (when enabled) replace functionality. In mosty cases the second category is expected to behave similar to the built in functionality because in a next step specific @@ -408,7 +408,7 @@ If you return something that is not a \type {<node>}, \LUATEX\ will apply the internal linebreak algorithm on the list that starts at \type {<head>}. Otherwise, the \type {<node>} you return is supposed to be the head of a list of nodes that are all allowed in vertical mode, and at least one of those has to -represent a hbox. Failure to do so will result in a fatal error. +represent an \prm {hbox}. Failure to do so will result in a fatal error. Setting this callback to \type {false} is possible, but dangerous, because it is possible you will end up in an unfixable \quote {deadcycles loop}. @@ -417,19 +417,20 @@ possible you will end up in an unfixable \quote {deadcycles loop}. \topicindex{callbacks+contributions} -This callback is called whenever \LUATEX\ adds a box to a vertical list: +This callback is called whenever \LUATEX\ adds a box to a vertical list (the +\type {mirrored} argument is obsolete): \startfunctioncall -function(<node> box, <string> locationcode, <number prevdepth>, - <boolean> mirrored) - return list, prevdepth +function(<node> box, <string> locationcode, <number> prevdepth) + return list [, prevdepth [, checkdepth ] ] end \stopfunctioncall -It is ok to return nothing in which case you also need to flush the box or deal -with it yourself. The prevdepth is also optional. Locations are \type {box}, -\type {alignment}, \type {equation}, \type {equation_number} and \type -{post_linebreak}. +It is ok to return nothing or \type {nil} in which case you also need to flush +the box or deal with it yourself. The prevdepth is also optional. Locations are +\type {box}, \type {alignment}, \type {equation}, \type {equation_number} and +\type {post_linebreak}. When the third argument returned is \type {true} the +normal prevdepth correction will be applied, based on the first node. \subsection{\cbk {post_linebreak_filter}} @@ -739,7 +740,7 @@ function(category,filename) end \stopfunctioncall -This callback replaces the code that prints \LUATEX's when a file is opened like +This callback replaces the code that \LUATEX\ prints when a file is opened like \type {(filename} for regular files. The category is a number: \starttabulate[|c|l|] @@ -762,7 +763,7 @@ function(category) end \stopfunctioncall -This callback replaces the code that prints \LUATEX's when a file is closed like +This callback replaces the code that \LUATEX\ prints when a file is closed like the \type {)} for regular files. \subsection{\cbk {wrapup_run}} diff --git a/doc/context/sources/general/manuals/luametatex/luametatex-differences.tex b/doc/context/sources/general/manuals/luametatex/luametatex-differences.tex index 4ec846b38..35812b13f 100644 --- a/doc/context/sources/general/manuals/luametatex/luametatex-differences.tex +++ b/doc/context/sources/general/manuals/luametatex/luametatex-differences.tex @@ -119,6 +119,11 @@ principle \DVI\ and \PDF\ unaware. There are only generic whatsit nodes that can be used for some management related tasks. For instance you can use them to implement user nodes. +The margin kern nodes are gone and we now use regular kern nodes for them. As a +consequence there are two extra subtypes indicating the injected left or right +kern. The glyph field served no real purpose so there was no reason for a special +kind of node. + The \KPSE\ library is no longer built|-|in. Because there is no backend, quite some file related callbacks could go away. The following file related callbacks remained (till now): diff --git a/doc/context/sources/general/manuals/luametatex/luametatex-enhancements.tex b/doc/context/sources/general/manuals/luametatex/luametatex-enhancements.tex index d70b8f2c0..f295b3464 100644 --- a/doc/context/sources/general/manuals/luametatex/luametatex-enhancements.tex +++ b/doc/context/sources/general/manuals/luametatex/luametatex-enhancements.tex @@ -86,8 +86,8 @@ There are three primitives to test the version of \LUATEX\ (and \LUAMETATEX): \NC the banner reported on the command line \NC \NR \NC \lpr {luatexversion} \NC \the\luatexversion \NC a combination of major and minor number \NC \NR -\NC \lpr {luatexrevision} \NC \luatexrevision - \NC the revision number, the current value is \NC \NR +\NC \lpr {luatexrevision} \NC \the\luatexrevision + \NC the revision number \NC \NR \LL \stoptabulate @@ -97,24 +97,29 @@ A version is defined as follows: \startitem The major version is the integer result of \lpr {luatexversion} divided by 100. The primitive is an \quote {internal variable}, so you may need to prefix - its use with \prm {the} depending on the context. + its use with \prm {the} or \prm {number} depending on the context. \stopitem \startitem - The minor version is the two|-|digit result of \lpr {luatexversion} modulo 100. + The minor version is a number running from 0 upto 99. \stopitem \startitem - The revision is reported by \lpr {luatexrevision}. This primitive expands to - a positive integer. + The revision is reported by \lpr {luatexrevision}. Contrary to other engines + in \LUAMETATEX\ is also a number so one needs to prefix it with \prm {the} or + \prm {number}. \footnote {In the past it always was good to prefix the + revision with \prm {number} anyway, just to play safe, although there have + for instance been times that \PDFTEX\ had funny revision indicators that at + some point ended up as letters due to the internal conversions.} \stopitem \startitem - The full version number consists of the major version, minor version and - revision, separated by dots. + The full version number consists of the major version (\type {X}), minor + version (\type {YY}) and revision (\type {ZZ}), separated by dots, so \type + {X.YY.ZZ}. \stopitem \stopitemize \stopsubsubsection -The \LUAMETATEX\ version number starts at 2 in order to prevent a clash with +The \LUAMETATEX\ version number starts at~2 in order to prevent a clash with \LUATEX, and the version commands are the same. This is a way to indicate that these projects are related. diff --git a/doc/context/sources/general/manuals/luametatex/luametatex-languages.tex b/doc/context/sources/general/manuals/luametatex/luametatex-languages.tex index b6607a9bb..78d739851 100644 --- a/doc/context/sources/general/manuals/luametatex/luametatex-languages.tex +++ b/doc/context/sources/general/manuals/luametatex/luametatex-languages.tex @@ -64,7 +64,8 @@ and finally it adjusts all the subtype identifiers so that the records are \quot {character} and a \quote {font} field, and they lived in the same memory as tokens did. The latter also contained a list of components, and a subtype indicating whether this ligature was the result of a word boundary, and it was -stored in the same place as other nodes like boxes and kerns and glues. +stored in the same place as other nodes like boxes and kerns and glues. In +\LUAMETATEX\ we no longer keep the list of components with the glyph node. In \LUATEX, these two types are merged into one, somewhat larger structure called a \nod {glyph} node. Besides having the old character, font, and component diff --git a/doc/context/sources/general/manuals/luametatex/luametatex-libraries.tex b/doc/context/sources/general/manuals/luametatex/luametatex-libraries.tex index d8210ac48..407544700 100644 --- a/doc/context/sources/general/manuals/luametatex/luametatex-libraries.tex +++ b/doc/context/sources/general/manuals/luametatex/luametatex-libraries.tex @@ -9,7 +9,7 @@ \startsection[title=Introduction] The libraries can be grouped in categories like fonts, languages, \TEX, -\METAPOST, \PDF, etc. There are however also some that are more general puspose +\METAPOST, \PDF, etc. There are however also some that are more general purpose and these are discussed here. \stopsection @@ -33,9 +33,9 @@ work on normal \LUA\ file handles. \NC readinteger3 \NC (f) \NC a 3 byte signed integer \NC \NR \NC readinteger4 \NC (f) \NC a 4 byte signed integer \NC \NR \NC readintegertable \NC (f,n,b) \NC \type {n} integers of \type {b} bytes \NC \NR -\NC readfixed2 \NC (f) \NC a 2 byte float (used in font files) \NC \NR -\NC readfixed4 \NC (f) \NC a 4 byte float (used in font files) \NC \NR -\NC read2dot14 \NC (f) \NC a 2 byte float (used in font files) \NC \NR +\NC readfixed2 \NC (f) \NC a float made from a 2 byte fixed format \NC \NR +\NC readfixed4 \NC (f) \NC a float made from a 4 byte fixed format \NC \NR +\NC read2dot14 \NC (f) \NC a float made from a 2 byte in 2dot4 format \NC \NR \NC setposition \NC (f,p) \NC goto position \type {p} \NC \NR \NC getposition \NC (f) \NC get the current position \NC \NR \NC skipposition \NC (f,n) \NC skip \type {n} positions \NC \NR @@ -45,7 +45,8 @@ work on normal \LUA\ file handles. \stoptabulate When relevant there are also variants that end with \type {le} that do it the -little endian way. +little endian way. The fixed and dot floating points formats are found in font +files and return \LUA\ doubles. A similar set of function as in the \type {fio} library is available in the \type {sio} library: \libidx {sio} {readcardinal1}, \libidx {sio} {readcardinal2}, @@ -268,6 +269,44 @@ These are accompanied by \type {libcerf} functions: \stopsection +\startsection[title=\type{xdecimal}] + +As an experiment \LUAMETATEX\ provides an interface to the \type {decNumber} +library that we have on board for \METAPOST\ anyway. Apart from the usual +support for operators there are some functions. + +\starttabulate[|Tw(12em)|T|T|] +\DB name \BC arguments \BC results \NC \NR +\TB +\NC abs \NC (a) \NC \NC \NR +\NC new \NC ([n or s]) \NC \NC \NR +\NC copy \NC (a) \NC \NC \NR +\NC trim \NC (a) \NC \NC \NR +\NC tostring \NC (a) \NC \NC \NR +\NC tonumber \NC (a) \NC \NC \NR +\NC setprecision \NC (n) \NC \NC \NR +\NC getprecision \NC () \NC \NC \NR +\NC conj \NC (a) \NC \NC \NR +\NC abs \NC (a) \NC \NC \NR +\NC pow \NC (a,b) \NC \NC \NR +\NC sqrt \NC (a) \NC \NC \NR +\NC ln \NC (a) \NC \NC \NR +\NC log \NC (a) \NC \NC \NR +\NC exp \NC (a) \NC \NC \NR +\NC bor \NC (a,b) \NC \NC \NR +\NC bxor \NC (a,b) \NC \NC \NR +\NC band \NC (a,b) \NC \NC \NR +\NC shift \NC (a,b) \NC \NC \NR +\NC rotate \NC (a,b) \NC \NC \NR +\NC minus \NC (a) \NC \NC \NR +\NC plus \NC (a) \NC \NC \NR +\NC min \NC (a,b) \NC \NC \NR +\NC max \NC (a,b) \NC \NC \NR +\LL +\stoptabulate + +\stopsection + \startsection[title=\type{lfs}] The original \type {lfs} module has been adapted a bit to our needs but for @@ -385,7 +424,7 @@ piecemeal: \libidx {string} {utfvalues}, \libidx {string} {utfcharacters}, \type {string.utfcharacters(s)}: a string with a single \UTF-8 token in it \stopitem \startitem - \type {string.cWharacters(s)}: a string containing one byte + \type {string.characters(s)}: a string containing one byte \stopitem \startitem \type {string.characterpairs(s)}: two strings each containing one byte or an @@ -483,7 +522,7 @@ the \type {lua} namespace. \startitem \type {os.gettimeofday} returns the current \quote {\UNIX\ time}, but as a float. Keep in mind that there might be platforms where this function is - available. + not available. \stopitem \startitem @@ -524,7 +563,7 @@ the \type {lua} namespace. \startsection[title={The \type {lua} library functions}] -The \type {lua} library provide some general helpers. +The \type {lua} library provides some general helpers. \startitemize diff --git a/doc/context/sources/general/manuals/luametatex/luametatex-math.tex b/doc/context/sources/general/manuals/luametatex/luametatex-math.tex index ce4fe1544..7f77bbd6d 100644 --- a/doc/context/sources/general/manuals/luametatex/luametatex-math.tex +++ b/doc/context/sources/general/manuals/luametatex/luametatex-math.tex @@ -365,7 +365,7 @@ Now we get: In \LUATEX, the font dimension parameters that \TEX\ used in math typesetting are now accessible via primitive commands. In fact, refactoring of the math engine -has resulted in many more parameters than were not accessible before. +has resulted in turning some hard codes properties into parameters. \starttabulate \DB primitive name \BC description \NC \NR @@ -392,7 +392,7 @@ has resulted in many more parameters than were not accessible before. expressed in \type {percents}, so 60\% is expressed as the integer $60$ \NC \NR \NC \lpr {Umathstackvgap} \NC vertical clearance between the two - elements in a \prm {atop} stack \NC \NR + elements in an \prm {atop} stack \NC \NR \NC \lpr {Umathstacknumup} \NC numerator shift upward in \prm {atop} stack \NC \NR \NC \lpr {Umathstackdenomdown} \NC denominator shift downward in \prm {atop} stack \NC \NR \NC \lpr {Umathfractionrule} \NC the width of the rule in a \prm {over} \NC \NR @@ -625,18 +625,15 @@ with zero being the default behaviour. \stop -Method six omits the surround glue when there is (x)spacing glue present while -method seven does the opposite, the glue is only applied when there is (x)space -glue present too. Anything more fancy, like checking the begining or end of a -paragraph (or edges of a box) would not be robust anyway. If you want that you -can write a callback that runs over a list and analyzes a paragraph. Actually, in -that case you could also inject glue (or set the properties of a math node) -explicitly. So, these modes are in practice mostly useful for special purposes -and experiments (they originate in a tracker item). Keep in mind that this glue -is part of the math node and not always treated as normal glue: it travels with -the begin and end math nodes. Also, method 6 and 7 will zero the skip related -fields in a node when applicable in the first occasion that checks them -(linebreaking or packaging). +Anything more fancy, like checking the beginning or end of a paragraph (or edges +of a box) would not be robust anyway. If you want that you can write a callback +that runs over a list and analyzes a paragraph. Actually, in that case you could +also inject glue (or set the properties of a math node) explicitly. So, these +modes are in practice mostly useful for special purposes and experiments (they +originate in a tracker item). Keep in mind that this glue is part of the math +node and not always treated as normal glue: it travels with the begin and end +math nodes. Also, method 6 and 7 will zero the skip related fields in a node when +applicable in the first occasion that checks them (linebreaking or packaging). \subsection{Pairwise spacing and \lpr {Umath...spacing} commands} @@ -726,7 +723,7 @@ like this: They are all initialized by \type {initex} to the values mentioned in the table in Chapter~18 of the \TEX book. -Note 1: for ease of use as well as for backward compatibility, \prm {thinmuskip}, +Note 1: For ease of use as well as for backward compatibility, \prm {thinmuskip}, \prm {medmuskip} and \prm {thickmuskip} are treated specially. In their case a pointer to the corresponding internal parameter is saved, not the actual \prm {muskip} value. This means that any later changes to one of these three @@ -771,9 +768,9 @@ $ The \type {\frozen} prefix does the magic: it injects information in the math list about the set parameter. -In \LUATEX\ 1.10 the last setting, the \type {10pt} drop wins, but in +In \LUATEX\ 1.10+ the last setting, the \type {10pt} drop wins, but in \LUAMETATEX\ you will see each local setting taking effect. The implementation -uses a new node type, parameters nodes, so you you might encounter these in an +uses a new node type, parameters nodes, so you might encounter these in an unprocessed math list. The result looks as follows: \blank \getbuffer \blank @@ -896,7 +893,7 @@ math is bound to fuzzy rules. So, control is the solution. If you want to typeset text in math macro packages often provide something \type {\text} which obeys the script sizes. As the definition can be anything there is a good chance that the kerning doesn't come out well when used in a script. Given -that the first glyph ends up in a \prm {hbox} we have some control over this. +that the first glyph ends up in an \prm {hbox} we have some control over this. And, as a bonus we also added control over the normal sublist kerning. The \lpr {mathscriptboxmode} parameter defaults to~1. @@ -906,7 +903,7 @@ And, as a bonus we also added control over the normal sublist kerning. The \lpr \NC \type {0} \NC forget about kerning \NC \NR \NC \type {1} \NC kern math sub lists with a valid glyph \NC \NR \NC \type {2} \NC also kern math sub boxes that have a valid glyph \NC \NR -\NC \type {2} \NC only kern math sub boxes with a boundary node present\NC \NR +\NC \type {3} \NC only kern math sub boxes with a boundary node present\NC \NR \LL \stoptabulate @@ -1259,7 +1256,7 @@ The vertical placements are controlled by \lpr {Umathunderdelimiterbgap}, \lpr The superscript in \lpr {Uoverdelimiter} is typeset in a suitable scripted style, the subscript in \lpr {Uunderdelimiter} is cramped as well. -These primitives accepts an option \type {width} specification. When used the +These primitives accepts an optional \type {width} specification. When used the also optional keywords \type {left}, \type {middle} and \type {right} will determine what happens when a requested size can't be met (which can happen when we step to successive larger variants). @@ -1360,11 +1357,11 @@ For Latin Modern the result looks as follows: Normally you will force delimiters to certain sizes by putting an empty box or rule next to it. The resulting delimiter will either be a character from the stepwise size range or an extensible. The latter can be quite differently -positioned than the characters as it depends on the fit as well as the fact if -the used characters in the font have depth or height. Commands like (plain \TEX -s) \type {\big} need use this feature. In \LUATEX\ we provide a bit more control -by three variants that support optional parameters \type {height}, \type {depth} -and \type {axis}. The following example uses this: +positioned than the characters as it depends on the fit as well as the fact +whether the used characters in the font have depth or height. Commands like +(plain \TEX s) \type {\big} need to use this feature. In \LUATEX\ we provide a bit +more control by three variants that support optional parameters \type {height}, +\type {depth} and \type {axis}. The following example uses this: \startbuffer \Uleft height 30pt depth 10pt \Udelimiter "0 "0 "000028 @@ -1429,7 +1426,7 @@ will return: [2] [3] [4] \stoptyping -These commands are provides as convenience. Before they come available you could +These commands are provided as convenience. Before they come available you could do the following: \starttyping @@ -1511,7 +1508,7 @@ $ $ \stopbuffer -\typebuffer +\typebuffer[script] results in \inlinebuffer[script]. @@ -1534,7 +1531,7 @@ requested math family is used. \topicindex {math+flattening} The \TEX\ math engine collapses \type {ord} noads without sub- and superscripts -and a character as nucleus. and which has the side effect that in \OPENTYPE\ mode +and a character as nucleus, which has the side effect that in \OPENTYPE\ mode italic corrections are applied (given that they are enabled). \startbuffer[sample] diff --git a/doc/context/sources/general/manuals/luametatex/luametatex-metapost.tex b/doc/context/sources/general/manuals/luametatex/luametatex-metapost.tex index 6cee0f493..bd9189956 100644 --- a/doc/context/sources/general/manuals/luametatex/luametatex-metapost.tex +++ b/doc/context/sources/general/manuals/luametatex/luametatex-metapost.tex @@ -30,8 +30,8 @@ To create a new \METAPOST\ instance, call <mpinstance> mp = mplib.new({...}) \stopfunctioncall -This creates the \type {mp} instance object. The argument hash can have a number -of different fields, as follows: +This creates the \type {mp} instance object. The argument is a hash table that +can have a number of different fields, as follows: \starttabulate[|l|l|pl|pl|] \DB name \BC type \BC description \BC default \NC \NR @@ -236,10 +236,10 @@ object! When the boundingbox represents a \quote {negated rectangle}, i.e.\ when the first set of coordinates is larger than the second set, the picture is empty. -Graphical objects come in various types that each has a different list of -accessible values. The types are: \type {fill}, \type {outline}, \type {text}, -\type {start_clip}, \type {stop_clip}, \type {start_bounds}, \type {stop_bounds}, -\type {special}. +Graphical objects come in various types: \type {fill}, \type {outline}, \type +{text}, \type {start_clip}, \type {stop_clip}, \type {start_bounds}, \type +{stop_bounds}, \type {special}. Each type has a different list of accessible +values. There is a helper function (\type {mplib.fields(obj)}) to get the list of accessible values for a particular object, but you can just as easily use the @@ -395,9 +395,9 @@ ordering in \POSTSCRIPT, where the translation comes last. \subsection{Dashes} -Each \type {dash} is two-item hash, using the same model as \POSTSCRIPT\ for the -representation of the dashlist. \type {dashes} is an array of \quote {on} and -\quote {off}, values, and \type {offset} is the phase of the pattern. +Each \type {dash} is a hash with two items. We use the same model as \POSTSCRIPT\ +for the representation of the dashlist. \type {dashes} is an array of \quote {on} +and \quote {off}, values, and \type {offset} is the phase of the pattern. \starttabulate[|l|l|p|] \DB field \BC type \BC explanation \NC \NR diff --git a/doc/context/sources/general/manuals/luametatex/luametatex-nodes.tex b/doc/context/sources/general/manuals/luametatex/luametatex-nodes.tex index 16c6e1202..50356da42 100644 --- a/doc/context/sources/general/manuals/luametatex/luametatex-nodes.tex +++ b/doc/context/sources/general/manuals/luametatex/luametatex-nodes.tex @@ -459,7 +459,7 @@ fields: \showfields {glyph}. \NC \type{left} \NC number \NC the frozen \type {\lefthyphenmnin} value \NC \NR \NC \type{right} \NC number \NC the frozen \type {\righthyphenmnin} value \NC \NR \NC \type{uchyph} \NC boolean \NC the frozen \prm {uchyph} value \NC \NR -\NC \type{components} \NC node \NC pointer to ligature components \NC \NR +\NC \type{state} \NC number \NC a user field (replaces the component list) \NC \NR \NC \type{xoffset} \NC number \NC a virtual displacement in horizontal direction \NC \NR \NC \type{yoffset} \NC number \NC a virtual displacement in vertical direction \NC \NR \NC \type{width} \NC number \NC the (original) width of the character \NC \NR @@ -472,10 +472,7 @@ fields: \showfields {glyph}. The \type {width}, \type {height} and \type {depth} values are read|-|only. The \type {expansion_factor} is assigned in the par builder and used in the backend. - -A warning: never assign a node list to the components field unless you are sure -its internal link structure is correct, otherwise an error may be result. Valid -bits for the \type {subtype} field are: +Valid bits for the \type {subtype} field are: \starttabulate[|c|l|] \DB bit \BC meaning \NC \NR @@ -583,26 +580,6 @@ directions. \stopsubsection -\startsubsection[title={\nod {marginkern} nodes}] - -\topicindex {nodes+paragraphs} -\topicindex {paragraphs} -\topicindex {protrusion} - -Margin kerns result from protrusion and have: \showfields {margin_kern}. - -\starttabulate[|l|l|p|] -\DB field \BC type \BC explanation \NC \NR -\TB -\NC \type{subtype} \NC number \NC \showsubtypes{marginkern} \NC \NR -\NC \type{attr} \NC node \NC list of attributes \NC \NR -\NC \type{width} \NC number \NC the advance of the kern \NC \NR -\NC \type{glyph} \NC node \NC the glyph to be used \NC \NR -\LL -\stoptabulate - -\stopsubsection - \startsubsection[title={Whatsits}] A whatsit node is a real simple one and it only has a subtype. It is even less @@ -950,8 +927,7 @@ positives. The general approach to a node related callback is as follows: \startitem When you remove a node, make sure that when this is permanent, you also free - the node or list. When you free a node its components are checked and when - they are nodes themselves they are also freed. + the node or list. \stopitem \startitem @@ -2149,7 +2125,6 @@ emulated in \LUA\ and not in the engine, so we retain downward compatibility. %supported {find_node} \nop \yes \relax \supported {first_glyph} \nop \yes \yes \supported {flatten_discretionaries} \nop \yes \yes -%supported {flush_components} \nop \yes \relax \supported {flush_list} \yes \yes \relax \supported {flush_node} \yes \yes \relax \supported {free} \yes \yes \relax @@ -2160,7 +2135,7 @@ emulated in \LUA\ and not in the engine, so we retain downward compatibility. \supported {getboth} \nop \yes \relax \supported {getbox} \nop \yes \relax \supported {getchar} \nop \yes \relax -\supported {getcomponents} \nop \yes \relax +\supported {getstate} \nop \yes \relax \supported {getdata} \nop \yes \relax \supported {getdepth} \nop \yes \relax \supported {getdirection} \nop \yes \relax @@ -2228,7 +2203,7 @@ emulated in \LUA\ and not in the engine, so we retain downward compatibility. \supported {setboth} \nop \yes \relax \supported {setbox} \nop \yes \relax \supported {setchar} \nop \yes \relax -\supported {setcomponents} \nop \yes \relax +\supported {setstate} \nop \yes \relax \supported {setdata} \nop \yes \relax \supported {setdepth} \nop \yes \relax \supported {setdirection} \nop \yes \relax @@ -2291,7 +2266,7 @@ sections that describe node properties. Some of the getters and setters handle multiple node types, given that the field is relevant. In that case, some field names are considered similar (like \type -{kern} and \type {width}, or \type {data} and \type {value}. In retrospect we +{kern} and \type {width}, or \type {data} and \type {value}). In retrospect we could have normalized field names better but we decided to stick to the original (internal) names as much as possible. After all, at the \LUA\ end one can easily create synonyms. @@ -2372,10 +2347,10 @@ This is experimental code and might take a while to become frozen. \libindex{set_properties_mode} Attributes are a convenient way to relate extra information to a node. You can -assign them at the \TEX\ end as well as at the \LUA\ end and and consult them at -the \LUA\ end. One big advantage is that they obey grouping. They are linked -lists and normally checking for them is pretty efficient, even if you use a lot -of them. A macro package has to provide some way to manage these attributes at the +assign them at the \TEX\ end as well as at the \LUA\ end and consult them at the +\LUA\ end. One big advantage is that they obey grouping. They are linked lists +and normally checking for them is pretty efficient, even if you use a lot of +them. A macro package has to provide some way to manage these attributes at the \TEX\ end because otherwise clashes in their usage can occur. Each node also can have a properties table and you can assign values to this @@ -2502,7 +2477,7 @@ as property, the new node will share that table. If the second argument of \typ copy gets its own table with the original table as metatable. If you use the generic font loader the mode is enabled that way. -A few more xperiments were done. For instance: copy attributes to the properties +A few more experiments were done. For instance: copy attributes to the properties so that we have fast access at the \LUA\ end. In the end the overhead is not compensated by speed and convenience, in fact, attributes are not that slow when it comes to accessing them. So this was rejected. diff --git a/doc/context/sources/general/manuals/luametatex/luametatex-pdf.tex b/doc/context/sources/general/manuals/luametatex/luametatex-pdf.tex index 3e2150053..79653fdf8 100644 --- a/doc/context/sources/general/manuals/luametatex/luametatex-pdf.tex +++ b/doc/context/sources/general/manuals/luametatex/luametatex-pdf.tex @@ -148,7 +148,7 @@ The other two root dictionaries are accessed with: \libindex {getbox} A specific page can conveniently be reached with the next command, which -returns a dictionary. The first argument is to be a page dictionary. +returns a dictionary. \starttyping <pdfe dictionary> = pdfe.getpage(<pdfe document>,pagenumber) @@ -185,7 +185,7 @@ n = getname (<pdfe array|dictionary>,index|key) \stopsubsection -\startsubsection[title={\type {get[from][dictionary|array|stream]}}] +\startsubsection[title={\type {get[dictionary|array|stream]}}] \libindex {getdictionary} \libindex {getfromdictionary} \libindex {getarray} \libindex {getfromarray} @@ -333,7 +333,7 @@ query. \libindex {new} -The \type {pdfe.new} that takes three arguments: +The \type {pdfe.new} function takes three arguments: \starttabulate \DB value \BC explanation \NC \NR @@ -343,12 +343,11 @@ The \type {pdfe.new} that takes three arguments: \NC \type {length} \NC this is the length of the stream in bytes (the stream can have embedded zeros) \NC \NR \NC \type {name} \NC optional, this is a unique identifier that is used for - hashing the stream, so that multiple doesn't use more - memory \NC \NR + hashing the stream \NC \NR \LL \stoptabulate -The third argument is optional. When it is not given the function will return an +The third argument is optional. When it is not given the function will return a \type {pdfe} document object as with a regular file, otherwise it will return a filename that can be used elsewhere (e.g.\ in the image library) to reference the stream as pseudo file. @@ -357,7 +356,7 @@ Instead of a light userdata stream (which is actually fragile but handy when you come from a library) you can also pass a \LUA\ string, in which case the given length is (at most) the string length. -The function returns an \type {pdfe} object and a string. The string can be used in +The function returns a \type {pdfe} 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). diff --git a/doc/context/sources/general/manuals/luametatex/luametatex-primitives.tex b/doc/context/sources/general/manuals/luametatex/luametatex-primitives.tex index 9e26c6bc4..187bbd85a 100644 --- a/doc/context/sources/general/manuals/luametatex/luametatex-primitives.tex +++ b/doc/context/sources/general/manuals/luametatex/luametatex-primitives.tex @@ -18,7 +18,7 @@ generic constructs (like box resources and directions) to core functionality. Some of the \PDFTEX\ support primitives have been around from the start but when \LUA\ integration became better and when a token scanner library was added, not all of those made sense as primitives. In previous chapters we already mentioned -what is gone from the core. Deep down some more has changes but not all is +what is gone from the core. Deep down some more has changed but not all is reflected at the primitive level. Because there is still a considerable amount of new primitives, a summary is given below. diff --git a/doc/context/sources/general/manuals/luametatex/luametatex-tex.tex b/doc/context/sources/general/manuals/luametatex/luametatex-tex.tex index 25f70dd2f..737f3b960 100644 --- a/doc/context/sources/general/manuals/luametatex/luametatex-tex.tex +++ b/doc/context/sources/general/manuals/luametatex/luametatex-tex.tex @@ -24,7 +24,7 @@ This library contains two read|-|only items: <string> s = lua.startupfile \stoptyping -This returns the \LUA\ version identifier string. The value is currently +This returns the \LUA\ version identifier string. The value currently is \directlua {tex.print(lua.version)}. \stopsubsection @@ -120,7 +120,7 @@ If you want to unset a \LUA\ name, you can assign \type {nil} to it. The functio accessors are: \startfunctioncall -lua.setluaname(<string> s,<number> n]) +lua.setluaname(<string> s,<number> n) <string> s = lua.getluaname(<number> n) \stopfunctioncall @@ -305,9 +305,7 @@ is a \nod {glue_spec} node but 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 \nod {glue_spec} or upto five numbers. If -you pass \type {true} to \type {get} you get 5 values returned for a glue and -when you pass \type {false} you only get the width returned. +glue quantity you can either pass a \nod {glue_spec} or upto five numbers. \subsubsection{Integer parameters} @@ -738,10 +736,10 @@ nodes, and toks by strings. Again the glue variants are not using the \nod {glue-spec} userdata nodes. The \type {setglue} function accepts upto 5 arguments: width, stretch, shrink, stretch order and shrink order and the \type {getglue} function reports them, -unless the second argument is \type {false} in which care only the width is +unless the second argument is \type {false} in which case only the width is returned. -Here is an example usign a threesome: +Here is an example using a threesome: \startfunctioncall local d = tex.getdimen("foo") @@ -1207,7 +1205,7 @@ makes it suitable for use as a partial line input mechanism: from eating spaces as result of interpreting the line. For example, in \starttyping - before\directlua{tex.sprint("\\relax")tex.sprint(" inbetween")}after + before\directlua{tex.sprint("\\relax")tex.sprint(" in between")}after \stoptyping the space before \type {in between} will be gobbled as a result of the \quote @@ -1426,7 +1424,7 @@ which can be shortcut to: tex.setlinenumber(10,true) \stopfunctioncall -This might be handy when you have a callback that read numbers from a file and +This might be handy when you have a callback that reads numbers from a file and combines them in one line (in which case an error message probably has to refer to the original line). Interference with \TEX's internal handling of numbers is of course possible. @@ -1470,7 +1468,7 @@ currently associated with it. \libindex{setinteraction} \libindex{getinteraction} -The engine can in one of four modes: +The engine can be in one of four modes: \starttabulate[|lT|l|pl|] \DB value \NC mode \BC meaning \NC \NR @@ -1862,7 +1860,7 @@ debugging and the (relative state) numbers can change with the implementation. For practical reasons \LUATEX\ has its own random number generator. The original \LUA\ random function is available as \typ {tex.lua_math_random}. You can initialize with a new seed with \type {init_rand} (\typ {lua_math_randomseed} is -equivalent to this one. +equivalent to this one). There are three generators: \type {normal_rand} (no argument is used), \type {uniform_rand} (takes a number that will get rounded before being used) and \type @@ -1989,7 +1987,7 @@ texio.write_nl(<string> target, <string> s, ...) texio.write_nl(<string> s, ...) \stopfunctioncall -This function behaves like \type {texio.write}, but make sure that the given +This function behaves like \type {texio.write}, but makes 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. @@ -2008,11 +2006,11 @@ zero. \libindex{closeinput} -This function that should be used with care. It acts as \prm {endinput} but at -the \LUA\ end. You can use it to (sort of) force a jump back to \TEX. Normally a -\LUA\ will just collect prints and at the end bump an input level and flush these -prints. This function can help you stay at the current level but you need to know -what you're doing (or more precise: what \TEX\ is doing with input). +This function should be used with care. It acts as \prm {endinput} but at the +\LUA\ end. You can use it to (sort of) force a jump back to \TEX. Normally a +\LUA\ call will just collect prints and at the end bump an input level and flush +these prints. This function can help you stay at the current level but you need +to know what you're doing (or more precise: what \TEX\ is doing with input). \stopsubsection @@ -2043,7 +2041,7 @@ what you're doing (or more precise: what \TEX\ is doing with input). 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 +purpose kept general and as performance is quite okay so 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 scanner functions are probably the @@ -2060,9 +2058,9 @@ most intriguing. \NC \type{scan_int} \NC \NC returns an integer \NC \NR \NC \type{scan_real} \NC \NC returns a number from e.g.\ \type {1}, \type {1.1}, \type {.1} with optional collapsed signs \NC \NR \NC \type{scan_float} \NC \NC returns a number from e.g.\ \type {1}, \type {1.1}, \type {.1}, \type {1.1E10}, , \type {.1e-10} with optional collapsed signs \NC \NR -\NC \type{scan_dimen} \NC infinity, mu-units \NC returns a number representing a dimension and or two numbers being the filler and order \NC \NR +\NC \type{scan_dimen} \NC infinity, mu-units \NC returns a number representing a dimension or two numbers being the filler and order \NC \NR \NC \type{scan_glue} \NC mu-units \NC returns a glue spec node \NC \NR -\NC \type{scan_toks} \NC definer, expand \NC returns a table of tokens tokens \NC \NR +\NC \type{scan_toks} \NC definer, expand \NC returns a table of tokens \NC \NR \NC \type{scan_code} \NC bitset \NC returns a character if its category is in the given bitset (representing catcodes) \NC \NR \NC \type{scan_string} \NC \NC returns a string given between \type {{}}, as \type {\macro} or as sequence of characters with catcode 11 or 12 \NC \NR \NC \type{scan_argument} \NC \NC this one is simular to \type {scanstring} but also accepts a \type {\cs} @@ -2074,7 +2072,7 @@ most intriguing. \stoptabulate The scanners can be considered stable apart from the one scanning for a token. -The \type {scan_code} function takes an optional number, the \type {keyword} +The \type {scan_code} function takes an optional number, the \type {scan_keyword} function a normal \LUA\ string. The \type {infinity} boolean signals that we also permit \type {fill} as dimension and the \type {mu-units} flags the scanner that we expect math units. When scanning tokens we can indicate that we are defining a @@ -2236,7 +2234,7 @@ primitive. The possible properties of tokens are: \NC \type {command} \NC a number representing the internal command number \NC \NR \NC \type {cmdname} \NC the type of the command (for instance the catcode in case of a character or the classifier that determines the internal - treatment \NC \NR + treatment) \NC \NR \NC \type {csname} \NC the associated control sequence (if applicable) \NC \NR \NC \type {id} \NC the unique id of the token \NC \NR \NC \type {tok} \NC the full token number as stored in \TEX \NC \NR @@ -2378,9 +2376,31 @@ token.put_next { t1, t2 } token.put_next ( t3, t4 ) \stoptyping -When we scan \type {wxyz!} we get \type {yzwx!} back. The argument is either a table -with tokens or a list of tokens. The \type {token.expand} function will trigger -expansion but what happens really depends on what you're doing where. +When we scan \type {wxyz!} we get \type {yzwx!} back. The argument is either a +table with tokens or a list of tokens. The \type {token.expand} function will +trigger expansion but what happens really depends on what you're doing where. + +This putter is actually a bit more flexible because the following input also +works out okay: + +\startbuffer +\def\foo#1{[#1]} + +\directlua { + local list = { 101, 102, 103, token.create("foo"), "{abracadabra}" } + token.put_next("(the)") + token.put_next(list) + token.put_next("(order)") + token.put_next(unpack(list)) + token.put_next("(is reversed)") +} +\stopbuffer + +\typebuffer + +We get this: \blank {\tt \inlinebuffer} \blank So, strings get converted to +individual tokens according to the current catcode regime and numbers become +characters also according to this regime. \stopsubsection @@ -2390,6 +2410,8 @@ When scanning for the next token you need to keep in mind that we're not scannin 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: +\pushmacro\bar \let\bar\undefined + \starttyping \bar \stoptyping @@ -2472,6 +2494,8 @@ 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. +\popmacro\bar + \stopsubsection \stopsection diff --git a/doc/context/sources/general/manuals/tools/tools-mkiv.tex b/doc/context/sources/general/manuals/tools/tools-mkiv.tex index 949a878ca..cd5214b3f 100644 --- a/doc/context/sources/general/manuals/tools/tools-mkiv.tex +++ b/doc/context/sources/general/manuals/tools/tools-mkiv.tex @@ -373,8 +373,8 @@ following: For quite a while we shipped so called \CONTEXT\ minimals. These zip files contained only the resources and programs that made sense for running \CONTEXT. Nowadays the minimals are installed and synchronized via internet. \footnote -{This project was triggered by Mojca Miklavec who is also charge of this bit of -the \CONTEXT\ infrastructure. More information can be found at \type +{This project was triggered by Mojca Miklavec who is also in charge of this bit +of the \CONTEXT\ infrastructure. More information can be found at \type {contextgarden.net}.} You can just run the installer again and no additional commands are needed. In the console you will see several calls to \sMTXRUN\ and \sLUATOOLS\ fly by. @@ -415,7 +415,7 @@ run. \typefile[ntyping]{tools-mkiv-help.tmp} -There are few exert options too: +There are few expert options too: \ctxlua{os.execute("context --expert > tools-mkiv-help.tmp")} @@ -451,7 +451,7 @@ a similar was as \TEX\ files. \startsection[title={Stubs}] -As the tools are written in the \LUA\ language we need a \LUA\ interpreter and or +As the tools are written in the \LUA\ language we need a \LUA\ interpreter and of course we use \LUATEX\ itself. On \UNIX\ we can copy \sLUATOOLS\ and \sMTXRUN\ to files in the binary path with the same name but without suffix. Starting them in another way is a waste of time, especially when \sKPSEWHICH\ is used to find @@ -498,12 +498,11 @@ mtxrun.exe You can copy \type {mtxrun.exe} to for instance \type {context.exe} and it will still use \sMTXRUN\ for locating the right script. It also takes care of mapping \sTEXMFSTART\ to \sMTXRUN. So we've removed the intermediate \type {cmd} step, -can not run the script as any program, and most of all, we're as efficient as can -be. Of course this program is only meaningful for the \CONTEXT\ approach to -tools. +can run the script as any program, and most of all, we're as efficient as can be. +Of course this program is only meaningful for the \CONTEXT\ approach to tools. It may all sound more complex than it is but once it works users will not notice -those details. Als, in practice not that much has changed in running the tools +those details. Also, in practice not that much has changed in running the tools between \MKII\ and \MKIV\ as we've seen no reason to change the methods. \stopsection @@ -562,11 +561,10 @@ Much of the code inside \MKIV\ can alter its behaviour based on either \quote alternate behaviour). Since this also affects the \LUA\ code within \sMTXRUN\ itself, it makes sense to list these options first. -Getting information on trackers, directives and experiments. Trackers enable more -extensive status messages on the console or in \CONTEXT\ additional visual clues. -Directives change behaviour that are not part of the official interface and have -no corresponding commands. Experiments are like directives but not official -(yet). +Trackers enable more extensive status messages on the console or in \CONTEXT\ +additional visual clues. Directives change behaviour that is not part of the +official interface and have no corresponding commands. Experiments are like +directives but not official (yet). \startoptions \option @@ -615,7 +613,7 @@ a challenge. Explaining the details of all the directives is outside of the scop of this article, but you can look them up in the \CONTEXT\ source by searching for \typ {directives.register} and \typ {trackers.register}. -In verbose mode, \sMTXRUN\ itself gives more messages, and it also \typ +In verbose mode, \sMTXRUN\ itself gives more messages, and it also enables \typ {resolvers.locating}, which is a tracker itself: \startoptions @@ -671,11 +669,13 @@ and: {use given texmf tree (default file: \type {setuptex.tmf})} \stopoptions +We don't provide such a \type {.tmf} file in the distribution. + \stopsubsection \startsubsection[title=Options for finding files and reporting configurations] -Once the configuration setup is done, it makes sense to have a bunch or options +Once the configuration setup is done, it makes sense to have a bunch of options to use and|/|or query the configuration. \startoptions @@ -808,7 +808,7 @@ scripts, and \type {<name>.lua} is just a last-ditch effort if nothing else works. Scripts are looked for in the local path, and in whatever directories the configuration variable \type {LUAINPUTS} points to. -The \type {--execute} options exists mostly for the non||\LUA\ {\MKII} scripts +The \type {--execute} option exists mostly for the non||\LUA\ {\MKII} scripts that still exist in the distribution. It will try to find a matching interpreter for non||\LUA\ scripts, and it is aware of a number of distribution||supplied scripts so that if you specify \type {--execute texexec}, it knows that what you @@ -1211,7 +1211,7 @@ function scripts.envtest.runtest() end \stoptyping -An finally, identify the current script, followed by handling the provided +And finally, identify the current script, followed by handling the provided options (usually with an \type {if}||\type {else} statement). \starttyping @@ -1229,11 +1229,11 @@ end \startsubsection[title=Script environment] \sMTXRUN\ includes lots of the internal \LUA\ helper libraries from \CONTEXT. We -actually maintains a version of the script without all those libraries included, +actually maintain a version of the script without all those libraries included, and before every (beta) \CONTEXT\ release, an amalgamated version of \sMTXRUN\ is -added to the distribution. In the merging process, most all comments are stripped -from the embedded libraries, so if you want to know details, it is better to look -in the original \LUA\ source file. +added to the distribution. In the merging process, all comments are stripped from +the embedded libraries, so if you want to know details, it is better to look in +the original \LUA\ source file. Inside \sMTXRUN, the full list of embedded libraries can be queried via the array \type {own.libs}: @@ -1259,8 +1259,8 @@ embedded libraries (\type {own.list}), which is used by the \type {--selfmerge} option and also allows the non||amalgamated version to run (since otherwise \type {--selfmerge} could not be bootstrapped). -\sMTXRUN\ offers a programming environment that makes it easy to write \LUA\ a -scripts. The most important element of that environment is a \LUA\ table that is +\sMTXRUN\ offers a programming environment that makes it easy to write \LUA\ +script. The most important element of that environment is a \LUA\ table that is conveniently called \type {environment} (\type {util-env} does the actual work of setting that up). @@ -1379,7 +1379,7 @@ As well as some functions: {Locates and compiles a \LUA\ file, returning its contents as data.} \mtxrunenv {make_format(name,arguments)} - {Creates a format file and stores in in the \CONTEXT\ cache, used by \type + {Creates a format file and stores it in the \CONTEXT\ cache, used by \type {mtxrun --make}.} \mtxrunenv {relativepath(path,root)} |