Leçon 16

Trouver de la documentation et demander de l’aide

Cette leçon présente les principales sources de documentation des logiciels et packages liés à LaTeX, et comment demander de l’aide lorsque vous êtes en difficulté.

Il y a différentes façons d’accéder à la documentation d’un package ou d’une classe.

texdoc

Si vous avez installé une distribution TeX (par exemple, TeXLive ou MikTeX) et que vous avez choisi à l’installation d’avoir la documentation stockée localement, alors vous pouvez y accéder en utilisant l’outil en ligne de commande texdoc. Il suffit de taper la commande :

texdoc < pkg >

qui ouvrira la documentation du package <pkg>. L’utilitaire recherchera la documentation disponible et ouvrira ce qu’il pense être la correspondance la plus pertinente pour votre demande. Vous aussi pouvez lister tous les résultats valables qu’il trouve et choisir parmi eux en utilisant :

texdoc -l < pkg >

texdoc.org

Il s’agit d’un site Web qui fonctionne exactement comme l’utilitaire texdoc. Vous pouvez rechercher la documentation disponible comme vous le feriez avec texdoc -l et ensuite choisir parmi les résultats.

CTAN

Le CTAN est le réseau global des archives TeX (Comprehensive TeX Archive Network), c’est à dire un ensemble de serveurs mettant à disposition de tous distributions, packages et documentations pour LaTeX. La plupart des packages LaTeX y sont publiés. Vous pouvez rechercher sur le site un package pour accéder à sa documentation. Habituellement, les packages sont enregistrés dans ctan.org/pkg/<pkg-name> et vous pouvez accéder à leur README et à leur documentation, et souvent trouver des exemples d’utilisations.

Livres à propos de LaTeX

Il existe beaucoup de livres qui peuvent vous aider à en savoir plus sur LaTeX. En tant que débutant, vous gagnerez beaucoup à consulter un guide structuré pour vous mettre le pied à l’étrier, car ceux-ci peuvent donner beaucoup plus de détails que ceux que nous avons couverts ici. Vous pouvez également choisir un ouvrage avec plus de détails et de recommandations.

Livres en français

Quelques manuels d’initiation :

Vous trouverez sur le site de l’association GUTenberg une liste assez complète des ouvrages disponibles en français, notamment des ouvrages plus avancés pour vous aider à progresser.

Livres en anglais

Lorsque vous ferez une utilisation avancée de LaTeX, il pourra vous être utile de vous tourner vers des documentations en anglais.

L’équipe LaTeX propose une liste de livres en grande partie écrits par ses membres. Les plus remarquables sont le guide officiel par Leslie Lamport et le LaTeX Companion, également disponible en français.

Foire aux questions

L’association GUTenberg héberge une FAQ LaTeX collaborative francophone. Vous pourrez y trouver les réponses à vos questions, mais aussi y contribuer pour que la communauté bénéficie de votre expérience au fil de vos expérimentations avec LaTeX.

Demander de l’aide aux autres utilisateurs

Il existe divers forums en ligne pour poser des questions sur LaTeX ; le plus populaire aujourd’hui est peut-être TeX - LaTeX StackExchange (en anglais). En français, vous pouvez vous inscrire à la liste GUT.

Chaque fois que vous posez une question, il est préférable de commencer par donner un exemple clair : ce que l’on appelle communément un « exemple complet minimal » (ECM ; en anglais minimal working example, MWE). Cela ne signifie pas que le code fonctionne (sinon vous ne poseriez pas de question!), mais plutôt que vous avez fait de votre mieux pour le rendre clair, autonome et minimal. Ce dernier qualificatif signifie que vous avez juste assez de contenu pour reproduire votre problème.

Comment fournir un exemple complet minimal (ECM)?

Comment construire un ECM ? Généralement, le plus simple est de partir de :

\documentclass{article}
\usepackage[T1]{fontenc}
\begin{document}
Texte
\end{document}

puis d’ajouter des lignes une par une jusqu’à ce que vous ayez reproduit le problème ciblé. Vous pouvez également partir de votre fichier réel puis de le réduire progressivement, mais si votre document est déjà bien avancé, la démarche peut être assez longue.

Si vous avez besoin de plus de texte pour inclure des sauts de pages ou autres effets, alors des packages tels que lipsum peuvent être utilisés pour produire plusieurs paragraphes de texte dépourvu de sens, tout en gardant votre fichier de test très court.

Fichier journal (aka log)

Vous devez garder sous la main votre fichier journal ; celui-ci est généré par LaTeX à chaque exécution, et porte le même nom que votre fichier d’entrée mais se termine par .log.

Selon l'interface de votre bureau, vous devrez peut-être « afficher les extensions » pour savoir de quel fichier il s'agit.

Dans ce fichier, vous aurez toujours la totalité des messages d’erreur. Les messages d’erreur de LaTeX s’efforcent d’être informatifs, mais il ne sont pas du même genre que ceux des traitements de textes.

Certains éditeurs ne vous facilitent pas la vie, car ils cachent les messages d'erreur complets. Leur version résumée peut ne pas contenir tous les détails.

Lorsque vous demandez de l’aide, les experts de LaTeX vous réclameront souvent une copie de votre fichier de log.

Et maintenant?

Pour finir, nous vous offrons une gallerie de petits exemples en LaTeX, qui illustrent des possibilités dans une vaste gamme de domaines non couverts par cette introduction, et différents packages développés pour ces domaines.