summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/luatex/luatextra/luatextra-reference.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/source/luatex/luatextra/luatextra-reference.tex')
-rw-r--r--Master/texmf-dist/source/luatex/luatextra/luatextra-reference.tex463
1 files changed, 0 insertions, 463 deletions
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}