From a94278f9e2c781a67d137e0df26c35592f60cb0b Mon Sep 17 00:00:00 2001 From: Taco Hoekwater Date: Fri, 18 Apr 2008 12:27:06 +0000 Subject: luatex 0.25.3 git-svn-id: svn://tug.org/texlive/trunk@7494 c570f23f-e606-0410-a88d-b1316a301751 --- Master/texmf-dist/doc/luatex/luatexref-env.tex | 312 ++ Master/texmf-dist/doc/luatex/luatexref-t.pdf | Bin 0 -> 446811 bytes Master/texmf-dist/doc/luatex/luatexref-t.tex | 6422 ++++++++++++++++++++++++ 3 files changed, 6734 insertions(+) create mode 100644 Master/texmf-dist/doc/luatex/luatexref-env.tex create mode 100644 Master/texmf-dist/doc/luatex/luatexref-t.pdf create mode 100644 Master/texmf-dist/doc/luatex/luatexref-t.tex (limited to 'Master/texmf-dist/doc/luatex') diff --git a/Master/texmf-dist/doc/luatex/luatexref-env.tex b/Master/texmf-dist/doc/luatex/luatexref-env.tex new file mode 100644 index 00000000000..69ddd7496ca --- /dev/null +++ b/Master/texmf-dist/doc/luatex/luatexref-env.tex @@ -0,0 +1,312 @@ +% engine=luatex + +\startenvironment luatexref-env + +\usemodule[abr-02] + +% \tex : tex command +% \lua : native lua code +% \luatex : lua lib, function, value defined in luatex + +\catcode`\_=12 % we will make a nice attribute for this kind of break stuff + +\setuptolerance[stretch,tolerant] + +\setuptype[lines=hyphenated] \setuptyping[lines=hyphenated] + +\let\lua \type +\let\luatex \type + +\def\|{\string|} +\def\>{\string>} + +\def\showfields#1{\ctxlua + { do + local t = string.split('#1',',') + local r = { } + for _,a in pairs(node.fields(t[1],t[2])) do + if not (a == 'id' or a == 'subtype' or a =='next' or a=='prev') then + table.insert(r,'\\type{'.. a .. '}') + end + end + tex.sprint(table.concat(r, ', ')) + end + }% +} + +\def\todo#1% + {\dontleavehmode{\bf\red }} + +\setuplayout + [height=middle, + width=middle, + backspace=2cm, + topspace=2cm] + +\setuppagenumbering + [alternative=doublesided] + +\setupitemize[each][packed] + +\setupwhitespace[medium] + +\preloadtypescripts + +\definetypeface[mainfacenormal] [ss][sans] [iwona] [default] +\definetypeface[mainfacenormal] [rm][serif][palatino] [default] +\definetypeface[mainfacenormal] [tt][mono] [modern] [default][rscale=1.1] +\definetypeface[mainfacenormal] [mm][math] [iwona] [default][encoding=default] + +\definetypeface[mainfacemedium] [ss][sans] [iwona-medium][default] +\definetypeface[mainfacenormal] [rm][serif][palatino] [default] +\definetypeface[mainfacemedium] [tt][mono] [modern] [default][rscale=1.1] +\definetypeface[mainfacemedium] [mm][math] [iwona-medium][default][encoding=default] + +\definetypeface[mainfacenarrowtt][tt][mono] [modern] [default][rscale=1.1] + +\setupbodyfont[mainfacenormal,11pt] + +\definehead + [remark] + [subsubsubject] + +\setuphead [chapter] [style=\mainfacemedium\bfd,color=blue] +\setuphead [section] [style=\mainfacemedium\bfc,color=blue] +\setuphead [subsection] [style=\mainfacemedium\bfb,color=blue] +\setuphead [subsubsection][style=\mainfacemedium\bfa,color=blue] + +\setupheadertexts + [] + +\setupcolors + [state=start] + +\setuptyping + [color=blue, +]% style=\mainfacenarrowtt] + +\definetyping[functioncall] + +\setuptype + [color=blue, +]% style=\mainfacenarrowtt] + +\definecolor[blue] [b=.5] +\definecolor[red] [r=.5] +\definecolor[green][g=.5] +\runMPgraphicstrue +\startuseMPgraphic{lualogo} + color luaplanetcolor ; luaplanetcolor := .5blue ; + color luaholecolor ; luaholecolor := white ; + numeric luaextraangle ; luaextraangle := 0 ; + + vardef lualogo = image ( + % Graphic design by A. Nakonechnyj. Copyright (c) 1998, All rights reserved. + + save luaorbitcolor, d, r, p ; color luaorbitcolor ; numeric d, r, p ; + + luaorbitcolor := .5luaholecolor ; d := sqrt(2)/4 ; r := 1/4 ; p := r/8 ; + + fill fullcircle scaled 1 withcolor luaplanetcolor ; + draw fullcircle rotated 40.5 scaled (1+r) dashed evenly scaled p withpen pencircle scaled (p/2) withcolor luaorbitcolor ; + fill fullcircle scaled r shifted (d+1/8,d+1/8) rotated luaextraangle withcolor luaplanetcolor ; + fill fullcircle scaled r shifted (d-1/8,d-1/8) withcolor luaholecolor ; + ) enddef ; + +\stopuseMPgraphic + +\startuseMPgraphic{luapage} + \includeMPgraphic{lualogo} + + StartPage ; + + fill Page withcolor (white-luaplanetcolor) ; + + picture p ; p := lualogo xsized (3PaperWidth/5) ; + draw p shifted center Page shifted (0,-ypart center ulcorner p) ; + + StopPage ; +\stopuseMPgraphic + +\startuseMPgraphic{luanumber} + \includeMPgraphic{lualogo} +% luaextraangle := \realfolio*360/\lastpage ; + luaextraangle := 10 * ( (\realfolio-2)*36/(\lastpage-2) ) ; + picture p ; p := lualogo ; + setbounds p to boundingbox fullcircle ; + draw p ysized 1cm ; +\stopuseMPgraphic + +\definelayer + [page] + [width=\paperwidth, + height=\paperheight] + +\setupbackgrounds + [leftpage] + [background=page] + +\setupbackgrounds + [rightpage] + [background=page] + +\startsetups pagenumber:right + \setlayerframed + [page] + [preset=rightbottom,offset=1cm] + [frame=off,height=1cm,offset=overlay] + {\useMPgraphic{luanumber}} + \setlayerframed + [page] + [preset=rightbottom,offset=1cm,x=1.5cm] + [frame=off,height=1cm,width=1cm,offset=overlay] + {\pagenumber} + \setlayerframed + [page] + [preset=rightbottom,offset=1cm,x=2.5cm] + [frame=off,height=1cm,offset=overlay] + {\getmarking[chapter]}% Lua\TeX\ Reference Manual} +\stopsetups + +\startsetups pagenumber:left + \setlayerframed + [page] + [preset=leftbottom,offset=1cm,x=2.5cm] + [frame=off,height=1cm,offset=overlay] + {\getmarking[chapter]} + \setlayerframed + [page] + [preset=leftbottom,offset=1cm,x=1.5cm] + [frame=off,height=1cm,width=1cm,offset=overlay] + {\pagenumber} + \setlayerframed + [page] + [preset=leftbottom,offset=1cm] + [frame=off,height=1cm,offset=overlay] + {\useMPgraphic{luanumber}} +\stopsetups + +\startsetups [titlepage] + + \startstandardmakeup + + \switchtobodyfont[mainfacemedium] + \definedfont[Bold at .08\paperheight] \setupinterlinespace + + \setlayer[page]{\useMPgraphic{luapage}} + + \setlayerframed + [page] + [preset=middletop, + voffset=.05\paperheight] + [align=middle, + foregroundcolor=blue, + frame=off] + {Lua\TeX\\Reference} + + \definedfont[Bold at 24pt] \setupinterlinespace + + \setlayerframed + [page] + [preset=middletop, + voffset=.35\paperheight] + [align=middle, + foregroundcolor=blue, + frame=off] + {\doifsomething + {\getvariable{document}{snapshot}} + {snapshot \getvariable{document}{snapshot}}% + \doifsomething + {\getvariable{document}{beta}} + {beta \getvariable{document}{beta}}% + } + + \stopstandardmakeup + + \startstandardmakeup + + \raggedleft + + \definedfont[Bold at 48pt] \setupinterlinespace + + \start \blue Lua\TeX \endgraf Reference \endgraf Manual \stop + + \blank + + \definedfont[Bold at 24pt] \setupinterlinespace + + \blank + + \vfill + + \definedfont[Bold at 12pt] \setupinterlinespace + + copyright: Lua\TeX\ development team \endgraf + more info: www.luatex.org \endgraf + version: \currentdate \doifsomething{\getvariable{document}{snapshot}}{(snapshot \getvariable{document}{snapshot})} \endgraf + + \stopstandardmakeup + + \setupbackgrounds + [leftpage] + [setups=pagenumber:left] + + \setupbackgrounds + [rightpage] + [setups=pagenumber:right] + +\stopsetups + +\def\nonterminal#1>{\mathematics{\langle\hbox{{\rm #1}}\rangle}} + +\ifx\directlua\undefined + + \definetyping[syntax] + \definetype[syntax] + +\else + + % taco's brainwave -) + + \newcatcodetable\syntaxcodetable + + \def\makesyntaxcodetable + {\begingroup + \catcode`\<=13 \catcode`\|=12 + \catcode`\!= 0 \catcode`\\=12 + \savecatcodetable\syntaxcodetable + \endgroup} + + \makesyntaxcodetable + + \def\startsyntax {\begingroup\catcodetable\syntaxcodetable \dostartsyntax} + \def\syntax {\begingroup\catcodetable\syntaxcodetable \dosyntax} + + \def\syntaxenvbody#1% + {\par + \tt + \startnarrower + {\blue #1}% + \stopnarrower + \par} + + \def\syntaxbody#1% + {{\blue \tt #1}} + + \bgroup \catcodetable\syntaxcodetable + + !gdef!dostartsyntax#1\stopsyntax{!let=1.114.112$, \LUATEX\ will +actually print the single byte corresponding to $c-1.114.112$. + +Output to the terminal uses \type{^^} notation for the lower control +range ($c<32$), with the exception of \type{^^I}, \type{^^J} and +\type{^^M}. These are considered \quote{safe} and therefore printed as-is. + +Normalization of the \UNICODE\ input can be handled by a macro package +during callback processing (this will be explained in \in{section}[iocallback]). + +\section{Wide math characters} + +Text handling is now extended up to the full \UNICODE\ range, but math mode +deals mostly with glyphs in fonts directly and fonts tend to be 16-bit +at maximum. The extension from 8-bit to 16-bit was already present in +\ALEPH\ by means of a set of extra primitives. + +Therefore, the math primitives from \TEX\ and \ALEPH\ are kept mostly +as they are, except for the ones that convert from input to math +commands like \type{matcode} and \type{omathcode}. The traditional +\TEX\ primitives are unchanged, their arguments are upscaled from 8~to +16~bits internally (as in \ALEPH). + +% hahe: again wrong by 1? +\starttabulate[|l|l|l|l|] +\NC \bf primitive \NC \bf max index/bits \NC \bf hex \NC \bf numeric \NC\NR +\NC \tex{mathchardef} \NC 15 \NC \tt~~~8000 \NC $2^{3}*2^{4}*2^{8}$ \NC\NR +\NC \tex{mathcode} \NC 8=15 \NC \tt~~~~~FF = ~~~800 \NC $2^{3}*2^{4}*2^{8}$ \NC\NR +\NC \tex{delcode} \NC 8=24 \NC \tt~~~~~FF = ~FFFFF \NC $2^{4}*2^{8}*2^{4}*2^{8}$ \NC\NR +\NC \tex{mathchar} \NC 15 \NC \tt~~~7FFF \NC $2^{3}*2^{4}*2^{8}$ \NC\NR +\NC \tex{mathaccent} \NC 15 \NC \tt~~~7FFF \NC $2^{3}*2^{4}*2^{8}$ \NC\NR +\NC \tex{delimiter} \NC 27 \NC \tt7FFFFFF \NC $2^{3}*2^{4}*2^{8}*2^{4}*2^{8}$ \NC\NR +\NC \tex{radical} \NC 27 \NC \tt7FFFFFF \NC $2^{3}*2^{4}*2^{8}*2^{4}*2^{8}$ \NC\NR +\NC \tex{omathchardef}\NC 27 \NC \tt8000000 \NC $2^{3}*2^{8}*2^{16}$ \NC\NR +\NC \tex{omathcode} \NC 21=27 \NC \tt~10FFFF = 8000000 \NC $2^{3}*2^{8}*2^{16}$ \NC\NR +\NC \tex{odelcode} \NC 21=24+24 \NC \tt~10FFFF = ~FFFFFF \NC $2^{8}*2^{16}$ \NC\NR +\NC \NC \NC \tt~~~~~~~ + ~FFFFFF \NC \quad $+ 2^{8}*2^{16}$ \NC\NR +\NC \tex{omathchar} \NC 27 \NC \tt7FFFFFF \NC $2^{3}*2^{8}*2^{18}$ \NC\NR +\NC \tex{omathaccent} \NC 27 \NC \tt7FFFFFF \NC $2^{3}*2^{8}*2^{18}$ \NC\NR +\NC \tex{odelimiter} \NC 27+24 \NC \tt7FFFFFF + ~FFFFFF \NC $2^{3}*2^{8}*2^{16}+2^{8}*2^{16}$ \NC\NR +\NC \tex{oradical} \NC 27+24 \NC \tt7FFFFFF + ~FFFFFF \NC $2^{3}*2^{8}*2^{16}+2^{8}*2^{16}$ \NC\NR +\stoptabulate + +\section{Extended tables} + +All traditional \TEX\ and \ETEX\ registers can be 16 bit numbers as in \ALEPH. The affected commands +are: + +\startcolumns[n=4] +\starttyping +\count +\dimen +\skip +\muskip +\marks +\toks +\countdef +\dimendef +\skipdef +\muskipdef +\toksdef +\box +\unhbox +\unvbox +\copy +\unhcopy +\unvcopy +\wd +\ht +\dp +\setbox +\vsplit +\stoptyping +\stopcolumns + +The same is true for the font-related \PDFTEX\ tables like \type{\rpcode} etc. + +\section{Attribute registers} + +Attributes are a completely new concept in \LUATEX. Syntactically, +they behave a lot like counters: attributes obey \TEX's nesting stack +and can be used after \tex{the} etc.\ just like the normal +\tex{count} registers. + +\startsyntax +\attribute <16-bit number> <31-bit number>!crlf +\attributedef <16-bit number> +\stopsyntax + +Conceptually, an attribute is either \quote{set} or \quote{unset}. Set +attributes can only have values of~0 or more, otherwise they are +considered unset and automatically remapped to an special negative +value meaning \quote{unset} (currently that value is $-1$, but please +test on negativity, not on a specific value). All attributes start +out in the \quote{unset} state (in \INITEX). + +Attributes can be used as extra counter values, but their usefulness +comes mostly from the fact that the numbers and values of all \quote{set} +attributes are attached to all nodes created in their scope. These can +then be queried from any \LUA\ code that deals with node +processing. Future versions of +\LUATEX\ will probably be using specific negative attribute ids for +internal use. Further information about how to use attributes for node +list processing from lua is given in~\in{chapter}[nodes]. + +\subsection{Box attributes} + +Nodes typically receive the list of attributes that is in effect when +they are created. This moment can be quite asynchronous. For example: in +paragraph building, the individual line boxes are created after the +\tex{par} command has been processed, so they will receive the list of +attributes that is in effect then, not the attributes that were in +effect in, say, the first or third line of the paragraph. + +Similar situations happen in \LUATEX\ regularly. A few of the more +obvious problematic cases are dealt with: the attributes for nodes +that are created during hyphenation and ligaturing borrow their +attributes from their surrounding glyphs, and it is possible to +influence box attributes directly. + +But many other inserted nodes, like the nodes resulting from math mode +and alignments, are processed `out of order', and will have the +attributes that are in effect at the precise moment of creation (which +is often later than expected). This area needs studying, and is in +fact one of the reasons for a beta at this moment. + + +It is possible to fine-tune the list of attributes that are applied +to a \type{hbox}, \type{vbox} or \type{vtop} by the use of the +keyword \type{attr}. An example: + +\starttyping +\attribute2=5 +\setbox0=\hbox {Hello} +\setbox2=\hbox attr1=12 attr2=-1{Hello} +\stoptyping + +This will set the attribute list of the box 2 to $1=12$, and the +attributes of box 0 will be $2=5$. As you can see, assigning a +negative value causes an attribute to be ignored. + +The \type{attr} keyword(s) should come before a \type{to} or +\type{spread}, if that is also specified. + +\section{\LUA\ related primitives} + +In order to merge \LUA\ code with \TEX\ input, a few new primitives are +needed. \LUATEX\ has support for 65536 separate \LUA\ interpreter +states. States are automatically created based on the integer argument +to the primitives \tex{directlua} and \tex{latelua}. + + +\subsection{\tex{directlua}} + +The primitive \tex{directlua} is used to execute \LUA\ code immediately. +The syntax is + +\startsyntax +\directlua <16-bit number> +\stopsyntax + +The \syntax{} is expanded fully, and then fed into the +\LUA\ interpreter state indicated by the \syntax{<16-bit number>}. +If the state does not exist yet, it will be initialized +automatically. After reading and expansion has been applied to the +\syntax{}, the resulting token list is converted to a +string as if it was displayed using \type{\the\toks}. On the \LUA\ +side, each \type{\directlua} block is treated as a separate chunk. + +The conversion from and to a token list means that you normally can +not use \LUA\ line comments (starting with \type{--}) within the +argument, as there typically will be only one \quote{line}, so that comment +will then run on until the end of the input. You will either need to +use \TEX-style line comments (starting with \%), or change the \TEX\ +category codes locally. + +\startbuffer +$\pi = \directlua0{tex.print(math.pi)}$ +\stopbuffer + +The \type{\directlua} command is expandable: the results of the \LUA\ +code become effective immediately. As an example, the following +input: +\typebuffer +will result in +\getbuffer + +Because the \syntax{} is a chunk, the normal \LUA\ error +handling is triggered if there is a problem in the included code. The +\LUA\ error messages should be clear enough, but the contextual +information is still pretty bad. Typically, you will only see the line +number of the right brace at the end of the code. + +While on the subject of errors: some of the things you can do inside +\LUA\ code can break up \LUATEX\ pretty bad. If you are not careful +while working with the node list interface, you may even end up with +assertion errors from within the \TEX\ portion of the executable. + +\subsection{\tex{latelua}} + +\tex{latelua} stores \LUA\ code in a whatsit that will be processed +inside the output routine. Its intended use is very similar to +\tex{pdfliteral}. Within the \LUA\ code, you can print \PDF\ +statements directly to the \PDF\ file. + +\startsyntax +\latelua <16-bit number> +\stopsyntax + +\subsection{\tex{luaescapestring}} + +This primitive converts a \TEX\ token sequence so that it can be +safely used as the contents of a \LUA\ string: embedded backslashes, +double and single quotes, and newlines and carriage returns are +escaped. This is done by prepending an extra token consisting of a +backslash with category code~12, and for the line endings, +converting them to \type{n} and \type{r} respectively. The token +sequence is fully expanded. + +\startsyntax +\luaescapestring +\stopsyntax + +Most often, this command is not actually the best way to deal with the +differences between the \TEX\ and \LUA. In very short bits of \LUA\ +code it is often not needed, and for longer stretches of \LUA\ code it +is easier to keep the code in a separate file and load it using \LUA's +\type{dofile}: +\starttyping +\directlua0 { dofile('mysetups.lua')} +\stoptyping + +\subsection{\tex{closelua}} + +This primitive allows you to close a \LUA\ state, freeing all of its +used memory. + +\startsyntax +\closelua <16-bit number> +\stopsyntax + +You cannot close the initial \LUA\ state~(0), attempts to do so +will be silently ignored. + +States are never closed automatically except when a fatal out of +memory error occurs, at which point \LUATEX\ will exit anyway. + +Also be aware that \LUA\ states are not closed immediately, but only +when the \tex{output} routine comes into play next (because there may be +pending \tex{latelua} calls). + +\section{New \ETEX\ primitives} + +\subsection{\tex{clearmarks}} + +This primitive clears a marks class completely, resetting all three +connected mark texts to empty. + +\startsyntax +\clearmarks <16-bit number> +\stopsyntax + +\subsection{\tex{noligs} and \tex{nokerns}} + +These primitives prohibit ligature and kerning insertion at the time +when the initial node list is built by \LUATEX's main control loop. +They are part of a temporary trick and will be removed in the near +future. For now, you need to enable these primitives when you want to +do node list processing of \quote{characters}, where \TEX's normal +processing would get in the way. + +\startsyntax +\noligs !crlf +\nokerns +\stopsyntax + + +\subsection{\tex{formatname}} + +\tex{formatname}'s syntax is identical to \tex{jobname}. + +In \INITEX, the expansion is empty. Otherwise, the expansion is the +value that \tex{jobname} had during the \INITEX\ run that dumped the +currently loaded format. + +\subsection{\tex{scantextokens}} + +The syntax of \tex{scantextokens} is identical to \tex{scantokens}. + +This is a slightly adapted version of \ETEX's \tex{scantokens}. The +differences are: + +\startitemize +\item The last (and usually only) line does not have a + \tex{endlinechar} appended +\item \tex{scantextokens} never raises an EOF error, + and it does not execute \tex{everyeof} tokens. +\item The \quote{.. while end of file ..} error tests are not executed, allowing + the expansion to end on a different grouping level or while a + conditional is still incomplete. +\stopitemize + + +\subsection{Catcode tables} + +Catcode tables are a new feature that allows you to switch to a +predefined catcode regime in a single statement. You can have a +practically unlimited number of different tables. + +The subsystem is backward compatible: if you never use the following +commands, your document will not notice any difference in behavior +compared to traditional \TEX. + +The contents of each catcode table is independent from any other +catcode tables, and their contents is stored and retrieved from the +format file. + +\subsubsection{\tex{catcodetable}} + +\startsyntax +\catcodetable <28-bit number> +\stopsyntax + +The \tex{catcodetable} switches to a different catcode table. +Such a table has to be previously created using one of the two +primitives below, or it has to be zero (table zero is initialized by +\INITEX). + +\subsubsection{\tex{initcatcodetable}} + +\startsyntax +\initcatcodetable <28-bit number> +\stopsyntax + +The \tex{initcatcodetable} creates a new table with catcodes +identical to those defined by \INITEX: + +\starttabulate[|l|l|l|l|] +\NC~0\NC \type{_} \NC \NC \tt escape \NC\NR +\NC~5\NC \tt\letterhat\letterhat M \NC return \NC \tt car\_ret \NC\NR +\NC~9\NC \tt\letterhat\letterhat @ \NC null \NC \tt ignore \NC\NR +\NC10\NC \tt \NC space \NC \tt spacer \NC\NR +\NC11\NC {\tt a} -- {\tt z} \NC \NC \tt letter \NC\NR +\NC11\NC {\tt A} -- {\tt Z} \NC \NC \tt letter \NC\NR +\NC12\NC everything else \NC \NC \tt other \NC\NR +\NC14\NC \tt\letterpercent \NC \NC \tt comment \NC\NR +\NC15\NC \tt\letterhat\letterhat ? \NC delete \NC \tt invalid\_char \NC\NR +\stoptabulate + +The new catcode table is allocated globally: it will not go away after +the current group has ended. If the supplied number is identical to +the currently active table, an error is raised. + +\subsubsection{\tex{savecatcodetable}} + +\startsyntax +\savecatcodetable <28-bit number> +\stopsyntax + +\tex{savecatcodetable} copies the current set of catcodes to a +new table with the requested number. The definitions in this new table +are all treated as if they were made in the outermost level. + +The new table is allocated globally: it will not go away after the +current group has ended. If the supplied number is the currently +active table, an error is raised. + +\subsection{\tex{suppressfontnotfounderror}} + +\startsyntax +\suppressfontnotfounderror = 1 +\stopsyntax + +If this new integer parameter is non-zero, then \LUATEX\ will not +complain about font metrics that are not found. Instead it will +silently skip the font assignment, making the requested csname for the +font \type{\ifx} equal to \type{\nullfont}, so that it can be tested +against that without bothering the user. + +\subsection{Font syntax} + +\LUATEX\ will accept a braced argument as a font name: + +\starttyping +\font\myfont = {cmr10} +\stoptyping + +This allows for embedded spaces, without the need for double quotes. +Macro expansion takes place inside the argument. + +\section{Debugging} + +If \tex{tracingonline} is larger than 2, the node list display will +also print the node number of the nodes. + +\chapter {\LUA\ general} + +\section[init]{Initialization} + +\subsection{\LUATEX\ as a \LUA\ interpreter} + +There are some situations that make \LUATEX\ behave like it is a \LUA\ +interpreter only: +\startitemize[packed] +\item If a \type{--luaonly} option is given on the commandline +\item If the executable is named \type{texlua} (or \type{luatexlua}) +\item if the only non|-|option argument (file) on the commandline has the extension + \type{lua} or \type{luc}. +\stopitemize + +In this mode, it will set \LUA's \type{arg[0]} to the found script +name, pushing preceding options in negative values and the rest of the +commandline in the positive values, just like the \LUA\ +interpreter. + +\LUATEX\ will exit immediately after executing the specified \LUA\ +script and is, in effect, a somewhat bulky standalone \LUA\ +interpreter with a bunch of extra preloaded libraries. + +\subsection{\LUATEX\ as a \LUA\ byte compiler} + +There are two situations that make \LUATEX\ behaves like the \LUA\ +byte compiler: +\startitemize[packed] +\item If a \type{--luaconly} option is given on the commandline +\item If the executable is named \type{texluac} +\stopitemize + +In this mode, \LUATEX\ is exactly like \type{luac} from the standalone +\LUA\ distribution, except that it does not have the \type{-l} switch, +and that it accepts (but ignores) the \type{--luaconly} switch. + +\subsection{Other commandline processing} + +When the \LUATEX\ executable starts, it looks for the \type{--lua} +commandline option. If there is no \type{--lua} option, the +commandline is interpreted in a similar fashion as in traditional +\PDFTEX\ and \ALEPH. But if the option is present, \LUATEX\ will enter an +alternative mode of commandline parsing in comparison to the standard +web2c programs. + +In this mode, a small series of actions is taken in order. At first, +it will only interpret a small subset of the commandline directly: + +\starttabulate[|l|p|] +\NC \tt --lua=s \NC load and execute a \LUA\ initialization script \NC\NR +\NC \tt --safer \NC disable easily exploitable \LUA\ commands \NC\NR +\NC \tt --help \NC display help and exit \NC\NR +\NC \tt --version \NC display version and exit \NC\NR +\stoptabulate + +Now it searches for the requested \LUA\ initialization script. If it +can not be found using the actual name given on the commandline, a +second attempt is made by prepending the value of the environment +variable \type{LUATEXDIR}, if that variable is defined. + +Then it checks the \type{--safer} switch. You can use that to disable +some \LUA\ commands that can easily be abused by a malicious document. At +the moment, this switch \type{nil}s the following functions: + +\starttabulate[|l|l|] +\NC \bf library \NC \bf functions \NC \NR +\NC \tt os \NC \tt execute exec setenv rename remove tmpdir \NC \NR +\NC \tt io \NC \tt popen output tmpfile \NC \NR +\NC \tt lfs \NC \tt rmdir mkdir chdir lock touch \NC \NR +\stoptabulate + +And it makes \lua{io.open()} fail on files that are opened for +anything besides reading. + +Next the initialization script is loaded and executed. From within the +script, the entire commandline is available in the \LUA\ table +\lua{arg}, beginning with \lua {arg[0]}, containing the name of the executable. + +Commandline processing happens very early on. So early, in fact, that +none of \TEX's initializations have taken place yet. For that reason, +the \luatex{tex}, \luatex{token}, \luatex{node} and \luatex{pdf} tables +are off|-|limits during the execution of the startup file (they are +nilled). Special care is taken that \luatex{texio.write} and +\luatex{texio.write_nl} function properly, so that you can at least +report your actions to the log file when (and if) it eventually +becomes opened (note that \TEX\ does not even know its \tex{jobname} +yet at this point). See \in{chapter}[libraries] for more information +about the \LUATEX-specific \LUA\ extension tables. + +The \LUA\ initialization script is loaded into \LUA\ state~0, and +everything you do will remain visible during the rest of the run, with +the exception of the aforementioned \luatex{tex}, \luatex{token}, +\luatex{node} and \luatex{pdf} tables: those will be initialized +to their documented state after the execution of the script. You +should not store anything in variables or within tables with these +four global names, as they will be overwritten completely. + +We recommend you use the startup file only for your own +\TEX|-|independent initializations (if you need any), to parse the +commandline, set values in the \luatex{texconfig} table, and register +the callbacks you need. \LUATEX\ will fetch some of the other +commandline options from the \luatex{texconfig} table at the end of +script execution (see the description of the \luatex{texconfig} table +later on in this document for more details on which ones exactly). + +Unless the \luatex{texconfig} table tells it not to start \KPATHSEA\ +at all (set \luatex{texconfig.kpse_init} to \type{false} for that), +\LUATEX\ acts on three more commandline options after the +initialization script is finished: + +\starttabulate[|l|l|] +\NC \bf flag \NC \bf meaning \NC \NR +\NC \tt --fmt=s \NC set the format name \NC \NR +\NC \tt --progname=s \NC set the progname (only for \KPATHSEA) \NC \NR +\NC \tt --ini \NC enable \INITEX\ mode \NC \NR +\stoptabulate + +In order to initialize the built|-|in \KPATHSEA\ library properly, +\LUATEX\ needs to know the correct \quote{progname} to use, and for that it +needs to check \type{--progname} (and \type{--ini} and \type{--fmt}, if +\type{--progname} is missing). + +\section{\LUA\ changes} + +The C coroutine (COCO) patches from luajit are applied to the Lua core, the used +version is 1.1.3. See \hyphenatedurl{http://luajit.org/coco.html} for details. + +The \lua{read("*line")} function from the io library has been +adjusted so that it is line|-|ending neutral: any of \type{LF}, \type +{CR} or \type{CR+LF} are acceptable line endings. + +The \lua{tostring()} printer for numbers has been changed so that it +returns~\type{0} instead of something like~\hbox{\type{2e-5}} (which confused \TEX\ +enormously) when the value is so small that \TEX\ cannot distinguish +it from zero. + +Dynamic loading of \type{.so} and \type{.dll} files is disabled on +all platforms. + +\lua{luafilesystem} has been extended with two extra boolean functions +(\luatex{isdir(filename)} and \luatex{isfile(filename)}) and one extra +string field in its attributes table (\type{permissions}). + +The \lua{string} library has an extra function: +\luatex{string.explode(s[,m])}. This function returns an array containing +the string argument \type{s} split into substrings based on the value +of the string argument \type{m}. The second argument is a string that +is either empty (this splits the string into characters), a single +character (this splits on each occurrence of that character, possibly +introducing empty strings), or a single character followed by the plus +sign \type{+} (this special version does not create empty +substrings). The default value for \type{m} is \quote{\type{ +}} (multiple +spaces). + +Note: \type{m} is not hidden by surrounding braces (as it would be if +this function was written in \TEX\ macros). + +The \lua{string} library also has six extra iterators that return strings +piecemeal: + +\startitemize +\item \luatex{string.utfvalues(s)} (returns an integer value in the +\UNICODE\ range) +\item \luatex{string.utfcharacters(s)} (returns a string with a single +\UTF-8 token in it) +\item \luatex{string.characters(s)} (a string containing one byte) +\item \luatex{string.characterpairs(s)} (two strings each containing one byte) will +produce an empty second string in the string length was odd. +\item \luatex{string.bytes(s)} (a single byte value) +\item \luatex{string.bytepairs(s)} (two byte values) Will produce nil instead of a +number as its second return value if the string length was odd. +\stopitemize + +The \luatex{string.characterpairs()} and \luatex{string.bytepairs()} +are useful especially in the conversion of UTF-16 encoded data into UTF-8. + + +Note: The \lua{string} library functions \luatex{find} etc. are not +Unicode-aware. In cases where this is required (i.\,e.\ because the +pattern used for searching contains characters above code point 127), +the corresponding functions from \lua{unicode.utf8} should be used. + +\blank + +The \lua{os} library has a few extra functions and variables: + +\startitemize +\item \luatex{os.exec(commandline)} is a variation on \lua{os.execute}. + + The \type{commandline} can be either a single string or a single table. + + If the argument is a table: \LUATEX\ first checks if there is a value at + integer index zero. If there is, this is the command to be executed. Otherwise, + it will use the value at integer index one. (if neither are present, nothing + at all happens). + + The set of consecutive values starting at integer 1 in the table are + the arguments that are passed on to the command (the value at index 1 + becomes \type{argv[0]}). The command is searched for in the execution path, + so there is normally no need to pass on a fully qualified pathname. + + If the argument is a string, then it is automatically converted into + a table by splitting on whitespace. In this case, it is impossible + for the command and first argument to differ from each other. + + In the string argument format, whitespace can be protected by putting (part + of) an argument inside single or double quotes. One layer of quotes is + interpreted by \LUATEX, and all occurences of \type{\"}, \type{\'} or + \type{\\} within the quoted text are un-escaped. In the table format, there + is no string handling taking place. + + This function normally does not return control back to the lua script: the + command will replace the current process. However, it will return \type{nil, 'error'} + if there was a problem while attempting to execute the command. + + On windows, the current process is actually kept in memory until after the + execution of the command has finished. This prevents crashes in situations + where \TEXLUA\ scripts are run inside integrated \TEX\ environments. + + + (the original reason for this command is that it cleans out the current + process before starting the new one, making it especially useful for + use in \TEXLUA.) + +\item \luatex{os.spawn(commandline)} is a returning version of \lua{os.exec}, + with otherwise identical calling conventions. + + If the command ran ok, then the return value is the exit status of the + command. Otherwise, it will return \type{nil, 'error'}. + +\item \luatex{os.setenv('key','value')} + This sets a variable in the environment. Passing \lua{nil} instead of a + value string will remove the variable. + +\item \luatex{os.env} + This is a hash table containing a dump of the variables and values + in the process environment at the start of the run. It is writeable, + but the actual environment is {\it not\/} updated automatically. + +\item \luatex{os.gettimeofday()} +Returns the current `unix time', but as a float. This function is +not available on the SunOS platforms, so do not use this function +for portable documents. + +\item \luatex{os.times()} +Returns the current process times cf. the unix C library `times' +call in seconds. This function is not available on the Windows and SunOS +platforms, so do not use this function for portable documents. + +\item \luatex{os.tmpdir()} This will create a directory in the `current +directory' with the name \type{luatex.XXXXXX} where the X-es are +replaced by a unique string. The function also returns this string, +so you can \type{lfs.chdir()} into it, or \type{nil} if it failed to +create the directory. The user is responsible for cleaning up at +the end of the run, it does not happen automatically. + +\item \luatex{os.type} +This is a string that gives a global indication of the class of operating +system. The possible values are currently \type{windows}, \type{unix}, and +\type{msdos} (you are unlikely to find this value `in the wild'). + +\item \luatex{os.name} +This is a string that gives a more precise indication of the operating +system. These possible values are not yet fixed, and for \type{os.type} values +\type{windows} and \type{msdos}, the \type{os.name} values are simply +\type{windows} and \type{msdos} + +The list for the type \type{unix} is more precise: \type{linux}, +\type{freebsd}, \type{openbsd}, \type{solaris}, \type{sunos} (pre-solaris), +\type{hpux}, \type{irix}, \type{macosx}, \type{bsd} (unknown, but BSD-like), +\type{sysv} (unknown, but SYSV-like), \type{generic} (unknown). + +(\type{os.version} is planned as a future extension) + +\stopitemize + +In stock Lua, many things depend on the current locale. In \LUATEX, we can't do +that, because it makes documents unportable. While \LUATEX\ is running if +forces the following locale settings: +\starttyping + LC_CTYPE=C + LC_COLLATE=C + LC_NUMERIC=C +\stoptyping + +\section {\LUA\ modules} + +Some modules that are normally external to Lua are statically linked +in with \LUATEX, because they offer useful functionality: + +\startitemize +\item \lua{slnunicode}, from the Selene libraries, \hyphenatedurl{http://luaforge.net/projects/sln}. (version 1.1) + +This library has been slightly extended so that the \type{unicode.utf8.*} +functions also accept the first 256 values of Plane~18. This is the range \LUATEX\ +uses for raw binary output, as explained above, + +\item \lua{luazip}, from the kepler project, \hyphenatedurl{http://www.keplerproject.org/luazip/}. + (version 1.2.1, but patched for compilation with lua 5.1) +\item \lua{luafilesystem}, also from the kepler project, \hyphenatedurl{http://www.keplerproject.org/luafilesystem/}. + (version 1.2, but patched for compilation with lua 5.1) +\item \lua{lpeg}, by Roberto Ierusalimschy, \hyphenatedurl{http://www.inf.puc-rio.br/~roberto/lpeg.html}. (version 0.8.1) + +Note: \lua{lpeg} is not Unicode-aware, but interprets strings on a +byte-per-byte basis. This mainly means that \luatex{lpeg.S} cannot be +used with characters above code point 127, since those characters are +encoded using two bytes, and thus \luatex{lpeg.S} will look for one +of those two bytes when matching, not the combination of the two. + +The same is true for \luatex{lpeg.R}, although the latter will display +an error message if used with characters above code point 127: I.\,e.\ +\luatex{lpeg.R('aä')} results in the message \type{bad argument #1 to +'R' (range must have two characters)}, since to \lua{lpeg}, \type{ä} +is two 'characters' (bytes), so \type{aä} totals three. + +\item \lua{lzlib}, by Tiago Dionizio, \hyphenatedurl{http://mega.ist.utl.pt/~tngd/lua/}. (version 0.2) +\item \lua{md5}, by Roberto Ierusalimschy \hyphenatedurl{http://www.inf.puc-rio.br/~roberto/md5/md5-5/md5.html}. +\stopitemize + +\chapter[libraries]{\LUATEX\ \LUA\ Libraries} + +The interfacing between \TEX\ and \LUA\ is facilitated by a set of +library modules. The \LUA\ libraries in this chapter are all defined and +initialized by the \LUATEX\ executable. Together, they allow \LUA\ +scripts to query and change a number of \TEX's internal variables, run +various internal functions \TEX, and set up \LUATEX's hooks to execute +\LUA\ code. + +\section{The \luatex{tex} library} + +The \luatex{tex} table contains a large list of virtual internal \TEX\ +parameters that are partially writable. + +The designation \quote{virtual} means that these items are not properly +defined in \LUA, but are only front\-ends that are handled by a metatable +that operates on the actual \TEX\ values. As a result, most of the \LUA\ +table operators (like \type{pairs} and \type{#}) do not work on such +items. + +At the moment, it is possible to access almost every parameter +that has these characteristics: + +\startitemize[packed] +\item You can use it after \tex{the} +\item It is a single token. +\stopitemize + +This excludes parameters that need extra arguments, like +\tex{the}\tex{scriptfont}. + +The subset comprising simple integer and dimension registers are +writable as well as readable (stuff like \tex{tracingcommands} and +\tex{parindent}). + +\subsection{Integer parameters} + +The integer parameters accept and return \LUA\ numbers. + +Read-write: + +\startcolumns[n=2] +\starttyping +tex.adjdemerits +tex.binoppenalty +tex.brokenpenalty +tex.catcodetable +tex.clubpenalty +tex.day +tex.defaulthyphenchar +tex.defaultskewchar +tex.delimiterfactor +tex.displaywidowpenalty +tex.doublehyphendemerits +tex.endlinechar +tex.errorcontextlines +tex.escapechar +tex.exhyphenpenalty +tex.fam +tex.finalhyphendemerits +tex.floatingpenalty +tex.globaldefs +tex.hangafter +tex.hbadness +tex.holdinginserts +tex.hyphenpenalty +tex.interlinepenalty +tex.language +tex.lastlinefit +tex.lefthyphenmin +tex.linepenalty +tex.localbrokenpenalty +tex.localinterlinepenalty +tex.looseness +tex.mag +tex.maxdeadcycles +tex.month +tex.newlinechar +tex.outputpenalty +tex.pausing +tex.pdfadjustinterwordglue +tex.pdfadjustspacing +tex.pdfappendkern +tex.pdfcompresslevel +tex.pdfdecimaldigits +tex.pdfgamma +tex.pdfgentounicode +tex.pdfimageapplygamma +tex.pdfimagegamma +tex.pdfimagehicolor +tex.pdfimageresolution +tex.pdfinclusionerrorlevel +tex.pdfminorversion +tex.pdfobjcompresslevel +tex.pdfoutput +tex.pdfpagebox +tex.pdfpkresolution +tex.pdfprependkern +tex.pdfprotrudechars +tex.pdftracingfonts +tex.pdfuniqueresname +tex.postdisplaypenalty +tex.predisplaydirection +tex.predisplaypenalty +tex.pretolerance +tex.relpenalty +tex.righthyphenmin +tex.savinghyphcodes +tex.savingvdiscards +tex.showboxbreadth +tex.showboxdepth +tex.time +tex.tolerance +tex.tracingassigns +tex.tracingcommands +tex.tracinggroups +tex.tracingifs +tex.tracinglostchars +tex.tracingmacros +tex.tracingnesting +tex.tracingonline +tex.tracingoutput +tex.tracingpages +tex.tracingparagraphs +tex.tracingrestores +tex.tracingscantokens +tex.tracingstats +tex.uchyph +tex.vbadness +tex.widowpenalty +tex.year +\stoptyping +\stopcolumns + +Read|-|only: + +\startcolumns[n=3] +\starttyping +tex.deadcycles +tex.insertpenalties +tex.parshape +tex.prevgraf +tex.spacefactor +\stoptyping +\stopcolumns + +\subsection{Dimension parameters} + +The dimension parameters accept \LUA\ numbers (signifying scaled points) +or strings (with included dimension). The result is always a string. + +Read-write: + +\startcolumns[n=3] +\starttyping +tex.boxmaxdepth +tex.delimitershortfall +tex.displayindent +tex.displaywidth +tex.emergencystretch +tex.hangindent +tex.hfuzz +tex.hoffset +tex.hsize +tex.lineskiplimit +tex.mathsurround +tex.maxdepth +tex.nulldelimiterspace +tex.overfullrule +tex.pagebottomoffset +tex.pageheight +tex.pagerightoffset +tex.pagewidth +tex.parindent +tex.pdfdestmargin +tex.pdfeachlinedepth +tex.pdfeachlineheight +tex.pdffirstlineheight +tex.pdfhorigin +tex.pdflastlinedepth +tex.pdflinkmargin +tex.pdfpageheight +tex.pdfpagewidth +tex.pdfpxdimen +tex.pdfthreadmargin +tex.pdfvorigin +tex.predisplaysize +tex.scriptspace +tex.splitmaxdepth +tex.vfuzz +tex.voffset +tex.vsize +\stoptyping +\stopcolumns + +Read|-|only: + +\startcolumns[n=3] +\starttyping +tex.pagedepth +tex.pagefilllstretch +tex.pagefillstretch +tex.pagefilstretch +tex.pagegoal +tex.pageshrink +tex.pagestretch +tex.pagetotal +tex.prevdepth +\stoptyping +\stopcolumns + +\subsection{Direction parameters} + +The direction parameters are read|-|only and return a \LUA\ string. + +\startcolumns[n=3] +\starttyping +tex.bodydir +tex.mathdir +tex.pagedir +tex.pardir +tex.textdir +\stoptyping +\stopcolumns + +\subsection{Glue parameters} + +All glue parameters are read|-|only and return a \LUA\ string. + +\startcolumns[n=3] +\starttyping +tex.abovedisplayshortskip +tex.abovedisplayskip +tex.baselineskip +tex.belowdisplayshortskip +tex.belowdisplayskip +tex.leftskip +tex.lineskip +tex.parfillskip +tex.parskip +tex.rightskip +tex.spaceskip +tex.splittopskip +tex.tabskip +tex.topskip +tex.xspaceskip +\stoptyping +\stopcolumns + +\subsection{Muglue parameters} + +All muglue parameters are read|-|only and return a \LUA\ string. + +\startcolumns[n=3] +\starttyping +tex.medmuskip +tex.thickmuskip +tex.thinmuskip +\stoptyping +\stopcolumns + +\subsection{Tokenlist parameters} + +All tokenlist parameters are read|-|only and return a \LUA\ string. + +\startcolumns[n=3] +\starttyping +tex.errhelp +tex.everycr +tex.everydisplay +tex.everyeof +tex.everyhbox +tex.everyjob +tex.everymath +tex.everypar +tex.everyvbox +tex.output +tex.pdfpageattr +tex.pdfpageresources +tex.pdfpagesattr +tex.pdfpkmode +\stoptyping +\stopcolumns + +\subsection{Convert commands} + +The supported commands at this moment are: + +\startcolumns[n=3] +\starttyping +tex.AlephVersion +tex.Alephrevision +tex.OmegaVersion +tex.Omegarevision +tex.eTeXVersion +tex.eTeXrevision +tex.formatname +tex.jobname +tex.luatexrevision +tex.luatexdatestamp +tex.pdfnormaldeviate +tex.pdftexbanner +tex.pdftexrevision +\stoptyping +\stopcolumns + +All \quote{convert} commands are read|-|only and return a \LUA\ string. + +If you are wondering why this list looks haphazard; these are all the +cases of the \quote{convert} internal command that do not require an +argument. + +\subsection{Attribute, count, dimension and token registers} + +\TEX's attributes (\tex{attribute}), counters (\tex{count}), +dimensions (\tex{dimen}) and token (\tex{toks}) registers can be +accessed and written to using four virtual sub|-|tables of the +\luatex{tex} table: + +\startcolumns[n=3] +\starttyping +tex.attribute +tex.count +tex.dimen +tex.toks +\stoptyping +\stopcolumns + +It is possible to use the names of relevant \tex{attributedef}, \tex{countdef}, +\tex{dimendef}, or \tex{toksdef} control sequences as indices +to these tables: + +\starttyping +tex.count.scratchcounter = 0 +enormous = tex.dimen['maxdimen'] +\stoptyping + +In this case, \LUATEX\ looks up the value for you on the fly. You have +to use a valid \tex{countdef} (or \tex{attributedef}, or +\tex{dimendef}, or \tex{toksdef}), anything else will generate an error +(the intent is to eventually also allow \type{} and even +macros that expand into a number). + +The attribute and count registers accept and return \LUA\ numbers. + +The dimension registers accept \LUA\ numbers (in scaled points) or +strings (with an included absolute dimension; \type {em} and \type {ex} and \type {px} +are forbidden). The result is always a number in scaled points. + +The token registers accept and return \LUA\ strings. \LUA\ strings are +converted to and from token lists using \tex{the}\tex{toks} style +expansion: all category codes are either space (10) or other (12). + +As an alternative to array addressing, there are also accessor +functions defined: + +\startfunctioncall +tex.setdimen(number n, string s) +tex.setdimen(string s, string s) +tex.setdimen(number n, number n) +tex.setdimen(string s, number n) +number n = tex.getdimen(number n) +number n = tex.getdimen(string s) + +tex.setcount(number n, number n) +tex.setcount(string s, number n) +number n = tex.getcount(number n) +number n = tex.getcount(string s) + +tex.settoks (number n, string s) +tex.settoks (string s, string s) +string s = tex.gettoks (number n) +string s = tex.gettoks (string s) +\stopfunctioncall + +\subsection{Box registers} + +The current dimensions of \tex{box} registers can be read and +altered using three other virtual sub|-|tables : + +\starttyping +tex.wd +tex.ht +tex.dp +\stoptyping + +These are indexed strictly by number. + +The box size registers accept \LUA\ numbers (in scaled points) +or strings (with included dimension). The result is always a number +in scaled points. + +As an alternative to array addressing, there are also accessor +functions defined: + +\startfunctioncall +tex.setboxwd(number n, number n) +number n = tex.getboxwd(number n) + +tex.setboxht(number n, number n) +number n = tex.getboxht(number n) + +tex.setboxdp(number n, number n) +number n = tex.getboxdp(number n) +\stopfunctioncall + +It is also possible to set and query actual boxes, using the node +interface as defined in the \luatex{node} library: + +\starttyping +tex.box +\stoptyping + +for array access, or + +\starttyping +tex.setbox(number n, s) + n = tex.getbox(number n) +\stoptyping + +for function|-|based access. + +Be warned that an assignment like + +\starttyping +tex.box[0] = tex.box[2] +\stoptyping + +does not copy the node list, it just duplicates a node pointer. If +\tex{box2} will be cleared by \TEX\ commands later on, the contents +of \tex{box0} becomes invalid as well. To prevent this from +happening, always use \luatex{node.copy_list()} unless you are +assigning to a temporary variable: + +\starttyping +tex.box[0] = node.copy_list(tex.box[2]) +\stoptyping + +\subsection{Print functions} + +The \luatex{tex} table also contains the three print functions that +are the major interface from \LUA\ scripting to \TEX. + +The arguments to these three functions are all stored in an in|-|memory +virtual file that is fed to the \TEX\ scanner as the result of the +expansion of \tex{directlua}. + +The total amount of returnable text from a \tex{directlua} command +is only limited by available system \RAM. However, each separate +printed string has to fit completely in \TEX's input buffer. + +\subsubsection{\luatex{tex.print}} + +\startfunctioncall +tex.print(string s, ...) +tex.print(number n, string s, ...) +\stopfunctioncall + +Each string argument is treated by \TEX\ as a separate input line. + +The optional parameter can be used to print the strings using the +catcode regime defined by \tex{catcodetable}~\type{n}. If \type{n} is not +a valid catcode table, then it is ignored, and the currently +active catcode regime is used instead. + +The very last string of the very last \luatex{tex.print()} command in a +\tex{directlua} will not have the \tex{endlinechar} appended, all +others do. + +\subsubsection{\luatex{tex.sprint}} + +\startfunctioncall +tex.sprint(string s, ...) +tex.sprint(number n, string s, ...) +\stopfunctioncall + +Each string argument is treated by \TEX\ as a special kind of input line +that makes it suitable for use as a partial line input mechanism: + +\startitemize[packed] +\item \TEX\ does not switch to the \quote{new line} state, so + that leading spaces are not ignored. +\item No \tex{endlinechar} is inserted. +\item Trailing spaces are not removed. + +(Note that this does not prevent \TEX\ itself from eating spaces as +result of interpreting the line. For example, in +\starttyping +before\directlua0{tex.sprint("\\relax")tex.sprint(" inbetween")}after +\stoptyping +the space before \type{inbetween} will be gobbled as a result of +the \quote{normal} scanning of \type{\relax}). +\stopitemize + + +\subsubsection{\luatex{tex.write}} + +\startfunctioncall +tex.write(string s, ...) +\stopfunctioncall + +Each string argument is treated by \TEX\ as a special kind of input +line that makes is suitable for use as a quick way to dump +information: + +\startitemize +\item All catcodes on that line are either \quote{space} (for '~') or + \quote{character} (for all others). +\item There is no \tex{endlinechar} appended. +\stopitemize + +\subsection{Helper functions} + +\subsubsection{\luatex{tex.round}} + +\startfunctioncall +number n = tex.round(number o) +\stopfunctioncall + +Rounds lua number \type{o}, and returns a number that is in the range +of a valid \TEX\ register value. If the number starts out of range, it +generates a \quote{Number to big} error as well. + +\subsubsection{\luatex{tex.scale}} + +\startfunctioncall +number n = tex.scale(number o, number delta) +table n = tex.scale(table o, number delta) +\stopfunctioncall + +Multiplies the lua numbers \type{o} and \type{delta}, and returns a +rounded number that is in the range of a valid \TEX\ register value. +In the table version, it creates a copy of the table with all numeric +top||level values scaled in that manner. If the multiplied number(s) are +of range, it generates \quote{Number to big} error(s) as well. + +\section{The \luatex{token} library} + +The \luatex{token} table contains interface functions to \TEX's +handling of tokens. These functions are most useful when combined with +the \luatex{token_filter} callback, but they could be used standalone as +well. + +A token is represented in \LUA\ as a small table. For the moment, this +table consists of three numeric entries: + +\starttabulate[|l|l|p|] +\NC \bf no.\NC \bf meaning \NC \bf description \NC \NR +\NC 1 \NC command code \NC this is a value between~$0$ and~$130$ (approximately)\NC \NR +\NC 2 \NC command modifier \NC this is a value between~$0$ and~$2^{21}$ \NC \NR +\NC 3 \NC control sequence id \NC for commands that are not the result of control + sequences, like letters and characters, it is zero, + otherwise, it is a number pointing into the \quote + {equivalence table} \NC \NR +\stoptabulate + +\subsection{\luatex{token.get_next}} + +\startfunctioncall +token t = token.get_next() +\stopfunctioncall + +This fetches the next input token from the current input source, +without expansion. + +\subsection{\luatex{token.is_expandable}} + +\startfunctioncall +boolean b = token.is_expandable(token t) +\stopfunctioncall + +This tests if the token \type{t} could be expanded. + +\subsection{\luatex{token.expand}} + +\startfunctioncall +token.expand() +\stopfunctioncall + +If a token is expandable, this will expand one level of it, so that +the first token of the expansion will now be the next token to be read +by \luatex{tex.get_next()}. + +\subsection{\luatex{token.is_activechar}} + +\startfunctioncall +boolean b = token.is_activechar(token t) +\stopfunctioncall + +This is a special test that is sometimes handy. Discovering whether +some token is the result of an active character turned out to be very +hard otherwise. + +\subsection{\luatex{token.create}} + +\startfunctioncall +token t = token.create(string csname) +token t = token.create(number charcode) +token t = token.create(number charcode, number catcode) +\stopfunctioncall + +This is the token factory. If you feed it a string, then it is the +name of a control sequence (without leading backslash), and it will be +looked up in the equivalence table. + +If you feed it number, then this is assumed to be an input character, +and an optional second number gives its category code. This means it +is possible to overrule a character's category code, with a few +exceptions: the category codes~0 (escape), 9~(ignored), 13~(active), +14~(comment), and 15 (invalid) cannot occur inside a token. The values~0, 9, 14 +and~15 are therefore illegal as input to \luatex{token.create()}, and +active characters will be resolved immediately. + +Note: unknown string sequences and never defined active characters +will result in a token representing an \quote{undefined control sequence} +with a near|-|random name. It is {\it not\/} possible to define brand +new control sequences using \luatex{token.create}! + +\subsection{\luatex{token.command_name}} + +\startfunctioncall +string commandname = token.command_name(token t) +\stopfunctioncall + +This returns the name associated with the \quote{command} value of the token +in \LUATEX. There is not always a direct connection between these names and +primitives. For instance, all \tex{ifxxx} tests are grouped under +\type {if_fest}, and the \quote{command modifier} defines which test is to be run. + +\subsection{\luatex{token.command_id}} + +\startfunctioncall +number i = token.command_idtring commandname) +\stopfunctioncall + +This returns a number that is the inverse operation of the previous +command, to be used as the first item in a token table. + +\subsection{\luatex{token.csname_name}} + +\startfunctioncall +string csname = token.csname_name(token t) +\stopfunctioncall + +This returns the name associated with the \quote{equivalence table} value of +the token in \LUATEX. It returns the string value of the command used +to create the current token, or an empty string if there is no +associated control sequence. + +\subsection{\luatex{token.csname_id}} + +\startfunctioncall +number i = token.csname_id(string csname) +\stopfunctioncall + +This returns a number that is the inverse operation of the previous +command, to be used as the third item in a token table. + +\section{The \luatex{node} library} + +The \luatex{node} library contains functions that facilitate dealing +with (lists of) nodes and their values. They allow you to create, alter, +copy, delete, and insert \LUATEX\ node objects, the core +objects within the typesetter. + +\LUATEX\ nodes are represented in \LUA\ as userdata with +the metadata type \luatex{luatex.node}. The various parts within +a node can be accessed using named fields. + +Each node has at least the three fields \type{next}, \type{id}, and +\type{subtype}: + +\startitemize[intro] + +\item The \type{next} field returns the userdata +object for the next node in a linked list of nodes, or +nil, if there is no next node. + +\item The \type{id} indicates \TEX's \quote{node type}. The field \type{id} +has a numeric value for efficiency reasons, but some of the library +functions also accept a string value instead of \type{id}. + +\item The \type{subtype} is another number. It often gives further information +about a node of a particular \type{id}, but it is most important when dealing +with \quote{whatsits}, because they are differentiated solely based on their +\type{subtype}. +\stopitemize + +The other available fields depend on the \type{id} (and for \quote{whatsits}, the +\type{subtype}) of the node. Further details on the various fields and their +meanings are given in~\in{chapter}[nodes]. + +\TEX's math nodes are not yet supported: there is not yet an interface +to the internals of the math list and it is not possible to create +them from \LUA. Support for \type{unset} (alignment) nodes is partial: +they can be queried and modified from \LUA\ code, but not created. + +Nodes can be compared to each other, but: you are actually comparing +indices into the node memory. This means that equality tests can only +be trusted under very limited conditions. It will not work correctly +in any situation where one of the two nodes has been freed and|/|or +reallocated: in that case, there will be false positives. + +At the moment, memory management of nodes should still be done +explicitly by the user. Nodes are not \quote{seen} by the \LUA\ +garbage collector, so you have to call the node free-ing functions +yourself when you are no longer in need of a node (list). Nodes form +linked lists without reference counting, so you have to be careful +that when control returns back to \LUATEX\ itself, you have not +deleted nodes that are still referenced from a \type{next} pointer +elsewhere, and that you did not create nodes that are referenced more +than once. + +\subsection{Node handling functions} + +\subsubsection{\luatex{node.types}} + +\startfunctioncall +table t = node.types() +\stopfunctioncall + +This function returns an array that maps node id numbers to node type +strings, providing an overview of the possible top|-|level \type{id} +types. + +\subsubsection{\luatex{node.whatsits}} + +\startfunctioncall +table t = node.whatsits() +\stopfunctioncall + +\TEX's \quote{whatsits} all have the same \type{id}. The various subtypes +are defined by their \type{subtype}. The function is much like +\luatex{node.types}, except that it provides an array of \type{subtype} +mappings. + +\subsubsection{\luatex{node.id}} + +\startfunctioncall +number id = node.id(string type) +\stopfunctioncall + +This converts a single type name to its internal numeric +representation. + +\subsubsection{\luatex{node.subtype}} + +\startfunctioncall +number subtype = node.subtype(string type) +\stopfunctioncall + +This converts a single whatsit name to its internal numeric +representation (\type{subtype}). + +\subsubsection{\luatex{node.type}} + +\startfunctioncall +string type = node.type(number id) +\stopfunctioncall + +This converts a internal numeric representation to an external string +representation. + +\subsubsection{\luatex{node.fields}} + +\startfunctioncall +table t = node.fields(number id) +table t = node.fields(number id, number subtype) +\stopfunctioncall + +This function returns an array of valid field names for a particular +type of node. If you want to get the valid fields for a +\quote{whatsit}, you have to supply the second argument also. In other +cases, any given second argument will be silently ignored. + +This function accepts string \type{id} and \type{subtype} values as +well. + +\subsubsection{\luatex{node.has_field}} + +\startfunctioncall +boolean t = node.has_field( n, string field) +\stopfunctioncall + +This function returns a boolean that is only true if \type{n} is +actually a node, and it has the field. + + +\subsubsection{\luatex{node.new}} + +\startfunctioncall + n = node.new(number id) + n = node.new(number id, number subtype) +\stopfunctioncall + +Creates a new node. All of the new node's fields are initialized to +either zero or nil except for \type{id} and \type{subtype} (if +supplied). If you want to create a new whatsit, then the second +argument is required, otherwise it need not be present. As with all +node functions, this function creates a node on the \TEX\ level. + +This function accepts string \type{id} and \type{subtype} values as +well. + +\subsubsection{\luatex{node.free}} + +\startfunctioncall +node.free( n) +\stopfunctioncall + +Removes the node \type{n} from \TEX's memory. Be careful: no checks +are done on whether this node is still pointed to from a register or some +\type{next} field: it is up to you to make sure that the internal data +structures remain correct. + +\subsubsection{\luatex{node.flush_list}} + +\startfunctioncall +node.flush_list( n) +\stopfunctioncall + +Removes the node list \type{n} and the complete node list following +\type{n} from \TEX's memory. Be careful: no checks are done on whether +any of these nodes is still pointed to from a register or some +\type{next} field: it is up to you to make sure that the internal data +structures remain correct. + +\subsubsection{\luatex{node.copy}} + +\startfunctioncall + m = node.copy( n) +\stopfunctioncall + +Creates a deep copy of node \type{n}, including all nested lists as in +the case of a hlist or vlist node. Only the \type{next} field is not +copied. + +\subsubsection{\luatex{node.copy_list}} + +\startfunctioncall + m = node.copy_list( n) +\stopfunctioncall + +Creates a deep copy of the node list that starts at \type{n}. + +\subsubsection{\luatex{node.hpack}} + +\startfunctioncall + h = node.hpack( n) + h = node.hpack( n, number w, string info) +\stopfunctioncall + +This function creates a new hlist by packaging the list that begins at node +\type{n} into a horizontal box. With only a single argument, this box +is created using the natural width of its components. In the three +argument form, \type{info} must be either \type{additional} or +\type{exactly}, and \type{w} is the additional (\type{\hbox spread}) +or exact (\type{\hbox to}) width to be used. + +Caveat: at this moment, there can be unexpected side|-|effects to this +function, like updating some of the \type{\marks} and \type{\inserts}. + +\subsubsection{\luatex{node.slide}} + +\startfunctioncall + m = node.slide( n) +\stopfunctioncall + +Returns the last node of the node list that starts at \type{n}. As a +side|-|effect, it also creates a reverse chain of \type{prev} pointers +between nodes. + +\subsubsection{\luatex{node.length}} + +\startfunctioncall +number i = node.length( n) +number i = node.length( n, m) +\stopfunctioncall + +Returns the number of nodes contained in the node list that starts at +\type{n}. If \type{m} is also supplied it stops at \type{m} instead of +at the end of the list. The node \type{m} is not counted. + +\subsubsection{\luatex{node.count}} + +\startfunctioncall +number i = node.count(number id, n) +number i = node.count(number id, n, m) +\stopfunctioncall + +Returns the number of nodes contained in the node list that starts at +\type{n} that have an matching \type{id} field. +If \type{m} is also supplied, counting stops at \type{m} instead of at +the end of the list. The node \type{m} is not counted. + +This function also accept string \type{id}'s. + +\subsubsection{\luatex{node.traverse}} + +\startfunctioncall + t = node.traverse( n) +\stopfunctioncall + +This is an iterator that loops over the node list that starts at \type{n}. + +\subsubsection{\luatex{node.traverse_id}} + +\startfunctioncall + t = node.traverse_id(number id, n) +\stopfunctioncall + +This is an iterator that loops over all the nodes in the list that +starts at \type{n} that have a matching \type{id} field. + +\subsubsection{\luatex{node.remove}} + +\startfunctioncall + head, current = node.remove( head, current) +\stopfunctioncall + +This function removes the node \type{current} from the list following +\type{head}. It is your responsibility to make sure it is really part +of that list. The return values are the new \type{head} and +\type{current} nodes. The returned \type{current} is the +node in the calling argument, and is only passed back as a convenience +(its \type{next} field will be cleared). The returned \type{head} is +more important, because if the function is called with \type{current} +equal to \type{head}, it will be changed. + + +\subsubsection{\luatex{node.insert_before}} + +\startfunctioncall + head, new = node.insert_before( head, current, new) +\stopfunctioncall + +This function inserts the node \type{new} before \type{current} into +the list following \type{head}. It is your responsibility to make sure +that \type{current} is really part of that list. The return values are +the (potentially mutated) \type{head} and the \type{new}, set up to +be part of the list (with correct \type{next} field). If \type{head} +is initially \type{nil}, it will become \type{new}. + + +\subsubsection{\luatex{node.insert_after}} + +\startfunctioncall + head, new = node.insert_after( head, current, new) +\stopfunctioncall + +This function inserts the node \type{new} after \type{current} into +the list following \type{head}. It is your responsibility to make sure +that \type{current} is really part of that list. The return values are +the \type{head} and the \type{new}, set up to be part of the list +(with correct \type{next} field). If \type{head} is initially +\type{nil}, it will become \type{new}. + +\subsubsection{\luatex{node.first_character}} + +\startfunctioncall + n = node.first_character( n) + n = node.first_character( n, m) +\stopfunctioncall + +Returns the first node that is a glyph node with a subtype indicating +it is a character, or \type{nil}. + +\subsubsection{\luatex{node.ligaturing}} + +\startfunctioncall + h, t, success = node.ligaturing( n) + h, t, success = node.ligaturing( n, m) +\stopfunctioncall + +Apply \TEX-style ligaturing to the specified nodelist. The tail node +\type{m} is optional. The two returned nodes \type{h} and \type{t} are +the new head and tail (both \type{n} and \type{m} can change into +a new ligature). + +\subsubsection{\luatex{node.kerning}} + +\startfunctioncall + h, t, success = node.kerning( n) + h, t, success = node.kerning( n, m) +\stopfunctioncall + +Apply \TEX-style kerning to the specified nodelist. The tail node +\type{m} is optional. The two returned nodes \type{h} and \type{t} are +the head and tail (either one of these can be an inserted kern node, +because special kernings with word boundaries are possible). + + + + +\subsubsection{\luatex{node.unprotect_glyphs}} + +\startfunctioncall +node.unprotect_glyphs( n) +\stopfunctioncall + +Substracts 256 from all glyph node subtypes. This and the next +function are helpers to convert from \type{characters} to +\type{glyphs} during node processing. + + +\subsubsection{\luatex{node.protect_glyphs}} + +\startfunctioncall +node.protect_glyphs( n) +\stopfunctioncall + +Adds 256 to all glyph node subtypes in the node list starting at +\type{n}, except that if the value is 1, it adds only 255. The special +handling of 1 means that \type{characters} will become \type{glyphs} +after substraction of 256. + +\subsubsection{\luatex{node.last_node}} + +\startfunctioncall + n = node.last_node() +\stopfunctioncall + +This function pops the last node from \TEX's `current list'. +It returns that node, or \type{nil} if the current list is empty. + +\subsubsection{\luatex{node.write}} + +\startfunctioncall +node.write( n) +\stopfunctioncall + +This is an experimental function that will append a node list to +\TEX's `current list'. There is no error checking yet! + + + +\subsection{Attribute handling} + +Attributes appear as linked list of userdata objects in the +\type{attr} field of individual nodes. They can be handled +individually, but it is much safer and more efficient to use the +dedicated functions associated with them. + +\subsubsection{\luatex{node.has_attribute}} + +\startfunctioncall +number v = node.has_attribute( n, number id) +number v = node.has_attribute( n, number id, number val) +\stopfunctioncall + +Tests if a node has the attribute with number \type{id} set. If +\type{val} is also supplied, also tests if the value matches \type{val}. +It returns the value, or, if no match is found, nil. + +\subsubsection{\luatex{node.set_attribute}} + +\startfunctioncall +node.set_attribute( n, number id, number val) +\stopfunctioncall + +Sets the attribute with number \type{id} to the value +\type{val}. Duplicate assignments are ignored. + +\subsubsection{\luatex{node.unset_attribute}} + +\startfunctioncall +number v = node.unset_attribute( n, number id, number val) +number v = node.unset_attribute( n, number id) +\stopfunctioncall + +Unsets the attribute with number \type{id}. If \type{val} is also supplied, +it will only perform this operation if the value matches \type{val}. +Missing attributes or attribute|-|value pairs are ignored. + +If the attribute was actually deleted, returns its old +value. Otherwise, returns nil. + +\section{The \luatex{texio} library} + +This library takes care of the low|-|level I/O interface. + +\subsection{Printing functions} + +\subsubsection{\luatex{texio.write}} + +\startfunctioncall +texio.write(string target, string s, ...) +texio.write(string s, ...) +\stopfunctioncall + +Without the \type{target} argument, writes all given strings to the same +location(s) \TEX\ writes messages to at this moment. If +\tex{batchmode} is in effect, it writes only to the log, +otherwise it writes to the log and the terminal. + +The optional \type{target} can be one of three possibilities: +\type{term}, \type{log} or \type {term and log}. + +Note: If several strings are given, and if the first of these strings +is or might be one of the targets above, the \type{target} must be +specified explicitely to prevent \LUA\ from interpreting the first +string as the target. + +\subsubsection{\luatex{texio.write_nl}} + +\startfunctioncall +texio.write_nl(string target, string s, ...) +texio.write_nl(string s, ...) +\stopfunctioncall + +Like \luatex{texio.write}, but make sure that the given strings will +appear at the beginning of a new line. You can pass a single empty string +if you only want to move to the next line. + +\section{The \luatex{pdf} library} + +This table contains the current \type{h} and \type{v} values that +define the location on the output page. The values can be queried +and set using scaled points as units. + +\starttyping +pdf.v +pdf.h +\stoptyping + +The associated function calls are + +\startfunctioncall +pdf.setv(number n) +number n = pdf.getv() +pdf.seth(number n) +number n = pdf.geth() +\stopfunctioncall + + +It also holds a print function to write stuff to the \PDF\ document +that can be used from within a \tex{latelua} argument. This function +is not to be used inside \tex{directlua} unless you know {\it +exactly} what you are doing. + +\subsubsubject{\luatex{pdf.print}} + +\startfunctioncall +pdf.print(string s) +pdf.print(string type, string s) +\stopfunctioncall + +The optional parameter can be used to mimic the behavior of +\tex{pdfliteral}: the \type{type} is \type{direct} or \type{page}. + +\section{The \luatex{img} library} + +The \type{img} library can be used as an alternative to +\tex{pdfximage} and \tex{pdfrefximage}, and the associated `satellite' +commands like \tex{pdfximagebbox}. + +\subsubsubject{\luatex{img.new}} + +\startfunctioncall + var = img.new() + var = img.new(image_spec) +\stopfunctioncall + +This function creates a userdata object of type `image'. The +\type{image_spec} argument is optional. If it is given, it must be +a table, and that table must contain a \type{filename} key. A number of +other keys can also be useful, these are explained below. + +You can either say +\starttyping +a=img.new() +\stoptyping +followed by +\starttyping +a.filename="foo.png" +\stoptyping +or you can put the file name (and some or all of the other keys) +into a table directly, like so: +\starttyping +a=img.new{filename='foo.pdf',page=1} +\stoptyping + +The generated \type{} userdata object allows access to a set of +user-specified values as well as a set of values that are normally +filled in and updated automatically by \LUATEX\ itself. Some of those +are derived from the actual image file, others are updated to reflect +the PDF output status of the object. + +There is one required user-specified field: the file name +(\type{filename}). It can optionally be augmented by the requested +image dimensions (\type{width}, \type{depth}, \type{height}), +user-specified image attributes (\type{attr}), the requested PDF page +identifier (\type{page}), the requested boundingbox (\type{pagebox}) +for PDF inclusion, the requested color space object (\type{colorspace}). + +The function \type{img.new} does not access the actual image file, it +just creates the \type{} userdata object and initializes some +memory structures. The \type{} object and its internal +structures are automatically garbage collected. + +Once the image is scanned, all the values in the +\type{} become frozen, and you cannot change them any more. + +\subsubsubject{\luatex{img.keys}} + +\startfunctioncall + keys = img.keys() +\stopfunctioncall + +This function returns a list of all the possible \type{image_spec} +keys, both user-supplied and automatic ones. + +% hahe: i need to add r/w ro column... +\starttabulate[|l|l|p|] +\NC Field name \NC Type \NC Description \NC \NR +\NC depth \NC number \NC Image depth for \LUATEX\ (in scaled points)\NC \NR +\NC height \NC number \NC Image height for \LUATEX\ (in scaled points)\NC \NR +\NC width \NC number \NC Image width for \LUATEX\ (in scaled points)\NC \NR +\NC transform \NC number \NC Image transform, integer number 0..7\NC \NR +\NC attr \NC string \NC Image attributes for \LUATEX \NC \NR +\NC filename \NC string \NC Image file name \NC \NR +\NC page \NC ?? \NC Identifier for the requested image + page (type is number or string, + default is the number 1)\NC \NR +\NC pagebox \NC string \NC Requested bounding box. + One of "none", "media", "crop", "bleed", "trim", "art" \NC \NR +\NC filepath \NC string \NC Full (expanded) file name of the image \NC \NR +\NC colordepth \NC number \NC Number of bits used by the color space \NC \NR +\NC colorspace \NC number \NC Color space object number \NC \NR +\NC imagetype \NC string \NC One of "pdf", "png", "jpg", "jbig2", or \type{nil} \NC \NR +\NC objnum \NC number \NC PDF image object number \NC \NR +\NC index \NC number \NC PDF image name suffix \NC \NR +\NC pages \NC number \NC Total number of available pages \NC \NR +\NC xsize \NC number \NC Natural image width \NC \NR +\NC ysize \NC number \NC Natural image height \NC \NR +\NC xres \NC number \NC Horizontal natural image resolution (dpi) \NC \NR +\NC yres \NC number \NC Vertical natural image resolution (dpi) \NC \NR +\stoptabulate + +A running (undefined) dimension in \type{width}, \type{height}, or \type{depth} is +represented as \type{nil} in Lua, so if you want to load an image at +its `natural' size, you do not have to specify any of those three fields. + +The \type{transform} allows to mirror and rotate the image in steps of 90~deg. +The default value~0 gives an unmirrored, unrotated image. +Values 1..3 give counterclockwise rotation by 90, 180, or 270~deg., +whereas with values 4..7 the image is first mirrored +and then rotated counterclockwise by 90, 180, or 270~deg. +The \type{transform} operation gives the same visual result +as if you would externally preprocess the image by a graphics tool +and then use it by \LUATEX. + +\subsubsubject{\luatex{img.scan}} + +\startfunctioncall + var = img.scan( var) + var = img.scan(image_spec) +\stopfunctioncall + +When you say \type{img.scan(a)} for a new image, the file is scanned, +and variables such as \type{xsize}, \type{ysize}, image \type{type}, number of +\type{pages}, and the resolution are extracted. Each of the \type{width}, +\type{height}, \type{depth} fields are set up according to the image dimensions, +if they were not given an explicit value already. +An image file will never be scanned more than once for a given image variable. +With all subsequent \type{img.scan(a)} calls only the dimensions are again +set up (if they have been changed by the user in the meantime). + +For ease of use, you can do right-away a +\starttyping +a=img.scan{filename="foo.png"} +\stoptyping +without a prior \type{img.new}. + +Nothing is written yet at this point, so you can do \type{a=img.scan}, +retrieve the available info like image width and height, and then +throw away \type{a} again by saying \type{a=nil}. In that case no +image object will be reserved in the PDF, and the used memory will be +cleaned up automatically. + +\subsubsubject{\luatex{img.copy}} + +\startfunctioncall + var = img.copy( var) + var = img.copy(image_spec) +\stopfunctioncall + +If you say \type{a = b}, then both variables point to the same +\type{} object. if you want to write out an image with +different sizes, you can do a \type{b=img.copy(a)}. + +Afterwards, \type{a} and \type{b} still reference the same actual +image dictionary, but the dimensions for \type{b} can now be changed +from their initial values that were just copies from \type{a}. + +% Hartmut, I don't know if this makes sense. An example of what +% can, and what cannot be changed would be helpful. +% -- will think about it... + +\subsubsubject{\luatex{img.write}} + +\startfunctioncall + var = img.write( var) + var = img.write(image_spec) +\stopfunctioncall + +By \type{img.write(a)} a \PDF\ object number is allocated, +and a whatsit node of subtype \type{pdf_refximage} is generated +and put into the output list. +By this the image \type{a} is placed into the \PDF\ page stream, +and the image file is written out into an image stream object +after the shipping of the current page is finished. + +Again you can do a terse call like + +\starttyping +img.write{filename="foo.png"} +\stoptyping + +The \type{} variable is returned in case you want it for later +processing. + +\subsubsubject{\luatex{img.immediatewrite}} + +\startfunctioncall + var = img.immediatewrite( var) + var = img.immediatewrite(image_spec) +\stopfunctioncall + +By \type{img.immediatewrite(a)} a \PDF\ object number is allocated, +and the image file for image \type{a} is written out immediately +into the \PDF\ file as an image stream object +(like with \type{\immediate\pdfximage}). +The object number of the image stream dictionary is then available +by the \type{objnum} key. +No \type{pdf_refximage} whatsit node is generated. +You will need a \luatex{img.write(a)} or \luatex{img.node(a)} call +to let the image appear on the page, +or reference it by another trick; +else you will have a dangling image object in the \PDF\ file. + +Also here you can do a terse call like + +\starttyping +a = img.immediatewrite{filename="foo.png"} +\stoptyping + +The \type{} variable is returned; you will most likely need it. + +\subsubsubject{\luatex{img.node}} + +\startfunctioncall + n = img.node( var) + n = img.node(image_spec) +\stopfunctioncall + +This function allocates a \PDF\ object number +and returns a whatsit node of subtype \type{pdf_refximage}, +filled with the image parameters \type{width}, \type{height}, +\type{depth}, and \type{objnum}. +Also here you can do a terse call like: + +\starttyping +n = img.node{filename="foo.png"} +\stoptyping + +This example outputs an image: + +\starttyping +node.write(img.node{filename="foo.png"}) +\stoptyping + +\subsubsubject{\luatex{img.types}} + +\startfunctioncall +
types = img.types() +\stopfunctioncall + +This function returns a list with the supported image file type names, +currently these are `pdf', `png', `jpg', and `jbig2'. + +\subsubsubject{\luatex{img.boxes}} + +\startfunctioncall +
boxes = img.boxes() +\stopfunctioncall + +This function returns a list with the supported \PDF\ page box names, +currently these are `media', `crop', `bleed', `trim', and `art' +(all in lowercase letters). + + +\section{The \luatex{mplib} library} + +The \MP\ library interface registers itself in the table \type{mplib}. It +is based on the MPlib beta version 0.40 (based on \MP\ 1.003). + +\subsection{\luatex{mplib.new}} + +To create a new metapost instance, call + +\startfunctioncall + mp = mplib.new({...}) +\stopfunctioncall + +This creates the \type{mp} instance object. The argument hash can have a number of +different fields, as follows: + +\starttabulate[|l|l|p|p|] +\NC name \NC type \NC description \NC default \NC\NR +\NC error_line \NC number \NC line width for terminal and log \NC 79 \NC\NR +\NC half_error_line \NC number \NC ``half'' of line width \NC 50 \NC\NR +\NC max_print_line \NC number \NC line length in ps output\NC 100\NC\NR +\NC main_memory \NC number \NC total memory size \NC 5000\NC\NR +\NC hash_size \NC number \NC hash size\NC 9500 \NC\NR +\NC hash_prime \NC number \NC prime number for hashing\NC 7919\NC\NR +\NC param_size \NC number \NC max. simultaneous macro parameters\NC 150\NC\NR +\NC max_in_open \NC number \NC max. input file nestings \NC 10\NC\NR +\NC random_seed \NC number \NC the initial random seed \NC variable\NC\NR +\NC interaction \NC string \NC the interaction mode, one of +"batch", "nonstop", "scroll", "errorstop"\NC "errorstop"\NC\NR +\NC ini_version \NC boolean \NC the --ini switch\NC false \NC\NR +\NC troff_mode \NC boolean \NC the -T switch \NC false \NC\NR +\NC print_found_names \NC boolean \NC whether long file names + should be printed to the log and terminal streams\NC false \NC\NR +\NC mem_name \NC string \NC --mem\NC plain.mem\NC\NR +\NC job_name \NC string \NC --jobname\NC mpout \NC\NR +\NC find_file \NC function \NC a function to find files \NC only local files\NC\NR +\stoptabulate + +The \type{find_file} function should be of this form: + +\starttyping + string found = finder (string name, string mode, string type) +\stoptyping + +\starttabulate[|l|l|p|] +\NC name \NC the requested file \NC \NR +\NC mode \NC the file mode: 'r' or 'w' \NC \NR +\NC type \NC the kind of file, one of: + "mp", "mem", "tfm", "map", "pfb", "enc" \NC \NR +\stoptabulate + +Return either the full pathname of the found file, or \type{nil} if +the file cannot be found. + +\subsection{\luatex{mp:statistics}} + +\startfunctioncall + table stats = mp:statistics() +\stopfunctioncall + +Returns the vital statistics for an MPlib instance. There are four +fields, giving the maximum number of used items in each of the four +statically allocated object classes: + +\starttabulate[|l|l|p|] +\NC main_memory \NC number \NC memory size \NC\NR +\NC hash_size \NC number \NC hash size\NC\NR +\NC param_size \NC number \NC simultaneous macro parameters\NC\NR +\NC max_in_open \NC number \NC input file nesting levels\NC\NR +\stoptabulate + +\subsection{\luatex{mp:execute}} + +You can ask the MP interpreter to run a bit of code by calling + +\startfunctioncall + local rettable = mp:execute('metapost language chunk') +\stopfunctioncall + +for various bits of Metapost language input. + +Be sure to check the \type{rettable.status} (see below) because when a +fatal Metapost error occurs the MPlib instance will become unusable +thereafter. + +Generally speaking, it is best to keep your chunks small, but beware +that all chunks have to obey proper syntax, like each of them is a +small file. For instance, you cannot split a single statement over +multiple chunks. + +\subsection{\luatex{mp:finish}} + +\startfunctioncall + local rettable = mp:finish() +\stopfunctioncall + +If for some reason you want to stop using an MPlib instance +while processing is not yet actually done, you can call +\type{mp:finish}. Memory and files can be closed by the +Lua garbage collector, but an explicit \type{mp:finish} is +the only way to capture the final part of the output streams. + +\subsection{Result table} + +The return value of \type{mp:execute} and \type{mp:finish} is a table +with a few possible keys (only `status' is always guaranteed to be present). + +\starttabulate[|l|l|p|] +\NC log \NC string \NC output to the 'log' stream \NC \NR +\NC term \NC string \NC output to the 'term' stream \NC \NR +\NC error \NC string \NC output to the 'error' stream (only used for +`Out Of Memory')\NC \NR +\NC status \NC number \NC the return value. 0 = good, 1 = warning, 2 = errors, + 3 = fatal error \NC \NR +\NC fig \NC table \NC An array of generated figures (if any)\NC \NR +\stoptabulate + +When \type{status} equals 3, you should stop using this MPlib instance +immediately, it is no longer capable of processing input. + +If it is present, each of the entries in the \type{fig} array is a +userdata representing a figure object, and each of those has a number of +object methods you can call: + +\starttabulate[|l|l|p|] +\NC boundingbox \NC function \NC returns the bounding box, as an array of 4 values\NC \NR +\NC postscript \NC function \NC return a string that is the ps output of the \type{fig} \NC \NR +\NC objects \NC function \NC returns the actual array of graphic objects in this \type{fig} \NC \NR +\NC copy_objects \NC function \NC returns a deep copy of the array of graphic objects in this \type{fig} \NC \NR +\NC filename \NC function \NC the filename this \type{fig}'s PostScript output + would have written to in standalone mode\NC \NR +\stoptabulate + +{\bf NOTE:} you can call \type{fig:objects()} only once for any one \type{fig} object! + +When the boundingbox represents a `negated rectangle' (i.w. the first set +of coordinates is larger than the second set), the picture is empty. + +Graphical objects come in various types that each have a different list of +accessible values. The types are: 'fill', 'outline', 'text', +'start_clip', 'stop_clip', 'start_bounds', 'stop_bounds', 'special'. + +There is 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 tables given below. + +All graphical objects have a field \type{type} that gives the object +type as a string value, that not explicit mentioned in the tables. In +the following, \type{number}s are PostScript points represented as +a floating point number, unless stated otherwise. Field values that +are of \type{table} are explained in the next section. + +\subsubsection{fill} + +\starttabulate[|l|l|p|] +\NC path \NC table \NC the list of knots \NC \NR +\NC htap \NC table \NC the list of knots for the reversed trajectory \NC \NR +\NC pen \NC table \NC knots of the pen \NC \NR +\NC color \NC table \NC the object's color \NC \NR +\NC linejoin \NC number \NC line join style (bare number)\NC \NR +\NC miterlimit \NC number \NC miterlimit\NC \NR +\NC prescript \NC string \NC the prescript text \NC \NR +\NC postscript \NC string \NC the postscript text \NC \NR +\stoptabulate + +The entries \type{htap} and \type{pen} are optional. + +\subsubsection{outline} + +\starttabulate[|l|l|p|] +\NC path \NC table \NC the list of knots \NC \NR +\NC pen \NC table \NC knots of the pen \NC \NR +\NC color \NC table \NC the object's color \NC \NR +\NC linejoin \NC number \NC line join style (bare number)\NC \NR +\NC miterlimit \NC number \NC miterlimit \NC \NR +\NC linecap \NC number \NC line cap style (bare number)\NC \NR +\NC dash \NC table \NC representation of a dash list\NC \NR +\NC prescript \NC string \NC the prescript text \NC \NR +\NC postscript \NC string \NC the postscript text \NC \NR +\stoptabulate + +The entry \type{dash} is optional. + +\subsubsection{text} + +\starttabulate[|l|l|p|] +\NC text \NC string \NC the text \NC \NR +\NC font \NC string \NC font tfm name \NC \NR +\NC dsize \NC number \NC font size\NC \NR +\NC color \NC table \NC the object's color \NC \NR +\NC width \NC number \NC \NC \NR +\NC height \NC number \NC \NC \NR +\NC depth \NC number \NC \NC \NR +\NC transform \NC table \NC a text transformation \NC \NR +\NC prescript \NC string \NC the prescript text \NC \NR +\NC postscript \NC string \NC the postscript text \NC \NR +\stoptabulate + +\subsubsection{special} + +\starttabulate[|l|l|p|] +\NC prescript \NC string \NC special text \NC \NR +\stoptabulate + + +\subsubsection{start_bounds, start_clip} + +\starttabulate[|l|l|p|] +\NC path \NC table \NC the list of knots \NC \NR +\stoptabulate + +\subsubsection{stop_bounds, stop_clip} + +No fields available. + +\subsection{Subsidiary table formats} + +\subsubsection{Paths and pens} + +Paths and pens (that are really just a special type of paths as far as +MPlib is concerned) are represented by an array where each entry +is a table that represents a knot. + +\starttabulate[|l|l|p|] +\NC left_type \NC string \NC when present: 'endpoint', but ususally absent \NC \NR +\NC right_type \NC string \NC like \type{left_type}\NC \NR +\NC x_coord \NC number \NC X coordinate of this knot\NC \NR +\NC y_coord \NC number \NC Y coordinate of this knot\NC \NR +\NC left_x \NC number \NC X coordinate of the precontrol point of this knot\NC \NR +\NC left_y \NC number \NC Y coordinate of the precontrol point of this knot\NC \NR +\NC right_x \NC number \NC X coordinate of the postcontrol point of this knot\NC \NR +\NC right_y \NC number \NC Y coordinate of the postcontrol point of this knot\NC \NR +\stoptabulate + +There is one special case: pens that are (possibly transformed) +ellipses have an extra string-valued key \type{type} with value +\type{elliptical} besides the array part containing the knot list. + +\subsubsection{Colors} + +A color is an integer array with 0, 1, 3 or 4 values: + +\starttabulate[|l|l|p|] +\NC 0 \NC Marking only \NC No values. \NC\NR +\NC 1 \NC Greyscale \NC 0ne value in the range 0 .. 1, `black' is 0 \NC\NR +\NC 3 \NC RGB \NC 3 values in the range 0 .. 1, `black' is 0,0,0 \NC\NR +\NC 4 \NC CMYK \NC 4 values in the range 0 .. 1, `black' is 0,0,0,1 \NC\NR +\stoptabulate + +If the color model of the internal object was \type{unitialized}, then +it was initialized to the values representing `black' in the colorspace +\type{defaultcolormodel} that was in effect at the time of the \type{shipout}. + +\subsubsection{Transforms} + +Each transform is a six-item array. + +\starttabulate[|l|l|p|] +\NC 1 \NC number \NC represents x \NC\NR +\NC 2 \NC number \NC represents y \NC\NR +\NC 3 \NC number \NC represents xx \NC\NR +\NC 4 \NC number \NC represents yx \NC\NR +\NC 5 \NC number \NC represents xy \NC\NR +\NC 6 \NC number \NC represents yy \NC\NR +\stoptabulate + +Note that the translation (index 1 and 2) comes first. This differs +from the ordering in PostScript, where the translation comes last. + +\subsubsection{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 +`on' and `off', values, and \type{offset} is the phase of the pattern. + +\starttabulate[|l|l|p|] +\NC dashes \NC hash \NC an array of on-off numbers \NC\NR +\NC offset \NC number \NC the starting offset value \NC\NR +\stoptabulate + + +\section{The \luatex{callback} library} + +This library has functions that register, find and list callbacks. + +The \luatex{callback} library is only available in \LUA\ state zero (0). + +\startfunctioncall +id, error = callback.register(string callback_name,function callback_func) +id, error = callback.register(string callback_name,nil) +\stopfunctioncall + +where the \syntax{callback_name} is a predefined callback name, see +below. The function returns the internal \type{id} of the callback +or \type{nil}, if the callback could not be registered. In the latter +case, \type{error} contains an error message, otherwise it is +\type{nil}. + +\LUATEX\ internalizes the callback function in such a way that +it does not matter if you redefine a function accidentally. +% hahe: what happens then? + +Callback assignments are always global. You can use the special value +\type {nil} instead of a function for clearing the callback. + +Currently, callbacks are not dumped into the format file. + +\startfunctioncall +table info = callback.list() +\stopfunctioncall + +The keys in the table are the known callback names, the value is a +boolean where \type{true} means that the callback is currently set +(active). + +\startfunctioncall +function f = callback.find(callback_name) +\stopfunctioncall + +If the callback is not set, \luatex{callback.find} returns \type{nil}. + +\subsection{File discovery callbacks} + +\subsubsection{\luatex{find_read_file} and \luatex{find_write_file}} + +Your callback function should have the following conventions: + +\startfunctioncall +string actual_name = function (number id_number, string asked_name) +\stopfunctioncall + +Arguments: + +\startitemize + +\sym{id_number} + +This number is zero for the log or \tex {input} files. For \TEX's \tex{read} or +\tex{write} the number is incremented by one, so \tex{read0} becomes~1. + +\sym{asked_name} + +This is the user|-|supplied filename, as found by \tex{input}, \tex{openin} +or \tex{openout}. + +\stopitemize + +Return value: + +\startitemize + +\sym{actual_name} + +This is the filename used. For the very first file that is read in by +\TEX, you have to make sure you return an \type{actual_name} that has +an extension and that is suitable for use as \type{jobname}. If you +don't, you will have to manually fix the name of the log file and +output file after \LUATEX\ is finished, and an eventual format +filename will become mangled. That is because these file names depend +on the jobname. + +You have to return \type{nil} if the file cannot be found. + +\stopitemize + +\subsubsection{\luatex{find_font_file}} + +Your callback function should have the following conventions: + +\startfunctioncall +string actual_name = function (string asked_name) +\stopfunctioncall + +The \type{asked_name} is an \OTF\ or \TFM\ font metrics file. + +Return \type{nil} if the file cannot be found. + +\subsubsection{\luatex{find_output_file}} + +Your callback function should have the following conventions: + +\startfunctioncall +string actual_name = function (string asked_name) +\stopfunctioncall + +The \type{asked_name} is the \PDF\ or \DVI\ file for writing. + +\subsubsection{\luatex{find_format_file}} + +Your callback function should have the following conventions: + +\startfunctioncall +string actual_name = function (string asked_name) +\stopfunctioncall + +The \type{asked_name} is a format file for reading (the format file +for writing is always opened in the current directory). + +\subsubsection{\luatex{find_vf_file}} + +Like \luatex{find_font_file}, but for virtual fonts. This applies to +both \ALEPH's \OVF\ files and traditional Knuthian \VF\ files. + +\subsubsection{\luatex{find_ocp_file}} + +Like \luatex{find_font_file}, but for ocp files. + +\subsubsection{\luatex{find_map_file}} + +Like \luatex{find_font_file}, but for map files. + +\subsubsection{\luatex{find_enc_file}} + +Like \luatex{find_font_file}, but for enc files. + +\subsubsection{\luatex{find_sfd_file}} + +Like \luatex{find_font_file}, but for subfont definition files. + +\subsubsection{\luatex{find_pk_file}} + +Like \luatex{find_font_file}, but for pk bitmap files. The argument +\type{name} is a bit special in this case. Its form is + +\starttyping +dpi/.pk +\stoptyping + +So you may be asked for \type{600dpi/manfnt.720pk}. It is up to you +to find a \quote{reasonable} bitmap file to go with that specification. + +\subsubsection{\luatex{find_data_file}} + +Like \luatex{find_font_file}, but for embedded files (\tex{pdfobj file '...'}). + +\subsubsection{\luatex{find_opentype_file}} + +Like \luatex{find_font_file}, but for \OPENTYPE\ font files. + +\subsubsection{\luatex{find_truetype_file} and \luatex{find_type1_file}} + +Your callback function should have the following conventions: + +\startfunctioncall +string actual_name = function (string asked_name) +\stopfunctioncall + +The \type{asked_name} is a font file. This callback is called while +\LUATEX\ is building its internal list of needed font files, so the +actual timing may surprise you. Your return value is later fed back +into the matching \luatex{read_file} callback. + +Strangely enough, \luatex{find_type1_file} is also used for \OPENTYPE\ +(\OTF) fonts. + +\subsubsection{\luatex{find_image_file}} + +Your callback function should have the following conventions: + +\startfunctioncall +string actual_name = function (string asked_name) +\stopfunctioncall + +The \type{asked_name} is an image file. Your return value is used to +open a file from the harddisk, so make sure you return something that +is considered the name of a valid file by your operating system. + +\subsection[iocallback]{File reading callbacks} + +\subsubsection{\luatex{open_read_file}} + +Your callback function should have the following conventions: + +\startfunctioncall +table env = function (string file_name) +\stopfunctioncall + +Argument: + +\startitemize + +\sym{file_name} + +The filename returned by a previous \luatex{find_read_file} or the return +value of \luatex{kpse.find_file()} if there was no such callback defined. + +\stopitemize + +Return value: + +\startitemize + +\sym{env} + +This is a table containing at least one required and one optional +callback function for this file. The required field is +\luatex{reader} and the associated function will be called once +for each new line to be read, the optional one is \luatex{close} +that will be called once when \LUATEX\ is done with the file. + +\LUATEX\ never looks at the rest of the table, so you can use it to +store your private per|-|file data. Both the callback functions will +receive the table as their only argument. + +\stopitemize + +\subsubsubsection{\luatex{reader}} + +\LUATEX\ will run this function whenever it needs a new input line +from the file. + +\startfunctioncall +function(table env) + return string line +end +\stopfunctioncall + +Your function should return either a string or \type{nil}. The value \type{nil} +signals that the end of file has occurred, and will make \TEX\ call +the optional \luatex{close} function next. + +\subsubsubsection{\luatex{close}} + +\LUATEX\ will run this optional function when it decides to close the file. + +\startfunctioncall +function(table env) + return +end +\stopfunctioncall + +Your function should not return any value. + +\subsubsection{General file readers} + +There is a set of callbacks for the loading of binary data +files. These all use the same interface: + +\startfunctioncall +function(string name) + return boolean success, string data, number data_size +end +\stopfunctioncall + +The \type{name} will normally be a full path name as it is returned by +either one of the file discovery callbacks or the internal version of +\luatex{kpse.find_file()}. + +\startitemize + +\sym{success} + +Return false when a fatal error occured (e.\,g.\ when the file cannot be +found, after all). + +\sym{data} + +The bytes comprising the file. + +\sym{data_size} + +The length of the \type{data}, in bytes. + +\stopitemize + +Return an empty string and zero if the file was found but there was a +reading problem. + +The list of functions is: +\starttabulate[|l|p|] +\NC \luatex{read_font_file} \NC This function is called when \TEX\ needs to read a \type{ofm} or + \type{tfm} file. \NC\NR +\NC \luatex{read_vf_file} \NC for virtual fonts.\NC\NR +\NC \luatex{read_ocp_file} \NC for ocp files.\NC\NR +\NC \luatex{read_map_file} \NC for map files.\NC\NR +\NC \luatex{read_enc_file} \NC for encoding files.\NC\NR +\NC \luatex{read_sfd_file} \NC for subfont definition files.\NC\NR +\NC \luatex{read_pk_file} \NC for pk bitmap files. \NC\NR +\NC \luatex{read_data_file} \NC for embedded files (\tex{pdfobj file '...'}).\NC\NR +\NC \luatex{read_truetype_file} \NC for \TRUETYPE\ font files. \NC\NR +\NC \luatex{read_type1_file} \NC for \TYPEONE\ font files.\NC\NR +\NC \luatex{read_opentype_file} \NC for \OPENTYPE\ font files. \NC\NR +\stoptabulate + +\subsection{Data processing callbacks} + +\subsubsection{\luatex{process_input_buffer}} + + +This callback allows you to change the contents of the line input +buffer just before \LUATEX\ actually starts looking at it. + +\startfunctioncall +function(string buffer) + return string adjusted_buffer +end +\stopfunctioncall + +If you return \type{nil}, \LUATEX\ will pretend like your callback +never happened. You can gain a small amount of processing time from +that. + + +\subsubsection{\luatex{token_filter}} + +This callback allows you to replace the way \LUATEX\ fetches +lexical tokens. + +\startfunctioncall +function() + return table token +end +\stopfunctioncall + +The calling convention for this callback is a bit more complicated than +for most other callbacks. The function should either return a \LUA\ +table representing a valid to|-|be|-|processed token or tokenlist, or +something else like nil or an empty table. + +If your \LUA\ function does not return a table representing a valid +token, it will be immediately called again, until it eventually does +return a useful token or tokenlist (or until you reset the callback +value to nil). See the description of \luatex{token} for some +handy functions to be used in conjunction with this callback. + +If your function returns a single usable token, then that token will +be processed by \LUATEX\ immediately. If the function returns a token +list (a table consisting of a list of consecutive token tables), then +that list will be pushed to the input stack at a completely new token +list level, with its token type set to \quote{inserted}. In either case, +the returned token(s) will not be fed back into the callback function. + +\subsection{Node list processing callbacks} + +The description of nodes and node lists is in~\in{chapter}[nodes]. + +\subsubsection{\luatex{buildpage_filter}} + +This callback is called whenever \LUATEX\ is ready to move stuff to +the main vertical list. You can use this callback to do specialized +manipulation of the page building stage like imposition or column +balancing. + +\startfunctioncall +function( head, string extrainfo) + return true | false | newhead +end +\stopfunctioncall + +As for all the callbacks that deal with nodes, the return value can be +one of three things: + +\startitemize[packed] +\item \type{boolean true} signals succesful processing +\item \type{node} signals that the \quote{head} node should be +replaced by this node +\item \type{boolean false} signals that the \quote{head} node list should be +ignored and flushed from memory +\stopitemize + +The string \type{extrainfo} gives some additional information about +what \TEX's state is with respect to the \quote{current page}. The possible +values are: + +\starttabulate[|lT|p|] +\NC \bf value \NC \bf explanation \NC\NR +\NC \tt alignment \NC a (partial) alignment is being added \NC\NR +\NC \tt box \NC a typeset box is being added \NC\NR +\NC \tt begin_of_par \NC the beginning of a new paragraph \NC\NR +\NC \tt vmode_par \NC \tex{par} was found in vertical mode \NC\NR +\NC \tt hmode_par \NC \tex{par} was found in horizontal mode \NC\NR +\NC \tt insert \NC an insert is added \NC\NR +\NC \tt penalty \NC a penalty (in vertical mode) \NC\NR +\NC \tt before_display \NC immediately before a display starts \NC\NR +\NC \tt after_display \NC a display is finished \NC\NR +\stoptabulate + +\subsubsection{\luatex{pre_linebreak_filter}} + +This callback is called just before \LUATEX\ starts converting a list +of nodes into a stack of \tex{hbox}es. The removal of a possible final skip +and the subsequent insertion of \tex{parfillskip} has not happened +yet at that moment. + +\startfunctioncall +function( head, string groupcode) + return true | false | newhead +end +\stopfunctioncall + +The string called \type {groupcode} identifies the nodelist's context +within \TEX's processing. The range of possibilities is given in the +table below, but not all of those can actually appear in +\luatex {pre_linebreak_filter}, some are for the +\luatex {hpack_filter} and \luatex {vpack_filter} callbacks that +will be explained in the next two paragraphs. + +\starttabulate[|lT|p|] +\NC \bf value \NC \bf explanation \NC\NR +\NC \tt hbox \NC \tex{hbox} in horizontal mode \NC\NR +\NC \tt adjusted_hbox\NC \tex{hbox} in vertical mode \NC\NR +\NC \tt vbox \NC \tex{vbox} \NC\NR +\NC \tt vtop \NC \tex{vtop} \NC\NR +\NC \tt align \NC \tex{halign} or \tex{valign} \NC\NR +\NC \tt disc \NC discretionaries \NC\NR +\NC \tt insert \NC packaging an insert \NC\NR +\NC \tt vcenter \NC \tex{vcenter} \NC\NR +\NC \tt local_box \NC \tex{localleftbox} or \tex{localrightbox} \NC\NR +\NC \tt split_off \NC top of a \tex{vsplit} \NC\NR +\NC \tt split_keep \NC remainder of a \tex{vsplit} \NC\NR +\NC \tt align_set \NC alignment cell \NC\NR +\NC \tt fin_row \NC alignment row \NC\NR +\stoptabulate + +\subsubsection{\luatex{post_linebreak_filter}} + +This callback is called just after \LUATEX\ has converted a list +of nodes into a stack of \tex{hbox}es. + +\startfunctioncall +function( head, string groupcode) + return true | false | newhead +end +\stopfunctioncall + +\subsubsection{\luatex{hpack_filter}} + +This callback is called when \TEX\ is ready to start boxing some +horizontal mode material. Math items are ignored at the moment. + +\startfunctioncall +function( head, string groupcode, number size, string packtype) + return true | false | newhead +end +\stopfunctioncall + +The \type{packtype} is either \type{additional} or \type{exactly}. If +\type{additional}, then the \type{size} is a \tex{hbox spread ...} +argument. If \type{exactly}, then the \type{size} is a \tex{hbox to ...}. +In both cases, the number is in scaled points. + +\subsubsection{\luatex{vpack_filter}} + +This callback is called when \TEX\ is ready to start boxing some +vertical mode material. Math displays are ignored at the moment. + +This function is very similar to the \luatex{hpack_filter}. Besides +the fact that it is called at different moments, there is an extra +variable that matches \TEX's \tex{maxdepth} setting. + +\startfunctioncall +function( head, string groupcode, number size, string packtype, number maxdepth) + return true | false | newhead +end +\stopfunctioncall + +\subsubsection{\luatex{pre_output_filter}} + +This callback is called when \TEX\ is ready to start boxing the +box 255 for \tex{output}. + +\startfunctioncall +function( head, string groupcode, number size, string packtype, number maxdepth) + return true | false | newhead +end +\stopfunctioncall + +\subsubsection{\luatex{hyphenate}} + +\startfunctioncall +function( head, tail) +end +\stopfunctioncall + +No return values. This callback has to insert discretionary nodes in +the node list it receives. + + +\subsubsection{\luatex{ligaturing}} + +\startfunctioncall +function( head, tail) +end +\stopfunctioncall + +No return values. This callback has to apply ligaturing to the node +list it receives. + +You don't have to worry about return values because the \type{head} +node that is passed on to the callback is guaranteed not to be a +glyph_node (if need be, a temporary node will be prepended), and +therefore it cannot be affected by the mutations that take place. +After the callback, the internal value of the `tail of the list' +will be recalculated. + +The \type{next} of \type{head} is guaranteed to be non-nil. + +The \type{next} of \type{tail} is guaranteed be nil, and therefore the +second callback argument can often be ignored. It is provided for +orthogonality, and because it can sometimes be handy when special +processing has to take place. + +\subsubsection{\luatex{kerning}} + +\startfunctioncall +function( head, tail) end +\stopfunctioncall + +No return values. This callback has to apply kerning between the nodes +in the node list it receives. See \type{ligaturing} for calling +conventions. + + +\subsection{Information reporting callbacks} + +\subsubsection{\luatex{start_run}} + +\startfunctioncall +function() +\stopfunctioncall + +Replaces the code that prints \LUATEX's banner. + +\subsubsection{\luatex{stop_run}} + +\startfunctioncall +function() +\stopfunctioncall + +Replaces the code that prints \LUATEX's statistics and \quote{output written +to} messages. + +\subsubsection{\luatex{start_page_number}} + +\startfunctioncall +function() +\stopfunctioncall + +Replaces the code that prints the \type{[} and the page number at the +begin of \tex{shipout}. This callback will also override the +printing of box information that normally takes place when +\tex{tracingoutput} is positive. + +\subsubsection{\luatex{stop_page_number}} + +\startfunctioncall +function() +\stopfunctioncall + +Replaces the code that prints the \type{]} at the end of \tex{shipout}. + +\subsubsection{\luatex{show_error_hook}} + +\startfunctioncall +function() + return +end +\stopfunctioncall + +This callback is run from inside the \TEX\ error function, and the idea +is to allow you to do some extra reporting on top of what \TEX\ already +does (none of the normal actions are removed). You may find some of +the values in the \luatex{status} table useful. + +\startitemize + +\sym{message} + +is the formal error message \TEX\ has given to the user. +(the line after the '!'). + +\sym{indicator} + +is either a filename (when it is a string) or a location indicator (a +number) that can mean lots of different things like a token list id +or a \tex{read} number. + +\sym{lineno} + +is the current line number. +\stopitemize + +This is an investigative item for 'testing the water' only. +The final goal is the total replacement of \TEX's error handling +routines, but that needs lots of adjustments in the web source because +\TEX\ deals with errors in a somewhat haphazard fashion. This is why the +exact definition of \type{indicator} is not given here. + +\subsection{Font-related callbacks} + +\subsubsection{\luatex{define_font}} + +\startfunctioncall +function(string name, number size, number id) return table font end +\stopfunctioncall + +The string \type{name} is the filename part of the font +specification, as given by the user. + +The number \type{size} is a bit special: + +\startitemize[packed] +\item if it is positive, it specifies an \quote{at size} in scaled points. +\item if it is negative, its absolute value represents a \quote{scaled} +setting relative to the designsize of the font. +\stopitemize + +The internal structure of the \type{font} table that is to be +returned is explained in \in{chapter}[fonts]. That table is saved +internally, so you can put extra fields in the table for your +later \LUA\ code to use. + +\section{The \luatex{lua} library} + +This library contains two read|-|only items: + +\subsection{Variables} + +\starttyping +number n = lua.id +\stoptyping + +This returns the id number of the instance. + +\starttyping +string s = lua.version +\stoptyping + +This returns a \LUATEX\ version identifier string. The value is +currently \directlua0{tex.print('lua.version')}, but it is soon to be +replaced by something more elaborate. + +\subsection{\LUA\ bytecode registers} + +\LUA\ registers can be used to communicate \LUA\ functions across \LUA\ +states. The accepted values for assignments are functions and +nil. Likewise, the retrieved value is either a function or \type{nil}. + +\starttyping +lua.bytecode[n] = function () .. end +lua.bytecode[n]() +\stoptyping + +The contents of the \luatex{lua.bytecode} array is stored inside the format +file as actual \LUA\ bytecode, so it can also be used to preload \LUA\ code. + +Note: The function must not contain any upvalues. Currently, functions +containing upvalues can be stored (and their upvalues are set to +\type{nil}), but this is an artefact of the current \LUA\ +implementation and thus subject to change. + +The associated function calls are + +\startfunctioncall +function f = lua.getbytecode(number n) +lua.setbytecode(number n, function f) +\stopfunctioncall + +Note: Since a \LUA\ file loaded using \luatex{loadfile(filename)} is +essentially an anonymous function, a complete file can be stored in a +bytecode register like this: + +\startfunctioncall +lua.bytecode[n] = loadfile(filename) +\stopfunctioncall + +Now all definitions (functions, variables) contained in the file can be +created by executing this bytecode register: + +\startfunctioncall +lua.bytecode[n]() +\stopfunctioncall + +\section{The \luatex{kpse} library} + +This library provides an interface to the \KPATHSEA\ file search method. + +Before the search library can be used at all, its database has to be +initialized. When \LUATEX\ is used to typeset documents, this happens +automatically (that is, unless explicitly prohibited by the user's +startup script. See~\in{section}[init] for more details). In \TEXLUA\ +mode, the initialization has to be done explicitly via the +\luatex{kpse.set_program_name} function. + +\subsection{\luatex{kpse.set_program_name}} + +Sets the \KPATHSEA\ executable (and optionally program) name. + +\startfunctioncall +kpse.set_program_name(string name) +kpse.set_program_name(string name, string progname) +\stopfunctioncall + +The second argument controls the use of the \quote{dotted} values in the +\type{texmf.cnf} configuration file, and defaults to the first argument. + + +\subsection{\luatex{kpse.find_file}} + +The most often used function in the library is find_file: + +\startfunctioncall +string f = kpse.find_file(string filename) +string f = kpse.find_file(string filename, string ftype) +string f = kpse.find_file(string filename, boolean mustexist) +string f = kpse.find_file(string filename, string ftype, boolean mustexist) +string f = kpse.find_file(string filename, string ftype, number dpi) +\stopfunctioncall + +Arguments: +\startitemize[intro] + +\sym{filename} + +the name of the file you want to find, with or without extension. + +\sym{ftype} + +maps to the \type {-format} argument of \KPSEWHICH. The supported + \type{ftype} values are the same as the ones supported by the +standalone \type{kpsewhich} program: + +\startsimplecolumns +\starttyping +'gf' +'pk' +'bitmap font' +'tfm' +'afm' +'base' +'bib' +'bst' +'cnf' +'ls-R' +'fmt' +'map' +'mem' +'mf' +'mfpool' +'mft' +'mp' +'mppool' +'MetaPost support' +'ocp' +'ofm' +'opl' +'otp' +'ovf' +'ovp' +'graphic/figure' +'tex' +'TeX system documentation' +'texpool' +'TeX system sources' +'PostScript header' +'Troff fonts' +'type1 fonts' +'vf' +'dvips config' +'ist' +'truetype fonts' +'type42 fonts' +'web2c files' +'other text files' +'other binary files' +'misc fonts' +'web' +'cweb' +'enc files' +'cmap files' +'subfont definition files' +'opentype fonts' +'pdftex config' +'lig files' +'texmfscripts' +\stoptyping +\stopsimplecolumns + +The default type is \type{tex}. + +\sym{mustexist} + +is similar to \KPSEWHICH's \type{-must-exist}, and the default is \type{false}. +If you specify \type{true} (or a non|-|zero integer), then the \KPSE\ library +will search the disk as well as the \type {ls-R} databases. + +\sym{dpi} + +This is used for the size argument of the formats \type{pk}, \type{gf}, and \type{bitmap font}. +\stopitemize + +\subsection{\luatex{kpse.init_prog}} + +Extra initialization for programs that need to generate bitmap fonts. + +\startfunctioncall +kpse.init_prog(string prefix, number base_dpi, string mfmode) +kpse.init_prog(string prefix, number base_dpi, string mfmode, string fallback) +\stopfunctioncall + + +\subsection{\luatex{kpse.readable_file}} + +Test if an (absolute) file name is a readable file + +\startfunctioncall +string f = kpse.readable_file(string name) +\stopfunctioncall + +The return value is the actual absolute filename you should use, +because the disk name is not always the same as the requested name, +due to aliases and system|-|specific handling under e.\,g.\ \MSDOS. + +Returns \lua {nil} if the file does not exist or is not readable. + +\subsection{\luatex{kpse.expand_path}} + +Like kpsewhich's \type {-expand-path}: + +\startfunctioncall +string r = kpse.expand_path(string s) +\stopfunctioncall + +\subsection{\luatex{kpse.expand_var}} + +Like kpsewhich's \type{-expand-var}: + +\startfunctioncall +string r = kpse.expand_var(string s) +\stopfunctioncall + +\subsection{\luatex{kpse.expand_braces}} + +Like kpsewhich's \type{-expand-braces}: + +\startfunctioncall +string r = kpse.expand_braces(string s) +\stopfunctioncall + +\subsection{\luatex{kpse.show_path}} + +Like kpsewhich's \type{-show-path}: + +\startfunctioncall +string r = kpse.show_path(string ftype) +\stopfunctioncall + + +\subsection{\luatex{kpse.var_value}} + +Like kpsewhich's \type{-var-value}: + +\startfunctioncall +string r = kpse.var_value(string s) +\stopfunctioncall + +\section{The \luatex{status} library} + +This contains a number of run|-|time configuration items that +you may find useful in message reporting, as well as an iterator +function that gets all of the names and values as a table. + +\startfunctioncall +table info = status.list() +\stopfunctioncall + +The keys in the table are the known items, the value is the current +value. + +Almost all of the values in \type{status} are fetched through a +metatable at run|-|time whenever they are accessed, so you cannot use +\type{pairs} on \type{status}, but you {\it can\/} use \type{pairs} +on \type{info}, of course. + +If you do not need the full list, you can also ask for a single item +by using its name as an index into \type{status}. + +The current list is: + +\starttabulate[|lT|p|] +\NC \ssbf key \NC \bf explanation \NC\NR +\NC pdf_gone\NC written \PDF\ bytes \NC \NR +\NC pdf_ptr\NC not yet written \PDF\ bytes \NC \NR +\NC dvi_gone\NC written \DVI\ bytes \NC \NR +\NC dvi_ptr\NC not yet written \DVI\ bytes \NC \NR +\NC total_pages\NC number of written pages \NC \NR +\NC output_file_name\NC name of the \PDF\ or \DVI\ file \NC \NR +\NC log_name\NC name of the log file \NC \NR +\NC banner\NC terminal display banner \NC \NR +\NC var_used\NC variable (one|-|word) memory in use \NC \NR +\NC dyn_used\NC token (multi|-|word) memory in use \NC \NR +\NC str_ptr\NC number of strings \NC \NR +\NC init_str_ptr\NC number of \INITEX\ strings \NC \NR +\NC max_strings\NC maximum allowed strings \NC \NR +\NC pool_ptr\NC string pool index \NC \NR +\NC init_pool_ptr\NC \INITEX\ string pool index \NC \NR +\NC pool_size\NC current size allocated for string characters \NC \NR +\NC node_mem_usage\NC a string giving insight into currently used nodes\NC\NR +\NC var_mem_max\NC number of allocated words for nodes\NC \NR +\NC fix_mem_max\NC number of allocated words for tokens\NC \NR +\NC fix_mem_end\NC maximum number of used tokens\NC \NR +\NC cs_count\NC number of control sequences \NC \NR +\NC hash_size\NC size of hash \NC \NR +\NC hash_extra\NC extra allowed hash \NC \NR +\NC font_ptr\NC number of active fonts \NC \NR +\NC max_in_stack\NC max used input stack entries \NC \NR +\NC max_nest_stack\NC max used nesting stack entries \NC \NR +\NC max_param_stack\NC max used parameter stack entries \NC \NR +\NC max_buf_stack\NC max used buffer position \NC \NR +\NC max_save_stack\NC max used save stack entries \NC \NR +\NC stack_size\NC input stack size \NC \NR +\NC nest_size\NC nesting stack size \NC \NR +\NC param_size\NC parameter stack size \NC \NR +\NC buf_size\NC current allocated size of the line buffer \NC \NR +\NC save_size\NC save stack size \NC \NR +\NC obj_ptr\NC max \PDF\ object pointer \NC \NR +\NC obj_tab_size\NC \PDF\ object table size \NC \NR +\NC pdf_os_cntr\NC max \PDF\ object stream pointer \NC \NR +\NC pdf_os_objidx\NC \PDF\ object stream index \NC \NR +\NC pdf_dest_names_ptr\NC max \PDF\ destination pointer \NC \NR +\NC dest_names_size\NC \PDF\ destination table size \NC \NR +\NC pdf_mem_ptr\NC max \PDF\ memory used \NC \NR +\NC pdf_mem_size\NC \PDF\ memory size \NC \NR +\NC largest_used_mark\NC max referenced marks class \NC \NR +\NC filename\NC name of the current input file \NC \NR +\NC inputid\NC numeric id of the current input \NC \NR +\NC linenumber\NC location in the current input file\NC \NR +\NC lasterrorstring\NC last error string\NC \NR +\NC luabytecodes\NC number of active \LUA\ bytecode registers\NC \NR +\NC luabytecode_bytes\NC number of bytes in \LUA\ bytecode registers\NC \NR +\NC luastates\NC number of active \LUA\ interpreters\NC \NR +\NC luastate_bytes\NC number of bytes in use by \LUA\ interpreters\NC \NR +\NC output_active\NC \type{true} if the \tex{output} routine is active\NC \NR +\stoptabulate + +\section{The \luatex{texconfig} table} + +This is a table that is created empty. A startup \LUA\ script could +fill this table with a number of settings that are read out by +the executable after loading and executing the startup file. + +\starttabulate[|lT|l|l|p|] +\NC \ssbf key \NC \bf type \NC \bf default \NC \bf explanation \NC\NR +\NC string_vacancies \NC number\NC 75000\NC cf.\ web2c docs \NC \NR +\NC pool_free \NC number\NC 5000\NC cf.\ web2c docs \NC \NR +\NC max_strings \NC number\NC 15000\NC cf.\ web2c docs \NC \NR +\NC strings_free \NC number\NC 100\NC cf.\ web2c docs \NC \NR +\NC nest_size \NC number\NC 50\NC cf.\ web2c docs \NC \NR +\NC max_in_open \NC number\NC 15\NC cf.\ web2c docs \NC \NR +\NC param_size \NC number\NC 60\NC cf.\ web2c docs \NC \NR +\NC save_size \NC number\NC 4000\NC cf.\ web2c docs \NC \NR +\NC stack_size \NC number\NC 300\NC cf.\ web2c docs \NC \NR +\NC dvi_buf_size \NC number\NC 16384\NC cf.\ web2c docs \NC \NR +\NC error_line \NC number\NC 79\NC cf.\ web2c docs \NC \NR +\NC half_error_line \NC number\NC 50\NC cf.\ web2c docs \NC \NR +\NC max_print_line \NC number\NC 79\NC cf.\ web2c docs \NC \NR +\NC ocp_list_size \NC number\NC 1000\NC cf.\ web2c docs \NC \NR +\NC ocp_buf_size \NC number\NC 1000\NC cf.\ web2c docs \NC \NR +\NC ocp_stack_size \NC number\NC 1000\NC cf.\ web2c docs \NC \NR +\NC hash_extra \NC number\NC 0\NC cf.\ web2c docs \NC \NR +\NC pk_dpi \NC number\NC 72\NC cf.\ web2c docs \NC \NR +\NC kpse_init \NC boolean \NC true \NC \type{false} totally disables \KPATHSEA\ initialisation + (only ever unset this if you implement {\it all\/} file + find callbacks!)\NC \NR +\NC trace_file_names \NC boolean \NC true \NC \type{false} disables \TEX's normal file open|-|close + feedback (the assumption is that callbacks will take care of + that) \NC \NR +\NC src_special_auto \NC boolean \NC false \NC source specials sub|-|item \NC \NR +\NC src_special_everypar \NC boolean \NC false \NC source specials sub|-|item \NC \NR +\NC src_special_everyparend \NC boolean \NC false \NC source specials sub|-|item \NC \NR +\NC src_special_everycr \NC boolean \NC false \NC source specials sub|-|item \NC \NR +\NC src_special_everymath \NC boolean \NC false \NC source specials sub|-|item \NC \NR +\NC src_special_everyhbox \NC boolean \NC false \NC source specials sub|-|item \NC \NR +\NC src_special_everyvbox \NC boolean \NC false \NC source specials sub|-|item \NC \NR +\NC src_special_everydisplay \NC boolean \NC false \NC source specials sub|-|item \NC \NR +\NC file_line_error \NC boolean \NC false \NC do \type{file:line} style error messages\NC \NR +\NC halt_on_error \NC boolean \NC false \NC abort run on the first encountered error\NC \NR +\NC formatname \NC string \NC \NC if no format name was given + on the commandline, this key will be tested first + instead of simply quitting\NC \NR +\NC jobname \NC string \NC \NC if no input file name was given + on the commandline, this key will be tested first + instead of simply giving up\NC \NR +\stoptabulate + +\section{The \luatex{font} library} + +The font library provides the interface into the internals of the font +system, and also it contains helper functions to load traditional +\TEX\ font metrics formats. Other font loading functionality is +provided by the \luatex{fontforge} library that will be discussed in +the next section. + +\subsection{Loading a \TFM\ file} + +\startfunctioncall +table fnt = font.read_tfm(string name, number s) +\stopfunctioncall + +The number is a bit special: + +\startitemize +\item if it is positive, it specifies an \quote{at size} in scaled points. +\item if it is negative, its absolute value represents a \quote{scaled} +setting relative to the designsize of the font. +\stopitemize + +The internal structure of the metrics font table that is returned is +explained in \in{chapter}[fonts]. + +\subsection{Loading a \VF\ file} + +\startfunctioncall +table vf_fnt = font.read_vf(string name, number s) +\stopfunctioncall + +The meaning of the number \type{s}, and the format of the returned +table is similar to the one returned by the \luatex{read_tfm()} function. + +\subsection{The fonts array} + +The whole table of \TEX\ fonts is accessible from lua using a virtual array. + +\starttyping +font.fonts[n] = { ... } +table f = font.fonts[n] +\stoptyping + +See \in{chapter}[fonts] for the structure of the tables. Because this +is a virtual array, you cannot call \type{pairs} on it, but see below +for the \type{font.each} iterator. + +The two metatable functions implementing the virtual array are: + +\startfunctioncall +table f = font.getfont(number n) +font.setfont(number n, table f) +\stopfunctioncall + +Also note the following: assignments can only be made to fonts that +have already been defined in \TEX, but have not been accessed {\it at +all\/} since that definition. This limits the usability of the write +access to \type{font.fonts} quite a lot, a less stringent ruleset will +likely be implemented later. + +\subsection{Checking a font's status} + +You can test for the status of a font by calling this function: + +\startfunctioncall +boolean f = font.frozen(number n) +\stopfunctioncall + +The return value is one of true (unassignable), false (can be changed) +or nil (not a valid font at all). + +\subsection{Defining a font directly} + +You can define your own font into \luatex{font.fonts} by calling this function: + +\startfunctioncall +number i = font.define(table f) +\stopfunctioncall + +The return value is the internal id number of the defined font (the +index into \luatex{font.fonts}). If the font creation fails, an error is +raised. The table is a font structure, as explained in +\in{chapter}[fonts]. + +\subsection{Projected next font id} + +\startfunctioncall +number i = font.nextid(); +\stopfunctioncall + +This returns the font id number that would be returned by a +\type{font.define} call if it was executed at this spot in the code +flow. This is useful for virtual fonts that need to reference +themselves. + + + +\subsection{Currently active font} + +\startfunctioncall +number i = font.current(); +font.current(number i); +\stopfunctioncall + +This gets or sets the currently used font number. + +\subsection{Maximum font id} + +\startfunctioncall +number i = font.max(); +\stopfunctioncall + +This is the largest used index in \type{font.fonts}. + +\subsection{Iterating over all fonts} + +\startfunctioncall +for i,v in font.each() do + ... +end +\stopfunctioncall + +This is an iterator over each of the defined \TEX\ fonts. The first +returned value is the index in \type{font.fonts}, the second the font +itself, as a lua table. The indices are listed incrementally, but they +do not always form an array of consecutive numbers: in some cases +there can be holes in the sequence. + +\section{The \luatex{fontforge} library} + +\subsection{Getting quick information on a font} + +\startfunctioncall +local info = fontforge.info('filename') +\stopfunctioncall + +This function returns either \type{nil}, or a \type{table}, or an +array of small tables (in the case of a TrueType collection). The +returned table(s) will contain six fairly interesting information +items from the font(s) defined by the file: + +\starttabulate[|lT|l|p|] +\NC \ssbf key \NC \bf type \NC \bf explanation \NC\NR +\NC fontname \NC string \NC the \quote{PostScript} name of the font\NC\NR +\NC fullname \NC string \NC The formal name of the font\NC\NR +\NC familyname \NC string \NC The family name this font belongs to\NC\NR +\NC weight \NC string \NC A string indicating the color value of the font\NC\NR +\NC version \NC string \NC The internal font version\NC\NR +\NC italicangle \NC float \NC The slant angle\NC\NR +\stoptabulate + +Getting information through this function is (sometimes much) more +efficient than loading the font properly, and is therefore handy when +you want to create a dictionary of available fonts based on a +directory contents. + +\subsection{Loading an \OPENTYPE\ or \TRUETYPE\ file} + +If you want to use an \OPENTYPE\ font, you have to get the metric +information from somewhere. Using the \type{fontforge} library, the +basic way to get that information is thus: + + +\starttyping +function load_font (filename) + local metrics = nil + local font = fontforge.open(filename) + if font then + metrics = fontforge.to_table(font) + fontforge.close(font) + end + return metrics +end + +myfont = load_font('/opt/tex/texmf/fonts/data/arial.ttf') +\stoptyping + +The main function call is + +\startfunctioncall +f, w = fontforge.open('filename') +\stopfunctioncall + +The first return value is a table representation of the font. The +second return value is a table containing any warnings and errors +reported by fontforge while opening the font. In normal typesetting, +you would probably ignore the second argument, but it can be useful +for debugging purposes. + +For \TRUETYPE\ collections (when filename ends in 'ttc'), you have to +use a second string argument to specify which font you want from the +collection. Use one of the \type{fullname} strings that are returned +by \type{fontforge.info} for that. + +\startfunctioncall +f, w = fontforge.open('filename','fullname') +\stopfunctioncall + + +The font file is parsed and partially interpreted by the font +loading routines from \FONTFORGE. The file format can be \OPENTYPE, +\TRUETYPE, \TRUETYPE\ Collection, \CFF, or \TYPEONE. + +There are a few advantages to this approach compared to reading the +actual font file ourselves: + +\startitemize + +\item The font is automatically re|-|encoded, so that the \type{metrics} + table for \TRUETYPE\ and \OPENTYPE\ fonts is using \UNICODE\ for + the character indices. + +\item Many features are pre|-|processed into a format that is easier to handle + than just the bare tables would be. + +\item \POSTSCRIPT|-|based \OPENTYPE\ fonts do not store the character height and + depth in the font file, so the character boundingbox has to be + calculated in some way. + +\item In the future, it may be interesting to allow \LUA\ scripts access to + the font program itself, perhaps even creating or changing the font. + +\stopitemize + +\subsection{Applying a \quote{feature file}} + +You can apply a \quote{feature file} to a loaded font: + +\startfunctioncall +fontforge.apply_featurefile(f,'filename') +\stopfunctioncall + +A \quote{feature file} is a textual representation of the features in an +OpenType font. See +\hyphenatedurl{http://www.adobe.com/devnet/opentype/afdko/topic_feature_file_syntax.html} +and +\hyphenatedurl{http://fontforge.sourceforge.net/featurefile.html} +for a more detailed description of feature files. + + +\subsection{Applying an \quote{afm file}} + +You can apply an \quote{afm file} to a loaded font: + +\startfunctioncall +fontforge.apply_afmfile(f,'filename') +\stopfunctioncall + +An \quote{afm file} is a textual representation of (some of) the metainformation +in a Type~1 font. See \hyphenatedurl{http://www.adobe.com/devnet/font/pdfs/5004.AFM_Spec.pdf} +for more information about afm files. + +Note: if you \type{fontforge.open()} a PFB file named \type{font.pfb}, +the library will automatically search for and apply \type{font.afm}, +if it exists in the same directory as \type{font.pfb}. In that case, +there is no need for an explicit call to \type{apply_afmfile()}. + + +\section{Fontforge font tables} + +The top|-|level keys in the returned table are (the explanations in +this part of the documentation are not yet finished): + +\starttabulate[|lT|l|p|] +\NC \ssbf key \NC \bf type \NC \bf explanation \NC\NR +\NC table_version \NC number \NC indicates the metrics version\NC\NR +\NC fontname \NC string \NC \POSTSCRIPT\ font name\NC\NR +\NC fullname \NC string \NC official font name\NC\NR +\NC familyname \NC string \NC family name\NC\NR +\NC weight \NC string \NC weight indicator\NC\NR +\NC copyright \NC string \NC copyright information\NC\NR +\NC filename \NC string \NC the file name\NC\NR +%\NC defbasefilename \NC string \NC \NC\NR +\NC version \NC string \NC font version\NC\NR +\NC italicangle \NC float \NC slant angle\NC\NR +\NC units_per_em \NC number \NC 1000 for \POSTSCRIPT-based fonts, usually 2048 for \TRUETYPE\NC\NR +\NC ascent \NC number \NC height of ascender in \type{units_per_em}\NC\NR +\NC descent \NC number \NC depth of descender in \type{units_per_em}\NC\NR +\NC upos \NC float \NC \NC\NR +\NC uwidth \NC float \NC \NC\NR +\NC vertical_origin \NC number \NC \NC\NR +\NC uniqueid \NC number \NC \NC\NR +\NC glyphcnt \NC number \NC number of included glyphs\NC\NR +\NC glyphs \NC array \NC \NC\NR +\NC glyphmax \NC number \NC maximum used index the glyphs array\NC\NR +%\NC changed \NC number \NC \NC\NR +\NC hasvmetrics \NC number \NC \NC\NR +\NC order2 \NC number \NC set to 1 for \TRUETYPE\ splines, 0 otherwise\NC\NR +\NC strokedfont \NC number \NC \NC\NR +\NC weight_width_slope_only \NC number \NC \NC\NR +\NC head_optimized_for_cleartype \NC number \NC \NC\NR +\NC uni_interp \NC enum \NC \type {unset}, \type {none}, \type {adobe}, + \type {greek}, \type {japanese}, \type {trad_chinese}, + \type {simp_chinese}, \type {korean}, \type {ams}\NC\NR +\NC origname \NC string \NC the file name, as supplied by the user\NC\NR +\NC map \NC table \NC \NC\NR +\NC private \NC table \NC \NC\NR +\NC xuid \NC string \NC \NC\NR +\NC pfminfo \NC table \NC \NC\NR +\NC names \NC table \NC \NC\NR +\NC cidinfo \NC table \NC \NC\NR +\NC subfonts \NC array \NC \NC\NR +\NC cidmaster \NC array \NC \NC\NR +\NC commments \NC string \NC \NC\NR +\NC anchor_classes \NC table \NC \NC\NR +\NC ttf_tables \NC table \NC \NC\NR +\NC kerns \NC table \NC \NC\NR +\NC vkerns \NC table \NC \NC\NR +\NC texdata \NC table \NC \NC\NR +\NC lookups \NC table \NC \NC\NR +\NC gpos \NC table \NC \NC\NR +\NC gsub \NC table \NC \NC\NR +\NC chosenname \NC string \NC \NC\NR +\NC macstyle \NC number \NC \NC\NR +\NC fondname \NC string \NC \NC\NR +\NC design_size \NC number \NC \NC\NR +\NC fontstyle_id \NC number \NC \NC\NR +\NC fontstyle_name \NC table \NC \NC\NR +\NC design_range_bottom \NC number \NC \NC\NR +\NC design_range_top \NC number \NC \NC\NR +\NC strokewidth \NC float \NC \NC\NR +\NC mark_classes \NC array \NC \NC\NR +\NC mark_class_names \NC array \NC \NC\NR +\NC creationtime \NC number \NC \NC\NR +\NC modificationtime \NC number \NC \NC\NR +\NC os2_version \NC number \NC \NC\NR +\stoptabulate + +\subsubsection{Glyph items} + +The \type{glyphs} is an array containing the per|-|character +information (quite a few of these are only present if nonzero). + +\starttabulate[|lT|l|p|] +\NC \ssbf key \NC \bf type \NC \bf explanation \NC\NR +\NC name \NC string \NC the glyph name\NC\NR +\NC unicode \NC number \NC unicode code point, or -1\NC\NR +\NC boundingbox \NC array \NC array of four numbers\NC\NR +\NC width \NC number \NC (only for horizontal fonts)\NC\NR +\NC vwidth \NC number \NC (only for vertical fonts)\NC\NR +\NC lsidebearing \NC number \NC (only if nonzero)\NC\NR +\NC glyph_class \NC number \NC (only if nonzero)\NC\NR +\NC kerns \NC array \NC (only for horizontal fonts, if set)\NC\NR +\NC vkerns \NC array \NC (only for vertical fonts, if set)\NC\NR +\NC dependents \NC array \NC linear array of glyph name strings (only if nonempty)\NC\NR +\NC lookups \NC table \NC (only if nonempty)\NC\NR +\NC ligatures \NC table \NC (only if nonempty)\NC\NR +\NC anchors \NC table \NC (only if set)\NC\NR +%\NC color \NC number \NC (only if set)\NC\NR +\NC tex_height \NC number \NC (only if set)\NC\NR +\NC tex_depth \NC number \NC (only if set)\NC\NR +\NC tex_sub_pos \NC number \NC (only if set)\NC\NR +\NC tex_super_pos \NC number \NC (only if set)\NC\NR +\NC comment \NC string \NC (only if set)\NC\NR +\stoptabulate + +The \type{kerns} and \type{vkerns} are linear arrays of small hashes: + +\starttabulate[|lT|l|p|] +\NC \ssbf key \NC \bf type \NC \bf explanation \NC\NR +\NC char \NC string \NC \NC\NR +\NC off \NC number \NC \NC\NR +\NC lookup \NC string \NC \NC\NR +\stoptabulate + +The \type{lookups} is a hash, based on lookup subtable names, with +the value of each key inside that a linear array of small hashes: + +% TODO: fix this description +\starttabulate[|lT|l|p|] +\NC \ssbf key \NC \bf type \NC \bf explanation \NC\NR +\NC type \NC enum \NC \type {position}, \type {pair}, \type {substitution}, \type {alternate}, + \type {multiple}, \type {ligature}, \type {lcaret}, \type {kerning}, \type {vkerning}, \type {anchors}, + \type {contextpos}, \type {contextsub}, \type {chainpos}, \type {chainsub}, + \type {reversesub}, \type {max}, \type {kernback}, \type {vkernback} \NC\NR +\NC specification \NC table \NC extra data \NC\NR +\stoptabulate + +For the first seven values of \type{type}, there can be additional +sub|-|information, stored in the sub-table \type{specification}: + +\starttabulate[|lT|l|l|p|] +\NC \bf value \NC \bf type \NC \bf explanation \NC\NR +\NC position \NC table \NC a table of the \type {offset_specs} type\NC\NR +\NC pair \NC table \NC one string: \type {paired}, and an array of one or + two \type {offset_specs} tables: \type{offsets}\NC\NR +\NC substitution \NC table \NC one string: \type {variant}\NC\NR +\NC alternate \NC table \NC one string: \type {components}\NC\NR +\NC multiple \NC table \NC one string: \type {components}\NC\NR +\NC ligature \NC table \NC two strings: \type {components}, \type {char}\NC\NR +\NC lcaret \NC array \NC linear array of numbers\NC\NR +\stoptabulate + +Tables for \type{offset_specs} contain up to four number|-|valued +fields: \type{x} (a horizontal offset), \type{y} (a vertical offset), +\type{h} (an advance width correction) and \type{v} (an advance height +correction). + +The \type{ligatures} is a linear array of small hashes: + +\starttabulate[|lT|l|p|] +\NC \ssbf key \NC \bf type \NC \bf explanation \NC\NR +\NC lig \NC table \NC uses the same substructure as a single \type{possub} item\NC\NR +\NC char \NC string \NC \NC\NR +\NC components \NC array \NC linear array of named components\NC\NR +\NC ccnt \NC number \NC \NC\NR +\stoptabulate + +The \type{anchor} table is indexed by a string signifying the +anchor type, which is one of + +\starttabulate[|lT|l|p|] +\NC \ssbf key \NC \bf type \NC \bf explanation \NC\NR +\NC mark \NC table \NC placement mark\NR +\NC basechar \NC table \NC mark for attaching combining items to a base char\NR +\NC baselig \NC table \NC mark for attaching combining items to a ligature\NR +\NC basemark \NC table \NC generic mark for attaching combining items to connect to\NR +\NC centry \NC table \NC cursive entry point\NR +\NC cexit \NC table \NC cursive exit point\NR +\stoptabulate + +The content of these is an short array of defined anchors, with the +entry keys being the anchor names. For all except \type{baselig}, the +value is a single table with this definition: + +\starttabulate[|lT|l|p|] +\NC \ssbf key \NC \bf type \NC \bf explanation \NC\NR +\NC x \NC number \NC x location\NC\NR +\NC y \NC number \NC y location\NC\NR +\NC ttf_pt_index \NC number \NC truetype point index, only if given\NC\NR +\stoptabulate + +For \type{baselig}, the value is a small array of such anchor sets +sets, one for each constituent item of the ligature. + +For clarification, an anchor table could for example look like this : +\starttyping + ['anchor']={ + ['basemark']={ + ['Anchor-7']={ ['x']=170, ['y']=1080 } + }, + ['mark']={ + ['Anchor-1'] ={ ['x']=160, ['y']=810 }, + ['Anchor-4']= { ['x']=160, ['y']=800 } + }, + ['baselig']={ + [1] = { ['Anchor-2'] ={ ['x']=160, ['y']=650 } }, + [2] = { ['Anchor-2']= { ['x']=460, ['y']=640 } } + } + }, +\stoptyping + + + +\subsubsection{map table} + +The top|-|level map is a list of encoding mappings. Each of those is a table itself. + +\starttabulate[|lT|l|p|] +\NC \ssbf key \NC \bf type \NC \bf explanation \NC\NR +\NC enccount \NC number \NC \NC\NR +\NC encmax \NC number \NC \NC\NR +\NC backmax \NC number \NC \NC\NR +\NC remap \NC table \NC \NC\NR +\NC map \NC array \NC non|-|linear array of mappings\NC\NR +\NC backmap \NC array \NC non|-|linear array of backward mappings\NC\NR +\NC enc \NC table \NC \NC\NR +\stoptabulate + +The \type{remap} table is very small: + +\starttabulate[|lT|l|p|] +\NC \ssbf key \NC \bf type \NC \bf explanation \NC\NR +\NC firstenc \NC number \NC \NC\NR +\NC lastenc \NC number \NC \NC\NR +\NC infont \NC number \NC \NC\NR +\stoptabulate + +The \type{enc} table is a bit more verbose: + +\starttabulate[|lT|l|p|] +\NC \ssbf key \NC \bf type \NC \bf explanation \NC\NR +\NC enc_name \NC string \NC \NC\NR +\NC char_cnt \NC number \NC \NC\NR +\NC char_max \NC number \NC \NC\NR +\NC unicode \NC array \NC of \UNICODE\ position numbers\NC\NR +\NC psnames \NC array \NC of \POSTSCRIPT\ glyph names\NC\NR +\NC builtin \NC number \NC \NC\NR +\NC hidden \NC number \NC \NC\NR +\NC only_1byte \NC number \NC \NC\NR +\NC has_1byte \NC number \NC \NC\NR +\NC has_2byte \NC number \NC \NC\NR +\NC is_unicodebmp \NC number \NC (only if nonzero)\NC\NR +\NC is_unicodefull \NC number \NC (only if nonzero)\NC\NR +\NC is_custom \NC number \NC (only if nonzero)\NC\NR +\NC is_original \NC number \NC (only if nonzero)\NC\NR +\NC is_compact \NC number \NC (only if nonzero)\NC\NR +\NC is_japanese \NC number \NC (only if nonzero)\NC\NR +\NC is_korean \NC number \NC (only if nonzero)\NC\NR +\NC is_tradchinese \NC number \NC (only if nonzero)\NC\NR +\NC is_simplechinese \NC number \NC (only if nonzero)\NC\NR +\NC low_page \NC number \NC \NC\NR +\NC high_page \NC number \NC \NC\NR +\NC iconv_name \NC string \NC \NC\NR +\NC iso_2022_escape \NC string \NC \NC\NR +\stoptabulate + +\subsubsection{private table} + +This is the font's private \POSTSCRIPT\ dictionary, if any. Keys and +values are both strings. + +\subsubsection{cidinfo table} + +\starttabulate[|lT|l|p|] +\NC \ssbf key \NC \bf type \NC \bf explanation \NC\NR +\NC registry \NC string \NC \NC\NR +\NC ordering \NC string \NC \NC\NR +\NC supplement \NC number \NC \NC\NR +\NC version \NC number \NC \NC\NR +\stoptabulate + +\subsubsection{pfminfo table} + +The \type{pfminfo} table contains most of the OS/2 information: + +\starttabulate[|lT|l|p|] +\NC \ssbf key \NC \bf type \NC \bf explanation \NC\NR +\NC pfmset \NC number \NC \NC\NR +\NC winascent_add \NC number \NC \NC\NR +\NC windescent_add \NC number \NC \NC\NR +\NC hheadascent_add \NC number \NC \NC\NR +\NC hheaddescent_add \NC number \NC \NC\NR +\NC typoascent_add \NC number \NC \NC\NR +\NC typodescent_add \NC number \NC \NC\NR +\NC subsuper_set \NC number \NC \NC\NR +\NC panose_set \NC number \NC \NC\NR +\NC hheadset \NC number \NC \NC\NR +\NC vheadset \NC number \NC \NC\NR +\NC pfmfamily \NC number \NC \NC\NR +\NC weight \NC number \NC \NC\NR +\NC width \NC number \NC \NC\NR +\NC avgwidth \NC number \NC \NC\NR +\NC firstchar \NC number \NC \NC\NR +\NC lastchar \NC number \NC \NC\NR +\NC fstype \NC number \NC \NC\NR +\NC linegap \NC number \NC \NC\NR +\NC vlinegap \NC number \NC \NC\NR +\NC hhead_ascent \NC number \NC \NC\NR +\NC hhead_descent \NC number \NC \NC\NR +\NC hhead_descent \NC number \NC \NC\NR +\NC os2_typoascent \NC number \NC \NC\NR +\NC os2_typodescent \NC number \NC \NC\NR +\NC os2_typolinegap \NC number \NC \NC\NR +\NC os2_winascent \NC number \NC \NC\NR +\NC os2_windescent \NC number \NC \NC\NR +\NC os2_subxsize \NC number \NC \NC\NR +\NC os2_subysize \NC number \NC \NC\NR +\NC os2_subxoff \NC number \NC \NC\NR +\NC os2_subyoff \NC number \NC \NC\NR +\NC os2_supxsize \NC number \NC \NC\NR +\NC os2_supysize \NC number \NC \NC\NR +\NC os2_supxoff \NC number \NC \NC\NR +\NC os2_supyoff \NC number \NC \NC\NR +\NC os2_strikeysize \NC number \NC \NC\NR +\NC os2_strikeypos \NC number \NC \NC\NR +\NC os2_family_class \NC number \NC \NC\NR +\NC os2_xheight \NC number \NC \NC\NR +\NC os2_capheight \NC number \NC \NC\NR +\NC os2_defaultchar \NC number \NC \NC\NR +\NC os2_breakchar \NC number \NC \NC\NR +\NC os2_vendor \NC string \NC \NC\NR +\NC panose \NC table \NC \NC\NR +\stoptabulate + +The \type{panose} subtable has exactly 10 string keys: + +\starttabulate[|lT|l|p|] +\NC \ssbf key \NC \bf type \NC \bf explanation \NC\NR +\NC familytype \NC string \NC Values as in the \OPENTYPE\ font specification: + \type {Any}, \type {No Fit}, \type {Text and Display}, \type {Script}, + \type {Decorative}, \type {Pictorial} \NC\NR +\NC serifstyle \NC string \NC See the \OPENTYPE\ font specification for values\NC\NR +\NC weight \NC string \NC id. \NC\NR +\NC proportion \NC string \NC id. \NC\NR +\NC contrast \NC string \NC id. \NC\NR +\NC strokevariation \NC string \NC id. \NC\NR +\NC armstyle \NC string \NC id. \NC\NR +\NC letterform \NC string \NC id. \NC\NR +\NC midline \NC string \NC id. \NC\NR +\NC xheight \NC string \NC id. \NC\NR +\stoptabulate + +\subsubsection{names table} + +Each item has two top|-|level keys: + +\starttabulate[|lT|l|p|] +\NC \ssbf key \NC \bf type \NC \bf explanation \NC\NR +\NC lang \NC string \NC language for this entry \NC\NR +\NC names \NC table \NC \NC\NR +\stoptabulate + +The \type{names} keys are the actual \TRUETYPE\ name strings. The +possible keys are: + +\starttabulate[|lT|p|] +\NC \ssbf key \NC \bf explanation \NC\NR +\NC copyright \NC \NC\NR +\NC family \NC \NC\NR +\NC subfamily \NC \NC\NR +\NC uniqueid \NC \NC\NR +\NC fullname \NC \NC\NR +\NC version \NC \NC\NR +\NC postscriptname \NC \NC\NR +\NC trademark \NC \NC\NR +\NC manufacturer \NC \NC\NR +\NC designer \NC \NC\NR +\NC descriptor \NC \NC\NR +\NC venderurl \NC \NC\NR +\NC designerurl \NC \NC\NR +\NC license \NC \NC\NR +\NC licenseurl \NC \NC\NR +\NC idontknow \NC \NC\NR +\NC preffamilyname \NC \NC\NR +\NC prefmodifiers \NC \NC\NR +\NC compatfull \NC \NC\NR +\NC sampletext \NC \NC\NR +\NC cidfindfontname \NC \NC\NR +\stoptabulate + +\subsubsection{anchor_classes table} + +The anchor_classes classes: + +\starttabulate[|lT|l|p|] +\NC \ssbf key \NC \bf type \NC \bf explanation \NC\NR +\NC name \NC string \NC A descriptive id of this anchor class\NC\NR +\NC lookup \NC string \NC \NC\NR +\NC type \NC string \NC One of 'mark', 'mkmk', 'curs', 'mklg' \NC\NR +\stoptabulate +% type is actually a lookup subtype, not a feature name. officiallu, these strings +% should be gpos_mark2mark etc. + +\subsubsection{gpos table} + +Th gpos table has one array entry for each lookup. + +\starttabulate[|lT|l|p|] +\NC \ssbf key \NC \bf type \NC \bf explanation \NC\NR +\NC type \NC string \NC One of + 'gpos_single', 'gpos_pair', 'gpos_cursive', + 'gpos_mark2base', 'gpos_mark2ligature', 'gpos_mark2mark', 'gpos_context', + 'gpos_contextchain' % , 'kern_statemachine' +\NC\NR +\NC flags \NC table \NC \NC\NR +\NC name \NC string \NC \NC\NR +\NC features \NC array \NC \NC\NR +\NC subtables \NC array \NC \NC\NR +\stoptabulate + +The flags table has a true value for each of the lookup flags that is +actually set: + +\starttabulate[|lT|l|p|] +\NC \ssbf key \NC \bf type \NC \bf explanation \NC\NR +\NC r2l \NC boolean \NC \NC\NR +\NC ignorebaseglyphs \NC boolean \NC \NC\NR +\NC ignoreligatures \NC boolean \NC \NC\NR +\NC ignorecombiningmarks \NC boolean \NC \NC\NR +\stoptabulate + + + +The features table has: + +\starttabulate[|lT|l|p|] +\NC \ssbf key \NC \bf type \NC \bf explanation \NC\NR +\NC tag \NC string \NC \NC\NR +\NC scripts \NC table \NC \NC\NR +\NC ismax \NC number \NC (only if true)\NC\NR +\stoptabulate + +The scripts table within features has: + +\starttabulate[|lT|l|p|] +\NC \ssbf key \NC \bf type \NC \bf explanation \NC\NR +\NC script \NC string \NC \NC\NR +\NC langs \NC array of strings \NC \NC\NR +\stoptabulate + + + +The subtables table has: + +\starttabulate[|lT|l|p|] +\NC \ssbf key \NC \bf type \NC \bf explanation \NC\NR +\NC name \NC string \NC \NC\NR +\NC suffix \NC string \NC (only if used)\NC\NR % used by gpos_single to get a default +\NC anchor_classes \NC number \NC (only if used)\NC\NR +\NC vertical_kerning \NC number \NC (only if used)\NC\NR +\NC kernclass \NC table \NC (only if used)\NC\NR +\stoptabulate + + +The kernclass with subtables table has: + +\starttabulate[|lT|l|p|] +\NC \ssbf key \NC \bf type \NC \bf explanation \NC\NR +%\NC first_cnt \NC number \NC \NC\NR +%\NC second_cnt \NC number \NC \NC\NR +\NC firsts \NC array of strings \NC \NC\NR +\NC seconds \NC array of strings \NC \NC\NR +\NC lookup \NC string \NC associated lookup \NC \NR +\NC offsets \NC array of numbers \NC \NC\NR +%\NC kcid \NC number \NC ? \NC\NR +\stoptabulate + +\subsubsection{gsub table} + +This has identical layout to the \type{gpos} table, except for the +type: + +\starttabulate[|lT|l|p|] +\NC \ssbf key \NC \bf type \NC \bf explanation \NC\NR +\NC type \NC string \NC One of 'gsub_single', 'gsub_multiple', 'gsub_alternate', + 'gsub_ligature', 'gsub_context', 'gsub_contextchain', 'gsub_reversecontextchain' +\NC\NR +\stoptabulate + + + +\subsubsection{ttf_tables table} + +\starttabulate[|lT|l|p|] +\NC \ssbf key \NC \bf type \NC \bf explanation \NC\NR +\NC tag \NC string \NC \NC\NR +\NC len \NC number \NC \NC\NR +\NC maxlen \NC number \NC \NC\NR +\NC data \NC number \NC \NC\NR +\stoptabulate + +\subsubsection{kerns table} + +Substructure is identical to the per|-|glyph subtable. + +\subsubsection{vkerns table} + +Substructure is identical to the per|-|glyph subtable. + +\subsubsection{texdata table} + + +\starttabulate[|lT|l|p|] +\NC \ssbf key \NC \bf type \NC \bf explanation \NC\NR +\NC type \NC string \NC \type {unset}, \type {text}, \type {math}, \type {mathext}\NC\NR +\NC params \NC array \NC 22 font numeric parameters\NC\NR +\stoptabulate + +\subsubsection{lookups table} + +Top|-|level \type{lookups} is quite different from the ones at +character level. The keys in this hash are strings, the values the +actual lookups, represented as dictionary tables. + +\starttabulate[|lT|l|p|] +\NC \ssbf key \NC \bf type \NC \bf explanation \NC\NR +\NC type \NC number \NC \NC\NR +\NC format \NC enum \NC One of 'glyphs', 'class', 'coverage', 'reversecoverage' \NC\NR +\NC tag \NC string \NC \NC\NR +\NC current_class \NC array \NC \NC\NR +\NC before_class \NC array \NC \NC\NR +\NC after_class \NC array \NC \NC\NR +\NC rules \NC array \NC an array of rule items\NC\NR +\stoptabulate + +Rule items have one common item and one specialized item: + +\starttabulate[|lT|l|p|] +\NC \ssbf key \NC \bf type \NC \bf explanation \NC\NR +\NC lookups \NC array \NC A linear array of lookup names\NC\NR +\NC glyph \NC array \NC Only if the parent's format is \quote{glyph}\NC\NR +\NC class \NC array \NC Only if the parent's format is \quote{glyph}\NC\NR +\NC coverage \NC array \NC Only if the parent's format is \quote{glyph}\NC\NR +\NC reversecoverage \NC array \NC Only if the parent's format is \quote{glyph}\NC\NR +\stoptabulate + +A glyph table is: + +\starttabulate[|lT|l|p|] +\NC \ssbf key \NC \bf type \NC \bf explanation \NC\NR +\NC names \NC string \NC \NC\NR +\NC back \NC string \NC \NC\NR +\NC fore \NC string \NC \NC\NR +\stoptabulate + + + +A class table is: + +\starttabulate[|lT|l|p|] +\NC \ssbf key \NC \bf type \NC \bf explanation \NC\NR +\NC current \NC array \NC of numbers \NC\NR +\NC before \NC array \NC of numbers \NC\NR +\NC after \NC array \NC of numbers \NC\NR +\stoptabulate + +coverage: + +\starttabulate[|lT|l|p|] +\NC \ssbf key \NC \bf type \NC \bf explanation \NC\NR +\NC current \NC array \NC of strings \NC\NR +\NC before \NC array \NC of strings\NC\NR +\NC after \NC array \NC of strings \NC\NR +\stoptabulate + +reversecoverage: + +\starttabulate[|lT|l|p|] +\NC \ssbf key \NC \bf type \NC \bf explanation \NC\NR +\NC current \NC array \NC of strings \NC\NR +\NC before \NC array \NC of strings\NC\NR +\NC after \NC array \NC of strings \NC\NR +\NC replacements \NC string \NC \NC\NR +\stoptabulate + +\section{The \luatex{lang} library} + +This library provides the interface to \LUATEX's structure +representing a language, and the associated functions. + +\startfunctioncall + l = lang.new() + l = lang.new(number id) +\stopfunctioncall + +This function creates a new userdata object. An object of type +\type{} is the first argument to most of the other functions +in the \luatex{lang} library. These functions can also be used as if +they were object methods, using the colon syntax. + +Without an argument, the next available internal id number will be +assigned to this object. With argument, an object will be created that +links to the internal language with that id number. + +\startfunctioncall +number n = lang.id( l) +\stopfunctioncall + +returns the internal \tex{language} id number this object refers to. + +\startfunctioncall +string n = lang.hyphenation( l) +lang.hyphenation( l, string n) +\stopfunctioncall + +Either returns the current hyphenation exceptions for this language, +or adds new ones. The syntax of the string is explained in the next +chapter,~\in{section}[patternsexceptions]. + +\startfunctioncall +lang.clear_hyphenation( l) +\stopfunctioncall + +Clears the exception dictionary for this language. + +\startfunctioncall +string n = lang.clean(string o) +\stopfunctioncall + +Creates a hypenation key from the supplied hyphenation value. The +syntax of the argument string is explained in the next +chapter,~\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. + +\startfunctioncall +string n = lang.patterns( l) +lang.patterns( l, string n) +\stopfunctioncall + +Adds additional patterns for this language object, or returns the +current set. The syntax of this string is explained in the next +chapter,~\in{section}[patternsexceptions]. + +\startfunctioncall +lang.clear_patterns( l) +\stopfunctioncall + +Clears the pattern dictionary for this language. + +\startfunctioncall +number n = lang.prehyphenchar( l) +lang.prehyphenchar( l, number n) +\stopfunctioncall + +Gets or sets the \quote{pre-break} hyphen character for this font +(initially the hyphen, decimal 45). + +\startfunctioncall +number n = lang.posthyphenchar( l) +lang.posthyphenchar( l, number n) +\stopfunctioncall + +Gets or sets the \quote{post-break} hyphen character for this font +(initially null, decimal 0). + + +\startfunctioncall +boolean success = lang.hyphenate( head) +boolean success = lang.hyphenate( head, tail) +\stopfunctioncall + +Inserts hyphenation points (discretionary nodes) in a node list. If +\type{tail} is given as argument, processing stops on that node. +Currently, \type{succes} is always true if \type{head} (and \type{tail}, if +specified) are proper nodes, regardless of possible other errors. + +\chapter[languages]{Languages and characters, Fonts and glyphs} + +\LUATEX's internal handling of the characters and glyphs that eventually +become typeset is quite different from the way \TEX82 handles those +same objects. The easiest way to explain the difference is to focus on +unrestricted horizontal mode (i.\,e.\ paragraphs) and hyphenation first. +Later on, it will be easy to deal with the differences that occur in +horizontal and math modes. + +In \TEX82, the characters you type are converted into \type{char_node} +records when they are encountered by the main control loop. \TEX\ +attaches and processes the font information while creating those +records, so that the resulting \quote{horizontal list} contains the final +forms of ligatures and implicit kerning. + +When it becomes necessary to hyphenate words in a paragraph, \TEX\ +converts (one word at time) the \type{char_node} records into a +string array by replacing ligatures with their components and +ignoring the kerning. Then it runs the hyphenation algorithm on this +string, and converts the hyphenated result back into a +\quote{horizontal list} that is consecutively spliced back into +the paragraph stream. + +The \type{char_node} records are somewhat misnamed, as they are glyph +positions in specific fonts, and therefore not really \quote{characters} +in the linguistic sense. There is no language information inside the +\type{char_node} records. Instead, language information is passed along +using \type{language whatsit} records inside the horizontal list. + +In \LUATEX, the situation is quite different. The characters you +type are always converted into \type{glyph_node} records with a +special subtype to identify them as being intended as linguistic +characters. \LUATEX\ stores the needed language information in those +records, but does not do any font-related processing at the time of +node creation. + +When it becomes necessary to typeset a paragraph, \LUATEX\ first +inserts all hyphenation points right into the whole node list. +Next, it processes all the font information in the whole list +(creating ligatures and adjusting kerning), and finally it adjusts +all the subtype identifiers so that the records are \quote{glyph +nodes} from now on. + +That was the broad overview. The rest of this chapter will deal with the +minutiae of the new process. + +\section[charsandglyphs]{Characters and glyphs} + +\TEX82 (including \PDFTEX) differentiated between \type{char_node}s +and \type{lig_node}s. The former are simple items that contained +nothing but a \quote{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. + +In \LUATEX, these two types are merged into one, somewhat larger +structure called a \type{glyph_node}. Besides having the old +character, font, and component fields, and the new special fields like +\quote{attr} (see~\in{section}[glyphnodes]), these nodes also contain: + +\startitemize +\item A subtype, split into four main types: + \startitemize + \item \quote{character} -- for characters to be hyphenated + \item \quote{glyph} -- for specific font glyphs + \item \quote{ligature} -- for ligatures + \item \quote{ghost} -- for \quote{ghost objects} + \stopitemize + The latter two make further use of two extra fields: + \startitemize + \item \quote{left} -- for ligatures: created from a left word boundary. + for ghosts: created from \tex{leftghost} + \item \quote{right} -- for ligatures: created from a right word boundary. + for ghosts: created from \tex{rightghost} + \stopitemize + for ligatures, both bits can be set at the same time (in case of a single-glyph word). + +\item \type{glyph_node}s of type \quote{character} also contain language data, + split into four items that were current when the node was created: + the \tex{setlanguage} (15 bits), \tex{lefthyphenmin} (8 bits), + \tex{righthyphenmin} (8 bits), and \tex{uchyph} (1 bit). +\stopitemize + +Incidentally, \LUATEX\ allows 32768 separate languages, and words can +be 256 characters long. + +Because the \tex{uchyph} value is saved in the actual nodes, its +handling is subtly different from \TEX82: changes to \tex{uchyph} +become effective immediately, not at the end of the current partial +paragraph. + +Typeset boxes now always have their language information embedded in +the nodes themselves, so there is no longer a possible dependancy on +the surrounding language settings. In \TEX82, a mid-paragraph +statement like \type{\unhbox0} would process the box using the current +paragraph language unless there was a \tex{setlanguage} issued inside +the box. In \LUATEX, all language variables are already frozen. + + +\section{The main control loop} + +In \LUATEX's main loop, almost all input characters that are to be +typeset are converted into \type{glyph_node} records with subtype +\quote{character}, but there are a few small exceptions. + +First, the \tex{accent} primitives creates nodes with subtype \quote{glyph} +instead of \quote{character}: one for the actual accent and one for the +accentee. The primary reason for this is that \tex{accent} in \TEX82 +is explicitly dependent on the current font encoding, so it would not +make much sense to attach a new meaning to the primitive's name, as +that would invalidate many old documents and macro packages. A +secondary reason is that in \TEX82, \tex{accent} prohibits hyphenation +of the current word. Since in \LUATEX\ hyphenation only takes place on +\quote{character} nodes, it is possible to achieve the same effect. + +This change of meaning did happen with \tex{char}, that now generates +\quote{character} nodes, consistent with its changed meaning in \XETEX. +The changed status of \tex{char} is not yet finalized, but if it stays +as it is now, a new primitive \tex{glyph} should be added to directly +insert a font glyph id. + +Second, all the results of processing in math mode eventually become +nodes with \quote{glyph} subtypes. + +Third, the \ALEPH-derived commands \tex{leftghost} and +\tex{rightghost} create nodes of a third subtype: \quote{ghost}. These nodes +are ignored completely by all further processing until the stage where +inter-glyph kerning is added. + +Fourth, automatic discretionaries are handled differently. \TEX82 +inserts an empty discretionary after sensing an input character that +matches the \tex{hyphenchar} in the current font. This test is wrong, +in our opinion: wether or not hyphenation takes place should not +depend on the current font, it is a language property. + +In \LUATEX, it works like this: if \LUATEX\ senses a string of input +characters that matches the value of the new integer parameter +\tex{exhyphenchar}, it will insert an empty discretionary after that +series of nodes. Initex sets the \type{\exhyphenchar=`\-}. +Incidentally, this is a global parameter instead of a +language-specific one because it may be useful to change the value +depending on the document structure instead of the text language. + +The exact status and meaning of \tex{hyphenchar} is still under +consideration, it will probably become used in the character to glyph +conversion stage. Currently it is simply ignored. + +Fifth, \tex{setlanguage} no longer creates whatsits. The meaning of +\tex{setlanguage} is changed so that it is now an integer parameter +like all others. That integer parameter is used in \tex{glyph_node} +creation to add language information to the glyph nodes. In +conjunction, the \tex{language} primitive is extended so that it +always also updates the value of \tex{setlanguage}. + +Sixth, the \tex{noboundary} command (this command prohibits word +boundary processing where that would normally take place) now does +create whatsits. These whatsits are needed because the exact place of +the \tex{noboundary} command in the input stream has to be retained +until after the ligature and font processing stages. + +Finally, there is no longer a \type{main_loop} label in the +code. Remember that \TEX82 did quite a lot of processing while adding +\type{char_nodes} to the horizontal list? For speed reasons, it handled +that processing code outside of the \quote{main control} loop, and only the +first character of any \quote{word} was handled by that \quote{main control} loop. +In \LUATEX, there is no longer a need for that (all hard work is done +later), and the (now very small) bits of character-handling code have +been moved back inline. When \tex{tracingcommands} is on, this is +visible because the full word is reported, instead of just the initial +character. + + +\section[patternsexceptions]{Loading patterns and exceptions} + +The hyphenation algorithm in \LUATEX\ is quite different from the one +in \TEX82, although it uses essentially the same user input. + +After expansion, the argument for \tex{patterns} has to be proper +UTF-8, no \tex{char} or \tex{chardef-ed} commands are allowed. (The +current implementation is even more strict, and will reject all +non-unicode characters, but that will be changed in the future. For +now, the generated errors are a valuable tool in discovering +font-encoding specific pattern files) + +Likewise, the expanded argument for \tex{hyphenation} also has to be +proper UTF-8, but here a tiny little bit of extra syntax is provided: + +\startitemize[n] +\item three sets of arguments in curly braces (\type{{}{}{}}) + indicates a desired complex discretionary, with arguments + as in \tex{discretionary}'s command in normal document input. +\item \type{-} indicates a desired simple discretionary, cf. \type{\-} and + \type{\discretionary{-}{}{}} in normal document input. +\item Internal command names are ignored. This rule is provided + especially for \tex{discretionary}, but it also helps to deal with + \tex{relax} commands that may sneak in. +\item \type{=} indicates a hyphen in the document input (but that + is only useful in documents where \tex{exhyphenchar} is not equal to + the hyphen). +\stopitemize + +The expanded argument is first converted back to a space-separated +string while dropping the internal command names. This string is then +converted into a dictionary by a routine that creates key||value pairs +by converting the other listed items. It is important to note that the +keys in an exception dictionary can always be generated from the +values. Here are a few examples: + +\starttabulate[|l|l|l|] +\NC \ssbf value \NC \ssbf implied key (input) \NC \ssbf effect\NC\NR +\NC \type{ta-ble} \NC table \NC \type{ta\-ble} + ($=$ \type{ta\discretionary{-}{}{}ble})\NC\NR +\NC \type{ba{k-}{}{c}ken}\NC backen \NC \type{ba\discretionary{k-}{}{c}ken}\NC\NR +\stoptabulate + +The resultant patterns and exception dictionary will be stored under +the language code that is the present value of \tex{language}. + +In the last line of the table, you see there is no \tex{discretionary} +command in the value: the command is optional in the \TEX-based input +syntax. The underlying reason for that is that it is conceivable that +a whole dictionary of words is stored as a plain text file and loaded +into \LUATEX\ using one of the functions in the Lua \luatex{lang} +library. This loading method is quite a bit faster than going through +the \TEX\ language primitives, but some (most?) of that speed gain +would be lost if it had to interpret command sequences while doing so. + +The motivation behind the \ETEX\ extension \tex{savinghyphcodes} was +that hyphenation heavily depended on font encodings. This is no longer +true in \LUATEX, and the corresponding primitive is ignored pending +complete removal. The future semantics of \tex{uppercase} and +\tex{lowercase} are still under consideration, no changes have taken +place yet. + + +\section{Applying hyphenation} + +The internal structures \LUATEX\ uses for the insertion of +discretionaries in words is very different from the ones in \TEX82, +and that means there are some noticable differences in handling as +well. + +First and foremost, there is no \quote{compressed trie} involved in +hyphenation. The algorithm still reads \PATGEN-generated pattern +files, but \LUATEX\ uses a finite state hash to match the patterns +against the word to be hyphenated. This algorithm is based on the +\quote{libhnj} library used by OpenOffice. +The memory allocation for this new implementation is completely +dynamic, so the \WEBC\ setting for \type{trie_size} is ignored. + +Differences between \LUATEX\ and \TEX82 that are a direct result of that: + +\startitemize +\item \LUATEX\ happily hyphenates the full Unicode character range. +\item Pattern and exception dictionary size is limited by the + available memory only, all allocations are done dynamically. + The trie-related settings in \type{texmf.cnf} are ignored. +\item Because there is no \quote{trie preparation} stage, language patterns + never become frozen. This means that the primitive \tex{patterns} + (and its lua counterpart \luatex{lang.patterns}) can be used at any + time, not only in initex. +\item Only the string representation of \tex{patterns} and + \tex{hyphenation} is stored in the format file. At format load time, + they are simply re-evaluated. It follows that there is no real + reason to preload languages in the format file. In fact, it is + usually not a good idea to do so. It is much smarter to load + patterns no sooner than the first time they are actually needed. +\item \LUATEX\ uses the language-specific variables +\tex{prehyphenchar} and \tex{posthyphenchar} in the creation of +discretionaries, instead of \TEX82's \tex{hyphenchar}. +\stopitemize + +Previously, there were problems with changing the node attributes +mid-word, but that problem is now solved, as nodes in a word are not +converted to and from a string any more (this was required by the old +hyphenation code), they are edited in place. Inserted characters and +ligatures inherit their attributes from the nearest glyph node item +(usually the preceding one, but the following one for the items +inserted at the left-hand side of a word). + +Word boundaries are no longer implied by font switches, but by +language switches. One word can have two separate fonts and still be +hyphenated correctly (but it can not have two different languages, +the \tex{setlanguage} command forces a word boundary). + +All languages start out with \type{\prehyphenchar=`\-} and +\type{\posthyphenchar=0}. When you assign the values of +\tex{prehyphenchar} and \tex{posthyphenchar}, you are actually +changing the settings for the current \tex{language}, this behavior +is compatible with \tex{patterns} and \tex{hyphenation}. + +\LUATEX\ also hyphenates the first word in a paragraph. + +Words can be up to 256 characters long (up from 64 in \TEX82). Longer +words generate an error right now, but eventually either the +limitation will be removed or perhaps it will become possbile to +silently ignore the excess characters (this is what happens in \TEX82, +but there the behavior cannot be controlled). + +If you are using the Lua function \type{lang.hyphenate}, you should be +aware that this function expects to receive a list of \quote{character} +nodes. It will not operate properly in the presence of \quote{glyph}, +\quote{ligature}, or \quote{ghost} nodes, nor does it know how to deal with +kerning. In the near future, it will be able to skip over \quote{ghost} +nodes, and we may add a less fuzzy function you can call as well. + +The hyphenation exception dictionary is maintained as key-value +hash, and that is also dynamic, so the \type{hyph_size} setting is not +used either. + +A technical paper detailing the new algorithm will be released as a +separate document. + +\section{Applying ligatures and kerning} + +After all possible hyphenation points have been inserted in the list, +\LUATEX\ will process the list to convert the \quote{character} nodes into +\quote{glyph} and \quote{ligature} nodes. This is actually done in two stages: +first all ligatures are processed, then all kerning information is +applied to the result list. But those two stages are somewhat +dependent on each other: If the used font makes it possible to do so, +the ligaturing stage adds virtual \quote{character} nodes to the word +boundaries in the list. While doing so, it removes and interprets +\type{noboundary} nodes. The kerning stage deletes those word boundary +items after it is done with them, and it does the same for \quote{ghost} +nodes. Finally, at the end of the kerning stage, all remaining +\quote{character} nodes are converted to \quote{glyph} nodes. + +This work separation is worth mentioning because, if you overrule from +Lua only one of the two callbacks related to font handling, then you +have to make sure you perform the tasks normally done by \LUATEX\ +itself in order to make sure that the other, non-overrruled, routine +continues to function properly. + +Work in this area is not yet complete, but most of the possible cases +are handled by our rewritten ligaturing engine. We are working hard to +make sure all of the possible inputs will become supported soon. + +For example, take the word \type{office}, hyphenated \type{of-fice}, +using a \quote{normal} font with all the \type{f}-\type{i} ligatures: +\starttabulate[|l|l|] +\NC Initial: \NC \type{{o}{f}{f}{i}{c}{e}} \NC\NR +\NC After hyphenation: \NC \type{{o}{f}{{-},{},{}}{f}{i}{c}{e}}\NC\NR +\NC First ligature stage: \NC \type{{o}{{f}{-},{f},{ff}}{i}{c}{e}}\NC\NR +\NC Final result: \NC \type{{o}{{f}{-},{fi},{ffi}}{c}{e}} \NC\NR +\stoptabulate + +That's bad enough, but if there was a hyphenation point between the +\type{f} and the \type{i}: \type{of-f-ice}, the final result should be: +\starttyping + {o}{{f}{-}, + {{f}{-}, + {i}, + {fi}}, + {{ff}{-}, + {i}, + {ffi}}}{c}{e} +\stoptyping +with discretionaries in the post-break text as well as in the +replacement text of the top-level discretionary that resulted from the +first hyphenation point. And this is only a simple case. + +\section{Breaking paragraphs into lines} + +This code is still almost unchanged, but because of the +above-mentioned changes with respect to discretionaries and ligatures, +line breaking will potentially be different from traditional \TEX. +The actual line breaking code is still based on the \TEX82 algorithms, +and it does not expect there to be discretionaries inside of +discretionaries. + +But that situation is now fairly common in \LUATEX, due to the changes +to the ligaturing mechanism. And also, the \LUATEX\ discretionary +nodes are implemented slightly different from the \TEX82 nodes: the +\type{no_break} text is now embedded inside the disc node, where +previously these nodes kept their place in the horizontal list (the +discretionary node contained a counter indicating how many nodes to +skip). + +The combined effect of these two differences is that \LUATEX\ does not +always use all of the potential breakpoints in a paragraph, especially +when fonts with many ligatures are used. + +% TODO: +% Check \sfcode handling +% Implement \glyph +% +% Remove \savinghyphcodes +% Allow non-UCS characters in \patterns + +\chapter[fonts]{Font structure} + +All \TEX\ fonts are represented to \LUA\ code as tables, and +internally as C~structures. All keys in the table below are saved in +the internal font structure if they are present in the table returned +by the +\luatex{define_font} callback, or if they result from the normal \TFM|/|\VF\ +reading routines if there is no \luatex{define_font} callback defined. + +The column \quote{from \VF} means that this key will be created by the +\luatex{font.read_vf()} routine, \quote{from \TFM} means that the key will be created +by the \luatex{font.read_tfm()} routine, and \quote{used} means whether or not the +\LUATEX\ engine itself will do something with the key. + +The top|-|level keys in the table are as follows: + +\starttabulate[|l|l|l|l|l|p|] +\NC \ssbf key \NC \bf from vf \NC \bf from tfm \NC \bf used\NC \bf value type \NC \bf description \NC\NR +\NC name \NC yes \NC yes \NC yes \NC string \NC metric (file) name\NC\NR +\NC area \NC no \NC yes \NC yes \NC string \NC (directory) location, typically empty\NC\NR +\NC used \NC no \NC yes \NC yes \NC boolean\NC used already? (initial: false)\NC \NR +\NC characters \NC yes \NC yes \NC yes \NC table \NC the defined glyphs of this font \NC \NR +\NC checksum \NC yes \NC yes \NC no \NC number \NC default: 0 \NC \NR +\NC designsize \NC no \NC yes \NC yes \NC number \NC expected size (default: 655360 == 10pt) \NC \NR +\NC direction \NC no \NC yes \NC yes \NC number \NC default: 0 (LTR) \NR +\NC encodingbytes \NC no \NC no \NC yes \NC number \NC default: depends on \type {format}\NC\NR +\NC encodingname \NC no \NC no \NC yes \NC string \NC encoding name\NC\NR +\NC fonts \NC yes \NC no \NC yes \NC table \NC locally used fonts\NC \NR +\NC fullname \NC no \NC no \NC yes \NC string \NC actual (\POSTSCRIPT) name\NC\NR +\NC header \NC yes \NC no \NC no \NC string \NC header comments, if any\NC \NR +\NC hyphenchar \NC no \NC no \NC yes \NC number \NC default: TeX's \tex{hyphenchar} \NC \NR +\NC parameters \NC no \NC yes \NC yes \NC hash \NC default: 7 parameters, all zero \NC \NR +\NC size \NC no \NC yes \NC yes \NC number \NC loaded (at) size. (default: same as designsize) \NC \NR +\NC skewchar \NC no \NC no \NC yes \NC number \NC default: TeX's \tex{skewchar} \NC \NR +\NC type \NC yes \NC no \NC yes \NC string \NC basic type of this font\NC \NR +\NC format \NC no \NC no \NC yes \NC string \NC disk format type\NC \NR +\NC embedding \NC no \NC no \NC yes \NC string \NC \PDF\ inclusion\NC \NR +\NC filename \NC no \NC no \NC yes \NC string \NC disk file name\NC\NR +\NC tounicode \NC no \NC yes \NC yes \NC number \NC if 1, \LUATEX\ assumes per-glyph tounicode entries are +present in the font\NC\NR +\NC stretch \NC no \NC no \NC yes \NC number \NC the `stretch' value from \type{\pdffontexpand}\NC\NR +\NC shrink \NC no \NC no \NC yes \NC number \NC the `shrink' value from \type{\pdffontexpand}\NC\NR +\NC step \NC no \NC no \NC yes \NC number \NC the `step' value from \type{\pdffontexpand}\NC\NR +\NC auto_expand \NC no \NC no \NC yes \NC boolean\NC the `autoexpand keyword from \type{\pdffontexpand}\NC\NR +\NC expansion_factor \NC no \NC no \NC no \NC number \NC the actual expansion factor of an expanded font\NC\NR +\NC attributes \NC no \NC no \NC yes \NC string \NC the \type{\pdffontattr}\NC\NR +\stoptabulate + +The key \type{name} is always required. + +The keys \type{stretch}, \type{shrink}, \type{step} and optionally \type{auto_expand} +only have meaning when used together: they can be used to replace a post-loading +\type{\pdffontexpand} command. + +The \type{expansion_factor} is value that can be present inside a font in \type{font.fonts}. +It is the actual expansion factor (a value between \type{-shrink} and \type{stretch}, with +step \type{step}) of a font that was automatically generated by the font expansion algorithm. + +The key \type{attributes} can be used to replace \type{\pdffontattr}. + +The key \type{used} is set by the engine when a font is actively in +use, this makes sure that the font's definition is written to the +output file (\DVI\ or \PDF). The \TFM\ reader sets it to false. + +The \type{direction} is a number signalling the \quote{normal} direction for +this font. There are sixteen possibilities: + +\starttabulate[|c|c|c|c|] +\NC \bf number \NC \bf meaning \NC \bf number \NC \bf meaning \NC\NR +\NC 0 \NC LT \NC 8 \NC TT \NC\NR +\NC 1 \NC LL \NC 9 \NC TL \NC\NR +\NC 2 \NC LB \NC 10 \NC TB \NC\NR +\NC 3 \NC LR \NC 11 \NC TR \NC\NR +\NC 4 \NC RT \NC 12 \NC BT \NC\NR +\NC 5 \NC RL \NC 13 \NC BL \NC\NR +\NC 6 \NC RB \NC 14 \NC BB \NC\NR +\NC 7 \NC RR \NC 15 \NC BR \NC\NR +\stoptabulate + +These are \OMEGA|-|style direction abbreviations: the first character +indicates the \quote{first} edge of the character glyphs (the edge that is +seen first in the writing direction), the second the \quote{top} side. + +The \type{parameters} is a hash with mixed key types. There are seven +possible string keys, as well as a number of integer indices (these +start from 8 up). The seven strings are actually used instead of the +bottom seven indices, because that gives a nicer user interface. + +The names and their internal remapping: + +\starttabulate[|l|c|] +\NC \bf name \NC \bf internal remapped number \NC\NR +\NC slant \NC 1 \NC\NR +\NC space \NC 2 \NC\NR +\NC space_stretch \NC 3 \NC\NR +\NC space_shrink \NC 4 \NC\NR +\NC x_height \NC 5 \NC\NR +\NC quad \NC 6 \NC\NR +\NC extra_space \NC 7 \NC\LR +\stoptabulate + +The keys \type{type}, \type{format}, \type{embedding}, \type{fullname} and +\type{filename} are used to embed \OPENTYPE\ fonts in the result \PDF. + +The \type{characters} table is a list of character hashes indexed by +an integer number. The number is the \quote{internal code} \TEX\ knows this +character by. + +Two very special string indexes can be used also: \type{left_boundary} is a +virtual character whose ligatures and kerns are used to handle word +boundary processing. \type{right_boundary} is similar but not actually +used for anything (yet!). + +Other index keys are ignored. + +Each character hash itself is a hash. For example, here is the +character \quote{f} (decimal 102) in the font cmr10 at 10 points: + +% hahe: why this complicated notation, why not e. g. width=200250? +\starttyping +[102] = { + ['width'] = 200250, + ['height'] = 455111, + ['depth'] = 0, + ['italic'] = 50973, + ['kerns'] = { + [63] = 50973, + [93] = 50973, + [39] = 50973, + [33] = 50973, + [41] = 50973 + }, + ['ligatures'] = { + [102] = { + ['char'] = 11, + ['type'] = 0 + }, + [108] = { + ['char'] = 13, + ['type'] = 0 + }, + [105] = { + ['char'] = 12, + ['type'] = 0 + } + } +} +\stoptyping + +The following top|-|level keys can be present inside a character hash: + +\starttabulate[|l|c|c|c|l|p|] +\NC \ssbf key \NC \bf from vf \NC \bf from tfm \NC \bf used \NC \bf value type \NC \bf description \NC\NR +\NC width \NC yes \NC yes \NC yes \NC number \NC character's width, in sp (default 0) \NC\NR +\NC height \NC no \NC yes \NC yes \NC number \NC character's height, in sp (default 0) \NC\NR +\NC depth \NC no \NC yes \NC yes \NC number \NC character's depth, in sp (default 0) \NC\NR +\NC italic \NC no \NC yes \NC yes \NC number \NC character's italic correction, in sp (default zero) \NC\NR +\NC left_protruding \NC no \NC no \NC maybe \NC number \NC character's \type{\lpcode}\NC\NR +\NC right_protruding \NC no \NC no \NC maybe \NC number \NC character's \type{\rpcode}\NC\NR +\NC expansion_factor \NC no \NC no \NC maybe \NC number \NC character's \type{\efcode}\NC\NR +\NC tounicode \NC no \NC no \NC maybe \NC string \NC character's Unicode equivalent(s), in +UTF-16BE hexadecimal format\NC\NR +\NC next \NC no \NC yes \NC yes \NC number \NC the \quote{next larger} character index \NC\NR +\NC extensible \NC no \NC yes \NC yes \NC table \NC the constituent parts of an extensible recipe \NC\NR +\NC kerns \NC no \NC yes \NC yes \NC table \NC kerning information \NC\NR +\NC ligatures \NC no \NC yes \NC yes \NC table \NC ligaturing information \NC\NR +\NC commands \NC yes \NC no \NC yes \NC array \NC virtual font commands \NC\NR +\NC name \NC no \NC no \NC no \NC string \NC the character (\POSTSCRIPT) name \NC\NR +\NC index \NC no \NC no \NC yes \NC number \NC the (\OPENTYPE\ or \TRUETYPE) font glyph index \NC\NR +\NC used \NC no \NC yes \NC yes \NC boolean \NC typeset already (default: false)? \NC\NR +\stoptabulate + +The values of \type{left_protruding} and \type{right_protruding} are used only when +\type{\pdfprotrudechars} is non-zero. + +Whether or not \type{expansion_factor} is used depends on the font's global expansion +settings, as well as on the value of \type{\pdfadjustspacing}. + +The usage of \type{tounicode} is this: if this font specifies a \type{tounicode=1} at +the top level, then \LUATEX\ will construct a \type{/ToUnicode} entry for the PDF +font (or font subset) based on the character-level \type{tounicode} strings, where +they are available. If a character does not have a sensible Unicode equivalent, +do not provide a string either (no empty strings). + +If the font-level \type{tounicode} is not set, then \LUATEX\ will build up +\type{/ToUnicode} based on the \TEX\ code points you used, and any character-level +\type{tounicodes} will be ignored. {\it At the moment, the string format is exactly the +format that is expected by Adobe CMAP files (UTF-16BE in hexadecimal encoding), minus +the enclosing angle brackets. This may change in the future.} Small example: the +\type{tounicode} for a \type{fi} ligature would be \type{00660069}. + +The presence of \type{extensible} will overrule \type{next}, if that is also present. + +The \type{extensible} table is very simple: + +\starttabulate[|l|l|p|] +\NC \ssbf key \NC \bf type \NC \bf description \NC\NR +\NC top \NC number \NC \quote{top} character index \NC\NR +\NC mid \NC number \NC \quote{middle} character index \NC\NR +\NC bot \NC number \NC \quote{bottom} character index \NC\NR +\NC rep \NC number \NC \quote{repeatable} character index \NC\NR +\stoptabulate + +The \type{kerns} table is a hash indexed by character index (and +\quote{character index} is defined as either a non|-|negative integer or the +string value \type {right_boundary}), with the values the kerning to be +applied, in scaled points. + +The \type{ligatures} table is a hash indexed by character index (and +\quote{character index} is defined as either a non|-|negative integer or the +string value \type {right_boundary}), with the values being yet another small +hash, with two fields: + +\starttabulate[|l|l|p|] +\NC \ssbf key \NC \bf type \NC \bf description \NC\NR +\NC type \NC number \NC the type of this ligature command, default 0 \NC\NR +\NC char \NC number \NC the character index of the resultant ligature \NC\NR +\stoptabulate + +The \type{char} field in a ligature is required. + +The \type{type} field inside a ligature is the numerical or string value of one of the eight +possible ligature types supported by \TEX. When \TEX\ inserts a new ligature, it puts the new +glyph in the middle of the left and right glyphs. The original left and right glyphs can +optionally be retained, and when at least one of them is kept, it is also possible to move the +new \quote{insertion point} forward one or two places. The glyph that ends up to the right of the +insertion point will become the next \quote{left}. + +\starttabulate[|l|c|l|l|] +\NC \bf textual (Knuth) \NC \bf number \NC \bf string \NC result \NC\NR +\NC l + r =: n \NC 0 \NC \type{=:} \NC \|n \NC\NR +\NC l + r =:\| n \NC 1 \NC \type{=:|} \NC \|nr \NC\NR +\NC l + r \|=: n \NC 2 \NC \type{|=:} \NC \|ln \NC\NR +\NC l + r \|=:\| n \NC 3 \NC \type{|=:|} \NC \|lnr \NC\NR +\NC l + r =:\|\> n \NC 5 \NC \type{=:|>} \NC n\|r \NC\NR +\NC l + r \|=:\> n \NC 6 \NC \type{|=:>} \NC l\|n \NC\NR +\NC l + r \|=:\|\> n \NC 7 \NC \type{|=:|>} \NC l\|nr \NC\NR +\NC l + r \|=:\|\>\> n \NC 11 \NC \type{|=:|>>} \NC ln\|r \NC\NR +\stoptabulate + +The default value is~0, and can be left out. That signifies a \quote{normal} +ligature where the ligature replaces both original glyphs. In this table +the~\| indicates the final insertion point. + +The \type{commands} array is explained below. + +\section {Real fonts} + +Whether or not a \TEX\ font is a \quote{real} font that should be written to +the \PDF\ document is decided by the \type{type} value in the top|-|level +font structure. If the value is \type{real}, then this is a proper +font, and the inclusion mechanism will attempt to add the needed +font object definitions to the \PDF. + +Values for \type{type}: + +\starttabulate[|l|p|] +\NC \bf value \NC \bf description \NC\NR +\NC real \NC this is a base font \NC\NR +\NC virtual \NC this is a virtual font \NC\NR +\stoptabulate + +The actions to be taken depend on a number of different variables: + +\startitemize[packed] +\item Whether the used font fits in an 8-bit encoding scheme or not +\item The type of the disk font file +\item The level of embedding requested +\stopitemize + +A font that uses anything other than an 8-bit encoding vector has to +be written to the \PDF\ in a different way. + +The rule is: if the font table has \type {encodingbytes} set to~2, +then this is a wide font, in all other cases it isn't. The value~2 is +the default for \OPENTYPE\ and \TRUETYPE\ fonts loaded via \LUA. For +\TYPEONE\ fonts, you have to set \type {encodingbytes} to~2 +explicitly. For \PK\ bitmap fonts, wide font encoding is not +supported at all. + +If no special care is needed, \LUATEX\ currently falls back to the +mapfile|-|based solution used by \PDFTEX\ and \DVIPS. This behavior +will be removed in the future, when the existing code becomes +integrated in the new subsystem. + +But if this is a \quote{wide} font, then the new subsystem kicks in, and +some extra fields have to be present in the font structure. In this +case, \LUATEX\ does not use a map file at all. + +The extra fields are: \type{format}, \type{embedding}, \type{fullname}, +\type{cidinfo} (as explained above), \type{filename}, and the +\type{index} key in the separate characters. + +Values for \type{format} are: + +\starttabulate[|l|p|] +\NC \bf value \NC \bf description \NC\NR +\NC type1 \NC this is a \POSTSCRIPT\ \TYPEONE\ font \NC\NR +\NC type3 \NC this is a bitmapped (\PK) font \NC\NR +\NC truetype \NC this is a \TRUETYPE\ or \TRUETYPE|-|based \OPENTYPE\ font \NC\NR +\NC opentype \NC this is a \POSTSCRIPT|-|based \OPENTYPE\ font \NC\NR +\stoptabulate + +(\type{type3} fonts are provided for backward compatibility only, and do not +support the new wide encoding options.) + +Values for \type{embedding} are: + +\starttabulate[|l|p|] +\NC \bf value \NC \bf description \NC\NR +\NC no \NC don't embed the font at all \NC\NR +\NC subset \NC include and atttempt to subset the font \NC\NR +\NC full \NC include this font in its entirety \NC\NR +\stoptabulate + +It is not possible to artificially modify the transformation matrix +for the font at the moment. + +The other fields are used as follows: The \type{fullname} will be the +\POSTSCRIPT|/|\PDF\ font name. The \type{cidinfo} will be used as the +character set (the CID \type{/Ordering} and \type{/Registry} keys). The +\type{filename} points to the actual font file. If you include the +full path in the \type{filename} or if the file is in the local +directory, \LUATEX\ will run a little bit more efficient because it +will not have to re|-|run the \type{find_xxx_file} callback in that +case. + +Be careful: when mixing old and new fonts in one document, it is possible to +create \POSTSCRIPT\ name clashes that can result in printing +errors. When this happens, you have to change the \type{fullname} +of the font. + +Typeset strings are written out in a wide format using 2~bytes per +glyph, using the \type{index} key in the character information as +value. The overall effect is like having an encoding based on numbers +instead of traditional (\POSTSCRIPT) name|-|based reencoding. The way +to get the correct \type{index} numbers for \TYPEONE\ fonts is by +loading the font via \type{fontforge.open}; use the table indices as +\type{index} fields. + +This type of reencoding means that there is no longer a clear +connection between the text in your input file and the strings in the +output \PDF\ file. Dealing with this is high on the agenda. + +\section {Virtual fonts} + +You have to take the following steps if you want \LUATEX\ to treat the +returned table from \luatex{define_font} as a virtual font: + +\startitemize[packed] +\item Set the top|-|level key \type {type} to \type {virtual}. +\item Make sure there is at least one valid entry in \luatex{fonts} (see below) +\item Give a \type {commands} array to every character (see below) +\stopitemize + +The presence of the toplevel \type {type} key with the specific value +\type {virtual} will trigger handling of the rest of the special virtual +font fields in the table, but the mere existance of 'type' is enough +to prevent \LUATEX\ from looking for a virtual font on its own. + +Therefore, this also works \quote{in reverse}: if you are absolutely certain +that a font is not a virtual font, assigning the value \type{base} or +\type{real} to \type{type} will inhibit \LUATEX\ from looking for a virtual font +file, thereby saving you a disk search. + +The \luatex{fonts} is another \LUA\ array. The values are one- or two|-|key +hashes themselves, each entry indicating one of the base fonts in a +virtual font. An example makes this easy to understand + +\starttyping +fonts = { { name = 'ptmr8a', size = 655360}, + { name = 'psyr', size = 600000}, + { id = 38 } } +\stoptyping + +says that the first referenced font (index 1) in this virtual font is +\type{ptrmr8a} loaded at 10pt, and the second is \type{psyr} loaded +at a little over 9pt. The third one is previously defined font that +is known to \LUATEX\ as fontid \quote{38}. + +The array index numbers are used by the character command definitions +that are part of each character. + +The \luatex{commands} array is a hash where each item is another small array, with the first +entry representing a command and the extra items being the parameters to that command. The +allowed commands and their arguments are: + +\starttabulate[|l|l|l|p|] +\NC \bf command name \NC \bf arguments \NC \bf arg type \NC \bf description \NC\NR +\NC font \NC 1 \NC number \NC select a new font from the local \luatex{fonts} table\NC\NR +\NC char \NC 1 \NC number \NC typeset this character number from the current font, + and move right by the character's width\NC\NR +\NC node \NC 1 \NC node \NC output this node (list), and move right + by the width of this list\NC\NR +\NC slot \NC 2 \NC number \NC a shortcut for the combination of a font and char command\NC\NR +\NC push \NC 0 \NC \NC save current position\NC\NR +\NC nop \NC 0 \NC \NC do nothing \NC\NR +\NC pop \NC 0 \NC \NC pop position \NC\NR +\NC rule \NC 2 \NC 2 numbers \NC output a rule $w*h$, and move right.\NC\NR +\NC down \NC 1 \NC number \NC move down on the page\NC\NR +\NC right \NC 1 \NC number \NC move right on the page\NC\NR +\NC special \NC 1 \NC string \NC output a \tex{special} command\NC\NR +\NC comment \NC any \NC any \NC the arguments of this command are ignored\NC\NR +\stoptabulate + +Here is a rather elaborate glyph commands example: +\starttyping +... +commands = { + {'push'}, -- remember where we are + {'right', 5000}, -- move right about 0.08pt + {'font', 3}, -- select the fonts[3] entry + {'char', 97}, -- place character 97 (ASCII 'a') + {'pop'}, -- go all the way back + {'down', -200000}, -- move upwards by about 3pt + {'special', 'pdf: 1 0 0 rg'} -- switch to red color + {'rule', 500000, 20000} -- draw a bar + {'special','pdf: 0 g'} -- back to black +} +... +\stoptyping + +The default value for \type {font} is always~1 at the start of the \type{commands} array. +Therefore, if the virtual font is essentially only a re|-|encoding, then you do usually not +have create an explicit \quote{font} command in the array. + +Rules inside of \type{commands} arrays are built up using only two dimensions: +they do not have depth. For correct vertical placement, an extra \type{down} command +may be needed. + +Regardless of the amount of movement you create within the \type {commands}, +the output pointer will always move by exactly the width that was given in +the \type {width} key of the character hash. Any movements that take place +inside the \type{commands} array are ignored on the upper level. + +\subsection{Artificial fonts} + +Even in a \quote{real} font, there can be virtual characters. When \LUATEX\ encounters a \type {commands} +field inside a character when it becomes time to typeset the character, it will interpret the commands, just +like for a true virtual character. In this case, if you have created no \quote{fonts} array, then the default +(and only) \quote{base} font is taken to be the current font itself. In practice, this means that you can +create virtual duplicates of existing characters which is useful if you want to create composite characters. + +Note: this feature does {\it not\/} work the other way around. There can not be \quote{real} characters in a +virtual font! You cannot use this technique for font re-encoding either; you need a truly virtual +font for that (because characters that are already present cannot be altered). + +\subsection{Example virtual font} + +Finally, here is a plain \TEX\ input file with a virtual font demonstration: + +\startbuffer +\directlua0 { + callback.register('define_font', + function (name,size) + if name == 'cmr10-red' then + f = font.read_tfm('cmr10',size) + f.name = 'cmr10-red' + f.type = 'virtual' + f.fonts = {{ name = 'cmr10', size = size }} + for i,v in pairs(f.characters) do + if (string.char(i)):find('[tacohanshartmut]') then + v.commands = { + {'special','pdf: 1 0 0 rg'}, + {'char',i}, + {'special','pdf: 0 g'}, + } + else + v.commands = {{'char',i}} + end + end + else + f = font.read_tfm(name,size) + end + return f + end + ) +} + +\font\myfont = cmr10-red at 10pt \myfont This is a line of text \par +\font\myfontx= cmr10 at 10pt \myfontx Here is another line of text \par +\stopbuffer + +\typebuffer + +%\getbuffer + +\chapter[nodes]{Nodes} + +\section{\LUA\ node representation} + +\TEX's nodes are represented in \LUA\ as userdata object with a variable +set of fields. In the following syntax tables, such the type of such a +userdata object is represented as \syntax{}. + + +The current return value of \luatex{node.types()} is: +\ctxlua { + local d = node.types() + tex.print('\\type{' .. d[0] .. '} (' .. 0 .. '), ') + for _,v in pairs(d) do + if _ > 0 then + tex.print('\\type{' .. v .. '} (' .. _ .. '), ') + end + end +} but as already mentioned, the math and alignment nodes +in this list are not supported at the moment. The useful list +is described in the next sections. + +\subsection{Auxiliary items} + +A few node|-|typed userdata objects do not occur in the \quote{normal} +list of nodes, but can be pointed to from within that list. They are +not quite the same as regular nodes, but it is easier for the library +routines to treat them as if they were. + +\subsubsection{glue_spec items} + +Skips are about the only type of data objects in traditional \TEX\ +that are not a simple value. The structure that represents the glue +components of a skip is called a \type {glue_spec}, and it has the following +accessible fields: + +\starttabulate[|lT|l|p|] +\NC \ssbf key \NC \bf type \NC \bf explanation \NC\NR +\NC width \NC number \NC \NC\NR +\NC stretch \NC number \NC \NC\NR +\NC stretch_order \NC number \NC \NC\NR +\NC shrink \NC number \NC \NC\NR +\NC shrink_order \NC number \NC \NC\NR +\stoptabulate + +These objects are reference counted, so there is actually an extra +field named \type {ref_count} as well. This item type will likely +disappear in the future, and the glue fields themselves will +become part of the nodes referencing glue items. + +\subsubsection{attribute\_list and attribute items} + +The newly introduced attribute registers are non|-|trivial, because +the value that is attached to a node is essentially a sparse array of +key|-|value pairs. + +It is generally easiest to deal with attribute lists and attributes +by using the dedicated functions in the \luatex{node} library, but +for completeness, here is the low|-|level interface. + +An \type{attribute_list} item is used as a head pointer for a list +of attribute items. It has only one user-visible field: + +\starttabulate[|lT|l|p|] +\NC \ssbf field \NC \bf type \NC \bf explanation \NC\NR +\NC next \NC \syntax{} \NC pointer to the first attribute\NC\NR +\stoptabulate + +A normal node's attribute field will point to an item of type +\type{attribute_list}, and the \type{next} field in that item will point +to the first defined \quote{attribute} item, whose \type {next} will +point to the second \quote{attribute} item, etc. + +Valid fields in \type{attribute} items: + +\starttabulate[|lT|l|p|] +\NC \ssbf field \NC \bf type \NC \bf explanation \NC\NR +\NC next \NC \syntax{} \NC pointer to the next attribute\NC\NR +\NC number \NC number \NC the attribute type id\NC\NR +\NC value \NC number \NC the attribute value\NC\NR +\stoptabulate + +\subsubsection{action item} + +Valid fields: \showfields{action} + +These are a special kind of item that only appears inside +pdf start link objects. + +\starttabulate[|lT|l|p|] +\NC \ssbf field \NC \bf type \NC \bf explanation \NC\NR +\NC action_type \NC number \NC \NC\NR +\NC action_id \NC number or string \NC \NC\NR +\NC named_id \NC number \NC \NC\NR +\NC file \NC string \NC \NC\NR +\NC new_window \NC number \NC \NC\NR +\NC data \NC string \NC \NC\NR +\NC ref_count \NC number \NC \NC\NR +\stoptabulate + +\subsection{Main text nodes} + +These are the nodes that comprise actual typesetting commands. + +A few fields are present in all nodes regardless of their type, these are: + +\starttabulate[|lT|l|p|] +\NC \ssbf field \NC \bf type \NC \bf explanation \NC\NR +\NC next \NC \syntax{} \NC The next node in a list, or nil\NC\NR +\NC id \NC number \NC The node's type (\type{id}) number \NC\NR +\NC subtype \NC number \NC The node \type{subtype} identifier\NC\NR +\stoptabulate + +The \type{subtype} is sometimes just a stub entry. Not all nodes +actually use the \type{subtype}, but this way you can be sure that all +nodes accept it as a valid field name, and that is often handy in node +list traversal. In the following tables \type{next} and \type{id} are +not explicitly mentioned. + +Besides these three fields, almost all nodes also have an \type {attr} +field, and there is a also a field called \type{prev}. That last field +is always present, but only initialized on explicit request: when the +function \type{node.slide()} is called, it will set up the \type{prev} +fields to be a backwards pointer in the argument node list. + + +\subsubsection{hlist nodes} + +Valid fields: \showfields{hlist} + +\starttabulate[|lT|l|p|] +\NC \ssbf field \NC \bf type \NC \bf explanation \NC\NR +\NC subtype \NC number \NC unused\NC\NR +\NC attr \NC \syntax{} \NC The head of the associated attribute list \NC\NR +\NC width \NC number \NC \NC\NR +\NC height \NC number \NC \NC\NR +\NC depth \NC number \NC \NC\NR +\NC shift \NC number \NC a displacement perpendicular to the + character progression direction \NC\NR +\NC glue_order \NC number \NC a number in the range 0--4, indicating + the glue order\NC\NR +\NC glue_set \NC number \NC the calculated glue ratio\NC\NR +\NC glue_sign \NC number \NC \NC\NR +\NC list \NC \syntax{} \NC the body of this list\NC\NR +\NC dir \NC number \NC the direction of this box\NC\NR +\stoptabulate + +\subsubsection{vlist nodes} + +Valid fields: As for hlist, except that \quote{shift} is a displacement +perpendicular to the line progression direction. + +\subsubsection{rule nodes} + +Valid fields: \showfields{rule} + +\starttabulate[|lT|l|p|] +\NC \ssbf field \NC \bf type \NC \bf explanation \NC\NR +\NC subtype \NC number \NC unused\NC\NR +\NC attr \NC \syntax{} \NC \NC\NR +\NC width \NC number \NC rule size. The special value $-1073741824$ + is used for \quote{running} glue dimensions\NC\NR +\NC height \NC number \NC ' '\NC\NR +\NC depth \NC number \NC ' '\NC\NR +\NC dir \NC number \NC the direction of this rule\NC\NR +\stoptabulate + +\subsubsection{ins nodes} + +Valid fields: \showfields{ins} + +\starttabulate[|lT|l|p|] +\NC \ssbf field \NC \bf type \NC \bf explanation \NC\NR +\NC subtype \NC number \NC the insertion class\NC\NR +\NC attr \NC \syntax{} \NC \NC\NR +\NC cost \NC number \NC the penalty associated with this insert\NC\NR +\NC height \NC number \NC \NC\NR +\NC depth \NC number \NC \NC\NR +\NC list \NC \syntax{} \NC the body of this insert\NC\NR +\NC spec \NC \syntax{} \NC a pointer to the \tex{splittopskip} glue spec\NC\NR +\stoptabulate + +\subsubsection{mark nodes} + +Valid fields: \showfields{mark} + +\starttabulate[|lT|l|p|] +\NC \ssbf field \NC \bf type \NC \bf explanation \NC\NR +\NC subtype \NC number \NC unused\NC\NR +\NC attr \NC \syntax{} \NC \NC\NR +\NC class \NC number \NC the mark class\NC\NR +\NC mark \NC table \NC a table representing a token list\NC\NR +\stoptabulate + +\subsubsection{adjust nodes} + +Valid fields: \showfields{adjust} + +\starttabulate[|lT|l|p|] +\NC \ssbf field \NC \bf type \NC \bf explanation \NC\NR +\NC subtype \NC number \NC 0 = normal, 1 = \quote{pre}\NC\NR +\NC attr \NC \syntax{} \NC \NC\NR +\NC list \NC \syntax{} \NC adjusted material\NC\NR +\stoptabulate + +\subsubsection{disc nodes} + +Valid fields: \showfields{disc} + +\starttabulate[|lT|l|p|] +\NC \ssbf field \NC \bf type \NC \bf explanation \NC\NR +\NC subtype \NC number \NC indicates the source of a discretionary. + 0 = the \tex{discretionary} command, + 1 = the \tex{-} command, + 2 = added automatically following a \type{-}, + 3 = added by the hyphenation algorithm\NC\NR +\NC attr \NC \syntax{} \NC \NC\NR +\NC pre \NC \syntax{} \NC pointer to the pre|-|break text\NC\NR +\NC post \NC \syntax{} \NC pointer to the post|-|break text\NC\NR +\NC replace \NC \syntax{} \NC pointer to the no|-|break text\NC\NR +\stoptabulate + +\subsubsection{math nodes} + +Valid fields: \showfields{math} + +\starttabulate[|lT|l|p|] +\NC \ssbf field \NC \bf type \NC \bf explanation \NC\NR +\NC subtype \NC number \NC 0 = \quote{on}, 1 = \quote{off}\NC\NR +\NC attr \NC \syntax{} \NC \NC\NR +\NC surround \NC number \NC width of the \tex{mathsurround} kern\NC\NR +\stoptabulate + +\subsubsection{glue nodes} + +Valid fields: \showfields{glue} + +\starttabulate[|lT|l|p|] +\NC \ssbf field \NC \bf type \NC \bf explanation \NC\NR +\NC subtype \NC number \NC 0 = \tex{skip}, + 1--18 = internal glue parameters, + 100 = \tex{leaders}, + 101 = \tex{cleaders}, + 102 = \tex{xleaders} \NC\NR +\NC attr \NC \syntax{} \NC \NC\NR +\NC spec \NC \syntax{} \NC pointer to a glue\_spec item \NC\NR +\NC leader \NC \syntax{} \NC pointer to a box or rule for leaders\NC\NR +\stoptabulate + +\subsubsection{kern nodes} + +Valid fields: \showfields{kern} + +\starttabulate[|lT|l|p|] +\NC \ssbf field \NC \bf type \NC \bf explanation \NC\NR +\NC subtype \NC number \NC 0 = from font, + 1 = from \tex{kern} or \tex{/}, + 2 = from \tex{accent}\NC\NR +\NC attr \NC \syntax{} \NC \NC\NR +\NC kern \NC number \NC \NC\NR +\stoptabulate + + +\subsubsection{penalty nodes} + +Valid fields: \showfields{penalty} + +\starttabulate[|lT|l|p|] +\NC \ssbf field \NC \bf type \NC \bf explanation \NC\NR +\NC subtype \NC number \NC not used\NC\NR +\NC attr \NC \syntax{} \NC \NC\NR +\NC penalty \NC number \NC \NC\NR +\stoptabulate + +\subsubsection[glyphnodes]{glyph nodes} + +Valid fields: \showfields{glyph} + +\newbox\mybox +\setbox\mybox=\hbox{\vbox {\hsize=3cm +\starttabulate[|l|l|] +\NC bit 0 \NC character \NC\NR +\NC bit 1 \NC glyph \NC\NR +\NC bit 2 \NC ligature \NC\NR +\NC bit 3 \NC ghost \NC\NR +\NC bit 4 \NC left \NC\NR +\NC bit 5 \NC right \NC\NR +\stoptabulate +}} + +\starttabulate[|lT|l|p|] +\NC \ssbf field\NC \ssbf type \NC \ssbf explanation \NC\NR +\NC subtype \NC number \NC bitfield, with bits:\crlf + \copy\mybox\NC\NR +\NC attr \NC \syntax{} \NC \NC\NR +\NC char \NC number \NC \NC\NR +\NC font \NC number \NC \NC\NR +\NC lang \NC number \NC \NC\NR +\NC left \NC number \NC \NC\NR +\NC right \NC number \NC \NC\NR +\NC uchyph \NC boolean \NC \NC\NR +\NC components \NC \syntax{} \NC pointer to ligature components\NC\NR +\NC xoffset \NC number \NC \NC\NR +\NC yoffset \NC number \NC \NC\NR +\stoptabulate + +See \in{section}[charsandglyphs] for a detailed description of the +\type{subtype} field. + +\subsubsection{margin\_kern nodes} + +Valid fields: \showfields{margin_kern} + +\starttabulate[|lT|l|p|] +\NC \ssbf field \NC \bf type \NC \bf explanation \NC\NR +\NC subtype \NC number \NC 0 = left side, + 1 = right side\NC\NR +\NC attr \NC \syntax{} \NC \NC\NR +\NC width \NC number \NC \NC\NR +\NC glyph \NC \syntax{} \NC \NC\NR +\stoptabulate + +\subsection{whatsit nodes} + +Whatsit nodes come in many subtypes that you can ask for by running +\luatex{node.whatsits()}: +\ctxlua {for _,v in pairs(node.whatsits()) do +tex.print('\\type{' .. v .. '} (' .. _ .. '), ') end } + +\subsubsection{open nodes} + +Valid fields: \showfields{whatsit,open} + +\starttabulate[|lT|l|p|] +\NC \ssbf field \NC \bf type \NC \bf explanation \NC\NR +\NC attr \NC \syntax{} \NC \NC\NR +\NC stream \NC number \NC \TEX's stream id number\NC\NR +\NC name \NC string \NC file name \NC\NR +\NC ext \NC string \NC file extension \NC\NR +\NC area \NC string \NC file area \NC\NR +\stoptabulate + +\subsubsection{write nodes} + +Valid fields: \showfields{whatsit,write} + +\starttabulate[|lT|l|p|] +\NC \ssbf field \NC \bf type \NC \bf explanation \NC\NR +\NC attr \NC \syntax{} \NC \NC\NR +\NC stream \NC number \NC \TEX's stream id number\NC\NR +\NC data \NC table \NC a table representing the token list to be written\NC\NR +\stoptabulate + +\subsubsection{close nodes} + +Valid fields: \showfields{whatsit,close} + +\starttabulate[|lT|l|p|] +\NC \ssbf field \NC \bf type \NC \bf explanation \NC\NR +\NC attr \NC \syntax{} \NC \NC\NR +\NC stream \NC number \NC \TEX's stream id number\NC\NR +\stoptabulate + +\subsubsection{special nodes} + +Valid fields: \showfields{whatsit,special} + +\starttabulate[|lT|l|p|] +\NC \ssbf field \NC \bf type \NC \bf explanation \NC\NR +\NC attr \NC \syntax{} \NC \NC\NR +\NC data \NC string \NC the \tex{special} information\NC\NR +\stoptabulate + +\subsubsection{language nodes} + + +\LUATEX\ does not have language whatsits any more. All language +information is already present inside the glyph nodes themselves. +This whatsit subtype will be removed in the next release. + + +\subsubsection{local_par nodes} + +Valid fields: \showfields{whatsit,local_par} + +\starttabulate[|lT|l|p|] +\NC \ssbf field \NC \bf type \NC \bf explanation \NC\NR +\NC attr \NC \syntax{} \NC \NC\NR +\NC pen_inter \NC number \NC interline penalty\NC\NR +\NC pen_broken\NC number \NC broken penalty\NC\NR +\NC dir \NC number \NC the direction of this par\NC\NR +\NC box_left \NC \syntax{} \NC the \tex{localleftbox}\NC\NR +\NC box_left_width\NC number\NC width of the \tex{localleftbox}\NC\NR +\NC box_right \NC \syntax{} \NC the \tex{localrightbox}\NC\NR +\NC box_right_width\NC number\NC width of the \tex{localrightbox}\NC\NR +\stoptabulate + +\subsubsection{dir nodes} + +Valid fields: \showfields{whatsit,dir} + +\starttabulate[|lT|l|p|] +\NC \ssbf field \NC \bf type \NC \bf explanation \NC\NR +\NC attr \NC \syntax{} \NC \NC\NR +\NC dir \NC number \NC the direction\NC\NR +\NC level \NC number \NC nesting level of this direction whatsit\NC\NR +\NC dvi_ptr \NC number \NC a saved dvi buffer byte offset\NC\NR +\NC dir_h \NC number \NC a saved dvi position\NC\NR +\stoptabulate + +\subsubsection{pdf_literal nodes} + +Valid fields: \showfields{whatsit,pdf_literal} + +\starttabulate[|lT|l|p|] +\NC \ssbf field \NC \bf type \NC \bf explanation \NC\NR +\NC attr \NC \syntax{} \NC \NC\NR +\NC mode \NC number \NC the \quote{mode} setting of this literal\NC\NR +\NC data \NC string \NC the \tex{pdfliteral} information\NC\NR +\stoptabulate + +\subsubsection{pdf_refobj nodes} + +Valid fields: \showfields{whatsit,pdf_refobj} + +\starttabulate[|lT|l|p|] +\NC \ssbf field \NC \bf type \NC \bf explanation \NC\NR +\NC attr \NC \syntax{} \NC \NC\NR +\NC objnum \NC number \NC the referenced \PDF\ object number\NC\NR +\stoptabulate + +\subsubsection{pdf_refxform nodes} + +Valid fields: \showfields{whatsit,pdf_refxform}. + +\starttabulate[|lT|l|p|] +\NC \ssbf field \NC \bf type \NC \bf explanation \NC\NR +\NC attr \NC \syntax{} \NC \NC\NR +\NC width \NC number \NC \NC \NR +\NC height \NC number \NC \NC \NR +\NC depth \NC number \NC \NC \NR +\NC objnum \NC number \NC the referenced \PDF\ object number\NC\NR +\stoptabulate + +Be aware that \type{pdf_refxform} nodes have dimensions that are used by \LUATEX. + +\subsubsection{pdf_refximage nodes} + +Valid fields: \showfields{whatsit,pdf_refximage} + +\starttabulate[|lT|l|p|] +\NC \ssbf field \NC \bf type \NC \bf explanation \NC\NR +\NC attr \NC \syntax{} \NC \NC\NR +\NC width \NC number \NC \NC \NR +\NC height \NC number \NC \NC \NR +\NC depth \NC number \NC \NC \NR +\NC objnum \NC number \NC the referenced \PDF\ object number\NC\NR +\stoptabulate + +Be aware that \type{pdf_refximage} nodes have dimensions that are used by \LUATEX. + +\subsubsection{pdf_annot nodes} + +Valid fields: \showfields{whatsit,pdf_annot} + +\starttabulate[|lT|l|p|] +\NC \ssbf field \NC \bf type \NC \bf explanation \NC\NR +\NC attr \NC \syntax{} \NC \NC\NR +\NC width \NC number \NC \NC \NR +\NC height \NC number \NC \NC \NR +\NC depth \NC number \NC \NC \NR +\NC objnum \NC number \NC the referenced \PDF\ object number\NC\NR +\NC data \NC string \NC the annotation data\NC\NR +\stoptabulate + + +\subsubsection{pdf_start_link nodes} + +Valid fields: \showfields{whatsit,pdf_start_link} + +\starttabulate[|lT|l|p|] +\NC \ssbf field \NC \bf type \NC \bf explanation \NC\NR +\NC attr \NC \syntax{} \NC \NC\NR +\NC width \NC number \NC \NC \NR +\NC height \NC number \NC \NC \NR +\NC depth \NC number \NC \NC \NR +\NC objnum \NC number \NC the referenced \PDF\ object number\NC\NR +\NC link_attr \NC table \NC the link attribute token list\NC\NR +\NC action \NC \syntax{} \NC the action to perform\NC\NR +\stoptabulate + +\subsubsection{pdf_end_link nodes} + +Valid fields: \showfields{whatsit,pdf_end_link} + +\starttabulate[|lT|l|p|] +\NC \ssbf field \NC \bf type \NC \bf explanation \NC\NR +\NC attr \NC \syntax{} \NC \NC\NR +\stoptabulate + +\subsubsection{pdf_dest nodes} + +Valid fields: \showfields{whatsit,pdf_dest} + +\starttabulate[|lT|l|p|] +\NC \ssbf field \NC \bf type \NC \bf explanation \NC\NR +\NC attr \NC \syntax{} \NC \NC\NR +\NC width \NC number \NC \NC \NR +\NC height \NC number \NC \NC \NR +\NC depth \NC number \NC \NC \NR +\NC named_id \NC number \NC is the dest_id a string value?\NC\NR +\NC dest_id \NC number or string \NC the destination id\NC\NR +\NC dest_type \NC number\NC type of destination\NC\NR +\NC xyz_zoom \NC number\NC \NC\NR +\NC objnum \NC number \NC the \PDF\ object number\NC\NR +\stoptabulate + +\subsubsection{pdf_thread nodes} + +Valid fields: \showfields{whatsit,pdf_thread} + +\starttabulate[|lT|l|p|] +\NC \ssbf field \NC \bf type \NC \bf explanation \NC\NR +\NC attr \NC \syntax{} \NC \NC\NR +\NC width \NC number \NC \NC \NR +\NC height \NC number \NC \NC \NR +\NC depth \NC number \NC \NC \NR +\NC named_id \NC number \NC is the tread_id a string value?\NC\NR +\NC tread_id \NC number or string \NC the thread id\NC\NR +\NC thread_attr\NC number \NC extra thread information\NC\NR +\stoptabulate + +\subsubsection{pdf_start_thread nodes} + +Valid fields: \showfields{whatsit,pdf_start_thread} + +\starttabulate[|lT|l|p|] +\NC \ssbf field \NC \bf type \NC \bf explanation \NC\NR +\NC attr \NC \syntax{} \NC \NC\NR +\NC width \NC number \NC \NC \NR +\NC height \NC number \NC \NC \NR +\NC depth \NC number \NC \NC \NR +\NC named_id \NC number \NC is the tread_id a string value?\NC\NR +\NC tread_id \NC number or string \NC the thread id\NC\NR +\NC thread_attr\NC number \NC extra thread information\NC\NR +\stoptabulate + +\subsubsection{pdf_end_thread nodes} + +Valid fields: \showfields{whatsit,pdf_end_thread} + +\starttabulate[|lT|l|p|] +\NC \ssbf field \NC \bf type \NC \bf explanation \NC\NR +\NC attr \NC \syntax{} \NC \NC\NR +\stoptabulate + +\subsubsection{pdf_save_pos nodes} + +Valid fields: \showfields{whatsit,pdf_save_pos} + +\starttabulate[|lT|l|p|] +\NC \ssbf field \NC \bf type \NC \bf explanation \NC\NR +\NC attr \NC \syntax{} \NC \NC\NR +\stoptabulate + +\subsubsection{late_lua nodes} + +Valid fields: \showfields{whatsit,late_lua} + +\starttabulate[|lT|l|p|] +\NC \ssbf field \NC \bf type \NC \bf explanation \NC\NR +\NC attr \NC \syntax{} \NC \NC\NR +\NC reg \NC number \NC \LUA\ state id number \NC\NR +\NC data \NC string \NC data to execute\NC\NR +\stoptabulate + +\subsubsection{close_lua nodes} + +Valid fields: \showfields{whatsit,close_lua} + +\starttabulate[|lT|l|p|] +\NC \ssbf field \NC \bf type \NC \bf explanation \NC\NR +\NC attr \NC \syntax{} \NC \NC\NR +\NC reg \NC number \NC \LUA\ state id number\NC\NR +\stoptabulate + +\subsubsection{pdf_colorstack nodes} + +Valid fields: \showfields{whatsit,pdf_colorstack} + +\starttabulate[|lT|l|p|] +\NC \ssbf field \NC \bf type \NC \bf explanation \NC\NR +\NC attr \NC \syntax{} \NC \NC\NR +\NC stack \NC number \NC colorstack id number\NC\NR +\NC cmd \NC number \NC command to execute\NC\NR +\NC data \NC string \NC data\NC\NR +\stoptabulate + +\subsubsection{pdf_setmatrix nodes} + +Valid fields: \showfields{whatsit,pdf_setmatrix} + +\starttabulate[|lT|l|p|] +\NC \ssbf field \NC \bf type \NC \bf explanation \NC\NR +\NC attr \NC \syntax{} \NC \NC\NR +\NC data \NC string \NC data\NC\NR +\stoptabulate + +\subsubsection{pdf_save nodes} + +Valid fields: \showfields{whatsit,pdf_save} + +\starttabulate[|lT|l|p|] +\NC \ssbf field \NC \bf type \NC \bf explanation \NC\NR +\NC attr \NC \syntax{} \NC \NC\NR +\stoptabulate + +\subsubsection{pdf_restore nodes} + +Valid fields: \showfields{whatsit,pdf_restore} + +\starttabulate[|lT|l|p|] +\NC \ssbf field \NC \bf type \NC \bf explanation \NC\NR +\NC attr \NC \syntax{} \NC \NC\NR +\stoptabulate + +\subsubsection{user_defined nodes} + +User-defined whatsit nodes can only be created and handled from Lua +code. In effect, they are an extension to the extension +mechanism. The \LUATEX\ engine will simply step over such whatsits +without ever looking at the contents. + +Valid fields: \showfields{whatsit,user_defined} + +\starttabulate[|lT|l|p|] +\NC \ssbf field \NC \bf type \NC \bf explanation \NC\NR +\NC attr \NC \syntax{} \NC \NC\NR +\NC user_id \NC number \NC id number\NC\NR +\NC type \NC number \NC type of the value\NC\NR +\NC value \NC number \NC \NC\NR +\NC \NC string \NC \NC\NR +\NC \NC \syntax{} \NC \NC\NR +\NC \NC table \NC \NC\NR +\stoptabulate + +The \type{type} can have one of five distinct values: + +\starttabulate[|lT|l|p|] +\NC \ssbf value \NC \bf explanation \NC\NR +\NC 97 \NC the value is an attribute node list \NC\NR +\NC 100 \NC the value is a number \NC\NR +\NC 110 \NC the value is a node list \NC\NR +\NC 115 \NC the value is a token list in string form\NC\NR +\NC 116 \NC the value is a token list in lua table form\NC\NR +\stoptabulate + + +\chapter{Modifications} + +Besides the expected changes caused by new functionality, there are a +number of not|-|so|-|expected changes. These are sometimes a side|-|effect +of a new (conflicting) feature, or, more often than not, a change +necessary to clean up the internal interfaces. + +\section{Changes from \TEX\ 3.141592} + +\startitemize + +\item See~\in{chapter}[languages] for many small changes related to paragraph + building, language handling, and hyphenation. + +\item There is no pool file, all strings are embedded during compilation. + +\item \type {plus 1 fillll} does not generate an error. The extra \quote{l} is +simply typeset. + +\item The \tex{endlinechar} can be either added (values 0 or more), or not +(negative values). If it is added, the character is always decimal 13 a/k/a +\type{^^M} a/k/a carriage return (This change may be temporary). + +\item The banner line and the statistics messages are different, as +well as many warnings and error texts. + +\stopitemize + +\section{Changes from \ETEX\ 2.2} + +\startitemize + +\item The \ETEX\ functionality is always present and enabled + (but see below about \TEXXET), so the prepended asterisk or + \type{-etex} switch for \INITEX\ is not needed. + +\item \TEXXET\ is not present, so the primitives + +\starttyping +\TeXXeTstate +\beginR +\beginL +\endR +\endL +\stoptyping + +are missing. + +\item Some of the tracing information that is output by \ETEX's \tex{tracingassigns} and + \tex{tracingrestores} is not there. + +\item Register management in \LUATEX\ uses the \ALEPH\ model, so the maximum value is 65535 + and the implementation uses a flat array instead of the mixed + flat|\&|sparse model from \ETEX. + +\item \type{savinghyphcodes} is a no-op and may possibly be removed. + See~\in{chapter}[languages] for details. + +\stopitemize + +\section{Changes from \PDFTEX\ 1.40} + +\startitemize + +\item The (experimental) support for snap nodes has been removed, because +it is much more natural to build this functionality on top of node +processing and attributes. The associated primitives that are now gone +are: \tex{pdfsnaprefpoint}, \tex{pdfsnapy}, and \tex{pdfsnapycomp}. + +\item The (experimental) support for specialized spacing around nodes +has also been removed. The associated primitives that are now gone are: +\tex{pdfadjustinterwordglue}, \tex{pdfprependkern}, and \tex{pdfappendkern}, +as well as the five supporting primitives \tex{knbscode}, \tex{stbscode}, +\tex{shbscode}, \tex{knbccode}, and \tex{knaccode}. + + + +\item A number of \quote{utility functions} is removed: + +\startcolumns[n=3] +\starttyping +\pdfelapsedtime +\pdfescapehex +\pdfescapename +\pdfescapestring +\pdffiledump +\pdffilemoddate +\pdffilesize +\pdflastmatch +\pdfmatch +\pdfmdfivesum +\pdfresettimer +\pdfshellescape +\pdfstrcmp +\pdfunescapehex +\stoptyping +\stopcolumns + +\item A few other experimental primitives are also provided without the + extra \luatex {pdf} prefix, so they can also be called like this: + +\startcolumns[n=3] +\starttyping +\primitive +\ifprimitive +\ifabsnum +\ifabsdim +\stoptyping +\stopcolumns + +\item The definitions for new didot and new cicero are patched. + +\item The \tex{pdfprimitive} is bugfixed. + +\item The \tex{pdftexversion} is set to 200. + +\stopitemize + +\section{Changes from \ALEPH\ RC4} + +\startitemize + +\item The input translations from \ALEPH\ are not implemented, the + related primitives are not available: + +\startcolumns[n=2] +\starttyping +\DefaultInputMode +\noDefaultInputMode +\noInputMode +\InputMode +\DefaultOutputMode +\noDefaultOutputMode +\noOutputMode +\OutputMode +\DefaultInputTranslation +\noDefaultInputTranslation +\noInputTranslation +\InputTranslation +\DefaultOutputTranslation +\noDefaultOutputTranslation +\noOutputTranslation +\OutputTranslation +\stoptyping +\stopcolumns + +\item A small series of bounds checking fixes to \tex{ocp} and + \tex{ocplist} has been added to prevent the system from crashing + due to array indexes running out of bounds. + +\item The \tex{hoffset} bug when \tex{pagedir TRT} is fixed, +removing the need for an explicit fix to \tex{hoffset} + +\item A bug causing \tex{fam} to fail for family numbers above + 15 is fixed. + +\item Some bits of \ALEPH\ assumed \type{0} and \type{null} were identical. +This resulted for instance in a bug that sometimes caused an eternal +loop when trying to \tex{show} a box. + +\item A fair amount of other minor bugs are fixed as well, most of these +related to \tex{tracingcommands} output. + +\item The number of possible fonts, ocps and ocplists is +smaller than their maximum \ALEPH\ value (around 5000 fonts and +30000 ocps / ocplists). + +\item The internal function \type{scan_dir()} has been renamed to +\type{scan_direction()} to prevent a naming clash. + +\item The \type{^^} notation can come in five and six item repetitions also, to +insert characters that do not fit in the BMP. + +\item Glues {\it immediately after} direction change commands are not +legal breakpoints. + +\item The \tex{ocp} and \tex{ocplist} statistics at the end of a run +are only printed if OCP's are actually used. + +\stopitemize + +\section{Changes from standard \WEBC} + +\startitemize + +\item There is no mltex + +\item There is no enctex + +\item The following commandline switches are silently ignored, even +in non|-|\LUA\ mode: + +\starttyping +-8bit +-translate-file=TCXNAME +-mltex +-enc +-etex +\stoptyping + +\item \tex{openout} whatsits are not written to the log file. + +\item Some of the so|-|called web2c extensions are hard to set up + in non|-|\KPSE\ mode because texmf.cnf is not read: \type{shell-escape} + is off (but that is not a problem because of \LUA's + \lua{os.execute}), and the paranoia checks on \type{openin} and + \type{openout} do not happen (however, it is easy for a \LUA\ script + to do this itself by overloading \lua{io.open}). + + +\stopitemize + +\chapter{Implementation notes} + +\section{Primitives overlap} + +The primitives + +\starttabulate[|l|l|] +\NC \tex{pdfpagewidth} \NC \tex{pagewidth} \NC \NR +\NC \tex{pdfpageheight}\NC \tex{pageheight} \NC \NR +\NC \tex{fontcharwd} \NC \tex{charwd} \NC \NR +\NC \tex{fontcharht} \NC \tex{charht} \NC \NR +\NC \tex{fontchardp} \NC \tex{chardp} \NC \NR +\NC \tex{fontcharic} \NC \tex{charic} \NC \NR +\stoptabulate + +are all aliases of each other. + +\section{Memory allocation} + +The single internal memory heap that traditional \TEX\ used for tokens +and nodes is split into two separate arrays. Each of these will grow +dynamically when needed. + +The \type{texmf.cnf} settings related to main memory are no longer +used (these are: \type{main_memory}, \type{mem_bot}, +\type{extra_mem_top} and \type{extra_mem_bot}). \quote{Out of main +memory} errors can still occur, but the limiting factor is now the +amount of RAM in your system, not a predefined limit. + +Also, the memory (de)allocation routines for nodes are completely +rewritten. The relevant code now lives in the C file \type{luanode.c}, +and basically uses a dozen or so avail lists instead of a +doubly|-|linked model. An extra function layer is added so that the +code can ask for nodes by type instead of directly requisitioning +a certain amount of memory words. + +Because of the split into two arrays and the resulting differences in +the data structures, some of the Pascal \WEB\ macros have been +duplicated. For instance, there are now \type{vlink} and \type{vinfo} +as well as \type{link} and \type{info}. All access to the variable +memory array is now hidden behind a macro called \type{vmem}. + +The implementation of the growth of two arrays (via reallocation) +introduces a potential pitfall: the memory arrays should never be used +as the left hand side of a statement that can modify the array in +question. + +The input line buffer and pool size are now also reallocated when +needed, and the \type{texmf.cnf} settings \type{buf_size} and +\type{pool_size} are silently ignored. + +\section{Sparse arrays} + +The \tex{mathcode}, \tex{delcode}, \tex{catcode}, +\tex{sfcode}, \tex{lccode} and \tex{uccode} tables are now +sparse arrays that are implemented in~C. They are no longer part of +the \TEX\ \quote{equivalence table} and because each had 1.1 million +entries with a few memory words each, this makes a major difference +in memory usage. + +These assignments do not yet show up when using the etex tracing +routines \tex{tracingassigns} and \tex{tracingrestores} (code +simply not written yet). + +A side|-|effect of the current implementation is that \tex{global} is +now more expensive in terms of processing than non|-|global assignments. + +See \type{mathcodes.c} and \type{textcodes.c} if you are interested in +the details. + +Also, the glyph ids within a font are now managed by means +of a sparse array and glyph ids can go up to index $2^{21}-1$. + +\section{Simple single-character csnames} + +Single|-|character commands are no longer treated specially in the +internals, they are stored in the hash just like the multiletter +csnames. + +The code that displays control sequences explicitly checks if +the length is one when it has to decide whether or not to add a +trailing space. + +\section{Compressed format} + +The format is passed through zlib, allowing it to shrink to roughly +half of the size it would have had in uncompressed form. This takes a +bit more CPU cycles but much less disk I/O, so it should still be +faster. + +\section{Binary file reading} + +All of the internal code is changed in such a way that if one of the +\type{read_xxx_file} callbacks is not set, then the file is read by +a C function using basically the same convention as the callback: a +single read into a buffer big enough to hold the entire file +contents. While this uses more memory than the previous code (that +mostly used \type{getc} calls), it can be quite a bit faster +(depending on your I/O subsystem). + +\chapter{Known bugs and limitations} + +The bugs below are going to be fixed eventually. + +The top ones will be fixed soon, but in the later items either the +actual problem is hard to find, or the code that causes the bug is +going to be replaced by a new subsystem soon anyway, or it may not +be worth the hassle and the limitations will eventually be documented. + +\startitemize + +\item The current linebreaking implementation does not yet take all +possible breakpoints into account where ligatures are involved in +the process. This means that line breaks may change in future +versions. + +\item Sometimes font loading via fontforge generates a message like this +\starttyping +Bad call to gww_iconv_open, neither arg is UCS4 (EUC-CN->UTF-8) +\stoptyping +during font loading. This is a limitation of the internal iconv +implementation. + +\item Font expansion does not work quite as it should. On the mailing +list (sep 21), Jonathan Sauer posted a very nice test file along with +an explanation. + +\item \luatex{tex.print()} and \luatex{tex.sprint()} do not work if +\tex{directlua} is used in an \OTP\ file (in the output of an +\type{expression} rule). + +\item Handling of attributes in math mode is not complete. The data +structures in math mode are quite different from those in text mode, +so this will take some extra effort to implement correctly. + +\item When used inside \type{\directlua}, \type{pdf.print()} should create a +literal node instead of flushing immediately. + +\item At the moment, only characters in plane~0 and plane~1 can be +assigned catcode~13 (i.\,e.\ turned into active characters). This is a +temporary measure to reduce the memory requirements of \LUATEX. In +general, \LUATEX's memory footprint is a bit larger that we would +like (with \type{plain.fmt} preloaded it needs about 55MB). + +\item Not all of \ALEPH's direction commands are handled properly in +\PDF\ mode, and especially the vertical scripts support is missing +almost completely (only TRT and TLT are routinely tested). + +\item Letter spacing (\tex{letterspacefont}) is currently non|-|functional +due to massive changes in the virtual font handling. This +functionality may actually be removed completely in the future, +because it is straightforward to set up letterspacing using the \LUA\ +\quote{define_font} interface. + +\item Node pointers are not always checked for validity, so if you make a +mistake in the node list processing, \LUATEX\ may terminate itself with an +assertion error or \quote{Emergency stop}. + +\item In \DVI\ generation mode, using a \type{\textdir} switch inside the +preamble of a \type{\halign} results in overprinted text in the \DVI\ file, +because the column width is not taken into account during the final +placement phase (this is a bug inherited from \ALEPH). Also, \ALEPH\ +apparently dislikes having more than one non-grouped \type{\textdir} +command in a single lined paragraph. + +\item Certain constructs in math mode leak memory nodes. + +\stopitemize + + +\chapter{TODO} + +On top of the \quote{normal} extensions that are planned, there are +some more specific small feature requests. Whether these will all be +included is not certain yet, (and new requests are welcome). + +\startitemize + +\item Implement the \TEX\ primitive \tex{dimension}, cf.\ \tex{number}. + +\item Change the \LUA\ table \type{tex.dimen} to accept and return float +values instead of strings. + +\item Do something about \tex{withoutpt} and/or a new register type \tex{real}? + +\item Create callback for the automatic creation of missing +characters in fonts. + +\item Implement the \TEX\ primitive \tex{htdp}? + +\item Do boxes with dual baselines. + +\item A way to (re?)calculate the width of a \tex{vbox}, taking only +the natural width of the included items into account. + +\item Make the number of the output box configurable. + +\item Complete the attributes in math and switch all the nodes to a double|-|linked list. + +\item Finish the interface from Lua to \TeX's internals, specially the hash and +equivalence table (a small subpart is implementing \type{\csname} +lookups for \type{tex.box} access). + +\item Use of Type1C for embedded PostScript font subsets in +traditional 8-bit encodings. + +\item Support font reencoding of 8-bit fonts via char index instead of +via map files. + +\item Attempt to parse OFM level~0 fonts that are masquerading as level~1. + +\item Add line numbers and input context information to the lua errors. +\stopitemize + +\stoptext -- cgit v1.2.3