summaryrefslogtreecommitdiff
path: root/Master
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2010-11-05 21:44:47 +0000
committerKarl Berry <karl@freefriends.org>2010-11-05 21:44:47 +0000
commitbd502c7ba3265942e57ac843d4530966b4f45241 (patch)
treed4402f160f754adde44988b22b3e69888597368b /Master
parent65da87ef9393c8b1d5da8f3c844ff00d24212dd9 (diff)
luatextra (4nov10)
git-svn-id: svn://tug.org/texlive/trunk@20328 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master')
-rw-r--r--Master/texmf-dist/doc/luatex/luatextra/News5
-rw-r--r--Master/texmf-dist/doc/luatex/luatextra/README8
-rw-r--r--Master/texmf-dist/doc/luatex/luatextra/luatextra-reference.pdfbin115572 -> 0 bytes
-rw-r--r--Master/texmf-dist/doc/luatex/luatextra/luatextra.pdfbin178866 -> 393519 bytes
-rw-r--r--Master/texmf-dist/doc/luatex/luatextra/test.tex18
-rw-r--r--Master/texmf-dist/source/luatex/luatextra/Makefile50
-rw-r--r--Master/texmf-dist/source/luatex/luatextra/luatextra-reference.tex463
-rw-r--r--Master/texmf-dist/source/luatex/luatextra/luatextra.dtx256
-rw-r--r--Master/texmf-dist/tex/luatex/luatextra/luatextra-latex.tex8
-rw-r--r--Master/texmf-dist/tex/luatex/luatextra/luatextra.lua8
-rw-r--r--Master/texmf-dist/tex/luatex/luatextra/luatextra.sty36
11 files changed, 236 insertions, 616 deletions
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 <http://github.com/mpg/luatextra/>, 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
--- a/Master/texmf-dist/doc/luatex/luatextra/luatextra-reference.pdf
+++ /dev/null
Binary files 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
--- a/Master/texmf-dist/doc/luatex/luatextra/luatextra.pdf
+++ b/Master/texmf-dist/doc/luatex/luatextra/luatextra.pdf
Binary files 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 <elie.roux@telecom-bretagne.eu>
-%
-% 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 <elie.roux@telecom-bretagne.eu>
+% Written in 2009, 2010 by Manuel Pégourié-Gonnard and Élie Roux.
+% <mpg@elzevir.fr>
+% <elie.roux@telecom-bretagne.eu>
%
% 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 <elie.roux@telecom-bretagne.eu>
+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
%</ignore>
%<*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}
%</lua>
-% \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}
%</package>
-% \fi
+% \end{macrocode}
+%
+% \section{Test file}
+%
+% Very minimal, just check that the package correctly loads.
+%
+% \begin{macrocode}
+%<*test>
+\RequirePackage{luatextra}
+\stop
+%</test>
+% \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 <elie.roux@telecom-bretagne.eu>
+%% 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 <elie.roux@telecom-bretagne.eu>
+-- 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 <elie.roux@telecom-bretagne.eu>
+%% 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