diff options
Diffstat (limited to 'doc')
11 files changed, 589 insertions, 396 deletions
diff --git a/doc/context/documents/general/manuals/lowlevel-paragraphs.pdf b/doc/context/documents/general/manuals/lowlevel-paragraphs.pdf Binary files differindex bde7fda14..ab46092b2 100644 --- a/doc/context/documents/general/manuals/lowlevel-paragraphs.pdf +++ b/doc/context/documents/general/manuals/lowlevel-paragraphs.pdf diff --git a/doc/context/documents/general/manuals/luametatex.pdf b/doc/context/documents/general/manuals/luametatex.pdf Binary files differindex 66c65f995..98b6466b8 100644 --- a/doc/context/documents/general/manuals/luametatex.pdf +++ b/doc/context/documents/general/manuals/luametatex.pdf diff --git a/doc/context/sources/general/manuals/lowlevel/lowlevel-paragraphs.tex b/doc/context/sources/general/manuals/lowlevel/lowlevel-paragraphs.tex index 3098333f0..a15ddb622 100644 --- a/doc/context/sources/general/manuals/lowlevel/lowlevel-paragraphs.tex +++ b/doc/context/sources/general/manuals/lowlevel/lowlevel-paragraphs.tex @@ -907,6 +907,69 @@ keyword in the next code. The result is shown in \in {figure} [fig:shape:skips]. \stopcombination \stopplacefigure +The shape mechanism has a few more tricks but these are really meant for usage +in specific situations, where one knows what one deals with. The following +examples are visualized in \in {figure} [fig:flow]. + +\startbuffer[jano] +\useMPlibrary[dum] +\usemodule[article-basics] + +\startbuffer + \externalfigure[dummy][width=6cm] +\stopbuffer + +\startshapedparagraph[text=\getbuffer] + \dorecurse{3}{\samplefile{ward}\par} +\stopshapedparagraph + +\page + +\startshapedparagraph[text=\getbuffer,distance=1em] + \dorecurse{3}{\samplefile{ward}\par} +\stopshapedparagraph + +\page + +\startshapedparagraph[text=\getbuffer,distance=1em, + hoffset=-2em] + \dorecurse{3}{\samplefile{ward}\par} +\stopshapedparagraph + +\page + +\startshapedparagraph[text=\getbuffer,distance=1em, + voffset=-2ex,hoffset=-2em] + \dorecurse{3}{\samplefile{ward}\par} +\stopshapedparagraph + +\page + +\startshapedparagraph[text=\getbuffer,distance=1em, + voffset=-2ex,hoffset=-2em,lines=1] + \dorecurse{3}{\samplefile{ward}\par} +\stopshapedparagraph + +\page + +\startshapedparagraph[width=4cm,lines=4] + \dorecurse{3}{\samplefile{ward}\par} +\stopshapedparagraph +\stopbuffer + +\typebuffer[jano] + +\startplacefigure[title={Flow around something},reference=fig:flow] + \startcombination[nx=3,ny=2] + {\typesetbuffer[jano][page=1,frame=on,width=\measure{combination}]}{} + {\typesetbuffer[jano][page=2,frame=on,width=\measure{combination}]}{} + {\typesetbuffer[jano][page=3,frame=on,width=\measure{combination}]}{} + {\typesetbuffer[jano][page=4,frame=on,width=\measure{combination}]}{} + {\typesetbuffer[jano][page=5,frame=on,width=\measure{combination}]}{} + {\typesetbuffer[jano][page=6,frame=on,width=\measure{combination}]}{} + \stopcombination +\stopplacefigure + \stopsection % \startsection[title=Linebreaks] @@ -936,6 +999,18 @@ keyword in the next code. The result is shown in \in {figure} [fig:shape:skips]. \snapshotpar \wrapuppar +% \starttext +% \tracingoutput1 \tracingonline1 +% \pretolerance9000 test \pretolerance8000 test \par +% \pretolerance9000 test \pretolerance7000 \updateparagraphproperties test \par +% \pretolerance9000 test \pretolerance6000 \snapshotpar\frozentolerancecode test \par +% \pretolerance9000 test {\pretolerance5000 \snapshotpar\frozentolerancecode}test \par +% \stoptext + +% \par[newgraf][16=1,17=1], .... pretolerance 9000, .... +% \par[newgraf][16=1,17=1], .... pretolerance 7000, .... +% \par[newgraf][16=1,17=1], .... pretolerance 6000, .... + % \parfillleftskip % I rewarded myself after writing a section by watching the video "Final Thing On @@ -946,3 +1021,5 @@ keyword in the next code. The result is shown in \in {figure} [fig:shape:skips]. % Gavin Harrison: Soundcheck, Drummerworld Jan 27, 2021 ... I wish I could make % something called a check into pefect solo. Okay, another section and I'll check % out the latest Simon Phillips and other favourite dummer uploads. + + diff --git a/doc/context/sources/general/manuals/luametatex/luametatex-differences.tex b/doc/context/sources/general/manuals/luametatex/luametatex-differences.tex index 5be5463e9..aaa2fce50 100644 --- a/doc/context/sources/general/manuals/luametatex/luametatex-differences.tex +++ b/doc/context/sources/general/manuals/luametatex/luametatex-differences.tex @@ -6,8 +6,11 @@ \startchapter[reference=differences,title={Differences with \LUATEX}] -As \LUAMETATEX\ is a leaner and meaner \LUATEX, this chapter will discuss -what is gone. We start with the primitives that were dropped. +As \LUAMETATEX\ is a leaner and meaner \LUATEX. This means that substantial parts and +dependencies are gone: quite some font code, all backend code with related frontend +code and of course image and font inclusion. There is also new functionality which +makes for less lean but in the end we still have less, also in terms of dependencies. +This chapter will discuss what is gone. We start with the primitives that were dropped. \starttabulate[|l|pl|] \BC fonts \NC \type {\letterspacefont} @@ -97,6 +100,9 @@ as macros that (via \LUA) inject nodes in the input that suit the macro package and backend. The three||letter direction primitives are gone and the numeric variants are now leading. There is no need for page and body related directions and they don't work well in \LUATEX\ anyway. We only have two directions left. +Because we can hook in \LUA\ functions that get information about what is expected +(consumer or provider) there are plenty possibilities for adding functionality +using this scripting langauge. The primitive related extensions were not that useful and reliable so they have been removed. There are some new variants that will be discussed later. The \type @@ -178,6 +184,13 @@ Because we use a more generic whatsit model, there is a new callback: show_whatsit \stoptyping +Because tracing boxes now reports a lot more information, we have a plug in for +detail: + +\starttyping +get_attribute +\stoptyping + Being the core of extensibility, the typesetting callbacks of course stayed. This is what we ended up with: @@ -195,12 +208,13 @@ define_font There are all kinds of subtle differences in the implementation, for instance we no longer intercept \type {*} and \type {&} as these were already replaced long ago in \TEX\ engines by command line options. Talking of options, only a few are -left. All input goes via \LUA, even the console. +left. All input goes via \LUA, even the console. One can program a terminal if +needed. We took our time for reaching a stable state in \LUATEX. Among the reasons is the -fact that most was experimented with in \CONTEXT. It took many years of work to -decide what to keep and how to do things. Of course there are places when things -can be improved and it might happen in \LUAMETATEX. Contrary to what is sometimes +fact that most was experimented with in \CONTEXT. It took many years to decide +what to keep and how to do things. Of course there are places when things can be +improved and it might happen in \LUAMETATEX. Contrary to what is sometimes suggested, the \LUATEX|-|\CONTEXT\ \MKIV\ combination (assuming matched versions) has been quite stable. It made no sense otherwise. Most \CONTEXT\ functionality didn't change much at the user level. Of course there have been issues, as is @@ -214,11 +228,13 @@ before a long term stable is defined. The good news is that, the source code being part of the \CONTEXT\ distribution, there is always a properly working, more or less long term stable, snapshot. -The error reporting subsystem has been redone a little but is still fundamentally -the same. We don't really assume interactive usage but if someone uses it, it -might be noticed that it is not possible to backtrack or inject something. Of -course it is no big deal to implement all that in \LUA\ if needed. It removes a -system dependency and makes for a bit cleaner code. +The error reporting subsystem has been redone quite a bit but is still +fundamentally the same. We don't really assume interactive usage but if someone +uses it, it might be noticed that it is not possible to backtrack or inject +something. Of course it is no big deal to implement all that in \LUA\ if needed. +It removes a system dependency and makes for a bit cleaner code. In \CONTEXT\ +we quit on an error simply because one has to fix source anyway and runs are +fast enough. There are new primitives as well as some extensions to existing primitive functionality. These are described in following chapters but there might be @@ -258,6 +274,7 @@ if luatex and luametatex then context("The following primitives are available in \\LUATEX\\ but not in \\LUAMETATEX. ") context("Some of these are emulated in \\CONTEXT.") + context.blank() context.startcolumns { n = 2 } for k, v in table.sortedhash(luatex) do if not luametatex[k] then @@ -266,13 +283,14 @@ if luatex and luametatex then end end context.stopcolumns() - + context.blank() -- context.page() context("The following primitives are available in \\LUAMETATEX\\ only. ") context("At some point in time some might be added to \\LUATEX.") + context.blank() context.startcolumns { n = 2 } for k, v in table.sortedhash(luametatex) do if not luatex[k] then @@ -281,11 +299,73 @@ if luatex and luametatex then end end context.stopcolumns() + context.blank() end \stopluacode +As part of a bit more consistency some function names also changed. Names with an +\type {_} got that removed (as that was the minority). It's easy to provide a +back mapping if needed (just alias the functions). + +{\em Todo: only mention the \LUATEX\ ones.} + +\starttabulate[|l|l|l|l|] +\DB library \BC old name \BC new name \BC comment \NC \NR +\TB +\NC language \NC clear_patterns \NC clearpatterns \NC \NR +\NC \NC clear_hyphenation \NC clearhyphenation \NC \NR +\NC mplib \NC italcor \NC italic \NC \NR +\NC \NC pen_info \NC peninfo \NC \NR +\NC \NC solve_path \NC solvepath \NC \NR +\NC texio \NC write_nl \NC writenl \NC old name stays \NC \NR +\NC node \NC protect_glyph \NC protectglyph \NC \NR +\NC \NC protect_glyphs \NC protectglyphs \NC \NR +\NC \NC unprotect_glyph \NC unprotectglyph \NC \NR +\NC \NC unprotect_glyphs \NC unprotectglyphs \NC \NR +\NC \NC end_of_math \NC endofmath \NC \NR +\NC \NC mlist_to_hlist \NC mlisttohlist \NC \NR +\NC \NC effective_glue \NC effectiveglue \NC \NR +\NC \NC has_glyph \NC hasglyph \NC \NR +\NC \NC first_glyph \NC firstglyph \NC \NR +\NC \NC has_field \NC hasfield \NC \NR +\NC \NC copy_list \NC copylist \NC \NR +\NC \NC flush_node \NC flushnode \NC \NR +\NC \NC flush_list \NC flushlist \NC \NR +\NC \NC insert_before \NC insertbefore \NC \NR +\NC \NC insert_after \NC insertafter \NC \NR +\NC \NC last_node \NC lastnode \NC \NR +\NC \NC is_zero_glue \NC iszeroglue \NC \NR +\NC \NC make_extensible \NC makeextensible \NC \NR +\NC \NC uses_font \NC usesfont \NC \NR +\NC \NC is_char \NC ischar \NC \NR +\NC \NC is_direct \NC isdirect \NC \NR +\NC \NC is_glyph \NC isglyph \NC \NR +\NC \NC is_node \NC isnode \NC \NR +\NC token \NC scan_keyword \NC scankeyword \NC \NR +\NC \NC scan_keywordcs \NC scankeywordcs \NC \NR +\NC \NC scan_int \NC scanint \NC \NR +\NC \NC scan_real \NC scanreal \NC \NR +\NC \NC scan_float \NC scanfloat \NC \NR +\NC \NC scan_dimen \NC scandimen \NC \NR +\NC \NC scan_glue \NC scanglue \NC \NR +\NC \NC scan_toks \NC scantoks \NC \NR +\NC \NC scan_code \NC scancode \NC \NR +\NC \NC scan_string \NC scanstring \NC \NR +\NC \NC scan_argument \NC scanargument \NC \NR +\NC \NC scan_word \NC scanword \NC \NR +\NC \NC scan_csname \NC scancsname \NC \NR +\NC \NC scan_list \NC scanlist \NC \NR +\NC \NC scan_box \NC scanbox \NC \NR +\LL +\stoptabulate + +It's all part of trying to make the code base consistent but it is sometimes a +bit annoying. However, that's why we develop this engine independent of the +\LUATEX\ code base. It's anyway a change that has been on my todo list for quite +a while because those inconsistencies annoyed me. + \stopchapter \stopcomponent diff --git a/doc/context/sources/general/manuals/luametatex/luametatex-preamble.tex b/doc/context/sources/general/manuals/luametatex/luametatex-internals.tex index 5a2dae818..70d45cfeb 100644 --- a/doc/context/sources/general/manuals/luametatex/luametatex-preamble.tex +++ b/doc/context/sources/general/manuals/luametatex/luametatex-internals.tex @@ -2,9 +2,9 @@ \environment luametatex-style -\startcomponent luametatex-preamble +\startcomponent luametatex-internals -\startchapter[reference=preamble,title={The internals}] +\startchapter[reference=internals,title={The internals}] \topicindex{nodes} \topicindex{boxes} @@ -66,9 +66,10 @@ indent box: Each character becomes a so called glyph node, a record with properties like the current font, the character code and the current language. Spaces become glue -nodes. There are many node types that we will discuss later. Each node points -back to a previous node or next node, given that these exist. Sometimes -multiple characters are represented by one glyphs, so one can also get: +nodes. There are many node types and nodes can have many properties but that will +be discussed later. Each node points back to a previous node or next node, given +that these exist. Sometimes multiple characters are represented by one glyph +(shape), so one can also get: \starttyping [par] <=> [hlist] <=> H <=> i <=> [glue] <=> Th <=> e <=> r <=> e ... @@ -101,6 +102,59 @@ take the list so far. Constructing the actual page is not part of \TEX\ but done using primitives that permit manipulation of boxes. The result is handled back to \TEX\ and flushed to a (often \PDF) file. +\starttyping +\setbox\scratchbox\vbox\bgroup + line 1\par line 2 +\egroup + +\showbox\scratchbox +\stoptyping + +The above code produces the next log lines that reveal how the engines sees a +paragraph (wrapped in a \type {\vbox}): + +\starttyping[style=small] +1:4: > \box257= +1:4: \vbox[normal][16=1,17=1,47=1], width 483.69687, height 27.58083, depth 0.1416, direction l2r +1:4: .\list +1:4: ..\hbox[line][16=1,17=1,47=1], width 483.69687, height 7.59766, depth 0.1416, glue 455.40097fil, direction l2r +1:4: ...\list +1:4: ....\glue[left hang][16=1,17=1,47=1] 0.0pt +1:4: ....\glue[left][16=1,17=1,47=1] 0.0pt +1:4: ....\glue[parfillleft][16=1,17=1,47=1] 0.0pt +1:4: ....\par[newgraf][16=1,17=1,47=1], hangafter 1, hsize 483.69687, pretolerance 100, tolerance 3000, adjdemerits 10000, linepenalty 10, doublehyphendemerits 10000, finalhyphendemerits 5000, clubpenalty 2000, widowpenalty 2000, brokenpenalty 100, emergencystretch 12.0, parfillskip 0.0pt plus 1.0fil, hyphenationmode 499519 +1:4: ....\glue[indent][16=1,17=1,47=1] 0.0pt +1:4: ....\glyph[32768][16=1,17=1,47=1], language (n=1,l=2,r=3), hyphenationmode 499519, options 128 , font <30: DejaVuSerif @ 10.0pt>, glyph U+00006C l +1:4: ....\glyph[32768][16=1,17=1,47=1], language (n=1,l=2,r=3), hyphenationmode 499519, options 128 , font <30: DejaVuSerif @ 10.0pt>, glyph U+000069 i +1:4: ....\glyph[32768][16=1,17=1,47=1], language (n=1,l=2,r=3), hyphenationmode 499519, options 128 , font <30: DejaVuSerif @ 10.0pt>, glyph U+00006E n +1:4: ....\glyph[32768][16=1,17=1,47=1], language (n=1,l=2,r=3), hyphenationmode 499519, options 128 , font <30: DejaVuSerif @ 10.0pt>, glyph U+000065 e +1:4: ....\glue[space][16=1,17=1,47=1] 3.17871pt plus 1.58936pt minus 1.05957pt, font 30 +1:4: ....\glyph[32768][16=1,17=1,47=1], language (n=1,l=2,r=3), hyphenationmode 499519, options 128 , font <30: DejaVuSerif @ 10.0pt>, glyph U+000031 1 +1:4: ....\penalty[line][16=1,17=1,47=1] 10000 +1:4: ....\glue[parfill][16=1,17=1,47=1] 0.0pt plus 1.0fil +1:4: ....\glue[right][16=1,17=1,47=1] 0.0pt +1:4: ....\glue[right hang][16=1,17=1,47=1] 0.0pt +1:4: ..\glue[par][16=1,17=1,47=1] 5.44995pt plus 1.81665pt minus 1.81665pt +1:4: ..\glue[baseline][16=1,17=1,47=1] 6.79396pt +1:4: ..\hbox[line][16=1,17=1,47=1], width 483.69687, height 7.59766, depth 0.1416, glue 455.40097fil, direction l2r +1:4: ...\list +1:4: ....\glue[left hang][16=1,17=1,47=1] 0.0pt +1:4: ....\glue[left][16=1,17=1,47=1] 0.0pt +1:4: ....\glue[parfillleft][16=1,17=1,47=1] 0.0pt +1:4: ....\par[newgraf][16=1,17=1,47=1], hangafter 1, hsize 483.69687, pretolerance 100, tolerance 3000, adjdemerits 10000, linepenalty 10, doublehyphendemerits 10000, finalhyphendemerits 5000, clubpenalty 2000, widowpenalty 2000, brokenpenalty 100, emergencystretch 12.0, parfillskip 0.0pt plus 1.0fil, hyphenationmode 499519 +1:4: ....\glue[indent][16=1,17=1,47=1] 0.0pt +1:4: ....\glyph[32768][16=1,17=1,47=1], language (n=1,l=2,r=3), hyphenationmode 499519, options 128 , font <30: DejaVuSerif @ 10.0pt>, glyph U+00006C l +1:4: ....\glyph[32768][16=1,17=1,47=1], language (n=1,l=2,r=3), hyphenationmode 499519, options 128 , font <30: DejaVuSerif @ 10.0pt>, glyph U+000069 i +1:4: ....\glyph[32768][16=1,17=1,47=1], language (n=1,l=2,r=3), hyphenationmode 499519, options 128 , font <30: DejaVuSerif @ 10.0pt>, glyph U+00006E n +1:4: ....\glyph[32768][16=1,17=1,47=1], language (n=1,l=2,r=3), hyphenationmode 499519, options 128 , font <30: DejaVuSerif @ 10.0pt>, glyph U+000065 e +1:4: ....\glue[space][16=1,17=1,47=1] 3.17871pt plus 1.58936pt minus 1.05957pt, font 30 +1:4: ....\glyph[32768][16=1,17=1,47=1], language (n=1,l=2,r=3), hyphenationmode 499519, options 128 , font <30: DejaVuSerif @ 10.0pt>, glyph U+000032 2 +1:4: ....\penalty[line][16=1,17=1,47=1] 10000 +1:4: ....\glue[parfill][16=1,17=1,47=1] 0.0pt plus 1.0fil +1:4: ....\glue[right][16=1,17=1,47=1] 0.0pt +1:4: ....\glue[right hang][16=1,17=1,47=1] 0.0pt +\stoptyping + The \LUATEX\ engine provides hooks for \LUA\ code at nearly every reasonable point in the process: collecting content, hyphenating, applying font features, breaking into lines, etc. This means that you can overload \TEX's natural @@ -110,14 +164,14 @@ kick in much \LUA\ code, you will notices that performance drops. Don't blame an bother the authors with performance issues. In \CONTEXT\ over 50\% of the time can be spent in \LUA, but so far we didn't get many complaints about efficiency. Adding more callbacks makes no sense, also because at some point the performance -hit gets too large. There are plenty ways to achieve one goals. For that reason: +hit gets too large. There are plenty of ways to achieve goals. For that reason: take remarks about \LUATEX, features, potential, performance etc.\ with a natural grain of salt. Where plain \TEX\ is basically a basic framework for writing a specific style, macro packages like \CONTEXT\ and \LATEX\ provide the user a whole lot of additional tools to make documents look good. They hide the dirty details of font -management, language demands, turning structure into typeset results, wrapping +management, language support, turning structure into typeset results, wrapping pages, including images, and so on. You should be aware of the fact that when you hook in your own code to manipulate lists, this can interfere with the macro package that you use. Each successive step expects a certain result and if you @@ -151,7 +205,7 @@ specifies what that command is supposed to do. In addition to an interface to nodes, there is an interface to tokens, as later chapters will demonstrate. Text (interspersed with macros) comes from an input medium. This can be a file, -token list, macro body cq.\ arguments, \ some internal quantity (like a number), +token list, macro body cq.\ arguments, some internal quantity (like a number), \LUA, etc. Macros get expanded. In the process \TEX\ can enter a group. Inside the group, changes to registers get saved on a stack, and restored after leaving the group. When conditionals are encountered, another kind of nesting happens, @@ -161,17 +215,18 @@ use \TEX\ a lot. You have access to most of the internals and when not, at least it is possible to query some state we're in or level we're at. When we talk about pack(ag)ing it can mean two things. When \TEX\ has consumed -some tokens that represent text. When the text is put into a so called \type -{\hbox} it (normally) first gets hyphenated (even in an horizontal list), next -ligatures are build, and finally kerns are added. Each of these stages can be -overloaded using \LUA\ code. When these three stages are finished, the dimension -of the content is calculated and the box gets its width, height and depth. What -happens with the box depends on what macros do with it. +some tokens that represent text they are added to the current list. When the text +is put into a so called \type {\hbox} (for instance a line in a paragraph) it +(normally) first gets hyphenated, next ligatures are build, and finally kerns are +added. Each of these stages can be overloaded using \LUA\ code. When these three +stages are finished, the dimension of the content is calculated and the box gets +its width, height and depth. What happens with the box depends on what macros do +with it. The other thing that can happen is that the text starts a new paragraph. In that case some information is stored in a leading \type {par} node. Then indentation is appended and the paragraph ends with some glue. Again the three stages are -applied but this time, afterwards, the long line is broken into lines and the +applied but this time afterwards, the long line is broken into lines and the result is either added to the content of a box or to the main vertical list (the running text so to say). This is called par building. At some point \TEX\ decides that enough is enough and it will trigger the page builder. So, building is diff --git a/doc/context/sources/general/manuals/luametatex/luametatex-introduction.tex b/doc/context/sources/general/manuals/luametatex/luametatex-introduction.tex index 2339bd342..f78b9f3e7 100644 --- a/doc/context/sources/general/manuals/luametatex/luametatex-introduction.tex +++ b/doc/context/sources/general/manuals/luametatex/luametatex-introduction.tex @@ -6,7 +6,7 @@ \startchapter[title=Introduction] -Around 2005 we started the \LUATEX\ projects and it took about a decade to reach +Around 2005 we started the \LUATEX\ project and it took about a decade to reach a state where we could consider the experiments to have reached a stable state. Pretty soon \LUATEX\ could be used in production, even if some of the interfaces evolved, but \CONTEXT\ was kept in sync so that was not really a problem. In 2018 @@ -16,17 +16,17 @@ reasonable feature complete. Among the reasons is that this engine is now used outside \CONTEXT\ too which means that we cannot simply change much without affecting other macro packages. -However, in reaching that state some decisions were delayed because they didn't -go well with a current stable version. This is why at the 2018 \CONTEXT\ meeting -those present agreed that we could move on with a follow up tagged \METATEX, a -name we already had in mind for a while, but as \LUA\ is an important component, -it got expanded to \LUAMETATEX. This follow up is a lightweight companion to -\LUATEX\ that will be maintained alongside. More about the reasons for this -follow up as well as the philosophy behind it can be found in the document(s) -describing the development. During \LUATEX\ development I kept track of what -happened in a series of documents, parts of which were published as articles in -user group journals, but all are in the \CONTEXT\ distribution. I did the same -with the development of \LUAMETATEX. +In reaching that state some decisions were delayed because they didn't go well +with a current stable version. This is why at the 2018 \CONTEXT\ meeting those +present agreed that we could move on with a follow up tagged \METATEX, a name we +already had in mind for a while, but as \LUA\ is an important component, it got +expanded to \LUAMETATEX. This follow up is a lightweight companion to \LUATEX\ +that will be maintained alongside. More about the reasons for this follow up as +well as the philosophy behind it can be found in the document(s) describing the +development. During \LUATEX\ development I kept track of what happened in a +series of documents, parts of which were published as articles in user group +journals, but all are in the \CONTEXT\ distribution. I did the same with the +development of \LUAMETATEX. The \LUAMETATEX\ engine is, as said, a follow up on \LUATEX. Just as we have \CONTEXT\ \MKII\ for \PDFTEX\ and \XETEX, we have \MKIV\ for \LUATEX. For @@ -42,18 +42,19 @@ ported back to \LUATEX, but only when there are good reasons for doing so and when no compatibility issues are involved. By now the code of these two related engines differs a lot so in retrospect it -makes less sense to waste time on backporting anyway. When considering this -follow up one consideration was that a lean and mean version with an extension -mechanism is a bit closer to original \TEX. Of course, because we also have new -primitives, this is not entirely true. The basic algorithms remain the same but -code got reshuffled and because we expose internals names of variables and such -are sometimes changed, something that is noticeable in the token and node -interfaces. Delegating tasks to \LUA\ already meant that some aspects, especially -system dependent ones, no longer made sense and therefore had consequences for -the interface at the system level. In \LUAMETATEX\ more got delegated, like all -file related operations. The penalty of moving more responsibility to \LUA\ has +makes less sense to waste time on porting back. When considering this follow up +one consideration was that a lean and mean version with an extension mechanism is +a bit closer to original \TEX. Of course, because we also have new primitives, +this is not entirely true. The basic algorithms remain the same but code got +reshuffled and because we expose internal names of variables and such that is +reflected in the code base (like more granularity in nodes and token commands). +Delegating tasks to \LUA\ already meant that some aspects, especially system +dependent ones, no longer made sense and therefore had consequences for the +interface at the system level. In \LUAMETATEX\ more got delegated, like all file +related operations. The penalty of moving even more responsibility to \LUA\ has been compensated by (hopefully) harmless optimization of code in the engine and -some more core functionality. +some more core functionality. In the process system dependencies have been +minimalized. This manual started as an adaptation of the \LUATEX\ manual and therefore looks similar. Some chapters are removed, others were added and the rest has been (and @@ -70,11 +71,11 @@ mentioned, the \CONTEXT\ variant for this engine is tagged \LMTX. The pair can b used in production, just as with \LUATEX\ and \MKIV. In fact, most users will probably not really notice the difference. In some cases there will be a drop in performance, due to more work being delegated to \LUA, but on the average -performance will be better, also due to some changes below the hood of the -engine. Memory consumption is also less. The timeline of development is roughly: -from 2018 upto 2020 engine development, 2019 upto 2021 the stepwise code split -between \MKIV\ and \LMTX, while in 2020 we will (mostly) freeze \MKIV\ and \LMTX\ -will be the default. +performance is much be better, due to some changes below the hood of the engine. +Memory consumption is also less. The timeline of development is roughly: from +2018 upto 2020 engine development, 2019 upto 2021 the stepwise code split between +\MKIV\ and \LMTX, while in 2021 and 2022 we will (mostly) freeze \MKIV\ and +\LMTX\ will be the default. As this follow up is closely related to \CONTEXT\ development, and because we expect stock \LUATEX\ to be used outside the \CONTEXT\ proper, there will be no @@ -94,7 +95,7 @@ you can always consider contacting the developers. % this 'always need to be present' negative remark (nagging) about the program, % documentation, development, support, etc. present, probably to put the writer on % a higher stand, or maybe to compensate some other personal shortcoming ... who -% knows. This 'i need to make my stupid point' behaviour seems to come with the +% knows. This 'I need to make my stupid point' behaviour seems to come with the % internet and it also seems to increase, but that doesn't mean that I want to deal % with those unpleasant people for the sake of the larger "tex good". Therefore, I'm % quite happy in the nearly always positive and motivating ConTeXt bubble. It's also @@ -136,14 +137,14 @@ real problem as there's not much demand for that anyway. {\bf remark:} Most \CONTEXT\ users seem always willing to keep up with the latest versions which means that \LMTX\ is tested well. We can therefore safely claim -that end of 2019 the code has become quite stable. There are no complaints about -performance (on my 2013 laptop this manual compiles at 24.5 pps with \LMTX\ -versus 20.7 pps for the \LUATEX\ manual with \MKIV). After updating some of the -\CONTEXT\ code to use recently added features by the end of 2020 I could do more -than 25.5 pps but don't expect spectacular bumps in performance (I need a new -machine for that to happen). Probably no one notices it, but memory consumption -stepwise got reduced too. And \unknown\ the binary is still below 3~MegaBytes on -all platforms. +that end of 2019 the code has become quite stable, although after that in some +areas there were substantial additions. There are no complaints about performance +(on my 2013 laptop this manual compiles at 24.5 pps with \LMTX\ versus 20.7 pps +for the \LUATEX\ manual with \MKIV). After updating some of the \CONTEXT\ code to +use recently added features by the end of 2020 I could do more than 25.5 pps but +don't expect spectacular bumps in performance (I need a new machine for that to +happen). Probably no one notices it, but memory consumption stepwise got reduced +too. And \unknown\ the binary is still below 3~MegaBytes on all platforms. \stopchapter diff --git a/doc/context/sources/general/manuals/luametatex/luametatex-languages.tex b/doc/context/sources/general/manuals/luametatex/luametatex-languages.tex index b60079477..1adab5c3a 100644 --- a/doc/context/sources/general/manuals/luametatex/luametatex-languages.tex +++ b/doc/context/sources/general/manuals/luametatex/luametatex-languages.tex @@ -814,9 +814,9 @@ language.hyphenation(<language> l, <string> n) When no string is given (the first example) a string with all exceptions is returned. -\subsection {\type {clear_hyphenation} and \type {clean}} +\subsection {\type {clearhyphenation} and \type {clean}} -\libindex {clear_hyphenation} +\libindex {clearhyphenation} \libindex {clean} This either returns the current hyphenation exceptions for this language, or adds @@ -824,7 +824,7 @@ new ones. The syntax of the string is explained in~\in {section} [patternsexceptions]. \startfunctioncall -language.clear_hyphenation(<language> l) +language.clearhyphenation(<language> l) \stopfunctioncall This call clears the exception dictionary (string) for this language. @@ -839,10 +839,10 @@ syntax of the argument string is explained in \in {section} [patternsexceptions] This function is useful if you want to do something else based on the words in a dictionary file, like spell|-|checking. -\subsection {\type {patterns} and \type {clear_patterns}} +\subsection {\type {patterns} and \type {clearpatterns}} \libindex {patterns} -\libindex {clear_patterns} +\libindex {clearpatterns} \startfunctioncall <string> n = language.patterns(<language> l) @@ -854,7 +854,7 @@ set. The syntax of this string is explained in \in {section} [patternsexceptions]. \startfunctioncall -language.clear_patterns(<language> l) +language.clearpatterns(<language> l) \stopfunctioncall This can be used to clear the pattern dictionary for a language. diff --git a/doc/context/sources/general/manuals/luametatex/luametatex-metapost.tex b/doc/context/sources/general/manuals/luametatex/luametatex-metapost.tex index c687a5a46..646894dbd 100644 --- a/doc/context/sources/general/manuals/luametatex/luametatex-metapost.tex +++ b/doc/context/sources/general/manuals/luametatex/luametatex-metapost.tex @@ -20,6 +20,9 @@ The \METAPOST\ library interface registers itself in the table \type {mplib}. It is based on \MPLIB\ version \ctxlua {context(mplib.version())}. +Not all functionality is described here. Once we're out of the experimental stage +some more information will be added. + \subsection{\type {new}} \libindex{new} @@ -219,15 +222,13 @@ you can call: \type {prologues} \NC \NR \NC \type{objects} \NC function \NC returns the actual array of graphic objects in this \type {fig} \NC \NR -\NC \type{copy_objects} \NC function \NC returns a deep copy of the array of graphic - objects in this \type {fig} \NC \NR \NC \type{filename} \NC function \NC the filename this \type {fig}'s \POSTSCRIPT\ output would have written to in stand alone mode \NC \NR \NC \type{width} \NC function \NC the \type {fontcharwd} value \NC \NR \NC \type{height} \NC function \NC the \type {fontcharht} value \NC \NR \NC \type{depth} \NC function \NC the \type {fontchardp} value \NC \NR -\NC \type{italcorr} \NC function \NC the \type {fontcharit} value \NC \NR +\NC \type{italic} \NC function \NC the \type {fontcharit} value \NC \NR \NC \type{charcode} \NC function \NC the (rounded) \type {charcode} value \NC \NR \LL \stoptabulate @@ -409,11 +410,11 @@ and \quote {off}, values, and \type {offset} is the phase of the pattern. \LL \stoptabulate -\subsection{Pens and \type {pen_info}} +\subsection{Pens and \type {peninfo}} -\libindex{pen_info} +\libindex{peninfo} -There is helper function (\type {pen_info(obj)}) that returns a table containing +There is helper function (\type {peninfo(obj)}) that returns a table containing a bunch of vital characteristics of the used pen (all values are floats): \starttabulate[|l|l|p|] @@ -457,20 +458,20 @@ still preliminary and mostly provided as reminder. \starttabulate[|l|l|p|] \DB scanner \BC argument \BC returns \NC \NR \TB -\NC \type{scan_next} \NC instance, keep \NC token, mode, type \NC \NR -\NC \type{scan_expression} \NC instance, keep \NC type \NC \NR -\NC \type{scan_token} \NC instance, keep \NC token, mode, kind \NC \NR -\NC \type{scan_symbol} \NC instance, keep, expand \NC string \NC \NR -\NC \type{scan_numeric} \NC instance, type \NC number \NC \NR -\NC \type{scan_integer} \NC instance, type \NC integer \NC \NR -\NC \type{scan_boolean} \NC instance, type \NC boolean \NC \NR -\NC \type{scan_string} \NC instance, type \NC string \NC \NR -\NC \type{scan_pair} \NC instance, hashed, type \NC table or two numbers \NC \NR -\NC \type{scan_color} \NC instance, hashed, type \NC table or three numbers \NC \NR -\NC \type{scan_cmykcolor} \NC instance, hashed, type \NC table or four numbers \NC \NR -\NC \type{scan_transform} \NC instance, hashed, type \NC table or six numbers \NC \NR -\NC \type{scan_path} \NC instance, hashed, type \NC table with hashes or arrays \NC \NR -\NC \type{scan_pen} \NC instance, hashed, type \NC table with hashes or arrays \NC \NR +\NC \type{scannext} \NC instance, keep \NC token, mode, type \NC \NR +\NC \type{scanexpression} \NC instance, keep \NC type \NC \NR +\NC \type{scantoken} \NC instance, keep \NC token, mode, kind \NC \NR +\NC \type{scansymbol} \NC instance, keep, expand \NC string \NC \NR +\NC \type{scannumeric} \NC instance, type \NC number \NC \NR +\NC \type{scaninteger} \NC instance, type \NC integer \NC \NR +\NC \type{scanboolean} \NC instance, type \NC boolean \NC \NR +\NC \type{scanstring} \NC instance, type \NC string \NC \NR +\NC \type{scanpair} \NC instance, hashed, type \NC table or two numbers \NC \NR +\NC \type{scancolor} \NC instance, hashed, type \NC table or three numbers \NC \NR +\NC \type{scancmykcolor} \NC instance, hashed, type \NC table or four numbers \NC \NR +\NC \type{scantransform} \NC instance, hashed, type \NC table or six numbers \NC \NR +\NC \type{scanpath} \NC instance, hashed, type \NC table with hashes or arrays \NC \NR +\NC \type{scanpen} \NC instance, hashed, type \NC table with hashes or arrays \NC \NR \LL \stoptabulate @@ -521,15 +522,15 @@ optimized. The other data structures were then added for completeness.} \starttabulate[|l|l|] \DB scanner \BC argument \NC \NR \TB -\NC \type{inject_numeric} \NC instance, number \NC \NR -\NC \type{inject_integer} \NC instance, number \NC \NR -\NC \type{inject_boolean} \NC instance, boolean \NC \NR -\NC \type{inject_string} \NC instance, string \NC \NR -\NC \type{inject_pair} \NC instance, (table with) two numbers \NC \NR -\NC \type{inject_color} \NC instance, (table with) three numbers \NC \NR -\NC \type{inject_cmykcolor} \NC instance, (table with) four numbers \NC \NR -\NC \type{inject_transform} \NC instance, (table with) six numbers \NC \NR -\NC \type{inject_path} \NC instance, table with hashes or arrays, cycle, variant \NC \NR +\NC \type{injectnumeric} \NC instance, number \NC \NR +\NC \type{injectinteger} \NC instance, number \NC \NR +\NC \type{injectboolean} \NC instance, boolean \NC \NR +\NC \type{injectstring} \NC instance, string \NC \NR +\NC \type{injectpair} \NC instance, (table with) two numbers \NC \NR +\NC \type{injectcolor} \NC instance, (table with) three numbers \NC \NR +\NC \type{injectcmykcolor} \NC instance, (table with) four numbers \NC \NR +\NC \type{injecttransform} \NC instance, (table with) six numbers \NC \NR +\NC \type{injectpath} \NC instance, table with hashes or arrays, cycle, variant \NC \NR \LL \stoptabulate diff --git a/doc/context/sources/general/manuals/luametatex/luametatex-nodes.tex b/doc/context/sources/general/manuals/luametatex/luametatex-nodes.tex index 6773d346d..bcdac0d39 100644 --- a/doc/context/sources/general/manuals/luametatex/luametatex-nodes.tex +++ b/doc/context/sources/general/manuals/luametatex/luametatex-nodes.tex @@ -350,7 +350,7 @@ suits the \TEX\ internals well so we decided to stick to that naming. The effective width of some glue subtypes depends on the stretch or shrink needed to make the encapsulating box fit its dimensions. For instance, in a paragraph lines normally have glue representing spaces and these stretch or shrink to make -the content fit in the available space. The \type {effective_glue} function that +the content fit in the available space. The \type {effectiveglue} function that takes a glue node and a parent (hlist or vlist) returns the effective width of that glue item. When you pass \type {true} as third argument the value will be rounded. @@ -1027,10 +1027,10 @@ there is no node with that id. \stopsubsubsection -\startsubsubsection[title={\type {fields} and \type {has_field}}] +\startsubsubsection[title={\type {fields} and \type {hasfield}}] \libindex {fields} -\libindex {has_field} +\libindex {hasfield} This function returns an indexed table with valid field names for a particular type of node. @@ -1043,11 +1043,11 @@ The function accepts a string or number, so \typ {node.fields ("glyph")} returns \inlineluavalue { node.fields ("glyph") } and \typ {node.fields (12)} gives \inlineluavalue { node.fields (12) }. -The \type {has_field} function returns a boolean that is only true if \type {n} +The \type {hasfield} function returns a boolean that is only true if \type {n} is actually a node, and it has the field. \startfunctioncall -<boolean> t = node.has_field(<node> n, <string> field) +<boolean> t = node.hasfield(<node> n, <string> field) \stopfunctioncall This function probably is not that useful but some nodes don't have a \type @@ -1090,11 +1090,11 @@ back somehow. \stopsubsubsection -\startsubsubsection[title={\type {free}, \type {flush_node} and \type {flush_list}}] +\startsubsubsection[title={\type {free}, \type {flushnode} and \type {flushlist}}] \libindex{free} -\libindex{flush_node} -\libindex{flush_list} +\libindex{flushnode} +\libindex{flushlist} The next one frees 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 @@ -1104,11 +1104,11 @@ you used their content for something else you need to set them to nil first. \startfunctioncall <node> next = node.free(<node> n) -flush_node(<node> n) +flushnode(<node> n) \stopfunctioncall The \type {free} function returns the next field of the freed node, while the -\type {flush_node} alternative returns nothing. +\type {flushnode} alternative returns nothing. A list starting with node \type {n} can be flushed from \TEX's memory too. Be careful: no checks are done on whether any of these nodes is still pointed to @@ -1116,19 +1116,19 @@ from a register or some \type {next} field: it is up to you to make sure that th internal data structures remain correct. \startfunctioncall -node.flush_list(<node> n) +node.flushlist(<node> n) \stopfunctioncall -When you free for instance a discretionary node, \type {flush_list} is applied to +When you free for instance a discretionary node, \type {flushlist} is applied to the \type {pre}, \type {post}, \type {replace} so you don't need to do that yourself. Assigning them \type {nil} won't free those lists! \stopsubsubsection -\startsubsubsection[title={\type {copy} and \type {copy_list}}] +\startsubsubsection[title={\type {copy} and \type {copylist}}] \libindex{copy} -\libindex{copy_list} +\libindex{copylist} This creates a deep copy of node \type {n}, including all nested lists as in the case of a hlist or vlist node. Only the \type {next} field is not copied. @@ -1141,8 +1141,8 @@ A deep copy of the node list that starts at \type {n} can be created too. If \type {m} is also given, the copy stops just before node \type {m}. \startfunctioncall -<node> m = node.copy_list(<node> n) -<node> m = node.copy_list(<node> n, <node> m) +<node> m = node.copylist(<node> n) +<node> m = node.copylist(<node> n, <node> m) \stopfunctioncall Note that you cannot copy attribute lists this way. However, there is normally no @@ -1248,12 +1248,12 @@ changed. When the third argument is passed, the node is freed. \stopsubsubsection -\startsubsubsection[title={\type {insert_before}}] +\startsubsubsection[title={\type {insertbefore}}] -\libindex {insert_before} +\libindex {insertbefore} \startfunctioncall -<node> head, new = node.insert_before(<node> head, <node> current, <node> new) +<node> head, new = node.insertbefore(<node> head, <node> current, <node> new) \stopfunctioncall This function inserts the node \type {new} before \type {current} into the list @@ -1265,12 +1265,12 @@ will become \type {new}. \stopsubsubsection -\startsubsubsection[title={\type {insert_after}}] +\startsubsubsection[title={\type {insertafter}}] -\libindex {insert_after} +\libindex {insertafter} \startfunctioncall -<node> head, new = node.insert_after(<node> head, <node> current, <node> new) +<node> head, new = node.insertafter(<node> head, <node> current, <node> new) \stopfunctioncall This function inserts the node \type {new} after \type {current} into the list @@ -1281,12 +1281,12 @@ field). If \type {head} is initially \type {nil}, it will become \type {new}. \stopsubsubsection -\startsubsubsection[title={\type {last_node}}] +\startsubsubsection[title={\type {lastnode}}] -\libindex {last_node} +\libindex {lastnode} \startfunctioncall -<node> n = node.last_node() +<node> n = node.lastnode() \stopfunctioncall This function pops the last node from \TEX's \quote{current list}. It returns @@ -1559,15 +1559,15 @@ glue and the sign. \stopsubsubsection -\startsubsubsection[title={\type {is_zero_glue}}] +\startsubsubsection[title={\type {iszeroglue}}] -\libindex {is_zero_glue} +\libindex {iszeroglue} This function returns \type {true} when the width, stretch and shrink properties are zero. \startfunctioncall -<boolean> isglue = node.is_zero_glue(<node> n) +<boolean> isglue = node.iszeroglue(<node> n) \stopfunctioncall \stopsubsubsection @@ -1626,23 +1626,23 @@ and there is no double linked list. \stopsubsubsection -\startsubsubsection[title={\type {current_attr}}] +\startsubsubsection[title={\type {currentattr}}] -\libindex{current_attr} +\libindex{currentattr} This returns the currently active list of attributes, if there is one. \startfunctioncall -<node> m = node.current_attr() +<node> m = node.currentattr() \stopfunctioncall -The intended usage of \type {current_attr} is as follows: +The intended usage of \type {currentattr} is as follows: \starttyping local x1 = node.new("glyph") -x1.attr = node.current_attr() +x1.attr = node.currentattr() local x2 = node.new("glyph") -x2.attr = node.current_attr() +x2.attr = node.currentattr() \stoptyping or: @@ -1650,7 +1650,7 @@ or: \starttyping local x1 = node.new("glyph") local x2 = node.new("glyph") -local ca = node.current_attr() +local ca = node.currentattr() x1.attr = ca x2.attr = ca \stoptyping @@ -1662,13 +1662,13 @@ passed back to \TEX. \stopsubsubsection -\startsubsubsection[title={\type {has_attribute}}] +\startsubsubsection[title={\type {hasattribute}}] -\libindex {has_attribute} +\libindex {hasattribute} \startfunctioncall -<number> v = node.has_attribute(<node> n, <number> id) -<number> v = node.has_attribute(<node> n, <number> id, <number> val) +<number> v = node.hasattribute(<node> n, <number> id) +<number> v = node.hasattribute(<node> n, <number> id, <number> val) \stopfunctioncall Tests if a node has the attribute with number \type {id} set. If \type {val} is @@ -1677,12 +1677,12 @@ or, if no match is found, \type {nil}. \stopsubsubsection -\startsubsubsection[title={\type {get_attribute}}] +\startsubsubsection[title={\type {getattribute}}] -\libindex {get_attribute} +\libindex {getattribute} \startfunctioncall -<number> v = node.get_attribute(<node> n, <number> id) +<number> v = node.getattribute(<node> n, <number> id) \stopfunctioncall Tests if a node has an attribute with number \type {id} set. It returns the @@ -1691,12 +1691,12 @@ zero attributes is assumed. \stopsubsubsection -\startsubsubsection[title={\type {find_attribute}}] +\startsubsubsection[title={\type {findattribute}}] -\libindex {find_attribute} +\libindex {findattribute} \startfunctioncall -<number> v, <node> n = node.find_attribute(<node> n, <number> id) +<number> v, <node> n = node.findattribute(<node> n, <number> id) \stopfunctioncall Finds the first node that has attribute with number \type {id} set. It returns @@ -1704,12 +1704,12 @@ the value and the node if there is a match and otherwise nothing. \stopsubsubsection -\startsubsubsection[title={\type {set_attribute}}] +\startsubsubsection[title={\type {setattribute}}] -\libindex {set_attribute} +\libindex {setattribute} \startfunctioncall -node.set_attribute(<node> n, <number> id, <number> val) +node.setattribute(<node> n, <number> id, <number> val) \stopfunctioncall Sets the attribute with number \type {id} to the value \type {val}. Duplicate @@ -1717,15 +1717,15 @@ assignments are ignored. \stopsubsubsection -\startsubsubsection[title={\type {unset_attribute}}] +\startsubsubsection[title={\type {unsetattribute}}] -\libindex {unset_attribute} +\libindex {unsetattribute} \startfunctioncall <number> v = - node.unset_attribute(<node> n, <number> id) + node.unsetattribute(<node> n, <number> id) <number> v = - node.unset_attribute(<node> n, <number> id, <number> val) + node.unsetattribute(<node> n, <number> id, <number> val) \stopfunctioncall Unsets the attribute with number \type {id}. If \type {val} is also supplied, it @@ -1741,13 +1741,13 @@ If the attribute was actually deleted, returns its old value. Otherwise, returns \startsubsection[title={Glyph handling}][library=node] -\startsubsubsection[title={\type {first_glyph}}] +\startsubsubsection[title={\type {firstglyph}}] -\libindex {first_glyph} +\libindex {firstglyph} \startfunctioncall -<node> n = node.first_glyph(<node> n) -<node> n = node.first_glyph(<node> n, <node> m) +<node> n = node.firstglyph(<node> n) +<node> n = node.firstglyph(<node> n, <node> m) \stopfunctioncall Returns the first node in the list starting at \type {n} that is a glyph node @@ -1772,14 +1772,14 @@ or not. \stopsubsubsection -\startsubsubsection[title={\type {has_glyph}}] +\startsubsubsection[title={\type {hasglyph}}] -\libindex {has_glyph} +\libindex {hasglyph} This function returns the first glyph or disc node in the given list: \startfunctioncall -<node> n = node.has_glyph(<node> n) +<node> n = node.hasglyph(<node> n) \stopfunctioncall \stopsubsubsection @@ -1815,14 +1815,14 @@ word boundaries are possible). \stopsubsubsection -\startsubsubsection[title={\type {unprotect_glyph[s]}}] +\startsubsubsection[title={\type {unprotectglyph[s]}}] -\libindex {unprotect_glyphs} -\libindex {unprotect_glyph} +\libindex {unprotectglyphs} +\libindex {unprotectglyph} \startfunctioncall -node.unprotect_glyph(<node> n) -node.unprotect_glyphs(<node> n,[<node> n]) +node.unprotectglyph(<node> n) +node.unprotectglyphs(<node> n,[<node> n]) \stopfunctioncall Subtracts 256 from all glyph node subtypes. This and the next function are @@ -1831,14 +1831,14 @@ processing. The second argument is optional and indicates the end of a range. \stopsubsubsection -\startsubsubsection[title={\type {protect_glyph[s]}}] +\startsubsubsection[title={\type {protectglyph[s]}}] -\libindex {protect_glyphs} -\libindex {protect_glyph} +\libindex {protectglyphs} +\libindex {protectglyph} \startfunctioncall -node.protect_glyph(<node> n) -node.protect_glyphs(<node> n,[<node> n]) +node.protectglyph(<node> n) +node.protectglyphs(<node> n,[<node> n]) \stopfunctioncall Adds 256 to all glyph node subtypes in the node list starting at \type {n}, @@ -1849,12 +1849,12 @@ optional and indicates the end of a range. \stopsubsubsection -\startsubsubsection[title={\type {protrusion_skippable}}] +\startsubsubsection[title={\type {protrusionskippable}}] -\libindex {protrusion_skippable} +\libindex {protrusionskippable} \startfunctioncall -<boolean> skippable = node.protrusion_skippable(<node> n) +<boolean> skippable = node.protrusionskippable(<node> n) \stopfunctioncall Returns \type {true} if, for the purpose of line boundary discovery when @@ -1862,10 +1862,10 @@ character protrusion is active, this node can be skipped. \stopsubsubsection -\startsubsubsection[title={\type {check_discretionary}, \type {check_discretionaries}}] +\startsubsubsection[title={\type {checkdiscretionary}, \type {checkdiscretionaries}}] -\libindex{check_discretionary} -\libindex{check_discretionaries} +\libindex{checkdiscretionary} +\libindex{checkdiscretionaries} 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 @@ -1875,8 +1875,8 @@ the linebreak routine 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) +node.checkdiscretionary(<node> n) +node.checkdiscretionaries(<node> head) \stopfunctioncall The plural variant runs over all disc nodes in a list, the singular variant @@ -1884,15 +1884,15 @@ checks one node only (it also checks if the node is a disc node). \stopsubsubsection -\startsubsubsection[title={\type {flatten_discretionaries}}] +\startsubsubsection[title={\type {flattendiscretionaries}}] -\libindex {flatten_discretionaries} +\libindex {flattendiscretionaries} This function will remove the discretionaries in the list and inject the replace field when set. \startfunctioncall -<node> head, count = node.flatten_discretionaries(<node> n) +<node> head, count = node.flattendiscretionaries(<node> n) \stopfunctioncall \stopsubsubsection @@ -2040,18 +2040,18 @@ A simple and somewhat more efficient variant is this: \startsubsection[title={Math}][library=node] -\startsubsubsection[title={\type {mlist_to_hlist}}] +\startsubsubsection[title={\type {mlisttohlist}}] -\libindex {mlist_to_hlist} +\libindex {mlisttohlist} \startfunctioncall <node> h = - node.mlist_to_hlist(<node> n, <string> display_type, <boolean> penalties) + node.mlisttohlist(<node> n, <string> display_type, <boolean> penalties) \stopfunctioncall This runs the internal mlist to hlist conversion, converting the math list in \type {n} into the horizontal list \type {h}. The interface is exactly the same -as for the callback \cbk {mlist_to_hlist}. +as for the callback \cbk {mlisttohlist}. \stopsubsubsection @@ -2204,28 +2204,28 @@ emulated in \LUA\ and not in the engine, so we retain downward compatibility. \starttabulate[|l|c|c|] \DB function \BC node \BC direct \NC emulated \NC \NR \TB -\supported {check_discretionaries} \nop \yes \yes -\supported {check_discretionary} \nop \yes \yes -\supported {copy_list} \yes \yes \relax -%supported {copy_only} \nop \yes \relax +\supported {checkdiscretionaries} \nop \yes \yes +\supported {checkdiscretionary} \nop \yes \yes +\supported {copylist} \yes \yes \relax +%supported {copyonly} \nop \yes \relax \supported {copy} \yes \yes \relax \supported {count} \nop \yes \yes -\supported {current_attributes} \yes \yes \relax +\supported {currentattributes} \yes \yes \relax \supported {dimensions} \nop \yes \yes -\supported {effective_glue} \nop \yes \yes -\supported {end_of_math} \nop \yes \yes -\supported {find_attribute_range} \nop \yes \relax -\supported {find_attribute} \nop \yes \yes -\supported {find_node} \nop \yes \relax -\supported {first_glyph} \nop \yes \yes -\supported {flatten_discretionaries} \nop \yes \yes -\supported {flush_list} \yes \yes \relax -\supported {flush_node} \yes \yes \relax +\supported {effectiveglue} \nop \yes \yes +\supported {endofmath} \nop \yes \yes +\supported {findattributerange} \nop \yes \relax +\supported {findattribute} \nop \yes \yes +\supported {findnode} \nop \yes \relax +\supported {firstglyph} \nop \yes \yes +\supported {flattendiscretionaries} \nop \yes \yes +\supported {flushlist} \yes \yes \relax +\supported {flushnode} \yes \yes \relax \supported {free} \yes \yes \relax -\supported {get_attributes} \nop \yes \relax -\supported {get_attribute} \yes \yes \relax -\supported {get_properties_table} \yes \yes \relax -\supported {get_synctex_fields} \nop \yes \relax +\supported {getattributes} \nop \yes \relax +\supported {getattribute} \yes \yes \relax +\supported {getpropertiestable} \yes \yes \relax +\supported {getsynctexfields} \nop \yes \relax \supported {getattributelist} \nop \yes \relax \supported {getboth} \nop \yes \relax \supported {getbox} \nop \yes \relax @@ -2280,44 +2280,44 @@ emulated in \LUA\ and not in the engine, so we retain downward compatibility. \supported {getxscale} \nop \yes \relax \supported {getxyscale} \nop \yes \relax \supported {getyscale} \nop \yes \relax -\supported {has_attribute} \yes \yes \relax -\supported {has_dimensions} \nop \yes \relax -\supported {has_field} \yes \yes \relax -\supported {has_glyph_option} \nop \yes \yes -\supported {has_glyph} \nop \yes \yes +\supported {hasattribute} \yes \yes \relax +\supported {hasdimensions} \nop \yes \relax +\supported {hasfield} \yes \yes \relax +\supported {hasglyphoption} \nop \yes \yes +\supported {hasglyph} \nop \yes \yes \supported {hpack} \nop \yes \yes \supported {hyphenating} \nop \yes \yes -\supported {ignore_math_skip} \nop \yes \relax -\supported {insert_after} \yes \yes \relax -\supported {insert_before} \yes \yes \relax -\supported {is_char} \nop \yes \relax -\supported {is_direct} \nop \yes \relax -\supported {is_glyph} \nop \yes \relax -\supported {is_next_char} \nop \yes \relax -\supported {is_next_glyph} \nop \yes \relax -\supported {is_node} \yes \yes \relax -\supported {is_prev_char} \nop \yes \relax -\supported {is_prev_glyph} \nop \yes \relax -\supported {is_valid} \nop \yes \relax -\supported {is_zero_glue} \nop \yes \yes +\supported {ignoremathskip} \nop \yes \relax +\supported {insertafter} \yes \yes \relax +\supported {insertbefore} \yes \yes \relax +\supported {ischar} \nop \yes \relax +\supported {isdirect} \nop \yes \relax +\supported {isglyph} \nop \yes \relax +\supported {isnextchar} \nop \yes \relax +\supported {isnextglyph} \nop \yes \relax +\supported {isnode} \yes \yes \relax +\supported {isprevchar} \nop \yes \relax +\supported {isprevglyph} \nop \yes \relax +\supported {isvalid} \nop \yes \relax +\supported {iszeroglue} \nop \yes \yes \supported {kerning} \nop \yes \yes -\supported {last_node} \nop \yes \yes +\supported {lastnode} \nop \yes \yes \supported {length} \nop \yes \yes \supported {ligaturing} \nop \yes \yes -\supported {make_extensible} \nop \yes \yes +\supported {makeextensible} \nop \yes \yes \supported {migrate} \nop \yes \relax -\supported {mlist_to_hlist} \nop \yes \yes +\supported {mlisttohlist} \nop \yes \yes \supported {naturalwidth} \nop \yes \yes \supported {new} \yes \yes \relax %supported {prepend_prevdepth} \nop \yes \yes -\supported {protect_glyphs} \nop \yes \yes -\supported {protect_glyph} \nop \yes \yes -\supported {protrusion_skippable} \nop \yes \yes +\supported {protectglyphs} \nop \yes \yes +\supported {protectglyph} \nop \yes \yes +\supported {protrusionskippable} \nop \yes \yes \supported {rangedimensions} \nop \yes \yes \supported {remove} \yes \yes \relax -\supported {set_attributes} \nop \yes \relax -\supported {set_attribute} \yes \yes \relax -\supported {set_synctex_fields} \nop \yes \relax +\supported {setattributes} \nop \yes \relax +\supported {setattribute} \yes \yes \relax +\supported {setsynctexfields} \nop \yes \relax \supported {setattributelist} \nop \yes \relax \supported {setboth} \nop \yes \relax \supported {setbox} \nop \yes \relax @@ -2365,7 +2365,7 @@ emulated in \LUA\ and not in the engine, so we retain downward compatibility. \supported {setwhd} \nop \yes \relax \supported {setwidth} \nop \yes \relax \supported {slide} \nop \yes \yes -\supported {start_of_par} \nop \yes \relax +\supported {startofpar} \nop \yes \relax \supported {subtype} \nop \nop \relax \supported {tail} \yes \yes \relax \supported {todirect} \nop \yes \relax @@ -2380,13 +2380,13 @@ emulated in \LUA\ and not in the engine, so we retain downward compatibility. \supported {traverse_list} \yes \yes \relax \supported {traverse} \yes \yes \relax \supported {type} \yes \nop \relax -\supported {unprotect_glyphs} \nop \yes \yes -\supported {unprotect_glyph} \nop \yes \yes -\supported {unset_attributes} \nop \yes \relax -\supported {unset_attribute} \yes \yes \relax +\supported {unprotectglyphs} \nop \yes \yes +\supported {unprotectglyph} \nop \yes \yes +\supported {unsetattributes} \nop \yes \relax +\supported {unsetattribute} \yes \yes \relax \supported {usedlist} \nop \yes \yes -\supported {uses_font} \nop \yes \yes -\supported {vertical_break} \nop \yes \relax +\supported {usesfont} \nop \yes \yes +\supported {verticalbreak} \nop \yes \relax \supported {vpack} \nop \yes \yes \supported {write} \yes \yes \relax \LL @@ -2425,9 +2425,9 @@ number, for a glue, kern, hlist, vlist, rule and math nodes as well as glyph nodes (although this last one is not used in native \SYNCTEX). \startfunctioncall -node.set_synctex_fields(<integer> f, <integer> l) +node.setsynctexfields(<integer> f, <integer> l) <integer> f, <integer> l = - node.get_synctex_fields(<node> n) + node.getsynctexfields(<node> n) \stopfunctioncall Of course you need to know what you're doing as no checking on sane values takes @@ -2477,9 +2477,8 @@ This is experimental code and might take a while to become frozen. \topicindex {nodes+properties} \topicindex {properties} -\libindex{flush_properties_table} -\libindex{get_properties_table} -\libindex{set_properties_mode} +\libindex{getpropertiestable} +\libindex{setpropertiesmode} 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 consult them at the @@ -2576,8 +2575,7 @@ with \CONTEXT\ uses the \type {injections} subtable and you should not mess with that one! There are a few helper functions that you normally should not touch as user: \typ -{flush_properties_table} will wipe the table (normally a bad idea), \typ -{get_properties_table} and will give the table that stores properties (using +{getpropertiestable} and will give the table that stores properties (using direct entries) and you can best not mess too much with that one either because \LUATEX\ itself will make sure that entries related to nodes will get wiped when nodes get freed, so that the \LUA\ garbage collector can do its job. In fact, the diff --git a/doc/context/sources/general/manuals/luametatex/luametatex-tex.tex b/doc/context/sources/general/manuals/luametatex/luametatex-tex.tex index 503bbfd82..decabbca7 100644 --- a/doc/context/sources/general/manuals/luametatex/luametatex-tex.tex +++ b/doc/context/sources/general/manuals/luametatex/luametatex-tex.tex @@ -1637,61 +1637,35 @@ debugging and the (relative state) numbers can change with the implementation. \stopsubsection -\startsubsection[title={Randomizers}] - -\libindex{lua_math_random} -\libindex{lua_math_randomseed} -\libindex{init_rand} -\libindex{normal_rand} -\libindex{uniform_rand} -\libindex{uniformdeviate} - -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). - -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 -{uniformdeviate} which behaves like the primitive and expects a scaled integer, so - -\startfunctioncall -tex.print(tex.uniformdeviate(65536)/65536) -\stopfunctioncall - -will give a random number between zero and one. - -\stopsubsection - \startsubsection[reference=synctex,title={Functions related to synctex}] \topicindex {synctex} -\libindex{set_synctex_mode} \libindex{get_synctex_mode} -\libindex{set_synctex_no_files} -\libindex{set_synctex_tag} \libindex{get_synctex_tag} \libindex{force_synctex_tag} -\libindex{set_synctex_line} \libindex{get_synctex_line} \libindex{force_synctex_line} +\libindex{setsynctexmode} \libindex{getsynctexmode} +\libindex{setsynctexnofiles} +\libindex{setsynctextag} \libindex{getsynctextag} \libindex{forcesynctextag} +\libindex{setsynctexline} \libindex{getsynctexline} \libindex{forcesynctexline} The next helpers only make sense when you implement your own synctex logic. Keep in mind that the library used in editors assumes a certain logic and is geared for plain and \LATEX, so after a decade users expect a certain behaviour. \starttabulate[|l|p|] -\DB name \BC explanation \NC \NR +\DB name \BC explanation \NC \NR \TB -\NC \type{set_synctex_mode} \NC \type {0} is the default and used normal synctex - logic, \type {1} uses the values set by the next - helpers while \type {2} also sets these for glyph - nodes; \type{3} sets glyphs and glue and \type {4} - sets only glyphs \NC \NR -\NC \type{set_synctex_tag} \NC set the current tag (file) value (obeys save stack) \NC \NR -\NC \type{set_synctex_line} \NC set the current line value (obeys save stack) \NC \NR -\NC \type{set_synctex_no_files} \NC disable synctex file logging \NC \NR -\NC \type{get_synctex_mode} \NC returns the current mode (for values see above) \NC \NR -\NC \type{get_synctex_tag} \NC get the currently set value of tag (file) \NC \NR -\NC \type{get_synctex_line} \NC get the currently set value of line \NC \NR -\NC \type{force_synctex_tag} \NC overload the tag (file) value (\type {0} resets) \NC \NR -\NC \type{force_synctex_line} \NC overload the line value (\type {0} resets) \NC \NR +\NC \type{setsynctexmode} \NC \type {0} is the default and used normal synctex + logic, \type {1} uses the values set by the next + helpers while \type {2} also sets these for glyph + nodes; \type{3} sets glyphs and glue and \type {4} + sets only glyphs \NC \NR +\NC \type{setsynctextag} \NC set the current tag (file) value (obeys save stack) \NC \NR +\NC \type{setsynctexline} \NC set the current line value (obeys save stack) \NC \NR +\NC \type{setsynctexnofiles} \NC disable synctex file logging \NC \NR +\NC \type{getsynctexmode} \NC returns the current mode (for values see above) \NC \NR +\NC \type{getsynctextag} \NC get the currently set value of tag (file) \NC \NR +\NC \type{getsynctexline} \NC get the currently set value of line \NC \NR +\NC \type{forcesynctextag} \NC overload the tag (file) value (\type {0} resets) \NC \NR +\NC \type{forcesynctexline} \NC overload the line value (\type {0} resets) \NC \NR \LL \stoptabulate @@ -1746,13 +1720,15 @@ be tested first instead of simply quitting. This library takes care of the low|-|level I/O interface: writing to the log file and|/|or console. -\startsubsection[title={\type {write}}] +\startsubsection[title={\type {write} and \type {writeselector}}] \libindex{write} +\libindex{writeselector} \startfunctioncall texio.write(<string> target, <string> s, ...) texio.write(<string> s, ...) +texio.writeselector(<string> s, ...) \stopfunctioncall Without the \type {target} argument, writes all given strings to the same @@ -1767,19 +1743,24 @@ prevent \LUA\ from interpreting the first string as the target. \stopsubsection -\startsubsection[title={\type {write_nl}}] +\startsubsection[title={\type {writenl} and \type {writeselectornl}}] -\libindex{write_nl} +\libindex{writenl} +\libindex{writeselectornl} \startfunctioncall -texio.write_nl(<string> target, <string> s, ...) -texio.write_nl(<string> s, ...) +texio.writenl(<string> target, <string> s, ...) +texio.writenl(<string> s, ...) +texio.writeselectornl(<string> target, ...) \stopfunctioncall 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. +The selector variants always expect a selector, so there is no misunderstanding +if \type {logfile} is a string or selector. + \stopsubsection \startsubsection[title={\type {setescape}}] @@ -1812,20 +1793,20 @@ to know what you're doing (or more precise: what \TEX\ is doing with input). \topicindex{libraries+\type{token}} \topicindex{tokens} -\libindex{scan_keyword} -\libindex{scan_keywordcs} -\libindex{scan_int} -\libindex{scan_real} -\libindex{scan_float} -\libindex{scan_dimen} -\libindex{scan_glue} -\libindex{scan_toks} -\libindex{scan_code} -\libindex{scan_string} -\libindex{scan_argument} -\libindex{scan_word} -\libindex{scan_csname} -\libindex{scan_list} +\libindex{scankeyword} +\libindex{scankeywordcs} +\libindex{scanint} +\libindex{scanreal} +\libindex{scanfloat} +\libindex{scandimen} +\libindex{scanglue} +\libindex{scantoks} +\libindex{scancode} +\libindex{scanstring} +\libindex{scanargument} +\libindex{scanword} +\libindex{scancsname} +\libindex{scanlist} 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 @@ -1837,26 +1818,26 @@ minimal set of tools and no solutions. The scanner functions are probably the most intriguing. \starttabulate[|l|l|p|] -\DB function \BC argument \BC result \NC \NR +\DB function \BC argument \BC result \NC \NR \TB -\NC \type{scan_keyword} \NC string \NC returns true if the given keyword is gobbled; as with - the regular \TEX\ keyword scanner this is case insensitive - (and \ASCII\ based) \NC \NR -\NC \type{scan_keywordcs} \NC string \NC returns true if the given keyword is gobbled; this variant - is case sensitive and also suitable for \UTF8 \NC \NR -\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 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 \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} - (which then get expanded) \NC \NR -\NC \type{scan_word} \NC \NC returns a sequence of characters with catcode 11 or 12 as string \NC \NR -\NC \type{scan_csname} \NC \NC returns \type {foo} after scanning \type {\foo} \NC \NR -\NC \type{scan_list} \NC \NC picks up a box specification and returns a \type {[h|v]list} node \NC \NR +\NC \type{scankeyword} \NC string \NC returns true if the given keyword is gobbled; as with + the regular \TEX\ keyword scanner this is case insensitive + (and \ASCII\ based) \NC \NR +\NC \type{scankeywordcs} \NC string \NC returns true if the given keyword is gobbled; this variant + is case sensitive and also suitable for \UTF8 \NC \NR +\NC \type{scanint} \NC \NC returns an integer \NC \NR +\NC \type{scanreal} \NC \NC returns a number from e.g.\ \type {1}, \type {1.1}, \type {.1} with optional collapsed signs \NC \NR +\NC \type{scanfloat} \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{scandimen} \NC infinity, mu-units \NC returns a number representing a dimension or two numbers being the filler and order \NC \NR +\NC \type{scanglue} \NC mu-units \NC returns a glue spec node \NC \NR +\NC \type{scantoks} \NC definer, expand \NC returns a table of tokens \NC \NR +\NC \type{scancode} \NC bitset \NC returns a character if its category is in the given bitset (representing catcodes) \NC \NR +\NC \type{scanstring} \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{scanargument} \NC \NC this one is simular to \type {scanstring} but also accepts a \type {\cs} + (which then get expanded) \NC \NR +\NC \type{scanword} \NC \NC returns a sequence of characters with catcode 11 or 12 as string \NC \NR +\NC \type{scancsname} \NC \NC returns \type {foo} after scanning \type {\foo} \NC \NR +\NC \type{scanlist} \NC \NC picks up a box specification and returns a \type {[h|v]list} node \NC \NR \LL \stoptabulate @@ -1864,7 +1845,7 @@ The integer, dimension and glue scanners take an extra optional argument that signals that en optional equal is permitted. 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 {scan_keyword} +The \type {scancode} function takes an optional number, the \type {scankeyword} 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 @@ -1872,7 +1853,7 @@ macro, in which case the result will also provide information about what arguments are expected and in the result this is separated from the meaning by a separator token. The \type {expand} flag determines if the list will be expanded. -The \type {scan_argument} function expands the given argument. When a braced +The \type {scanargument} function expands the given argument. When a braced argument is scanned, expansion can be prohibited by passing \type {false} (default is \type {true}). In case of a control sequence passing \type {false} will result in a one|-|level expansion (the meaning of the macro). @@ -1894,9 +1875,9 @@ we get: \starttabulate[|l|Tl|l|] \DB name \BC result \NC \NR \TB -\NC \type {\directlua{token.scan_string()}{foo}} \NC \directlua{context("{\\red\\type {"..token.scan_string().."}}")} {foo} \NC full expansion \NC \NR -\NC \type {\directlua{token.scan_string()}foo} \NC \directlua{context("{\\red\\type {"..token.scan_string().."}}")} foo \NC letters and others \NC \NR -\NC \type {\directlua{token.scan_string()}\foo} \NC \directlua{context("{\\red\\type {"..token.scan_string().."}}")}\foo \NC meaning \NC \NR +\NC \type {\directlua{token.scanstring()}{foo}} \NC \directlua{context("{\\red\\type {"..token.scanstring().."}}")} {foo} \NC full expansion \NC \NR +\NC \type {\directlua{token.scanstring()}foo} \NC \directlua{context("{\\red\\type {"..token.scanstring().."}}")} foo \NC letters and others \NC \NR +\NC \type {\directlua{token.scanstring()}\foo} \NC \directlua{context("{\\red\\type {"..token.scanstring().."}}")}\foo \NC meaning \NC \NR \LL \stoptabulate @@ -1905,13 +1886,13 @@ expanded definition (\prm {edef}'d). In the case of the braced variant one can o course use the \prm {detokenize} and \prm {unexpanded} primitives since there we do expand. -The \type {scan_word} scanner can be used to implement for instance a number +The \type {scanword} scanner can be used to implement for instance a number scanner. An optional boolean argument can signal that a trailing space or \type {\relax} should be gobbled: \starttyping -function token.scan_number(base) - return tonumber(token.scan_word(),base) +function token.scannumber(base) + return tonumber(token.scanword(),base) end \stoptyping @@ -1942,7 +1923,7 @@ You can also do this: \starttyping \directlua { function mymacro() - local d = token.scan_dimen() + local d = token.scandimen() ... end } @@ -1975,19 +1956,19 @@ a bit but for passing strings conversion to and from tokens has to be done anywa \startsubsection[title={Picking up one token}] -\libindex {scan_next} -\libindex {scan_next_expanded} -\libindex {skip_next} -\libindex {skip_next_expanded} -\libindex {peek_next} -\libindex {peek_next_expanded} -\libindex {scan_token} +\libindex {scannext} +\libindex {scannextexpanded} +\libindex {skipnext} +\libindex {skipnextexpanded} +\libindex {peeknext} +\libindex {peeknextexpanded} +\libindex {scantoken} \libindex {expand} The scanners look for a sequence. When you want to pick up one token from the -input you use \type {scan_next}. This creates a token with the (low level) +input you use \type {scannext}. This creates a token with the (low level) properties as discussed next. This token is just the next one. If you want to -enforce expansion first you can use \type {scan_token} or the \type {_expanded} +enforce expansion first you can use \type {scantoken} or the \type {_expanded} variants. Internally tokens are characterized by a number that packs a lot of information. In order to access the bits of information a token is wrapped in a userdata object. @@ -1998,14 +1979,14 @@ enough about \TEX\ not to be too worried about that. It basically is a call to the internal expand related function. \starttabulate[|lT|p|] -\DB name \BC explanation \NC \NR +\DB name \BC explanation \NC \NR \TB -\NC scan_next \NC get the next token \NC \NR -\NC scan_next_expanded \NC get the next expanded token \NC \NR -\NC skip_next \NC skip the next token \NC \NR -\NC skip_next_expanded \NC skip the next expanded token \NC \NR -\NC peek_next \NC get the next token and put it back in the input \NC \NR -\NC peek_next_expanded \NC get the next expanded token and put it back in the input \NC \NR +\NC scannext \NC get the next token \NC \NR +\NC scannextexpanded \NC get the next expanded token \NC \NR +\NC skipnext \NC skip the next token \NC \NR +\NC skipnextexpanded \NC skip the next expanded token \NC \NR +\NC peeknext \NC get the next token and put it back in the input \NC \NR +\NC peeknextexpanded \NC get the next expanded token and put it back in the input \NC \NR \LL \stoptabulate @@ -2026,20 +2007,20 @@ alike. \libindex{commands} \libindex{command_id} -\libindex{get_command} -\libindex{get_cmdname} -\libindex{get_csname} -\libindex{get_id} -\libindex{get_active} -\libindex{get_expandable} -\libindex{get_protected} -\libindex{get_mode} -\libindex{get_index} -\libindex{get_tok} -\libindex{get_frozen} -\libindex{get_user} - -\libindex{scan_next} +\libindex{getcommand} +\libindex{getcmdname} +\libindex{getcsname} +\libindex{getid} +\libindex{getactive} +\libindex{getexpandable} +\libindex{getprotected} +\libindex{getmode} +\libindex{getindex} +\libindex{gettok} +\libindex{getfrozen} +\libindex{getuser} + +\libindex{scannext} The creator function can be used as follows: @@ -2069,7 +2050,7 @@ primitive. The possible properties of tokens are: \LL \stoptabulate -Alternatively you can use a getter \type {get_<fieldname>} to access a property +Alternatively you can use a getter \type {get<fieldname>} to access a property of a token. The numbers that represent a catcode are the same as in \TEX\ itself, so using @@ -2124,14 +2105,14 @@ need to know that boundary condition. \topicindex {macros} -\libindex{set_macro} -\libindex{get_macro} -\libindex{get_meaning} -\libindex{set_char} -\libindex{set_lua} -\libindex{get_functions_table} -\libindex{push_macro} -\libindex{pop_macro} +\libindex{setmacro} +\libindex{getmacro} +\libindex{getmeaning} +\libindex{setchar} +\libindex{setlua} +\libindex{getfunctionstable} +\libindex{pushmacro} +\libindex{popmacro} The \type {set_macro} function can get upto 4 arguments: @@ -2157,8 +2138,8 @@ The results are like: \def\csname{} \stoptyping -The \type {get_macro} function can be used to get the content of a macro while -the \type {get_meaning} function gives the meaning including the argument +The \type {getmacro} function can be used to get the content of a macro while +the \type {getmeaning} function gives the meaning including the argument specification (as usual in \TEX\ separated by \type {->}). The \type {set_char} function can be used to do a \prm {chardef} at the @@ -2177,11 +2158,11 @@ set_lua("mycode",id,"global","protected") \stoptyping This creates a token that refers to a \LUA\ function with an entry in the table -that you can access with \type {lua.get_functions_table}. It is the companion +that you can access with \type {lua.getfunctions_table}. It is the companion to \lpr {luadef}. When the first (and only) argument is true the size will preset to the value of \type {texconfig.function_size}. -The \type {push_macro} and \type {pop_macro} function are very experimental and +The \type {pushmacro} and \type {popmacro} function are very experimental and can be used to get and set an existing macro. The push call returns a user data object and the pop takes such a userdata object. These object have no accessors and are to be seen as abstractions. @@ -2190,20 +2171,20 @@ and are to be seen as abstractions. \startsubsection[title={Pushing back}] -\libindex{scan_next} -\libindex{put_next} +\libindex{scannext} +\libindex{putnext} There is a (for now) experimental putter: \starttyping -local t1 = token.scan_next() -local t2 = token.scan_next() -local t3 = token.scan_next() -local t4 = token.scan_next() +local t1 = token.scannext() +local t2 = token.scannext() +local t3 = token.scannext() +local t4 = token.scannext() -- watch out, we flush in sequence -token.put_next { t1, t2 } +token.putnext { t1, t2 } -- but this one gets pushed in front -token.put_next ( t3, t4 ) +token.putnext ( t3, t4 ) \stoptyping When we scan \type {wxyz!} we get \type {yzwx!} back. The argument is either a @@ -2218,11 +2199,11 @@ works out okay: \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)") + token.putnext("(the)") + token.putnext(list) + token.putnext("(order)") + token.putnext(unpack(list)) + token.putnext("(is reversed)") } \stopbuffer @@ -2259,9 +2240,9 @@ create a hash entry and when later it gets defined that entry will be reused. So \type {\oof} really exists but can be in an undefined state. \startbuffer[demo] -oof : \directlua{tex.print(token.scan_csname())}\oof -foo : \directlua{tex.print(token.scan_csname())}\foo -myfirstoof : \directlua{tex.print(token.scan_csname())}\myfirstoof +oof : \directlua{tex.print(token.scancsname())}\oof +foo : \directlua{tex.print(token.scancsname())}\foo +myfirstoof : \directlua{tex.print(token.scancsname())}\myfirstoof \stopbuffer \startlines @@ -2307,9 +2288,9 @@ 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.scan_next() tex.print(t.id.." "..t.tok)}\myfirstoof -\directlua{local t = token.scan_next() tex.print(t.id.." "..t.tok)}\mysecondoof -\directlua{local t = token.scan_next() tex.print(t.id.." "..t.tok)}\mythirdoof +\directlua{local t = token.scannext() tex.print(t.id.." "..t.tok)}\myfirstoof +\directlua{local t = token.scannext() tex.print(t.id.." "..t.tok)}\mysecondoof +\directlua{local t = token.scannext() tex.print(t.id.." "..t.tok)}\mythirdoof \stopbuffer \startlines diff --git a/doc/context/sources/general/manuals/luametatex/luametatex.tex b/doc/context/sources/general/manuals/luametatex/luametatex.tex index b7b0ab749..48279e1a8 100644 --- a/doc/context/sources/general/manuals/luametatex/luametatex.tex +++ b/doc/context/sources/general/manuals/luametatex/luametatex.tex @@ -106,7 +106,7 @@ \stopfrontmatter \startbodymatter - \component luametatex-preamble + \component luametatex-internals \component luametatex-differences \component luametatex-modifications \component luametatex-lua |