diff options
| author | Karl Berry <karl@freefriends.org> | 2009-09-26 23:23:37 +0000 |
|---|---|---|
| committer | Karl Berry <karl@freefriends.org> | 2009-09-26 23:23:37 +0000 |
| commit | be069a8171e0e5028a8893ee64753dd07b4f1180 (patch) | |
| tree | 637af89dff9e6ff0c218a813b7cbbef5e7d13347 /Master/texmf-dist/source/luatex | |
| parent | 4e17af35bf2cf25beac93a51cfe56c026cf72eb0 (diff) | |
luatextra 0.94 update (26sep09)
git-svn-id: svn://tug.org/texlive/trunk@15473 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source/luatex')
5 files changed, 963 insertions, 426 deletions
diff --git a/Master/texmf-dist/source/luatex/luatextra/Makefile b/Master/texmf-dist/source/luatex/luatextra/Makefile index 771b5085219..766e9756e20 100644 --- a/Master/texmf-dist/source/luatex/luatextra/Makefile +++ b/Master/texmf-dist/source/luatex/luatextra/Makefile @@ -12,7 +12,8 @@ UNPACKED_MCB = luamcallbacks-test.tex luamcallbacks.lua UNPACKED_TEXTRA = luatextra-latex.tex luatextra.lua luatextra.sty UNPACKED = $(UNPACKED_EXTRA) $(UNPACKED_MCB) $(UNPACKED_TEXTRA) COMPILED = $(DOC_DTX) $(DOC_TEX) -GENERATED = $(UNPACKED) $(COMPILED) +# $(DOC_TEX) has a compiled version in the repository +GENERATED = $(UNPACKED) $(DOC_DTX) SOURCE = $(DTX) $(SRC_TEX) README Makefile # Files grouped by installation location @@ -22,14 +23,14 @@ SRCFILES = $(DTX) $(SRC_TEX) Makefile # The following definitions should be equivalent # ALL_FILES = $(RUNFILES) $(DOCFILES) $(SRCFILES) -ALL_FILES = $(GENERATED) $(SOURCE) +ALL_FILES = $(GENERATED) $(SOURCE) $(DOC_TEX) # Installation locations FORMAT = luatex -RUNDIR = $(TEXMF)/tex/$(FORMAT)/$(NAME) -DOCDIR = $(TEXMF)/doc/$(FORMAT)/$(NAME) -SRCDIR = $(TEXMF)/source/$(FORMAT)/$(NAME) -TEXMF = ./texmf +RUNDIR = $(TEXMFROOT)/tex/$(FORMAT)/$(NAME) +DOCDIR = $(TEXMFROOT)/doc/$(FORMAT)/$(NAME) +SRCDIR = $(TEXMFROOT)/source/$(FORMAT)/$(NAME) +TEXMFROOT = ./texmf CTAN_ZIP = $(NAME).zip TDS_ZIP = $(NAME).tds.zip @@ -40,7 +41,7 @@ DO_PDFLATEX = pdflatex --interaction=batchmode $< >/dev/null DO_PDFLUALATEX = pdflualatex --interaction=batchmode $< >/dev/null DO_MAKEINDEX = makeindex -s gind.ist $(subst .dtx,,$<) >/dev/null 2>&1 -all: $(GENERATED) +all: $(GENERATED) $(DOC_TEX) doc: $(COMPILED) unpack: $(UNPACKED) ctan: $(CTAN_ZIP) @@ -78,18 +79,18 @@ define run-install @mkdir -p $(SRCDIR) && cp $(SRCFILES) $(SRCDIR) endef -$(TDS_ZIP): TEXMF=./tmp-texmf +$(TDS_ZIP): TEXMFROOT=./tmp-texmf $(TDS_ZIP): $(ALL_FILES) @echo "Making TDS-ready archive $@." @$(RM) -- $@ $(run-install) - @cd $(TEXMF) && zip -9 ../$@ -r . >/dev/null - @$(RM) -r -- $(TEXMF) + @cd $(TEXMFROOT) && zip -9 ../$@ -r . >/dev/null + @$(RM) -r -- $(TEXMFROOT) .PHONY: install manifest clean mrproper install: $(ALL_FILES) - @echo "Installing in '$(TEXMF)'." + @echo "Installing in '$(TEXMFROOT)'." $(run-install) manifest: diff --git a/Master/texmf-dist/source/luatex/luatextra/luaextra.dtx b/Master/texmf-dist/source/luatex/luatextra/luaextra.dtx index cb95dd882d5..51b2835c403 100644 --- a/Master/texmf-dist/source/luatex/luatextra/luaextra.dtx +++ b/Master/texmf-dist/source/luatex/luatextra/luaextra.dtx @@ -53,7 +53,8 @@ and the derived file luaextra.lua. \endpreamble -% The following hacks are to generate a lua file with lua comments starting by -- instead of %% +% The following hacks are to generate a lua file with lua comments starting by +% -- instead of %% \def\MetaPrefix{-- } @@ -125,20 +126,39 @@ and the derived file luaextra.lua. % \maketitle % % \begin{abstract} -% Additional lua functions taken from the libs of Con\TeX t. For an introduction on this package (among others), please refer to the document \texttt{luatex-reference.pdf}. +% Additional lua functions taken from the libs of Con\TeX t. For an +% introduction on this package (among others), please refer to the document +% \texttt{luatex-reference.pdf}. % \end{abstract} % % \section{Overview} % -% Lua is a very minimal language, and it does not have a lot of built-in functions. Some functions will certainly be needed by a lot of packages. Instead of making each of them implement these functions, the aim of this file is to provide a minimal set of functions. All functions are taken from Con\TeX t libraries. -% -% There are some differences with the Con\TeX t funtions though, especially on names: for example the \texttt{file.*} funtions are renamed in \texttt{fpath.*}. It seems more logical as they deal with file paths, not files. Also the \texttt{file.is\_readable} and \texttt{file.is\_writable} are renamed \texttt{lfs.is\_readable} and \texttt{lfs.is\_writable}. -% -% If you use a function you think is missing in this file, please tell the maintainer. -% -% \texttt{Warning:} Even if the names will certainly remain the same, some implementations may differ, and some functions might appear or dissapear. As Lua\TeX\ is not stable, this file is not neither. -% -% All functions are described in this document, but the one of the functions you'll use most will certainly be \texttt{table.serialize} (also named \texttt{table.tostring}) that takes a table and returns an intented string describing the table. It describes the table so that Lua\TeX\ can read it again as a table. You can do a lot of things with this functions, like printing a table for debugging, or saving a table into a file. Functions are also converted into bytecode to be saved. +% Lua is a very minimal language, and it does not have a lot of built-in +% functions. Some functions will certainly be needed by a lot of packages. +% Instead of making each of them implement these functions, the aim of this +% file is to provide a minimal set of functions. All functions are taken from +% Con\TeX t libraries. +% +% There are some differences with the Con\TeX t funtions though, especially on +% names: for example the \texttt{file.*} funtions are renamed in +% \texttt{fpath.*}. It seems more logical as they deal with file paths, not +% files. Also the \texttt{file.is\_readable} and \texttt{file.is\_writable} +% are renamed \texttt{lfs.is\_readable} and \texttt{lfs.is\_writable}. +% +% If you use a function you think is missing in this file, please tell the +% maintainer. +% +% \texttt{Warning:} Even if the names will certainly remain the same, some +% implementations may differ, and some functions might appear or dissapear. As +% Lua\TeX\ is not stable, this file is not neither. +% +% All functions are described in this document, but the one of the functions +% you'll use most will certainly be \texttt{table.serialize} (also named +% \texttt{table.tostring}) that takes a table and returns an intented string +% describing the table. It describes the table so that Lua\TeX\ can read it +% again as a table. You can do a lot of things with this functions, like +% printing a table for debugging, or saving a table into a file. Functions are +% also converted into bytecode to be saved. % % \section{\texttt{luaextra.lua}} % @@ -162,9 +182,10 @@ do end % \end{macrocode} % -% \begin{macro}{string:stripspaces} +% \begin{macro}{string:stripspaces} % -% A function to strip the spaces at the beginning and at the end of a string. +% A function to strip the spaces at the beginning and at the end of a +% string. % % \begin{macrocode} @@ -174,9 +195,11 @@ end % \end{macrocode} % -% \end{macro}\begin{macro}{string.is boolean} +% \end{macro} +% \begin{macro}{string.is boolean} % -% If the argument is a string describing a boolean, this function returns the boolean, otherwise it retuns nil. +% If the argument is a string describing a boolean, this function returns +% the boolean, otherwise it retuns nil. % % \begin{macrocode} @@ -193,9 +216,10 @@ end % \end{macrocode} % -% \end{macro}\begin{macro}{string.is number} +% \end{macro} +% \begin{macro}{string.is number} % -% Returns true if the argument string is a number. +% Returns true if the argument string is a number. % % \begin{macrocode} @@ -205,9 +229,11 @@ end % \end{macrocode} % -% \end{macro}\begin{macro}{lpeg.space and lpeg.newline} +% \end{macro} +% \begin{macro}{lpeg.space and lpeg.newline} % -% Two small helpers for \texttt{lpeg}, that will certainly be widely used: spaces and newlines. +% Two small helpers for \texttt{lpeg}, that will certainly be widely used: +% spaces and newlines. % % \begin{macrocode} @@ -216,15 +242,17 @@ lpeg.newline = lpeg.P("\r\n") + lpeg.P("\r") +lpeg.P("\n") % \end{macrocode} % -% \end{macro}\begin{macro}{table.fastcopy} +% \end{macro} +% \begin{macro}{table.fastcopy} % -% A function copying a table fastly. +% A function copying a table fastly. % % \begin{macrocode} if not table.fastcopy then do - local type, pairs, getmetatable, setmetatable = type, pairs, getmetatable, setmetatable + local type, pairs, getmetatable, setmetatable = + type, pairs, getmetatable, setmetatable local function fastcopy(old) -- fast one if old then @@ -252,9 +280,11 @@ end end % \end{macrocode} % -% \end{macro}\begin{macro}{table.copy} +% \end{macro} +% \begin{macro}{table.copy} % -% A function copying a table in more cases than fastcopy, for example when a key is a table. +% A function copying a table in more cases than fastcopy, for example when +% a key is a table. % % \begin{macrocode} @@ -297,9 +327,10 @@ end end % \end{macrocode} % -% \end{macro}\begin{macro}{table.serialize} +% \end{macro} +% \begin{macro}{table.serialize} % -% A bunch of functions leading to \texttt{table.serialize}. +% A bunch of functions leading to \texttt{table.serialize}. % % \begin{macrocode} @@ -554,9 +585,11 @@ end % \end{macrocode} % -% \end{macro}\begin{macro}{table.tohash} +% \end{macro} +% \begin{macro}{table.tohash} % -% Returning a table with all values of the argument table as keys, and \texttt{false} as values. This is what we will call a hash. +% Returning a table with all values of the argument table as keys, and +% \texttt{false} as values. This is what we will call a hash. % % \begin{macrocode} @@ -570,9 +603,10 @@ end % \end{macrocode} % -% \end{macro}\begin{macro}{table.fromhash} +% \end{macro} +% \begin{macro}{table.fromhash} % -% Returning a table built from a hash, with simple integer keys. +% Returning a table built from a hash, with simple integer keys. % % \begin{macrocode} @@ -586,9 +620,11 @@ end % \end{macrocode} % -% \end{macro}\begin{macro}{table.contains value} +% \end{macro} +% \begin{macro}{table.contains value} % -% A function returning true if the value \texttt{val} is in the table \texttt{t}. +% A function returning true if the value \texttt{val} is in the table +% \texttt{t}. % % \begin{macrocode} @@ -605,9 +641,11 @@ end % \end{macrocode} % -% \end{macro}\begin{macro}{table.contains key} +% \end{macro} +% \begin{macro}{table.contains key} % -% A function returning true if the key \texttt{key} is in the table \texttt{t} +% A function returning true if the key \texttt{key} is in the table +% \texttt{t} % % \begin{macrocode} @@ -624,9 +662,11 @@ end % \end{macrocode} % -% \end{macro}\begin{macro}{table.value position} +% \end{macro} +% \begin{macro}{table.value position} % -% A function returning the position of a value in a table. This will be important to be able to remove a value. +% A function returning the position of a value in a table. This will be +% important to be able to remove a value. % % \begin{macrocode} @@ -645,9 +685,10 @@ end % \end{macrocode} % -% \end{macro}\begin{macro}{table.key position} +% \end{macro} +% \begin{macro}{table.key position} % -% A function returning the position of a key in a table. +% A function returning the position of a key in a table. % % \begin{macrocode} @@ -666,9 +707,10 @@ end % \end{macrocode} % -% \end{macro}\begin{macro}{table.remove value} +% \end{macro} +% \begin{macro}{table.remove value} % -% Removes the first occurence of a value from a table. +% Removes the first occurence of a value from a table. % % \begin{macrocode} @@ -681,9 +723,10 @@ end % \end{macrocode} % -% \end{macro}\begin{macro}{table.remove key} +% \end{macro} +% \begin{macro}{table.remove key} % -% Removing a key from a table. +% Removing a key from a table. % % \begin{macrocode} @@ -696,9 +739,10 @@ end % \end{macrocode} % -% \end{macro}\begin{macro}{table.is empty} +% \end{macro} +% \begin{macro}{table.is empty} % -% Returns true if a table is empty. +% Returns true if a table is empty. % % \begin{macrocode} @@ -708,7 +752,8 @@ end % \end{macrocode} % -% \texttt{fpath} will contain all the file path manipulation functions. Some functions certainly need a little update or cleanup... +% \texttt{fpath} will contain all the file path manipulation functions. +% Some functions certainly need a little update or cleanup... % % \begin{macrocode} @@ -716,9 +761,10 @@ fpath = { } % \end{macrocode} % -% \end{macro}\begin{macro}{fpath.removesuffix} +% \end{macro} +% \begin{macro}{fpath.removesuffix} % -% A function to remove the suffix (extention) of a filename. +% A function to remove the suffix (extention) of a filename. % % \begin{macrocode} @@ -728,9 +774,10 @@ end % \end{macrocode} % -% \end{macro}\begin{macro}{fpath.addsuffix} +% \end{macro} +% \begin{macro}{fpath.addsuffix} % -% A function adding a suffix to a filename, except if it already has one. +% A function adding a suffix to a filename, except if it already has one. % % \begin{macrocode} @@ -744,9 +791,10 @@ end % \end{macrocode} % -% \end{macro}\begin{macro}{fpath.replacesuffix} +% \end{macro} +% \begin{macro}{fpath.replacesuffix} % -% A function replacing a suffix by a new one. +% A function replacing a suffix by a new one. % % \begin{macrocode} @@ -760,9 +808,10 @@ end % \end{macrocode} % -% \end{macro}\begin{macro}{fpath.dirname} +% \end{macro} +% \begin{macro}{fpath.dirname} % -% A function returning the directory of a file path. +% A function returning the directory of a file path. % % \begin{macrocode} @@ -772,7 +821,8 @@ end % \end{macrocode} % -% \end{macro}\begin{macro}{fpath.basename} +% \end{macro} +% \begin{macro}{fpath.basename} % % A function returning the basename (the name of the file, without the directories) of a file path. % @@ -787,9 +837,10 @@ end % \end{macrocode} % -% \end{macro}\begin{macro}{fpath.nameonly} +% \end{macro} +% \begin{macro}{fpath.nameonly} % -% Returning the basename of a file without the suffix. +% Returning the basename of a file without the suffix. % % \begin{macrocode} @@ -799,9 +850,10 @@ end % \end{macrocode} % -% \end{macro}\begin{macro}{fpath.suffix} +% \end{macro} +% \begin{macro}{fpath.suffix} % -% Returns the suffix of a file name. +% Returns the suffix of a file name. % % \begin{macrocode} @@ -811,9 +863,10 @@ end % \end{macrocode} % -% \end{macro}\begin{macro}{fpath.join} +% \end{macro} +% \begin{macro}{fpath.join} % -% A function joining any number of arguments into a complete path. +% A function joining any number of arguments into a complete path. % % \begin{macrocode} @@ -833,9 +886,10 @@ end % \end{macrocode} % -% \end{macro}\begin{macro}{fpath.split} +% \end{macro} +% \begin{macro}{fpath.split} % -% A function returning a table with all directories from a filename. +% A function returning a table with all directories from a filename. % % \begin{macrocode} @@ -854,9 +908,10 @@ end % \end{macrocode} % -% \end{macro}\begin{macro}{fpath.normalize sep} +% \end{macro} +% \begin{macro}{fpath.normalize sep} % -% A function to change directory separators to canonical ones (\texttt{/}). +% A function to change directory separators to canonical ones (\texttt{/}). % % \begin{macrocode} @@ -866,9 +921,11 @@ end % \end{macrocode} % -% \end{macro}\begin{macro}{fpath.localize sep} +% \end{macro} +% \begin{macro}{fpath.localize sep} % -% A function changing directory separators into local ones (\texttt{/} on Unix, |\| on Windows). +% A function changing directory separators into local ones (\texttt{/} on +% Unix, |\| on Windows). % % \begin{macrocode} @@ -882,9 +939,11 @@ end % \end{macrocode} % -% \end{macro}\begin{macro}{lfs.is writable} +% \end{macro} +% \begin{macro}{lfs.is writable} % -% Returns true if a file is writable. This function and the following ones are a bit too expensive, they should be made with |lfs.attributes|. +% Returns true if a file is writable. This function and the following ones +% are a bit too expensive, they should be made with |lfs.attributes|. % % \begin{macrocode} @@ -900,9 +959,10 @@ end % \end{macrocode} % -% \end{macro}\begin{macro}{lfs.is readable} +% \end{macro} +% \begin{macro}{lfs.is readable} % -% Returns true if a file is readable. +% Returns true if a file is readable. % % \begin{macrocode} @@ -918,9 +978,10 @@ end % \end{macrocode} % -% \end{macro}\begin{macro}{math.round} +% \end{macro} +% \begin{macro}{math.round} % -% Returns the closest integer. +% Returns the closest integer. % % \begin{macrocode} @@ -932,9 +993,10 @@ end % \end{macrocode} % -% \end{macro}\begin{macro}{math.div} +% \end{macro} +% \begin{macro}{math.div} % -% Returns the quotient of the euclidian division of n by m. +% Returns the quotient of the euclidian division of n by m. % % \begin{macrocode} @@ -946,9 +1008,10 @@ end % \end{macrocode} % -% \end{macro}\begin{macro}{math.mod} +% \end{macro} +% \begin{macro}{math.mod} % -% Returns the remainder of the euclidian division of n by m. +% Returns the remainder of the euclidian division of n by m. % % \begin{macrocode} diff --git a/Master/texmf-dist/source/luatex/luatextra/luamcallbacks.dtx b/Master/texmf-dist/source/luatex/luatextra/luamcallbacks.dtx index 17e9ded637d..c23a1980139 100644 --- a/Master/texmf-dist/source/luatex/luatextra/luamcallbacks.dtx +++ b/Master/texmf-dist/source/luatex/luatextra/luamcallbacks.dtx @@ -32,7 +32,7 @@ \input docstrip.tex \Msg{************************************************************************} \Msg{* Installation} -\Msg{* Package: luamcallbacks 2009/03/19 v0.92 LuaTeX multiple callbacks package} +\Msg{* Package: luamcallbacks 2009/09/18 v0.93 LuaTeX multiple callbacks.} \Msg{************************************************************************} \keepsilent @@ -60,7 +60,8 @@ and the derived files \file{luamcallbacks-test.tex}{\from{luamcallbacks.dtx}{test}}% } -% The following hacks are to generate a lua file with lua comments starting by -- instead of %% +% The following hacks are to generate a lua file with lua comments starting by +% -- instead of %% \def\MetaPrefix{-- } @@ -96,7 +97,7 @@ and the derived files %<*driver> \NeedsTeXFormat{LaTeX2e} \ProvidesFile{luamcallbacks.drv} - [2009/03/19 v0.92 LuaTeX multiple callbacks package] + [2009/09/18 v0.93 LuaTeX multiple callbacks package] \documentclass{ltxdoc} \EnableCrossrefs \CodelineIndex @@ -127,49 +128,81 @@ and the derived files % \GetFileInfo{luamcallbacks.drv} % % \title{The \textsf{luamcallbacks} package} -% \date{2009/03/19 v0.92} +% \date{2009/09/18 v0.93} % \author{Elie Roux \\ \texttt{elie.roux@telecom-bretagne.eu}} % % \maketitle % % \begin{abstract} -% This package manages the callback adding and removing, by adding \texttt{callback.add} -% and \texttt{callback.remove}, and overwriting \texttt{callback.register}. It also allows to create and call new callbacks. For an introduction on this package (among others), please refer to the document \texttt{luatextra-reference.pdf}. +% This package manages the callback adding and removing, by adding +% \texttt{callback.add} and \texttt{callback.remove}, and overwriting +% \texttt{callback.register}. It also allows to create and call new callbacks. +% For an introduction on this package (among others), please refer to the +% document \texttt{luatextra-reference.pdf}. % \end{abstract} % % \section{Documentation} % -%Lua\TeX\ provides an extremely interesting feature, named callbacks. It allows to call some lua functions at some points of the \TeX\ algorithm (a \emph{callback}), like when \TeX\ breaks likes, puts vertical spaces, etc. The Lua\TeX\ core offers a function called \texttt{callback.register} that enables to register a function in a callback. +% Lua\TeX\ provides an extremely interesting feature, named callbacks. It +% allows to call some lua functions at some points of the \TeX\ algorithm (a +% \emph{callback}), like when \TeX\ breaks likes, puts vertical spaces, etc. +% The Lua\TeX\ core offers a function called \texttt{callback.register} that +% enables to register a function in a callback. % -%The problem with \texttt{callback.register} is that is registers only one function in a callback. For a lot of callbacks it can be common to have several packages registering their function in a callback, and thus it is impossible with them to be compatible with each other. +% The problem with \texttt{callback.register} is that is registers only one +% function in a callback. For a lot of callbacks it can be common to have +% several packages registering their function in a callback, and thus it is +% impossible with them to be compatible with each other. % -%This package solves this problem by adding mainly one new function \texttt{callback.\\add} that adds a function in a callback. With this function it is possible for packages to register their function in a callback without overwriting the functions of the other packages. +% This package solves this problem by adding mainly one new function +% \texttt{callback.\\add} that adds a function in a callback. With this +% function it is possible for packages to register their function in a +% callback without overwriting the functions of the other packages. % -%The functions are called in a certain order, and when a package registers a callback it can assign a priority to its function. Conflicts can still remain even with the priority mechanism, for example in the case where two packages want to have the highest priority. In these cases the packages have to solve the conflicts themselves. +% The functions are called in a certain order, and when a package registers a +% callback it can assign a priority to its function. Conflicts can still +% remain even with the priority mechanism, for example in the case where two +% packages want to have the highest priority. In these cases the packages have +% to solve the conflicts themselves. % -% This package also privides a way to create and call new callbacks, in addition to the default Lua\TeX\ callbacks. +% This package also privides a way to create and call new callbacks, in +% addition to the default Lua\TeX\ callbacks. % -% This package contains only a \texttt{.lua} file, that can be called by another lua script. For example, this script is called in \textsf{luatextra}. +% This package contains only a \texttt{.lua} file, that can be called by +% another lua script. For example, this script is called in +% \textsf{luatextra}. % %\subsubsection*{Limitations} % -%This package only works for callbacks where it's safe to add multiple functions without changing the functions' signatures. There are callbacks, though, where registering several functions is not possible without changing the function's signatures, like for example the readers callbacks. These callbacks take a filename and give the datas in it. One solution would be to change the functions' signature to open it when the function is the first, and to take the datas and modify them eventually if they are called after the first. But it seems rather fragile and useless, so it's not implemented. With these callbacks, in this package we simply execute the first function in the list. -% -%Other callbacks in this case are \texttt{define\_font} and \texttt{open\_read\_file}. There is though a solution for several packages to use these callbacks, see the implementation of \texttt{luatextra}. +% This package only works for callbacks where it's safe to add multiple +% functions without changing the functions' signatures. There are callbacks, +% though, where registering several functions is not possible without changing +% the function's signatures, like for example the readers callbacks. These +% callbacks take a filename and give the datas in it. One solution would be to +% change the functions' signature to open it when the function is the first, +% and to take the datas and modify them eventually if they are called after +% the first. But it seems rather fragile and useless, so it's not implemented. +% With these callbacks, in this package we simply execute the first function +% in the list. +% +% Other callbacks in this case are \texttt{define\_font} and +% \texttt{open\_read\_file}. There is though a solution for several packages +% to use these callbacks, see the implementation of \texttt{luatextra}. % % \StopEventually{ % } % % \section{Package code} % -% The package contains \texttt{luamcallbacks.lua} with the new functions, and an example of the use of luamcallbacks. -% % \iffalse %<*lua> % \fi % +% The package contains \texttt{luamcallbacks.lua} with the new functions, +% and an example of the use of luamcallbacks. % -% First the \texttt{luamcallbacks} module is registered as a Lua\TeX\ module, with some informations. +% First the \texttt{luamcallbacks} module is registered as a Lua\TeX\ +% module, with some informations. % % \begin{macrocode} @@ -177,8 +210,8 @@ luamcallbacks = { } luamcallbacks.module = { name = "luamcallbacks", - version = 0.92, - date = "2009/03/19", + version = 0.93, + date = "2009/09/18", description = "Module to register several functions in a callback.", author = "Hans Hagen & Elie Roux", copyright = "Hans Hagen & Elie Roux", @@ -189,7 +222,8 @@ luatextra.provides_module(luamcallbacks.module) % \end{macrocode} % -% \texttt{callbacklist} is the main list, that contains the callbacks as keys and a table of the registered functions a values. +% \texttt{callbacklist} is the main list, that contains the callbacks as +% keys and a table of the registered functions a values. % % \begin{macrocode} @@ -197,7 +231,8 @@ luamcallbacks.callbacklist = luamcallbacks.callbacklist or { } % \end{macrocode} % -% A table with the default functions of the created callbacks. See \texttt{luamcallbacks.create} for further informations. +% A table with the default functions of the created callbacks. See +% \texttt{luamcallbacks.create} for further informations. % % \begin{macrocode} @@ -207,13 +242,16 @@ local format = string.format % \end{macrocode} % -% There are 4 types of callback: -% \begin{itemize} -% \item the ones taking a list of nodes and returning a boolean and eventually a new head (\texttt{list}) -% \item the ones taking datas and returning the modified ones (\texttt{data}) -% \item the ones that can't have multiple functions registered in them (\texttt{first}) -% \item the ones for functions that don't return anything (\texttt{simple}) -% \end{itemize} +% There are 4 types of callback: +% \begin{itemize} +% \item the ones taking a list of nodes and returning a boolean and +% eventually a new head (\texttt{list}) +% \item the ones taking datas and returning the modified ones +% (\texttt{data}) +% \item the ones that can't have multiple functions registered in them +% (\texttt{first}) +% \item the ones for functions that don't return anything (\texttt{simple}) +% \end{itemize} % % \begin{macrocode} @@ -224,7 +262,8 @@ local simple = 4 % \end{macrocode} % -% \texttt{callbacktypes} is the list that contains the callbacks as keys and the type (list or data) as values. +% \texttt{callbacktypes} is the list that contains the callbacks as keys +% and the type (list or data) as values. % % \begin{macrocode} @@ -280,7 +319,20 @@ read_data_file = first, % \end{macrocode} % -% As we overwrite \texttt{callback.register}, we save it as \texttt{luamcallbacks.internalregister}. After that we declare some functions to write the errors or the logs. +% In Lua\TeX\ version 0.43, a new callback called |process_output_buffer| +% appeared, so we enable it. +% +% \begin{macrocode} + +if tex.luatexversion > 42 then + luamcallbacks.callbacktypes["process_output_buffer"] = data +end + +% \end{macrocode} +% +% As we overwrite \texttt{callback.register}, we save it as +% \texttt{luamcallbacks.internalregister}. After that we declare some +% functions to write the errors or the logs. % % \begin{macrocode} @@ -306,7 +358,9 @@ end % \end{macrocode} % -% A simple function we'll use later to understand the arguments of the \texttt{create} function. It takes a string and returns the type corresponding to the string or nil. +% A simple function we'll use later to understand the arguments of the +% \texttt{create} function. It takes a string and returns the type +% corresponding to the string or nil. % % \begin{macrocode} @@ -326,11 +380,18 @@ end % \end{macrocode} % -% \begin{macro}{luamcallbacks.create} +% \begin{macro}{luamcallbacks.create} % -% This first function creates a new callback. The signature is \texttt{create(name, ctype, default)} where \texttt{name} is the name of the new callback to create, \texttt{ctype} is the type of callback, and \texttt{default} is the default function to call if no function is registered in this callback. +% This first function creates a new callback. The signature is +% \texttt{create(name, ctype, default)} where \texttt{name} is the name of +% the new callback to create, \texttt{ctype} is the type of callback, and +% \texttt{default} is the default function to call if no function is +% registered in this callback. % -% The created callback will behave the same way Lua\TeX\ callbacks do, you can add and remove functions in it. The difference is that the callback is not automatically called, the package developer creating a new callback must also call it, see next function. +% The created callback will behave the same way Lua\TeX\ callbacks do, you +% can add and remove functions in it. The difference is that the callback +% is not automatically called, the package developer creating a new +% callback must also call it, see next function. % % \begin{macrocode} @@ -359,11 +420,12 @@ end % \end{macrocode} % -% \end{macro} +% \end{macro} % -% \begin{macro}{luamcallbacks.call} +% \begin{macro}{luamcallbacks.call} % -% This function calls a callback. It can only call a callback created by the \texttt{create} function. +% This function calls a callback. It can only call a callback created by +% the \texttt{create} function. % % \begin{macrocode} @@ -398,15 +460,28 @@ end % \end{macrocode} % -% \end{macro} +% \end{macro} % -% \begin{macro}{luamcallbacks.add} +% \begin{macro}{luamcallbacks.add} % -%The main function. The signature is \texttt{luamcallbacks.add (name, func, description, priority)} with \texttt{name} being the name of the callback in which the function is added; \texttt{func} is the added function; \texttt{description} is a small character string describing the function, and \texttt{priority} an optional argument describing the priority the function will have. +% The main function. The signature is \texttt{luamcallbacks.add (name, +% func, description, priority)} with \texttt{name} being the name of the +% callback in which the function is added; \texttt{func} is the added +% function; \texttt{description} is a small character string describing the +% function, and \texttt{priority} an optional argument describing the +% priority the function will have. % -%The functions for a callbacks are added in a list (in \texttt{luamcallbacks.callbacklist\\.callbackname}). If they have no priority or a high priority number, they will be added at the end of the list, and will be called after the others. If they have a low priority number, the will be added at the beginning of the list and will be called before the others. +% The functions for a callbacks are added in a list (in +% \texttt{luamcallbacks.callbacklist\\.callbackname}). If they have no +% priority or a high priority number, they will be added at the end of the +% list, and will be called after the others. If they have a low priority +% number, the will be added at the beginning of the list and will be called +% before the others. % -%Something that must be made clear, is that there is absolutely no solution for packages conflicts: if two packages want the top priority on a certain callback, they will have to decide the priority they will give to their function themself. Most of the time, the priority is not needed. +% Something that must be made clear, is that there is absolutely no +% solution for packages conflicts: if two packages want the top priority on +% a certain callback, they will have to decide the priority they will give +% to their function themself. Most of the time, the priority is not needed. % % \begin{macrocode} @@ -474,11 +549,14 @@ end % \end{macrocode} % -% \end{macro} +% \end{macro} % -% \begin{macro}{luamcallbacks.get priority} +% \begin{macro}{luamcallbacks.get priority} % -% This function tells if a function has already been registered in a callback, and gives its current priority. The arguments are the name of the callback and the description of the function. If it has already been registered, it gives its priority, and if not it returns false. +% This function tells if a function has already been registered in a +% callback, and gives its current priority. The arguments are the name of +% the callback and the description of the function. If it has already been +% registered, it gives its priority, and if not it returns false. % % \begin{macrocode} @@ -498,11 +576,14 @@ end % \end{macrocode} % -% \end{macro} +% \end{macro} % -% \begin{macro}{luamcallbacks.remove} +% \begin{macro}{luamcallbacks.remove} % -% The function that removes a function from a callback. The signature is \texttt{mcallbacks.remove (name, description)} with \texttt{name} being the name of callbacks, and description the description passed to \texttt{mcallbacks.add}. +% The function that removes a function from a callback. The signature is +% \texttt{mcallbacks.remove (name, description)} with \texttt{name} being +% the name of callbacks, and description the description passed to +% \texttt{mcallbacks.add}. % % \begin{macrocode} @@ -532,8 +613,11 @@ function luamcallbacks.remove (name, description) table.remove(l,k) luamcallbacks.log( format("removing function '%s' from '%s'",description,name)) - if l == {} and not luamcallbacks.lua_callbacks_defaults[name] then + if not next(l) then + luamcallbacks.callbacklist[name] = nil + if not luamcallbacks.lua_callbacks_defaults[name] then luamcallbacks.internalregister(name, nil) + end end return end @@ -544,11 +628,11 @@ end % \end{macrocode} % -% \end{macro} +% \end{macro} % -% \begin{macro}{luamcallbacks.reset} +% \begin{macro}{luamcallbacks.reset} % -% This function removes all the functions registered in a callback. +% This function removes all the functions registered in a callback. % % \begin{macrocode} @@ -574,11 +658,13 @@ end % \end{macrocode} % -% \end{macro} +% \end{macro} % -% This function and the following ones are only internal. This one is the handler for the first type of callbacks: the ones that take a list head and return true, false, or a new list head. +% This function and the following ones are only internal. This one is the +% handler for the first type of callbacks: the ones that take a list head +% and return true, false, or a new list head. % -% \begin{macro}{luamcallbacks.listhandler} +% \begin{macro}{luamcallbacks.listhandler} % % \begin{macrocode} @@ -615,11 +701,11 @@ end % \end{macrocode} % -% \end{macro} +% \end{macro} % -% The handler for callbacks taking datas and returning modified ones. +% The handler for callbacks taking datas and returning modified ones. % -% \begin{macro}{luamcallbacks.datahandler} +% \begin{macro}{luamcallbacks.datahandler} % % \begin{macrocode} @@ -637,11 +723,13 @@ end % \end{macrocode} % -% \end{macro} +% \end{macro} % -% This function is for the handlers that don't support more than one functions in them. In this case we only call the first function of the list. +% This function is for the handlers that don't support more than one +% functions in them. In this case we only call the first function of the +% list. % -% \begin{macro}{luamcallbacks.firsthandler} +% \begin{macro}{luamcallbacks.firsthandler} % % \begin{macrocode} @@ -659,11 +747,11 @@ end % \end{macrocode} % -% \end{macro} +% \end{macro} % -% Handler for simple functions that don't return anything. +% Handler for simple functions that don't return anything. % -% \begin{macro}{luamcallbacks.simplehandler} +% \begin{macro}{luamcallbacks.simplehandler} % % \begin{macrocode} @@ -680,9 +768,10 @@ end % \end{macrocode} % -% \end{macro} +% \end{macro} % -% Finally we add some functions to the \texttt{callback} module, and we overwrite \texttt{callback.register} so that it outputs an error. +% Finally we add some functions to the \texttt{callback} module, and we +% overwrite \texttt{callback.register} so that it outputs an error. % % \begin{macrocode} @@ -709,9 +798,9 @@ end % % \section{Test file} % -% The test file is made to run in plainTeX, but is trivial to adapt for LaTeX. -% First we input the package, and we typeset a small sentence to get a non-empty -% document. +% The test file is made to run in plainTeX, but is trivial to adapt for +% LaTeX. First we input the package, and we typeset a small sentence to +% get a non-empty document. % % \begin{macrocode} \input luatextra.sty @@ -719,7 +808,7 @@ end This is just a test file. % \end{macrocode} % -% Then we declare three functions that we will use. +% Then we declare three functions that we will use. % % \begin{macrocode} \luadirect{ @@ -739,7 +828,7 @@ local function three(head,...) end % \end{macrocode} % -% Then we add the three functions to the hpack\_filter callback +% Then we add the three functions to the hpack\_filter callback % % \begin{macrocode} callback.add("hpack_filter",one,"my example function one",1) @@ -747,14 +836,14 @@ callback.add("hpack_filter",two,"my example function two",2) callback.add("hpack_filter",three,"my example function three",1) % \end{macrocode} % -% We remove the function three from the callback. +% We remove the function three from the callback. % % \begin{macrocode} callback.remove("hpack_filter","my example function three") % \end{macrocode} % -% And we remove a non-declared function to the callback, which will generate an -% error. +% And we remove a non-declared function to the callback, which will +% generate an error. % % \begin{macrocode} } diff --git a/Master/texmf-dist/source/luatex/luatextra/luatextra-reference.tex b/Master/texmf-dist/source/luatex/luatextra/luatextra-reference.tex index 7f650bfb16e..3fe05478d84 100644 --- a/Master/texmf-dist/source/luatex/luatextra/luatextra-reference.tex +++ b/Master/texmf-dist/source/luatex/luatextra/luatextra-reference.tex @@ -7,13 +7,20 @@ % \documentclass{article} -\usepackage[english]{babel} \usepackage[utf8]{luainputenc} \usepackage[T1]{fontenc} +\usepackage{times} \usepackage{amsfonts} \usepackage{eurosym} -\usepackage[pdftex, bookmarks, colorlinks=false, pdftitle={LuaTeXtra references}, pdfauthor={Elie Roux}, pdfsubject={LuaTeXtra references}, pdfborder={0 0 0}]{hyperref} \usepackage[pdftex]{graphicx} +\usepackage[pdftex, + bookmarks, + colorlinks=false, + pdftitle={LuaTeXtra references}, + pdfauthor={Elie Roux}, + pdfsubject={LuaTeXtra references}, + pdfborder={0 0 0}]{hyperref} +\usepackage[english]{babel} \makeatletter \newlength\xxt@kern@Te @@ -40,8 +47,6 @@ }\kern\xxt@kern@Te\TeX}}% \TeX@logo@spacing{-0.15em}{-0.15em}{0.5ex}{-0.36em}{-0.15em}{-0.1em} - -\usepackage{times} \title{Lua\TeX tra references} \author{Elie Roux \\ \url{elie.roux@telecom-bretagne.eu}} \begin{document} @@ -50,122 +55,237 @@ \subsubsection*{Preamble: What is this document?} -This document describes, from the user or developer point of view, how to use the coherent set of packages \textsf{luatextra}, \textsf{luainputenc}, \textsf{luaotfload}, \textsf{luamcallbacks} and \textsf{luaextra}. +This document describes, from the user or developer point of view, how to use +the coherent set of packages \textsf{luatextra}, \textsf{luainputenc}, +\textsf{luaotfload}, \textsf{luamcallbacks} and \textsf{luaextra}. -If you are looking for documentation on the \LuaTeX\ engine, please refer to the file \texttt{luatexref-t.pdf}, but note that using these packages will slightly modify some \LuaTeX\ behaviours, especially the \texttt{callback} library. +If you are looking for documentation on the \LuaTeX\ engine, please refer to +the file \texttt{luatexref-t.pdf}, but note that using these packages will +slightly modify some \LuaTeX\ behaviours, especially the \texttt{callback} +library. -If you are looking for technical details about one of the packages, you can refer to its documentation. Each of them have a complete documentation in the file \texttt{package.pdf} with package being the name of the package. +If you are looking for technical details about one of the packages, you can +refer to its documentation. Each of them have a complete documentation in the +file \texttt{package.pdf} with package being the name of the package. \tableofcontents \section{Introduction} -Before going any further, we need to explain the difference between an engine, a format, and a program. If you know the difference between these, please go to section \ref{sub:luatextra}. +Before going any further, we need to explain the difference between an engine, +a format, and a program. If you know the difference between these, please go +to section \ref{sub:luatextra}. \subsection{What is \LuaTeX ?} -\LuaTeX\ is a \TeX\ engine. A \TeX\ engine is a binary executable that provides some very low-level primitives, for example \texttt{\string\count} to set a counter to a certain value. Examples of engines are the old \TeX\ 82, \eTeX, pdf\TeX, Omega, Aleph, Lua\TeX\ and \XeTeX . +\LuaTeX\ is a \TeX\ engine. A \TeX\ engine is a binary executable that +provides some very low-level primitives, for example \texttt{\string\count} to +set a counter to a certain value. Examples of engines are the old \TeX\ 82, +\eTeX, pdf\TeX, Omega, Aleph, Lua\TeX\ and \XeTeX . -There are two main differences between \LuaTeX\ and its predecessor, pdfTeX: \LuaTeX\ now truely understands UTF-8 and enables the execution of some lua code at certain points of the \TeX\ algorithm. These two features allow, among other things, to open modern fonts like OpenType or TrueType fonts. +There are two main differences between \LuaTeX\ and its predecessor, pdfTeX: +\LuaTeX\ now truely understands UTF-8 and enables the execution of some lua +code at certain points of the \TeX\ algorithm. These two features allow, among +other things, to open modern fonts like OpenType or TrueType fonts. \subsection{What is the difference with \LaTeX ?} -The nature of \LaTeX\ is fundamentally different: \LaTeX\ is a \TeX\ format. Examples of formats are Plain, \LaTeX\ and Con\TeX t. +The nature of \LaTeX\ is fundamentally different: \LaTeX\ is a \TeX\ format. +Examples of formats are Plain, \LaTeX\ and Con\TeX t. -This distinction is very hard to make, first because you cannot find any documentation on it, and secondly because the only things everyone knows are programs. A program is a command you type in your terminal that calls an engine with a format. Here are the different things behind what you type: +This distinction is very hard to make, first because you cannot find any +documentation on it, and secondly because the only things everyone knows are +programs. A program is a command you type in your terminal that calls an +engine with a format. Here are the different things behind what you type: \begin{itemize} -\item \texttt{tex} is the engine \TeX\ 82 with the format Plain. Both were created by Donald Knuth a very long time ago. -\item \texttt{pdftex} is the engine pdf\TeX\ (in PDF mode) with the format Plain. -\item \texttt{luatex} is the engine \LuaTeX\ (in PDF mode) with the format Plain. -\item \texttt{xetex} is the engine \XeTeX\ (in PDF mode) with the format Plain. -\item \texttt{latex} is the engine pdf\TeX\ (in DVI mode) with the format \LaTeX . -\item \texttt{pdflatex} is the engine pdf\TeX\ (in PDF mode) with the format \LaTeX . -\item \texttt{lualatex} is the engine \LuaTeX\ (in PDF mode) with the format \LaTeX . -\item \texttt{xelatex} is the engine \XeTeX\ (in PDF mode) with the format \LaTeX . + \item \texttt{tex} is the engine \TeX\ 82 with the format Plain. Both were + created by Donald Knuth a very long time ago. + \item \texttt{pdftex} is the engine pdf\TeX\ (in PDF mode) with the format + Plain. + \item \texttt{luatex} is the engine \LuaTeX\ (in PDF mode) with the format + Plain. + \item \texttt{xetex} is the engine \XeTeX\ (in PDF mode) with the format + Plain. + \item \texttt{latex} is the engine pdf\TeX\ (in DVI mode) with the format + \LaTeX . + \item \texttt{pdflatex} is the engine pdf\TeX\ (in PDF mode) with the format + \LaTeX . + \item \texttt{lualatex} is the engine \LuaTeX\ (in PDF mode) with the format + \LaTeX . + \item \texttt{xelatex} is the engine \XeTeX\ (in PDF mode) with the format + \LaTeX . \end{itemize} -pdf\TeX\ and \LuaTeX\ can produce both DVI and PDF output. To choose it, you can simply set \texttt{\string\pdfoutput} to 0 or 1. +pdf\TeX\ and \LuaTeX\ can produce both DVI and PDF output. To choose it, you +can simply set \texttt{\string\pdfoutput} to 0 or 1. -As you can see, there is absolutely no corellation between \LuaTeX\ and \LaTeX , even if the names are close\dots +As you can see, there is absolutely no corellation between \LuaTeX\ and +\LaTeX, even if the names are close\dots \subsection{What is Lua\TeX tra?\label{sub:luatextra}} -Lua\TeX tra is the adaptation of the engine \LuaTeX\ to the formats Plain and \LaTeX . It enables these formats to benefit from the \LuaTeX\ new features, like UTF-8 reading, attributes handling, extended registers, modern font opening, etc. +Lua\TeX tra is the adaptation of the engine \LuaTeX\ to the formats Plain and +\LaTeX . It enables these formats to benefit from the \LuaTeX\ new features, +like UTF-8 reading, attributes handling, extended registers, modern font +opening, etc. -\LuaTeX\ provides only very low-level macros for these features, and a lot of code has to be done by the format to really provide a good user experience. +\LuaTeX\ provides only very low-level macros for these features, and a lot of +code has to be done by the format to really provide a good user experience. -With what I just said, a good question would be the following: why isn't \textsf{luatextra} integrated into \LaTeX\ and Plain? +With what I just said, a good question would be the following: why isn't +\textsf{luatextra} integrated into \LaTeX\ and Plain? -The answer is simple: because Plain and \LaTeX\ are frozen. This means that they don't accept new code anymore, even if it's totally necessary to benefit from new engines. Thus, the only solution is to provide a package that every user will have to load. +The answer is simple: because Plain and \LaTeX\ are frozen. This means that +they don't accept new code anymore, even if it's totally necessary to benefit +from new engines. Thus, the only solution is to provide a package that every +user will have to load. \subsection{Why is it necessary?} -\LuaTeX tra is necessary for users and developers because it provides a way for several packages to access ressources. - -Let's take a very concrete example: \LuaTeX\ has a totally new concept named attributes; basically they can be considered as special counts: you can name them with the primitive \texttt{\string\attribute}, like you can name an counter with \texttt{\string\count}, and you can give them a value with \texttt{\string\attributedef}, that works like \texttt{\string\countdef} (see the \LuaTeX\ documentation for more details about attributes). Attributes, like counts, are described by numbers, for example you have \texttt{\string\attribute0}, \texttt{\string\attribute1}, etc. - -Plain and \LaTeX\ provide a macro \texttt{\string\newcount} that takes the first free counter and attributes it a name, for example we can image that \texttt{\string\newcount\string\foo} will in fact do \texttt{\string\count25\string\foo}. This enables packages to automatically take a free counter. Without it, package developers would have to maintain a list saying ``please don't take attribute number foo, it's for the package bar!". - -Plain and \LaTeX\ do not provide \texttt{\string\newattribute} to allocate a free attribute; but we do it in \textsf{luatextra}. Without \LuaTeX tra, people have to take arbitrary attributes and cross their fingers hoping that noone else will use the attributes they've chosen. With \LuaTeX tra, you can safely take attributes, being sure that noone else will use them. - -Another similar problem is callback access: by default \LuaTeX\ does not provide a way to register several functions in a callback, so if two packages want to register a function in a callback, they won't be compatible, as only one will work. \textsf{luamcallback} provides a new mechanism for callbacks that enables this, allowing more package compatibility. - -These two problems are very concrete, that's the main reason why \LuaTeX tra has been created: without it a lot of package compatibility problems would have been raised. +\LuaTeX tra is necessary for users and developers because it provides a way +for several packages to access ressources. + +Let's take a very concrete example: \LuaTeX\ has a totally new concept named +attributes; basically they can be considered as special counts: you can name +them with the primitive \texttt{\string\attribute}, like you can name an +counter with \texttt{\string\count}, and you can give them a value with +\texttt{\string\attributedef}, that works like \texttt{\string\countdef} (see +the \LuaTeX\ documentation for more details about attributes). Attributes, +like counts, are described by numbers, for example you have +\texttt{\string\attribute0}, \texttt{\string\attribute1}, etc. + +Plain and \LaTeX\ provide a macro \texttt{\string\newcount} that takes the +first free counter and attributes it a name, for example we can image that +\texttt{\string\newcount\string\foo} will in fact do +\texttt{\string\count25\string\foo}. This enables packages to automatically +take a free counter. Without it, package developers would have to maintain a +list saying ``please don't take attribute number foo, it's for the package +bar!". + +Plain and \LaTeX\ do not provide \texttt{\string\newattribute} to allocate a +free attribute; but we do it in \textsf{luatextra}. Without \LuaTeX tra, +people have to take arbitrary attributes and cross their fingers hoping that +noone else will use the attributes they've chosen. With \LuaTeX tra, you can +safely take attributes, being sure that noone else will use them. + +Another similar problem is callback access: by default \LuaTeX\ does not +provide a way to register several functions in a callback, so if two packages +want to register a function in a callback, they won't be compatible, as only +one will work. \textsf{luamcallback} provides a new mechanism for callbacks +that enables this, allowing more package compatibility. + +These two problems are very concrete, that's the main reason why \LuaTeX tra +has been created: without it a lot of package compatibility problems would +have been raised. \subsection{The different packages} The \LuaTeX tra coherent set of packages contains: \begin{itemize} -\item \textsf{luatextra}: the basic general macros and lua functions -\item \textsf{luainputenc}: adaptation of \textsf{inputenc} to \LuaTeX -\item \textsf{luamcallbacks}: pure lua package to be able to register several functions in a callback -\item \textsf{luaextra}: additional lua functions + \item \textsf{luatextra}: the basic general macros and lua functions + \item \textsf{luainputenc}: adaptation of \textsf{inputenc} to \LuaTeX + \item \textsf{luamcallbacks}: pure lua package to be able to register + several functions in a callback + \item \textsf{luaextra}: additional lua functions \end{itemize} \subsection{Overview} -The main idea, as explained above, is to provide a safe way to use different packages that are not coherent, without loading several times the same code, or taking ressources (like attributes) already used by other packages. +The main idea, as explained above, is to provide a safe way to use different +packages that are not coherent, without loading several times the same code, +or taking ressources (like attributes) already used by other packages. -To do so, we have used a concept for lua files named ``module", inspired by the \LaTeX\ packages. \textbf{Warning:} the module concept described here comes as an extention to the base lua module concept. We advise not to use the base lua modules, but the \LuaTeX tra module system, as it provides more informations, prints informations in logs, etc. The \LuaTeX tra lua module system works basically like the \LaTeX\ package system: you can simply use them, or require them with a version number, etc. +To do so, we have used a concept for lua files named ``module", inspired by +the \LaTeX\ packages. \textbf{Warning:} the module concept described here +comes as an extention to the base lua module concept. We advise not to use the +base lua modules, but the \LuaTeX tra module system, as it provides more +informations, prints informations in logs, etc. The \LuaTeX tra lua module +system works basically like the \LaTeX\ package system: you can simply use +them, or require them with a version number, etc. -As explained above, another important function provided by \LuaTeX tra is attributes allocation with \texttt{\string\newluaattribute}. +As explained above, another important function provided by \LuaTeX tra is +attributes allocation with \texttt{\string\newluaattribute}. \subsection{Naming conventions} -In \LuaTeX tra we decided to adopt a simple naming convention: all macros start by \texttt{lua}. There are though a few exceptions: for instance we renamed the concept of \LuaTeX 's \texttt{attribute} to \texttt{luaattribute}, as attribute is already something used by a lot of packages and users. This lead us to name our macros \texttt{\string\newluaattribute}, \texttt{\string\unsetluaattribute}, etc. for backward compatibility. On the same principle, \texttt{catcodetable} is replaced by \texttt{luacatcodetable}. +In \LuaTeX tra we decided to adopt a simple naming convention: all macros +start by \texttt{lua}. There are though a few exceptions: for instance we +renamed the concept of \LuaTeX 's \texttt{attribute} to \texttt{luaattribute}, +as attribute is already something used by a lot of packages and users. This +lead us to name our macros \texttt{\string\newluaattribute}, +\texttt{\string\unsetluaattribute}, etc. for backward compatibility. On the +same principle, \texttt{catcodetable} is replaced by \texttt{luacatcodetable}. \section{Basic user point of view} \subsection{Plain and \LaTeX\ macros} -The most useful macro provided by \textsf{luatextra} is certainly \texttt{\string\luadirect}, which is a wrapper for \texttt{\string\directlua}, but will keep the same signature whatever the \LuaTeX\ version. For example this macro works for \LuaTeX\ versions $<$ 0.36, and will most certainly work for future versions of \LuaTeX . It is advised to use this macro to keep the compatibility of your package with all versions of \LuaTeX . \texttt{\string\lualate} is also provided as a wrapper for \texttt{\string\latelua}. - -Some small but useful macros are \texttt{\string\LuaTeX} and \texttt{\string\LuaLaTeX} that produce \LaTeX\ and \LuaLaTeX . - -\textsf{luatextra} automatically loads \textsf{luaotfload}, so you can open otf fonts directly, for instance \texttt{\string\font\string\foo = "LinLibertine.otf"\string\foo} will work. You can also pass options to the font opening, for example the different OTF options you want. These options are passed with the \XeTeX\ font syntax (briefly described in \texttt{XeTeX-reference.pdf}), for example if you want to open a font with the usual \TeX\ substitutions and ligatures, with also the font default ligatures, you can try \newline \texttt{\string\font\string\foo = "LinLibertine.otf;+tlig;+tsub;+liga;+rlig;"\string\foo}. +The most useful macro provided by \textsf{luatextra} is certainly +\texttt{\string\luadirect}, which is a wrapper for \texttt{\string\directlua}, +but will keep the same signature whatever the \LuaTeX\ version. For example +this macro works for \LuaTeX\ versions $<$ 0.36, and will most certainly work +for future versions of \LuaTeX . It is advised to use this macro to keep the +compatibility of your package with all versions of \LuaTeX . +\texttt{\string\lualate} is also provided as a wrapper for +\texttt{\string\latelua}. + +Some small but useful macros are \texttt{\string\LuaTeX} and +\texttt{\string\LuaLaTeX} that produce \LaTeX\ and \LuaLaTeX . + +\textsf{luatextra} automatically loads \textsf{luaotfload}, so you can open +otf fonts directly, for instance \texttt{\string\font\string\foo = + "LinLibertine.otf"\string\foo} will work. You can also pass options to the +font opening, for example the different OTF options you want. These options +are passed with the \XeTeX\ font syntax (briefly described in +\texttt{XeTeX-reference.pdf}), for example if you want to open a font with the +usual \TeX\ substitutions and ligatures, with also the font default ligatures, +you can try \newline \texttt{\string\font\string\foo = + "LinLibertine.otf;+tlig;+tsub;+liga;+rlig;"\string\foo}. \subsection{\LaTeX -only macros} \subsubsection{luainputenc} -From the user point of view, adapting an old document for \LuaTeX\ is really easy: replacing \textsf{inputenc} by \textsf{luainputenc} in the preamble is enough. +From the user point of view, adapting an old document for \LuaTeX\ is really +easy: replacing \textsf{inputenc} by \textsf{luainputenc} in the preamble is +enough. -\textsf{Warning:} the current version of \textsf{luainputenc} automatically loads the \LuaTeX tra packages. It won't necessarily be the case in the future. So if you use some functions of \LuaTeX tra (like \texttt{\string\newluaattribute}), it is advised to also explicitely use \texttt{luatextra}. A typical part of \LaTeX\ preamble for \LuaTeX\ will be for example: +\textsf{Warning:} the current version of \textsf{luainputenc} automatically +loads the \LuaTeX tra packages. It won't necessarily be the case in the +future. So if you use some functions of \LuaTeX tra (like +\texttt{\string\newluaattribute}), it is advised to also explicitely use +\texttt{luatextra}. A typical part of \LaTeX\ preamble for \LuaTeX\ will be +for example: \begin{verbatim} \usepackage[utf8]{luainputenc} \usepackage{luatextra} \end{verbatim} -Another important thing to know, for \LaTeX , is that loading \textsf{luainputenc} is necessary if you use old fonts. One could believe that \LuaTeX\ reading UTF-8 natively, \textsf{inputenc} is not necessary anymore. It's not the case! The exception to this is the case where you only use OTF fonts. But you can't simply suppress \textsf{inputenc} for your old documents. - -Note that \textsf{luainputenc} automatically loads \textsf{inputenc} if called with an old engine, so you will still be able to compile your documents with pdf\TeX\ without changing them. - -A new font encoding has been added: \texttt{EU2}. It is meant to be used with OTF fonts. It is very minimal and just defines a default font (lmodern). Use it if you use only OTF fonts. To use it simply call \textsf{fontenc} with the option \texttt{EU2}. - -EU2 encoding is special as it needs non-ASCII characters to be non-active (unlike other font encodings), so you cannot mix old encodings and EU2. If you want to use both old fonts and OTF fonts in your document, the way to do so is by using a new option of \textsf{luainputenc}: \texttt{lutf8x}. This option overrides \LaTeX 's mechanism to change the font encoding and activates or unactivates non-ASCII characters. If you use this option, you will be able to change the encoding, for example: +Another important thing to know, for \LaTeX , is that loading +\textsf{luainputenc} is necessary if you use old fonts. One could believe that +\LuaTeX\ reading UTF-8 natively, \textsf{inputenc} is not necessary anymore. +It's not the case! The exception to this is the case where you only use OTF +fonts. But you can't simply suppress \textsf{inputenc} for your old documents. + +Note that \textsf{luainputenc} automatically loads \textsf{inputenc} if called +with an old engine, so you will still be able to compile your documents with +pdf\TeX\ without changing them. + +A new font encoding has been added: \texttt{EU2}. It is meant to be used with +OTF fonts. It is very minimal and just defines a default font (lmodern). Use +it if you use only OTF fonts. To use it simply call \textsf{fontenc} with the +option \texttt{EU2}. + +EU2 encoding is special as it needs non-ASCII characters to be non-active +(unlike other font encodings), so you cannot mix old encodings and EU2. If you +want to use both old fonts and OTF fonts in your document, the way to do so is +by using a new option of \textsf{luainputenc}: \texttt{lutf8x}. This option +overrides \LaTeX 's mechanism to change the font encoding and activates or +unactivates non-ASCII characters. If you use this option, you will be able to +change the encoding, for example: \begin{verbatim} abc @@ -177,11 +297,15 @@ abc abc \end{verbatim} -Another new option has been added to \textsf{luainputenc}: \texttt{unactivate}. With this option, non-ASCII characters won't be activated, so you will be able to use only OTF fonts. Typically you can use this options with the \texttt{EU2} \textsf{fontenc} option. +Another new option has been added to \textsf{luainputenc}: +\texttt{unactivate}. With this option, non-ASCII characters won't be +activated, so you will be able to use only OTF fonts. Typically you can use +this options with the \texttt{EU2} \textsf{fontenc} option. \subsubsection{luacode environment} -\LuaTeX tra also provides an environment for lua code integration: \textsf{luacode}. You can simply use it this way: +\LuaTeX tra also provides an environment for lua code integration: +\textsf{luacode}. You can simply use it this way: \begin{verbatim} \begin{luacode} @@ -193,57 +317,99 @@ texio.write_nl("It works!") \subsection{lua modules} -For more informations about this part (and the attributes and catcodetables), see the documentation \texttt{luatextra.pdf}. +For more informations about this part (and the attributes and catcodetables), +see the documentation \texttt{luatextra.pdf}. -\LuaTeX tra provides the same kind of functions for lua modules as \LaTeX\ does for packages: it provides the macros \texttt{\string\luaUseModule} and \texttt{\string\luaRequireModule}, as well as the functions \texttt{luatextra.use\_module}, \texttt{luatextra.require\_module} and \texttt{luatextra.provides\_module}. +\LuaTeX tra provides the same kind of functions for lua modules as \LaTeX\ +does for packages: it provides the macros \texttt{\string\luaUseModule} and +\texttt{\string\luaRequireModule}, as well as the functions +\texttt{luatextra.use\_module}, \texttt{luatextra.require\_module} and +\texttt{luatextra.provides\_module}. -If you want to use a lua file mypackage.lua, you can safely use \texttt{\string\luaUseModule\{mypackage\}}: it will automatically load the file; and will load it only once if the function is called several times. You can also use \texttt{\string\luaRequireModule} that takes the minimal version (or date) as a second (optional under \LaTeX ) argument. +If you want to use a lua file mypackage.lua, you can safely use +\texttt{\string\luaUseModule\{mypackage\}}: it will automatically load the +file; and will load it only once if the function is called several times. You +can also use \texttt{\string\luaRequireModule} that takes the minimal version +(or date) as a second (optional under \LaTeX ) argument. -In a lua module, you have to call \texttt{luatextra.provides\_module}. It takes a table as an argument. This table must contain at least the fields \texttt{name}, \texttt{version}, \texttt{date} and \texttt{description}. You can also use the fields \texttt{author}, \texttt{copyright}, \texttt{license}, or any field you want. +In a lua module, you have to call \texttt{luatextra.provides\_module}. It +takes a table as an argument. This table must contain at least the fields +\texttt{name}, \texttt{version}, \texttt{date} and \texttt{description}. You +can also use the fields \texttt{author}, \texttt{copyright}, \texttt{license}, +or any field you want. See section \ref{sub:luatemplate} for an example of a lua module. \subsection{attributes} -We already talked about the most important function: \texttt{\string\newluaattribute}. It is the equivalent of \texttt{\string\newcount} for attributes. +We already talked about the most important function: +\texttt{\string\newluaattribute}. It is the equivalent of +\texttt{\string\newcount} for attributes. -Another important function is \texttt{\string\unsetluaattribute} that unsets an attribute. It's adised to use this macro instead of unsetting it by hand, as the unset value may change (it changed in version 0.37 from \texttt{-1} to \texttt{-"7FFFFFFF}). +Another important function is \texttt{\string\unsetluaattribute} that unsets +an attribute. It's adised to use this macro instead of unsetting it by hand, +as the unset value may change (it changed in version 0.37 from \texttt{-1} to +\texttt{-"7FFFFFFF}). -You can also use the macro \texttt{\string\setluaattribute} that takes an attribute and a value as arguments, and set the argument to the asked value. +You can also use the macro \texttt{\string\setluaattribute} that takes an +attribute and a value as arguments, and set the argument to the asked value. \subsection{catcodetables} -The equivalent of \texttt{\string\newcount} for catcodetables is \texttt{\string\newluacatcodetable}. Also a set of predefined catcodetables comes with \LuaTeX tra: +The equivalent of \texttt{\string\newcount} for catcodetables is +\texttt{\string\newluacatcodetable}. Also a set of predefined catcodetables +comes with \LuaTeX tra: \begin{itemize} -\item \texttt{\string\CatcodeTableIniTeX}: the base \TeX\ catcodes -\item \texttt{\string\CatcodeTableString}: almost all characters have catcode 12 -\item \texttt{\string\CatcodeTableOther}: all characters have catcode 12 (even space) -\item \texttt{\string\CatcodeTableLaTeX}: the \LaTeX\ classical catcodes + \item \texttt{\string\CatcodeTableIniTeX}: the base \TeX\ catcodes + \item \texttt{\string\CatcodeTableString}: almost all characters have + catcode 12 + \item \texttt{\string\CatcodeTableOther}: all characters have catcode 12 + (even space) + \item \texttt{\string\CatcodeTableLaTeX}: the \LaTeX\ classical catcodes \end{itemize} \subsection{callbacks} -For more informations about this part, see the documentation \texttt{luamcallbacks.pdf}. +For more informations about this part, see the documentation +\texttt{luamcallbacks.pdf}. -One of the main goals of \LuaTeX tra is also to provide a way for several packages to register their functions in one callback. The function \texttt{callback.register} does not provide any way to do so. To fix it, \LuaTeX tra provides the function \texttt{callback.add} that takes the same two first arguments as \texttt{callback.register} (name of the callback and function to register), and two other arguments: a mandatory description of the function, and an optional priority (the lower the number, the higher the priority). +One of the main goals of \LuaTeX tra is also to provide a way for several +packages to register their functions in one callback. The function +\texttt{callback.register} does not provide any way to do so. To fix it, +\LuaTeX tra provides the function \texttt{callback.add} that takes the same +two first arguments as \texttt{callback.register} (name of the callback and +function to register), and two other arguments: a mandatory description of the +function, and an optional priority (the lower the number, the higher the +priority). -If people use \texttt{callback.register} all the \LuaTeX tra mechanism is broken, so we override \texttt{callback.register} with a function that simply outputs an error message. +If people use \texttt{callback.register} all the \LuaTeX tra mechanism is +broken, so we override \texttt{callback.register} with a function that simply +outputs an error message. Three other very useful new functions are provided: \begin{itemize} -\item \texttt{callback.remove} takes the name of a callback and the description of a register function (third argument of \texttt{callback.add}), and removes the function from a callback. -\item \texttt{callback.reset} removes all register functions from a callback. -\item \texttt{callback.get\_priority} takes the name of a callback and the description of a registered function, and returns the priority of the function in the callback, or 0 if the function is not registered. + \item \texttt{callback.remove} takes the name of a callback and the + description of a register function (third argument of + \texttt{callback.add}), and removes the function from a callback. + \item \texttt{callback.reset} removes all register functions from a + callback. + \item \texttt{callback.get\_priority} takes the name of a callback and the + description of a registered function, and returns the priority of the + function in the callback, or 0 if the function is not registered. \end{itemize} - \subsection{lua extra functions} -Some extra functions have been added to the standard lua library, mostly coming from the Con\TeX t libraries, for the complete list of functions, please refer to the documentation \texttt{luaextra.pdf}. +Some extra functions have been added to the standard lua library, mostly +coming from the Con\TeX t libraries, for the complete list of functions, +please refer to the documentation \texttt{luaextra.pdf}. -The most useful of these added functions is certainly \texttt{table.serialize} that returns the string describing a given table. This string can be used for debugging purposes, or table saving in files, as the string can be read by lua to rebuild the original table. +The most useful of these added functions is certainly \texttt{table.serialize} +that returns the string describing a given table. This string can be used for +debugging purposes, or table saving in files, as the string can be read by lua +to rebuild the original table. \subsection{\texttt{.lua} module template\label{sub:luatemplate}} diff --git a/Master/texmf-dist/source/luatex/luatextra/luatextra.dtx b/Master/texmf-dist/source/luatex/luatextra/luatextra.dtx index 62c763d8484..3265121c2c6 100644 --- a/Master/texmf-dist/source/luatex/luatextra/luatextra.dtx +++ b/Master/texmf-dist/source/luatex/luatextra/luatextra.dtx @@ -34,7 +34,7 @@ \input docstrip.tex \Msg{************************************************************************} \Msg{* Installation} -\Msg{* Package: luatextra 2009/04/15 v0.93 Additional low level functions for LuaTeX} +\Msg{* Package: luatextra 2009/09/22 v0.94 Extra low level functions for LuaTeX} \Msg{************************************************************************} \keepsilent @@ -64,7 +64,8 @@ and the derived files \file{luatextra-latex.tex}{\from{luatextra.dtx}{latex}}% } -% The following hacks are to generate a lua file with lua comments starting by -- instead of %% +% The following hacks are to generate a lua file with lua comments starting by +% -- instead of %% \def\MetaPrefix{-- } @@ -100,7 +101,7 @@ and the derived files %<*driver> \NeedsTeXFormat{LaTeX2e} \ProvidesFile{luaminimalotf.drv}% - [2009/04/15 v0.93 LuaTeX extra low-level macros.]% + [2009/09/22 v0.94 LuaTeX extra low-level macros.]% \documentclass{ltxdoc} \EnableCrossrefs \CodelineIndex @@ -131,13 +132,14 @@ and the derived files % \GetFileInfo{luatextra.drv} % % \title{The \textsf{luatextra} package} -% \date{2009/04/15 v0.93} +% \date{2009/09/22 v0.94} % \author{Elie Roux \\ \texttt{elie.roux@telecom-bretagne.eu}} % % \maketitle % % \begin{abstract} -% \textsf{luatextra} provides low-level addition to the formats Plain and \LaTeX\ to be used with the engine Lua\TeX. +% \textsf{luatextra} provides low-level addition to the formats Plain and +% \LaTeX\ to be used with the engine Lua\TeX. % \end{abstract} % % \tableofcontents @@ -146,41 +148,98 @@ and the derived files % % \subsection{Preamble} % -% This document is made for people wanting to understand how the package was made. For an introduction to the use of Lua\TeX\ with the formats Plain and \LaTeX , please read the document \texttt{luatextra-reference.pdf} that you can find in your \TeX\ distribution (\TeX Live from version 2009) or on the CTAN. -% -% \subsection{History of formats and engines} -% -% To understand this package, one must fist understand some historical choices in the \TeX\ world. -% -% A \TeX\ engine is a binary executable that provides some very low-level primitives, for example \texttt{\string\count} to set a counter to a certain value. A \TeX\ format is a macro package that provides higher-level macros for the user and the package developer, for example \texttt{\string\newcount} that allocates a new counter and gives it a name. Examples of engines are the old \TeX\ 82, $\varepsilon$-\TeX, pdf\TeX, Omega/Aleph, Lua\TeX\ and Xe\TeX. Examples of formats are Plain, \LaTeX\ and Con\TeX t. -% -% This distinction is hard to make as only one command is invoked, for example when you call the command \texttt{tex}, you often have no idea that the engine \TeX\ 82 is invoked with the format Plain. +% This document is made for people wanting to understand how the package was +% made. For an introduction to the use of Lua\TeX\ with the formats Plain and +% \LaTeX , please read the document \texttt{luatextra-reference.pdf} that you +% can find in your \TeX\ distribution (\TeX Live from version 2009) or on the +% CTAN. % -% Evolution is also something confusing in the \TeX\ world: engines often evolve, and new engines have always appeared, when most formats are frozen: the Plain and \LaTeX\ formats do not accept any new code to cope with the new engines. In theory, this package shouldn't exist, or at least shouldn't be a package, but its code should be integrated into a format. But as Plain and \LaTeX\ are frozen, people wanting to take advantage of the new engines have to use a package. +% \subsection{History of formats and engines} % -% This package is really necessary to take advantage of Lua\TeX\ as it provides things users are expecting a macro package to provide, for example \texttt{\string\newluaattribute} that acts like \texttt{\string\newcount} for lua attributes. It also enables all Lua\TeX\ primitives, that are disabled by default. +% To understand this package, one must fist understand some historical choices +% in the \TeX\ world. +% +% A \TeX\ engine is a binary executable that provides some very low-level +% primitives, for example \texttt{\string\count} to set a counter to a certain +% value. A \TeX\ format is a macro package that provides higher-level macros +% for the user and the package developer, for example +% \texttt{\string\newcount} that allocates a new counter and gives it a name. +% Examples of engines are the old \TeX\ 82, $\varepsilon$-\TeX, pdf\TeX, +% Omega/Aleph, Lua\TeX\ and Xe\TeX. Examples of formats are Plain, \LaTeX\ and +% Con\TeX t. +% +% This distinction is hard to make as only one command is invoked, for example +% when you call the command \texttt{tex}, you often have no idea that the +% engine \TeX\ 82 is invoked with the format Plain. +% +% Evolution is also something confusing in the \TeX\ world: engines often +% evolve, and new engines have always appeared, when most formats are frozen: +% the Plain and \LaTeX\ formats do not accept any new code to cope with the +% new engines. In theory, this package shouldn't exist, or at least shouldn't +% be a package, but its code should be integrated into a format. But as Plain +% and \LaTeX\ are frozen, people wanting to take advantage of the new engines +% have to use a package. +% +% This package is really necessary to take advantage of Lua\TeX\ as it +% provides things users are expecting a macro package to provide, for example +% \texttt{\string\newluaattribute} that acts like \texttt{\string\newcount} +% for lua attributes. It also enables all Lua\TeX\ primitives, that are +% disabled by default. % % \subsection{choices made in this package} % -% In the very long term, it is higly possible that Lua\TeX\ will replace pdf\TeX\ as the default \LaTeX\ engine, so it is necessary to keep backward compatibility. This lead us to the decision of renaming Lua\TeX -only primitives so that they all start by \texttt{lua}, like the pdf\TeX -only primitives start by \texttt{pdf}. Thus attributes become luaattributes, \texttt{\string\directlua} becomes \texttt{\string\luadirect}, etc. This also allows primitives to keep having the same name, even if their name is changed later at the engine level. +% In the very long term, it is higly possible that Lua\TeX\ will replace +% pdf\TeX\ as the default \LaTeX\ engine, so it is necessary to keep backward +% compatibility. This lead us to the decision of renaming Lua\TeX -only +% primitives so that they all start by \texttt{luatex}, like the pdf\TeX -only +% primitives start by \texttt{pdf}. Thus attributes become luatexattributes, +% etc. This % also allows primitives to keep having the same name, even if their +% name is changed later at the engine level. Also some new functions like +% \texttt{newluatexattribute} are provided with the \texttt{lua} prefix, to +% shorten the already too long name. % % \subsection{registers allocation scheme} % -% The default register allocation scheme of \LaTeX\ is old and limited (like the one of \TeX 82) to 256 values. The engine $\varepsilon$-\TeX allows more different registers (up to 32768), and Lua\TeX\ allows even 65536 ones. These new limits were not acknowledged by \LaTeX . A package \textsf{etex} was created for \LaTeX\ to extends the allocation scheme. \textsf{luatextra} loads \textsf{etex}, and overrides somes values to extend the allocation max number to 65536. +% The default register allocation scheme of \LaTeX\ is old and limited (like +% the one of \TeX 82) to 256 values. The engine $\varepsilon$-\TeX allows more +% different registers (up to 32768), and Lua\TeX\ allows even 65536 ones. +% These new limits were not acknowledged by \LaTeX . A package \textsf{etex} +% was created for \LaTeX\ to extends the allocation scheme. \textsf{luatextra} +% loads \textsf{etex}, and overrides somes values to extend the allocation max +% number to 65536. % % \subsection{attributes} -% -% Attributes are a new concept in Lua\TeX\ (see the Lua\TeX\ documentation for details). As the macro \texttt{\string\attribute} is certainly very common in the user's documents, they are renamed \texttt{luaattribute}s. This package provides a simple way to allocate new attributes, with the macro \texttt{\string\newluaattribute}. For more informations about attribute handling in lua, please read section \ref{sub:attr}. -% +% +% Attributes are a new concept in Lua\TeX\ (see the Lua\TeX\ documentation for +% details). As the macro \texttt{\string\attribute} is certainly very common +% in the user's documents, they are renamed \texttt{luaattribute}s. This +% package provides a simple way to allocate new attributes, with the macro +% \texttt{\string\newluaattribute}. For more informations about attribute +% handling in lua, please read section \ref{sub:attr}. +% % \subsection{Module system} % -% Lua has some embedded module management, with the functions \texttt{module} and \texttt{require}. With this package we try get more control on the module system, by implementing something close to the \LaTeX 's \texttt{\string\usepackage} and \texttt{\string\RequirePackage} macros: the \texttt{\string\luaUseModule} and \texttt{\string\luaRequireModule} that act like them, but for lua files. The functions \texttt{module} and \texttt{require} should not be used, in profit of the lua functions \texttt{luatextra.provides\_module} and \texttt{luatextra.use\_module} or \texttt{luatextra.require\_module}. +% Lua has some embedded module management, with the functions \texttt{module} +% and \texttt{require}. With this package we try get more control on the +% module system, by implementing something close to the \LaTeX 's +% \texttt{\string\usepackage} and \texttt{\string\RequirePackage} macros: the +% \texttt{\string\luatexUseModule} and \texttt{\string\luatexRequireModule} that act +% like them, but for lua files. The functions \texttt{module} and +% \texttt{require} should not be used, in profit of the lua functions +% \texttt{luatextra.provides\_module} and \texttt{luatextra.use\_module} or +% \texttt{luatextra.require\_module}. % % \subsection{Multiple callbacks handling} % -% Lua\TeX\ has no way to register multiple functions in a callback. This package loads \textsf{luamcallbacks} that provides a safe way to do so. But the \textsf{luamcallbacks} package can't register several functions in some callbacks, like \texttt{open\_read\_file} and \texttt{define\_font}. This package takes advantage of the callback creation possibilities of \textsf{luamcallbacks} to split these callbacks into several ones that can agregate several functions. Thus it allows several packages to safely use the callbacks. See section \ref{sub:orf} for more details. +% Lua\TeX\ has no way to register multiple functions in a callback. This +% package loads \textsf{luamcallbacks} that provides a safe way to do so. But +% the \textsf{luamcallbacks} package can't register several functions in some +% callbacks, like \texttt{open\_read\_file} and \texttt{define\_font}. This +% package takes advantage of the callback creation possibilities of +% \textsf{luamcallbacks} to split these callbacks into several ones that can +% agregate several functions. Thus it allows several packages to safely use +% the callbacks. See section \ref{sub:orf} for more details. % -% % \section{\texttt{luatextra.lua}} % % \subsection{Initialization and internal functions} @@ -189,9 +248,14 @@ and the derived files %<*lua> % \fi % -% \TeX\ always prints the names of the files that are input. Unfortunatly it can't do so with lua files called with \texttt{dofile}. We will fix it with the \texttt{luatextra.use\_module} function, but in the meantime we print this information for the \texttt{luatextra.lua} file. +% \TeX\ always prints the names of the files that are input. Unfortunatly +% it can't do so with lua files called with \texttt{dofile}. We will fix it +% with the \texttt{luatextra.use\_module} function, but in the meantime we +% print this information for the \texttt{luatextra.lua} file. % -% A change compared to usual filename printings is the fact that Lua\TeX\ does not print the \texttt{./} for files in the current directory. We keep this convention for lua filename printings. +% A change compared to usual filename printings is the fact that Lua\TeX\ +% does not print the \texttt{./} for files in the current directory. We +% keep this convention for lua filename printings. % % \begin{macrocode} do @@ -200,13 +264,14 @@ do if luatextrapath:sub(1,2) == "./" then luatextrapath = luatextrapath:sub(3) end - texio.write(' ('..luatextrapath) + texio.write(' ('..luatextrapath) end end % \end{macrocode} % -% We create the \texttt{luatextra} table that will contain all the functions and variables, and we register it as a normal lua module. +% We create the \texttt{luatextra} table that will contain all the +% functions and variables, and we register it as a normal lua module. % % \begin{macrocode} @@ -216,16 +281,20 @@ module("luatextra", package.seeall) % \end{macrocode} % -% We initiate the modules table that will contain informations about the loaded modules. And we register the \texttt{luatextra} module. The informations contained in the table describing the module are always the same, it can be taken as a template. See \texttt{luatextra.provides\_module} for more details. +% We initiate the modules table that will contain informations about the +% loaded modules. And we register the \texttt{luatextra} module. The +% informations contained in the table describing the module are always the +% same, it can be taken as a template. See +% \texttt{luatextra.provides\_module} for more details. % % \begin{macrocode} luatextra.modules = {} luatextra.modules['luatextra'] = { - version = 0.93, + version = 0.94, name = "luatextra", - date = "2009/04/15", + date = "2009/09/22", description = "Additional low level functions for LuaTeX", author = "Elie Roux", copyright = "Elie Roux, 2009", @@ -236,7 +305,8 @@ local format = string.format % \end{macrocode} % -% Here we define the warning and error functions specific to \texttt{luatextra}. +% Here we define the warning and error functions specific to +% \texttt{luatextra}. % % \begin{macrocode} @@ -258,7 +328,11 @@ end % % \subsection{Error, warning and info function for modules} % -% Some module printing functions are provided, they have the same philosophy as the \LaTeX 's \texttt{\string\PackageError} and \texttt{\string\PackageWarning} macros: their first argument is the name of the module, and the second is the message. These functions are meant to be used by lua module writers. +% Some module printing functions are provided, they have the same +% philosophy as the \LaTeX 's \texttt{\string\PackageError} and +% \texttt{\string\PackageWarning} macros: their first argument is the name +% of the module, and the second is the message. These functions are meant +% to be used by lua module writers. % % \begin{macrocode} @@ -269,7 +343,7 @@ function luatextra.module_error(package, msg, helpmsg) if helpmsg then tex.sprint(format("\\errhelp{%s}", helpmsg)) end - tex.sprint(format("\\luaModuleError{%s}{%s}", package, msg)) + tex.sprint(format("\\luatexModuleError{%s}{%s}", package, msg)) end function luatextra.module_warning(modulename, msg) @@ -302,9 +376,10 @@ end % \end{macrocode} % -% \subsection{module loading and providing functions} +% \subsection{module loading and providing functions} % -% A small function to find a lua module file according to its name, with or without the \texttt{.lua} at the end of the filename. +% A small function to find a lua module file according to its name, with or +% without the \texttt{.lua} at the end of the filename. % % \begin{macrocode} @@ -321,7 +396,8 @@ end % \end{macrocode} % -% A small patch, for the \texttt{module} function to work in this file. I can't understand why it doens't otherwise. +% A small patch, for the \texttt{module} function to work in this file. I +% can't understand why it doens't otherwise. % % \begin{macrocode} @@ -329,9 +405,12 @@ luatextra.module = module % \end{macrocode} % -% \begin{macro}{luatextra.use module} +% \begin{macro}{luatextra.use module} % -% This macro is the one used to simply load a lua module file. It does not reload it if it's already loaded, and prints the filename in the terminal and the log. A lua module must call the macro \texttt{luatextra.provides\_module}. +% This macro is the one used to simply load a lua module file. It does not +% reload it if it's already loaded, and prints the filename in the terminal +% and the log. A lua module must call the macro +% \texttt{luatextra.provides\_module}. % % \begin{macrocode} @@ -361,9 +440,12 @@ end % \end{macrocode} % -% \end{macro} +% \end{macro} % -% Some internal functions to convert a date into a number, and to determine if a string is a date. It is useful for \texttt{luatextra.require\_package} to understand if a user asks a version with a date or a version number. +% Some internal functions to convert a date into a number, and to determine +% if a string is a date. It is useful for +% \texttt{luatextra.require\_package} to understand if a user asks a +% version with a date or a version number. % % \begin{macrocode} @@ -393,9 +475,11 @@ luatextra.requiredversions = {} % \end{macrocode} % -% \begin{macro}{luatextra.require module} +% \begin{macro}{luatextra.require module} % -% This function is like the \texttt{luatextra.use\_module} function, but can accept a second argument that checks for the version of the module. The version can be a number or a date (format yyyy/mm/dd). +% This function is like the \texttt{luatextra.use\_module} function, but +% can accept a second argument that checks for the version of the module. +% The version can be a number or a date (format yyyy/mm/dd). % % \begin{macrocode} @@ -425,13 +509,19 @@ end % \end{macrocode} % -% \end{macro} +% \end{macro} % -% \begin{macro}{luatextra.provides module} +% \begin{macro}{luatextra.provides module} % -% This macro is the one that must be called in the module files. It takes a table as argument. You can put any information you want in this table, but the mandatory ones are \texttt{name} (a string), \texttt{version} (a number), \texttt{date} (a string) and \texttt{description} (a string). Other fields are usually \texttt{copyright}, \texttt{author} and \texttt{license}. +% This macro is the one that must be called in the module files. It takes a +% table as argument. You can put any information you want in this table, +% but the mandatory ones are \texttt{name} (a string), \texttt{version} (a +% number), \texttt{date} (a string) and \texttt{description} (a string). +% Other fields are usually \texttt{copyright}, \texttt{author} and +% \texttt{license}. % -% This function logs informations about the module the same way \LaTeX\ does for informations about packages. +% This function logs informations about the module the same way \LaTeX\ +% does for informations about packages. % % \begin{macrocode} @@ -458,9 +548,11 @@ end % \end{macrocode} % -% \end{macro} +% \end{macro} % -% Here we load the \textsf{luaextra} module, that contains a bunch of very useful functions. See the documentation of \textsf{luaextra} for more details. +% Here we load the \textsf{luaextra} module, that contains a bunch of very +% useful functions. See the documentation of \textsf{luaextra} for more +% details. % % \begin{macrocode} @@ -468,7 +560,10 @@ luatextra.use_module('luaextra') % \end{macrocode} % -% \texttt{luatextra.kpse\_module\_loader} finds a module with the \texttt{kpse} library. This function is then registered in the table of the functions used by the lua function \texttt{require} to look for modules. +% \texttt{luatextra.kpse\_module\_loader} finds a module with the +% \texttt{kpse} library. This function is then registered in the table of +% the functions used by the lua function \texttt{require} to look for +% modules. % % \begin{macrocode} @@ -490,9 +585,23 @@ table.insert(package.loaders, luatextra.kpse_module_loader) % \end{macrocode} % -% \subsection{Attributes handling\label{sub:attr}} -% -% Attribute allocation is done mainly in the \texttt{sty} file, but there is also a lua addition for attribute handling: Lua\TeX\ is by default unable to tell the attribute number corresponding to an attribute name. This attribute number is necessary for functions such as \texttt{node.has\_attribute}, which is used very often. The solution until now was to give a chosen attribute number to each attribute, and pray that someone else didn't use it before. With this method it was easy to know the number of an attribute, as it was chosen. Now with the \texttt{\string\newluaattribute} macro, it's impossible to know the number of an attribute. To fix it, when \texttt{\string\newluaattribute} is called, it calls \texttt{luatextra.attributedef\_from\_tex}. This function registers the number in the table \texttt{tex.attributenumber}. For example to get the number of the attribute \texttt{myattribute} registered with \texttt{\string\newluaattribute\string\myattribute}, you can simply call \texttt{tex.attributenumber[myattribute]}. +% \subsection{Attributes handling\label{sub:attr}} +% +% Attribute allocation is done mainly in the \texttt{sty} file, but there +% is also a lua addition for attribute handling: Lua\TeX\ is by default +% unable to tell the attribute number corresponding to an attribute name. +% This attribute number is necessary for functions such as +% \texttt{node.has\_attribute}, which is used very often. The solution +% until now was to give a chosen attribute number to each attribute, and +% pray that someone else didn't use it before. With this method it was easy +% to know the number of an attribute, as it was chosen. Now with the +% \texttt{\string\newluaattribute} macro, it's impossible to know the +% number of an attribute. To fix it, when \texttt{\string\newluaattribute} +% is called, it calls \texttt{luatextra.attributedef\_from\_tex}. This +% function registers the number in the table \texttt{tex.attributenumber}. +% For example to get the number of the attribute \texttt{myattribute} +% registered with \texttt{\string\newluaattribute\string\myattribute}, you +% can simply call \texttt{tex.attributenumber[myattribute]}. % % \begin{macrocode} @@ -509,7 +618,9 @@ end % % \subsection{Catcodetables handling} % -% In the same way, the table \texttt{tex.catcodetablenumber} contains the numbers of the catcodetables registered with \texttt{\string\newluacatcodetable}. +% In the same way, the table \texttt{tex.catcodetablenumber} contains the +% numbers of the catcodetables registered with +% \texttt{\string\newluacatcodetable}. % % \begin{macrocode} @@ -524,19 +635,36 @@ end % \end{macrocode} % -% \subsection{Multiple callbacks on the \texttt{open\_read\_file} callback\label{sub:orf}} -% -% The luamcallbacks (see documentation for details) cannot really provide a simple and reliable way of registering multiple functions in some callbacks. To be able to do so, the solution we implemented is to register one function in these callbacks, and to create "sub-callbacks" that can accept several functions. That's what we do here for the callback \texttt{open\_read\_file}. -% -% \begin{macro}{luatextra.open read file} -% -% This function is the one that will be registered in the callback. It calls new callbacks, that will be created later. These callbacks are: -% -%\begin{itemize} -% \item \texttt{pre\_read\_file} in which you can register a function with the signature \texttt{pre\_read\_file(env)}, with \texttt{env} being a table containing the fields \texttt{filename} which is the argument of the callback \texttt{open\_read\_file}, and \texttt{path} which is the result of \texttt{kpse.find\_file}. You can put any field you want in the \texttt{env} table, you can even override the existing fields. This function is called at the very beginning of the callback, it allows for instance to register functions in the other callbacks. It is useless to add a field \texttt{reader} or \texttt{close}, as they will be overriden. -% \item \texttt{file\_reader} is automatically registered in the \texttt{reader} callback for every file, it has the same signature. -% \item \texttt{file\_close} is registered in the \texttt{close} callback for every file, and has the same signature. -%\end{itemize} +% \subsection{Multiple callbacks on the \texttt{open\_read\_file} +% callback\label{sub:orf}} +% +% The luamcallbacks (see documentation for details) cannot really provide a +% simple and reliable way of registering multiple functions in some +% callbacks. To be able to do so, the solution we implemented is to +% register one function in these callbacks, and to create "sub-callbacks" +% that can accept several functions. That's what we do here for the +% callback \texttt{open\_read\_file}. +% +% \begin{macro}{luatextra.open read file} +% +% This function is the one that will be registered in the callback. It +% calls new callbacks, that will be created later. These callbacks are: +% +% \begin{itemize} +% \item \texttt{pre\_read\_file} in which you can register a function with +% the signature \texttt{pre\_read\_file(env)}, with \texttt{env} being a +% table containing the fields \texttt{filename} which is the argument of +% the callback \texttt{open\_read\_file}, and \texttt{path} which is the +% result of \texttt{kpse.find\_file}. You can put any field you want in the +% \texttt{env} table, you can even override the existing fields. This +% function is called at the very beginning of the callback, it allows for +% instance to register functions in the other callbacks. It is useless to +% add a field \texttt{reader} or \texttt{close}, as they will be overriden. +% \item \texttt{file\_reader} is automatically registered in the +% \texttt{reader} callback for every file, it has the same signature. +% \item \texttt{file\_close} is registered in the \texttt{close} callback +% for every file, and has the same signature. +% \end{itemize} % % \begin{macrocode} @@ -568,11 +696,11 @@ end % % \end{macro} % -% The two next functions are the one called in the \texttt{open\_read\_file} callback. +% The two next functions are the one called in the +% \texttt{open\_read\_file} callback. % % \begin{macrocode} - function luatextra.reader(env) local line = (env.file):read() line = luamcallbacks.call('file_reader', env, line) @@ -586,11 +714,13 @@ end % \end{macrocode} % -% In the callback creation process we need to have default behaviours. Here they are. These are called only when no function is registered in the created callback. See the documentation of \texttt{luamcallbacks} for more details. +% In the callback creation process we need to have default behaviours. Here +% they are. These are called only when no function is registered in the +% created callback. See the documentation of \texttt{luamcallbacks} for +% more details. % % \begin{macrocode} - function luatextra.default_reader(env, line) return line end @@ -605,21 +735,41 @@ end % \end{macrocode} % -% \subsection{Multiple callbacks on the \texttt{define\_font} callback\label{sub:df}} -% -% The same principle is applied to the \texttt{define\_font} callback. The main difference is that this mechanism is not applied by default. The reason is that the callback most people will register in the \texttt{define\_font} callback is the one from Con\TeX t allowing the use of OT fonts. When the code will be more adapted (not so soon certainly), this mechanism will certainly be used, as it allows more flexibility in the font syntax, the OT font load mechanism, etc. -% -% The callbacks we register here are the following ones: -% -% \begin{itemize} -% \item \texttt{font\_syntax} that takes a table with the fields \texttt{asked\_name}, \texttt{name} and \texttt{size}, and modifies this table to add more information. It must add at least a \texttt{path} field. The structure of the final table is not precisely defined, as it can vary from one syntax to another. -% \item \texttt{open\_otf\_font} takes the previous table, and must return a valid font structure as described in the Lua\TeX\ manual. -% \item \texttt{post\_font\_opening} takes the final font table and can modify it, before this table is returned to the \texttt{define\_font} callback. -% \end{itemize} -% -% But first, we acknowledge the fact that \texttt{fontforge} has been renamed to \texttt{fontloader}. This check allows older versions of Lua\TeX\ to use \texttt{fontloader}. -% -% As this mechanism is not loaded by default and certainly won't be until version 1.0 of Lua\TeX , we don't document it further. See the documentation of \texttt{luatextra.sty} (macro \texttt{\string\ltxtra\string@RegisterFontCallback}) to know how to load this mechanism anyway. +% \subsection{Multiple callbacks on the \texttt{define\_font} +% callback\label{sub:df}} +% +% The same principle is applied to the \texttt{define\_font} callback. The +% main difference is that this mechanism is not applied by default. The +% reason is that the callback most people will register in the +% \texttt{define\_font} callback is the one from Con\TeX t allowing the use +% of OT fonts. When the code will be more adapted (not so soon certainly), +% this mechanism will certainly be used, as it allows more flexibility in +% the font syntax, the OT font load mechanism, etc. +% +% The callbacks we register here are the following ones: +% +% \begin{itemize} +% \item \texttt{font\_syntax} that takes a table with the fields +% \texttt{asked\_name}, \texttt{name} and \texttt{size}, and modifies this +% table to add more information. It must add at least a \texttt{path} +% field. The structure of the final table is not precisely defined, as it +% can vary from one syntax to another. +% \item \texttt{open\_otf\_font} takes the previous table, and must return +% a valid font structure as described in the Lua\TeX\ manual. +% \item \texttt{post\_font\_opening} takes the final font table and can +% modify it, before this table is returned to the \texttt{define\_font} +% callback. +% \end{itemize} +% +% But first, we acknowledge the fact that \texttt{fontforge} has been +% renamed to \texttt{fontloader}. This check allows older versions of +% Lua\TeX\ to use \texttt{fontloader}. +% +% As this mechanism is not loaded by default and certainly won't be until +% version 1.0 of Lua\TeX , we don't document it further. See the +% documentation of \texttt{luatextra.sty} (macro +% \texttt{\string\ltxtra\string@RegisterFontCallback}) to know how to load +% this mechanism anyway. % % \begin{macrocode} @@ -730,9 +880,9 @@ end %<*package> % \fi % -% \subsection{Initializations} +% \subsection{Initializations} % -% First we prevent multiple loads of the file (useful for plain-\TeX ). +% First we prevent multiple loads of the file (useful for plain-\TeX ). % % \begin{macrocode} \csname ifluatextraloaded\endcsname @@ -740,7 +890,7 @@ end % \end{macrocode} % -% Then we load \textsf{ifluatex}. +% Then we load \textsf{ifluatex}. % % \begin{macrocode} @@ -755,18 +905,23 @@ end \expandafter\ifx\csname ProvidesPackage\endcsname\relax % \end{macrocode} % -% If the package is loaded with Plain, we raise an error if the package is called with a non-Lua\TeX\ engine, and we define \texttt{\string\luaRequireModule} with two mandatory arguments. +% If the package is loaded with Plain, we raise an error if the package is +% called with a non-Lua\TeX\ engine, and we define +% \texttt{\string\luaRequireModule} with two mandatory arguments. % % \begin{macrocode} \ifluatex\else \immediate\write16{} \errmessage{Package luatextra Error: This package must be used with LuaTeX} \fi - \def\luaRequireModule#1#2{\luadirect{luatextra.require_module([[#1]], [[#2]])}} + \def\luatexRequireModule#1#2{\luadirect{luatextra.require_module([[#1]], [[#2]])}} \else % \end{macrocode} % -% If the package is loaded with \LaTeX , we also print the error message, and we define \texttt{\string\luaRequireModule} with one mandatory argument (the name of the package) and one optional (the version or the date). We also define the environment \texttt{luacode}. +% If the package is loaded with \LaTeX , we also print the error message, +% and we define \texttt{\string\luaRequireModule} with one mandatory +% argument (the name of the package) and one optional (the version or the +% date). We also define the environment \texttt{luacode}. % % \begin{macrocode} \ifluatex\else @@ -777,10 +932,17 @@ end [2009/04/15 v0.93 LuaTeX extra low-level macros] \RequirePackage{environ} \NewEnviron{luacode}{\luadirect{\BODY}} - \newcommand\luaRequireModule[2][0]{\luadirect{luatextra.require_module([[#2]], [[#1]])}} + \newcommand\luatexRequireModule[2][0]{\luadirect{luatextra.require_module([[#2]], [[#1]])}} % \end{macrocode} % -% We also require the package \textsf{etex} to be loaded. The \texttt{\string\input} is a hack that modifies some values in the register attribution scheme of $\varepsilon$-\TeX\ and remaps \texttt{\string\newcount} to \textsf{etex}'s \texttt{\string\globcount}. We have to do such a remapping in a separate file that Plain doesn't see, otherwise it outputs an error if we try to change \texttt{\string\newcount} (because it is an \texttt{\string\outer} macro). See section \ref{sub:latex} for the file content. +% We also require the package \textsf{etex} to be loaded. The +% \texttt{\string\input} is a hack that modifies some values in the +% register attribution scheme of $\varepsilon$-\TeX\ and remaps +% \texttt{\string\newcount} to \textsf{etex}'s \texttt{\string\globcount}. +% We have to do such a remapping in a separate file that Plain doesn't see, +% otherwise it outputs an error if we try to change +% \texttt{\string\newcount} (because it is an \texttt{\string\outer} +% macro). See section \ref{sub:latex} for the file content. % % \begin{macrocode} \RequirePackage{etex}[1998/03/26]% @@ -789,7 +951,9 @@ end % \end{macrocode} % -% The two macros \texttt{\string\LuaTeX} and \texttt{\string\LuaLaTeX} are defined to Lua\TeX\ and Lua\LaTeX , because that's the way it's written in the Lua\TeX 's manual (not in small capitals). +% The two macros \texttt{\string\LuaTeX} and \texttt{\string\LuaLaTeX} are +% defined to Lua\TeX\ and Lua\LaTeX , because that's the way it's written +% in the Lua\TeX 's manual (not in small capitals). % % \begin{macrocode} @@ -800,54 +964,69 @@ end % % \subsection{Primitives renaming} % -% Here we differenciate two very different cases: Lua\TeX\ version < 0.36 has no \texttt{tex.enableprimitives} function, and has support for multiple lua states, and for versions > 0.35, the \texttt{tex.enableprimitives} is provided, and the old \texttt{\string\directlua} syntax prints a warning. +% Here we differenciate two very different cases: Lua\TeX\ version < 0.36 +% has no \texttt{tex.enableprimitives} function, and has support for +% multiple lua states, and for versions > 0.35, the +% \texttt{tex.enableprimitives} is provided, and the old +% \texttt{\string\directlua} syntax prints a warning. % % \begin{macrocode} \ifnum\luatexversion<36 % \end{macrocode} % -% For old versions, we simply rename the primitives. You can note that \texttt{\string\attribute} (and also others) have no \texttt{\string\primitive} before them, because it would make users unable to call \texttt{\string\global\string\luaattribute}, which is a strong restriction. With this method, we can call it, but if \texttt{\string\attribute} was defined before, this means that \texttt{\string\luaattribute} will get its meaning, which is dangerous. Note also that you cannot use multiple states. +% For old versions, we simply rename the primitives. You can note that +% \texttt{\string\attribute} (and also others) have no +% \texttt{\string\primitive} before them, because it would make users +% unable to call \texttt{\string\global\string\luaattribute}, which is a +% strong restriction. With this method, we can call it, but if +% \texttt{\string\attribute} was defined before, this means that +% \texttt{\string\luaattribute} will get its meaning, which is dangerous. +% Note also that you cannot use multiple states. % % \begin{macrocode} \def\directlua{\pdfprimitive\directlua0} \def\latelua{\pdfprimitive\latelua0} \def\luadirect{\pdfprimitive\directlua0} \def\lualate{\pdfprimitive\latelua0} - \def\luaattribute{\attribute} - \def\luaattributedef{\attributedef} - \def\luaclearmarks{\pdfprimitive\luaclearmarks} - \def\luaformatname{\pdfprimitive\formatname} - \def\luascantexttokens{\pdfprimitive\scantexttokens} - \def\luacatcodetable{\catcodetable} + \def\luatexattribute{\attribute} + \def\luatexattributedef{\attributedef} + \def\luatexclearmarks{\pdfprimitive\luaclearmarks} + \def\luatexformatname{\pdfprimitive\formatname} + \def\luatexscantexttokens{\pdfprimitive\scantexttokens} + \def\luatexcatcodetable{\catcodetable} + \def\initluatexcatcodetable{\pdfprimitive\initcatcodetable} + \def\saveluatexcatcodetable{\pdfprimitive\savecatcodetable} + \def\luaclose{\pdfprimitive\closelua} \else % \end{macrocode} % -% For newer versions, we first enable all primitives with their default name. Then we add a prefix to some. Note that with this method, \texttt{\string\luaattribute} will always have the good meaning (except, of course, if it was defined before, but I think we can call it perversion...). +% From TeXLive 2009, all primitives should be provided with the |luatex| +% prefix. For TeXLive 2008, we provide some primitives with this prefix too, +% to keep backward compatibility. % % \begin{macrocode} - \directlua{tex.enableprimitives('lua', {'attribute'})} - \directlua{tex.enableprimitives('lua', {'attributedef'})} - \directlua{tex.enableprimitives('lua', {'clearmarks'})} - \directlua{tex.enableprimitives('lua', {'formatname'})} - \directlua{tex.enableprimitives('lua', {'scantexttokens'})} - \directlua{tex.enableprimitives('lua', {'catcodetable'})} - \def\luadirect{\pdfprimitive\directlua} - \def\lualate{\pdfprimitive\latelua} + \directlua{tex.enableprimitives('luatex', {'attribute'})} + \directlua{tex.enableprimitives('luatex', {'attributedef'})} + \directlua{tex.enableprimitives('luatex', {'clearmarks'})} + \directlua{tex.enableprimitives('luatex', {'formatname'})} + \directlua{tex.enableprimitives('luatex', {'scantexttokens'})} + \directlua{tex.enableprimitives('luatex', {'catcodetable'})} + \directlua{tex.enableprimitives('luatex', {'latelua'})} + \directlua{tex.enableprimitives('luatex', {'initcatcodetable'})} + \directlua{tex.enableprimitives('luatex', {'savecatcodetable'})} + \directlua{tex.enableprimitives('luatex', {'closelua'})} + \let\luadirect\directlua + \let\lualate\luatexlatelua + \let\initluatexcatcodetable\luatexinitcatcodetable + \let\saveluatexcatcodetable\luatexsavecatcodetable + \let\luaclose\luatexcloselua \fi -% \end{macrocode} -% -% Finally we add some common definitions that have lua inside their name, or that must remove their suffix. -% -% \begin{macrocode} -\def\initluacatcodetable{\pdfprimitive\initcatcodetable} -\def\saveluacatcodetable{\pdfprimitive\savecatcodetable} -\def\luaclose{\pdfprimitive\closelua} % \end{macrocode} % -% We load the \texttt{lua} file. +% We load the \texttt{lua} file. % % \begin{macrocode} @@ -855,7 +1034,8 @@ end % \end{macrocode} % -% A small macro to register the \texttt{define\_font} callback from \textsf{luatextra}. See section \ref{sub:df} for more details. +% A small macro to register the \texttt{define\_font} callback from +% \textsf{luatextra}. See section \ref{sub:df} for more details. % % \begin{macrocode} @@ -865,50 +1045,57 @@ end % \end{macrocode} % -% \subsection{Module handling} -% -% The \texttt{\string\luaModuleError} macro is called by the lua function \texttt{luatextra.module\_error}. It is necessary because we can't call directly \texttt{\string\errmessage} in lua. +% \subsection{Module handling} % -% \begin{macrocode} - -% \end{macrocode} +% The \texttt{\string\luaModuleError} macro is called by the lua function +% \texttt{luatextra.module\_error}. It is necessary because we can't call +% directly \texttt{\string\errmessage} in lua. % -% \subsection{Module handling} +% \subsection{Module handling} % -% The \texttt{\string\luaModuleError} macro is called by the lua function \texttt{luatextra.module\_error}. It is necessary because we can't call directly \texttt{\string\errmessage} in lua. Then we define \texttt{\string\luaUseModule} that simply calls \texttt{luatextra.use\_module}. Remember that \texttt{\string\luaRequireModule} is defined at the beginning of this file. +% The \texttt{\string\luatexModuleError} macro is called by the lua function +% \texttt{luatextra.module\_error}. It is necessary because we can't call +% directly \texttt{\string\errmessage} in lua. Then we define +% \texttt{\string\luatexUseModule} that simply calls +% \texttt{luatextra.use\_module}. Remember that +% \texttt{\string\luatexRequireModule} is defined at the beginning of this +% file. % % \begin{macrocode} - -\def\luaModuleError#1#2{% +\def\luatexModuleError#1#2{% \errorcontextlines=0\relax \immediate\write16{}% \errmessage{Module #1 error: #2^^J^^J% See the module #1 documentation for explanation.^^J ...^^J}% } -\def\luaUseModule#1{\luadirect{luatextra.use_module([[#1]])}} +\def\luatexUseModule#1{\luadirect{luatextra.use_module([[#1]])}} % \end{macrocode} % -% \subsection{Attributes handling} +% \subsection{Attributes handling} % -% The most important macro here is \texttt{\string\newluaattribute} that allocates a new attribute, and adds it in the \texttt{tex.attributename} table (see \texttt{luatextra.attributedef\_from\_tex} for more details. It works just like the other \texttt{\string\new*} macros, we can allocate up to 65536 different attributes. +% The most important macro here is \texttt{\string\newluatexattribute} that +% allocates a new attribute, and adds it in the \texttt{tex.attributename} +% table (see \texttt{luatextra.attributedef\_from\_tex} for more details. +% It works just like the other \texttt{\string\new*} macros, we can +% allocate up to 65536 different attributes. % % \begin{macrocode} -\newcount\luaattdefcounter -\luaattdefcounter = 1 +\newcount\luatexattdefcounter +\luatexattdefcounter = 1 -\def\newluaattribute#1{% - \ifnum\luaattdefcounter<65535\relax % - \global\advance\luaattdefcounter by 1\relax % - \allocationnumber\luaattdefcounter % +\def\newluatexattribute#1{% + \ifnum\luatexattdefcounter<65535\relax % + \global\advance\luatexattdefcounter by 1\relax % + \allocationnumber\luatexattdefcounter % \ifluatex % - \global\luaattributedef#1=\allocationnumber % + \global\luatexattributedef#1=\allocationnumber % \fi % - \wlog{\string#1=\string\attribute\the\allocationnumber}% + \wlog{\string#1=\string\luatexattribute\the\allocationnumber}% \luadirect{% luatextra.attributedef_from_tex([[\noexpand#1]], '\number\allocationnumber')}% \else % @@ -918,15 +1105,18 @@ See the module #1 documentation for explanation.^^J ...^^J}% % \end{macrocode} % -% Two convenient macros, one to set an attribute (basically just a wrapper), and another one to uset it. Unsetting attributes with this function is important, as the \texttt{unset} value may change, as it already has in the 0.37 version. +% Two convenient macros, one to set an attribute (basically just a +% wrapper), and another one to uset it. Unsetting attributes with this +% function is important, as the \texttt{unset} value may change, as it +% already has in the 0.37 version. % % \begin{macrocode} -\def\setluaattribute#1#2{% +\def\setluatexattribute#1#2{% #1=\numexpr#2\relax % } -\def\unsetluaattribute#1{% +\def\unsetluatexattribute#1{% \ifnum\luatexversion<37\relax % #1=-1\relax % \else % @@ -936,20 +1126,20 @@ See the module #1 documentation for explanation.^^J ...^^J}% % \end{macrocode} % -% \subsection{Catcodetables handling} +% \subsection{Catcodetables handling} % -% Here we allocate catcodetables the same way we handle attributes. +% Here we allocate catcodetables the same way we handle attributes. % % \begin{macrocode} -\newcount\luacatcodetabledefcounter +\newcount\luatexcatcodetabledefcounter -\luacatcodetabledefcounter = 1 +\luatexcatcodetabledefcounter = 1 -\def\newluacatcodetable#1{% - \ifnum\luacatcodetabledefcounter<1114110\relax % 0x10FFFF is maximal \chardef - \global\advance\luacatcodetabledefcounter by 1\relax % - \allocationnumber=\luacatcodetabledefcounter % +\def\newluatexcatcodetable#1{% + \ifnum\luatexcatcodetabledefcounter<1114110\relax % 0x10FFFF is maximal \chardef + \global\advance\luatexcatcodetabledefcounter by 1\relax % + \allocationnumber=\luatexcatcodetabledefcounter % \global\chardef#1=\allocationnumber % \luadirect{% luatextra.catcodetabledef_from_tex([[\noexpand#1]], '\number\allocationnumber')}% @@ -961,7 +1151,8 @@ See the module #1 documentation for explanation.^^J ...^^J}% % \end{macrocode} % -% A small patch to manage the catcode of \@ in Plain, and to get two new counters in Plain too. +% A small patch to manage the catcode of \@ in Plain, and to get two new +% counters in Plain too. % % \begin{macrocode} @@ -980,11 +1171,14 @@ See the module #1 documentation for explanation.^^J ...^^J}% % \end{macrocode} % -% A macro that sets the catcode of a range of characters. The first parameter is the character number of the first character of the range, the second parameter is one for the last character, and the third parameter is the catcode we want them to have. +% A macro that sets the catcode of a range of characters. The first +% parameter is the character number of the first character of the range, +% the second parameter is one for the last character, and the third +% parameter is the catcode we want them to have. % % \begin{macrocode} -\def\luasetcatcoderange#1#2#3{% +\def\luatexsetcatcoderange#1#2#3{% \edef\luaSCR@temp{% \noexpand\@tempcnta=\the\@tempcnta \noexpand\@tempcntb=\the\@tempcntb @@ -1003,22 +1197,25 @@ See the module #1 documentation for explanation.^^J ...^^J}% % \end{macrocode} % -% Finally we create several catcodetables that may be used by the user. These are: +% Finally we create several catcodetables that may be used by the user. +% These are: % -% \begin{itemize} -% \item \texttt{\string\CatcodeTableIniTeX}: the base \TeX\ catcodes -% \item \texttt{\string\CatcodeTableString}: almost all characters have catcode 12 -% \item \texttt{\string\CatcodeTableOther}: all characters have catcode 12 (even space) -% \item \texttt{\string\CatcodeTableLaTeX}: the \LaTeX\ classical catcodes -% \end{itemize} +% \begin{itemize} +% \item \texttt{\string\CatcodeTableIniTeX}: the base \TeX\ catcodes +% \item \texttt{\string\CatcodeTableString}: almost all characters have +% catcode 12 +% \item \texttt{\string\CatcodeTableOther}: all characters have catcode 12 +% (even space) +% \item \texttt{\string\CatcodeTableLaTeX}: the \LaTeX\ classical catcodes +% \end{itemize} % % \begin{macrocode} -\newluacatcodetable\CatcodeTableIniTeX -\newluacatcodetable\CatcodeTableString -\newluacatcodetable\CatcodeTableOther -\newluacatcodetable\CatcodeTableLaTeX -\initluacatcodetable\CatcodeTableIniTeX +\newluatexcatcodetable\CatcodeTableIniTeX +\newluatexcatcodetable\CatcodeTableString +\newluatexcatcodetable\CatcodeTableOther +\newluatexcatcodetable\CatcodeTableLaTeX +\initluatexcatcodetable\CatcodeTableIniTeX \expandafter\ifx\csname @firstofone\endcsname\relax \long\def\@firstofone#1{#1}% @@ -1027,13 +1224,13 @@ See the module #1 documentation for explanation.^^J ...^^J}% \begingroup \def\@makeother#1{\catcode#1=12\relax}% \@firstofone{% - \luacatcodetable\CatcodeTableIniTeX + \luatexcatcodetable\CatcodeTableIniTeX \begingroup - \luasetcatcoderange{0}{8}{15}% + \luatexsetcatcoderange{0}{8}{15}% \catcode9=10 % tab \catcode11=15 % \catcode12=13 % form feed - \luasetcatcoderange{14}{31}{15}% + \luatexsetcatcoderange{14}{31}{15}% \catcode35=6 % hash \catcode36=3 % dollar \catcode38=4 % ampersand @@ -1043,24 +1240,43 @@ See the module #1 documentation for explanation.^^J ...^^J}% \catcode125=2 % brace right \catcode126=13 % tilde \catcode127=15 % - \saveluacatcodetable\CatcodeTableLaTeX + \saveluatexcatcodetable\CatcodeTableLaTeX \endgroup \@makeother{0}% nul \@makeother{13}% carriage return \@makeother{37}% percent \@makeother{92}% backslash \@makeother{127}% - \luasetcatcoderange{65}{90}{12}% A-Z - \luasetcatcoderange{97}{122}{12}% a-z - \saveluacatcodetable\CatcodeTableString + \luatexsetcatcoderange{65}{90}{12}% A-Z + \luatexsetcatcoderange{97}{122}{12}% a-z + \saveluatexcatcodetable\CatcodeTableString \@makeother{32}% space - \saveluacatcodetable\CatcodeTableOther + \saveluatexcatcodetable\CatcodeTableOther \endgroup } +\ltxtra@AtEnd + % \end{macrocode} % -% We load \textsf{luaotfload}. +% We provide some functions for backward compatibility with old versions of luatextra. +% +% \begin{macrocode} + +\let\newluaattribute\newluatexattribute +\let\luaattribute\luatexattribute +\let\unsetluaattribute\unsetluatexattribute +\let\initluacatcodetable\initluatexcatcodetable +\let\luasetcatcoderange\luatexsetcatcoderange +\let\newluacatcodetable\newluatexcatcodetable +\let\setluaattribute\setluatexattribute +\let\luaModuleError\luatexModuleError +\let\luaRequireModule\luatexRequireModule +\let\luaUseModule\luatexUseModule + +% \end{macrocode} +% +% Finally, we load \textsf{luaotfload}. % % \begin{macrocode} @@ -1070,7 +1286,6 @@ See the module #1 documentation for explanation.^^J ...^^J}% \RequirePackage{luaotfload} \fi -\ltxtra@AtEnd % \end{macrocode} % \iffalse %</package> @@ -1078,11 +1293,14 @@ See the module #1 documentation for explanation.^^J ...^^J}% % % \section{\texttt{luatextra-latex.tex}\label{sub:latex}} % -% This file is very small, it just changes the maximum values of allowed registers from 32768 to 65536, and remaps \texttt{\string\newcount} (and friends) to \textsf{etex}'s \texttt{\string\globcount}. -% % \iffalse %<*latex> % \fi +% +% This file is very small, it just changes the maximum values of allowed +% registers from 32768 to 65536, and remaps \texttt{\string\newcount} (and +% friends) to \textsf{etex}'s \texttt{\string\globcount}. +% % \begin{macrocode} \def\ltxtra@temp#1{% \ifnum\count27#1=32768 % @@ -1105,6 +1323,6 @@ See the module #1 documentation for explanation.^^J ...^^J}% %</latex> % \fi % -% +% % \Finale \endinput |