lualatex-doc-fr.tex

% lualatex-doc-fr: un guide touristique de LuaLaTeX
%
% Écrit par Manuel Pégourié-Gonnard <mpg@elzevir.fr>, 2010-2013.
% Adaptation française: Jérémy Just <jeremy@jejust.fr>, 2013-2014.
%
% 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}
  \selectlanguage{french}

\title{Un guide touristique de \lualatex\thanks{Traduit en français par Jérémy Just \email{jeremy@jejust.fr}.}}
\author{Manuel Pégourié-Gonnard \email{mpg@elzevir.fr}}
%\date{\today}
\date{5 mai 2013}

\begin{document}

\maketitle

\begin{abstract}
  Ce document se veut un guide touristique du nouveau monde offert par
  \lualatex.\footnote{Bien que centré sur LuaLaTeX, il inclut également des
    informations utiles sur \luatex quand il est utilisé avec le format Plain.}
  Le public visé va des nouveaux venus (ayant une connaissance pratique
  du \latex conventionnel) aux développeurs de packages. Ce guide se veut
  exhaustif dans le sens suivant: il contient des pointeurs vers toutes
  les sources pertinentes, rassemble des informations qui sont autrement
  dispersées et ajoute des éléments d'introduction.

  Vos commentaires et suggestions d'améliorations sont les bienvenus.
  Ce document est un travail en cours; merci pour votre bienveillance et
  votre patience.
\end{abstract}

\vspace{\stretch{1}}
\setcounter{tocdepth}{2}
\listoftoc*{toc}
\vspace*{\stretch{2}}
\clearpage

\section{Introduction}\label{intro}

\subsection{Qu'est-ce que \lualatex?}\label{what}

Pour répondre à cette question, nous devons préciser un détail sur le monde \tex
que vous pouvez habituellement négliger: la différence entre un \emph{moteur}
et un \emph{format}. Un moteur est un programme informatique réel, tandis
qu'un format est un ensemble de macros exécutées par un moteur, et généralement
préchargé lorsque le moteur est invoqué sous un nom spécifique.

En fait, un format est plus ou moins comme une classe de document ou un paquetage,
sauf qu'il est associé à un nom de commande particulier. Imaginez qu'il existe une
commande \cmd{latex-article} qui ferait la même chose que \cmd{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 \cmd{pdflatex} est la même que
la commande \cmd{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 légèrement
plus efficace aussi.

Les formats sont une belle invention car ils permettent d'implémenter des commandes
puissantes, en utilisant les outils de base fournis par le moteur. Cependant, la
puissance du format reste limitée par l'ensemble des outils du moteur, c'est pourquoi
les gens ont commencé à développer des moteurs plus puissants afin que d'autres
personnes puissent mettre en \oe uvre des formats (ou des packages) encore plus
puissants. Les moteurs les plus connus actuellement (à l'exception du \tex original)
sont \pdftex, \xetex et \luatex.

Pour compliquer encore le tableau, le moteur \tex original ne produisait que des
fichiers~DVI, alors que ses successeurs peuvent (aussi) produire des fichiers~PDF.
Chaque commande de votre système correspond à un moteur particulier avec un format
particulier et un mode de sortie particulier. Le tableau suivant résume cela:
les lignes indiquent le format, les colonnes le moteur, et dans chaque case,
la première ligne est la commande pour ce moteur avec ce format en mode~DVI,
et la seconde en mode~PDF.

\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 (aucun)}} {#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}

Nous pouvons maintenant répondre à la question posée plus haut: \lualatex est
le moteur \luatex avec le format \latex. Cette réponse n'est pas très satisfaisante
si vous ne savez pas ce qu'est \luatex (et peut-être \latex).

\medskip

Commençons par ce que vous savez sans doute déjà: dans le monde \tex au sens large,
\latex est le cadre général dans lequel les documents commencent par
©\documentclass©, les packages sont chargés par ©\usepackage©, les polices sont
sélectionnées de manière intelligente (de sorte que vous puissiez passer en gras
tout en préservant l'italique), les pages sont construites à l'aide d'algorithmes
compliqués comprenant la prise en charge des en-têtes, des pieds de page, des
notes de bas de page, des notes de marge, des flottants, etc. Tout cela ne change
pas avec \lualatex, mais de nouveaux packages plus puissants sont disponibles
pour améliorer le fonctionnement de certaines parties du système.


Alors, qu'est-ce que \luatex? Version courte: le moteur \tex le plus
populaire du moment!
Version longue: c'est le successeur désigné de pdfTeX et il inclut
toutes ses fonctionnalités principales: génération directe de fichiers~PDF
avec support des fonctionnalités PDF avancées et améliorations
micro-typographiques des algorithmes typographiques \tex.
Les principales nouveautés de \luatex sont:
\begin{enumerate}
  \item Support natif d'Unicode, la norme moderne de classement et
    d'encodage des caractères, supportant tous les caractères du monde,
    de l'anglais au chinois traditionnel en passant par l'arabe,
    y compris de nombreux symboles mathématiques (ou symboles
    spécifiques d'autres domaines).
  \item Intégration de Lua comme langage de script embarqué
    (voir section~\ref{luaintex} pour plus de détails).
  \item Une multitude de merveilleuses bibliothèques Lua, notamment:
    \begin{itemize}
      \item ©fontloader©, prenant en charge les formats de polices modernes
        tels que TrueType et OpenType;
      \item ©font©, permettant une manipulation avancée des polices à partir
        du document;
      \item ©mplib©, une version embarquée du programme graphique MetaPost;
      \item ©callback©, qui permet d'accéder à des parties du moteur \tex
        qui étaient auparavant inaccessibles au programmeur;
      \item des bibliothèques utilitaires pour la manipulation d'images,
        de fichiers~PDF, etc.
    \end{itemize}
\end{enumerate}
Certaines de ces fonctionnalités, comme la prise en charge d'Unicode, ont un
impact direct sur tous les documents, tandis que d'autres fournissent simplement
des outils que les auteurs de packages utiliseront pour vous fournir des commandes
plus puissantes et autres améliorations.


\subsection{Passage de \latex à \lualatex}\label{switch}

Comme l'explique la section précédente, \lualatex{} est en grande partie comme \latex,
avec quelques différences, et des packages et outils plus puissants disponibles.
Nous présentons ici le minimum absolu que vous devez savoir pour produire
un document avec \lualatex, tandis que le reste du document fournit
plus de détails sur les packages disponibles.


Il n'y a que trois différences:
\begin{enumerate}
  \item Ne chargez pas \pf{inputenc}, encodez simplement votre source en UTF-8.
  \item Ne chargez pas \pf{fontenc} ni \pf{textcomp}, mais chargez \pf{fontspec}
     à la place.
  \item \pf{babel} fonctionne avec \lualatex mais vous pouvez charger \pf{polyglossia}
     à la place.
  \item N'utilisez pas de package qui change les polices, mais utilisez les commandes
    de \pf{fontspec} à la place.
\end{enumerate}
Ainsi, vous n'avez qu'à vous familiariser avec \pf{fontspec}, ce qui est facile:
sélectionnez la police principale (avec empattement) avec ©\setmainfont©,
la police sans empattement avec ©\setsansfont© et la police à chasse fixe
(style machine à écrire) avec ©\setmonofont©. L'argument de ces commandes est
le petit nom de la police, lisible par un humain, par exemple ©Latin Modern Roman©
(et non ©ec-lmr10©). Pour que les substitutions \tex habituelles fonctionnent
(comme ©---© pour un tiret cadratin), vous pouvez utiliser
©\defaultfontfeatures{Ligatures=TeX}© avant ces commandes.

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 votre distribution \tex),
y compris les polices TrueType et OpenType, et avoir accès à leurs fonctionnalités
les plus avancées. Cela signifie qu'il est désormais facile d'installer n'importe
quelle police moderne que vous pouvez télécharger ou acheter auprès d'un éditeur,
de les utiliser avec \lualatex et de bénéficier de tout leur potentiel.

Passons maintenant aux mauvaises nouvelles: il n'est pas toujours facile d'obtenir
une liste de toutes les polices disponibles. Sous Windows avec \texlive, l'outil
de ligne de commande \cmd{fc-list} les liste toutes, mais n'est pas très convivial.
Sous Mac OS~X, l'application \emph{Fontbook} liste les polices de votre système,
mais pas celles de votre distribution \tex. Même chose avec \cmd{fc-list} sous Linux.
Autre mauvaise nouvelle: il n'est pas facile d'accéder à vos anciennes polices
de cette manière. Heureusement, progressivement (et rapidement), de plus en plus
de polices sont disponibles dans des formats modernes.

Soit dit en passant, le contenu de cette section jusqu'à présent vaut aussi pour
\xelatex, c'est-à-dire \latex sur \xetex. En effet, \xetex partage deux des
caractéristiques essentielles de \luatex: l'Unicode natif et le support des formats
de polices modernes (en revance, il n'a pas les autres caractéristiques de \luatex;
mais actuellement, il est considéré comme plus stable). Bien que leurs implémentations
concernant les polices de caractères soient très différentes, \pf{fontspec} parvient
à offrir une interface de police pratiquement unifiée pour \xelatex et \lualatex.

\medskip

Ainsi, pour bénéficier des nouvelles fonctionnalités de \luatex, vous devez
renoncer à un peu de l'ancien monde, à savoir les polices qui ne sont pas
disponibles dans un format moderne (ainsi qu'à la liberté d'encoder votre source
comme bon vous semble, mais UTF-8 est tellement supérieur aux autres encodages
que vous ne perdez quasiment rien au change). Le package \pk{luainputenc}
fournit des solutions de transition qui vous permettent de retrouver certains
anciens comportemenbts\footnote{Bien que son nom suggère qu'il ne s'occupe
  que des encodages d'entrée, l'implémentation de l'encodage des polices
  en \latex implique que ce package est nécessaire (et fonctionne)
  également pour utiliser les anciennes polices.}, peut-être au prix
de la perte du support réel d'Unicode.

En gros, c'est tout ce que vous devez savoir pour commencer à produire des
documents avec \lualatex. Je vous recommande de jeter un coup d'oeil au manuel
de \pf{fontspec} et d'essayer de compiler vous-même un petit document
en utilisant des polices amusantes.
Vous pourrez ensuite parcourir le reste de ce document comme bon vous semble.
La section~\ref{workornot} liste toutes les autres différences que je connais
entre \latex conventionnel et \lualatex.


\subsection{Une introduction à Lua-dans-\tex}\label{luaintex}

Lua est un petit langage, plutôt bien pensé, bien moins surprenant que \tex
en tant que langage de programmation, et beaucoup plus facile à apprendre que lui.
La référence essentielle est l'excellent livre \emph{Programming in Lua},
dont la première édition est \href{http://www.lua.org/pil/}{disponible gratuitement en ligne}
(en anglais). Pour commencer rapidement, je vous recommande de lire les
chapitres~1 à~5 et de jeter un coup d'\oe il à la partie~3. Notez que toutes
les bibliothèques mentionnées dans le chapitre~3 sont incluses dans \luatex,
mais que la bibliothèque ©os© est restreinte pour des raisons de sécurité.

En fonction de vos connaissances en matière de programmation, vous serez
peut-être directement intéressé par le reste de la partie~1 et la partie~2,
qui présentent des fonctionnalités plus avancées du langage, mais la partie~4
est inutile dans un contexte de \luatex, à moins bien sûr que vous ne vouliez
modifier \luatex lui-même. Enfin, le manuel de référence de Lua est
\href{http://www.lua.org/manual/5.2/}{disponible en ligne} et est accompagné d'un index très pratique.

\medskip

Passons maintenant à l'utilisation de Lua \emph{dans} \luatex. La principale
façon d'exécuter du code Lua à partir de \tex est la commande ©\directlua©,
qui prend du code Lua arbitraire comme argument. Inversement, vous pouvez
passer des informations de Lua à \tex avec la commande ©tex.sprint©\footnote{Dans
  ce nom, \og{}sprint\fg{} signifie \og{}\emph{string print}\fg{}
  (\og{}imprimer une chaîne\fg{}), et non \og{}aller très vite\fg{}!}.
Par exemple,
\begin{Verbatim}
  approximation standard de $\pi = \directlua{tex.sprint(math.pi)}$
\end{Verbatim}
affiche \og{}approximation standard de $\pi = \directlua{tex.sprint(math.pi)}$\fg
dans votre document. Vous voyez comme il est facile d'entremêler du \tex et du Lua?

En fait, il y a quelques pièges. Regardons d'abord le passage de Lua vers \tex,
c'est le plus simple (puisqu'il s'agit davantage de Lua que de \tex).
Si vous regardez le manuel de \luatex, vous verrez qu'il existe une autre fonction
avec un nom plus simple, ©tex.print©, pour faire transiter des informations
dans ce sens. Elle fonctionne en insérant virtuellement une ligne complète
dans votre source \tex, dont le contenu est son argument. Au cas où vous ne
le sauriez pas, \tex fait beaucoup de choses néfastes\footnote{D'accord, ce
  sont généralement des actions utiles et bien intentionnées, mais dans ce
  cas présent, elles sont inattendues, donc je les appelle ``néfastes''.} avec
les lignes complètes de la source: ignorer les espaces en début et en fin
de ligne et ajouter un caractère de fin de ligne. La plupart du temps, vous
ne voulez pas que cela se produise, donc je recommande d'utiliser ©tex.sprint©
qui insère simplement son argument dans la ligne courante, et donne un résultat
plus prévisible.

Si vous êtes suffisamment bon \tex{}nicien pour connaître les catcodes,
vous serez heureux d'apprendre que ©tex.print© et ses variantes vous donnent
un contrôle presque total sur les catcodes utilisés pour tokeniser l'argument,
puisque vous pouvez spécifier une table de catcodes comme premier argument.
Les tables de catcodes sont présentées à la section~2.7.6 dans le manuel de
\luatex (dans la version actuelle), vous avez sans doute intérêt à y jeter
un \oe il. Si vous ne connaissez pas les catcodes, passez ce
paragraphe.\footnote{Arf, trop tard, vous l'avez déjà lu!\dots}

\medskip

Regardons maintenant ©\directlua©. Pour vous faire une idée de son fonctionnement,
imaginez qu'il s'agit d'une commande ©\write©, mais qu'elle écrit uniquement dans
un fichier virtuel et s'arrange pour que ce fichier soit immédiatement transmis
à l'interpréteur Lua. Du côté de Lua, la conséquence est que chaque argument
d'une commande ©\directlua© a sa propre portée: les variables définies localement
dans un argument ne seront pas visibles par le suivant
(ce qui est plutôt sain, mais toujours bon à savoir).

Maintenant, le problème majeur est qu'avant d'être transmis à l'interpréteur Lua,
l'argument est d'abord lu et tokénisé par \tex, puis entièrement développé et
transformé en une chaîne de caractères ordinaire. La lecture par \tex a plusieurs
conséquences. L'une d'entre elles est que les fins de lignes sont transformées
en espaces, de sorte que l'interprète Lua ne voit qu'une (longue) ligne d'entrée.
Comme Lua est un langage à la forme libre, cela n'a généralement pas d'importance,
sauf si vous utilisez des commentaires:

\begin{Verbatim}
  \directlua{une_fonction()
    -- un commentaire
    une_autre_fonction()}
\end{Verbatim}
ne fera pas ce que vous attendez probablement: ©une_autre_fonction()© sera
considéré comme faisant partie du commentaire (tout est mis sur une seule
ligne, ne l'oubliez pas).

Une autre conséquence de la lecture par \tex est que les espaces successives
sont fusionnées en une unique espace, et que les commentaires \tex sont éliminés.
Voici donc une version correcte de l'exemple précédent, de façon surprenante:

\begin{Verbatim}
  \directlua{une_fonction()
    % un commentaire
    une_autre_fonction()}
\end{Verbatim}

Il convient également de noter que, puisque l'argument se trouve, de fait,
à l'intérieur d'un ©\write©, il se trouve dans un contexte purement d'expansion.
Si vous ne savez pas ce que cela signifie, laissez-moi seulement vous dire que
les problèmes d'expansion sont ce qui rend la programmation \tex si difficile
et qu'il vaut mieux éviter de développer davantage cette question aujourd'hui.

\medskip

Je vous prie de m'excuser si les trois derniers paragraphes ont été un peu \tex{}niques
mais j'ai préféré vous prévenir de ces pièges. Pour vous récompenser d'être resté
avec moi, voici une astuce de débogage.
Collez le code suivant au début de votre document:
\begin{Verbatim}
  \newwrite\luadebug
  \immediate\openout\luadebug luadebug.lua
  \AtEndDocument{\immediate\closeout\luadebug}
  \newcommand\directluadebug{\immediate\write\luadebug}
\end{Verbatim}
Ensuite, lorsque vous aurez du mal à comprendre pourquoi un appel particulier
à ©\directlua© ne fait pas ce que vous attendez, remplacez cette occurrence
de la commande par ©\directluadebug©, compilez comme d'habitude et regardez
dans le fichier \file{luadebug.lua} ce que l'interpréteur Lua a réellement lu.

Le package \pk{luacode} fournit des commandes et des environnements qui aident
de différentes façons à résoudre certains de ces problèmes. Cependant, dès que
le code Lua utilisé n'est plus trivial, il est plus sage d'utiliser un fichier
externe contenant uniquement du code Lua définissant des fonctions,
puis de le charger et d'appeler ses fonctions depuis le document \luatex.
Par exemple:
%%
\begin{Verbatim}
  \directlua{dofile("mes-functions-lua.lua")}
  \newcommand*{\macrogeniale}[2]{%
    \directlua{ma_fonction_geniale("\luatexluaescapestring{#1}", #2)}}
\end{Verbatim}

L'exemple suppose que ©ma_fonction_geniale© est définie dans ©mes-fonctions-lua.lua©
et prend une chaîne de caractères et un nombre comme arguments. Remarquez que nous
prenons soin d'utiliser la primitive ©\luatexluaescapestring© sur la chaîne de
caractères passée en argument, afin de protéger tout anti-slash ou guillemets doubles
qu'elle pourrait contenir et qui pourraient perturber l'analyseur syntaxique de
Lua.\footnote{Si vous avez déjà utilisé SQL, le concept de protection (ou échappement)
  des chaînes de caractères devrait vous être familier.}

\medskip

C'est tout pour ce qui concerne Lua dans \tex. Maintenant, si vous vous
demandez pourquoi ©\luatexluaescapestring© a un nom aussi ridiculement long,
lisez la section suivante.

\subsection{Autres choses à savoir}\label{things}

Avant toute chose, mentionnons que le manuel de \luatex, \file{luatexref-t.pdf},
est une excellente source d'informations sur \luatex et vous voudrez probablement
le consulter à un moment ou à un autre (bien qu'il soit un peu aride et technique).

Il est important de noter que les noms des nouvelles primitives de \luatex tels
que vous les lisez dans le manuel ne sont pas les noms réels que vous pourrez
utiliser dans \lualatex. En effet, pour éviter des conflits avec les noms de macros
existants, toutes les nouvelles primitives ont été préfixées par ©\luatex©,
à moins qu'elles ne commencent déjà par ce terme. Ainsi, ©\luaescapestring©
devient ©\luatexluaescapetring©, tandis que ©\luatexversion© reste ©\luatexversion©.
Le raisonnement est détaillé dans la section~\ref{formats}.

\medskip

Oh, et au fait, ai-je mentionné que \luatex est en version bêta et que
la version~1.0 est attendue pour le printemps~2014? Vous pourrez en apprendre
davantage en lisant la feuille de route présentée sur le
\href{http://luatex.org/}{site web de \luatex}. Des versions bêta stables
sont publiées régulièrement et sont incluses dans \texlive depuis~2008,
et dans \miktex depuis 2.9.

Le support de \luatex dans \latex est tout nouveau, ce qui signifie qu'il peut
être bourré de bugs et que les choses peuvent encore changer à tout moment.
Il est donc important de garder votre distribution \tex bien à jour pour avoir
les corrections de bugs\footnote{For \texlive, consider using the complementary
  \href{http://tlcontrib.metatex.org/}{tlcontrib} repository.} et éviter
d'utiliser \lualatex pour des documents critiques, au moins pendant un certain temps
(pour ne pas rencontrer un nouveau bug au mauvais moment).

De façon générale, ce guide documente les choses telles qu'elles sont au moment
précis où il est écrit (ou mis à jour), sans tenir compte des changements
éventuellement déjà prévus. Nous espérons que vous mettrez à jour votre
distribution dans son ensemble afin d'avoir toujours des versions
qui se correspondent entre ce guide et les packages, formats et moteurs
qu'il décrit.


\selectlanguage{english}
\section{Packages et pratiques essentiels}\label{essential}

Cette section présente les packages que vous voudrez sans doute toujours
charger en tant qu'utilisateur, ou que vous devez absolument connaître
en tant que développeur.

\subsection{Niveau utilisateur}

\pkdesc{fontspec}{\WSPR}{\xetex, \luatex}{\latex}{%
  macros/latex/contrib/fontspec/}[https://github.com/wspr/fontspec/]
Interface conviviale pour la gestion des polices, bien intégrée dans le modèle
de sélection des polices de \latex. Déjà présenté dans la section précédente.

\pkdesc{polyglossia}{\FC \& \AR}{\xetex, \luatex}{\latex}{%
  macros/latex/contrib/polyglossia/}[https://github.com/reutenauer/polyglossia/]
Un remplacement simple et moderne de Babel, travaillant main dans la main avec \pk{fontspec}.

\subsection{Niveau développeur}

\subsubsection{Conventions de nommage}

Du côté de \tex, les séquences de contrôle commençant par ©\luatex© sont
réservées aux primitives. Il est fortement recommandé de \emph{ne pas} définir
de telles séquences de contrôle, afin d'éviter les conflits de noms avec
les futures versions de \luatex. Si vous souhaitez souligner qu'une macro est
spécifique à \luatex, nous vous recommandons d'utiliser le préfixe ©\lua©
(sans le ©tex© suivant). Il est possible d'utiliser le préfixe ©\luatex@©
pour les macros internes, puisque les noms des primitives ne contiennent
jamais ©@©, mais cela peut prêter à confusion.
Dans tous les cas, il est conseillé d'utiliser un préfixe unique pour
les macros internes de tous vos packages, donc ces conventions de nommage
ne devrait pas vous poser de problème.

En ce qui concerne Lua, veuillez garder l'espace de noms global aussi propre
que possible. En d'autres termes, utilisez une table ©mypackage© et placez
toutes vos fonctions et objets publics dans cette table. Vous devez aussi
éviter d'utiliser la fonction \code{module()} de Lua, qui est obsolète.
D'autres stratégies pour la gestion des modules Lua sont discutées dans
\href{http://www.lua.org/pil/15.html}{le chapitre~15 de \emph{Programming in Lua}},
et des exemples sont donnés dans \file{luatexbase-modutils.pdf}. De plus,
c'est une saine habitude d'utiliser ©local© pour vos variables et fonctions
internes. Enfin, pour éviter tout conflit avec les futures versions de \luatex,
il est nécessaire d'éviter de modifier les espaces de noms des bibliothèques
par défaut de \luatex.

\subsubsection{Détection du moteur et du mode}\label{detect}

Plusieurs packages permettent d'identifier le moteur qui traite actuellement le document.

\pkdesc{ifluatex}{\HO}{tous}{\latex, Plain}{%
  macros/latex/contrib/oberdiek/}
Fournit ©\ifluatex© et s'assure que ©\luatexversion© est disponible.

\pkdesc{iftex}{\VK}{tous}{\latex, Plain}{%
  macros/latex/contrib/iftex/}[http://bitbucket.org/vafa/iftex]
Fournit les commandes ©\ifPDFTeX©, ©\ifXeTeX©, ©\ifLuaTeX© et les commandes
©\Require© correspondantes.

\pkdesc{expl3}{The \LaTeX3 Project}{tous}{\latex}{%
  macros/latex/contrib/expl3/}[http://www.latex-project.org/code.html]
Fournit, entre \emph{beaucoup} d'autres choses, ©\luatex_if_engine:TF©,
©\xetex_if_engine:TF© et leurs variantes.
%%

\pkdesc{ifpdf}{\HO}{tous}{\latex, Plain}{%
  macros/latex/contrib/oberdiek/}
Fournit le commutateur ©\ifpdf©. \luatex, comme \pdftex, peut produire une
sortie~PDF ou DVI; cette dernière n'est pas très utile avec \luatex car elle
ne supporte aucune fonctionnalité avancée telle que l'Unicode et les formats
de police modernes. Le commutateur ©\ifpdf© est vrai si et seulement si vous
exécutez \pdftex-ou-\luatex en mode PDF (notez que cela n'inclut pas \xetex,
dont le support du format PDF est différent).


\subsubsection{Ressources de base}

\pkdesc{luatexbase}{\ER, \MPG \& \PHG}{\luatex}{\latex, Plain}{%
  macros/luatex/generic/luatexbase/}[https://github.com/lualatex/luatexbase]
Les formats Plain et \latex fournissent des macros pour gérer les ressources
de base de \tex, comme les compteurs ou les registres de boîtes.
\luatex introduit de nouvelles ressources qui doivent être partagées intelligemment
par les packages. Ce package fournit les outils de base pour gérer: les
ressources \tex conventionnelles étendues, les tables de catcodes, les attributs,
les callbacks, le chargement et l'identification des modules Lua. Il fournit
également des outils de base pour gérer quelques problèmes de compatibilité
avec les anciennes versions de \luatex.

\note{Attention:} Ce package est actuellement en conflit avec le package
\pk{luatex}, puisqu'ils font quasiment la même chose. Les auteurs des deux
packages sont bien conscients de cette situation et prévoient de les fusionner
d'une manière ou d'une autre dans un avenir proche, bien que le calendrier
ne soit pas encore fixé.

\pkdesc{luatex}{\HO}{\luatex}{\latex, Plain}{%
  macros/latex/contrib/oberdiek/}
Voir la description de \pk{luatexbase} ci-dessus. Ce package fournit les mêmes
fonctionnalités de base, à l'exception de la gestion des callbacks et de
l'identification des modules Lua.

\pkdesc{lualibs}{\ER \& \PHG}{\luatex}{Lua}{%
  macros/luatex/generic/lualibs/}[https://github.com/lualatex/lualibs]
Collection de bibliothèques Lua et de compléments aux bibliothèques standards;
principalement dérivé des bibliothèques \context. Si vous avez besoin
d'une fonction de base que Lua ne fournit pas, consultez ce package avant
de vous lancer dans votre propre développement.


\subsubsection{Gestion interne des polices de caractères}\label{fontint}

Ces packages sont chargés par \pk{fontspec} pour gérer certaines polices
de bas niveau et les problèmes d'encodage. Un utilisateur normal ne devrait
utiliser que \pk{fontspec}, mais un développeur peut avoir besoin de les connaître.

\pkdesc{luaotfload}{\ER, \KH \& \PHG}{\luatex}{\latex, Plain}{%
  macros/luatex/generic/luaotfload/}[https://github.com/lualatex/luaotfload]
Chargement de bas niveau des polices OpenType, adapté du code générique de \context.
En gros, il utilise la bibliothèque Lua ©fontloader© et les callbacks correspondants
pour implémenter une syntaxe pour la primitive ©\font© très similaire à celle de \xetex
et donner accès aux propriétés correspondantes des polices. Il gère également une base
de données de polices pour un accès transparent aux polices du système et de la
distribution \tex, soit par nom de famille, soit par nom de fichier, ainsi qu'un
système de cache pour un chargement plus rapide des polices.

\pkdesc{euenc}{\WSPR, \ER \& \KH}{\xetex, \luatex}{\latex}{%
  macros/latex/contrib/euenc/}[https://github.com/wspr/euenc]
Implémente les encodages de polices Unicode ©EUx© pour le système \pf{fontenc}
de \latex. Actuellement, \xelatex utilise ©EU1© et \lualatex utilise ©EU2©.
Inclut les définitions (fichiers \file{fd}) pour Latin Modern, la police
chargée par défaut par \pk{fontspec}.

Pour être précis, \pf{euenc} déclare simplement l'encodage, mais ne fournit pas
de définitions pour les macros LICR; ceci est fait en chargeant \pk{xunicode}
avec ©\UTFencname© défini à ©EU1© ou ©EU2©, ce que fait \pk{fontspec}.
Les encodages réels sont les mêmes, mais il est utile d'avoir des noms distincts
pour que différents fichiers \file{fd} puissent être utilisés selon le moteur
(ce qui est en fait le cas avec Latin Modern).

\section{Autres packages}\label{other}

Notez que les packages sont listés sans ordre particulier.

\subsection{Niveau utilisateur}

\pkdesc{luatextra}{\ER \& \MPG}{\luatex}{\latex}{%
  macros/luatex/latex/luatextra/}[https://github.com/lualatex/luatextra]
Charge les packages habituels, actuellement \pk{fontspec}, \pk{luacode}, \pf{metalogo}
(commandes pour les logos, y compris ©\LuaTeX© et ©\LuaLaTeX©), \pk{luatexbase},
\pk{lualibs}, \pf{fixltx2e} (corrections et améliorations pour le noyau \latex).

\pagebreak[4]
\pkdesc{luacode}{\MPG}{\luatex}{\latex}{%
  macros/luatex/latex/luacode/}[https://github.com/lualatex/luacode]
Fournit des commandes et des macros qui aident à inclure du code Lua
dans un source \tex, en particulier pour les caractères spéciaux.

\pkdesc{luainputenc}{\ER \& \MPG}{\luatex, \xetex, \pdftex}{\latex}{%
  macros/luatex/latex/luainputenc/}[https://github.com/lualatex/luainputenc]
Aide à la compilation de documents utilisant des encodages anciens
(soit dans le source, soit avec les polices). Déjà présenté dans l'introduction.
Sous \xetex, charge simplement \pf{xetex-inputenc}; sous \pdftex,
charge l'\pf{inputenc} standard.

\pkdesc{luamplib}{\HH, \Taco \& \PHG}{\luatex}{\latex, Plain}{%
  macros/luatex/generic/luamplib/}[https://github.com/lualatex/luamplib]
Fournit une interface conviviale pour la bibliothèque Lua ©mplib©,
qui intègre MetaPost dans \luatex.

\pkdesc{luacolor}{\HO}{\luatex}{\latex}{%
  macros/latex/contrib/oberdiek/}
Change l'implémentation de bas niveau des couleurs pour utiliser les attributs
\luatex à la place des \emph{whatsits} (\og{}éléments extraordinaires\fg{}).
Cela rend l'implémentation plus robuste et corrige des bugs bizarres, notamment
un mauvais alignement lorsque ©\color© se trouve au début d'un ©\vbox©.

\subsection{Niveau développeur}

\pkdesc{pdftexcmds}{\HO}{\luatex, \pdftex, \xetex}{\latex, Plain}{%
  macros/latex/contrib/oberdiek/}
Bien que \luatex soit principalement un sur-ensemble de \pdftex, quelques
primitives utilitaires ont été supprimées (celles qui sont en quelque sorte
remplacées par Lua) ou renommées. Ce package les fournit avec des noms cohérents
entre les différents moteurs, y compris \xetex qui a récemment implémenté
certaines de ces primitives, comme ©\strcmp©.

\pkdesc{magicnum}{\HO}{\luatex, \pdftex, \xetex}{\latex, Plain}{%
  macros/latex/contrib/oberdiek/}
Fournit un accès hiérarchique aux \og{}nombres magiques\fg{} tels que
les \emph{catcodes}, les types de groupes, etc., utilisés en interne par \tex
et ses héritiers. Sous \luatex, une implémentation plus efficace est
utilisée et une interface Lua est fournie.

\pagebreak[4]
\pkdesc{lua-alt-getopt}{Aleksey Cheusov}{\cmd{texlua}}{ligne de commandes}{%
  support/lua/lua-alt-getopt}[https://github.com/LuaDist/alt-getopt]
Parseur d'options de ligne de commande, principalement compatible avec POSIX
et GNU~getopt, à utiliser dans les scripts Lua en ligne de commande tels
que \cmd{mkluatexfontdb} ou \pk{luaotfload}.

\section{Les formats \cmd{luatex} et \cmd{lualatex}}\label{formats}

Cette section s'adresse aux développeurs et aux utilisateurs curieux;
les utilisateurs normaux peuvent la sauter. Les informations suivantes
s'appliquent à \texlive{}~2010, et très probablement à \miktex{}~2.9 aussi,
bien que je n'aie pas vérifié. Les versions antérieures de \texlive avaient
des fonctionnalités légèrement différentes et moins complètes.


\para{\parbox[t][1.5ex]{14ex}{\raggedleft Noms des\\ primitives}}[nomsprimitives]
Comme mentionné dans la section~\ref{things}, les noms des primitives spécifiques
à \luatex ne sont pas les mêmes dans le format \cmd{lualatex} que dans le manuel
de \luatex. Dans le format \cmd{luatex} (c'est-à-dire \luatex avec le format Plain),
les primitives sont disponibles avec leur nom naturel, mais aussi avec le nom préfixé,
afin de faciliter le développement de packages génériques.

Le raisonnement, copié-collé du fichier \file{lualatexiniconfig.tex} qui implémente
ceci pour le format \cmd{lualatex}, est le suivant:

\begin{myquote}
  \begin{enumerate}
    \item Tous les packages de macros actuels fonctionnent sans problème
      avec pdf(e)TeX, donc ces primitives sont conservées telles quelles.
    \item D'autres primitives (ne datant pas de TeX82) dans \luatex peuvent
      provoquer des conflits de noms avec des macros existantes dans des packages,
      en particulier lorsqu'elles utilisent des noms très \og{}naturels\fg{}
      tels que ©\outputbox©, ©\mathstyle©, etc. La probabilité d'un tel conflit
      de noms est importante et la situation est assez inconfortable, car plus
      les documents \latex existants fonctionneront dans leur état actuel avec
      \luatex, mieux ce sera.
    \item L'équipe \luatex ne souhaite pas appliquer une politique de préfixage
      systématique, mais elle a aimablement fourni 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 préférable de les activer avec un préfixe systématique, afin
      d'éviter que chaque package (ou chaque utilisateur) les active avec des
      préfixes variés et incohérents (y compris avec le préfixe vide).
    \item Le préfixe ©luatex© a été choisi car il est déjà utilisé comme
      préfixe pour certaines primitives, comme ©\luatexversion©: de cette façon,
      ces primitives ne se retrouvent pas avec un double préfixe (pour plus de détails,
      voir ©tex.enableprimitives© dans le manuel de \luatex).
    \item La primitive ©\directlua© est fournie à la fois avec son nom naturel
      (permettant une détection facile de \luatex) et une version préfixée,
      ©\luatexdirectlua© (par souci de cohérence avec ©\luatexlatelua©).
    \item Remarques diverses:
      \begin{itemize}
        \item L'inconvénient évident d'une telle politique de préfixage est
          que les noms utilisés par \latex ou l'outil générique d'écriture de
          macros ne correspondront pas aux noms utilisés dans le manuel.
          Nous espérons que cet inconvénient est compensé par le gain en
          compatibilité ascendante.
        \item Toutes les primitives s'occupant de la gymnastique Unicode
          commencent déjà par ©\U©, et leurs noms correspondront peut-être
          un jour aux noms des primitives \xetex; donc peut-être que le
          préfixage n'était ni nécessaire ni souhaitable pour elles.
          Cependant, nous avons essayé de rendre la règle de préfixage aussi
          simple que possible, afin de ne pas aggraver les inconvénients
          évoqués ci-dessus.
        \item Peut-être qu'un jour nous penserons qu'il est préférable de fournir
          toutes les primitives sans préfixe. Si cela se produit, il sera facile
          d'ajouter les primitives non préfixées dans le format tout en conservant
          les noms préfixés pour la compatibilité. Ce serait beaucoup plus
          problématique dans l'autre sens: si l'on réalisait tardivement qu'il
          vaudrait mieux ne pas fournir de primitives sans préfixe, cela casserait
          tous les packages spécifiques à \luatex qui auront été écrits.
      \end{itemize}
  \end{enumerate}
\end{myquote}

\para{\cs{jobname}}[jobname]
Le noyau \latex (et de nombreux packages) utilise des constructions comme
©\input\jobname.aux© dans divers buts. Lorsque ©\jobname© contient des espaces,
cela ne fait pas ce qu'il faut, puisque l'argument de ©\input© se termine au
premier espace. Pour contourner ce problème, \pdftex met automatiquement des
guillemets autour de ©\jobname© lorsque cela est nécessaire, mais \luatex ne le fait pas,
pour une raison inconnue. Une solution de contournement presque idéale
est incluse dans les formats \luatex basés sur \latex (par opposition à Plain \tex).

Malheureusement, cette solution ne fonctionne pas, cependant, si \luatex est invoqué avec la syntaxe
©lualatex '\input name'©, par opposition au plus habituel ©lualatex name©.
Pour contourner cette limitation de la solution de contournement incluse dans le format,
spécifiez un nom de travail explicitement, comme dans
©lualatex jobname=name '\input name'©. Ou encore mieux: n'utilisez pas d'espaces
dans les noms de vos fichiers \tex.

Pour plus de détails, voir \href{http://www.ntg.nl/pipermail/dev-luatex/2009-April/002549.html}{cet
ancien fil de discussion} et \href{http://tug.org/pipermail/luatex/2010-August/001986.html}{ce fil
plus récent} sur les listes de diffusion \luatex, ainsi que le fichier \file{lualatexquotejobname.tex}
pour l'implémentation de la solution de contournement.

\para{\parbox[t][1.5ex]{14ex}{\raggedleft motifs\\ de césure}}[motifscesure]
\luatex permet le chargement dynamique des motifs de césure. Le support pour ceci
dans \pf{babel} et \pf{polyglossia} est apparu seulement sur \texlive{}~2013,
mais devrait bien fonctionner depuis.

La documentation et les détails d'implémentation sont inclus dans \file{luatex-hyphen.pdf}.
Les sources font partie du \href{http://tug.org/tex-hyphen/}{projet \emph{texhyphen}}.

\para{codes}
Le moteur lui-même ne définit pas les ©\catcode©s, ©\lccode©s, etc. pour les
caractères non-ASCII. Des ©\lccode©s corrects, en particulier, sont essentiels
pour que la césure fonctionne. Les formats pour \luatex incluent maintenant
\file{luatex-unicode-letters.tex}, une version modifiée de \file{unicode-letters.tex}
de la distribution \xetex, qui se charge de régler ces valeurs en conformité avec
la norme Unicode.

Ceci a été ajouté après la sortie de \texlive{}~2010, il est donc fortement conseillé
de mettre à jour votre installation si vous voulez bénéficier d'une césure correcte
pour les textes non-ASCII.


\section{Ce qui marche, ce qui marchotte et ce qui ne marche pas (encore)}\label{workornot}

\subsection{Ça marche}\label{working}

\para{Unicode}
Le \latex conventionnel offre un certain niveau de support pour UTF-8 dans
les fichiers d'entrée. Cependant, à bas niveau, les caractères non-ASCII
ne sont pas atomiques dans ce cas: ils sont constitués de plusieurs morceaux
élémentaires (connus sous le nom de \emph{tokens} par les \tex{}niciens).
Par conséquent, certains packages qui analysent le texte caractère par caractère
ou effectuent d'autres opérations atomiques sur les caractères (comme la
modification de leurs \emph{catcodes}) ont souvent des problèmes avec UTF-8
en \latex conventionnel. Par exemple, vous ne pouvez pas utiliser n'importe
quel caractère non-ASCII pour du verbatim court avec \pf{fancyvrb}, etc.

La bonne nouvelle est qu'avec \lualatex, certaines des fonctionnalités de ces packages
commencent à fonctionner sur des caractères Unicode arbitraires sans avoir besoin de
modifier le package. La mauvaise nouvelle est que ce n'est pas toujours vrai.
Voir la section suivante pour plus de détails.

\subsection{Ça marche partiellement}\label{partial}

\para{microtype}
Le package \pf{microtype} n'est pas entièrement compatible avec \luatex:
plus précisément, à partir de la version~2.5 (2013/03/13), la protrusion
et l'expansion sont disponibles et activées par défaut en mode~PDF, mais
le crénage, l'espacement et le réglage de l'approche ne sont pas supportés
(voir le tableau~1 dans la section~3.1 de \file{microtype.pdf}).
%%

D'un autre côté, \pk{luaotfload}, chargé par \pk{fontspec}, supporte un grand
nombre de fonctionnalités microtypographiques. Le seul problème est donc
l'absence d'une interface unifiée.

\para{xunicode}
La principale fonctionnalité du package \pf{xunicode} est de s'assurer que les
séquences de contrôle habituelles pour les caractères non-ASCII (comme ©\'e©)
font ce qu'il faut dans un contexte Unicode. Il pourrait \emph{probablement}
fonctionner avec \luatex, mais ça n'est officiellement vrai que pour \xetex.
Cependant, \pk{fontspec} utilise une astuce pour le charger de toutes façons.
Donc, vous ne pouvez pas le charger explicitement, mais vous n'en avez pas besoin,
puisque \pk{fontspec} s'en est déjà occupé.

\para{encodings}
Comme mentionné dans la section précédente, certaines choses qui posaient problème
avec UTF-8 en \latex conventionnel fonctionnent maintenant naturellement, mais pas
toujours. Par exemple, avec le package \pf{listings} de \lualatex, vous ne pouvez
utiliser que les caractères inférieurs à~256 (c'est-à-dire les caractères du jeu
Latin-1), dans vos listings (mais bien sûr, toute la gamme Unicode est toujours
disponible dans le reste de votre document).

\para{métriques}
Ça, ça fonctionne en soi, mais ça ne fonctionne pas exactement de la même manière
que \pdftex ou \xetex: vous pourrez observer des différences mineures dans
la mise en page et les coupures de mots de votre texte.

Elles peuvent être dues à des variations entre deux versions de la même police
utilisée par les différents moteurs, à des ajustements apportés aux algorithmes
de césure, de ligature ou de crénage (par exemple, le premier mot d'un paragraphe,
ainsi que les mots contenant des polices différentes, peuvent désormais être coupés
en fin de ligne), ou à des différences dans les motifs de césure utilisés (les motifs
utilisés par \pdftex sont fondamentalement figés, mais \luatex et \xetex utilisent
des versions plus récentes pour certaines langues) pour cette langue.

Si vous observez une différence majeure entre pdf\latex et \lualatex avec les
mêmes polices, il n'est pas du tout improbable qu'un bug dans \luatex\footnote{Par
  exemple, \luatex{}~0.60 avait un bug qui empêchait toute césure après une ligature
  \code{-{}-{}-} jusqu'à la fin du paragraphe.} ou dans la police soit impliqué.
Comme d'habitude, assurez-vous que votre distribution est à jour avant de signaler
un tel problème.

\para{babel}
Fonctionne pour l'essentiel sans problème pour les langues latines. Pour les
autres langues, les résultats peuvent varier. Même pour les langues latines,
des problèmes liés à l'encodage peuvent survenir.

\para{polyglossia}[polyglossia2]
Un package plus moderne que \pf{babel}, mais moins complet, pour le support
multilingue, \pf{polyglossia}, est également disponible et devrait être préféré,
bien qu'il ne supporte pas encore toutes les fonctionnalités de \pf{babel}.

\subsection{Ça ne marche pas (encore)}\label{notworking}

\para{\parbox[t][1.5ex]{14ex}{\raggedleft anciens\\ encodages}}[oldenco] Les packages jouant avec les encodages d'entrée
(fichiers sources) ou de sortie (polices) sont très susceptibles de ne pas fonctionner
avec \luatex. Cela inclut \pf{inputenc}, \pf{fontenc}, \pf{textcomp}, et probablement
la plupart des packages de polices classiques tels que \pf{mathptmx} ou \pf{fourier}.
La bonne nouvelle est qu'Unicode est un moyen plus puissant de gérer les problèmes
d'encodage que les anciens packages essayaient de résoudre, donc vous n'avez probablement
plus besoin de ces anciens packages. Cependant, tout n'a pas encore été porté
dans le nouveau monde merveilleux d'Unicode, et il se peut que vous ayez un choix
plus limité (ou simplement différent) pendant un certain temps (ceci est particulièrement
vrai pour les polices).

\para{espaces} Les espaces dans les noms de fichiers ne sont pas vraiment
bien supportés dans le monde \tex en général. Cela ne s'améliore pas non plus
avec \luatex. De plus, pour des raisons délicates, les choses peuvent être pires
si vous avez des espaces dans le nom de votre fichier \tex principal \emph{et}
que vous n'invoquez pas \luatex de la manière habituelle. Si vous l'invoquez
de la manière habituelle, tout devrait fonctionner, et je ne vous dirai pas
à quoi ressemble l'invocation inhabituelle. Sinon, lisez le paragraphe sur
\pararef{jobname} dans la section~\ref{formats} pour une solution de contournement
et des détails techniques. Mais le mieux, c'est de ne pas utiliser d'espaces
dans les noms de vos fichiers \tex.

\end{document}

% vim: spell spelllang=en