3.3.2 Commande pour extension (classe ou paquetage)

Voici les commandes conçues pour aider les auteurs d’extension (classes ou paquetages).

\AtBeginDvi{specials}

Sauvegarde dans une registre de boîte des choses qui sont à écrire dans le fichier .dvi au début de l’achèvement de la première page du

document.

\AtEndOfClass{code}

\AtEndOfPackage{code}

Crochet pour insérer le code à exécuter lorsque LaTeX termine le traitement de la classe ou du paquetage courants. On peut utiliser ces crochet plusieurs fois ; le code sera exécuté dans l’ordre d’appel. Voir aussi \AtBeginDocument.

\CheckCommand{cmd}[num][défaut]{définition}

\CheckCommand*{cmd}[num][défaut]{définition}

Similaire à \newcommand (voir \newcommand & \renewcommand) mais ne définit pas cmd ; à la place vérifie que la définition actuelle de cmd est exactement celle donnée par définition et est ou n’est pas longue selon ce que l’on attend. Une commande est dite longue lorsque elle accepte \par au sein d’un argument. On attend que la commande cmd soit longue avec la version non-étoilée de \CheckCommand. Lève une erreur en cas d’échec de la vérification. Ceci vous permet de vérifier avant de redéfinir vous-même cmd qu’aucun paquetage ne l’a pas déjà fait.

\ClassError{nom de la classe}{texte de l'erreur}{texte d'aide}

\PackageError{nom du paquetage}{texte de l'erreur}{texte d'aide}

\ClassWarning{nom de la classe}{texte avertissement}

\PackageWarning{nom du paquetage}{texte avertissement}

\ClassWarningNoLine{nom de la classe}{texte avertissement}

\PackageWarningNoLine{nom du paquetage}{texte avertissement}

\ClassInfo{nom de la classe}{texte info}

\PackageInfo{nom du paquetage}{texte info}

\ClassInfoNoLine{nom de la classe}{texte info}

\PackageInfoNoLine{nom du paquetage}{texte info}

Produit un message d’erreur, ou des messages d’avertissement ou d’information.

Pour \ClassError et \PackageError le message est texte de l’erreur, suivi de l’invite d’erreur ? de TeX. Si l’utilisateur demande de l’aide en tapant h, il voit le texte d’aide.

Les quatre commandes d’avertissement (warning) sont similaires à ceci près qu’elles écrivent texte avertissement à l’écran sans invite d’erreur. Les quatre commandes d’information écrivent texte info seulement dans le fichier journal. Les versions en NoLine n’affichent pas le numéro de la ligne générant le message, alors que les autres versions le font.

Pour formater les messages, y compris le texte d’aide : utilisez \protect pour empêcher une commande de se développer, obtenez un saut de ligne avec \MessageBreak, et obtenez une espace avec \space lorsque l’utilisation d’un caractère espace ne le permet pas, comme après une commande. Notez que LaTeX ajoute un point final à chaque message.

\CurrentOption

Se développe au contenu de l’option en cours de traitement. Peut uniquement être utilisé au sein de l’argument code soit de \DeclareOption, soit de \DeclareOption*.

\DeclareOption{option}{code}

\DeclareOption*{option}{code}

Rend un option option disponible pour l’utilisateur, de sorte à ce qu’il puisse la passer à leur commande \documentclass. Par exemple, la classe notecms pourrait avoir une option logo pour mettre le logo de leur organisation sur la première page avec \documentclass[logo]{notcms}. Le fichier de classe doit contenir \DeclareOption{logo}{code} (et plus loin, \ProcessOptions).

Si vous invoquez une option qui n’a pas été déclarée, par défaut cela produit une avertissement semblable à Unused global option(s): [badoption]. Vous pouvez changer ce comportement avec la version étoilée \DeclareOption*{code}. Par exemple, beaucoup de classes étendent une classe existante en utilisant une commande du genre \LoadClass{article}, et pour passer les options supplémentaires à la classe sous-jacente utilisent un code tel que celui-ci :

\DeclareOption*{%
\PassOptionsToClass{\CurrentOption}{article}%
}

Un autre exemple est que la classes notecms permette aux utilisateur de tenir des listes de destinataire des notes dans des fichiers externes. Par exemple l’utilisateur invoque \documentclass[math]{notecms} et la classe lit le fichier math.memo. Ce code gère le fichier s’il existe et sinon passe l’option à la classe article.

\DeclareOption*{\InputIfFileExists{\CurrentOption.memo}{}{%
    \PassOptionsToClass{\CurrentOption}{article}}}

\DeclareRobustCommand{cmd}[num][défaut]{définition}

\DeclareRobustCommand*{cmd}[num][défaut]{définition}

Similaire à \newcommand et \newcommand* (voir \newcommand & \renewcommand) mais déclare une commande robuste, même si définition comprend du code fragile. (Pour une discussion sur les commandes robustes et fragiles voir \protect). Utilisez ces commande pour définir de nouvelles commandes robustes, ou redéfinir des commandes existantes en les rendant robustes. Contrairement à \newcommand elle ne produisent pas d’erreur si la macro cmd existe déjà ; au lieu de cela un message est écrit dans le fichier journal pour indiquer la redéfinition de la commande.

Les commandes définies de cette manière sont légèrement moins efficace que celle définies avec \newcommand, c’est pourquoi, à moins que le contenu de la commande soit fragile et que la commande soit utilisée au sein d’un argument mouvant, utilisez \newcommand.

Le paquetage etoolbox offre les commandes \newrobustcmd, \newrobustcmd*, \renewrobustcmd, \renewrobustcmd*, \providerobustcmd, et \providrobustcmd* qui sont similaire aux commandes standardes \newcommand, \newcommand*, \renewcommand, \renewcommand*, \providecommand, et \providecommand*, mais définissent une commande cmd robuste avec deux avantages par rapport à \DeclareRobustCommand :

1. Elle utilisent un mécanisme de protection de bas niveau d’e-TeX au lieu du mécanisme de plus au niveau de LaTeX utilisant \protect, ainsi elles ne subissent pas la légère perte de performance mentionnée plus haut, et
2. Elles font la même distinction entre \new…, \renew…, et \provide… que les commandes standardes, ainsi elle ne font pas qu’envoyer un message dans le journal lorsque vous redéfinissez cmd déjà existantes, dans ce cas vous devez utiliser soit \renew… soit \provide… ou il y a une erreur.

\IfFileExists{nom fichier}{si vrai}{si faux}

\InputIfFileExists{nom fichier}{si vrai}{si faux}

Exécute si vrai si LaTeX peut trouver le fichier nom fichier et si faux sinon. Dans le second cas, le fichier est lu immédiatement après exécuter si vrai. Ainsi \IfFileExists{img.pdf}{\includegraphics{img.pdf}}{\typeout{AVERTISSEMENT : img.pdf introuvable}} n’inclut le graphique img.pdf que s’il est trouvé, mais autrement produit seulement un avertissement.

Cette commande cherche le fichier dans tous les chemins de recherche que that LaTeX utilise, et non pas seulement dans le répertoire courant. Pour chercher uniquement dans le répertoire courant faites quelque chose du genre de \IfFileExists{./nom fichier}{si vrai}{si faux}. Si vous demandez un fichier dont le nom n’a pas d’extension .tex alors LaTeX commencera par chercher le fichier en apposant .tex à son nom ; pour plus ample information sur la façon dont LaTeX gère les extensions de nom de fichier voir \input.

\LoadClass[liste d'options]{nom de la classe}[date de parution]

\LoadClassWithOptions{nom de la classe}[date de parution]

Charge une classe, comme avec \documentclass[options list]{nom de la classe}[release info]. Voici un exemple : \LoadClass[twoside]{article}.

La liste d’options, si présente, est une liste ponctuée par des virgules. La date de parution est optionnelle. Si elle est présente, elle doit avoir le format AAAA/MM/JJ. Si vous demandez une date de parution et que la date du paquetage installé sur votre système est antérieure, alors vous obtiendrez un avertissement à l’écran et dans le journal de compilation du genre de You have requested, on input line 4, version `2038/01/19' of document class article, but only version `2014/09/29 v1.4h Standard LaTeX document class' is available.

La variante de la commande \LoadClassWithOptions utilise la liste des options de la classe courante. Cela veut dire qu’elle ignore toute options passée via \PassOptionsToClass. Ceci est une commande de commodité qui vous permet de construire une nouvelle classe en l’héritant d’une classe existante, telle que la classe standarde article, sans avoir à gérer les options qui furent passée.

\ExecuteOptions{liste d'options}

Pour chaque option option de la liste d’options, dans l’ordre d’apparition, cette commande exécute la commande \ds@option. Si cette commande n’est pas définie, alors l’option option est ignorée.

Ceci peut être utilisé pour fournir d’un liste d’option par défaut avant le \ProcessOptions. Par exemple, si dans un fichier de classe vous désirez utiliser par défaut la taille de police 11pt alors vous devriez spécifier \ExecuteOptions{11pt}\ProcessOptions\relax.

\NeedsTeXFormat{format}[date du format]

Spécifie le format sous lequel cette classe doit être utilisée. Cette directive est souvent donnée à la première ligne du fichier de classe, et le plus souvent elle est utilisée de cette façon : \NeedsTeXFormat{LaTeX2e}. Lorsque un document utilisant cette classe est traité, le nom du format donné ici doit s’accorder avec le format qui est en cours d’exécution (y compris le fait que la chaîne format est sensible à la casse). Si il ne s’y accorde pas alors l’exécution est interrompue par une erreur du genre de ‘This file needs format `LaTeX2e' but this is `xxx'.’

Pour spécifier une version du format dont vous savez qu’elle prend en charge certaines fonctions, incluez l’argument optionnel date du format correspondant au format où ces fonction furent implémentés. Si cette argument est présent il doit être de la forme AAAA/MM/JJ. Si la version de format installée sur votre système est antérieure à la date du format alors vous obtiendrez un avertissement du genre de ‘You have requested release `2038/01/20' of LaTeX, but only release `2016/02/01' is available.’

\OptionNotUsed

Ajoute l’option courante à la liste des options non utilisées. Ne peut être utilisé qu’au sein de l’argument code de \DeclareOption ou \DeclareOption*.

\PassOptionsToClass{liste d'options}{nom de la classe}

\PassOptionsToPackage{liste d'options}{nom du paquetage}

Ajoute les options de la liste ponctuée par des virgules option list aux options utilisée par toute commande ultérieure \RequirePackage ou \usepackage pour le paquetage nom du paquetage ou la classe nom de la classe.

La raison d’être de ces commande est que vous pouvez charger un paquetage autant de fois que vous le voulez sans options, mais que si voulez passer des options alors vous ne pouvez les fournir qu’au premier chargement. Charger un paquetage avec des options plus d’une fois produit une erreur du genre de Option clash for package toto. (LaTeX lance l’erreur même s’il n’y a pas de conflit entre les options.)

Si votre propre code introduit un paquetage deux fois alors vous pouvez réduire cela en une fois, par exemple en remplaçant les deux \RequirePackage[landscape]{geometry}\RequirePackage[margins=1in]{geometry} par un seul \RequirePackage[landscape,margins=1in]{geometry}. Mais si vous chargez un paquetage qui à son tour en charge un autre alors vous devez mettre en queue les options que vous désirez pour cet autre paquetage. Par exemple, supposons que le paquetage toto charge le paquetage geometry. Au lieu de \RequirePackage{toto}\RequirePackage[draft]{graphics} vous devez écrire \PassOptionsToPackage{draft}{graphics} \RequirePackage{toto}. (Si toto.sty charge une option en conflit avec ce que vous désirez alors vous devrez considérer une modification de son code source.)

Ces commandes sont également utiles aux utilisateurs de base et pas seulement aux auteurs de classes et paquetage. Par exemple, supposons qu’un utilisateur veuille charger le paquetage graphicx avec l’option draft et veuille également utiliser une classe toto qui charge le paquetage graphicx, mais sans cette option. L’utilisateur peut commencer son fichier LaTeX avec \PassOptionsToPackage{draft}{graphicx}\documentclass{toto}.

\ProcessOptions

\ProcessOptions*\@options

Exécute le code pour chaque option que l’utilisateur a invoquée. À inclure dans le fichier classe sous la forme \ProcessOptions\relax (à cause de l’existence de la variante étoilée de la commande).

Les options tombent dans deux catégories. Les options locales sont spécifiées pour un paquetage particulier au sein de l’argument options dans \PassOptionsToPackage{options}, \usepackage[options], ou \RequirePackage[options]. Les options globales sont celles données par l’utilisateur de la classe dans \documentclass[options]. (Si une option est spécifiée à la fois localement et globalement, alors elle est locale).

Lorsque \ProcessOptions est appelé pour un paquetage pkg.sty, il se produit ce qui suit :

1. Pour chaque option option déclarée jusqu’à ce point avec \DeclareOption, LaTeX examine si cette option est soit globale soit locale pour pkg. Si c’est le cas, il exécute le code déclaré. Ceci est fait dans l’ordre de passage de ces options à pkg.sty.
2. Pour chaque option locale restante, il exécute la commande \ds@option si elle a été définie quelque part (autrement que par un \DeclareOption) ; sinon, il exécute le code de traitement par défaut des options donné dans \DeclareOption*. Si aucun code de traitement par défaut n’a été déclaré, il produit un message d’erreur. Ceci est fait dans l’ordre dans lequel ces options ont été spécifiées.

Lorsque \ProcessOptions est appelé pour une classe il fonctionne de la même manière à ceci près que toutes les options sont locales, et que le code par défaut pour \DeclareOption* et \OptionNotUsed plutôt qu’une erreur.

La version étoilée \ProcessOptions* exécute le traitement des options dans l’ordre spécifié par les commandes appelante, plutôt que dans l’ordre de déclaration de la classe ou du paquetage. Pour un paquetage, ceci signifie que les options globales sont traitées en premier.

\ProvidesClass{nom de la classe}[date de parution brève information supplémentaire]

\ProvidesClass{nom de la classe}[date de parution]

\ProvidesPackage{nom du paquetage}[date de parution brève information supplémentaire]

\ProvidesPackage{nom du paquetage}[date de parution]

Identifie la classe ou le paquetage, en tapant un message sur la console et dans le fichier journal.

Lorsqu’un utilisateur écrit \documentclass{notecms} alors LaTeX charge le fichier notecms.cls. De même, un utilisateur écrivant \usepackage{essai} invite LaTeX à charger le fichier essai.sty. Si le nom du fichier ne s’accorde pas à l’argument nom de la classe ou nom du paquetage alors un avertissement est produit. Ainsi, si vous invoquez \documentclass{notecms}, et que le fichier the file notecms.cls comprend la déclaration statement \ProvidesClass{xxx} alors vous obtiendrez un avertissement du genre de like You have requested document class `notecms', but the document class provides 'xxx'. Cet avertissement n’empêche pas LaTeX de traiter le reste du fichier de la classe normalement.

Si vous incluez l’argument optionnel, alors vous devez inclure la date, avant le premier espace s’il y en a, et elle doit avoir le format AAAA/MM/JJ. Le reste de l’argument est en format libre, toutefois il identifie traditionnellement la classe, et est écrit pendant la compilation à l’écran et dans le journal. Ainsi, si votre fichier notecms.cls contient la ligne \ProvidesClass{smcmem}[2008/06/01 v1.0 Classe note CMS] la première ligne de votre document est \documentclass{notecms} alors vous pourrez voir Document Class: notecms 2008/06/01 v1.0 Classe note CMS.

La date dans l’argument optionnel permet aux utilisateurs de classe et de paquetage de demander à être avertis si la version de la classe ou du paquetage installé sur leur système est antérieure à date de parution, en utilisant les arguments optionnels comme dans \documentclass{smcmem}[2018/10/12] ou \usepackage{toto}[[2017/07/07]]. (Notez que les utilisateurs de paquetages incluent seulement rarement une date, et les utilisateurs de classe presque jamais).

\ProvidesFile{nom fichier}[information supplémentaire]

Déclare un fichier autre que les fichiers principaux de classe ou de paquetage, tel qu’un fichier de configuration ou un fichier de définition de police. Mettez la commande dans ce fichier et vous obtiendrez dans le journal une information du genre de File: essai.config 2017/10/12 fichier de configuration pour essai.cls lorsque nom fichier vaut ‘essai.config’ et que information supplémentaire vaut ‘2017/10/12 fichier de configuration pour essai.cls’.

\RequirePackage[liste d'options]{nom du paquetage}[date de parution]

\RequirePackageWithOptions{nom du paquetage}[date de parution]

Charge un paquetage, comme la commande \usepackage pour les auteurs de documents. Voir Additional packages. Voici un exemple : \RequirePackage[landscape,margin=1in]{geometry}. Notez que l’équipe de développement de LaTeX recommande fortement l’utilisation de ces commandes de préférence à l’\input de TeX de base ; voir le « Class Guide ».

La liste d’options, si présente, est une liste ponctuée de virgules. La date de parution, si présente, doit avoir le format AAAA/MM/JJ. Si la date de parution du paquetage tel qu’il est installé sur votre système est antérieure à date de parution alors vous obtiendrez un avertissement du genre de You have requested, on input line 9, version `2017/07/03' of package jhtest, but only version `2000/01/01' is available.

La variante \RequirePackageWithOptions utilise la liste d’options de la classe courante. Ceci implique qu’elle ignore toute option passée à la classe via \PassOptionsToClass. C’est une commande de commodité pour permettre facilement de construire des classes sur des classes existantes sans avoir à gérer les options qui sont passées.

La différence entre \usepackage et \RequirePackage est mince. La commande \usepackage est à l’intention du fichier document alors que \RequirePackage l’est à celle des fichiers paquetage ou classe. Ainsi, utiliser \usepackage avant la commande \documentclass amène LaTeX à produire une erreur du genre de \usepackage before \documentclass, là où vous pouvez utiliser \RequirePackage.