La structure du document : synthèse et défis

Résumé

Cette leçon clôt la troisième unité du cours, consacrée à la structure du document. Elle reconstruit la chaîne de décisions et de mécanismes qui va de la classe du document au préambule personnel, en indiquant pour chaque maillon quel principe il met en œuvre et dans quelle leçon celui-ci est établi ; elle situe l’acquis par rapport au plan du cours et précise quelles questions, à peine esquissées, restent pour les unités suivantes ; elle reprend dans son évaluation de sortie les compétences de l’évaluation d’entrée ; et elle se termine par six défis, plus difficiles que les problèmes des leçons, qui exigent d’en combiner plusieurs pour planifier une thèse à partir de ses normes, prévoir la numérotation et les renvois d’un livre et diagnostiquer des documents divisés qui échouent ou qui mentent.

Objectifs d’apprentissage

Reconstruire l’ordre des décisions et des mécanismes de l’unité, en identifiant le principe sur lequel chacun s’appuie.
Expliquer comment la numérotation, la table des matières, les renvois et la compilation partielle dépendent des fichiers auxiliaires.
Distinguer ce que l’unité a établi de ce qu’elle n’a fait qu’esquisser et que les unités suivantes développeront.
Diagnostiquer des documents divisés en plusieurs fichiers qui échouent, ou qui se compilent avec des numéros faux, en ordonnant les corrections.
Planifier la classe, la page, les parties, les renvois et les fichiers d’une thèse à partir des normes qu’elle doit respecter.

L’acquis de l’unité

L’unité se proposait de donner au document une architecture dont les numéros, la table des matières et les renvois restent vrais à travers toutes ses modifications. Le but a été atteint en s’appuyant sur ce que l’introduction tenait pour acquis des unités précédentes : les passes de la compilation, la division entre préambule et corps, et le balisage logique. Dès lors, le chemin parcouru peut se lire comme une seule chaîne en cinq tronçons.

Classes de document et mise en page

La leçon sur les classes de document et la mise en page a établi que la classe décide quelles divisions existent, ce que fait \maketitle, s’il y a un résumé et si les pages paires se distinguent des impaires ; elle en a tiré un critère pour choisir entre article, report et book selon la structure et l’impression, et elle a présenté les classes KOMA-Script, avec l’option es-noquoting qu’exige leur association avec l’espagnol dans la version de TeX Live de ces exemples. Elle a passé en revue les options de classe, expliqué pourquoi les marges dépendent de la longueur de la ligne et comment les fixer avec geometry, et s’est terminée par les styles de page, que certaines commandes de la classe imposent d’elles-mêmes.

Sections, table des matières et annexes

La leçon sur les sections, la table des matières et les annexes a composé les données du titre et le résumé, ordonné les niveaux de division et établi que deux compteurs indépendants, secnumdepth et tocdepth, décident de ce qui est numéroté et de ce qui entre dans la table des matières. Elle a expliqué que la table des matières se compose avec ce que la passe précédente a inscrit, sans avertissement lorsqu’elle n’est plus à jour ; que \appendix change la numérotation de ce qui la suit ; et qu’un livre a trois parties, avec deux numérotations de pages, dont l’ordre n’est pas indifférent.

Renvois

La leçon sur les renvois a établi le principe dont dépend tout renvoi : une étiquette enregistre le dernier numéro attribué avant elle, dans son environnement. Elle en a déduit où se place l’étiquette dans chaque élément, pourquoi une étiquette placée avant la légende d’une figure renvoie à la section et pourquoi une section non numérotée n’a pas de numéro propre auquel renvoyer. Elle a montré qu’après une modification une seule compilation imprime les numéros précédents avec toutes les apparences de l’exactitude, et elle a présenté hyperref, qui doit être chargée à la fin des extensions, et cleveref, qui vient après elle et dont le nom « équation » exige l’élision de l’article.

Documents longs

La leçon sur les documents longs a réparti un document entre un fichier principal et des pièces sans préambule. Elle a distingué \input, une substitution littérale, de \include, qui ouvre une page, écrit un fichier auxiliaire propre et admet \includeonly, dont la numérotation dépend des fichiers auxiliaires d’une compilation complète antérieure. Elle a établi que les chemins s’écrivent depuis le dossier du fichier principal, que dans Texmaker on déclare le document maître, et elle a passé en revue les erreurs propres aux documents divisés, dont deux silencieuses : la pièce introuvable avec \include et la pièce munie d’un préambule, dont le \end{document} termine la thèse.

Macros et préambule personnel

La leçon sur les macros et le préambule personnel a fait du balisage logique une méthode : \newcommand avec des arguments et avec un argument optionnel, la protection qui empêche de redéfinir un nom déjà pris, l’espace perdue après une commande sans argument, \NewDocumentCommand, les environnements personnels, dont les arguments n’existent qu’à l’ouverture, et le préambule déplacé dans un fichier ou dans une extension, qui ne doit imposer ni la classe, ni la langue, ni la position d’hyperref.

La figure suivante réunit les cinq tronçons en une seule chaîne. Chaque nœud de la colonne est une décision ou un mécanisme, numéroté selon l’ordre dans lequel ils s’appuient les uns sur les autres et relié par un arc aux maillons antérieurs qu’il utilise ; autour flottent les appuis, c’est-à-dire les principes auxquels la chaîne recourt sans cesse, chacun relié par un trait plein aux maillons qui s’appuient sur lui et par un pointillé au maillon où il est établi, sauf ceux qui ont été établis dans des unités antérieures, dessinés comme des anneaux. Un clic sur un appui met en évidence tous les maillons qui l’utilisent, et chaque maillon renvoie à la leçon où il est étudié.

Appuis de la chaîne

APasses. Le moteur inscrit dans les fichiers auxiliaires les numéros, les titres et les pages lors d’une passe, et les utilise lors de la suivante. Établi dans la première unité. Admis sans démonstration dans cette unité.
BPréambule et corps. Le préambule configure et charge les extensions, et le corps compose ; ce qui ne fait que définir ou mémoriser peut aller dans l’un ou l’autre. Établi dans la première unité. Admis sans démonstration dans cette unité.
CFond et forme. L’auteur déclare ce qu’est chaque chose, et une décision prise ailleurs fixe son aspect. Établi dans les unités précédentes. Admis sans démonstration dans cette unité.
DLa classe décide. La classe du document décide quelles divisions existent, ce qui compose le titre, s’il y a un résumé, comment les pages se répartissent et quel style imposent ses commandes. Établi dans: 1. Trois classes standard.
ECe qu’enregistre une étiquette. Une étiquette enregistre le dernier numéro attribué avant elle, dans son environnement, sans savoir à quoi elle est attachée. Établi dans: 11. Étiquettes et renvois.
FOrdre de chargement. Les extensions se chargent dans l’ordre où elles sont lues, et une extension postérieure peut défaire ce qu’avait fait une extension antérieure : hyperref vient à la fin, et cleveref après elle. Établi dans: 13. Liens.
GLe fichier principal. On compile toujours le fichier principal ; les pièces sont des fragments de son corps, sans préambule, et leurs chemins s’écrivent depuis le dossier du principal. Établi dans: 16. La commande include.

Tronçon 1 Classes de document et mise en page
- Choisir la classe selon la structure et l’impression du document.
- Déclarer les options de classe et prévoir leur effet.
- Fixer les marges avec geometry sans trop allonger la ligne.
- Prévoir et changer les styles de page, les en-têtes et les pieds de page.
1. Trois classes standard. article n’a pas de chapitres ; report en a, avec titre et résumé sur des pages à part ; book imprime en recto verso et n’a pas de résumé.
  Repose sur: B (Préambule et corps). Démontré dans: Classes de document et mise en page.
2. KOMA-Script. scrartcl, scrreprt et scrbook correspondent aux classes standard avec des choix européens ; avec babel en espagnol, elles exigent, dans cette version, l’option es-noquoting.
  Utilise: 1. Trois classes standard. Repose sur: C (Fond et forme). Démontré dans: Classes de document et mise en page.
3. Options de classe. Papier, corps du texte, recto ou recto verso, page de titre, début des chapitres et mode brouillon se déclarent dans la première ligne.
  Utilise: 1. Trois classes standard. Repose sur: D (La classe décide). Démontré dans: Classes de document et mise en page.
4. Marges. geometry calcule la page à partir de quelques mesures ; la largeur de la zone de texte fixe la longueur de la ligne, qui est ce que subit le lecteur.
  Utilise: 3. Options de classe. Repose sur: B (Préambule et corps). Démontré dans: Classes de document et mise en page.
5. Styles de page. Le style décide des en-têtes et des pieds de page ; \maketitle et \chapter imposent le style plain à leur page, et fancyhdr ou scrlayer-scrpage composent des styles personnels.
  Utilise: 1. Trois classes standard, 4. Marges. Repose sur: D (La classe décide). Démontré dans: Classes de document et mise en page.
Tronçon 2 Sections, table des matières et annexes
- Composer le titre et le résumé selon la classe.
- Choisir le niveau de division et prévoir la numérotation et la table des matières.
- Produire la table des matières et les listes, en sachant de quelle passe elles dépendent.
- Ordonner les annexes et les parties d’un livre.
1. Titre et résumé. \title, \author et \date mémorisent, \maketitle compose ; l’environnement abstract existe dans article et report, non dans book.
  Utilise: 1. Trois classes standard. Repose sur: D (La classe décide), B (Préambule et corps). Démontré dans: Sections, table des matières et annexes.
2. Niveaux de division. Sept niveaux, de la partie au sous-paragraphe ; le chapitre n’existe que dans report et book, et la hiérarchie ne se choisit pas d’après la taille du titre.
  Utilise: 1. Trois classes standard. Repose sur: D (La classe décide). Démontré dans: Sections, table des matières et annexes.
3. Numérotation et table. secnumdepth décide quels niveaux sont numérotés et tocdepth lesquels entrent dans la table des matières ; la forme étoilée ne numérote pas et ne consomme pas de numéro.
  Utilise: 7. Niveaux de division. Repose sur: C (Fond et forme). Démontré dans: Sections, table des matières et annexes.
4. Table des matières et listes. La table des matières compose ce que la passe précédente a inscrit dans le fichier .toc, et ne prévient pas lorsqu’elle n’est plus à jour.
  Utilise: 7. Niveaux de division, 8. Numérotation et table. Repose sur: A (Passes). Démontré dans: Sections, table des matières et annexes.
5. Annexes et parties du livre. \appendix change la numérotation de ce qui suit ; dans book, les pages liminaires, le corps de l’ouvrage et les pages finales ont deux numérotations, et les annexes viennent avant \backmatter.
  Utilise: 7. Niveaux de division, 5. Styles de page. Repose sur: D (La classe décide). Démontré dans: Sections, table des matières et annexes.
Tronçon 3 Renvois
- Placer et nommer les étiquettes.
- Prévoir ce qu’imprime un renvoi après une ou deux passes.
- Charger hyperref et cleveref dans leur ordre.
- Renvoyer avec le nom et le numéro, ou avec le titre.
1. Étiquettes et renvois. \label marque un lieu, \ref et \pageref en écrivent le numéro et la page, en deux passes.
  Utilise: 7. Niveaux de division. Repose sur: A (Passes). Démontré dans: Renvois.
2. Où va l’étiquette. Après la commande qui attribue le numéro et dans le même environnement : après \section, après \caption ; avec un préfixe qui dise ce qu’elle désigne.
  Utilise: 11. Étiquettes et renvois. Repose sur: E (Ce qu’enregistre une étiquette). Démontré dans: Renvois.
3. Liens. hyperref transforme les renvois, la table des matières et les notes en liens et les sections en signets, et se charge à la fin des extensions.
  Utilise: 11. Étiquettes et renvois, 9. Table des matières et listes. Repose sur: B (Préambule et corps). Démontré dans: Renvois.
4. Renvois nommés. cleveref écrit le nom et le numéro, en français « section », « figure », « équation », ce dernier avec l’élision de l’article, réglables avec \crefname ; nameref renvoie par le titre.
  Utilise: 13. Liens, 12. Où va l’étiquette. Repose sur: E (Ce qu’enregistre une étiquette), F (Ordre de chargement). Démontré dans: Renvois.
Tronçon 4 Documents longs
- Choisir entre \input et \include pour chaque pièce.
- Prévoir ce que conserve \includeonly.
- Organiser les dossiers et déclarer le document maître.
- Reconnaître les erreurs, bruyantes et silencieuses, des documents divisés.
1. La commande input. \input insère un fichier comme si son texte était écrit à sa place, sans couper la page ni créer de fichiers auxiliaires.
  Repose sur: B (Préambule et corps). Démontré dans: Documents longs.
2. La commande include. \include ouvre une page avant et après, écrit un fichier auxiliaire propre par pièce et ne peut pas s’imbriquer.
  Utilise: 15. La commande input, 7. Niveaux de division. Repose sur: A (Passes). Démontré dans: Documents longs.
3. Compilation partielle. \includeonly ne compose que les pièces choisies et numérote les autres avec leurs fichiers auxiliaires, qui doivent provenir d’une compilation complète postérieure à leur dernière modification.
  Utilise: 16. La commande include, 11. Étiquettes et renvois. Repose sur: A (Passes). Démontré dans: Documents longs.
4. Dossiers et document maître. Un fichier principal à la racine, des pièces dans des dossiers, des chemins depuis le principal, des noms simples, et dans Texmaker le principal comme document maître.
  Utilise: 16. La commande include. Repose sur: G (Le fichier principal). Démontré dans: Documents longs.
5. Erreurs des documents divisés. Un \input sans fichier arrête la compilation ; un \include sans fichier inscrit seulement « No file » ; une pièce munie d’un préambule termine la thèse à son \end{document}.
  Utilise: 16. La commande include, 18. Dossiers et document maître. Repose sur: G (Le fichier principal), B (Préambule et corps). Démontré dans: Documents longs.
Tronçon 5 Macros et préambule personnel
- Définir des commandes avec des arguments et un argument optionnel.
- Distinguer définir, redéfinir et fournir, et éviter l’espace perdue.
- Définir des environnements personnels.
- Réunir le préambule dans un fichier ou dans une extension.
1. Commandes personnelles. \newcommand définit une commande à neuf arguments au plus, le premier optionnel avec sa valeur par défaut ; elle nomme une fonction qui revient.
  Repose sur: C (Fond et forme). Démontré dans: Macros et préambule personnel.
2. Noms pris et espaces. \newcommand refuse un nom existant et \renewcommand un nom inexistant ; une commande sans argument absorbe l’espace qui la suit.
  Utilise: 20. Commandes personnelles. Repose sur: B (Préambule et corps). Démontré dans: Macros et préambule personnel.
3. Environnements personnels. \newenvironment définit l’ouverture et la fermeture ; ses arguments n’existent qu’à l’ouverture, et \NewDocumentEnvironment les admet aussi à la fermeture.
  Utilise: 20. Commandes personnelles. Repose sur: C (Fond et forme). Démontré dans: Macros et préambule personnel.
4. Préambule personnel. Le préambule se déplace dans un fichier lu avec \input ou dans une extension .sty, qui n’impose ni la classe, ni la langue, ni la position d’hyperref.
  Utilise: 20. Commandes personnelles, 21. Noms pris et espaces, 15. La commande input, 13. Liens. Repose sur: F (Ordre de chargement), C (Fond et forme). Démontré dans: Macros et préambule personnel.

Vers les mathématiques. La chaîne s’arrête là où l’architecture est complète et reste à remplir : les équations et les théorèmes numérotés, auxquels on renverra avec les étiquettes de cette unité, sont l’objet de la suivante.