LaTeX/À l'aide !

Si LaTeX est un programme très stable (il ne plante pas), il y a en revanche des possibilités de faire des erreurs en entrant les instructions. Cela va se manifester par des messages d'erreur et un résultat non conforme à vos désirs, voire pas de résultat du tout…

Voir aussi Premier exemple > Déroulement de la compilation.

Comme il s'agit d'un logiciel libre, vous avez une communauté du Web qui sera prête à vous aider, à condition que vous vous montriez poli !

Nous allons voir quelques erreurs communes, comment les éviter, et comment demander de l'aide sur le Web.

Utiliser un éditeur de texte adapté

Nous avons vu précédemment que le choix d'un éditeur de texte adapté était fondamental (voir Installer LaTeX > Choisir un éditeur de texte) :

• il permet de repérer les parenthèses, crochets ou environnements que l'on aurait ouverts et pas refermés ;
• il permet d'insérer les instructions les plus courantes, réduisant le risque de faute de frappe ;
• la coloration syntaxique permet de mieux repérer les instructions et appariements d'accolades et de crochets, donc de déceler les sources d'erreur ;
• en facilitant la mise en forme du code (indentations), il le rend plus lisible et donc rend plus facile son déverminage (voir Éléments de base > Structuration du code source).

Faire des essais

Vous voudrez probablement, à un moment ou à un autre, faire des essais, pour tester une commande que vous venez de découvrir ou de créer par exemple. Deux outils peuvent vous être utiles : la classe de document minimal et l'extension lipsum.

La classe de document minimal, comme son nom l'indique, contient le minimum requis pour faire un texte, et rien d'autre. De ce fait, tout ce que vous utilisez dans votre document ne marche pas, mais l'utilisation d'une classe minimale permet de faire fonctionner ce qui est « universel ». Par exemple, vous ne pouvez pas mettre de sectionnement (\chapter{…}, \section{…}, …), les listes s'affichent sans symbole ou numéro en tête d'alinéa, les tableaux n'ont pas de filet, …

L'extension lipsum fournit la commande \lipsum, qui génère sept paragraphes d'un texte en pseudo-latin (le fameux « Lorem ipsum… »), occupant environ une page. Le texte complet comporte 150 paragraphes, et s'obtient avec \lipsum[1-150], ce qui représente une vingtaine de pages. Vous pouvez ne mettre que le premier paragraphe en utilisant \lipsum[1]. Ceci permet de faire du remplissage.

Voici par exemple un document de test minimal :

\documentclass{minimal}

\usepackage{lipsum}

\begin{document}
   \lipsum
\end{document}

Problèmes de rendu

Les fichiers générés, utilisés pour la visualisation ou l'impression, sont au format device independent (fichier .dvi), Adobe PostScript (fichier .ps) ou Adobe Portable Document Format (fichier .pdf). Ce ne sont pas des « images figées » qui sont simplement affichées par le visualiseur ; le visualiseur « redessine » à chaque fois le document à partir des informations contenues dans le fichier.

De fait, les différents programmes de visualisation n'ont pas exactement le même comportement, et l'on peut obtenir un affichage légèrement différent de ce à quoi on s'attend. L'impression, elle, est en général correcte (elle est gérée par le pilote d'impression, ou driver, qui interprète « correctement » le fichier).

Ce genre de problème ne se produit pas avec du texte simple, bien que certains visualiseurs peuvent avoir un rendu assez mauvais des polices Computer Modern et Extended Computer Modern. Il va surtout survenir avec des fonds colorés, où l'on peut voir des décalages entre le pavé de couleur et le filet (contour de la boîte), ou bien si l'on fait des dessins (problèmes d'épaisseur de trait).

Face à un tel problème, on peut

• imprimer la page incriminée et la comparer au rendu à l'écran ;
• essayer avec un autre visualiseur, et comparer les rendus ;
• générer un fichier de l'autre format (.ps si l'on utilise le .pdf, .pdf si l'on utilise le .ps) et comparer les rendus ;

pour voir si le problème vient du rendu ou du fichier (et donc du code que vous avez tapé ou bien d'une bogue de l'extension employée).

Nettoyage des fichiers générés

Parfois, vous pensez avoir corrigé le problème, mais un message d'erreur persiste. Les fichiers générés (.aux, éventuellement .bbl et .blg pour la bibliographie, et .idx et .ind pour un index) peuvent contenir des erreurs générées par la compilation de l'ancienne version du document LaTeX. Le fait d'effacer ces fichiers — mais en faisant attention à bien conserver le fichier .tex (ils portent tous le même nom …) — peut résoudre le problème.

Consultation du journal des erreurs

Lors de la compilation, latex (ou pdftex) génère des messages indiquant le bon déroulement de l'opération, ou bien des avertissement et messages d'erreur.

Si vous compilez en ligne de commande, les messages s'affichent dans la fenêtre du shell. Il peuvent aussi s'afficher dans une fenêtre dédiée de votre éditeur de texte. Sinon, ils sont placés dans un fichier portant le nom du fichier source mais l'extension .log, appelé « fichier de log » ou « journal des erreurs ».

La première chose à faire est donc de consulter le journal des erreurs afin de voir les problèmes. Il s'agit d'un fichier de texte, s'ouvrant avec n'importe quel éditeur de texte.

Démarche de déverminage

La première chose à faire est de tenter de résoudre les erreurs indiquées dans le journal des erreurs.

Voir Chasse aux erreurs

Parfois, vous n'arriverez pas à résoudre certaines erreurs. La première chose à faire est d'isoler le passage problématique. En effet, une erreur peut se manifester bien plus loin ; par exemple, si vous oubliez de fermer une accolade ou un environnement, tout le texte qui suit est considéré comme influencé par la commande ou faisant partie de l'environnement, et le message peut apparaître lorsque le contenu devient incompatible avec la commande ou l'environnement.

Ordre des extensions

L'ordre dans lequel les extensions sont déclarées dans le préambule peut avoir de l'importance. En effet, certaines extensions redéfinissent le comportement d'une ou plusieurs fonctions de LaTeX, une fonction peut ainsi se voir redéfinir par plusieurs extensions.

De manière générale, il faut :

1. placer les extensions inputenc et fontenc en premier ;
2. puis, placer les extensions qui modifient la mise en page du document, comme par exemple geometry ;
3. placer babel en dernier.

Il existe des exceptions, qui sont en général mentionnées dans la documentation de l'extension. Par exemple, l'extension hyperref doit être placée en dernier (après babel) dans le préambule.

Isoler le passage problématique

Le message d'erreur indique le numéro de ligne où se produit l'erreur. Si vous avez un éditeur de texte adapté, vous retrouverez facilement cette ligne. Il faut alors isoler le passage :

• créez un fichier .tex vierge ; on le baptise traditionnellement ecm.tex, comme « exemple complet et minimal » ;
• copiez le préambule du fichier en cause ;
• copiez le passage en cause.

Le passage en cause contiendra évidemment la ligne citée, mais

• si cette ligne est à l'intérieur d'un bloc, on mettra tout le bloc et éventuellement la ou les instructions qui agissent sur le bloc ; une bonne précaution consiste à garder le paragraphe en cours ;
• si cette ligne est dans un environnement, on mettra tout l'environnement.

Puis, on recompile cet ECM. Si l'erreur ne se produit pas, c'est que le problème se trouve ailleurs, on fera une recherche par dichotomie (cf. ci-après). Sinon, on va essayer de simplifier encore l'ECM afin d'isoler vraiment l'erreur. Pour cela,

1. on enlève les extensions inutiles, pour ne garder que inputenc (si l'on a des caractères accentués dans le source) et les extensions spécifiques au passage (commandes ou environnements non-standard) ;
2. on enlève tout le texte inutile, précédant ou suivant l'instruction à problème ; pour un tableau, on ne gardera par exemple qu'une ligne du tableau, et on mettra un texte simplifié dans les autres cases du tableau.

On enregistre et on recompile après chaque simplification : si le problème disparaît, c'est que l'on a enlevé une partie contribuant au problème ; il faut alors la remettre et continuer la simplification.

Cette démarche peut vous permettre de déceler l'erreur. Sinon, vous disposez d'un fichier ECM que vous pourrez soumettre à la communauté Internet.

Recherche par dichotomie

Si le problème ne se situe pas dans le passage pointé par le journal d'erreur, il va falloir chercher le passage incriminé… La stratégie la plus rapide est la dichotomie :

1. on renomme le fichier en question en ecm.tex (par exemple) ;
2. on supprime tout ce qui suit le passage problématique (en conservant le bloc et/ou l'environnement en cours, et bien sûr le \end{document} final) ; on enregistre et on recompile pour vérifier que l'erreur se situe bien avant ;
3. soit n le numéro de la ligne signalé ; on supprime les lignes entre le \begin{document} et la ligne n/2 (arrondie au dessus ou en dessous si n est impair), en faisant attention de ne pas couper un paragraphe ni un environnement, a fortiori un bloc ;
4. on enregistre et on recompile ;
   • si l'erreur disparaît, c'est qu'une partie du problème se trouve dans la partie supprimée ; on remet donc cette partie et on supprime la partie entre la ligne n/2 et la ligne en cours (en ne coupant ni un paragraphe, ni un environnement, ni un bloc) ; on reprend au point 3 (le numéro de ligne n a changé puisqu'il y a moins de lignes) ;
   • si l'erreur est toujours là, on reprend au point 3 (le numéro de ligne n a changé puisqu'il y a moins de lignes).

En quelques étapes, on arrive à isoler l'erreur : si un fichier fait 10 000 lignes, il contiendra 5 000 à la première étape, 2 500 à la deuxième, …, et 10 lignes à la dixième étape.

Si vous n'arrivez pas à résoudre le problème isolé ainsi, vous disposez d'un ECM à soumettre à la communauté Internet.

Rechercher sur Internet

Mais avant de faire appel à la communauté, il convient d'essayer de vous débrouiller par vous-même.

La première chose à faire consiste à consulter les foires aux questions (FAQ) ; vous avez de nombreuses ressources sur :

• en français :
  • https://www.gutenberg.eu.org/, le site du Groupe francophone des utilisateurs de TeX (GUT) ;
  • https://faq.gutenberg.eu.org/, FAQ collaborative hébergée par GUTenberg et ouverte à tous ;
  • http://faqfctt.fr.eu.org ;
• en anglais :
  • http://www.texfaq.org/ en anglais
  • http://www.ctan.org/ (ou http://tug.ctan.org/), le Comprehensive TeX Archive network du TeX User Group (TUG) ;
  • http://tug.org/, le site du TUG.

Si une extension est en cause, il faut penser à consulter la documentation de cette extension ; une recherche par mots-clefs devrait vous permettre de la trouver.

Notez que vous avez également une documentation installée avec LaTeX. Sous un système Unix, vous pouvez taper en ligne de commande texdoc ltx-2 pour avoir la documentation en HTML, et texdoc latex2e pour l'avoir en PDF. Si ces commandes ne fonctionnent pas, essayez de chercher « latex2e » sur votre disque dur. Avec la distribution TeXlive sous MacOS X, la documentation HTML se trouve en /sw/share/texmf-dist/doc/help/Catalogue/index.html, et les fichiers PDF sont dans /sw/share/texmf-dist/doc/latex/ (il existe un répertoire pour chaque extension importante, et un répertoire general pour LaTeX en général) — le tout en anglais.

La deuxième chose consiste à faire une recherche avec un moteur de recherche, contenant comme mots-clefs les instruction, environnement, extension en cause, ainsi que « latex ». Une recherche dans les archives du groupe usenet fr.comp.text.tex s'impose : vous n'êtes sans doute pas le premier à avoir eu le problème, la solution s'y trouve sans doute déjà. Les archives se trouvent sur

http://groups.google.com/group/fr.comp.text.tex

Enfin, si tout cela est infructueux, vous pouvez poster votre problème sur news:fr.comp.text.tex, (fctt pour les intimes) avec un agent usenet (rechercher « usenet » dans l'aide de votre système d'exploitation ; Microsoft Outlook remplit cette fonction, sinon, pensez à Mozilla Thunderbird).

Si vous n'avez jamais posté, la première chose consiste à configurer le lecteur de forums. vérifiez que vous postez bien en texte pur et pas en HTML (en général dans le menu Outil | Options ou bien le menu Préférences de l'application). Cherchez votre adresse mél dans la configuration, et maquillez-là pour éviter d'avoir des messages non-sollicités (spam). Puis, allez faire un test en postant sur le groupe news:fr.test.

Ceci fait, postez sur fctt :

• mettez un titre explicite (par exemple avec le nom de l'instruction, de l'environnement ou de l'extension en cause), et non pas simplement « a l'aide » ;
  ne mettez pas d'accent dans le titre ;
• dites « bonjour »,
• décrivez votre configuration (système d'exploitation, distribution de LaTeX avec son numéro de version ou sa date) ;
• décrivez votre problème, en collant le contenu de l'ECM ;
• indiquez les recherches que vous avez déjà faites.

Surveillez le forum afin de voir les réponses, on vous demandera peut-être de fournir des précisions. Si personne ne répond au bout de 2-3 jours, relancez poliment : personne n'est peut-être compétent sur votre problème, mais peut-être que quelqu'un connaît un endroit où chercher, mais attendait de voir les réponses des autres.

Si l'on vous apporte la solution, n'oubliez pas de dire merci (-:

« Protéger » les commandes « fragiles »

Dans certains cas, vous utilisez une commande de manière correcte, mais le résultat est erroné en raison du contexte dans lequel elle se trouve. Par exemple, telle commande se comporte bien dans du corps de texte, mais donnera des résultats bizarre si elle est insérée dans une commande \chapter{…} ou un environnement tabular.

Une telle commande est dite « fragile ». On peut souvent résoudre le problème en « protégeant » cette commande, c'est-à-dire en mettant une commande \protect devant lorsque le problème se pose.

Exemple de commandes fragiles :

• \verb ;
• \numberline ;
• \chemical de l'extension ppchtex.

Chasse aux erreurs

Avertissements fréquents

Avertissements de mise en page

Overfull ou Underfull \vbox ou \hbox

• Cause : le typographe virtuel a du mal à agencer le texte, ce qui peut produire un effet inesthétique ;
• prévention : aucune ;
• solution : ne pas s'en préoccuper dans un premier temps ; dans la version finale, éventuellement insérer des contraintes sur la mise en page, par exemple un saut de page avec \newpage.

Float too large for page by …

• Cause : l'objet flottant est trop grand par rapport à la page ;
• prévention : contrôler la taille des tableaux et images à intégrer ;
• solution : ajuster la taille de l'objet.

h float specfier changed to ht

• Cause : l'objet flottant est défini avec une position h (here), mais il sera placé en haut de la page suivante ;
• prévention : aucune ;
• solution : faire précéder le h d'un point d'exclamation pour forcer le positionnement.

Avertissements de références

• Label '[…]' multiply defined ;
• Reference '[…]' on page […] undefined ;
• Labels may have changed.

Voir Structuration du texte > Erreurs possibles.

Erreurs fréquentes

! No room for …

• Cause : LaTeX gère par défaut 256 « registres » : compteurs, ressorts (blancs élastiques), blancs fixes, unités lexicales, … ; cette limite a été atteinte
• prévention : aucune ;
• solution : utiliser l'extension etex qui rajoute des registres supplémentaires (plus de 65 000).

Compilation en ligne de commande

Si vous compilez en ligne de commande, les messages s'affichent dans la fenêtre du shell, et à moins que vous ne l'ayez précisé par un option, la compilation s'interrompt à la première erreur.

Si vous ne voulez pas que la compilation s'arrête à chaque erreur, il faut la lancer avec l'option -interaction=nonstopmode :

latex -interaction=nonstopmode nom_du_fichier

Dans le cas contraire, la compilation peut s'arrêter et attendre une action de votre part :

• parce qu'elle ne trouve pas un fichier : il faut alors entrer le nom du fichier ;
• pour une erreur de syntaxe :
  • appuyer sur Entrée pour ignorer l'erreur et continuer,
  • taper X puis Entrée pour arrêter la compilation,
  • H pour avoir des détails sur l'erreur,
  • R pour ignorer cette erreur et toutes les suivantes,
  • ? pour connaître les possibilités.

Voir aussi

• Doc et aide, site des tuteurs de l'ENS
• Détecter et résoudre les problèmes (fichier PDF, 61 p., 464 kio), Latex Companion 2^e édition, F. Mittelbach, M. Goossens, D. Carlisle, C. Rowley (trad. J. André, B. Belet, J.-C. Charpentier, J.-M. Hufflen, Y. Soulet), Pearson Education