> For the complete documentation index, see [llms.txt](https://overleaf-pro.ayaka.space/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://overleaf-pro.ayaka.space/latex/fr/fichiers-de-classe/03-writing-your-own-package.md). # Écrire votre propre package Parfois, la meilleure option pour utiliser vos propres commandes et macros dans un document est d’écrire un nouveau package à partir de zéro. Cet article explique la structure principale d’un nouveau package. ## Introduction La première chose à faire avant de coder un nouveau package est de déterminer si vous avez réellement besoin d’un nouveau package ou non. Il est recommandé de [faire une recherche sur CTAN (Comprehensive TeX Archive Network)](http://www.ctan.org/ctan-portal/search/) et de voir si quelqu’un a déjà créé quelque chose de similaire à ce dont vous avez besoin. Une autre chose importante à garder à l’esprit est [la différence entre les packages et les classes](/latex/fr/fichiers-de-classe/01-understanding-packages-and-class-files.md). Faire le mauvais choix peut affecter la flexibilité du produit final. ## Structure générale La structure de tous les fichiers de package peut être décrite grossièrement en quatre parties : * ***Identification***. Le fichier se déclare comme un package écrit avec la syntaxe LaTeX2ε. * ***Déclarations préliminaires***. Ici, les packages externes nécessaires sont importés. De plus, dans cette partie du fichier, les commandes et définitions nécessaires aux options déclarées sont codées. * ***Options***. Le package déclare et traite les options. * ***Autres déclarations***. Le corps principal du package. Presque tout ce qu’un package fait est défini ici. Dans les sous-sections suivantes, une description plus détaillée de la structure et un exemple fonctionnel, *examplepackage.sty*, seront présentés. ### Identification Il y a deux commandes simples que tous les packages doivent avoir : ```latex \NeedsTeXFormat{LaTeX2e} \ProvidesPackage{examplepackage}[2014/08/24 Package LaTeX d’exemple] ``` La commande `\NeedsTeXFormat{LaTeX2e}` définit la version de LaTeX avec laquelle le package doit fonctionner. De plus, une date peut être ajoutée entre crochets pour spécifier la date minimale de version requise. La commande `ProvidesPackage{examplepackage}[...]` identifie ce package comme *examplepackage* et, à l’intérieur des crochets, la date de publication et quelques informations supplémentaires sont incluses. La date doit être au format AAAA/MM/JJ [Ouvrir un exemple de rédaction d’un package dans Overleaf](https://www.sharelatex.com/project/new/template?zipUrl=/project/53f11ec1eceb82a67658cb02/download/zip\&templateName=PackageExample\&compiler=pdflatex) ### Déclarations préliminaires La plupart des packages étendent et personnalisent des packages existants, et nécessitent également quelques packages externes pour fonctionner. Ci-dessous, du code supplémentaire est ajouté au package d’exemple « examplepackage.sty ». ```latex \NeedsTeXFormat{LaTeX2e} \ProvidesPackage{examplepackage}[2014/08/21 Package d’exemple] \RequirePackage{imakeidx} \RequirePackage{xstring} \RequirePackage{xcolor} \definecolor{greycolour}{HTML}{525252} \definecolor{sharelatexcolour}{HTML}{882B21} \definecolor{mybluecolour}{HTML}{394773} \newcommand{\wordcolour}{greycolour} ``` Les commandes dans cette partie initialisent soit certains paramètres qui seront ensuite utilisés pour gérer les options, soit importent des fichiers externes. La commande `\RequirePackage` est très similaire au bien connu `\usepackage`, l’ajout de paramètres optionnels entre crochets fonctionne aussi. La seule différence est que la `\usepackage` ne peut pas être utilisé avant `\documentclass` la commande. Il est fortement recommandé d’utiliser `\RequirePackage` lors de la rédaction de nouveaux packages ou de nouvelles classes. [Ouvrir un exemple de rédaction d’un package dans Overleaf](https://www.sharelatex.com/project/new/template?zipUrl=/project/53f11ec1eceb82a67658cb02/download/zip\&templateName=PackageExample\&compiler=pdflatex) ### Options Pour permettre une certaine flexibilité dans les packages, quelques options supplémentaires sont très utiles. La partie suivante du fichier « examplepackage.sty » gère les paramètres transmis à l’instruction d’importation du package. ```latex \NeedsTeXFormat{LaTeX2e} \ProvidesPackage{examplepackage}[2014/08/21 Package d’exemple] \RequirePackage{imakeidx} \RequirePackage{xstring} \RequirePackage{xcolor} \definecolor{greycolour}{HTML}{525252} \definecolor{sharelatexcolour}{HTML}{882B21} \definecolor{mybluecolour}{HTML}{394773} \newcommand{\wordcolour}{greycolour} \DeclareOption{red}{\renewcommand{\wordcolour}{sharelatexcolour}} \DeclareOption{blue}{\renewcommand{\wordcolour}{mybluecolour}} \DeclareOption*{\PackageWarning{examplepackage}{Unknown ‘\CurrentOption’}} \ProcessOptions\relax ``` Ci-dessous, une description des principales commandes qui peuvent gérer les options passées au package. La commande `\DeclareOption{}{}` gère une option donnée. Elle prend deux paramètres, le premier est le nom de l’option et le second est le code à exécuter si l’option est passée. La commande `\OptionNotUsed` affichera un message dans le compilateur et dans les journaux, l’option ne sera pas utilisée. La commande `\Declareoption*{}` gère toute option non définie explicitement. Elle ne prend qu’un seul paramètre, le code à exécuter lorsqu’une option inconnue est passée. Dans ce cas, elle affichera un avertissement au moyen de la commande suivante : `\PackageWarning{}{}`. Voir [gestion des erreurs](#handling-errors) pour une description de ce que fait cette commande. `\CurrentOption` stocke le nom de l’option du package en cours de traitement à un moment donné. La commande `\ProcessOptions\relax` exécute le code pour chaque option et doit être insérée après que toutes les commandes de gestion des options aient été écrites. Il existe une version étoilée de cette commande qui exécutera les options dans l’ordre exact spécifié par les commandes appelantes. Dans l’exemple, si les options *red* ou *blue* sont passées à la `\usepackage` commande dans le document, la commande `\wordcolor` est redéfinie. Les deux couleurs et la couleur grise par défaut ont été définies dans les [déclarations préliminaires](#preliminary-declaration) après l’importation de la *xcolor* package. [Ouvrir un exemple de rédaction d’un package dans Overleaf](https://www.sharelatex.com/project/new/template?zipUrl=/project/53f11ec1eceb82a67658cb02/download/zip\&templateName=PackageExample\&compiler=pdflatex) ### Autres déclarations Dans cette partie, la plupart des commandes apparaîtront. Dans « examplepackage.sty ». Ci-dessous, vous pouvez voir le fichier complet du package. ```latex \NeedsTeXFormat{LaTeX2e} \ProvidesPackage{examplepackage}[2014/08/21 Package d’exemple] \RequirePackage{imakeidx} \RequirePackage{xstring} \RequirePackage{xcolor} \definecolor{greycolour}{HTML}{525252} \definecolor{sharelatexcolour}{HTML}{882B21} \definecolor{mybluecolour}{HTML}{394773} \newcommand{\wordcolour}{greycolour} \DeclareOption{red}{\renewcommand{\wordcolour}{sharelatexcolour}} \DeclareOption{blue}{\renewcommand{\wordcolour}{mybluecolour}} \DeclareOption*{\PackageWarning{examplepackage}{Unknown ‘\CurrentOption’}} \ProcessOptions\relax %%Environnement numéroté \newcounter{example}[section] \newenvironment{example}[1][]{\refstepcounter{example}\par\medskip \noindent \textbf{My~environment~\theexample. #1} \rmfamily}{\medskip} %%Les mots importants sont ajoutés à l’index et imprimés dans une couleur différente \newcommand{\important}[1] {\IfSubStr{#1}{!} {\textcolor{\wordcolour}{\textbf{\StrBefore{#1}{!}~\StrBehind{#1}{!}}}\index{#1}} {\textcolor{\wordcolour}{\textbf{#1}}\index{#1}\kern-1pt} } ``` Ce package définit le nouvel environnement `example`, et une nouvelle commande `\important`, qui affiche les mots dans une couleur spéciale et les ajoute à l’index. Pour bien comprendre chaque commande, voir le [guide de référence](#reference-guide) et les liens dans la [section de lecture complémentaire](#further-reading). Ci-dessous, un document qui utilise le package *examplepackage.sty*. ```latex \documentclass{article} \usepackage[utf8]{inputenc} \usepackage[red]{examplepackage} \makeindex \title{Package Example} \author{Team Learn ShareLaTeX} \date{ } \begin{document} \maketitle \section{Introduction} Dans ce document, un nouveau package est testé. Ce package permet des environnements \begin{example} Ce texte se trouve dans un environnement spécial, du texte en gras est affiché au début et une nouvelle indentation est définie. \end{example} De plus, il existe une commande spéciale pour \important{important!words} qui sera affichée dans une \important{couleur} spéciale selon le paramètre utilisé dans la déclaration d’importation de \important{package}. Parce que c’est \important{important}. \printindex \end{document} ``` ![WrittingPackagesEx1.png](/files/56709762d962010689df8e1a236c537db9bfa726) Remarquez la commande ```latex \usepackage[red]{examplepackage} ``` [Ouvrir un exemple de rédaction d’un package dans Overleaf](https://www.sharelatex.com/project/new/template?zipUrl=/project/53f11ec1eceb82a67658cb02/download/zip\&templateName=PackageExample\&compiler=pdflatex) ## Gestion des erreurs Lorsqu’il s’agit de développer de nouveaux packages, il est important de gérer les erreurs possibles pour informer l’utilisateur que quelque chose s’est mal passé. Il existe quatre commandes principales pour signaler les erreurs dans le compilateur. * `\PackageError{*package-name*}{*error-text*}{*help-text*}`. Prend trois paramètres, chacun entre accolades : le nom du package, le texte de l’erreur qui va être affiché (le processus de compilation sera suspendu), et le texte d’aide qui sera imprimé si l’utilisateur appuie sur « h » lorsque la compilation suspend à cause de l’erreur. * `\PackageWarning{*package-name*}{*warning-text*}`. Dans ce cas, le texte est affiché mais le processus de compilation ne s’arrêtera pas. Le numéro de ligne où l’avertissement s’est produit sera affiché. * `\PackageWarningNoLine{*package-name*}{*warning-text*}`. Fonctionne comme la commande précédente, mais n’affichera pas la ligne où l’avertissement s’est produit. * `\PackageInfo{*package-name*}{*info-text*}`. Dans ce cas, l’information contenue dans le second paramètre ne sera imprimée que dans le fichier de transcription, y compris le numéro de ligne. [Ouvrir un exemple de rédaction d’un package Overleaf](https://www.sharelatex.com/project/new/template?zipUrl=/project/53f11ec1eceb82a67658cb02/download/zip\&templateName=PackageExample\&compiler=pdflatex) ## Guide de référence **Liste des commandes couramment utilisées dans les packages et les classes** * `\newcommand{*name*}{*definition*}`. Définit une [nouvelle commande](/latex/fr/commandes/01-commands.md#defining-a-new-command), le premier paramètre est le nom de la nouvelle commande, le second paramètre est ce que la commande fera. * `\renewcommand{}{}`. Comme `\newcommand` mais écrasera une commande existante. * `\providecommand{}{}`. Fonctionne exactement comme `\newcommand` mais si la commande est déjà définie, celle-ci sera ignorée silencieusement. * `\CheckCommand{}{}`. La syntaxe est la même que `\newcommand`, mais au lieu de cela elle vérifiera si la commande existe et possède la définition attendue ; LaTeX affichera un avertissement si la commande n’est pas ce que `\CheckCommand` attendu. * `\setlength{}{}`. Définit la longueur de l’élément passé en premier paramètre à la valeur écrite en second paramètre. * `\mbox{}`. Crée une boîte qui contient les éléments écrits à l’intérieur des accolades. * `\fbox{}`. Comme `\mbox`, mais une boîte est réellement imprimée autour du contenu. ## Lectures complémentaires Pour plus d'informations, voir * [Comprendre les paquets et les fichiers de classe](/latex/fr/fichiers-de-classe/01-understanding-packages-and-class-files.md) * [Écrire votre propre classe](/latex/fr/fichiers-de-classe/04-writing-your-own-class.md) * [Commandes](/latex/fr/commandes/01-commands.md) et [Environnements](/latex/fr/commandes/02-environments.md) * [Longueurs en LaTeX](/latex/fr/mise-en-forme/01-lengths-in-latex.md) * [Utiliser les couleurs dans LaTeX](/latex/fr/mise-en-forme/13-using-colors-in-latex.md) * [Gestion dans un grand projet](/latex/fr/structure-du-document/07-management-in-a-large-project.md) * [LaTeX2ε pour les packages et les rédacteurs de packages](http://www.latex-project.org/guides/clsguide.pdf) * [Notes sur la programmation en TeX](http://pgfplots.sourceforge.net/TeX-programming-notes.pdf) * [Minutes en moins d’heures : utilisation des ressources LaTeX](https://tug.org/pracjourn/2005-4/hefferon/hefferon.pdf) * [The LaTeX Companion. Deuxième édition](http://ptgmedia.pearsoncmg.com/images/9780201362992/samplepages/0201362996.pdf) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://overleaf-pro.ayaka.space/latex/fr/fichiers-de-classe/03-writing-your-own-package.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.