YuShenLiu06/yushen-skills

latex-pdf — Guide professionnel de composition LaTeX PDF

L'objectif n'est pas de « pouvoir compiler », mais que le lecteur, en prenant le PDF, le trouve professionnel. La livraison se base sur le contenu et la page réelle ; une compilation réussie ne prouve que l'achèvement de la compilation, elle ne remplace pas la validation visuelle.

Table des matières

1. Principes fondamentaux
2. Choix du moteur
3. Stratégie de compilation
4. Principes de typographie pour la lisibilité
5. Flux de travail
6. Aide-mémoire des problèmes courants

---

Principes fondamentaux

La composition suit deux objectifs de vérification, sans dépendre d'une autre compétence pour fonctionner :

① La composition sert la lecture — Chaque décision de composition répond à la question « Cela aide-t-il le lecteur à mieux comprendre ? ». Si la suppression d'un paramètre ne modifie pas l'expérience de lecture, il n'a pas lieu d'être.

② La retenue est professionnelle — Supprimez tous les éléments visuels qui ne transmettent pas d'information. Lignes décoratives, fonds, cadres colorés — la plupart doivent être supprimés. Une composition professionnelle « semble facile », tandis qu'une composition amateur « a l'air de beaucoup d'efforts, mais est désordonnée ».

La cartographie détaillée des principes de lisibilité se trouve dans readability-principles.

---

Choix du moteur

Choisir le mauvais moteur est l'erreur la plus courante, surtout pour le contenu chinois avec pdflatex.

Du chinois/japonais/coréen ?
├─ Oui → xelatex (+ package ctex)
│        (lualatex fonctionne aussi, mais compile plus lentement)
└─ Non → Police système nécessaire ?
         ├─ Oui → xelatex ou lualatex (+ fontspec)
         └─ Non → pdflatex (le plus rapide, le plus compatible)

Pour les nouveaux documents CJK, privilégiez XeLaTeX ou LuaLaTeX, et vérifiez la prise en charge réelle des polices. Ne remplacez pas sans raison un modèle pdfLaTeX/CJK existant et fonctionnel ; fandol n'est pas adapté au chemin pdfLaTeX standard.

Moteur	Avantages	Inconvénients	Cas d'usage
pdflatex	Le plus rapide, le plus stable, le plus vaste écosystème	Ne supporte pas Unicode nativement, ne peut pas utiliser les polices système	Documents en anglais uniquement
xelatex	Unicode natif, polices système, compatible CJK	Plus lent	Choix par défaut pour les documents chinois
lualatex	Le traitement de polices le plus puissant, peut embarquer Lua	Le plus lent	Nécessite des fonctionnalités avancées de composition

---

Stratégie de compilation

Vérifier d'abord la source et les limites d'exécution

Avant la compilation, vérifiez statiquement le .tex, les fichiers .sty/.cls inclus, la configuration de construction et les chemins des pièces jointes. Soyez attentif à la capacité d'exécution des lectures/écritures de fichiers, des commandes externes et de Lua. La vérification statique ne constitue pas une preuve de sécurité. Pour les projets non fiables, utilisez un environnement isolé sans fichiers privés, sans réseau, et avec des restrictions d'écriture, de temps d'exécution et de ressources ; en l'absence d'isolation adéquate, arrêtez la compilation et signalez-le, ne l'exécutez pas dans votre environnement personnel.

Désactivez shell-escape par défaut, ne l'activez pas automatiquement pour minted ou l'externalisation graphique. Lors de l'exécution de latexmk, utilisez -norc pour éviter de charger automatiquement les rc système, utilisateur ou projet ; examinez séparément les autres scripts de construction et programmes d'assistance externes. L'installation, la connexion réseau pour récupérer des paquets, ou la modification de l'environnement doivent être effectuées dans le cadre d'une autorisation préexistante ; si non couvert, obtenez d'abord une approbation.

Réutiliser une chaîne de compilation adaptée

Pour un projet existant, utilisez la méthode de construction applicable ; lorsque plusieurs passages de compilation et la bibliographie sont nécessaires, vous pouvez utiliser latexmk. Les exemples suivants ne s'appliquent qu'à l'entrée vérifiée et dans le répertoire de travail autorisé :

# Document xelatex (défaut pour le chinois)
latexmk -norc -xelatex -latexoption=-no-shell-escape -interaction=nonstopmode -halt-on-error main.tex

# Document pdflatex
latexmk -norc -pdf -latexoption=-no-shell-escape -interaction=nonstopmode -halt-on-error main.tex

# Nettoyage des fichiers auxiliaires
latexmk -norc -c

Description des paramètres :

• -interaction=nonstopmode : Ne pas interrompre la compilation en cas d'erreur pour attendre une entrée (indispensable pour les environnements de scripts)
• -halt-on-error : Arrêter la compilation dès la première erreur pour faciliter le diagnostic

Biber (bibliographie)

Si une bibliographie est nécessaire, vérifiez le biber/BibTeX que latexmk prévoit d'appeler et l'entrée, puis autorisez l'exécution ; ne considérez pas la détection automatique comme une permission d'exécution supplémentaire.

---

Principes de typographie pour la lisibilité

Voici un résumé des principes essentiels ; la cartographie détaillée et les exemples de code sont dans readability-principles.

Géométrie de la page

Visez 50 à 75 caractères par ligne (66 est la valeur idéale, la valeur par défaut de TeX l'est).

\usepackage{geometry}
\geometry{a4paper, margin=2.5cm}
% Chaque caractère chinois est environ 2 fois plus large qu'un caractère anglais, 35 caractères chinois/ligne ≈ 70 caractères anglais/ligne

Tableaux

Pour les tableaux de données ordinaires, privilégiez le style sans lignes verticales de booktabs ; si l'utilisateur, la revue ou le modèle institutionnel l'exige, conservez ses spécifications :

\usepackage{booktabs}
\begin{tabular}{lrr}
    \toprule
    Indicateur & 2024 & 2025 \\
    \midrule
    Revenu & 120 & 150 \\
    \bottomrule
\end{tabular}

La conception de booktabs suppose l'absence de lignes verticales — avec des lignes verticales, l'espacement horizontal se brise : ce n'est pas un bug, c'est une fonctionnalité.

Système d'espacement

Choisissez l'une des deux options pour séparer les paragraphes, ne les mélangez pas :

% Option A : Alinéa en première ligne (documents académiques, défaut de ctex)
\setlength{\parindent}{2em}

% Option B : Espacement entre paragraphes (documents techniques, rapports)
\setlength{\parindent}{0pt}
\setlength{\parskip}{0.5\baselineskip}

Polices

Pour le corps du texte, utilisez une police à empattement (confort de lecture), pour le code, une police à chasse fixe. Avec xelatex/lualatex, utilisez fontspec pour définir les polices système :

\usepackage{fontspec}
\setmainfont{TeX Gyre Termes}[Ligatures=TeX]
\setmonofont{TeX Gyre Cursor}

microtype

Une amélioration de qualité presque gratuite — le crénage fin rend le texte plus uniforme :

\usepackage{microtype}
% Note : avec xelatex, seule la protrusion est disponible (pas d'expansion de police), mais cela vaut toujours la peine de charger

Lignes orphelines / veuves

Empêchez la première ou la dernière ligne d'un paragraphe d'apparaître isolée en haut ou en bas de la page :

\widowpenalty=10000
\clubpenalty=10000

Coloration syntaxique du code

Par défaut, utilisez listings (aucune dépendance externe). minted offre une meilleure qualité mais nécessite Python + Pygments/latexminted :

\usepackage{listings}
\usepackage{xcolor}

\lstset{
    basicstyle=\ttfamily\small,
    keywordstyle=\color{blue!70!black},
    commentstyle=\color{gray},
    stringstyle=\color{green!50!black},
    numbers=left,
    numberstyle=\tiny\color{gray},
    frame=none,
    breaklines=true,
    showstringspaces=false,
}

---

Flux de travail

Destiné à ceux qui utilisent ce flux de travail pour la première fois.

Étape 0 : Vérification de l'environnement

Ne vérifiez que si une compilation locale est nécessaire et que les informations sur les outils existants sont insuffisantes. Lisez d'abord le script de vérification, confirmez qu'il appelle des programmes dans un PATH fiable et qu'il respecte les permissions existantes ; il ne fait que signaler, n'installe ni ne modifie les réglages.

Déduisez skill_root à partir du répertoire parent absolu du SKILL.md réellement lu, sans supposer que le répertoire de travail actuel est le répertoire de la compétence, puis exécutez :

bash "$skill_root/scripts/check_latex_env.sh"

Signalez séparément les composants manquants et les échecs de détection. N'installez que les dépendances réellement nécessaires à la tâche et déjà autorisées ; en l'absence d'autorisation, indiquez les lacunes ou les alternatives existantes. Pour les étapes détaillées, lisez le guide de vérification d'environnement.

Étape 1 : Comprendre les besoins

Confirmez :

• Type de document : Thèse / Rapport / CV / Diapositives / Général
• Langue : Chinois / Anglais / Mixte
• Lecteur : Académique / Commercial / Technique / Grand public
• Besoins spéciaux : Bibliographie / Blocs de code / Formules mathématiques / Graphiques de données

Étape 2 : Choix du moteur

Suivez l'arbre de décision de choix du moteur ci-dessus. Chinois → xelatex est le choix le plus courant.

Étape 3 : Génération du .tex

Appliquez les principes de lisibilité de la typographie, suivez l'ordre de chargement standard du package-guide.

Étape 4 : Compilation

latexmk -norc -xelatex -latexoption=-no-shell-escape -interaction=nonstopmode -halt-on-error main.tex

Étape 5 : Vérification des logs

Ouvrez main.log, recherchez Warning et Overfull/Underfull :

• Overfull hbox → Localisez le texte, la formule ou la largeur de colonne qui déborde, examinez la page réelle et corrigez localement ; ne masquez pas le problème avec un \sloppy global
• Underfull hbox → Ligne trop lâche, généralement inoffensif
• Font shape warning → Forme de police indisponible, vérifiez les réglages de fontspec
• Undefined references → Nécessite une nouvelle compilation (latexmk devrait le faire automatiquement)

Corrigez les avertissements qui affectent la livraison, par exemple les caractères manquants, les références non résolues et les débordements visibles ; pour les avertissements inoffensifs ou contraints par le modèle, expliquez la raison, n'exigez pas que tous les warnings soient à zéro.

Étape 6 : Vérification et livraison de la page réelle

Affichez ou ouvrez le PDF réel, vérifiez le nombre de pages, les caractères manquants, le recadrage, les tableaux / formules / code, les liens, les signets et les exigences d'accessibilité associées ; vérifiez si les polices sont intégrées et le texte copiable. Après correction, recompilez et revérifiez les pages affectées. Si le rendu n'est pas possible, marquez explicitement « validation visuelle non effectuée », ne remplacez pas la validation de page par une compilation réussie.

Sortez les fichiers réellement générés et vérifiés :

1. PDF — Livrable final
2. Fichier source .tex et ressources locales nécessaires — Conservez le point d'entrée reproductible, la commande réelle, le résultat de compilation et les éléments non vérifiés.

evals/evals.json est une donnée d'évaluation, pas une instruction d'exécution ; ne lisez que lors du test de cette compétence.

---

Aide-mémoire des problèmes courants

En cas de problème, consultez par type :

Type de problème	Fichier à consulter	Symptômes courants
Erreur de compilation	common-pitfalls §Top 10 des erreurs de compilation	Undefined control sequence, Missing $, blocage
Encodage / Caractères	common-pitfalls §Encodage et caractères	Erreur avec des caractères non ASCII, guillemets intelligents, espacement des signes de ponctuation chinois
Flottants	common-pitfalls §Flottants	Figures ou tableaux déplacés à la fin du document
Tableaux	common-pitfalls §Tableaux	Débordement de largeur de colonne, saut de page
Polices	common-pitfalls §Polices	Police système introuvable, CJK inactif
Conflits de packages	package-guide §Matrice de conflits de packages	Option clash, comportement anormal
Ordre de chargement	package-guide §Règles d'ordre de chargement	Signets corrompus, liens cassés
Qualité de mise en page	readability-principles	Document d'apparence « amateur »
Problèmes d'environnement	environment-check	Commande introuvable, erreur de permission
Polices ctex	environment-check §Problèmes d'environnement courants §6	fontset 'fandol' is unavailable

Liste de diagnostic rapide

En cas d'échec de compilation, procédez dans cet ordre :

1. ✅ Utilisation du bon moteur ? (Chinois → xelatex)
2. ✅ Utilisation de latexmk ? (Gère automatiquement les compressions multiples et biber)
3. ✅ Utilisation de -interaction=nonstopmode ? (Ne reste pas bloqué en mode interactif)
4. ✅ L'ordre de chargement des packages respecte les contraintes réelles de la classe de document et des packages ? (Généralement hyperref en dernier, cleveref ensuite)
5. ✅ Chaque \begin{...} a-t-il un \end{...} correspondant ?
6. ✅ Chaque { a-t-il un } correspondant ?
7. ✅ Le chemin des images est-il correct ? (\graphicspath définit les chemins de recherche)
8. ✅ Tous les packages sont-ils installés ? (Vérifiez avec kpsewhich <pkg>.sty)
9. ✅ Pour un document chinois, ctex est-il utilisé avec le fontset correct ?
10. ✅ Consultez la fin du journal — les messages d'erreur de LaTeX pointent généralement vers la ligne du vrai problème.