From e0c6872cf40896c7be36b11dcc744620f10adf1d Mon Sep 17 00:00:00 2001 From: Norbert Preining Date: Mon, 2 Sep 2019 13:46:59 +0900 Subject: Initial commit --- info/luatex/lualatex-doc-de/lualatex-doc-DE.pdf | Bin 0 -> 123776 bytes info/luatex/lualatex-doc-de/lualatex-doc-DE.tex | 806 ++++++++++++++++++++++++ info/luatex/lualatex-doc/Makefile | 47 ++ info/luatex/lualatex-doc/News | 20 + info/luatex/lualatex-doc/README | 23 + info/luatex/lualatex-doc/lltxdoc.cls | 110 ++++ info/luatex/lualatex-doc/lualatex-doc.pdf | Bin 0 -> 155858 bytes info/luatex/lualatex-doc/lualatex-doc.tex | 743 ++++++++++++++++++++++ 8 files changed, 1749 insertions(+) create mode 100644 info/luatex/lualatex-doc-de/lualatex-doc-DE.pdf create mode 100644 info/luatex/lualatex-doc-de/lualatex-doc-DE.tex create mode 100644 info/luatex/lualatex-doc/Makefile create mode 100644 info/luatex/lualatex-doc/News create mode 100644 info/luatex/lualatex-doc/README create mode 100644 info/luatex/lualatex-doc/lltxdoc.cls create mode 100644 info/luatex/lualatex-doc/lualatex-doc.pdf create mode 100644 info/luatex/lualatex-doc/lualatex-doc.tex (limited to 'info/luatex') 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 Binary files /dev/null and b/info/luatex/lualatex-doc-de/lualatex-doc-DE.pdf 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 , 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 , 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 Binary files /dev/null and b/info/luatex/lualatex-doc/lualatex-doc.pdf 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 , 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 -- cgit v1.2.3