Guide des bonnes pratiques en LaTeX

Introduction du cours

Ceci est un guide des bonnes pratiques pour écrire efficacement du code LaTeX, et aussi pour poser efficacement des questions lorsqu'on a un problème. Ces conseils font consensus chez les utilisateurs avancés.

On pourrait se demander pourquoi il existe des bonnes pratiques alors qu'un code qui compile et donne le résultat souhaité est acceptable. En fait, il s'agit surtout de bien s'organiser pour s'y retrouver efficacement lorsqu'on doit intervenir sur les fichiers quelques temps plus tard.

Maîtriser l'encodage de ses fichiers

Avec LaTeX et les langages de programation en général, on édite des fichiers texte bruts, c'est-à-dire que les caractères tapés ne sont pas traités. Il faut donc faire attention à ce qu'on écrit, comment on l'écrit, et comment le système doit l'interpréter. L'encodage des fichiers sources doit donc impérativement être suivi de près. Par aileurs, LaTeX ne détecte pas automatiquement l'encodage des fichiers.

Il existe un grand nombre d'encodages. Le meilleur est l'UTF-8 : utilisez-le tout le temps, sans exceptions. Il est maintenant supporté par tous les vrais éditeurs de code. Veillez à enregistrer vos fichiers dans cet encodage (votre éditeur de texte doit vous proposer une option pour le faire). Notez également que XeLaTeX et LuaLaTeX, les variantes les plus récentes, imposent cet encodage.

Dans le préambule de vos documents, il faut dire au package inputenc quel encodage vous utilisez :

\usepackage[utf8]{inputenc}

Avec XeLaTeX et LuaLaTeX, les packages inputenc et fontenc ne sont plus nécessaires et importer fontspec suffit (car il importe implicitement xltxtra, qui lui-même importe implicitement xunicode) :

\usepackage{fontspec}

Lors des inclusions de fichiers (par exemple avec \input), LaTeX applique l'encodage spécifié à inputenc sur ces fichiers. Il faut donc qu'ils soient dans le même encodage.

En règle générale, il faut toujours vérifier si l'encodage des fichiers correspond bien à l'encodage spécifié dans le préambule.

Une attention toute particulière aux encodages évite bien des problèmes.

Pour en savoir plus sur les encodages, vous pouvez consulter l'article comprendre les encodages de maëlan.

Organisation des fichiers sourcesAppeler intelligemment les packages

Il y a des dépendances entre les packages. Ainsi, un package X peut nécessiter un package Y. Par ailleurs, un package peut modifier le comportement d'autres packages. C'est pourquoi il faut que les dépendances soient appelées avant les packages en ayant besoin. Les dépendances sont parfois directement appelées par les packages et il n'est donc pas toujours nécessaire de les appeler soi-même. Pour en être sûr, lisez la documentation du package qui vous intéresse (voir plus loin).

L'exemple typique est babel. Ce package sert à modifier le comportement par défaut de LaTeX pour que le document corresponde aux normes de la langue choisie :

• traduction des textes (« chapter » devient « chapitre » par exemple pour le français) ;

• formatage des nombres ;

• modification légère de la mise en page ;

• création de commandes utiles ;

• etc.

Pour que le travail de babel soit efficace, il doit être appelé après les autres packages dont il modifie le comportement, mais avant les packages qui en ont besoin. Dans ce cas précis, on appelle babel toujours en dernier, car aucun package ou presque n'en dépend. C'est d'ailleurs communément admis, si bien que seuls les packages qui en ont besoin le mentionnent dans leur documentation (c'est par exemple le cas de microtype).

Appelez les packages concernant les encodages en tout premier, et babel en tout dernier.

Dans l'idéal, n'appelez que les packages dont vous avez besoin. Inutile de surcharger le préambule de packages inutiles. Par exemple, si vous ne voulez pas de couleur, n'incluez pas xcolor. Évitez également de commenter l'appel des packages que vous n'utilisez pas : supprimez plutôt la commande \usepackage pour que votre code soit plus lisible.

Ayez un code clair

Aéréz votre code. Vous vous y retrouverez plus facilement et ceux qui le liront aussi. Sautez des lignes autour des commandes de sectionnement et des figures ; ne surchargez pas les lignes.

Vous devriez commenter votre code, surtout dans le préambule. Écrivez quelques mots ou phrases pour expliquer ce que font vos commandes personnalisées. Cela facilitera la compréhension lorsque vous devrez y revenir.

Un modèle de départ

Le code ci-dessous est une bonne base. Le premier exemple est valable pour pdfLaTeX et le suivant pour XeLaTeX et LuaLaTeX.

\documentclass[ (options) ]{ (classe) } \usepackage[utf8]{inputenc} \useackage[T1]{fontenc} % Autres packages nécessaires. \usepackage[french]{babel} % Commandes personnalisées. \title{ (titre) } \author{ (auteur) } \date{ (date) } \begin{document} \maketitle \end{document}\documentclass[ (options) ]{ (classe) } \usepackage{fontspec} % Autres packages nécessaires. \usepackage[french]{babel} % Commandes personnalisées. \title{ (titre) } \author{ (auteur) } \date{ (date) } \begin{document} \maketitle \end{document}Trouver et lire la documentation des packages

Les cours que vous trouverez ne présenteront jamais tout ce qu'il est possible de faire avec un packages, et il n'y a d'ailleurs pas de tutoriel pour tous les packages. Le seul endroit où trouver ce qu'il peut faire et comment le faire est sa documentations. Lorsque vous commencez à être à l'aise avec LaTeX, vous devez avoir le réflexe d'aller la lire. Il n'est par contre pas toujours nécessaire de la lire en détail (surtout lorsqu'elle fait plusieurs centaines de pages — et dans tous les cas la lecture du code source commenté n'apporte souvent rien de plus) : il y a souvent une partie pour débuter, ou alors il est assez simple de trouver la partie qui vous intéresse à l'aide de la table des matières ou de l'index.

Pour trouver les documentations, rendez-vous sur le site du CTAN. Là, vous pouvez effectuer une recherche sur le nom du package qui vous intéresse et accéder aux fichiers qui le composent. Un fichier PDF de documentation est systématiquement présent.

Notez que toutes les documentations sont en anglais. Que cela vous plaise ou non, il est nécessaire de connaître un minimum l'anglais pour utiliser correctement LaTeX.

Demander de l'aide sur les forums

Sur un forum, ceux qui vous aident ne vous connaissent pas, ne savent pas a priori ce que vous voulez faire, quelle est votre configuration et ne peuvent pas deviner. Plus encore : il ne le veulent pas. Il est impératif de se poser les bonnes questions, de donner le maximum d'informations utiles et de respecter les autres afin d'obtenir de l'aide. Vous devez donc impérativement suivre ces quelques recommandations.

Il est également recommandé de lire le texte intitulé De la bonne manière de poser des questions qui, bien que vieillissant, est tout à fait valable aujourd'hui.

Règle no. 0. — Cherchez par vous-même

Il n'y a rien de plus énervant que de voir un sujet dont le problème aurait été résolu par une simple recherche. Avant de demander de l'aide, utilisez un moteur de recherche et tapez votre message d'erreur ou quelques mots clés (comme le nom du package, et l'anglais vous aidera plus que le français). Souvent, c'est le simple fait de formuler votre question qui vous aidera à en trouver la réponse.

Si votre problème concerne un package, n'oubliez pas de parcourir la documentation. La réponse s'y trouve certainement.

Règle no. 1. — Soyez poli et écrivez correctement

Les gens à qui vous vous adressez sont comme vous et ne sont en rien tenus de vous aider, ni même de vous lire. Lorsque vous créez un sujet, assurez-vous de dire bonjour, d'être poli et d'écrire dans un français correct. Respectez les usages du forum sur lequel vous postez. Vous n'écrivez pas pour vous, mais pour les autres.

Écrivez ceci :

Bonjour,

J'ai un problème de compilation avec le package X. Le compilateur indique que Y n'est pas Z, alors que c'est bien le cas.

Merci pour votre aide.

...plutôt que ceci :

X sa marche ps

Pensez également à choisir un titre explicite, par exemple :

[XeLaTeX] Police pour les symboles mathématiques

À ne pas faire :

Problème à la compilation

Règle no. 2. — Décrivez précisément votre objectif

Il est impératif de décrire ce que vous voulez faire. J'entends par là qu'il ne faut pas se contenter de décrire ce que vous faites (par exemple forcer deux paragraphes à rester sur la même page), mais vous devez dire pourquoi vous le faites (ici pour ajouter une légende à une image). En effet, votre solution n'est pas forcément la meilleure et pourrait être améliorée.

Règle no. 3. — Présentez un exemple complet minimal (ECM)

Dans tous les cas, postez votre code. Mais poster son code ne suffit pas : il contient des éléments inutiles qui doivent être enlevez pour mieux vous aider. C'est pourquoi votre code doit être minimal. Il doit aussi être complet : le problème doit se reproduire. C'est aussi un exemple : vous n'êtes pas obligé de poster le vrai texte si le problème n'y est pas lié. Vous pouvez générer du faux texte avec le package lipsum.

Si vous ne postez pas d'ECM, ceux qui daigneront vous répondre le feront pour vous le demander.

Règle no. 4. — Rédigez de façon claire

Structurez correctement votre message. Commencez par expliquer ce que vous êtes en train de faire et pourquoi. Ensuite, présentez votre ECM. Décrivez alors le résultat obtenu (message d'erreurs, captures d'écran, etc.) et le résultat attendu. Enfin, présentez le résultat de vos recherches à propos de ce problème en expliquant pourquoi cela ne vous a pas aidé.

Voici un exemple de bon post :

Bonjour,

J'ai un problème avec le package mathspec. J'utilise la police Linux Libertine avec fontspec, mais ele ne s'applique pas aux mathématiques. J'ai trouvé le package mathspec, qui semble l'équivalent ed fontspec pour le mode maths, mais même si maintenant j'ai bien du Linux Libertine partout, les symboles mathématiques (somme, intégrales, etc.) restent dans la police par défaut, or j'aimerait bien utiliser leurs versions Libertine.

Voici ce que j'ai fait :

\documentclass{article} \usepackage{fontspec} \usepackage{mathspec} \usepackage[french]{babel} \setmainfont{Linux Libertine O} \setmathfont{Linux Libertine O} \begin{document} Du texte normal \[1+1=\sum_{i=0}^{i=2}1=\frac{4}{2}\rightarrow 2\] \end{document}

Tous les symboles qui ne sont pas des chiffres ou du texte sont ceux par défaut, alors qu'ils devraient correspondre mieux à la police que j'ai choisie.

Je me suis renseigné, et je pense que ce serait parce que Linux Libertine ne contient pas de symboles mathématiques. J'ai également lu qu'il existe une police commerciale (Minion Pro) qui n'en a pas non plus, mais un package a été écrit (mnsymbol) pour lui en donner. Est-ce qu'il en existe un pour Linux Libertine, ou y a-t-il une autre solution ?

Merci pour votre aide.

Règle no. 5. — Postez au bon endroit

Pour que votre demande d'aide aboutisse, choisissez convenablement l'endroit où vous postez votre sujet. Même si les modérateurs peuvent déplacer votre sujet après coup, prenez quelques secondes pour être sûr.

Règle no. 6 — Remerciez les intervenants vous ayant aidé et informez-les de la résolution

Les auteurs des réponses vous ayant aidé doivent être remerciés et informés que votre problème est résolu. Écrivez alors un dernier message dans le fil de discussion, utilisez la fonctionnalité pour passer le sujet en résolu et pour « plussoyer » les bonnes réponses.

• #

Waouh !

Très heureux de voir que nos cours vous plaisent, déjà 3 pages lues aujourd'hui ! Vous pouvez continuer la lecture de nos cours en devenant un Roomie, un membre de la communauté d'OpenClassrooms. C'est gratuit !

Vous pourrez aussi suivre votre avancement dans le cours, faire les exercices et discuter avec les autres Roomies.

S'inscrire Se connecter

• Thématiques du cours : LaTeX

Chaque cours est créé par un professeur ou un expert dans le domaine. Il est composé d'une ou plusieurs parties et peut comporter du texte, des images (schéma, illustration) et des vidéos. Chaque partie d'un cours certifiant est ponctuée d'exercices de 2 types : Des quiz corrigés automatiquement Des devoirs libres (exemple : créer un site web avec des consignes précises). Ces devoirs sont évalués par les pairs. Chaque devoir est corrigé 3 fois par 3 autres élèves, dans un processus en double aveugle, selon un barème fixé par le professeur. La note finale est la moyenne des 3 notes reçues sur le devoir. 50% des devoirs corrigés par les pairs obtiennent quasiment les 3 mêmes notes, avec une variance inférieure à 1. La recherche académique montre d'ailleurs que l'évaluation par les pairs peut être aussi précise que celle des professeurs.