Premiers pas : introduction

Résumé

Cette leçon ouvre la première unité du cours, consacrée aux premiers pas avec LaTeX. Elle explique à quoi sert l’unité : amener quiconque n’a jamais utilisé LaTeX au point d’écrire, de compiler et de corriger seul un document bref ; elle présente ses quatre leçons et le fil qui les relie, de l’idée de composition typographique jusqu’à la lecture des erreurs ; elle précise le peu qui est tenu pour acquis, à savoir la manipulation des fichiers et des dossiers sur un ordinateur ; elle formule le problème que l’unité résout, celui de passer d’un fichier vide à un document composé et, lorsque quelque chose échoue, du message du moteur à sa cause ; et elle montre que ce même cycle sert aussi bien un compte rendu de travaux pratiques qu’une dissertation de philosophie ou l’édition d’un texte latin.

Objectifs d’apprentissage

Décrire la progression des contenus de l’unité et expliquer ce que chaque leçon apporte à la suivante.
Reconnaître les connaissances préalables que l’unité suppose et préparer l’ordinateur en conséquence, en particulier l’affichage des extensions de fichiers.
Expliquer, sur un exemple, pourquoi un document LaTeX peut ne produire aucun résultat et pourquoi l’erreur n’est pas toujours signalée là où elle se trouve.
Reconnaître, dans d’autres disciplines et dans les unités suivantes, le cycle écrire, compiler, corriger que l’unité construit.

Évaluation d’entrée

Avant de parcourir l’unité, il convient de mesurer le point de départ. Cette évaluation est une autoévaluation : elle n’est pas notée, et son seul but est d’orienter l’étude. Ses huit questions portent, deux par deux et dans l’ordre, sur les quatre leçons de l’unité ; qui n’a jamais utilisé LaTeX ne doit pas s’attendre à y répondre juste, et cela n’a pas d’importance : chaque réponse, juste ou non, explique le point et indique la leçon qui le traite. Les mêmes compétences sont de nouveau mesurées à la fin, dans la leçon de synthèse ; comme il s’agit de la première unité du cours, il n’y a pas de questions sur des unités antérieures.

Les contenus de l’unité

Cette unité sert le premier des objectifs du cours, produire et compiler des documents en diagnostiquant et en corrigeant leurs erreurs, et elle est la condition de tous les autres : composer des textes en plusieurs langues et écritures, structurer des documents longs, écrire des mathématiques et de la logique, présenter des tableaux et des figures, gérer la bibliographie et choisir la classe adaptée à chaque genre académique supposent que le cycle écrire, compiler, corriger ne présente plus de difficulté. Son but est que quiconque n’a jamais utilisé LaTeX puisse, au terme de l’unité, écrire un document bref à partir d’un fichier vide, le compiler avec LuaLaTeX dans Texmaker ou sur Overleaf et, lorsqu’il ne compile pas, trouver et corriger la cause seul. Ses quatre leçons forment une chaîne dans laquelle chacune s’appuie sur les précédentes.

Ce qu’est LaTeX. Elle explique la composition typographique, compare le langage de balisage au traitement de texte, raconte l’origine de TeX et de LaTeX et leur principe de séparer le fond de la forme, justifie le choix de LuaLaTeX et montre comment un source devient un PDF. Elle fixe le vocabulaire de toute l’unité : source, moteur, compilation, préambule, corps et journal.
L’environnement de travail. Elle installe ce que la première leçon a décrit : une distribution TeX, avec son gestionnaire de paquets, et l’éditeur Texmaker, configuré pour compiler avec LuaLaTeX et enregistrer en UTF-8 ; elle présente Overleaf comme solution de rechange dans le navigateur et explique quels fichiers la compilation laisse derrière elle et lesquels on conserve. Elle se termine par deux documents d’essai qui vérifient l’installation.
Anatomie d’un document. Elle décompose le source en ses pièces : le préambule et le corps, les commandes et leurs arguments, les groupes qui limitent la portée des déclarations, les environnements, les dix caractères réservés, les commentaires, les extensions et la classe. Grâce à elle, le document minimal de la première leçon cesse d’être une recette et devient une structure que l’on comprend pièce par pièce.
Compiler et corriger les erreurs. Elle apprend à lire le journal : distinguer les erreurs des avertissements, situer chaque erreur dans le source, reconnaître les messages les plus fréquents et isoler la cause quand le message ne suffit pas. Elle rassemble ce qui précède, car presque toute erreur est l’infraction à une règle de l’anatomie du source, et son diagnostic s’appuie sur l’environnement de travail.

L’unité se termine par la leçon de synthèse et défis, qui réunit les acquis en une chaîne de concepts et de procédures, reprend dans son évaluation de sortie les compétences de l’évaluation d’entrée et propose des défis qui combinent plusieurs leçons.

Ce qui est tenu pour acquis

L’unité part de presque rien. Elle ne suppose pas d’avoir utilisé LaTeX, ni de savoir programmer, ni de connaissances en mathématiques ; elle ne suppose pas non plus de savoir l’anglais, bien que les messages du moteur soient dans cette langue, car le cours explique chacun de ceux qu’il présente. Elle suppose seulement l’usage courant d’un ordinateur : créer un dossier, enregistrer un fichier sous un nom donné et dans un dossier donné, le retrouver ensuite, copier, déplacer et supprimer des fichiers, et installer un programme, ou bien disposer d’un navigateur et d’un compte Overleaf.

Il en découle une seule préparation préalable, qu’il convient de faire avant la leçon sur l’environnement de travail. Un nom de fichier se compose d’une base et d’une extension, la partie qui suit le dernier point : dans rapport.tex, la base est rapport et l’extension, tex. Or l’Explorateur de fichiers de Windows et le Finder de macOS masquent par défaut les extensions connues, de sorte que rapport.tex et rapport.pdf apparaissent tous deux comme rapport, et les fichiers auxiliaires de la compilation, qui ne se distinguent que par leur extension, deviennent impossibles à distinguer. Par conséquent, il convient d’activer l’option qui affiche les extensions : sous Windows, dans le menu Affichage de l’Explorateur de fichiers ; sous macOS, dans les réglages avancés du Finder. Sous Linux, les gestionnaires de fichiers les affichent par défaut.

Le problème que l’unité résout

Qui écrit dans un traitement de texte voit le résultat à mesure qu’il écrit. Dans LaTeX, entre le source et la page se trouve un programme qui lit le source au pied de la lettre, et le résultat n’apparaît qu’à la compilation. Cela pose deux problèmes, qui sont ceux de l’unité. Le premier est de savoir comment on passe d’un fichier vide à un document composé : ce qu’il faut installer, ce que le source doit contenir au minimum et ce que le moteur en fait. Le second est de savoir que faire lorsque le document ne sort pas, ou sort autrement qu’on ne le voulait : le moteur ne montre pas l’erreur sur la page, il la décrit dans le journal, dans un langage qui lui est propre, et la signale parfois loin de l’endroit où elle a été commise. L’exemple suivant montre les deux problèmes dans un document de quinze lignes.

ExempleUne accolade qui manque

Le source suivant est un document complet : il déclare la classe, charge les extensions, mémorise le titre, l’auteur et une date vide, et compose deux sections. Compilé avec LuaLaTeX, il produit ce résultat.

Si, à la onzième ligne, on omet l’accolade qui ferme l’argument de \emph, le moteur ne produit aucun PDF, et le journal contient, entre autres, ces lignes.

Journal de compilation

Runaway argument?{hypothèse portant sur 40~\% des cas. \par \section {La réponse} La\ETC.! File ended while scanning use of \emph ....!  ==> Fatal error occurred, no output PDF file produced!

L’erreur n’est pas signalée à la onzième ligne, mais à la fin du fichier : le moteur a continué à lire l’argument de \emph à travers le paragraphe, la section suivante et \end{document}, jusqu’à ce que le fichier s’achève. Or le journal donne l’indice qui manque : la ligne qui suit « Runaway argument? » reproduit l’argument emballé depuis son début, et ce début, l’accolade qui précède « hypothèse », est exactement l’endroit de l’erreur. Lire ainsi le journal, c’est ce qu’enseigne la leçon sur la compilation et la correction des erreurs ; comprendre pourquoi une accolade non fermée entraîne tout ce qui suit, c’est ce qu’enseigne celle sur l’anatomie d’un document.

La réponse de l’unité à ces deux problèmes comporte donc deux parties. Pour le premier, un environnement installé et éprouvé, et un source dont la structure se comprend pièce par pièce, de sorte que rien n’y est une formule magique. Pour le second, une méthode : lire le journal à partir de la première erreur, situer l’erreur dans le source, reconnaître la règle enfreinte et, si le message ne suffit pas, isoler la cause en désactivant des parties du source. Aucune des deux parties n’exige de mémoriser des commandes ; toutes deux exigent de lire le source comme le moteur le lit.

L’unité dans les disciplines

Le cycle que l’unité enseigne est le même dans toutes les disciplines, et ce qui change de l’une à l’autre est seulement ce que l’on écrit. Un compte rendu de travaux pratiques de chimie, une dissertation de philosophie avec une centaine de notes de bas de page, un commentaire d’un passage de Cicéron avec le texte latin et sa traduction, un travail d’économie avec des tableaux, une thèse d’histoire avec des documents d’archives et un article de mathématiques avec des théorèmes commencent de la même façon : un dossier, un fichier source avec son préambule et son corps, une compilation et la lecture de son journal. De même, les erreurs de cette unité, une accolade non fermée, un caractère réservé écrit tel quel, une extension chargée hors de sa place, apparaissent dans n’importe lequel de ces documents, quelle que soit la discipline.

C’est pourquoi ce que l’unité enseigne sert dans les autres cours du site. Les travaux et les notes de Logique aristotélicienne ou de Fondements de la mécanique peuvent s’écrire en LaTeX dès la première semaine ; en Analyse de données avec R, les résultats d’une analyse s’intègrent à un document composé ; et en Programmation en C++ I, le cycle est pour l’essentiel le même : on écrit un source, un compilateur le lit, et ses messages, qui renvoient à des numéros de ligne, se lisent avec la méthode que cette unité enseigne.

Où elle mène

Au terme de l’unité, le document minimal sera un point de départ connu, et les unités suivantes bâtiront sur lui. La deuxième traitera du texte lui-même : les langues et les écritures, parmi lesquelles le grec et le latin, les polices, les notes de bas de page et les longues citations. La troisième, de la structure des documents longs, avec leurs chapitres, leur table des matières et leurs renvois internes, répartis en plusieurs fichiers. La quatrième, de l’écriture des mathématiques et de la logique dans leur notation correcte ; la cinquième, des tableaux et des figures ; la sixième, de la bibliographie et des conventions de citation de chaque discipline ; et la septième, des classes de document adaptées à chaque genre académique, des présentations aux lettres et aux posters. Dans toutes, chaque nouvelle commande sera écrite, compilée et, lorsqu’elle échouera, corrigée avec ce qui aura été appris dans celle-ci.