From bd502c7ba3265942e57ac843d4530966b4f45241 Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Fri, 5 Nov 2010 21:44:47 +0000 Subject: luatextra (4nov10) git-svn-id: svn://tug.org/texlive/trunk@20328 c570f23f-e606-0410-a88d-b1316a301751 --- Master/texmf-dist/doc/luatex/luatextra/News | 5 + Master/texmf-dist/doc/luatex/luatextra/README | 8 +- .../doc/luatex/luatextra/luatextra-reference.pdf | Bin 115572 -> 0 bytes .../texmf-dist/doc/luatex/luatextra/luatextra.pdf | Bin 178866 -> 393519 bytes Master/texmf-dist/doc/luatex/luatextra/test.tex | 18 + Master/texmf-dist/source/luatex/luatextra/Makefile | 50 +-- .../luatex/luatextra/luatextra-reference.tex | 463 --------------------- .../source/luatex/luatextra/luatextra.dtx | 256 ++++++++---- .../tex/luatex/luatextra/luatextra-latex.tex | 8 +- .../texmf-dist/tex/luatex/luatextra/luatextra.lua | 8 +- .../texmf-dist/tex/luatex/luatextra/luatextra.sty | 36 +- 11 files changed, 236 insertions(+), 616 deletions(-) delete mode 100644 Master/texmf-dist/doc/luatex/luatextra/luatextra-reference.pdf create mode 100644 Master/texmf-dist/doc/luatex/luatextra/test.tex delete mode 100644 Master/texmf-dist/source/luatex/luatextra/luatextra-reference.tex (limited to 'Master') diff --git a/Master/texmf-dist/doc/luatex/luatextra/News b/Master/texmf-dist/doc/luatex/luatextra/News index aec037bcede..73498dfc815 100644 --- a/Master/texmf-dist/doc/luatex/luatextra/News +++ b/Master/texmf-dist/doc/luatex/luatextra/News @@ -1,5 +1,10 @@ History of the luatextra bundle +2010/10/04 v0.98 + * load metalogo under LaTeX; don't define logos under Plain TeX + * documentation overhaul; added a "planned changes" section + * rm luatextra-reference.pdf; will be back separatly as lualatex-doc.pdf + 2010/08/02 v0.971 * fix latex detection that used to break latex detection in other packages (inc. TikZ). diff --git a/Master/texmf-dist/doc/luatex/luatextra/README b/Master/texmf-dist/doc/luatex/luatextra/README index a8fba74a818..65c1bd20567 100644 --- a/Master/texmf-dist/doc/luatex/luatextra/README +++ b/Master/texmf-dist/doc/luatex/luatextra/README @@ -1,14 +1,11 @@ The luatextra generic bundle -WARNING: this package is undergoing major changes. The documentation (including -this readme) is sometimes inconsistent. Also, everything may change in the near -future. +WARNING: this package is undergoing major changes. See section "Planned +changes" in the documentation for details. luatextra loads many usefull packages for LuaTeX (like luaotfload) and provides a few additional features and goodies. -Please see the luatextra-reference.pdf documentation for more details. - This package is developed on , see the 'News' file for version history. @@ -30,6 +27,7 @@ distribution's manual for details. b. Run 'make install TEXMFROOT=/path/to/texmf'. c. See 2c. + License ------- diff --git a/Master/texmf-dist/doc/luatex/luatextra/luatextra-reference.pdf b/Master/texmf-dist/doc/luatex/luatextra/luatextra-reference.pdf deleted file mode 100644 index da2654571c7..00000000000 Binary files a/Master/texmf-dist/doc/luatex/luatextra/luatextra-reference.pdf and /dev/null differ diff --git a/Master/texmf-dist/doc/luatex/luatextra/luatextra.pdf b/Master/texmf-dist/doc/luatex/luatextra/luatextra.pdf index e914f67113d..f8ea3a3772b 100644 Binary files a/Master/texmf-dist/doc/luatex/luatextra/luatextra.pdf and b/Master/texmf-dist/doc/luatex/luatextra/luatextra.pdf differ diff --git a/Master/texmf-dist/doc/luatex/luatextra/test.tex b/Master/texmf-dist/doc/luatex/luatextra/test.tex new file mode 100644 index 00000000000..62ee4041e9d --- /dev/null +++ b/Master/texmf-dist/doc/luatex/luatextra/test.tex @@ -0,0 +1,18 @@ +%% +%% This is file `test.tex', +%% generated with the docstrip utility. +%% +%% The original source files were: +%% +%% luatextra.dtx (with options: `test') +%% +%% Written in 2009, 2010 by Manuel Pegourie-Gonnard and Elie Roux. +%% +%% This work is under the CC0 license. +%% See source file 'luatextra.dtx' for details. +%% +\RequirePackage{luatextra} +\stop +\endinput +%% +%% End of file `test.tex'. diff --git a/Master/texmf-dist/source/luatex/luatextra/Makefile b/Master/texmf-dist/source/luatex/luatextra/Makefile index 50656034230..60708ac0665 100644 --- a/Master/texmf-dist/source/luatex/luatextra/Makefile +++ b/Master/texmf-dist/source/luatex/luatextra/Makefile @@ -3,24 +3,21 @@ NAME = luatextra DTX = $(wildcard *.dtx) DOC_DTX = $(patsubst %.dtx, %.pdf, $(DTX)) -SRC_TEX = luatextra-reference.tex -DOC_TEX = $(patsubst %.tex, %.pdf, $(SRC_TEX)) # Files grouped by generation mode UNPACKED= luatextra-latex.tex luatextra.lua luatextra.sty -COMPILED = $(DOC_DTX) $(DOC_TEX) -# $(DOC_TEX) has a compiled version in the repository -GENERATED = $(UNPACKED) $(DOC_DTX) -SOURCE = $(DTX) $(SRC_TEX) README Makefile News +COMPILED = $(DOC_DTX) +GENERATED = $(UNPACKED) $(COMPILED) +SOURCE = $(DTX) README Makefile News -# Files grouped by installation location -RUNFILES = $(UNPACKED) -DOCFILES = $(DOC_DTX) $(DOC_TEX) README News -SRCFILES = $(DTX) $(SRC_TEX) Makefile +# Fi-es grouped by installation location +RUNFILES = $(filter-out test.tex, $(UNPACKED)) +DOCFILES = $(DOC_DTX) test.tex README News +SRCFILES = $(DTX) Makefile # The following definitions should be equivalent # ALL_FILES = $(RUNFILES) $(DOCFILES) $(SRCFILES) -ALL_FILES = $(GENERATED) $(SOURCE) $(DOC_TEX) +ALL_FILES = $(GENERATED) $(SOURCE) # Installation locations FORMAT = luatex @@ -34,32 +31,25 @@ TDS_ZIP = $(NAME).tds.zip ZIPS = $(CTAN_ZIP) $(TDS_ZIP) DO_TEX = tex --interaction=batchmode $< >/dev/null -DO_PDFLATEX = pdflatex --interaction=batchmode $< >/dev/null -DO_PDFLUALATEX = lualatex --interaction=batchmode $< >/dev/null -DO_MAKEINDEX = makeindex -s gind.ist $(subst .dtx,,$<) >/dev/null 2>&1 +DO_LATEXMK = latexmk -silent $< >/dev/null -all: $(GENERATED) $(DOC_TEX) +all: $(GENERATED) doc: $(COMPILED) unpack: $(UNPACKED) -ctan: $(CTAN_ZIP) +ctan: check $(CTAN_ZIP) tds: $(TDS_ZIP) world: all ctan -.PHONY: all doc unpack ctan tds world +.PHONY: all doc unpack ctan tds world check %.pdf: %.dtx - $(DO_PDFLATEX) - $(DO_MAKEINDEX) - $(DO_PDFLATEX) - $(DO_PDFLATEX) - -$(DOC_TEX): $(SRC_TEX) - $(DO_PDFLUALATEX) - $(DO_PDFLUALATEX) - $(DO_PDFLUALATEX) + $(DO_LATEXMK) $(UNPACKED): luatextra.dtx $(DO_TEX) +check: $(UNPACKED) + lualatex --interaction=batchmode test.tex >/dev/null + $(CTAN_ZIP): $(SOURCE) $(COMPILED) $(TDS_ZIP) @echo "Making $@ for CTAN upload." @$(RM) -- $@ @@ -92,9 +82,11 @@ manifest: @echo "Derived files:" @for f in $(GENERATED); do echo $$f; done -clean: - @$(RM) -- *.log *.aux *.toc *.idx *.ind *.ilg *.out +clean: + @latexmk -silent -c *.dtx >/dev/null + @# for tex-only runs: + @rm -f -- *.log mrproper: clean - @$(RM) -- $(GENERATED) $(ZIPS) + @$(RM) -- $(GENERATED) $(ZIPS) test.* diff --git a/Master/texmf-dist/source/luatex/luatextra/luatextra-reference.tex b/Master/texmf-dist/source/luatex/luatextra/luatextra-reference.tex deleted file mode 100644 index 30a1898197e..00000000000 --- a/Master/texmf-dist/source/luatex/luatextra/luatextra-reference.tex +++ /dev/null @@ -1,463 +0,0 @@ -% Copyright (C) 2009 by Elie Roux -% -% This work is under the CC0 license. Basically this means that you can do -% (almost) whatever you want with it without asking for permission. -% -% To compile it, you must use LuaLaTeX. -% - -\documentclass{article} -\usepackage[utf8]{luainputenc} -\usepackage[T1]{fontenc} -\usepackage{times} -\usepackage{amsfonts} -\usepackage{eurosym} -\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 -\newlength\xxt@kern@eX -\newlength\xxt@lower@e -\newlength\xxt@kern@La -\newlength\xxt@kern@aT -\newlength\xxt@kern@eL -\newcommand*\TeX@logo@spacing[6]{% - \setlength\xxt@kern@Te{#1}% - \setlength\xxt@kern@eX{#2}% - \setlength\xxt@lower@e{#3}% - \setlength\xxt@kern@La{#4}% - \setlength\xxt@kern@aT{#5}% - \setlength\xxt@kern@eL{#6}% -} -\DeclareRobustCommand\XeTeX{% - \leavevmode - \smash{% - X\lower\xxt@lower@e - \hbox{\kern\xxt@kern@eX - \setbox0=\hbox{E}\dimen0=\ht0\advance\dimen0by\dp0% - \raise\dimen0\hbox{\rotatebox{180}{\box0}}% - }\kern\xxt@kern@Te\TeX}}% -\TeX@logo@spacing{-0.15em}{-0.15em}{0.5ex}{-0.36em}{-0.15em}{-0.1em} - -\title{Lua\TeX tra references} -\author{Elie Roux \\ \url{elie.roux@telecom-bretagne.eu}} -\begin{document} - -\maketitle - -\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{lualibs} (previously -\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 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}. - -\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 . - -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. - -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 . -\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. - -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. - -\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? - -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. - -\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{lualibs}: additional lua functions (previously - \textsf{luaextra}). -\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. - -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}. - -\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}. - -\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}. - -\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. - -\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: - -\begin{verbatim} -abc -{ -\fontencoding{EU2}\usefont -\font\foo="MyOtfFont.otf"\foo -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. - -\subsubsection{luacode environment} - -\LuaTeX tra also provides an environment for lua code integration: -\textsf{luacode}. You can simply use it this way: - -\begin{verbatim} -\begin{luacode} -texio.write_nl("It works!") -\end{luacode} -\end{verbatim} - -\section{Advanced user point of view} - -\subsection{lua modules} - -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}. - -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. - -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. - -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. - -\subsection{catcodetables} - -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 -\end{itemize} - -\subsection{callbacks} - -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). - -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. -\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{lualibs.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. - -\subsection{\texttt{.lua} module template\label{sub:luatemplate}} - -\begin{verbatim} -mypackage = { } - -mypackage.module = { - name = "mypackage", - version = 1.0, - date = "2009/03/08", - description = "My fancy package", - author = "Me", - copyright = "Myself", - license = "My License", -} - -luatextra.provides_module(mypackage.module) - -local format = string.format - -function mypackage.log (...) - luatextra.module_log('mypackage', format(...)) -end - -function mypackage.warning (...) - luatextra.module_warning('mypackage', format(...)) -end - -function mypackage.error (...) - luatextra.module_error('mypackage', format(...)) -end -\end{verbatim} - -\subsection{\texttt{.sty} template} - -\begin{verbatim} -\expandafter\ifx\csname ProvidesPackage\endcsname\relax - \input luatextra.sty -\else - \NeedsTeXFormat{LaTeX2e} - \ProvidesPackage{mypackage} - [2009/03/08 v1.00 My super package.] - \RequirePackage{luatextra} -\fi - -\luaUseModule{mymodule} -\end{verbatim} - -\end{document} diff --git a/Master/texmf-dist/source/luatex/luatextra/luatextra.dtx b/Master/texmf-dist/source/luatex/luatextra/luatextra.dtx index 406386d0abe..ff56b6e4211 100644 --- a/Master/texmf-dist/source/luatex/luatextra/luatextra.dtx +++ b/Master/texmf-dist/source/luatex/luatextra/luatextra.dtx @@ -1,6 +1,8 @@ % \iffalse meta-comment % -% Copyright (C) 2009 by Elie Roux +% Written in 2009, 2010 by Manuel Pégourié-Gonnard and Élie Roux. +% +% % % This work is under the CC0 license. % @@ -10,17 +12,9 @@ % % Unpacking: % tex luatextra.dtx -% % Documentation: % pdflatex luatextra.dtx % -% The class ltxdoc loads the configuration file ltxdoc.cfg -% if available. Here you can specify further options, e.g. -% use A4 as paper format: -% \PassOptionsToClass{a4paper}{article} -% -% -% %<*ignore> \begingroup \def\x{LaTeX2e}% @@ -39,29 +33,26 @@ \let\MetaPrefix\relax \preamble -This is a generated file. -Copyright (C) 2009 by Elie Roux +Written in 2009, 2010 by Manuel Pegourie-Gonnard and Elie Roux. This work is under the CC0 license. - -This work consists of the main source file luainputenc.dtx -and the derived files - luatextra.sty, luatextra.lua, luatextra-latex.tex, luatextra.pdf +See source file '\inFileName' for details. \endpreamble \let\MetaPrefix\DoubleperCent - \generate{% \usedir{tex/luatex/luatextra}% \file{luatextra.sty}{\from{luatextra.dtx}{package}}% \file{luatextra-latex.tex}{\from{luatextra.dtx}{latex}}% } -% The following hacks are to generate a lua file with lua comments starting by -% -- instead of %% +\generate{% + \usedir{doc/luatex/luatextra}% + \file{test.tex}{\from{luatextra.dtx}{test}}% +} \def\MetaPrefix{-- } @@ -95,12 +86,20 @@ and the derived files \fi % %<*driver> -\NeedsTeXFormat{LaTeX2e} -\ProvidesFile{luatextra.drv}% - [2010/08/02 v0.971 LuaTeX extra low-level macros.]% \documentclass{ltxdoc} -\EnableCrossrefs -\CodelineIndex +\usepackage[utf8]{inputenc} +\usepackage[T1]{fontenc} +\usepackage{textcomp} +\usepackage{lmodern} +\usepackage{metalogo} +\usepackage[bookmarks=true, colorlinks=true]{hyperref} +\usepackage{bookmark} +\usepackage[english]{babel} +\providecommand\eTeX{e\TeX} +\newcommand\pf{\textsf} +\newcommand\file{\texorpdfstring{\nolinkurl}{}} +\newcommand\code{\texttt} +\newcommand*\email[1]{\href{mailto:#1}{#1}} \begin{document} \DocInput{luatextra.dtx}% \end{document} @@ -125,35 +124,123 @@ and the derived files % Grave accent \` Left brace \{ Vertical bar \| % Right brace \} Tilde \~} % -% \GetFileInfo{luatextra.drv} -% % \title{The \textsf{luatextra} package} -% \date{2010/08/02 v0.971} -% \author{Elie Roux \\ \texttt{elie.roux@telecom-bretagne.eu}} +% \date{2010/11/04 v0.98} +% \author{% +% Manuel P\'egouri\'e-Gonnard \email{mpg@elzevir.fr} \\ +% \'Elie Roux \email{elie.roux@telecom-bretagne.eu}} % % \maketitle % % \begin{abstract} -% 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. -% -% \textbf{Warning.} This package is undergoing major changes, so the -% documentation may sometimes be inconsistent. Also, be aware that everything -% may change. +% The \pf{luatextra} package loads essential packages for \LuaTeX, and +% provides few additional user-level goodies. It is meant as a convenience +% package for users. Developers should load directly the underlying packages +% they specifically need. +% +% \textbf{Warning.} This package is undergoing major changes, see the +% ``Planned changes'' section on page~\pageref{sec-plan}. % \end{abstract} % % \tableofcontents % -% \section{\texttt{luatextra.lua}} -% -% \subsection{Initialization and internal functions} +% \section{Documentation} +% +% The \pf{luatextra} package loads the following essential packages: +% \begin{itemize} +% \item \pf{luatexbase}: low-level functions for resources handling and +% compatibility. Divided in sub-packages, like \pf{luatexbase-mcb} (formerly +% \pf{luamcallbacks}) that allows to register several functions in a +% callback; +% \item \pf{lualibs}: additional lua functions (previously \pf{luaextra}) ; +% \item \pf{luaotfload}: implements extended syntax for \verb+\font+; +% \end{itemize} +% When running \LaTeX\ (as opposed to Plain \TeX), the \pf{metalogo} package +% is loaded too, proviging the macros \verb+\LuaTeX+ and \verb+\LuaLaTeX+ to +% typeset the logos. +% +% It also provides additional goodies, detailled in the next sections. +% +% By the way, people wanting to port their old documents to \LuaLaTeX\ without +% needing to change the input and font encodings may want to use the +% additional package \pf{luainputenc} (which is \emph{not} recommended for +% anything but compatibility). +% +% \subsection{Plain and \LaTeX\ macros} +% +% The most useful macro provided by \pf{luatextra} is certainly +% \verb+\luadirect+, which is a wrapper for \verb+\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 . +% \verb+\lualate+ is also provided as a wrapper for +% \verb+\latelua+. +% +% \pf{luatextra} automatically loads \pf{luaotfload}, so you can open otf fonts +% directly, for instance \verb+\font\foo="LinLibertine.otf"\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 \file{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 +% \verb!\font\foo="LinLibertine.otf;+tlig;+tsub;+liga;+rlig;"\foo!. +% +% \subsection{\LaTeX -only macros} +% +% \LuaTeX tra also provides an environment for lua code integration: +% \code{luacode}. You can simply use it this way: +% +% \begin{verbatim} +% \begin{luacode} +% texio.write_nl("It works!") +% \end{luacode} +% \end{verbatim} +% +% \subsection{Planned changes} \label{sec-plan} +% +% If, for some reason, you disagree with one of the upcoming changes described +% below, please discuss it on the development list: +% \email{lualatex-dev@tug.org}. Here they are, in semi-random order. +% +% The most major change planned is to make this package compatible with +% \LaTeX\ only. Rationale: it is (or will soon be) mostly a convenience +% package loading other packages. Users of Plain \TeX\ often are assumed not +% to care that much about such convenience. Then, \pf{fontspec} would be +% loaded rather than \pf{luaotfload}. +% +% Note that \pf{luatextra} currently expands on \pf{luatexbase-mcb} by +% proposing solutions for the \verb+define_font+ and \verb+open_read_file+ +% callbacks. See the implementation section below for details. In the future, +% this will either be merged in \pf{luatexbase-mcb} or just disappear, since +% it seems rather unlikely that different packages want to (or are able to +% usefully) share these callbacks. If you don't want this feature to +% disappear, please protest on the mailing list. +% +% The \code{luatextra} Lua namespace (aka table) would then disappear. Most of +% it has already been moved to \code{luatexbase} anyway. +% +% The remainning goodies (currently, just the \code{luacode} environment) mau +% move to another (\LaTeX-only) package for better modularity. +% +% Also, the package will bail out in error when not running \LuaTeX, rather +% than semi-silently exiting as it currently does. +% +% All name aliases (for primitives and macro from \pf{luatexbase}) will be +% dropped, so as to maintain a the name space clean. Only \verb+\luadirect+ +% would be kept as it may be used by the user, and provides +% version-independance. Please check section~\ref{rename} for the complete +% list of what will be dropped. +% +% \section{Implementation} +% +% \subsection{Lua module} +% +% \subsubsection{Initialization and internal functions} % -% \iffalse +% \begin{macrocode} %<*lua> -% \fi +% \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. @@ -181,7 +268,7 @@ luatexbase.provides_module { local format = string.format % \end{macrocode} % -% \subsection{Multiple callbacks on the \texttt{open\_read\_file} +% \subsubsection{Multiple callbacks on the \texttt{open\_read\_file} % callback\label{sub:orf}} % % |luatexbase| (see documentation for details) cannot really provide a @@ -272,7 +359,7 @@ function luatextra.default_pre_read(env) end % \end{macrocode} % -% \subsection{Multiple callbacks on the \texttt{define\_font} +% \subsubsection{Multiple callbacks on the \texttt{define\_font} % callback\label{sub:df}} % % The same principle is applied to the \texttt{define\_font} callback. The @@ -395,17 +482,18 @@ end luatexbase.create_callback('open_otf_font', 'first', luatextra.default_open_otf) luatexbase.create_callback('post_font_opening', 'simple', luatextra.default_post_font) % \end{macrocode} -% \iffalse +% +% \begin{macrocode} % -% \fi +% \end{macrocode} % -% \section{\texttt{luatextra.sty}} +% \subsection{\TeX\ package} % -% \iffalse +% \begin{macrocode} %<*package> -% \fi +% \end{macrocode} % -% \subsection{Initializations} +% \subsubsection{Initializations} % % First we prevent multiple loads of the file (useful for plain-\TeX ). % @@ -433,29 +521,19 @@ 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). -% -% These two macros are the only two loaded if we are under a non-Lua\TeX{} -% engine. +% Delegate logo definition to the metalogo package (unless running with +% Plain TeX). % % \begin{macrocode} - -\def\LuaTeX{Lua\TeX } -\def\LuaLaTeX{Lua\LaTeX } - +\begingroup\expandafter\expandafter\expandafter\endgroup +\expandafter\ifx\csname RequirePackage\endcsname\relax \else + \RequirePackage{metalogo} +\fi % \end{macrocode} % % Make sure Lua\TeX\ is being used. % % \begin{macrocode} -\bgroup\expandafter\expandafter\expandafter\egroup -\expandafter\ifx\csname ProvidesPackage\endcsname\relax - \input ifluatex.sty -\else - \RequirePackage{ifluatex} -\fi \ifluatex\else \begingroup \expandafter\ifx\csname PackageWarningNoLine\endcsname\relax @@ -465,7 +543,7 @@ end \let\x\PackageWarningNoLine \fi \expandafter\endgroup - \x{luatexbase-modutils}{LuaTeX is required for this package.^^J + \x{luatextra}{LuaTeX is required for this package.^^J Aborting package loading.} \expandafter\endinput \fi @@ -476,16 +554,12 @@ end % \begin{macrocode} \bgroup\expandafter\expandafter\expandafter\egroup \expandafter\ifx\csname ProvidesPackage\endcsname\relax + \input luatexbase.sty \input luatexbase-modutils.sty - \input luatexbase-attr.sty - \input luatexbase-cctb.sty - \input luatexbase-regs.sty \input luatexbase-mcb.sty \else + \RequirePackage{luatexbase} \RequirePackage{luatexbase-modutils} - \RequirePackage{luatexbase-attr} - \RequirePackage{luatexbase-cctb} - \RequirePackage{luatexbase-regs} \RequirePackage{luatexbase-mcb} \fi \luatexUseModule{lualibs} @@ -503,7 +577,11 @@ end % \end{macrocode} % % -% \subsection{Primitives renaming} +% \subsubsection{Primitives and macros renaming}\label{rename} +% +% \textbf{Warning.} This entire section will probably be dropped in a +% future release. Check section~\ref{sec-plan} for what to do if ouy +% deperately need it. % % Here we differenciate two very different cases: Lua\TeX\ version < 0.36 % has no \texttt{tex.enableprimitives} function, and has support for @@ -571,13 +649,7 @@ end % \end{macrocode} % % A small macro to register the \texttt{define\_font} callback from -% \textsf{luatextra}. See section \ref{sub:df} for more details. -% -% \begin{macrocode} -\def\ltxtra@RegisterFontCallback{ - \directlua{luatextra.register_font_callback()} -} -% \end{macrocode} +% \textsf{luatextra}. % % We provide some functions for backward compatibility with old versions of % luatextra. @@ -595,6 +667,14 @@ end \let\luaUseModule\luatexUseModule % \end{macrocode} % +% \subsubsection{Misc} +% +% \begin{macrocode} +\def\ltxtra@RegisterFontCallback{ + \directlua{luatextra.register_font_callback()} +} +% \end{macrocode} +% % Finally, we load \textsf{luaotfload}. % % \begin{macrocode} @@ -605,9 +685,21 @@ end \RequirePackage{luaotfload} \fi % \end{macrocode} -% \iffalse +% +% \begin{macrocode} % -% \fi +% \end{macrocode} +% +% \section{Test file} +% +% Very minimal, just check that the package correctly loads. +% +% \begin{macrocode} +%<*test> +\RequirePackage{luatextra} +\stop +% +% \end{macrocode} % % % \Finale diff --git a/Master/texmf-dist/tex/luatex/luatextra/luatextra-latex.tex b/Master/texmf-dist/tex/luatex/luatextra/luatextra-latex.tex index dc9a1fff5f3..9b53a13c3c2 100644 --- a/Master/texmf-dist/tex/luatex/luatextra/luatextra-latex.tex +++ b/Master/texmf-dist/tex/luatex/luatextra/luatextra-latex.tex @@ -5,15 +5,11 @@ %% The original source files were: %% %% luatextra.dtx (with options: `latex') -%% This is a generated file. %% -%% Copyright (C) 2009 by Elie Roux +%% Written in 2009, 2010 by Manuel Pegourie-Gonnard and Elie Roux. %% %% This work is under the CC0 license. -%% -%% This work consists of the main source file luainputenc.dtx -%% and the derived files -%% luatextra.sty, luatextra.lua, luatextra-latex.tex, luatextra.pdf +%% See source file 'luatextra.dtx' for details. %% \endinput %% diff --git a/Master/texmf-dist/tex/luatex/luatextra/luatextra.lua b/Master/texmf-dist/tex/luatex/luatextra/luatextra.lua index 4721e5871c2..6a590cd5a0a 100644 --- a/Master/texmf-dist/tex/luatex/luatextra/luatextra.lua +++ b/Master/texmf-dist/tex/luatex/luatextra/luatextra.lua @@ -5,15 +5,11 @@ -- The original source files were: -- -- luatextra.dtx (with options: `lua') --- This is a generated file. -- --- Copyright (C) 2009 by Elie Roux +-- Written in 2009, 2010 by Manuel Pegourie-Gonnard and Elie Roux. -- -- This work is under the CC0 license. --- --- This work consists of the main source file luainputenc.dtx --- and the derived files --- luatextra.sty, luatextra.lua, luatextra-latex.tex, luatextra.pdf +-- See source file 'luatextra.dtx' for details. -- module("luatextra", package.seeall) luatexbase.provides_module { diff --git a/Master/texmf-dist/tex/luatex/luatextra/luatextra.sty b/Master/texmf-dist/tex/luatex/luatextra/luatextra.sty index 68743355202..f69184acb13 100644 --- a/Master/texmf-dist/tex/luatex/luatextra/luatextra.sty +++ b/Master/texmf-dist/tex/luatex/luatextra/luatextra.sty @@ -5,15 +5,11 @@ %% The original source files were: %% %% luatextra.dtx (with options: `package') -%% This is a generated file. %% -%% Copyright (C) 2009 by Elie Roux +%% Written in 2009, 2010 by Manuel Pegourie-Gonnard and Elie Roux. %% %% This work is under the CC0 license. -%% -%% This work consists of the main source file luainputenc.dtx -%% and the derived files -%% luatextra.sty, luatextra.lua, luatextra-latex.tex, luatextra.pdf +%% See source file 'luatextra.dtx' for details. %% \csname ifluatextraloaded\endcsname \let\ifluatextraloaded\endinput @@ -31,15 +27,9 @@ [2010/08/02 v0.971 LuaTeX extra low-level macros] \fi - -\def\LuaTeX{Lua\TeX } -\def\LuaLaTeX{Lua\LaTeX } - -\bgroup\expandafter\expandafter\expandafter\egroup -\expandafter\ifx\csname ProvidesPackage\endcsname\relax - \input ifluatex.sty -\else - \RequirePackage{ifluatex} +\begingroup\expandafter\expandafter\expandafter\endgroup +\expandafter\ifx\csname RequirePackage\endcsname\relax \else + \RequirePackage{metalogo} \fi \ifluatex\else \begingroup @@ -50,22 +40,18 @@ \let\x\PackageWarningNoLine \fi \expandafter\endgroup - \x{luatexbase-modutils}{LuaTeX is required for this package.^^J + \x{luatextra}{LuaTeX is required for this package.^^J Aborting package loading.} \expandafter\endinput \fi \bgroup\expandafter\expandafter\expandafter\egroup \expandafter\ifx\csname ProvidesPackage\endcsname\relax + \input luatexbase.sty \input luatexbase-modutils.sty - \input luatexbase-attr.sty - \input luatexbase-cctb.sty - \input luatexbase-regs.sty \input luatexbase-mcb.sty \else + \RequirePackage{luatexbase} \RequirePackage{luatexbase-modutils} - \RequirePackage{luatexbase-attr} - \RequirePackage{luatexbase-cctb} - \RequirePackage{luatexbase-regs} \RequirePackage{luatexbase-mcb} \fi \luatexUseModule{lualibs} @@ -106,9 +92,6 @@ \let\luaclose\luatexcloselua \fi \directlua{dofile(kpse.find_file("luatextra.lua"))} -\def\ltxtra@RegisterFontCallback{ - \directlua{luatextra.register_font_callback()} -} \let\newluaattribute\newluatexattribute \let\luaattribute\luatexattribute \let\unsetluaattribute\unsetluatexattribute @@ -119,6 +102,9 @@ \let\luaModuleError\luatexModuleError \let\luaRequireModule\luatexRequireModule \let\luaUseModule\luatexUseModule +\def\ltxtra@RegisterFontCallback{ + \directlua{luatextra.register_font_callback()} +} \bgroup\expandafter\expandafter\expandafter\egroup \expandafter\ifx\csname ProvidesPackage\endcsname\relax \input luaotfload.sty -- cgit v1.2.3