De nouvelles commandes

Dans ce chapitre, nous allons apprendre à créer nos propres commandes, puis nous verrons où trouver des classes et des packages déjà faits et comment apprendre à les utiliser. Avec nos propres commandes, nous pourront avoir du code plus facile à écrire et surtout plus lisible.

Par exemple, si nous faisons plusieurs fois des citations, il pourrait être judicieux d’avoir une commande de citation qui prend en paramètre la citation et son auteur et la met en forme. Ainsi, notre code sera plus lisible grâce à l’utilisation de cette commande, et en plus nous sommes assurés d’avoir un style de citation uniforme dans tout le document.

Créer ses commandes

La première étape est de voir comment définir de nouvelles commandes et de nouveaux environnements.

Créer une commande

Pour définir une nouvelle commande, nous utilisons la commande \newcommand.

\newcommand{\nom_commande}[nb_arguments]{code_de_la_commande}

On lui donne le nom de la commande à définir, son nombre d’arguments (0 par défaut) et le code de la commande.

Pour illustrer son fonctionnement, nous allons prendre l’exemple d’une commande de citation, qui prend en paramètre le nom de l’auteur et la citation, et la met en forme entre guillemets.

Voici comment nous pourrions définir cette commande.

\newcommand{\citer}[2]{\og #2 \fg (\bsc{#1})}

Ici, nous définissons une commande \citer, qui prend 2 arguments. Dans le code de la commande, nous faisons référence au ne argument en écrivant #n. Ainsi, cette commande écrit son deuxième argument entre guillemets, suivi de son premier argument entre parenthèses.

Généralement, les définitions de commandes sont placées dans le préambule du document.

Essayons notre commande.

\documentclass[12pt,french]{article}
\usepackage[utf8]{inputenc}
\usepackage[T1]{fontenc}
\usepackage{babel}

\newcommand{\citer}[2]{\og #2 \fg{} (#1)}

\begin{document}
   Pouvons-nous dire qu’\citer{Machiavel}{une guerre est juste quand elle nécessaire} ?
\end{document}

Nous ne pouvons pas définir une commande qui existe déjà, sous peine d’obtenir l’erreur « command <\nom_commande> already defined ».

Commandes courtes

Notre commande n’est pas très adaptée pour les citations sur plusieurs paragraphes. Nous ne voudrions pas l’utiliser de cette manière par exemple.

\citer{auteur}{Une citation longue. En fait 
sur plusieurs paragraphes. Avec des listes.
\begin{itemize}
   \item Un item.
   \item Un deuxième.
   \item Un dernier pour la route.
\end{itemize}

Un autre paragraphe de la citation.
}

Pourtant ce code est légal et ne donnera pas d’erreurs. Pour régler ce problème, il nous suffit de définir une commande courte. Et pour cela il n’y a presque rien à changer : il faut juste utiliser la version étoilée de \newcommand.

\newcommand*{\citer}[2]{\og #2 \fg{} (#1)}

\begin{document}
   \citer{auteur}{Une citation longue. En fait 
   sur plusieurs paragraphes. Avec des listes.
   \begin{itemize}
      \item Un item.
      \item Un deuxième.
      \item Un dernier pour la route.
   \end{itemize}

   Un autre paragraphe de la citation.
   }  
\end{document}

Cette fois, nous obtenons une erreur : « paragraph ended before \citer was complete ».

Créer un environnement

Pour créer un environnement, nous pouvons tout simplement créer une commande \nom et une commande \endnom (rappelons-nous ceci). Cependant, il existe également une commande \newenvironment qui s’utilise de cette manière.

\newenvironment{nom_environnement}[nb_arguments]{code_de_début}{code_de_fin}

En gardant l’exemple de la citation, créons un environnement de citation qui imprime « auteur a dit : » suivi de la citation dans un environnement quotation.

\newenvironment{citerlong}[1]{\bsc{#1} a dit : \begin{quotation}}{\end{quotation}}

On peut alors écrire ce code.

\documentclass[12pt,french]{article}
\usepackage[utf8]{inputenc}
\usepackage[T1]{fontenc}
\usepackage{babel}

\newenvironment{citerlong}[1]{\bsc{#1} a dit : \begin{quotation}}{\end{quotation}}

\begin{document}
   \begin{citerlong}{Tartempion}
      Voici une citation longue. 

      Tellement longue qu'elle est sur plusieurs paragraphes.

      Espérons que l'environnement saura distinguer les différents paragraphes.
   \end{citerlong}
\end{document}

Et on a bien le résultat attendu.

De même que pour les commandes, les définitions d’environnements sont généralement placées dans le préambule, et essayer de définir un environnement qui existe déjà donnera une erreur.

Redéfinition de commande et d’environnements

S’il n’est pas possible de définir une commande ou un environnement qui existe déjà, on peut cependant les redéfinir grâce aux commandes \renewcommand et \renewenvironment. Elles prennent les mêmes arguments que \newcommand et \renewenvironment.

Par exemple, si un jour nous voulons que la commande \bsc mettent les noms qu’on lui passe en argument en emphase plutôt qu’en petites capitales, nous la redéfinirons de cette manière.

\renewcommand{\bsc}[1]{\emph{#1}}

La redéfinition de commandes est très utile pour garder un texte sémantique. Comme nous l’avons déjà dit, si un jour nous voulons les mots importants en gras, nous redéfinirons la commande \emph plutôt que d’utiliser une commande de mise en gras pour chaque mot important. Cette solution, en plus d’être plus sémantique, est plus simple à mettre en place (si un jour nous en avons marre du gras, et voulons tout mettre en rouge, il nous suffira de changer la redéfinition).

La commande renewcommand a aussi une version étoilée qui agit de la même manière que la version étoilée de \newcommand. Ici, nous avons redéfini \bsc avec la version non étoilée de \renewcommand, donc elle est théoriquement utilisable avec plusieurs paragraphes (en pratique, elle ne l’est pas puisqu’elle utilise la commande \emph qui elle est courte).

Redéfinition récursive

Il arrive que l’on veuille redéfinir une méthode, mais en l’utilisant pour sa redéfinition. Un code de ce type en gros.

\renewcommand*{\emph}[1]{(\emph{#1} en emphase)}

\begin{document}
   \emph{important}
\end{document}

Si nous essayons ceci, nous aurons l’erreur TeX capacity exceeded. En effet, ici, en appelant la commande \emph, on voit qu’elle utilise la commande \emph, donc on l’appelle, mais elle s’utilise donc on l’appelle… Et ce jusqu’à l’erreur.

Pour régler ce problème, il nous faut garder en mémoire l’ancienne commande \emph dans une autre commande, et appeler cette commande que nous venons de définir plutôt que l’ancienne.

\newcommand*{\oldemph}[1]{\emph{#1}}
\renewcommand*{\emph}[1]{(\oldemph{#1} en emphase)}

\begin{document}
   \emph{important}
\end{document}

Mais ça ne marche pas ! L’erreur est toujours présente !

Le problème, c’est qu’en définissant \oldemph, on est en train de dire (en gros) « quand tu croises \odlemph, tu devras appeler \emph», et donc voici ce qui arrive quand on appelle \emph : elle utilise \oldemph, donc on appelle \oldemph, mais celui-ci demande d’appeler \emph, et on retombe dans ce cercle vicieux. Voici un exemple illustrant ce phénomène.

\newcommand*{\exemple}[1]{\emph{#1}}
\renewcommand*{\emph}[1]{\bsc{#1}}

\begin{document}
   \exemple{important} % Ici, important sera écrit en utilisant la commande \bsc.
\end{document}

Pour régler ce problème, nous allons utiliser la primitive Tex \let. Avec \let\oldemph\emph, on indique à Tex que \oldemph doit prendre la valeur qu’a \emph au moment où est écrite la ligne.

En fait, ce comportement est à opposer à celui d’une autre primitive Tex, la primitive \def, puisque qu’avec \def\oldemph\emph, on indique à TeX qu’il faudra que \oldemph prenne la valeur de \emph, mais à la ligne d’utilisation (et donc si depuis la commande \emph a été modifiée, cela sera pris en compte).

Tout ceci nous permet de finalement faire un exemple correct.

\let\oldemph\emph
\renewcommand*{\emph}[1]{(\oldemph{#1} en emphase)}

\begin{document}
   \emph{important}
\end{document}

Ici, nous voyons comment créer une commande avec un argument optionnel.

Pour créer une commande avec un argument optionnel, nous allons utiliser le second argument optionnel de \newcommand. Nous mettons en premier argument optionnel le nombre total d’arguments de la commande que l’on veut créer, et la présence d’un second argument optionnel indique à LaTeX qu’il y a un argument optionnel. Cet argument optionnel sera alors l’argument #1. 

\newcommand\test[1][]{Argument optionnel (#1).}

Avec le code \test \test[A], nous obtenons alors « Argument optionnel : (). Argument optionnel : (A) ». Notons que nous pouvons donner une valeur par défaut à l’argument optionnel. Il nous suffit pour cela de la donner dans le second argument optionnel de \newcommand. Ainsi, on écrit ce code.

\newcommand\test[1][X]{Argument optionnel (#1).}

Cette fois, le code \test \test[A] nous donne « Argument optionnel : (X). Argument optionnel : (A) ».

Puisque #1 fait référence à l’argument optionnel, les autres arguments, ceux qui sont obligatoires commencent bien sûr à partir de #2.

Réécrivons \test avec deux arguments obligatoires qu’elle affiche (en plus de l’argument optionnel).

\newcommand\test[3][X]{Arguments : optionnel (#1), obligatoire 1 (#2), obligatoire 2 (#3).}

Avec \newcommand, nous ne pouvons avoir qu’un seul argument optionnel. Quelques astuces nous permettent d’outrepasser cette limite, mais nous n’allons pas les voir ici. Lorsque nous voudrons faire cela, et plus généralement lorsque nous voudrons créer de manière plus précise des commandes, nous nous tournerons vers des packages comme xparse qui nous facilitent la tâche.

Le CTAN, découverte de classes et de packages

La création de commandes c’est bien. Pouvoir profiter de commandes déjà écrites par d’autres personnes, c’est mieux. Ces commandes sont regroupées dans des packages et certaines personnes ont même créé des classes alternatives (par exemple pour écrire des thèses, des lettres, des journaux, etc.). Il est donc intéressant d’avoir ces packages (et ils sont vraiment très nombreux) à notre disposition.

Le CTAN se décrit lui-même comme the cen­tral place for all kinds of ma­te­rial around TeX c’est-à-dire le site où l’on retrouve toutes sortes de choses autour de TeX (et aussi de LaTeX). On peut y trouver une bonne quantité de packages.

La page d’accueil du CTAN peut sembler austère à première vue. Si nous cherchons par exemple un package pour écrire du pseudo-code, nous pouvons naviguer à travers la liste des sujets (« Browse » → « Topics »). Là, nous choisissons la lettre « P », puis la section pseudo-code et nous avons une liste de packages permettant d’écrire du pseudo-code.

Mais comment savoir quel package prendre ? Et comment savoir dans quel topic trouver ce qui nous intéresse.

Les noms des sujets sont généralement assez parlant, et ce même pour quelqu’un qui n’est pas habitué à l’anglais. Nous trouvons par exemple les sujets cv, lettre ou encore colour.

Pour choisir un package parmi tous ceux qui font ce que l’on désire, il n’y a pas de méthode miracle ; le mieux reste de regarder les avis (voir de les demander). Néanmoins, il faudra parfois tester avant de trouver le package que l’on veut.

Bien sûr, la fonction de recherche du site sert également. Si par exemple, nous cherchons des packages permettant de formater des liens, nous pouvons rechercher url. La page de résultat nous liste des packages ayant un lien avec notre recherche et nous pouvons alors nous renseigner à propos de ces packages et trouver lequel nous convient.

La recherche peut être personnalisée de plusieurs manières. La colonne « Tips for the search » nous aide à construire des recherches plus précises.

Regardons l’un des résultats de notre recherche, le package url. Sur la page du package nous avons une petite description de ce qu’il fait, quelques informations (licence, sources, version, etc.), un lien pour le télécharger, des suggestions de packages et même une note. Néanmoins, l’information qui va le plus nous intéresser est la documentation quand elle est présente.

Certaines classes et certains packages ne sont pas présents sur le CTAN, mais sur d’autres sites (site de l’auteur, Github, etc.).

Utiliser les documentations

Quasiment toutes les classes et tous les packages que nous utilisons sont accompagnés d’une documentation. Celle-ci nous liste les choses à connaître sur le package (nom et arguments des différentes commandes, problèmes que l’on peut rencontrer, compatibilité ou incompatibilité avec d’autres packages, etc.). La documentation permet alors de savoir tout ça et donc de prendre en main un nouveau package.

Les documentations sont généralement en anglais, mais c’est de l’anglais technique assez simple à comprendre.

Mais comment trouver une documentation ?

La documentation d’un package est généralement disponible sur le CTAN (si ce package est disponible sur le CTAN) ou encore sur le site de l’auteur. En gros, la documentation sera trouvable sur la page Web du projet.

Néanmoins, le plus simple pour avoir accès à une documentation reste la commande texdoc. Ainsi, en tapant texdoc babel dans un terminal, le PDF de la documentation de babel est censé s’ouvrir. Ceci dépend cependant des choix faits à l’installation de la distribution LaTeX (on choisit d’installer ou non les documentations sur notre ordinateur).

Puisque ces documentations sont stockées sur notre ordinateur, elles ne sont pas forcément à jour (tout comme les packages que nous avons sur notre ordinateur).

Comme nous pouvons le voir en ouvrant la documentation de babel, elle est plutôt grosse (aux alentours de 150 pages). Pas d’inquiétudes ! C’est normal, babel est un gros package avec beaucoup d’options. La plupart des documentations font beaucoup moins de pages, et en fait, les documentations se lisent assez facilement une fois qu’on est habitué (oui, même celle de babel) car elles sont très bien documentées.

En fait, la plupart des documentations suivent un schéma somme toute assez classique. Tout d’abord, on retrouve une petite introduction qui indique l’utilité du package, ce qu’il apporte, ses avantages et désavantages (parfois par rapport aux autres packages existants), etc. Puis viennent généralement une présentation générale du package. Et finalement, les différentes commandes qu’il offre sont présentées de même que les options éventuelles du package, et bien sûr, on peut souvent trouver quelques exemples d’utilisation.

Il n’est pas rare de trouver également un récapitulatif des problèmes que l’on peut rencontrer avec le package (en particulier quand il peut être en conflit avec d’autres packages connus), et des améliorations qui sont à venir.

Bien sûr, en lisant des documentations, on s’habitue à en lire et à trouver les informations qui nous intéressent de manière efficace.

La documentation du package url pris en exemple plus haut est assez courte et peut être un bon premier pas pour apprendre à lire une documentation.

Ce petit chapitre nous aura introduit à la création de commandes et d’environnements et surtout nous aura présenté le très grand monde des packages du CTAN. Voici quelques packages souvent utilisés dans leurs domaines respectifs.

  • csquotes qui permet de faire des citations (il propose par exemple une commande \enquote qui place juste des guillemets autour de son argument).
  • hyperref pour créer des hyperliens et gérer les méta-données des PDFs créés.
  • biblatex pour la gestion des bibliographies (avec biber).
  • tikz pour dessiner et créer des graphiques et pgfplots qui utilise tikz et offre des outils de plus haut niveau.

Tout comme l’on devient forgeron en forgeant, c’est en utilisant LateX qu’on découvre les packages qui nous sont utiles et que l’on se forge petit à petit sa propre boîte à outils, que ce soit en termes de packages ou de commandes personnelles.