Un guide pour LuaLaTeX

Pour répondre à cette question, nous devons mentionner quelques détails sur le monde TeX que vous pouvez généralement ignorer : la différence entre un moteur et un format. Un moteur est un programme de l'ordinateur réel, tandis que le format est un ensemble de macros exécutées par ce moteur. Ce format est généralement préchargé lorsque le moteur est invoqué avec un nom particulier.

En fait, un format est plus ou moins comme une classe de document ou une extension, sauf qu'il est associé à un nom de commande particulière. Imaginez qu'il y ait une commande latex-article qui ferait la même chose que LaTeX, sauf que vous n'auriez pas besoin de dire \documentclass{article} au début de votre fichier. De même, dans les distributions actuelles, la commande pdflatex est la même que la commande pdftex, sauf que vous n'avez pas besoin de mettre les instructions pour charger LaTeX au début de votre fichier source. C'est pratique et aussi beaucoup plus efficace.

Les formats sont bien parce qu'ils mettent en œuvre des commandes puissantes en utilisant les outils de base fournis par le moteur. Cependant, la puissance des formats est parfois limitée par les outils mis à disposition par le moteur. C'est ainsi que des personnes ont commencé à développer des moteurs plus puissants, permettant à d'autres personnes de mettre en œuvre des formats encore plus puissants (ou extensions). Les plus célèbres moteurs maintenant (à l'exception du TeX origine) sont pdfTeX, XeTeX et LuaTeX.

Pour compliquer un peu plus la situation, le moteur de TeX original produit uniquement des fichiers DVI, alors que ses successeurs peuvent (aussi) produire des fichiers PDF. Chaque commande, dans votre système, correspond à un moteur particulier avec un format et un mode de sortie particuliers. Le tableau suivant résume cela: les lignes sont indexées par le format, les colonnes par le moteur. Dans chaque cellule, la première ligne est la commande de ce moteur avec le format en mode DVI et la deuxième ligne pour le mode PDF.

Nous pouvons maintenant répondre à la question du titre : LuaLaTeX est le moteur de LuaTeX avec le format LaTeX. Eh bien, cette réponse n'est pas très satisfaisante si vous ne savez pas ce que sont LuaTeX et LaTeX.

Comme vous le savez probablement, LaTeX est le cadre général dans lequel les documents commencent par \documentclass, les extensions sont chargées avec \usepackage, les polices sont sélectionnées de façon intelligente (de sorte que vous pouvez passer en gras tout en préservant l'italique), les pages sont construites avec des algorithmes compliqués y compris le support pour les en-têtes, pieds de page, les notes, les notes en marge, les notes flottantes, etc. Cela ne change pas avec LuaLaTeX, mais des extensions nouvelles et plus puissantes sont disponibles pour que le système fonctionne d'une meilleure façon.

Alors, qu'est-ce que LuaTeX ? Version courte : le meilleur moteur TeX du moment ! Version longue : Il est le successeur désigné de pdfTeX et comprend toutes ses fonctions de base : la génération directe de fichiers PDF avec le support de fonctionnalités PDF avancées et des améliorations microtypographiques par rapport aux algorithmes typographiques de TeX. Les principales nouvelles fonctionnalités de LuaTeX sont indiquées ci-dessous.

1. La prise en charge native de l'Unicode, la norme moderne pour la classification et l'encodage des caractères supportant tous ceux du monde, de l'anglais au chinois traditionnel en passant par l'arabe, y compris beaucoup de symboles mathématiques (et autres symboles spécialisés).
2. L'inclusion de Lua comme langage de script intégré (voir section 1.3 pour plus de détails).

3. Un grand nombre de bibliothèques Lua, avec entre autres :

   1. fontloader, pour le support du format de polices modernes telles que TrueType et OpenType ;
   2. font, permettant la manipulation avancée des polices de l'intérieur du document ;
   3. mplib, une version intégrée du programme graphique MetaPost ;
   4. callback, pour fournir des fonctions de rappel (hook ou callback) dans le moteur TeX qui étaient auparavant inaccessibles pour le développeur ;
   5. des bibliothèques d'utilitaires pour la manipulation d'images, de fichiers PDF, etc.

Certaines de ces fonctionnalités, telles que le support Unicode, ont un impact direct sur tous les documents, tandis que d'autres se contentent de fournir des outils que les auteurs d'extensions vont utiliser pour vous fournir des commandes plus puissantes et d'autres améliorations.

Comme expliqué dans le paragraphe précédent, LuaLaTeX est la plupart du temps identique à LaTeX, avec toutefois quelques différences, des extensions et des outils disponibles plus puissants. Nous présentons ici le strict minimum de ce que vous devez savoir pour produire un document avec LuaLaTeX, tandis que le reste du document fournit plus de détails sur les extensions disponibles.

Il y a seulement quatre différences.

1. Ne chargez pas inputenc, il suffit juste d'encoder votre source en UTF-8.
2. Ne chargez ni fontenc, ni textcomp, mais chargez fontspec.
3. Babel fonctionne avec LuaLaTeX, mais vous pouvez aussi charger polyglossia à sa place.
4. N'utilisez pas les extensions qui changent les polices, mais utilisez les commandes fontspec à leur place.

Donc, vous avez seulement besoin de vous familiariser avec fontspec, ce qui est facile : sélectionnez la police principale (serif) avec \setmainfont, la fonte de caractères sans empattement avec \setsansfont et la police à espacement fixe (machine à écrire) avec \setmonofont. L'argument de ces commandes est le nom de la police, par exemple Latin Modern Roman plutôt que ec-lmr10. Vous voudrez aussi probablement utiliser la commande \{defaultfontfeatures ligatures = TeX} avant ces commandes pour conserver les substitutions habituelles TeX (comme --- pour un tiret long).

La bonne nouvelle est que vous pouvez accéder directement à n'importe quelle police de votre système d'exploitation (en plus de celles de la distribution TeX), y compris des polices TrueType et OpenType, et avoir accès à leurs fonctionnalités les plus avancées. Cela signifie aussi qu'il est maintenant possible d'utiliser, avec LuaLaTeX, n'importe quelle police moderne que vous pourriez télécharger ou acheter chez un éditeur, et ainsi bénéficier de leur plein potentiel.

Maintenant, pour les mauvaises nouvelles : il n'est pas toujours facile d'obtenir la liste de toutes les polices disponibles. Sous Windows, avec TeX Live, l'outil en ligne de commande fc-list les énumère toutes, mais n'est pas très convivial. Sous Mac OS X, l'application Fontbook répertorie les polices de votre système, mais pas celles de votre distribution TeX. C'est pareil avec fc-list sur Linux. Encore pire, il n'est pas facile d'accéder à vos anciennes polices de cette façon. Heureusement, de plus en plus de fontes modernes sont disponibles tous les jours (enfin tous les mois ou toutes les années si on ne compte que les bonnes polices).

En passant, mentionnons que le contenu de cette section est aussi valable pour XeLaTeX, c'est-à-dire LaTeX sur XeTeX. En effet, XeTeX partage deux caractéristiques essentielles avec LuaTeX : Unicode et le support des formats de polices modernes (bien qu'il ne possède pas les autres caractéristiques de LuaTeX, il est maintenant plus stable). Bien que la mise en œuvre concernant les polices soit très différente, fontspec parvient à offrir une interface unifiée pour tous les deux, XeLaTeX et LuaLaTeX.

Ainsi, pour bénéficier des nouvelles fonctionnalités de LuaTeX, vous devez supprimer quelques parties, à savoir les polices qui ne sont pas disponibles dans un format moderne (et aussi la liberté d'encoder votre texte comme vous voulez, mais UTF-8 est tellement supérieur que cela ne compte guère). L'extension luainputenc fournit différents compromis qui vous permettent de retrouver ces parties(2) probablement au prix de la perte du soutien Unicode.

C'est tout ce que vous avez besoin de savoir pour commencer à produire des documents avec LuaLaTeX. Je vous recommande de jeter un coup d'œil au manuel de fontspec et d'essayer de compiler un petit document en utilisant des polices amusantes. Vous pouvez ensuite survoler le reste de ce document comme vous le souhaitez. La section 5 répertorie toutes les autres différences entre LaTeX et LuaLaTeX dont je suis au courant.

Lua est un petit langage sympathique, évidemment moins surprenant et beaucoup plus facile à apprendre que TeX comme langage de programmation. La référence essentielle est le livre Programming in Lua qui est très facile à lire, dont la première édition est gratuitement disponible en ligne. Pour un démarrage rapide, je vous recommande de lire les chapitres 1 à 5 et de survoler la partie 3. Notez que toutes les bibliothèques mentionnées dans le chapitre 3 sont incluses dans LuaTeX, mais la bibliothèque OS est limitée pour des raisons de sécurité. En fonction de votre culture de la programmation, vous pouvez être directement intéressé par la fin de la partie 1 et la partie 2 qui présentent des fonctionnalités plus avancées de la langue. Par contre, la partie 4 est inutile dans un contexte de LuaTeX, à moins bien sûr que vous vouliez pirater LuaTeX lui-même. Enfin, le manuel de référence Lua est disponible en ligne et est livré avec un index pratique.

Maintenant, passons à Lua dans LuaTeX. Le principal moyen pour exécuter du code Lua dans TeX est d'utiliser la commande \directlua qui prend comme argument du code arbitraire Lua. Inversement, vous pouvez aussi passer des informations de Lua vers TeX avec tex.sprint(3). Par exemple :

the standard approximation $\pi = \directlua{tex.sprint(math.pi)}$

affiche « the standard approximation π = 3.1415926535898 » dans votre document. Vous voyez comment il est simple de mixer Lua et TeX ?

En fait, il y a quelques pièges. Regardons tout d'abord le passage de Lua vers TeX, c'est le plus simple (car c'est plus Lua que TeX). Si vous regardez le manuel de LuaTeX, vous verrez qu'il existe une autre fonction avec un nom plus simple, tex.print, pour transmettre des informations de cette façon. Il fonctionne en insérant littéralement une ligne de texte dans votre source TeX dont le contenu est l'argument passé. Au cas où vous ne le sauriez pas, TeX fait de drôles de choses(4) avec les lignes de source : il ignore les espaces au début et à la fin de la ligne et il ajoute un caractère de fin de ligne. La plupart du temps, vous ne voulez pas que cela arrive, nous vous recommandons alors d'utiliser tex.sprint qui insère littéralement son argument dans la ligne actuelle, il en est beaucoup plus prévisible.

Si vous êtes assez TeXnicien pour comprendre les catcodes, vous serez heureux de savoir que tex.print et ses variantes vous donnent presque les pleins pouvoirs sur les catcodes, puisque vous pouvez spécifier un tableau de catcodes en tant que premier argument. Vous aurez probablement envie de tout savoir sur ces tables de catcodes (paragraphe 2.7.6 dans le manuel de LuaTEX) avant que vous soyez pleinement heureux. Si vous ne connaissez pas les catcodes, sautez ce paragraphe(5).

Regardons \directlua maintenant. Pour avoir une idée sur la façon dont cela fonctionne, imaginez que c'est une commande \write, mais qui écrit dans un fichier virtuel immédiatement mis à disposition et envoyé à l'interpréteur Lua. Côté Lua, la conséquence est que chaque argument d'une commande \directlua a son propre champ d'application : les variables locales de l'un ne seront pas visibles par l'autre (c'est plutôt sain, mais toujours bon à savoir).

Maintenant, le gros problème c'est qu'avant d'être envoyé à l'interpréteur Lua, l'argument est d'abord lu et analysé par TeX, puis complètement transformé en une chaîne simple. Cette lecture par TeX a plusieurs conséquences. L'une d'elles est que les fins de lignes sont transformées en espaces, donc Lua ne voit qu'une seule (longue) ligne d'entrée. Lua est un langage de forme libre et cela n'a pas d'importance en général, mais il si vous utilisez commentaires suivants :

\directlua{a_function()
 -- a comment
 another_function()}

Cela ne fera pas ce que vous attendez : another_function() sera considérée comme faisant partie du commentaire (c'est une seule ligne, rappelez-vous).

Une autre conséquence de la lecture par TeX est que les espaces successifs sont fusionnés en un seul espace et les commentaires TeX sont ignorés. Voici une version correcte de l'exemple précédent :

\directlua{a_function()
 % a comment
 another_function()}

Il faut aussi remarquer que, puisque l'argument est fondamentalement à l'intérieur d'un \write, c'est dans un contexte d'expansion uniquement. Si vous ne savez pas ce que cela signifie, laissez-moi vous dire que les questions d'expansion sont celles qui rendent la programmation TeX si difficile, pour éviter de s'étendre sur ce sujet.

Je suis désolé si les trois derniers paragraphes sont TeXniques, mais je pensais qu'il était nécessaire que vous le sachiez. Pour vous récompenser de rester avec moi, voici une astuce de débogage. Placez le code suivant au début de votre document :

\newwrite\luadebug
\immediate\openout\luadebug luadebug.lua
\AtEndDocument{\immediate\closeout\luadebug}
\newcommand\directluadebug{\immediate\write\luadebug}

Puis, quand vous aurez passé suffisamment de temps à essayer de comprendre pourquoi un appel à \directlua ne fait pas ce que vous attendez, remplacez cette commande par \directluadebug, compilez comme d'habitude et regardez le fichier luadebug.lua qui contient ce qui est réellement interprété par Lua.

L'extension luacode fournit des commandes et des environnements qui aident à des degrés divers, avec certains de ces problèmes. Cependant, pour des morceaux de code triviaux de Lua, il est plus courant d'utiliser un fichier externe contenant uniquement du code Lua définissant ces fonctions, puis le charger et utiliser ses fonctions. Par exemple :

\directlua{dofile("my-lua-functions.lua")}
\newcommand*{\greatmacro}[2]{%
 \directlua{my_great_function("\luatexluaescapestring{#1}", #2)}}

L'exemple suppose que my_great_function est défini dans my-lua-functions.lua et prend une chaîne de caractères et un nombre comme arguments. Notez que nous utilisons les primitives \luatexluaescapestring avec l'argument de la chaîne de caractères pour échapper à tout caractère backslask ou guillemet qu'il pourrait contenir et qui pourrait perturber l'analyseur Lua(6).

C'est tout ce qui concerne l'insertion de code Lua dans TeX. Si vous vous demandez pourquoi \luatexluaescapestring a un nom long et stupide, vous pouvez lire la section suivante.

Juste au cas où cela ne semble pas évident, le manuel de LuaTeX, luatexref-t.pdf, est une grande source d'informations sur LuaTeX et vous aurez probablement besoin de le consulter à un moment donné (même s'il est un peu aride et technique). Il est important de savoir que les noms des nouvelles primitives de LuaTeX que vous trouverez dans le manuel ne sont pas les noms réels que vous pourrez utiliser dans LuaLaTeX. Pour éviter des conflits avec des noms de macros existantes, toutes les nouvelles primitives ont été préfixées avec \luaTeX à moins qu'elles ne commencent déjà comme cela, donc \luaescapestring devient \luatexluaescapetring alors que \luatexversion reste \luatexversion. La raison est détaillée dans la section 4.

Oh, en passant, je vous ai dit que LuaTeX est en version bêta et que la version 1.0 est attendue pour le printemps 2014 ? Vous pouvez en apprendre plus sur la page de la feuille de route du site LuaTEX. Des versions bêta stables sont régulièrement publiées et sont incluses dans TeX Live depuis 2008 et depuis MikTeX 2.9.

Sans surprise, le soutien à LuaTeX pour LaTeX est flambant neuf, ce qui signifie qu'il peut y avoir pleins de bogues et que les choses peuvent changer à tout moment. Vous pouvez garder votre distribution TeX à jour(7) et également éviter d'utiliser LuaLaTeX dans des documents critiques, au moins pour un certain temps.

En règle générale, ce guide documente les choses telles qu'elles sont au moment où il est écrit ou mis à jour, sans garder trace des changements. J'espère que vous allez mettre à jour votre distribution dans son ensemble de sorte que vous obteniez toujours les versions de ce guide, les extensions, les formats et le moteur correspondant.

2-1-1. fontspec▲

2-1-2. polyglossia▲

2-2-1. Conventions de nommage▲

2-2-2. Moteur et mode de détection▲

2-2-3. Ressources de base▲

2-2-4. Fontes internes▲

3-1-1. luatextra▲

3-1-2. luacode▲

3-1-3. luainputenc▲

3-1-4. luamplib▲

3-1-5. luacolor▲

3-2-1. pdftexcmds▲

3-2-2. magicnum▲

3-2-3. lua-alt-getopt▲

Comme indiqué dans la section 1.4, les noms des primitives spécifiques LuaTeX ne sont pas les mêmes dans le format de LuaLaTeX comme dans le manuel de LuaTeX. Dans le format de LuaTeX (c'est-à-dire LuaTEX avec le format ordinaire), les primitives sont disponibles avec leur nom naturel, mais aussi avec le nom préfixé afin de faciliter le développement de forfaits génériques.

Ci-dessous les raisons, copier-coller à partir du fichier lualatexiniconfig.tex qui implémente ceci pour le format LuaLaTeX.

1. Toutes les macros actuelles s'exécutent correctement sur pdf(e)TeX de sorte que ces primitives sont laissées intactes.
2. Les autres primitives non-TeX82 de LuaTeX peuvent causer des conflits de noms avec des macros existantes dans des extensions de macros, surtout quand elles utilisent des noms très « naturels » tels que \outputbox, \mathstyle, etc. Une telle probabilité pour les conflits de noms n'est pas souhaitable, car la plupart des documents LaTeX existants fonctionnent sans changement sous LuaTeX, ce qui est très bien.
3. L'équipe LuaTeX ne veut pas appliquer une politique de préfixation systématique, mais fournit aimablement un outil permettant d'appliquer des préfixes, nous avons donc choisi de l'utiliser. Auparavant, nous avions même désactivé les primitives supplémentaires, mais maintenant, nous pensons qu'il est mieux d'autoriser la préfixation systématique afin d'éviter que chaque extension macro (ou utilisateur) l'autorise avec des préfixes divers et incohérents (y compris le préfixe vide).
4. Le préfixe LuaTeX a été choisi, car il est déjà utilisé pour certaines primitives telles que \luatexversion. De cette façon, ces primitives n'ont pas un double préfixe (pour les détails, voir tex.enableprimitives dans le manuel de LuaTeX).
5. La primitive \directlua est fournie à la fois par son nom naturel (permettant une détection facile de LuaTeX) et par une version \luatexdirectlua préfixée (par souci de cohérence avec \luatexlatelua).

6. Remarques diverses :

   1. l'inconvénient évident d'une telle politique préfixe est que les noms utilisés par LaTeX ou les macros génériques ne correspondront pas aux noms utilisés dans le manuel. Nous espérons que cela est compensé par le gain de compatibilité ascendante ;
   2. toutes les primitives relatives à Unicode commencent déjà avec \U et correspondront, peut-être un jour, aux noms des primitives XeTeX. Alors peut-être que l'utilisation de tel préfixe n'était pas utile ou désirable pour elles. Malgré tout, nous avons essayé de créer des règles de préfixes aussi simples que possible, de sorte que le point précédent ne devienne pire ;
   3. peut-être qu'un jour, nous éprouverons le besoin de définir les primitives sans préfixe. Si cela arrive, il sera facile d'ajouter ces primitives sans préfixe dans les formats qui resteront compatibles avec les primitives avec préfixes. Cela n'aurait pas fonctionné dans l'autre sens, c'est-à-dire, réaliser tardivement que nous n'aurions pas dû définir les primitives sans préfixes, les rajouter reviendrait à rendre inutilisables toutes les extensions à macros déjà écrites spécifiquement pour luaTeX.

Le noyau LaTeX et un grand nombre d'extensions utilisent des constructions comme \input\jobname.aux à des fins diverses. Lorsque \jobname contient des espaces, cela produit des problèmes, puisque l'argument de \input se termine avec le premier espace. Pour contourner ce problème, pdfTeX protège automatiquement \jobname en cas de besoin avec des guillemets, mais LuaTeX ne le fait pas pour une autre raison. Une solution presque parfaite est incluse avec LaTeX-based (par opposition à Plain-based) dans les formats LuaTeX.

Cela ne fonctionne pas cependant si LuaTeX est invoqué comme lualatex '\input name', par opposition à la méthode plus habituelle lualatex name. Pour contourner cette limitation de la solution de contournement inclus dans le format, il faut spécifier explicitement un nom, comme dans lualatex jobname = nom '\input'. Ou mieux encore, il suffit de ne pas utiliser d'espaces dans les noms de vos fichiers TeX.

Pour plus de détails, voir cette vieille discussion et celle-ci plus récente sur les listes de diffusion de LuaTeX et lualatexquotejobname.tex pour la mise en œuvre de la solution de contournement.

LuaTeX offre un chargement dynamique des modèles de césure. Son support au sein de babel et Polyglossia apparaît seulement sur TeX Live 2013, mais doit bien fonctionner maintenant.

La documentation et les détails de mise en œuvre sont inclus dans luatex-hyphen.pdf. Les sources font partie du projet de texhyphen.

Le moteur lui-même ne définit pas \catcodes, \lccodes, etc. pour les caractères non ASCII. Des corrections dans \lccodes en particulier sont nécessaires pour que la césure fonctionne. Les formats pour LuaTeX comprennent maintenant luatex-unicode-letters.tex, une version modifiée de unicode-letters.tex de la distribution de XeTeX qui s'occupe de positionner les valeurs conformément à la norme Unicode.

Cela a été ajouté après que TeX Live 2010 soit sorti. Il est donc fortement recommandé de mettre à jour votre installation si vous voulez profiter de la césure correcte pour le texte non-ASCII.

5-1-1. Unicode▲

5-2-1. microtype▲

5-2-2. xunicode▲

5-2-3. Les encodages▲

5-2-4. metrics▲

5-2-5. babel▲

5-2-6. polyglossia▲

5-3-1. Les anciens encodages▲

5-3-2. Les espaces▲