summaryrefslogtreecommitdiff
path: root/info/luatex
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
committerNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
commite0c6872cf40896c7be36b11dcc744620f10adf1d (patch)
tree60335e10d2f4354b0674ec22d7b53f0f8abee672 /info/luatex
Initial commit
Diffstat (limited to 'info/luatex')
-rw-r--r--info/luatex/lualatex-doc-de/lualatex-doc-DE.pdfbin0 -> 123776 bytes
-rw-r--r--info/luatex/lualatex-doc-de/lualatex-doc-DE.tex806
-rw-r--r--info/luatex/lualatex-doc/Makefile47
-rw-r--r--info/luatex/lualatex-doc/News20
-rw-r--r--info/luatex/lualatex-doc/README23
-rw-r--r--info/luatex/lualatex-doc/lltxdoc.cls110
-rw-r--r--info/luatex/lualatex-doc/lualatex-doc.pdfbin0 -> 155858 bytes
-rw-r--r--info/luatex/lualatex-doc/lualatex-doc.tex743
8 files changed, 1749 insertions, 0 deletions
diff --git a/info/luatex/lualatex-doc-de/lualatex-doc-DE.pdf b/info/luatex/lualatex-doc-de/lualatex-doc-DE.pdf
new file mode 100644
index 0000000000..b6dfc722e6
--- /dev/null
+++ b/info/luatex/lualatex-doc-de/lualatex-doc-DE.pdf
Binary files differ
diff --git a/info/luatex/lualatex-doc-de/lualatex-doc-DE.tex b/info/luatex/lualatex-doc-de/lualatex-doc-DE.tex
new file mode 100644
index 0000000000..dee95427b8
--- /dev/null
+++ b/info/luatex/lualatex-doc-de/lualatex-doc-DE.tex
@@ -0,0 +1,806 @@
+% lualatex-doc: a guide to LuaLaTeX
+%
+% Written by Manuel Pégourié-Gonnard <mpg@elzevir.fr>, 2010.
+%
+% Distributed under the terms of the GNU free documentation licence:
+% http://www.gnu.org/licenses/fdl.html
+% without any invariant section or cover text.
+
+\documentclass{lltxdoc}
+
+\title{Eine Einführung in \lualatex}
+\author{Manuel Pégourié-Gonnard \email{mpg@elzevir.fr}}
+\date{\today}
+
+\begin{document}
+
+\maketitle
+
+\begin{abstract}
+ Dieses Dokument ist eine Karte oder vielmehr ein touristischer Reiseführer
+ für die neue Welt von \lualatex.\footnote{Obwohl der Fokus des Dokumentes auf
+ \lualatex liegt, beinhaltet es auch nützliche Informationen über \luatex im
+ Nur-Text-Format.} Die angestrebte Zielgruppe reicht von völligen Anfängern
+ (mit etwas Wissen über gängiges \latex) bis hin zu Paket-Entwicklern. Dieser
+ Führer versteht sich als "umfassend" im folgenden Sinne: Es enthält Verweise
+ zu allen relevanten Quellen, trägt Informationen zusammen, die sonst verstreut
+ liegen und fügt einführende Materialien bei.
+
+ Rückmeldungen und Vorschläge für Verbesserungen sind besonders willkommen.
+ Dieses Dokument ist unter permanenter Bearbeitung. Danke für ihr Verständnis
+ und ihre Geduld.
+\end{abstract}
+
+\vspace{\stretch{1}}
+\setcounter{tocdepth}{2}
+\listoftoc*{toc}
+\vspace*{\stretch{2}}
+\clearpage
+
+\section{Einf"uhrung}\label{intro}
+
+\subsection{Was ist eigentlich \lualatex?}\label{what}
+
+Um diese Frage zu beantworten müssen wir ein paar Details über die Welt von \tex
+aufgreifen, die sie vielleicht für gewöhnlich nicht beachten würden, nämlich den
+Unterschied zwischen der \emph{Maschine} und einem \emph{Format}. Eine Maschine
+(engl. \emph{engine}) ist ein Computerprogramm währenddessen ein Format eine
+Menge von Makros darstellt, die durch die Maschine ausgeführt wird. Üblicherweise
+werden die Makros vor der eigentlichen Ausführung mit einer konkreten Datei
+vorgeladen.
+
+Eigentlich ist ein Format mehr oder weniger wie eine Dokumentenklasse oder ein
+Paket, mit dem Unterschied, dass es mit einem bestimmten Kommando verknüpft ist.
+Stellen sie sich vor, es gäbe ein Kommando \cmd{latex-article}, das das gleiche
+machen würde, wie \cmd{latex}, allerdings brauchen sie dabei nicht die Präambel
+©\documentclass{article}© zu Beginn ihrer Datei verwenden. Gleichermaßen
+ist das Kommando \cmd{pdflatex} dasselbe wie das Kommando \cmd{pdftex}, mit dem
+Unterschied, dass sie keine Anweisungen am Beginn ihrer Datei machen müssen, \latex
+zu laden. Das ist bequem und auch ein wenig effizienter.
+
+Formate sind großartig, weil sie mächtige Kommandos mit den einfach Werkzeugen
+implementieren, die eine Maschine bereitstellt. Trotzdem ist die Mächtigkeit
+eines Formates manchmal durch die von der Maschine bereitgestellten Werkzeuge
+beschränkt, weshalb einige Leute begonnen haben, funktionsreichere Maschinen zu
+entwickeln, damit andere wiederum mächtigere Formate (oder Pakete) implementieren
+können. Die zur Zeit bekanntesten Maschinen (ausgenommen das ursprüngliche \tex)
+sind \pdftex, \xetex und \luatex.
+
+Um das Bild noch etwas weiter zu verkomplizieren, erzeugte die ursprüngliche
+\tex Maschine ausschließlich DVI-Dateien, während seine Nachfolger zusätzlich
+PDF-Dateien erzeugen können. Jedes Kommando in ihrem System gehört zu einer
+bestimmten Maschine mit einem bestimmten Format und einem bestimmt Ausgabemodus.
+Die folgende Tabelle fasst dies zusammen: In der Zeile das Format, in der Spalte
+Maschine und in jeder Zelle steht oben das Kommando für den DVI-Modus und darunter
+das für den PDF-Modus.
+
+\begin{center}
+ \newcommand*\cell [2] {%
+ \parbox{6em}{\centering\leavevmode\color{code}\ttfamily
+ \strut\maybe{#1} \\ \strut\maybe{#2}}}
+ \makeatletter
+ \newcommand*\maybe [1] {%
+ \@ifmtarg{#1} {\textcolor{gray}{\normalfont (none)}} {#1}}
+ \begin{tabular}{l|cccc}
+ & \tex & \pdftex & \xetex & \luatex
+ \\ \hline
+ Plain
+ & \cell{tex}{}
+ & \cell{etex}{pdftex}
+ & \cell{}{xetex}
+ & \cell{dviluatex}{luatex}
+ \\ \hline
+ \latex
+ & \cell{}{}
+ & \cell{latex}{pdflatex}
+ & \cell{}{xelatex}
+ & \cell{dvilualatex}{lualatex}
+ \\
+ \end{tabular}
+\end{center}
+
+Wir können jetzt die Frage in der Überschrift beantworten: \lualatex ist die
+\luatex Maschine mit dem \latex Format. Nun gut, diese Antwort ist nicht
+besonders befriedigend, wenn sie den Unterschied zwischen \luatex und \latex
+nicht kennen.
+
+\medskip
+
+Wie sie vielleicht wissen ist \latex das allgemeine Rahmenwerk, in welchem
+Dokumente mit ©\documentclass© beginnen, Pakete mit ©\usepackage© geladen,
+Schriftarten auf eine schlaue Art und Weise ausgewählt werden (damit sie in die
+Fettschrift wechseln können, aber kursiv beibehalten können), Seiten mit
+komplizierten Algorithmen erstellt werden, darunter Unterstützung für Kopf- und
+Fußzeilen, Fußnoten, Randnotizen, Textflussmaterial usw. Dies ändert sich nicht
+mit \lualatex, aber neue und mächtigere Pakete werden damit verfügbar, die
+Teile des Systems auf bessere Weise arbeiten lassen.
+
+Was also ist \luatex? Kurz gesagt: Die heißeste \tex Maschine, die es zur Zeit
+gibt! Etwas genauer ausgedrückt: Es ist der vorgesehene Nachfolger von \pdftex
+und beinhaltet all dessen Kernfunktionen: Direkte Generierung von PDF Dateien
+mit Unterstützung erweiterter PDF-Funktionen und mikrotypografischen
+Verbesserungen an den typografischen \tex-Algorithmen.
+
+Die wichtigsten Neuerungen von \luatex sind:
+
+\begin{enumerate}
+ \item Nativer Support von Unicode, dem modernen Standard von Zeichenklassifikation
+ und Kodierung mit Unterstützung aller Buchstaben der Welt, vom
+ Englischen über Arabisch bis hin zu traditionellem Chinesisch und mit
+ Einbezug einer großen Menge von mathematischen und sonstigen Symbolen.
+ \item Die Inklusion von Lua als der eingebetteten Scriptsprache (siehe
+ Kapitel~\ref{luaintex} für Details).
+ \item Eine Menge von großartigen Lua-Bibliothenken, darunter:
+ \begin{itemize}
+ \item ©fontloader©, die moderne Schriftartenformate wie Truetype oder
+ Opentype unterstützt;
+ \item ©font©, die die Veränderung von Schriftarten innerhalb des Dokumentes
+ ermöglicht;
+ \item ©mplib©, eine eingebettete Version des Grafikprogramms Metapost;
+ \item ©callback©, die Zugänge zu teilen der \tex-Maschine bereitstellt,
+ die vorher nicht erreichbar waren;
+ \item Dienstprogramm-Bibliotheken, um Bilder, PDF und andere Dateien zu
+ manipulieren.
+ \end{itemize}
+\end{enumerate}
+
+Einige dieser Funktionen, wie zum Beispiel die Unicode-Unterstützung, wirken sich
+direkt auf alle Dokumente auf, während andere Funktionen hauptsächlich Werkzeuge
+bereitstellen, die Autoren von Paketen nutzen, um noch noch mehr Kommandos und
+Erweiterungen bereitzustellen.
+
+\subsection{Wechseln von \latex nach \lualatex}\label{switch}
+
+Wie das vorangegangene Kapitel zeigt ist \lualatex vergleichbar mit \latex, hat
+einige wenige Unterschiede und hält eine höhere Anzahl von funktionsreichen Paketen
+und Werkzeugen verfügbar. In diesem Abschnitt präsentieren wir das absolute
+Minimum, das sie wissen sollten, um ein Dokument mit \lualatex zu erzeugen, während
+der Rest des dieses Dokumentes mehr Details über die verfügbaren Packages
+bereithält.
+
+Es gibt nur drei Unterschiede:
+There are only three differences:
+\begin{enumerate}
+ \item Verwenden sie nicht das Paket \pf{inputenc}! Kodieren sie ihre Quelldatei
+ einfach in UTF-8.
+ \item Laden sie nicht \pf{fontenc}, sondern stattdessen \pf{fontspec}.
+
+ \item Benutzen sie kein Paket, das die Schriftarten ändert, stattdessen
+ verwenden sie \pf{fontspec}'s-Kommandos.
+\end{enumerate}
+
+Sie müssen sich also lediglich mit \pf{fontspec} vertraut machen, was sehr
+einfach ist: Wählen sie die Hauptserifenschriftart mit ©\setmainfont© aus, die
+serifenlose Schriftart mit ©\setsansfont©, die Festbreitenschriftart mit
+©\setmonofont©. Der Parameter für diese Kommandos ist ein menschen-lesbarer
+Name der Schriftart, zum Beispiel ©Latin Modern Roman© anstelle von ©ec-lmr10©.
+Sie möchten gegebenenfalls ©\defaultfontfeatures{Ligatures=TeX}© vor der
+Verwendung dieser Kommandos setzen, um die üblichen \tex-Ersetzungen (wie zum
+Beispiel ©---© für einen hervorgehobenen Gedankenstrich) zu bewahren.
+
+Die gute Nachricht ist, dass sie jetzt direkt auf jede Schriftart ihres
+Betriebssystems zugreifen können, zusätzlich zu denen der \tex-Distribution,
+darunter auch TrueType und OpenType-Schriftarten und sie haben Zugriff auf
+deren neueste Funktionen. Das bedeutet, dass es jetzt einfach ist ist, mit
+\lualatex jede moderne Schriftart zu verwenden, die sie heruntergeladen oder
+gekauft haben - und sie profitieren von deren vollem Potenzial.
+
+Die schlechte Nachricht ist, dass es nicht immer einfach ist, eine Liste von
+allen verfügbaren Schriftarten zu erhalten. Unter Windows mit \texlive listet
+ihnen das Kommandozeilenwerkzeug \cmd{fc-list} alle auf, aber es ist nicht
+besonders nutzerfreundlich. Unter Mac OS X, zeigt ihnen die
+\emph{Fontbook}-Anwendung alle Schriftarten ihres Systems an, aber nicht die
+der \tex-Distribution. Das Gleiche gilt für \cmd{fc-list} unter Linux. Eine
+weitere schlechte Nachricht ist, dass sie auf diese Art nicht auf ihre alten
+Schriftarten zugreifen können. Glücklicherweise gibt es tagtäglich immer mehr
+neue Schriftarten in modernen Formaten.
+
+Übrigens sollten wir hier erwähnen, dass der Inhalt dieses Kapitels so weit
+auch auf \xelatex zutrifft, das heißt für \latex nach \xetex. Tatsächlich
+teilt \xetex zwei der essenziellen Features von \luatex, nämlich die native
+Unicode-Unterstützung und die Verwendung moderner Schriftartenformate
+(allerdings ohne die anderen Funktionen von \luatex; auf der anderen Seite ist
+es zur Zeit stabiler). Obwohl sich die \xelatex-Implementierung bezüglich
+Schriftarten erheblich unterscheidet, so stellt doch \pf{fontspec} eine
+vereinheitlichte Schriftarten-Schnittstelle für beide bereit.
+
+\medskip
+
+Um die Vorzüge der neuen Funktionen von \luatex zu erhalten, müssen sie einige
+Teile der alten Welt fallenlassen und zwar jene Schriftarten, die nicht in
+einem modernen Format verfügbar sind. Auch die Freiheit der Kodierung der
+Quelldatei nach Wahl muss aufgegeben werden, aber UTF-8 ist so überlegen, dass
+dieser Punkt kaum zählt. Das Paket \pk{luainputenc} stellt verschiedene
+Krücken bereit, um diese Teile zu erhalten\footnote{Obwohl der Name andeutet,
+es ginge lediglich um Eingabe-Kodierungen, so sind die Details der
+\latex-Schriftartenimplementierung für dieses Paket notwendig und unterstützen
+daher ebenfalls die alten Schriftarten.}, allerdings mit dem
+Nachteil, die korrekte Unicode-Unterstützung zu verlieren.
+
+Das ist alles, was sie wissen müssen, um Dokumente mit \lualatex zu erstellen.
+Ich empfehle ihnen einen Blick ins die \pf{fontspec}-Anleitung zu werfen und
+konkret ein kleines Dokument mit lustigen Schriftarten zu übersetzen. Sie
+können dann den Rest des Dokuments nach Bedarf überfliegen.
+Kapitel~\ref{workornot} listet alle anderen Unterschiede zwischen konventionellem
+\latex und \lualatex auf, die mir bekannt sind.
+
+
+\subsection{Eine Lua-in-\tex Fibel}\label{luaintex}
+
+Lua ist eine kleine, feine Sprache ganz offensichtlich weniger überraschend
+und viel einfacher zu lernen als \tex. Die Haupt-Referenz ist das sehr gut
+lesbare Buch \emph{Programming in Lua}, dessen erste Ausgabe
+\href{http://www.lua.org/pil/} {online frei verfügbar} ist. Für den
+Schnelleinstieg empfehle ich die Kapitel~1 bis~5 zu lesen und einen schnellen
+Blick auf Teil~3 zu werfen. Beachten sie bitte, dass alle Bibliotheken, die in
+Kapitel~3 erwähnt werden, auch Bestandteil von \luatex sind. Allerdings ist
+die ©os©-Bibliothek aus Sicherheitsgründen beschränkt.
+
+Je nach ihrer Programmierweise sind sie vielleicht gleich an den restlichen
+Abschnitten von Teil~1 und Teil~2, die ihnen die erweiterten Funktionalitäten
+der Sprache aufzeigen. Teil~4 ist bedeutungslos im Kontext von \luatex, sofern
+sie nicht an \luatex selbst entwickeln wollen. Schließlich ist das \emph{Lua
+Referenz Handbuch} \href{http://www.lua.org/manual/}{in einigen Sprachen
+online verfügbar} und beinhaltet einen praktischen Index.
+
+\medskip
+
+Kommen wir nun zu Lua in \luatex. Die gebräuchlichste Art, Lua-Code auszuführen
+ist das ©\directlua©-Kommando, das Lua code als Argument erhält. Genauso können
+sie Informationen von Lua nach \tex übergeben mittels ©tex.sprint©.\footnote{
+Der Name bedeutet vermutlich ``Zeichenkettendruck'' im Gegensatz zu ``laufe
+sehr schnell für eine sehr kurze Zeit.'' } Zum Beispiel
+
+\begin{Verbatim}
+ die Standardnäherung von $\pi = \directlua{tex.sprint(math.pi)}$
+\end{Verbatim}
+
+gibt ``die Standardnäherung von $\pi = \directlua{tex.sprint(math.pi)}$'' in
+ihr Dokument aus. Sie sehen, wie einfach es ist \tex und Lua zu vermischen?
+
+Tatsächlich gibt es einige wenige Treffer. Schauen wir zuerst auf den Lua
+nach \tex-Weg, denn es ist der einfachste. Wenn sie in das \luatex-Handbuch
+schauen, werden sie sehen, dass es dort eine weitere Funktion mit einem
+einfacheren Namen ©tex.print©, gibt. Es fügt eine komplette Zeile
+in ihre \tex-Quelle ein, wobei der Inhalt das Argument des Kommandos ist. Falls
+sie das noch nicht wussten: \tex macht alle garstigen Dinge mit kompletten
+Quellcodezeilen, wie das Überspringen am Anfang und am Ende einer Zeile und dem
+Hinzufügen eines EOL-Zeichens am Ende der Zeile. Die meiste Zeit werden sie
+das Feature nicht brauchen, daher empfehle ich die Verwendung von ©tex.sprint©.
+
+Wenn sie genügend tief in \tex bewandt sind und sogenannte catcodes kennen,
+werden sie sich freuen, dass ihnen ©tex.print© und seine Varianten beinahe
+die volle Kontrolle über catcodes gibt, die sie benutzen können, um die
+Argumente zu zerlegen, da sie eine catcode-Tabelle als erstes Argument
+übergeben können. Sie möchten vielleicht mehr über catcodes erfahren, die
+zur Zeit~2.7.6 im \luatex Handbuch sind. Wenn sie mit catcodes nichts am
+Hut haben, überspringen sie einfach diesen Abschnitt.
+
+\medskip
+
+Lassen sie uns nun auf ©\directlua© blicken. Um einen Eindruck davon zu bekommen
+wie es arbeitet, stellen sie sich vor, dass es ein ©\write©-Kommando sei, aber
+es schreibt nur in eine virtuelle Datei und schickt diese Datei sofort an den
+Lua-Interpreter. Im Lua-Kontext ergibt sich daruas, dass jedes Argument eines
+©\directlua©-Kommandos seinen eigenen Geltungsbereich hat: Lokale Variablen
+des einen Argumentes sind nicht sichtbar für das andere (was eigentlich
+vernünftig ist, aber man weiß besser darüber bescheid).
+
+Nun der wichtigste Punkt ist, dass das Argument zuerst vom \tex-Interpreter
+zerlegt wird, dann vollständig erweitert und zurückverwandelt wird in eine
+reine Zeichenkette, bevor es in den Lua-Interpreter gesteckt wird. Das Einlesen
+in den \tex-Interpreter hat einige Konsequenzen. Eine davon ist, dass die
+EOL-Zeichen in Leerzeichen umgewandelt werden, sodass es nur eine (lange)
+Eingabezeile gibt. Da Lua eine formfreie Sprache ist, spielt das für gewöhnlich
+keine Rolle, allerdings dann schon, wenn es um Kommentare geht:
+
+\begin{Verbatim}
+ \directlua{a_function()
+ -- a comment
+ another_function()}
+\end{Verbatim}
+
+wird nicht das tun, was sie vermutlich erwarten würden. ©another_function()©
+würde als Teil des Kommentars verstanden werden.
+
+Eine weitere Konsequenz ist, dass aufeinanderfolgende Leerzeichen werden
+zusammengefasst zu einem Leerzeichen und \tex-Kommentare werden verworfen.
+Hier nun die korrekte Version des vorigen Beispiels:
+\begin{Verbatim}
+ \directlua{a_function()
+ % a comment
+ another_function()}
+\end{Verbatim}
+Es ist ebenfalls zu bemerken, dass das Argument general in einem ©\write© ist,
+und daher im expansion-only-Kontext ist. Wenn sie nicht wissen, was das
+bedeutet, lassen sie es mich so sagen, dass die Expansion-Sache der Hauptgrund
+ist, der die \tex-Programmierung so schwierig gestaltet.
+
+\medskip
+
+Ich entschuldige mich dafür, dass die letzten drei Abschnitte ein wenig
+\tex{}nisch gewesen sind, aber ich dachte mir, dass sie das wissen sollten. Um
+sie dafür zu belohnen, dabei geblieben zu sein, gebe ich ihnen hier einen
+debugging-Trick. Setzen sie den folgenden Code an den Anfang ihres Dokumentes:
+\begin{Verbatim}
+ \newwrite\luadebug
+ \immediate\openout\luadebug luadebug.lua
+ \AtEndDocument{\immediate\closeout\luadebug}
+ \newcommand\directluadebug{\immediate\write\luadebug}
+\end{Verbatim}
+
+Wenn sie einmal schwer mit einem speziellen Aufruf von ©\directlua© zu kämpfen
+haben, weil er nicht das macht, was sie wollen, dann ersetzen sie den Aufruf
+dieser Instanz durch ©\directluadebug©. Übersetzen sie dann wie immer und
+schauen in die Datei \file{luadebug.lua}. Sie sehen dannm, was der Lua-Interpreter
+tatsächlich gelesen hat.
+
+Das \pk{luacode}-Pakte stellt Kommandos und Umgebungen bereit, die ihnen helfen
+verschiedene Grade dieser Probleme zu lösen. Wie dem auch seim, für alles was
+nicht trivial ist, sollte man eine externe Datei mit dem Lua-Code verwenden, sie
+laden und verwenden. Zum Beispiel:
+
+\begin{Verbatim}
+ \directlua{dofile("my-lua-functions.lua")}
+ \newcommand*{\greatmacro}[2]{%
+ \directlua{my_great_function("\luatexluaescapestring{#1}", #2)}}
+\end{Verbatim}
+
+Das Beispiel nimmt an, dass ©my_great_function© in ©my-lua-functions.lua©
+definiert ist und eine Zeichenkette und eine Zahl als Argument nimmt. Bemerken
+sie auch, dass wir vorsichtig die ©\luatexluaescapestring© Primitive auf das
+Zeichenkettenargument anwenden, um jeden backslash oder Gänsefüßchen zu
+escapen. Das würde sonst den Lua Parser durcheinanderbringen.\footnote{
+Wenn sie jemals schonmal SQL verwendet haben, dann ist das Konzept,
+Zeichenketten zu escapen hoffentlich nicht neu für sie.}
+
+\medskip
+
+Das ist alles, was Lua in \tex betrifft. Wenn sie sich darüber wundern, warum
+©\luatexluaescapestring© einen so langen und dummen Namen hat, dann wollen sie
+vielleicht das nächste Kapitel anschauen.
+
+\subsection{Andere wissenswerte Dinge}\label{things}
+
+Nur für den Fall, dass dies nicht offensichtlich ist: Das \luatex-Handbuch,
+\file{luatexref-t.pdf} ist eine großartige Quelle.
+
+Es ist wichtig zu wissen, dass die Namen der Primitive von \luatex im Handbuch
+nicht mit den aktuellen Namen übereinstimmen. Um Konflikte mit bestehenden
+Makros zu vermeiden, sind alle neuen Primitive mit der Voranstellung ©\luatex©
+versehen worden, es sei denn, sie begannen nicht bereits schon mit diesem Prefix.
+
+To prevent clashes with existing macro names, all new primitives
+have been prefixed with ©\luatex© unless they already start with it, so
+©\luaescapestring© becomes ©\luatexluaescapetring© while ©\luatexversion©
+remains ©\luatexversion©. The rationale is detailed in section~\ref{formats}.
+
+\medskip
+
+Oh, and by the way, did I mention that \luatex is in beta and version 1.0 is
+expected in late 2012? You can learn more on the roadmap page of
+\href{http://luatex.org/}{the \luatex site}. Stable betas are released
+regularly and are included in \texlive since 2008 and \miktex since 2.9.
+
+Not surprisingly, support for \luatex in \latex is shiny new, which means it
+may be full of (shiny) bugs, and things may change at any point. You might
+want to keep your \tex distribution very up-to-date\footnote{For \texlive,
+ consider using the complementary
+ \href{http://tlcontrib.metatex.org/} {tlcontrib} repository.} and also avoid
+using \lualatex for critical documents at least for some time.
+
+As a general rule, this guide documents things as they are at the time it is
+written or updated, without keeping track of changes. Hopefully, you'll update
+your distribution as a whole so that you always get matching versions of this
+guide and the packages, formats and engine it describes.
+
+\section{Essenzielle Pakete und Praktiken}\label{essential}
+
+Dieser Abschnitt präsentiert die Pakete, die Sie als Anwender möglicherweise
+immer laden wollen oder über die Sie als Entwickler auf jeden Fall Bescheid
+wissen sollten.
+
+\subsection{Anwender-Level}
+
+\pkdesc{fontspec}{\WSPR}{\xetex, \luatex}{\latex}{%
+macros/latex/contrib/fontspec/}[https://github.com/wspr/fontspec/]
+Schönes Interface zur Schriftartenverwaltung, welches gut in die \latex
+Schriftartenauswahlschema integriert ist. Dies wurde schon in einem vorherigen
+Abschnitt vorgestellt.
+
+\subsection{Entwickler-Level}
+
+\subsubsection{Naming conventions}
+
+Auf der \tex Seite sind Kontrollsequenzen, die mit ©\luatex© beginnen, für
+Primitiven reserviert. Es wird stark empfohlen, dass Sie \emph{keine} solcher
+Kontrollsequenzen definieren, um Namensueberschneidungen mit zukünftigen
+Versionen von \luatex zu verhindern. Sollten Sie hervorheben wollen, dass ein
+Makro \luatex-spezifisch ist, empfehlen wir, dass Sie stattdessen das ©\lua©
+Präfix (ohne folgendem ©tex©) benutzen. Es ist in Ordnung, das ©\luatex@©
+Präfix für interne Makros zu benutzen, da primitive Namen nie ©@© enthalten,
+dennoch könnte dies Verwirrung stiften. Ausserdem benutzen Sie ja schon ein
+einzigartigen Präfix für interne Makros in allen Ihren Paketen, nicht wahr?
+
+Auf der Lua-Seite halten Sie bitte den globalen Namespace so sauber wie möglich.
+ Das heisst, Sie verwenden eine Tabelle ©mypackage© and setzen alle Ihre
+öffentlichen Funktionen und Objekte in diese. Sie möchten möglicherweise dafür
+Lua's \href{http://www.lua.org/manual/5.1/manual.html#pdf-module}
+{\code{module()}} benutzen.
+Andere Strategien für die Lua Modulverwaltung werden in
+\href{http://www.lua.org/pil/15.html} {Kapitel~15 aus \emph{Programming in Lua}}
+ diskutiert. Es ist ausserdem eine gute Idee ©local© für Ihre internen
+Variablen und Funktionen zu verwenden. Zu guter Letzt wird zur Vermeidung
+von Überschneidungen mit zukünftigen Versionen von \luatex empfohlen, die
+Namespaces von \luatex's Standardbibliotheken nicht zu verändern.
+
+\subsubsection{Engine und Modusfeststellung}\label{detect}
+
+Zahlreiche Pakete erlauben es, die Engine festzustellen, die gegenwärtig mit
+der Verarbeitung des Dokuments beschäftigt ist.
+
+\pkdesc{ifluatex}{\HO}{all}{\latex, Plain}{%
+ macros/latex/contrib/oberdiek/}
+Stellt ©\ifluatex© zur Verfügung und stellt sicher, dass ©\luatexversion©
+benutzbar ist.
+
+\pkdesc{iftex}{\VK}{all}{\latex, Plain}{%
+ macros/latex/contrib/iftex/}[http://bitbucket.org/vafa/iftex]
+Stellt ©\ifPDFTeX©, ©\ifXeTeX©, ©\ifLuaTeX© und korrespondierendes ©\Require©
+Kommandos zur Verfügung.
+
+\pkdesc{expl3}{The \LaTeX3 Project}{all}{\latex}{%
+ macros/latex/contrib/expl3/}[http://www.latex-project.org/code.html]
+Stellt neben \emph{vieler} anderer Dinge ©\luatex_if_engine:TF©,
+©\xetex_if_engine:TF© und deren Varianten zur Verfügung.
+
+\pkdesc{ifpdf}{\HO}{all}{\latex, Plain}{%
+ macros/latex/contrib/oberdiek/}
+Stellt den ©\ifpdf© Schalter zur Verfügung. \luatex, wie auch \pdftex kann
+sowohl PDF als auch DVI Ausgaben erzeugen; letzteres ist nicht wirklich sinnvoll
+ mit \luatex, da es keine erweiterten Funktionen wie Unicode und moderne
+Schriftformate unterstützt. Der ©\ifpdf© Schalter ist nur aktiv, wenn und nur
+wenn Sie \pdftex oder \luatex im PDF Modus laufen lassen (beachten Sie dass dies
+ nicht für \xetex gilt, dessen PDF Unterstuetzung anders funktioniert).
+
+
+\subsubsection{Grundlegende Ressourcen}
+
+\pkdesc{luatexbase}{\ER \& \MPG}{\luatex}{\latex, Plain}{%
+ macros/luatex/generic/luatexbase/}[https://github.com/mpg/luatexbase]
+Die Text- und \latex-Formate enthalten Makros, um grundlegende \tex Ressourcen
+zu verwalten, wie zum Beispiel Zähl- und Kistenregister. \luatex führt neue
+Ressourcen ein, die anstandslos von Paketen gemeinsam benutzt werden können
+müssen. Dieses Paket stellt die grundlegenden Werkzeuge dafür zur Verfügung:
+die erweiterten konventionellen \tex Ressourcen, catcode Tabellen, Attribute,
+Callbacks sowie zum Laden und Identifizieren von Lua Modulen. Ausserdem verfügt
+es über Werkzeuge, um einige Kompatibilitätsprobleme mit älteren Versionen von
+\luatex zu händeln.
+
+\note{Warnung} Dieses Paket ist derzeitig im Konflikt mit dem \pk{luatex} Paket,
+ da sie nahezu das Gleiche machen. Die entsprechenden Paketautoren sind sich
+dieser Situation bewusst und planen die beiden Pakete in der nahen Zukunft zu
+verschmelzen. Noch ist nicht klar, wann dies geschehen wird.
+
+\pkdesc{luatex}{\HO}{\luatex}{\latex, Plain}{%
+ macros/latex/contrib/oberdiek/}
+Sehen Sie sich die Beschreibung des oben an. Dieses Paket stellt die selben
+Kernfunktionalitaeten, ausser Callback-Management und Lua Moduldentifizierung,
+zur Verfügung.
+
+\pkdesc{lualibs}{\ER}{\luatex}{Lua}{%
+ macros/luatex/generic/lualibs/}[https://github.com/mpg/lualibs]
+Eine Zusammenstellung von Lua-Bibliotheken und Erweiterungen der
+Standardbibliotheken; meist abgeleitet von den \context-Bibliotheken. Wenn Sie
+eine grundlegende Funktion brauchen, die Lua nicht zur Verfügung stellt, dann
+prüfen Sie dieses Paket, bevor Sie eine eigene Implementierung vornehmen.
+
+\subsubsection{Font internals}\label{fontint}
+
+Diese Pakete werden von \pk{fontspec} geladen, um einige Low-Level-Probleme von
+Schriften und Encoding zu haendeln. Ein normaler Anwender sollte nur
+\pk{fontspec} nutzen, aber ein Entwickler sollte darüber Kenntnis haben.
+
+\pkdesc{luaotfload}{\ER \& \KH}{\luatex}{\latex, Plain}{%
+ macros/luatex/generic/luaotfload/}[https://github.com/khaledhosny/luaotfload]
+Low-level Open Type Schriften Lader, adaptiert von einem Teil von \context.
+Grundsätzlich benutzt es die ©fontloader© Lua-Bibliothek und die entsprechenden
+Callbacks, um eine Syntax für die ©\font© Primitive ähnlich wie tetex
+bereitzustellen, und die entsprechenden Schriftenfunktionalitäten umzusetzen.
+ Zudem verwaltet es auch eine Schriftendatenbank für transparenten Zugriff auf
+die Schriften im System und der \tex Distribution entweder durch den
+Schriftfamiliennamen oder Dateinamen. Ausserdem hat es auch einen Schriftencache
+ für schnelleres Laden.
+
+\pkdesc{euenc}{\WSPR, \ER \& \KH}{\xetex, \luatex}{\latex}{%
+ macros/latex/contrib/euenc/}[https://github.com/wspr/euenc]
+Setzt die ©EUx© Unicode Schrift Enkodierungen für \latex's \pf{fontenc} System
+um.
+Derzeit benutzt \xelatex ©EU1© und \luatex ©EU2©. Enthält Definitionen
+(\file{fd} Dateien) für Latin Modern, die von \pk{fontspec} geladene
+Standardschrift.
+
+
+\section{Andere Pakete}\label{other}
+
+Bitte beachten Sie, dass diese Pakete nicht in einer bestimmten Reihenfolge
+aufgelistet sind.
+
+\subsection{Anwender-Level}
+
+\pkdesc{luatextra}{\ER \& \MPG}{\luatex}{\latex}{%
+ macros/luatex/latex/luatextra/}[https://github.com/mpg/luatextra]
+Lädt die üblichen Pakete, derzeitig \pk{fontspec}, \pk{luacode}, \pf{metalogo}
+(Kommandos für Logos, unter anderem ©\LuaTeX© und ©\LuaLaTeX©), \pk{luatexbase},
+\pk{lualibs}, \pf{fixltx2e} (Fixes und Erweiterungen fuer den \latex-Kern).
+
+\pkdesc{luacode}{\MPG}{\luatex}{\latex}{%
+ macros/luatex/latex/luacode/}[https://github.com/mpg/luacode]
+Stellt Kommandos und Makros zur Verfügung, die dabei helfen, Lua Code in eine
+\tex-Quelle einzufügen, insbesondere Sonderzeichen.
+
+\pkdesc{luainputenc}{\ER \& \MPG}{\luatex, \xetex, \pdftex}{\latex}{%
+ macros/luatex/latex/luainputenc/}[https://github.com/mpg/luainputenc]
+Hilft, Dokumente zu kompilieren, die auf veralteten Enkodierenden basieren (sei
+ es in der Quelle oder in den Schriften). Wurde schon in der Einfuehrung
+vorgestellt. Wenn \xetex benutzt wird, dann lädt es einfach \pf{xetex-inputenc};
+ unter \pdftex laedt es das standardmäßige \pf{inputenc}.
+
+\pkdesc{luamplib}{\HH, \Taco \& \ER}{\luatex}{\latex, Plain}{%
+ macros/luatex/generic/luamplib/}[https://github.com/mpg/luamplib]
+Stellt eine schöne Schnittstelle für die ©mplib© Lua Bibliothek zur Verfügung
+die Metapost in \luatex einbettet.
+
+\pkdesc{luacolor}{\HO}{\luatex}{\latex}{%
+ macros/latex/contrib/oberdiek/}
+Ändert die Low-Level-Farbenimplementierung, um \luatex Attribute anstatt
+whatsits. Dies macht die Implementierung robuster und korrigiert seltsame
+Fehler, wie zum Beispiel die fehlerhafte Ausrichtung, wenn ©\color© zu Beginn
+einer ©\vbox© gesetzt ist.
+
+\pkdesc{luadirections}{\KH}{\luatex}{\latex, Plain, \context}{}
+[https://github.com/khaledhosny/luadirections]
+Hoehergelegene Schnittstelle zu multi-direcktionaler Unterstützung. Derzeit
+nicht im CTAN vorhanden.
+
+\subsection{Entwickler-Level}
+
+\pkdesc{pdftexcmds}{\HO}{\luatex, \pdftex, \xetex}{\latex, Plain}{%
+ macros/latex/contrib/oberdiek/}
+Auch wenn \luatex normalerweise eine Erweiterung von \pdftex ist, wurden dennoch
+ einige Primitiven entfernt (die, die durch Lua sozusagen abgelöst wurden) oder
+umbenannt. Dieses Paket stellt diese Primitiven mit konsistenten Namen
+durchgängig allen Engines zur Verfügung, unter anderem \xetex, welches vor
+Kurzem einige dieser Primitiven implementiert hat, zum Beispiel ©\strcmp©.
+
+\pkdesc{magicnum}{\HO}{\luatex, \pdftex, \xetex}{\latex, Plain}{%
+ macros/latex/contrib/oberdiek/}
+Stellt einen hierarchischen Zugriff auf ``magic numbers'', wie Catcodes,
+Gruppentypen usw., die intern von \tex und seinen Nachfolgern benutzt werden,
+zur Verfügung. In \luatex wird eine effizientere Implementierung benutzt und
+eine Lua-Schnittstelle ist bereitgestellt.
+
+\pkdesc{lua-alt-getopt}{Aleksey Cheusov}{\cmd{texlua}}{command-line}{%
+ support/lua/lua-alt-getopt}[http://luaforge.net/project/lua_altgetopt]
+Kommandozeilen-Options-Parser, nahezu vollständig kompatibel mit POSIX und GNU
+getopt, zu benutzen in Kommandozeilen-LUA-Skripten, zum Beispiel
+\cmd{mkluatexfontdb} aus \pk{luaotfload}.
+
+
+\section{Die \cmd{luatex} - und \cmd{lualatex}-Formate}\label{formats}
+
+Dieser Abschnitt ist nur für Entwickler und neugierige Anwender gedacht;
+normale Anwender können dies gefahrlos überspringen. Die folgende Information
+bezieht sich auf \texlive 2010 und höchstwahrscheinlich auch auf \miktex 2.9,
+auch wenn ich dies nicht überprüft habe. Frühere Versionen von \texlive hatten
+eicht unterschiedliche und unvollständigere Arrangements.
+
+\para{Primitivennamen}
+Wie im Abschnitt~\ref{things} erwähnt wurde, sind die Namen der
+\luatex-spezifischen Primitiven nicht die selben im \cmd{lualatex} Format wie
+im \luatex Handbuch. Im \cmd{lualatex} Format (das heisst \luatex mit dem Plain
+Format) sind die Primitiven mit ihrem natürlichen Namen verfügbar, und
+zusätzlich auch mit einem Präfix vorangestellten Namen, um die Entwicklung von
+generischen Paketen zu erleichtern.
+
+Die Rationale, entnommen der Datei \file{lualatexiniconfig.tex} , die dies für
+das \cmd{lualatex} Format umsetzt, ist:
+
+\begin{myquote}
+ \begin{enumerate}
+ \item Alle derzeitigen Makropakete laufen unproblematisch auf pdf(e) TeX,
+daher sind diese Primitiven unberührt.
+ \item Andere nicht-TeX82 Primitiven in \luatex können
+Namensueberschneidungen mit existierenden Makros in Makropaketen verursachen,
+besonders wenn sie sehr ``natürliche'' Namen benutzen, wie zum Beispiel
+©\outputbox©, ©\mathstyle© usw. Solch eine Wahrscheinlichkeit für
+Überschneidungen ist nicht gewünscht, da die meisten existierenden
+LaTeX-Dokumente ohne Änderungen unter \luatex laufen.
+ \item Das \luatex Team möchte keine systematische Präfixrichtlinie
+ vorschreiben, stellt aber netterweise ein Werkzeug zur Verfügung, mit dem
+Präfixe gesetzt werden können. Deshalb haben wir uns entschieden, dies zu
+nutzen. Vorher deaktivierten sogar die Extra-Primitiven, aber nun denken wir,
+dass es besser ist, sie mit der systematischen Präfixvoranstellung zu
+aktivieren, um zu vermeiden, dass jedes Makropaket (oder auch Anwender) diese
+mit vielfaltigen und inkonsistenten Präfixen aktiviert (inkl. dem leeren
+Präfix).
+ \item Der ©luatex©-Praefix wurde ausgewählt, da er bereits als Präfix für
+einige Primitiven benutzt wird, wie zum Beispiel ©\luatexversion©: dadurch
+erhalten diese nicht am Ende einen Doppelpräfix (für Details siehe
+©tex.enableprimitives© im \luatex-Handbuch).
+ \item Die ©\directlua© Primitive wird mit ihrem natürlichen (erlaubt die
+leichte Festellung von \luatex ) sowie mit einem Präfix versehen Namen
+(©\luatexdirectlua© (für Konsistenz mit ©\luatexlatelua©)) bereitgestellt.
+ \item Einige Anmerkungen:
+ \begin{itemize}
+ \item Der offensichtliche Nachteile einer solchen Präfixrichtlinie ist,
+dass die Namen, die von \latex oder einem generischen Makroersteller benutzt
+werden, nicht mit den Namen im Handbuch übereinstimmen. Wir hoffen, dass sich
+dies durch den Gewinn der Rückwärtskompatibilitaet ausgleicht.
+ \item Alle Primitiven, die das Thema Unicode Mathematik behandeln
+beginnen bereits mit ©\U© und werden möglicherweise in der Zukunft mit den
+Namen der \xetex-Primitiven übereinstimmen, sodass möglicherweise ein Präfix
+für diese nicht notwendig oder gewünscht waren. Nichtsdestotrotz haben wir
+versucht, die Präfixregeln so einfach wie möglich zu halten, sodass der
+vorherige Punkt nicht noch schlimmer wird.
+ \item Der endgültige Name einiger Primitiven möge sich seltsam anhören,
+ besonders, die, die bereits den Namen einer Engine enthalten, wie zum Beispiel
+©\luatexOmegaVersion©. Da aber \luatex nicht einfach ein Ersatz für Omega/Aleph
+ist, empfanden wir es als falsch, ©\OmegaVersion© zur Verfügung zu stellen.
+ \item Vielleicht empfinden wir es eines Tages besser, alle Primitiven
+ohne Präfix bereitzustellen. Wenn dies passiert, wird es einfach sein du
+Primitiven ohne Präfix in dem Format hinzuzufügen, während die Namen mit Präfix
+aus Kompatibilitätsgründen beibehalten werden. Andersherum würde dies nicht
+funktionieren; zum Beispiel zu spät zu erkennen, dass wir die Primitiven ohne
+Präfix nicht hätten bereitstellen sollen würde dann alle \luatex-spezifische
+Makropakete kaputtmachen, die bereits geschrieben wurden.
+ \end{itemize}
+ \end{enumerate}
+\end{myquote}
+
+\para{\cs{jobname}}[jobname]
+Der \latex Kernel (and eine Menge Pakete) benutzen Konstrukte wie
+©\input\jobname.aux© aus verschiedensten Gründen. Wenn ©\jobname© Leerzeichen
+enthält, funktioniert dies nicht richtig, da die Argumente von ©\input© beim
+ersten auftretenden Leerzeichen enden. Um dies zu umgehen, setzt \pdftex
+automatisch ©\jobname© in Anführungszeichen wenn gebraucht, aber \luatex tut
+dies aus unerfindlichen Gründen nicht. Ein nahezu vollständiger Workaround ist
+in den \latex-basierten (im Gegensatz zu den plain-basierten) \luatex-Formaten
+vorhanden.
+
+Dies funktioniert aber nicht, wenn \luatex als ©lualatex†'\input†name'©
+aufgerufen wird, im Gegensatz zum gebräuchlicheren ©lualatex†name©. Um diese
+Einschränkung zu umgehen, kann ein Jobname explizit angegeben werden, wie zum
+Beispiel ©lualatex†jobname=name '\input†name'©. Oder besser noch, benutzen Sie
+keine Leerzeichen in den Namen Ihrer \tex-Dateien.
+
+Für mehr Details siehe
+\href{http://www.ntg.nl/pipermail/dev-luatex/2009-April/002549.html}{diesen
+alten Eintrag} und
+\href{http://tug.org/pipermail/luatex/2010-August/001986.html}{ein neuerer
+Eintrag}
+auf der \luatex Mailingliste, und \file{lualatexquotejobname.tex} für die
+Umsetzung eines Workarounds.
+
+\para{babel}
+\luatex bietet dynamisches Laden von Silbentrennungsmustern. Derzeitig gibt es
+keine Unterstützung dafür in \pf{babel} aber einige Dateien wurden angepasst,
+um ein halbdynamisches Laden bereitzustellen, welches eine bessere Ladezeit des
+Formates erreicht. Dies ist nur eine Änderung in der Implementierung; nichts
+sollte auf der Anwenderebene sichtbar sein. Ein verändertes Muster-Ladeschema
+wird auch für Plain-basierten benutzt.
+
+Dokumentation und Implementierungsdetails sind enthalten in
+\file{luatex-hyphen.pdf}. Die Quellen sind Teil des
+\href{http://tug.org/tex-hyphen/}{texhyphen Projektes}.
+
+\para{codes}
+Die Engine setzt selbst keine ©\catcode©s, ©\lccode©s, usw. für nich-ASCII
+Zeichen. Korrekte ©\lccode©s sind im Besonderen essenziell, so dass
+Silbentrennung funktioniert. Die Formate für \luatex enthalten nun
+\file{luatex-unicode-letters.tex}, eine angepasste Version von
+\file{unicode-letters.tex} aus der \xetex Distribution, welches die
+entsprechenden Einstellungen konform zum Unicode Standard setzt.
+
+Dies wurde hinzugefügt, nachdem \texlive 2010 ausgeliefert. Daher wird stark
+empfohlen, dass Sie Ihre Installation aktualisieren, wenn Sie in den Genuss
+einer korrekten Silbentrennung für nicht-ASCII Text kommen wollen.
+
+\section{Dinge, die einfach funktionieren, teilweise funktionieren oder (noch)
+gar nicht funktionieren}
+\label{workornot}
+
+\subsection{Voll funktionierend}\label{working}
+
+\para{Unicode}
+Konventionelles \latex bietet etwas Unterstützung für UTF-8 in Eingabedateien
+an. Aber auf einer niedrigeren Ebene werden nicht-ASCII Zeichen in diesem Fall
+nicht atomar behandelt: sie bestehen auch mehreren elementaren Teilen
+(den \tex{}nikern als \emph{Tokens} bekannt). Demzufolge haben Pakete,
+die Text Zeichen für Zeichen scannen oder andere atomare Operationen auf Zeichen
+ ausüben(z.B. das Ändern ihrer catcodes), oft Probleme mit UTF-8 in
+konventionellem \latex. Zum Beispiel können for nicht-ASCII Zeichen kein short
+verbatim mit \emph{tokens} benutzt werden usw.
+
+Die gute Nachricht ist, dass mit \lualatex einige der Features dieser Pakete
+damit beginnen, mit beliebigen Unicode Zeichen zu funktionieren ohne das Paket
+anpassen zu müssen. The schlechte Nachricht ist, dass dies nicht immer wahr ist.
+ Siehe nächsten Abschnitt für die Details.
+
+\subsection{Teilweise funktionierend}\label{partial}
+
+\para{microtype}
+Paket \pf{microtype} hat eingeschränkte Unterstützung für \luatex: präziser
+gesagt, seit Version 2.4 2010/01/10 sind Protrusion und Expansion verfügbar und
+standardmäßig aktiviert im PDF Modus, aber Kerning, Spacing und Tracking werden
+nicht unterstützt (siehe Tabelle~1 in Abschnitt~3.1 von \file{microtype.pdf}).
+
+Auf der anderen Seite, besitzt \pk{luaotfload}, dass durch \pk{fontspec}
+geladen wird, eine Menge an Mikrotypografischer Funktionen. Das einzige Problem
+besteht daher im Fehlen einer einheitlichen Schnittstelle.
+
+
+\para{xunicode}
+
+Das Paket \pf{xunicode} hat als Hauptaufgabe sicherzustellen, dass die üblichen
+Steuersequenzen für nicht-ASCII-Zeichen (wie etwa ©\'e©) im Unicode-Kontext
+korrekt arbeiten. Es könnte \emph{vermutlich} mit \luatex arbeiten, aber nur mit
+expliziten Tests für \xetex. Wie dem auch sei, \pk{fontspec} benutzt einen
+Trick, um es dennoch zu laden. Daher können Sie es nicht explizit laden, müssen
+es auch nicht, da \pk{fontspec} sich ohnehin darum kümmert.
+
+\para{encodings}
+
+Wie im vorherigen Abschnitt erwähnt, gibt es einige Dinge, die mit UTF-8 unter
+konventionellem Latex manchmal funktionieren, aber eben nicht immer. Zum
+Beispiel können sie mit dem \pf{listings}-Paket unter \lualatex innerhalb
+ihrer Listings nur Zeichen unterhalb von 256 verwenden - das heißt, Zeichen aus
+dem Latin-1 Zeichensatz.
+
+\para{metrics}
+
+Dieser Abschnitt handelt nicht konkret von "funktionieren" oder "nicht
+funktionieren", sondern eher, dass es nicht wie \pdftex oder \xetex
+funktioniert. Sie werden kleinere Unterschiede im Layout und der Silbentrennung
+ihres Textes bemerken. Diese entstehen wegen der Unterschiede zwischen zwei
+Versionen derselben Schriftart bei Anwendung von verschiedenen Maschinen,
+Anpassungen an der Silbentrennung, Ligaturen oder Kerning-Algorithmen, oder
+Unterschieden in den verwendeten Silbentrennungs-Mustern (Muster von \pdftex
+frieren in der Regel ein, aber \luatex und \xetex nutzen neuere Versionen
+für Sprachen).
+
+Wenn Sie jemals einen größeren Unterschied zwischen pdf\latex und \lualatex mit
+der selben Schriftart sehen, dann ist es nicht ungewöhnlich, dass es sich um einen
+Fehler in \lualatex\footnote{\lualatex 0.60 hatte einen Fehler, der die
+Silbentrennung nach einer \code{-{}-{}-}-Ligatur am Ende eines Abschnittes
+verhinderte.} handelt. Wie für gewöhnlich stellen Sie sicher, dass ihre
+Distribution aktuell ist.
+
+\par{babel}
+
+Kurz gesagt: Es arbeitet fast immer ohne Probleme mit latinisierten Sprachen.
+Für andere Sprachen kann es Probleme geben. Ein moderneres, weniger fertigeres
+Paket für die Mehrsprachigkeit ist \pf{polyglossia}, das für \xelatex verfügbar
+ist. Das Paket gibt es für \lualatex noch nicht.
+
+\subsection{(Noch) nicht funktionierend}\label{notworking}
+
+\para{Alte Encodings}[oldenco] Pakete, die mit Eingabedateien oder Ausgabe
+(Schriftarten) spielen, werden sehr wahrscheinlich nicht mit \lualatex
+funktionieren. Die gute Nachricht ist, dass Unicode einen viel mächtigeren
+Ansatz zur Lösung von Encoding-Problemen bereitstellt, als die alten Pakete.
+Daher werden Sie die alten Pakete ohnehin nicht benötigen. Leider ist noch nicht
+alles in die glitzernde neue Welt von Unicode portiert worden und es wird
+noch ein reduzierte Auswahl für einige Zeit geben, was besonders auf
+Schriftarten zutrifft.
+
+\para{soul} Das \pf{soul}-Paket benutzt einen schlauen Trick mit einer
+Festbreitenschriftart, um Zeichen zu zählen. Wie dem auch sei, wegen Unterschiede
+im Schriftartenhandling funktioniert dies nicht mit mehr als 256 Zeichen.
+
+\para{Leerzeichen} Leerzeichen in Dateinamen sind nicht gut unterstützt, was
+generell für die \tex Welt gilt.
+
+\end{document}
+
+% vim: spell spelllang=en
diff --git a/info/luatex/lualatex-doc/Makefile b/info/luatex/lualatex-doc/Makefile
new file mode 100644
index 0000000000..f2778000a5
--- /dev/null
+++ b/info/luatex/lualatex-doc/Makefile
@@ -0,0 +1,47 @@
+NAME = lualatex-doc
+FORMAT = lualatex
+
+DOC = $(NAME).pdf
+SRC = $(NAME).tex
+README = README
+MKD = $(README).markdown
+
+SRCFILES = $(SRC) Makefile lltxdoc.cls
+DOCFILES = $(DOC) $(README) News
+ALL = $(SRCFILES) $(DOCFILES)
+
+GENERATED = $(DOC) $(README)
+
+all: lualatex-doc.pdf
+world: all ctan
+
+.PHONY: all world
+
+# (with the next version of latexmk: -pdf -pdflatex=lualatex)
+LATEXMK_FMT = -pdf -e '$$pdflatex = q(lualatex %O %S)'
+
+%.pdf: %.tex
+ latexmk -silent $(LATEXMK_FMT) $< >/dev/null
+
+$(README): $(MKD)
+ @cp $(MKD) $(README)
+
+ctan: $(NAME).tds.zip
+ @zip -q $(NAME).zip $(ALL) $(NAME).tds.zip
+
+$(NAME).tds.zip -q: $(ALL)
+ @rm -rf texmf
+ @mkdir -p texmf/doc/$(FORMAT)/$(NAME)
+ @cp $(DOCFILES) texmf/doc/$(FORMAT)/$(NAME)
+ @mkdir -p texmf/source/$(FORMAT)/$(NAME)
+ @cp $(SRCFILES) texmf/source/$(FORMAT)/$(NAME)
+ @cd texmf && zip -q -r ../$(NAME).tds.zip .
+ @rm -rf texmf
+
+.PHONY: clean mrproper
+
+clean:
+ @latexmk -silent -c >/dev/null
+
+mrproper: clean
+ @rm -f -- $(GENERATED) $(NAME)*.zip
diff --git a/info/luatex/lualatex-doc/News b/info/luatex/lualatex-doc/News
new file mode 100644
index 0000000000..29ef9b4a97
--- /dev/null
+++ b/info/luatex/lualatex-doc/News
@@ -0,0 +1,20 @@
+2013/05/10 (Elie Roux)
+ * update for the large changes appearing in TeXLive 2013 and
+ for Lua 5.2.
+
+2010/11/11
+ * fix a lot of typos, thanks to all readers
+ * add a paragraph about hyphenation and other metric changes, with
+ relevant information provided by Stephan Hennig
+ * add a stub paragraph about languages support (suggested by Stephan)
+ * fix euenc/xunicode description thanks to Ulrike Fischer
+ * be more realistic about soul and listings thanks to Ulrike
+ * add a paragraph about luatex-unicode-letters.tex
+ * add a paragraph about modified hyphenation loading
+ * mention LuaTeX's beta status
+ * mention new luacode package, update luatextra description
+
+2010/11/08
+ * initial release
+
+vim: spell spelllang=en
diff --git a/info/luatex/lualatex-doc/README b/info/luatex/lualatex-doc/README
new file mode 100644
index 0000000000..8c5db2745c
--- /dev/null
+++ b/info/luatex/lualatex-doc/README
@@ -0,0 +1,23 @@
+A guide to LuaLaTeX
+===================
+
+This document is a map, or touristic guide, for the new world of LuaLaTeX.
+Though focusing on LuaLaTeX, it includes relevant information about LuaTeX
+with the Plain format, too.
+
+The intended audience ranges from complete newcomers (with a working knowledge
+of conventional LaTeX) to package developers. This guide is intended to be
+comprehensive in the following sense: it contains pointers to all relevant
+sources, gathers information that is otherwise scattered, and adds
+introductory material.
+
+Feedback and suggestions for improvement are most welcome.
+
+License
+-------
+
+Written by Manuel Pégourié-Gonnard <mpg@elzevir.fr>, 2010.
+
+Distributed under the terms of the [_GNU free documentation licence_][gfdl].
+
+[gfdl]: http://www.gnu.org/licenses/fdl.html
diff --git a/info/luatex/lualatex-doc/lltxdoc.cls b/info/luatex/lualatex-doc/lltxdoc.cls
new file mode 100644
index 0000000000..ae0e8961b1
--- /dev/null
+++ b/info/luatex/lualatex-doc/lltxdoc.cls
@@ -0,0 +1,110 @@
+% private class for lualatex-doc
+% see lualatex-doc.tex for copying conditions
+
+\ProvidesClass{lltxdoc}
+
+\LoadClass[a4paper]{scrartcl}
+\RequirePackage{fontspec}
+\RequirePackage{metalogo, xspace, ifmtarg, xargs, fancyvrb}
+\RequirePackage[table]{xcolor}
+\RequirePackage[english]{babel}
+\RequirePackage[colorlinks=true]{hyperref}
+\RequirePackage{bookmark}
+
+\defaultfontfeatures{Ligatures=TeX, Scale=MatchLowercase}
+\setmainfont{Linux Libertine O}
+\setsansfont{Kurier}
+\setmonofont{Inconsolata}
+
+\newcommand*\simplelogo [1] {%
+ \ifcsname #1\endcsname \else \badlogocommand \fi
+ \lowercase{\expandafter\simple@logo\expandafter{%
+ \csname #1\expandafter\endcsname\expandafter}}\expandafter{%
+ \csname #1\endcsname}{#1}}
+\newcommand*\simple@logo [3] {%
+ \newcommand #1 {#2\xspace}%
+ \pdfstringdefDisableCommands{\def#1{#3\space}}}
+
+\providecommand \ConTeXt {Con\TeX{}t}
+\providecommand \pdfTeX {pdf\TeX}
+\providecommand \TeXLive {\TeX\thinspace Live}
+\providecommand \MiKTeX {Mik\TeX}
+
+\simplelogo {TeX}
+\simplelogo {LaTeX}
+\simplelogo {LuaTeX}
+\simplelogo {LuaLaTeX}
+\simplelogo {XeTeX}
+\simplelogo {XeLaTeX}
+\simplelogo {ConTeXt}
+\simplelogo {pdfTeX}
+\simplelogo {MiKTeX}
+\simplelogo {TeXLive}
+
+\colorlet{code}{blue!80!black}
+\fvset{formatcom=\color{code}}
+\DefineShortVerb\©
+\catcode`\  10 % non-breakable space
+
+\newcommand*\email [1] {<\href{mailto:#1}{#1}>}
+\newcommand*\ctan [1] {\href{http://mirror.ctan.org/#1}{\nolinkurl{#1}}}
+\newcommand \file {\nolinkurl}
+\newcommand*\note [1] {\noindent\textsf{\bfseries #1.}\quad\ignorespaces}
+\newcommand \cmd {\texttt}
+\newcommand \code [1] {\texorpdfstring {\texttt{\color{code}#1}} {#1}}
+\newcommand*\cs [1] {\code{\textbackslash #1}}
+
+\newcommandx*\para [2][2] {%
+ \@ifmtarg{#2}{\para@{#1}{#1}}{\para@{#1}{#2}}}
+\newcommand \para@ [2] {%
+ \par \medskip
+ \hypertarget{para.#2}{}%
+ \belowpdfbookmark{#1}{para.#2}%
+ \noindent
+ \label{para.#2}%
+ \makebox [0pt][r] {%
+ \textsf{\bfseries #1\quad}}%
+ \ignorespaces
+}
+\newcommandx*\pararef [3][1, 3] {%
+ \@ifmtarg{#3}{\para@ref{#1}{#2}{#2}}{\para@ref{#1}{#2}{#3}}}
+\newcommand \para@ref [3] {%
+ \hyperlink{para.#3}{#1{#2}}}
+\newcommand*\parapageref [1] {%
+ \autopagref{para.#1}}
+
+\newcommand \pf {\textsf}
+\newcommand \pk {\pararef[\pf]}
+
+\newcommandx*\pkdesc [6][6] {%
+ \para {#1}
+ \pkditem {Engines} {#3}
+ \pkditem {Formats} {#4}
+ \pkditem {Authors} [\\]{#2}
+ \pkditem {CTAN location} [\\]{#5}[\ctan]
+ \pkditem {Development url} [\\]{#6}[\url]
+ \newline
+}
+\newcommandx*\pkditem [4][2,4] {\@ifnotmtarg{#3}{%
+ #2\textsf{\bfseries #1:} #4{#3}.%
+ }}
+
+\newcommand \WSPR {Will Robertson\xspace}
+\newcommand \KH {Khaled Hosny\xspace}
+\newcommand \HO {Heiko Oberdiek\xspace}
+\newcommand \ER {Élie Roux\xspace}
+\newcommand \MPG {Manuel Pégourié-Gonnard\xspace}
+\newcommand \VK {Vafa Khalighi\xspace}
+\newcommand \HH {Hans Hagen\xspace}
+\newcommand \Taco {Taco Hoewater\xspace}
+\newcommand \FC {François Charette\xspace}
+\newcommand \PHG {Philipp Gesang\xspace}
+\newcommand \AR {Arthur Reuntenauer\xspace}
+
+\newenvironment{myquote}{%
+ \list{}{\leftmargin0pt \rightmargin1em}%
+ \item\relax
+ \small
+}{%
+\endlist
+}
diff --git a/info/luatex/lualatex-doc/lualatex-doc.pdf b/info/luatex/lualatex-doc/lualatex-doc.pdf
new file mode 100644
index 0000000000..27dfd1bafa
--- /dev/null
+++ b/info/luatex/lualatex-doc/lualatex-doc.pdf
Binary files differ
diff --git a/info/luatex/lualatex-doc/lualatex-doc.tex b/info/luatex/lualatex-doc/lualatex-doc.tex
new file mode 100644
index 0000000000..445c9ff1c0
--- /dev/null
+++ b/info/luatex/lualatex-doc/lualatex-doc.tex
@@ -0,0 +1,743 @@
+% lualatex-doc: a guide to LuaLaTeX
+%
+% Written by Manuel Pégourié-Gonnard <mpg@elzevir.fr>, 2010.
+%
+% Distributed under the terms of the GNU free documentation licence:
+% http://www.gnu.org/licenses/fdl.html
+% without any invariant section or cover text.
+
+\documentclass{lltxdoc}
+
+\title{A guide to \lualatex}
+\author{Manuel Pégourié-Gonnard \email{mpg@elzevir.fr}}
+\date{\today}
+
+\begin{document}
+
+\maketitle
+
+\begin{abstract}
+ This document is a map, or touristic guide, for the new world of
+ \lualatex.\footnote{Though focusing on \lualatex, it includes relevant
+ information about \luatex with the Plain format, too.} The intended
+ audience ranges from complete newcomers (with a working knowledge of
+ conventional \latex) to package developers. This guide is intended to be
+ comprehensive in the following sense: it contains pointers to all relevant
+ sources, gathers information that is otherwise scattered, and adds
+ introductory material.
+
+ Feedback and suggestions for improvement are most welcome. This document is
+ work in progress; thanks for your comprehension and patience.
+\end{abstract}
+
+\vspace{\stretch{1}}
+\setcounter{tocdepth}{2}
+\listoftoc*{toc}
+\vspace*{\stretch{2}}
+\clearpage
+
+\section{Introduction}\label{intro}
+
+\subsection{Just what is \lualatex?}\label{what}
+
+To answer this question, we need to mention a few details about the \tex world
+that you may usually ignore: the difference between an \emph{engine} and a
+\emph{format}. An engine is an actual computer program, while a format is a
+set of macros executed by an engine, usually preloaded when the engine is
+invoked with a particular name.
+
+Actually, a format is more or less like a document class or a package, except
+it is associated with a particular command name. Imagine there is a command
+\cmd{latex-article} that would do the same as \cmd{latex}, except you wouldn't
+need to say ©\documentclass{article}© at the beginning of your file.
+Similarly, in current distributions, the command \cmd{pdflatex} is the same as
+the command \cmd{pdftex} except that you don't need to put the instructions to
+load \latex at the beginning of your source file. This is convenient, and
+slightly more efficient too.
+
+Formats are great because they implement powerful commands using the basic
+tools an engine provides. However the power of the format is sometimes
+limited by the engine's tools set, so people started developing more
+powerful engines so that other people can implement even more powerful formats
+(or packages). The most famous engines now (except the original \tex) are
+\pdftex, \xetex and \luatex.
+
+To further complicate the picture, the original \tex engine produced only DVI
+files, while its successors may (also) produce PDF file. Each command in your
+system corresponds to a particular engine with a particular format and a
+particular output mode. The following table summarizes this: rows are indexed
+by format, columns by engine, and in each cell the first line is the command
+for this engine with this format in DVI mode, and the second for the same PDF
+mode.
+
+\begin{center}
+ \newcommand*\cell [2] {%
+ \parbox{6em}{\centering\leavevmode\color{code}\ttfamily
+ \strut\maybe{#1} \\ \strut\maybe{#2}}}
+ \makeatletter
+ \newcommand*\maybe [1] {%
+ \@ifmtarg{#1} {\textcolor{gray}{\normalfont (none)}} {#1}}
+ \begin{tabular}{l|cccc}
+ & \tex & \pdftex & \xetex & \luatex
+ \\ \hline
+ Plain
+ & \cell{tex}{}
+ & \cell{etex}{pdftex}
+ & \cell{}{xetex}
+ & \cell{dviluatex}{luatex}
+ \\ \hline
+ \latex
+ & \cell{}{}
+ & \cell{latex}{pdflatex}
+ & \cell{}{xelatex}
+ & \cell{dvilualatex}{lualatex}
+ \\
+ \end{tabular}
+\end{center}
+
+We can now answer the title question: \lualatex is the \luatex engine with the
+\latex format. Well, this answer isn't very satisfying if you don't know what
+\luatex and \latex are.
+
+\medskip
+
+As you probably know, \latex is the general framework
+in which documents begin with ©\documentclass©, packages are loaded with
+©\usepackage©, fonts are selected in a clever way (so that you can switch to
+boldface while preserving italics), pages are build with complicated
+algorithms
+including support for headers, footers, footnotes, margin notes, floating
+material, etc. This mostly doesn't change with \lualatex, but new and more
+powerful packages are available to make parts of the system work in a better
+way.
+
+So, what's \luatex? Short version: the hottest \tex engine right now!
+Long version: It is the designated successor of \pdftex and
+includes all of its core features: direct generation of PDF files with support
+for advanced PDF features and micro-typographic enhancements to \tex
+typographic algorithms. The main new features of \luatex are:
+\begin{enumerate}
+ \item Native support of Unicode, the modern standard for character
+ classification and encoding, supporting all characters in the world, from
+ English to traditional Chinese through Arabic, including a lot of
+ mathematical (or otherwise specialised) symbols.
+ \item Inclusion of Lua as an embedded scripting language (see
+ section~\ref{luaintex} for details).
+ \item A lot of wonderful Lua libraries, including:
+ \begin{itemize}
+ \item ©fontloader©, supporting modern font formats such as
+ TrueType and OpenType;
+ \item ©font©, allowing advanced manipulation of the fonts
+ from within the document;
+ \item ©mplib©, an embedded version of the graphic program MetaPost;
+ \item ©callback©, providing hooks into parts of the \tex engine that
+ were previously inaccessible to the programmer;
+ \item utility libraries for manipulating images, pdf files, etc.
+ \end{itemize}
+\end{enumerate}
+Some of these features, such as Unicode support, directly impact all
+documents, while others merely provide tools that package authors will use to
+provide you with more powerful commands and other enhancements.
+
+\subsection{Switching from \latex to \lualatex}\label{switch}
+
+As the previous section explains, \lualatex is mostly like \latex, with a few
+differences, and more powerful packages and tools available. Here we present
+an absolute minimum you should know to produce a document with \lualatex, while
+the rest of the document provides more details about the available packages.
+
+There are only three differences:
+\begin{enumerate}
+ \item Don't load \pf{inputenc}, just encode your source in UTF-8.
+ \item Don't load \pf{fontenc} nor \pf{textcomp}, but load \pf{fontspec}.
+ \item \pf{babel} works with \lualatex{} but you can load \pf{polyglossia} instead.
+ \item Don't use any package that changes the fonts, but use \pf{fontspec}'s
+ commands instead.
+\end{enumerate}
+So, you only need to get familiar with \pf{fontspec}, which is
+easy: select the main (serif) font with ©\setmainfont©, the sans serif font
+with ©\setsansfont© and the mono-spaced (typewriter) font with ©\setmonofont©.
+The argument to these commands is the human-friendly name of the font, for
+example ©Latin Modern Roman© rather than ©ec-lmr10©. You probably want to use
+©\defaultfontfeatures{Ligatures=TeX}© before these commands to keep the usual
+\tex substitutions (such as ©---© for an em-dash) working.
+
+The good news is: you can directly access any font on your operating system
+(in addition to those of your \tex distribution) including TrueType and
+OpenType fonts and have access to their most advanced features. It means it
+is now easy to install for use with \lualatex any modern font you may download
+or purchase from an editor and benefit from their full potential.
+
+Now for the bad news: it is not always easy to get a list of all available
+fonts. Under Windows with \texlive, the command-line tool \cmd{fc-list} lists
+them all, but is not very friendly. Under Mac OS X, the \emph{Fontbook}
+application lists the fonts of your system, but not those of your \tex
+distribution. Same with \cmd{fc-list} on Linux. More bad news: it is not easy
+to access your old fonts that way. Happily, more fonts are available in modern
+formats every day (well, month or year, actually, if you count only good
+fonts).
+
+\emph{En passant}, let's mention that the content of this section so far also
+holds for \xelatex, that is, \latex over \xetex. Indeed, \xetex shares two of
+the essential features of \luatex: native Unicode and support for modern font
+formats (but doesn't have the other features of \luatex; on the other hand, it
+is more stable right now). Though their implementations concerning fonts are
+vastly different, \pf{fontspec} manages to offer a mostly unified font
+interface for both \xelatex and \lualatex.
+
+\medskip
+
+So, to benefit from the new features of \luatex, you must drop a few parts of
+the old world, namely the fonts that are not available in a modern format (and
+also the liberty to encode your source how you want, but UTF-8 is so much
+superior that this one hardly counts). The package \pk{luainputenc} provides
+various trade-offs that allow you to regain these parts\footnote{While the
+ name suggests it is only about input encodings, the details of \latex's font
+ encoding implementation imply this package is needed (and works) for old
+ fonts too.} possibly at the expense of loosing real Unicode support.
+
+That's all you need to know to start producing documents with \lualatex. I
+recommend you have a look at the \pf{fontspec} manual and actually try to
+compile a small document using funny fonts. You can then skim over the rest of
+this document as you wish. Section~\ref{workornot} lists all the other
+differences between conventional \latex and \lualatex that I'm aware of.
+
+\subsection{A Lua-in-\tex primer}\label{luaintex}
+
+Lua is a nice, small language, obviously less surprising and much easier to
+learn than \tex as a programming language. The essential reference is the very
+readable book \emph{Programming in Lua}, whose first edition is freely
+\href{http://www.lua.org/pil/} {available online}. For a quick start, I
+recommend you read chapters~1 to~5 and have a quick glance at part~3. Note
+that all the libraries mentioned in chapter~3 are included in \luatex, but the
+©os© library is restricted for security reasons.
+
+Depending on your programming culture, you may be directly interested in the
+rest of part~1 and part~2 which present more advanced features of the
+language, but part~4 is useless in a \luatex context, unless of course you
+want to hack \luatex itself. Finally, the \emph{Lua reference manual} is
+\href{http://www.lua.org/manual/5.2/}{available online} and
+comes with a handy index.
+
+\medskip
+
+Now, let's turn to Lua in \luatex. The main way to execute Lua code from the
+\tex end is the ©\directlua© command, which takes arbitrary Lua code as an
+argument. Conversely, you can pass information from Lua to \tex with
+©tex.sprint©.\footnote{The name probably means ``string print'' as opposed to
+ ``run very fast for a short period of time.''} For example,
+\begin{Verbatim}
+ the standard approximation $\pi = \directlua{tex.sprint(math.pi)}$
+\end{Verbatim}
+prints ``the standard approximation $\pi = \directlua{tex.sprint(math.pi)}$''
+in your document. See how easy it is to mix \tex and Lua?
+
+Actually, there are a few gotchas. Let's look at the Lua to \tex way first,
+it's the simplest (since it's more Lua than \tex). If you look at the \luatex
+manual, you'll see there is another function with a simpler name, ©tex.print©,
+to pass information this way. It works by virtually inserting a full line into
+your \tex source, whose contents are its argument. In case you didn't know,
+\tex does many nasty\footnote{Okay, these are usually nice and helpful
+ actions, but in this case they are most probably unexpected so I call them
+ nasty.} things with full lines of the source:
+ignoring spaces at the beginning and end of line and appending an end-of-line
+character. Most of the time, you don't want this to happen, so I recommend
+using ©tex.sprint© which virtually inserts its argument in the current line,
+so is much more predictable.
+
+If you're enough of a \tex{}nician to know about catcodes, you'll be happy to
+know that ©tex.print© and its variants give you nearly full control over the
+catcodes used for tokenizing the argument, since you can specify a catcode
+table as the first argument. You'll probably want to learn about catcode
+tables (currently~2.7.6 in the \luatex manual) before you're fully happy. If
+you don't know about catcodes, just skip this paragraph.\footnote{Erf, too
+ late, you already read it.}
+
+\medskip
+
+Let's look at ©\directlua© now. To get an idea about how it works, imagine that
+it's a ©\write© command, but it writes only to a virtual file and immediately
+arranges for this file to be fed to the Lua interpreter. On the Lua end, the
+consequence is that each argument of a ©\directlua© command has its own scope:
+local variables from one will not be visible to the other. (Which is rather
+sane, but always good to know.)
+
+Now, the major gotcha is that before being fed to the Lua interpreter, the
+argument is first read and tokenised by \tex, then fully expanded and turned
+back into a plain string. Being read by \tex has several consequences. One of
+them is that end of lines are turned into spaces, so the Lua interpreter sees
+only one (long) line of input. Since Lua is a free-form language, it doesn't
+usually matter, but it does if you use comments:
+\begin{Verbatim}
+ \directlua{a_function()
+ -- a comment
+ another_function()}
+\end{Verbatim}
+won't do what you probably expect: ©another_function()© will be seen as part
+of the comment (it's only one line, remember).
+
+Another consequence of being read by \tex is that successive spaces are merged
+into one space, and \tex comments are discarded. So, here is a surprisingly
+correct version of the previous example.
+\begin{Verbatim}
+ \directlua{a_function()
+ % a comment
+ another_function()}
+\end{Verbatim}
+It is also worth noticing that, since the argument basically is inside a
+©\write©, it's in expansion-only context. If you don't know what it means, let
+me say that expansion issues are mostly what makes \tex programming so
+difficult to avoid expanding further on that matter.
+
+\medskip
+
+I'm sorry if the last three paragraphs were a bit \tex{}nical in nature but
+I thought you had to know. To reward you for staying with me, here is a
+debugging trick. Put the following code near the beginning of your document:
+\begin{Verbatim}
+ \newwrite\luadebug
+ \immediate\openout\luadebug luadebug.lua
+ \AtEndDocument{\immediate\closeout\luadebug}
+ \newcommand\directluadebug{\immediate\write\luadebug}
+\end{Verbatim}
+Then, when you have a hard time understanding why a particular call to
+©\directlua© doesn't do what you expect, replace this instance of the command
+with ©\directluadebug©, compile as usual and look in the file
+\file{luadebug.lua} produced what the Lua interpreter actually read.
+
+The \pk{luacode} package provides commands and environments that help to
+varying degrees with some of these problems. Hoewever, for everything but
+trivial pieces of Lua code, it is wiser to use an external file containing
+only Lua code defining functions, then load it and use its functions. For
+example:
+\begin{Verbatim}
+ \directlua{dofile("my-lua-functions.lua")}
+ \newcommand*{\greatmacro}[2]{%
+ \directlua{my_great_function("\luatexluaescapestring{#1}", #2)}}
+\end{Verbatim}
+The example assumes that ©my_great_function© is defined in
+©my-lua-functions.lua© and takes a string and a number as arguments. Notice
+that we carefully use the ©\luatexluaescapestring© primitives on the string
+argument to escape any backslash or double-quote it might contain and which
+would confuse the Lua parser.\footnote{If you ever used SQL then the concept
+ of escaping strings is hopefully not new to you.}
+
+\medskip
+
+That's all concerning Lua in \tex. If you're wondering why
+©\luatexluaescapestring© has such a long and silly name, you might want to
+read the next section.
+
+\subsection{Other things you should know}\label{things}
+
+Just in case it isn't obvious, the \luatex manual, \file{luatexref-t.pdf}, is
+a great source of information about \luatex and you'll probably want to
+consult it at some point (though it is a bit arid and technical).
+
+It is important to know that the name of the new primitives of \luatex as you
+read them in the manual are not the actual names you'll be able to use in
+\lualatex. To prevent clashes with existing macro names, all new primitives
+have been prefixed with ©\luatex© unless they already start with it, so
+©\luaescapestring© becomes ©\luatexluaescapetring© while ©\luatexversion©
+remains ©\luatexversion©. The rationale is detailed in section~\ref{formats}.
+
+\medskip
+
+Oh, and by the way, did I mention that \luatex is in beta and version 1.0 is
+expected in spring 2014? You can learn more on the roadmap page of
+\href{http://luatex.org/}{the \luatex site}. Stable betas are released
+regularly and are included in \texlive since 2008 and \miktex since 2.9.
+
+Not surprisingly, support for \luatex in \latex is shiny new, which means it
+may be full of (shiny) bugs, and things may change at any point. You might
+want to keep your \tex distribution very up-to-date\footnote{For \texlive,
+ consider using the complementary
+ \href{http://tlcontrib.metatex.org/} {tlcontrib} repository.} and also avoid
+using \lualatex for critical documents at least for some time.
+
+As a general rule, this guide documents things as they are at the time it is
+written or updated, without keeping track of changes. Hopefully, you'll update
+your distribution as a whole so that you always get matching versions of this
+guide and the packages, formats and engine it describes.
+
+\section{Essential packages and practices}\label{essential}
+
+This section presents the packages you'll probably want to always load as a
+user, or that you should absolutely know about as a developer.
+
+\subsection{User-level}
+
+\pkdesc{fontspec}{\WSPR}{\xetex, \luatex}{\latex}{%
+ macros/latex/contrib/fontspec/}[https://github.com/wspr/fontspec/]
+Nice interface to font management, well-integrated in to the \latex font
+selection scheme. Already presented in the previous section.
+
+\pkdesc{polyglossia}{\FC \& \AR}{\xetex, \luatex}{\latex}{%
+ macros/latex/contrib/polyglossia/}[https://github.com/reutenauer/polyglossia/]
+A simple and modern replacement for Babel, working in synergy with \pk{fontspec}.
+
+\subsection{Developer-level}
+
+\subsubsection{Naming conventions}
+
+On the \tex end, control sequences starting with ©\luatex© are reserved for
+primitives. It is strongly recommended that you do \emph{not} define any such
+control sequence, to prevent name clashes with future versions of \luatex. If
+you want to a emphasize that a macro is specific to \luatex, we recommend that
+you use the ©\lua© prefix (without a following ©tex©) instead. It is okay to
+use the ©\luatex@© prefix for internal macros, since primitive names never
+contain ©@©, but it might be confusing. Moreover, you're already using a
+unique prefix for internal macros in all of your packages, aren't you?
+
+On the Lua end, please keep the global namespace as clean as possible. That
+is, use a table ©mypackage© and put all your public functions and objects in
+this table. You might want to avoid using Lua's deprecated \code{module()}.
+Other strategies for Lua module management are discussed in
+\href{http://www.lua.org/pil/15.html} {chapter~15 of \emph{Programming in
+ Lua}}, and examples are given in \file{luatexbase-modutils.pdf}. Also, it
+is a good and necessary practice to use ©local© for your internal variables and
+functions. Finally, to avoid clashes with future versions of \luatex, it is
+necessary to avoid modifying the namespaces of \luatex's default libraries.
+
+\subsubsection{Engine and mode detection}\label{detect}
+
+Various packages allow to detect the engine currently processing the document.
+
+\pkdesc{ifluatex}{\HO}{all}{\latex, Plain}{%
+ macros/latex/contrib/oberdiek/}
+Provides ©\ifluatex© and makes sure ©\luatexversion© is available.
+
+\pkdesc{iftex}{\VK}{all}{\latex, Plain}{%
+ macros/latex/contrib/iftex/}[http://bitbucket.org/vafa/iftex]
+Provides ©\ifPDFTeX©, ©\ifXeTeX©, ©\ifLuaTeX© and corresponding ©\Require©
+commands.
+
+\pkdesc{expl3}{The \LaTeX3 Project}{all}{\latex}{%
+ macros/latex/contrib/expl3/}[http://www.latex-project.org/code.html]
+Amongst \emph{many} other things, provides ©\luatex_if_engine:TF©,
+©\xetex_if_engine:TF© and their variants.
+
+\pkdesc{ifpdf}{\HO}{all}{\latex, Plain}{%
+ macros/latex/contrib/oberdiek/}
+Provides ©\ifpdf© switch. \luatex, like \pdftex, can produce either PDF or DVI
+output; the later is not very useful with \luatex as it doesn't support any
+advanced feature such as Unicode and modern font formats. The ©\ifpdf© switch
+is true if and only if you are running \pdftex-or-\luatex in PDF mode (note
+that this doesn't include \xetex, whose support for PDF is different).
+
+\subsubsection{Basic resources}
+
+\pkdesc{luatexbase}{\ER, \MPG \& \PHG}{\luatex}{\latex, Plain}{%
+ macros/luatex/generic/luatexbase/}[https://github.com/lualatex/luatexbase]
+The Plain and \latex formats provide macros to manage \tex basic resources,
+such as count or box registers. \luatex introduces new resources that need to
+be shared gracefully by packages. This package provides the basic tools to
+manage: the extended conventional \tex resources, catcode tables, attributes,
+callbacks, Lua modules loading and identification. It also provides basic
+tools to handle a few compatibility issues with older version of \luatex.
+
+\note{Warning} This package is currently in conflict with the \pk{luatex}
+package, since they both do almost the same thing. The respective package
+authors are well aware of this situation and plan to somehow merge the two
+packages in the near future, though the timeline is not clear.
+
+\pkdesc{luatex}{\HO}{\luatex}{\latex, Plain}{%
+ macros/latex/contrib/oberdiek/}
+See the description of \pk{luatexbase} above. This package provides the same
+core features except for callback management and Lua module identification.
+
+\pkdesc{lualibs}{\ER \& \PHG}{\luatex}{Lua}{%
+ macros/luatex/generic/lualibs/}[https://github.com/lualatex/lualibs]
+Collection of Lua libraries and additions to the standard libraries; mostly
+derived from the \context libraries. If you need a basic function that Lua
+doesn't provide, check this package before rolling your own implementation.
+
+\subsubsection{Font internals}\label{fontint}
+
+Those packages are loaded by \pk{fontspec} to handle some low-level font and
+encoding issues. A normal user should only use \pk{fontspec}, but a developer
+may need to know about them.
+
+\pkdesc{luaotfload}{\ER, \KH \& \PHG}{\luatex}{\latex, Plain}{%
+ macros/luatex/generic/luaotfload/}[https://github.com/lualatex/luaotfload]
+Low-level OpenType font loading, adapted from the generic subset of \context.
+Basically, it uses the ©fontloader© Lua library and the appropriate callbacks
+to implement a syntax for the ©\font© primitive very similar to that of \xetex
+and implement the corresponding font features. It also handles a font database
+for transparent access to fonts from the system and the \tex distribution
+either by family name or by file name, as well as a font cache for faster
+loading.
+
+\pkdesc{euenc}{\WSPR, \ER \& \KH}{\xetex, \luatex}{\latex}{%
+ macros/latex/contrib/euenc/}[https://github.com/wspr/euenc]
+Implements the EUx Unicode font encodings for \latex's \pf{fontenc} system.
+Currently, \xelatex is using ©EU1© and \lualatex is using ©EU2©. Includes
+definitions (\file{fd} files) for Latin Modern, the default font loaded by
+\pk{fontspec}.
+
+To be precise, \pf{euenc} merely declares the encoding, but
+doesn't provide definitions for LICR macros; this is done by loading
+\pk{xunicode} with ©\UTFencname© defined to ©EU1© or ©EU2©, which
+\pk{fontspec} does. The actual encodings are the same, but it is useful to
+have distinct names so that different \file{fd} files can be used according to
+the engine (which is actually the case with Latin Modern).
+
+\section{Other packages}\label{other}
+
+Note that the packages are not listed in any particular order.
+
+\subsection{User-level}
+
+\pkdesc{luatextra}{\ER \& \MPG}{\luatex}{\latex}{%
+ macros/luatex/latex/luatextra/}[https://github.com/lualatex/luatextra]
+Loads usual packages, currently \pk{fontspec}, \pk{luacode}, \pf{metalogo}
+(commands for logos, including ©\LuaTeX© and ©\LuaLaTeX©), \pk{luatexbase},
+\pk{lualibs}, \pf{fixltx2e} (fixes and enhancements for the \latex core).
+
+\pkdesc{luacode}{\MPG}{\luatex}{\latex}{%
+ macros/luatex/latex/luacode/}[https://github.com/lualatex/luacode]
+Provides commands and macros that help including Lua code in a \tex source,
+especially concerning special characters.
+
+\pkdesc{luainputenc}{\ER \& \MPG}{\luatex, \xetex, \pdftex}{\latex}{%
+ macros/luatex/latex/luainputenc/}[https://github.com/lualatex/luainputenc]
+Helps compiling documents relying on legacy encodings (either in the source or
+with the fonts). Already presented in the introduction. When running \xetex,
+just loads \pf{xetex-inputenc}; under \pdftex, loads the standard
+\pf{inputenc}.
+
+\pkdesc{luamplib}{\HH, \Taco \& \PHG}{\luatex}{\latex, Plain}{%
+ macros/luatex/generic/luamplib/}[https://github.com/lualatex/luamplib]
+Provides a nice interface for the ©mplib© Lua library that embeds metapost in
+\luatex.
+
+\pkdesc{luacolor}{\HO}{\luatex}{\latex}{%
+ macros/latex/contrib/oberdiek/}
+Changes low-level color implementation to use \luatex attributes in place of
+whatsits. This makes the implementation more robust and fixes strange bugs
+such as wrong alignment when ©\color© happens at the beginning of a ©\vbox©.
+
+\subsection{Developer-level}
+
+\pkdesc{pdftexcmds}{\HO}{\luatex, \pdftex, \xetex}{\latex, Plain}{%
+ macros/latex/contrib/oberdiek/}
+Though \luatex is mostly a superset of \pdftex, a few utility primitives were
+removed (those that are sort of superseded by Lua) or renamed. This package
+provides them with consistent names across engines, including \xetex which
+recently implemented some of these primitives, such as ©\strcmp©.
+
+\pkdesc{magicnum}{\HO}{\luatex, \pdftex, \xetex}{\latex, Plain}{%
+ macros/latex/contrib/oberdiek/}
+Provides hierarchical access to ``magic numbers'' such as catcodes, group
+types, etc. used internally by \tex and its successors. Under \luatex, a more
+efficient implementation is used and a Lua interface is provided.
+
+\pkdesc{lua-alt-getopt}{Aleksey Cheusov}{\cmd{texlua}}{command-line}{%
+ support/lua/lua-alt-getopt}[https://github.com/LuaDist/alt-getopt]
+Command-line option parser, mostly compatible with POSIX and GNU getopt, to be
+used in command-line Lua scripts such as \cmd{mkluatexfontdb} from
+\pk{luaotfload}.
+
+\section{The \cmd{luatex} and \cmd{lualatex} formats}\label{formats}
+
+This section is for developers and curious users only; normal users can safely
+skip it. The following information apply to \texlive 2010, and most likely to
+\miktex 2.9 too, though I didn't actually check. Earlier versions of \texlive
+had slightly different and less complete arrangements.
+
+\para{Primitive names}
+As mentioned in section~\ref{things}, the names of the \luatex-specific
+primitives are not the same in the \cmd{lualatex} format as in the \luatex
+manual. In the \cmd{luatex} format (that is, \luatex with the Plain format),
+primitives are available with their natural name, but also with the prefixed
+name, in order to ease development of generic packages.
+
+The rationale, copy-pasted from the file \file{lualatexiniconfig.tex} that
+implements this for the \cmd{lualatex} format, is:
+
+\begin{myquote}
+ \begin{enumerate}
+ \item All current macro packages run smoothly on top of pdf(e)TeX, so
+ those primitives are left untouched.
+ \item Other non-TeX82 primitives in \luatex may cause name clashes with
+ existing macros in macro packages, especially when they use very
+ ``natural'' names such as ©\outputbox©, ©\mathstyle© etc. Such a
+ probability for name clashes is undesirable, since the most existing
+ LaTeX documents that run without change under \luatex, the better.
+ \item The \luatex team doesn't want to apply a systematic prefixing policy,
+ but kindly provided a tool allowing prefixes to be applied. So we chose
+ to use it. Previously, we even disabled the extra primitives, but now
+ we feel it's better to enable them with systematic prefixing, in order
+ to avoid that each and every macro package (or user) enables them with
+ various and inconsistent prefixes (including the empty prefix).
+ \item The ©luatex© prefix was chosen since it is already used as a prefix
+ for some primitives, such as ©\luatexversion©: this way, those
+ primitives don't end up with a double prefix (for details, see
+ ©tex.enableprimitives© in the \luatex manual).
+ \item The ©\directlua© primitive is provided both with its natural name
+ (allowing easy detection of \luatex) and a prefixed version
+ ©\luatexdirectlua© (for consistency with ©\luatexlatelua©).
+ \item Various remarks:
+ \begin{itemize}
+ \item The obvious drawback of such a prefixing policy is that the
+ names used by \latex or generic macro writer won't match the names
+ used in the manual. We hope this is compensated by the gain in
+ backwards compatibility.
+ \item All primitives dealing with Unicode math already begin with ©\U©,
+ and maybe will match the names of \xetex primitives some day, so
+ maybe prefixing was not necessary/desirable for them. However, we
+ tried to make the prefixing rule as simple as possible, so that
+ the previous point doesn't get even worse.
+ \item Maybe some day we'll feel it's better to provide all primitives
+ without prefixing. If this happens, it will be easy to add the
+ unprefixed primitives in the format while keeping the prefixed names
+ for compatibility. It wouldn't work the other way round; i.e.,
+ belatedly realizing that we should not provide the unprefixed
+ primitives would then break any \luatex-specific macro packages
+ that had been written.
+ \end{itemize}
+ \end{enumerate}
+\end{myquote}
+
+\para{\cs{jobname}}[jobname]
+The \latex kernel (and a lot of packages) use constructs like
+©\input\jobname.aux© for various purposes. When ©\jobname© contains spaces,
+this doesn't do the right thing, since the argument of ©\input© ends at the
+first space. To work around this, \pdftex automagically quotes ©\jobname© when
+needed, but \luatex doesn't for some reason. A nearly complete workaround is
+included in \latex-based (as opposed to Plain-based) \luatex formats.
+
+It doesn't work, however, if \luatex is invoked as ©lualatex '\input name'©,
+as opposed to the more usual ©lualatex name©. To work around this
+limitation of the workaround included in the format, specifying a jobname
+explicitly, as in ©lualatex jobname=name '\input name'©. Or even better, just
+don't use spaces in the names of your \tex files.
+
+For more details, see
+\href{http://www.ntg.nl/pipermail/dev-luatex/2009-April/002549.html}{this old
+ thread} and
+\href{http://tug.org/pipermail/luatex/2010-August/001986.html}{this newer one}
+on the \luatex mailing lists, and \file{lualatexquotejobname.tex} for the
+implementation of the workaround.
+
+\para{hyphenation}
+\luatex offers dynamic loading for hyphenation patterns. The support for this in
+\pf{babel} and \pf{polyglossia} appeared only on \texlive 2013, but should
+work well since then.
+
+Documentation and implementation details are included in
+\file{luatex-hyphen.pdf}. The sources are part of the
+\href{http://tug.org/tex-hyphen/}{texhyphen project}.
+
+\para{codes}
+The engine itself does not set ©\catcode©s, ©\lccode©s, etc. for non-ASCII
+characters. Correct ©\lccode©s in particular are essential for hyphenation to
+work. Formats for \luatex now include \file{luatex-unicode-letters.tex}, a
+modified version of \file{unicode-letters.tex} from the \xetex distribution,
+that takes care of settings these values in accordance with the Unicode
+standard.
+
+This was added after \texlive 2010 went out, so you are strongly advised to
+update your installation if you want to enjoy proper hyphenation for non-ASCII
+text.
+
+
+\section{Things that just work, partially work, or don't work (yet)}
+\label{workornot}
+
+\subsection{Just working}\label{working}
+
+\para{Unicode}
+Conventional \latex offers some level of support for UTF-8 in input files.
+However, at a low level, non-ASCII characters are not atomic in this case:
+they consist of several elementary pieces (known as \emph{tokens} to
+\tex{}nicians). Hence, some packages that scan text character by character or
+do other atomic operations on characters (such as changing their catcodes)
+often have problems with UTF-8 in conventional \latex. For example, you can't
+use any non-ASCII character for short verbatim with \pf{fancyvrb}, etc.
+
+The good news is, with \lualatex, some of these package's features start
+working on arbitrary Unicode characters without needing to modify the package.
+The bad news is, this isn't always true. See the next section for details.
+
+\subsection{Partially working}\label{partial}
+
+\para{microtype}
+Package \pf{microtype} has limited support for \luatex: more precisely, as of
+version 2.5 2013/03/13, protrusion and expansion are available and activated
+by default in PDF mode, but kerning, spacing and tracking are not supported
+(see table~1 in section~3.1 of \file{microtype.pdf}).
+
+On the other hand, \pk{luaotfload}, loaded by \pk{fontspec}, supports a lot of
+microtypographic features. So the only problem is the lack of a unified
+interface.
+
+\para{xunicode}
+Package \pf{xunicode}'s main feature is to ensure that the usual control
+sequences for non-ASCII characters (such as ©\'e©) do the right thing in a
+Unicode context. It could \emph{probably} work with \luatex, but explicitly
+checks for \xetex only. However, \pk{fontspec} uses a trick to load it anyway.
+So, you can't load it explicitly, but you don't need to, since \pk{fontspec}
+already took care of it.
+
+\para{encodings}
+As mentioned in the above section, a few things that were problematic with
+UTF-8 on conventional \latex spontaneously works, but not always. For example,
+with the \pf{listings} package on \lualatex, you may use only characters below
+256 (that is, characters from the Latin-1 set), inside your listings (but of
+course the full Unicode range is still available in the rest of your
+document).
+
+\para{metrics}
+This item isn't exactly about working or not working, but rather about not
+working in exactly the same way as \pdftex or \xetex: you may observe minor
+differences in the layout and hyphenation of your text.
+
+They may be due variations between two versions of the same font used by the
+various engines, adjustments made to the hyphenation, ligaturing or kerning
+algorithms (or example, the first word of a paragraph, as well as words
+containing different fonts, can now be hyphenated), or differences in the
+hyphenation patterns used (patterns used by \pdftex are basically frozen, but
+\luatex and \xetex use newer version for some languages) for this language.
+
+If you ever observe a major difference between pdf\latex and \lualatex with
+the same fonts, it is not at all unlikely that a bug in \luatex\footnote{For
+ example, \luatex 0.60 had a bug that prevented any hyphenation after a
+ \code{-{}-{}-} ligature until the end of the paragraph.} or in the font is
+involved. As usual, make sure your distribution is up-to-date before reporting
+such a problem.
+
+\para{babel}
+Mostly working mostly without problems for Latin languages. For other
+languages, your mileage may vary. Even for Latin languages, encoding-related
+problems my happen.
+
+\para{polyglossia}
+A more modern, but less complete, package for multilingual support,
+\pf{polyglossia}, is also available and should be preffered, though it does
+not support all \pf{babel} features yet.
+
+\subsection{Not working (yet)}\label{notworking}
+
+\para{old encodings}[oldenco] Packages playing with input (source files) or
+output (fonts) encodings are very likely to break with \luatex. This includes
+\pf{inputenc}, \pf{fontenc}, \pf{textcomp}, and probably most classical font
+packages such as \pf{mathptmx} or \pf{fourier}. The good news
+is, Unicode is a more powerful way to handle encoding problems that old
+packages were trying to solve, so you most likely don't need these packages
+anyway. However, not everything is already ported to the shiny new world of
+Unicode, so you may have a more limited (or just different) set of choices
+available for some time (this is especially true for fonts).
+
+\para{spaces} Spaces in file names are not really well supported in the \tex
+world in general. This doesn't really get better with \luatex. Also, due to
+tricky reasons, things may be worse if you have spaces in the name of your main
+\tex file \emph{and} don't invoke \luatex in the usual way. If you do
+invoke it in the usual way, everything should work, and I won't tell you what
+the unusual invocation looks like. Otherwise, read the point about
+\pararef{jobname} in section~\ref{formats} for a workaround and technical
+details. Or even better, don't use spaces in the names of your \tex files.
+
+\end{document}
+
+% vim: spell spelllang=en