2009-09-20 12:34:28 +02:00
<?xml version="1.0" encoding="UTF-8"?>
2003-03-18 01:15:44 +01:00
<!DOCTYPE html
PUBLIC "-//ENS/Tuteurs//DTD TML 1//EN"
"tuteurs://DTD/tml.dtd">
<html>
<head>
<title>Son package</title>
</head>
<body>
2009-09-20 12:27:14 +02:00
<h1>Écrire son propre package</h1>
2003-03-18 01:15:44 +01:00
2009-09-20 12:27:14 +02:00
<h2>Pourquoi
2003-03-18 01:15:44 +01:00
<p>
2009-09-20 12:27:14 +02:00
Définir son propre package permet
2003-03-18 01:15:44 +01:00
<ul>
2009-09-20 12:27:14 +02:00
<li>de ne pas avoir à toujours insérer toujours les mêmes lignes
2003-03-18 01:15:44 +01:00
<pre>
\usepackage[francais]{babel}
\usepackage[latin1]{inputenc}
\usepackage[T1]{fontenc}
\usepackage[dvips]{graphicx}
\usepackage{amsmath}
\usepackage{amssymb}
</pre>
</li>
2009-09-20 12:27:14 +02:00
<li>de ne pas avoir à redéfinir toutes ses macros et aussi de gagner
du temps à force de s'habituer à ses commandes persos
<li>d'avoir des documents cohérents entre eux.</li>
2003-03-18 01:15:44 +01:00
</ul>
<h2>Principe</h2>
2009-09-20 12:27:14 +02:00
<p>Nous allons créer un fichier « <code>mon_package.sty</code> » (ou
tout autre nom qui ne crée de doublon) qui comportera les instructions
qui permettront
2003-03-18 01:15:44 +01:00
<ul>
2009-09-20 12:27:14 +02:00
<li>de charger nos extensions préférées
<li>de définir nos commandes préférées
2003-03-18 01:15:44 +01:00
<li>de passer des options lors du chargement du package qui lui
donneront un comportement particulier.</li>
</ul>
<h2>Organisation</h2>
<h3>Listing</h3>
<pre>
2009-09-20 12:27:14 +02:00
<b>%% Informations générales</b>
2003-03-18 01:15:44 +01:00
\NeedsTeXFormat{LaTeX2e}[1999/01/01]
\ProvidesPackage{mon_package}[2003/01/01]
<b>%% Chargement des extensions</b>
\RequirePackage[dvips]{graphicx}
2009-09-20 12:27:14 +02:00
<b>%% Déclaration des options</b>
2003-03-18 01:15:44 +01:00
\DeclareOption{option}{...}
\DeclareOption*{...}
\ProcessOptions
2009-09-20 12:27:14 +02:00
<b>%% Définition des commandes</b>
2003-03-18 01:15:44 +01:00
\newcommand{\blabla}{Super commande}
<b>%% Fin du package</b>
\endinput
</pre>
<h3>Explications</h3>
<ul>
2012-02-23 16:49:02 +01:00
<li><code><b>\NeedsTeXFormat{<format>}[<version>]</b></code>
2003-03-18 01:15:44 +01:00
informe TeX du format (LaTeX2e, donc refus de LaTeX2.09, plain TeX,
2009-09-20 12:27:14 +02:00
eplain TeX, AMS-TeX, etc.) nécessaire pour l'utilisation du
package, on peut spécifier un argument optionnel (entre crochets)
permettant d'utiliser des versions récentes dudit format
<li><code><b>\ProvidesPackage{<package>}[<version>]</b></code>
le package s'identifie (là encore on peut donner en argument
optionnel une date de version)
<li><code><b>\RequirePackage[<options>]{<package>}</b></code>
équivalent de <code>\usepackage</code> pour l'écriture d'un package
2003-03-18 01:15:44 +01:00
ou d'une classe, on peut passer des options au package comme
2009-09-20 12:27:14 +02:00
habituellement
<li><code><b>\DeclareOption{<option>}{<action>}</b></code>
déclare une option qui peut être passée lors de l'appel du
package, lorsque l'option <code><option></code> est passée
<code><action></code> est exécutée
<li><code><b>\DeclareOption*{<action>}</b></code>
comportement adopté par le package quand il est confronté à une
option passée qui n'est pas déclarée
<li><code><b>\ProcessOptions</b></code>
passées, si cette commande n'existe pas dans le package les options
2003-03-18 01:15:44 +01:00
seront sans effet (bien prendre conscience que les declarations
2009-09-20 12:27:14 +02:00
n'exécutent pas de code!)
<li><code><b>\newcommand{\commande}{<code>}</b></code>
définition d'une nouvelle commande (voir la page sur les
<a href="&url.tuteurs;logiciels/latex/macros.html">macros</a>)
<li><code><b>\endinput</b></code>
2003-03-18 01:15:44 +01:00
<h2>Exemple simple</h2>
2009-09-20 12:27:14 +02:00
<p>Supposons qu'il m'arrive d'écrire des documents sans algorithmes et
2003-03-18 01:15:44 +01:00
d'autres avec. Lorsque j'en ai besoin je charge les packages
<code>algorithm</code> et <code>algorithmic</code> qui permettent de
2009-09-20 12:27:14 +02:00
mettre en forme des algorithmes, d'en faire une «
algorithmes
encore utiliser mon propre package pour gérer ces cas, il suffit
d'introduire une option «
idoines. Voilà comment
2003-03-18 01:15:44 +01:00
<pre>
<b>%% (...) \NeedsTeXFormat et \ProvidesPackage</b>
\newif\if@algo \@algofalse
\DeclareOption{algo}{\@algotrue}
\DeclareOption*{}<b>%% Ne rien faire quand une option est inconnue</b>
\ProcessOptions
\if@algo
\RequirePackage{algorithm}
\RequirePackage{algorithmic}
\RequirePackage{mes-commandes-algo}
\newcommand{\algorithme}{Blabla}
\fi
<b>%% (...) \newcommand's et \endinput</b>
</pre>
<p>
2009-09-20 12:27:14 +02:00
La commande <code>\newif\if<i>quelquechose</i></code> crée trois
commandes
2003-03-18 01:15:44 +01:00
<ul>
2009-09-20 12:27:14 +02:00
<li><code><b>\if<i>quelquechose</i></b></code>
partie «
2003-03-18 01:15:44 +01:00
<pre>
\if<i>quelquechose</i>
<i>Code si oui</i>
\else
<i>Code si non</i>
\fi
</pre></li>
2009-09-20 12:27:14 +02:00
<li><code><b>\<i>quelquechose</i>true</b></code>
<code>\if<i>quelquechose</i></code>
équivalent à <b>if true</b>
<li><code><b>\<i>quelquechose</i>false</b></code>
<code>\if<i>quelquechose</i></code>
équivalent à <b>if false</b>.</li>
2003-03-18 01:15:44 +01:00
</ul>
2009-09-20 12:27:14 +02:00
<p>Dans notre exemple on crée une instruction conditionnelle
<code>\if@algo</code> qui est équivalente à <b>if false</b> (à cause
de <code>\@algofalse</code>). Cependant, si l'option «
passée au package, on exécute <code>\@algotrue</code> qui a pour effet
de rendre <code>\if@algo</code> équivalent à <b>if true</b>. Les
packages relatifs à l'algo (et les commandes définies dans le bloc)
seront chargés si et seulement si l'option «
le fichier <code>.tex</code>
2003-03-18 01:15:44 +01:00
<ul>
<li>soit au niveau du <code>\usepackage</code>
<pre>
\documentclass[a4paper, dvips]{article}
\usepackage[<b>algo</b>]{mon_package}
\begin{document}
.
.
.
\end{document}
</pre></li>
<li>soit au niveau du <code>\documentclass</code>
<pre>
\documentclass[a4paper, dvips, <b>algo</b>]{article}
\usepackage{mon_package}
\begin{document}
.
.
.
\end{document}
</pre></li></ul>
2009-09-20 12:27:14 +02:00
<p><b>Remarque
(contrairement aux document <code>.tex</code> où « @ » est un symbole)
et que donc on peut écrire des noms de commandes avec « @ ». D'où les
noms <code>\makeatletter</code> et <code>\makeatother</code> utilisées
2003-03-18 01:15:44 +01:00
dans des cas un peu exceptionnels. Dans un fichier <code>.tex</code>,
2009-09-20 12:27:14 +02:00
« <code>\if@algo</code> » aurait été interprétée comme la commande
<code>\if</code> suivie de « @algo
2003-03-18 01:15:44 +01:00
2009-09-20 12:27:14 +02:00
<h2>Exemple moins simple, plus réaliste</h2>
2003-03-18 01:15:44 +01:00
<h3>Listing</h3>
<pre>
\NeedsTeXFormat{LaTeX2e}[1999/01/01]
\ProvidesPackage{mon_package}[2003/01/01]
\newif\if@algo \@algofalse
\newif\if@listings \@listingsfalse
\DeclareOption{listings}{\@listingstrue}
\DeclareOption{algo}{\@algotrue}
\DeclareOption*{\PassOptionsToPackage{\CurrentOption}{babel}}
\ProcessOptions
\RequirePackage{babel}
\if@algo
\RequirePackage{algorithm}
\RequirePackage{algorithmic}
\RequirePackage{mes-commandes-algo}
\fi
\if@listings
\RequirePackage{listings}
\RequirePackage{verbatim}
\RequirePackage{moreverb}
\RequirePackage{mes-commandes-listings}
\fi
\endinput
</pre>
<h3>Explications</h3>
2009-09-20 12:27:14 +02:00
<p>On déclare comme précédemment deux options «
<code>algo</code> et <code>listings</code> mais quand on est face à
une option inconnue on la passe à babel, ainsi
2003-03-18 01:15:44 +01:00
<pre>
\documentclass[a4paper]{article}
\usepackage[algo, listings, english, greek, francais]{mon_package}
\begin{document}
.
.
.
\end{document}
</pre>
<p>
2009-09-20 12:27:14 +02:00
sera équivalent à charger les modules d'algorithmiques, les modules de
d'écriture de programmes, et babel avec les options
2003-03-18 01:15:44 +01:00
<code>english</code>, <code>greek</code> et <code>francais</code>
(dans cet ordre). La commande <code>\PassOptionsToPackage<!--
-->{<options>}{<package>}</code> ne charge pas le package
<code><package></code>, elle rajoute les
2009-09-20 12:27:14 +02:00
<code><options></code> à la liste d'options qui seront passées
2003-03-18 01:15:44 +01:00
au package <code><package></code> lors de l'appel
<code>\RequirePackage{<package>}</code>.
</p>
<p>
2009-09-20 12:27:14 +02:00
<b>Remarque
<code>\DeclareOption{...}{...}</code> peuvent être passées comme
<em>options globales</em> du document comme dans
2003-03-18 01:15:44 +01:00
</p>
<pre>
\documentclass[a4paper, algo, listings]{article}
\usepackage[english, greek, francais]{mon_package}
\begin{document}
.
.
.
\end{document}
</pre>
<p>
2009-09-20 12:27:14 +02:00
En revanche les langages doivent être passés au package lui-même
(notamment babel n'a pas tenté de trouver un langage nommé «
ce qui aurait abouti à une erreur).
2003-03-18 01:15:44 +01:00
</p>
<h3>Limitations</h3>
2009-09-20 12:27:14 +02:00
<p>D'une part on ne peut pas utiliser ce mécanisme pour plusieurs
packages auquel on passerait les options non déclarées avec
2003-03-18 01:15:44 +01:00
<code>\DeclareOption{...}{...}</code> et d'autre part on ne peut pas
s'abstenir de passer au moins une option de langage au package.</p>
2009-09-20 12:27:14 +02:00
<h2>Exemple (très) compliqué</h2>
2003-03-18 01:15:44 +01:00
2009-09-20 12:27:14 +02:00
<h3>Prérequis</h3>
2003-03-18 01:15:44 +01:00
<ul>
<li>Avoir lu la doc du package <code>keyval</code> de David Carliste (ou
2009-09-20 12:27:14 +02:00
peut-être prochainement une page tuteurs à ce sujet)
2003-03-18 01:15:44 +01:00
<li> <code><b>\@ifundefined{commande}<!--
2009-09-20 12:27:14 +02:00
-->{<then>}{<else>}</b></code>
<code>\commande</code> (avec le backslash contrairement à l'argument
de <code>\@ifundefined</code>) n'est pas définie alors exécute
<code><then></code> sinon exécute
<code><else></code> (LaTeX interne)
2003-03-18 01:15:44 +01:00
<li> <code><b>\PackageWarning{<package>}<!--
2009-09-20 12:27:14 +02:00
-->{<texte>}</b></code>
compilation (par opposition à <code>\PackageError{...}{...}</code>)
2003-03-18 01:15:44 +01:00
2009-09-20 12:27:14 +02:00
<li> <code><b>\CurrentOption</b></code>
traitement
2003-03-18 01:15:44 +01:00
<li>le reste c'est du TeX, donc il ne vaut mieux pas s'attarder
dessus.</li>
</ul>
2009-09-20 12:27:14 +02:00
<h3>Listing général</h3>
2003-03-18 01:15:44 +01:00
<pre>
\NeedsTeXFormat{LaTeX2e}[1999/01/01]
\ProvidesPackage{mon_package}[2003/01/01]
\RequirePackage{keyval}
<b>%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2009-09-20 12:27:14 +02:00
% Pour gérer les deux types d'options : %
2003-03-18 01:15:44 +01:00
% 1. les options normales (\DeclareOption{...}{...}) %
% 2. les options type key-val option=value (\define@key{...}{...}{...}) %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%</b>
\@ifundefined{my@unusedlist}{<b>%</b>
\let\my@unusedlist\@empty}{}
\@ifundefined{my@extractkey}{<b>%</b>
\def\my@extractkey#1=#2\my@extractkey{#1}}{}
\newcommand{\ProcessUnusedOptions}[1]{<b>%</b>
\let\my@tempa\@empty
\let\my@tempb\@empty
\@for\CurrentOption:=\my@unusedlist\do{<b>%</b>
\expandafter\expandafter\expandafter\def
\expandafter\expandafter\expandafter\my@key
\expandafter\expandafter\expandafter{<b>%</b>
\expandafter\my@extractkey\CurrentOption=\my@extractkey}<b>%</b>
\@ifundefined{KV@#1@\my@key}{<b>%</b>
\edef\my@tempa{\my@tempa,\CurrentOption,}}{<b>%</b>
\edef\my@tempb{\my@tempb,\CurrentOption,}}}<b>%</b>
\@for\CurrentOption:=\my@tempa\do{<b>%</b>
\ifx\CurrentOption\@empty\else
\PackageWarning{mypack}{`\CurrentOption' not defined.}\fi}<b>%</b>
\edef\my@tempb{<b>%</b>
\noexpand\setkeys{#1}{\my@tempb}}<b>%</b>
\my@tempb
\AtEndOfPackage{\let\@unprocessedoptions\relax}}
\DeclareOption*{<b>%</b>
\expandafter\expandafter\expandafter\def
\expandafter\expandafter\expandafter\my@unusedlist
\expandafter\expandafter\expandafter{<b>%</b>
\expandafter\my@unusedlist\expandafter,<b>%</b>
\CurrentOption}}
<b>%%%%%%%%%%%%%%%
% Fin du bloc %
%%%%%%%%%%%%%%%</b>
2009-09-20 12:27:14 +02:00
<b>%% Options «normales»</b>
2003-03-18 01:15:44 +01:00
\DeclareOption{foo}{<action foo>}
\DeclareOption{bar}{<action bar>}
2009-09-20 12:27:14 +02:00
<b>%% Options passées sous forme key=val</b>
\define@key{mypack}{<key1>}{<action 1> dépendant de #1}
2003-03-18 01:15:44 +01:00
\define@key{mypack}{<key2>}[<default>]<!--
2009-09-20 12:27:14 +02:00
-->{<action 2> dépendant de #1}
2003-03-18 01:15:44 +01:00
\ProcessOptions
\ProcessUnusedOptions{mypack}
\endinput
</pre>
<h3>Explications</h3>
<p>Dans l'exemple suivant</p>
<pre>
\documentclass[foo]{article}
\usepackage[foo, key1=value1, key2=value2]{mypack}
\begin{document}
.
.
.
\end{document}
</pre>
<p>l'option <code>foo</code> va agir comme dans les exemples simples,
2009-09-20 12:27:14 +02:00
<code>key1=value1</code> va exécuter le code <code><action 1></code>
2003-03-18 01:15:44 +01:00
en utilisant <code>value1</code> en lieu et place de <code>#1</code>. Idem
pour <code>key2=value2</code> sauf que on peut omettre la partie
2009-09-20 12:27:14 +02:00
« <code>=value2</code> » auquel cas <code><action 2></code> est exécuté
en utilisant <code><default></code> à la place de <code>#1</code>.
Par exemple si <code>mon_package.sty</code> contient
2003-03-18 01:15:44 +01:00
<pre>
<b>%% (...) </b>
\newcounter{nombre}
\define@key{mypack}{number}[14]{%
\setcounter{nombre}{#1}}
<b>%% (...) </b>
</pre>
<p>on pourra l'appeler ainsi</p>
<pre>
\documentclass[foo]{article}
\usepackage[number=10]{mypack}
\begin{document}
.
\thenombre\ affiche 10.
.
.
\end{document}
</pre>
<p>ou encore comme cela</p>
<pre>
\documentclass[foo]{article}
\usepackage[number]{mypack}
\begin{document}
.
\thenombre\ affiche 14.
.
.
\end{document}
</pre>
2009-09-20 12:27:14 +02:00
<p>ou bien sûr sans option du tout (auquel cas le code
<code>\setcounter</code> ne sera pas exécuté et donc le compteur
<code>nombre</code> vaudra zéro).</p>
2003-03-18 01:15:44 +01:00
<h3>Exemple d'application</h3>
2009-09-20 12:27:14 +02:00
<p>Si <code>mon_package</code> contient
2003-03-18 01:15:44 +01:00
<pre>
\newcommand{\pack@languages}{francais}
\define@key{mypack}{language}{%
\renewcommand{\pack@languages}{#1}}
\RequirePackage[\pack@languages]{babel}
</pre>
<p>alors on peut l'appeler ainsi</p>
<pre>
\documentclass[a4paper]{article}
\usepackage[<b>language={english, francais}</b>]{mon_package}
\newcommand{\option}{\texttt}
\begin{document}
.
\paragraph{Remarque}
Noter les accolades pour que l'option \option{francais} ne soit pas
2009-09-20 12:27:14 +02:00
passée comme une option à part.
2003-03-18 01:15:44 +01:00
.
.
\end{document}
</pre>
2009-09-20 12:27:14 +02:00
<p>ou encore ainsi
2003-03-18 01:15:44 +01:00
<pre>
\documentclass[a4paper]{article}
\usepackage{mon_package}
\newcommand{\option}{\texttt}
\begin{document}
.
2009-09-20 12:27:14 +02:00
Babel chargé avec l'option \option{francais}.
2003-03-18 01:15:44 +01:00
.
.
\end{document}
</pre>
<p>
2009-09-20 12:27:14 +02:00
Là encore les options de langages ne pourront pas être spécifiées
2003-03-18 01:15:44 +01:00
globalement avec la commande <code>\documentclass</code>. (La raison en est
2009-09-20 12:27:14 +02:00
que les options globales qui ne correspondent pas à des options déclarées
avec <code>\DeclareOption</code> ne sont pas transmises à
2003-03-18 01:15:44 +01:00
<code>\DeclareOption*</code>.)
</p>
<h2>Utiliser son package</h2>
2009-09-20 12:27:14 +02:00
<p>Le package <code>mon_package</code> doit pouvoir être trouvé par LaTeX,
pour cela on peut
2003-03-18 01:15:44 +01:00
<ul>
2009-09-20 12:27:14 +02:00
<li>mettre le fichier <code>mon_package</code> dans le même répertoire que
les fichier <code>.tex</code> qui l'utilisent
<li>mettre le fichier dans un répertoire de son compte (par exemple
<code>~/texmf/tex/latex/perso/</code> et créer la variable d'environnement
2003-03-18 01:15:44 +01:00
<code>export TEXINPUTS=$HOME/texmf//:</code> (certaines distributions
2009-09-20 12:27:14 +02:00
permettent de créer un fichier ls-R grâce à la commande
<code>texhash</code>)
2003-03-18 01:15:44 +01:00
<li>si l'on est root sur sa machine on peut le mettre dans l'arborescence
2009-09-20 12:27:14 +02:00
texmf classique (mais ça ne facilite pas des upgrades des distributions
LaTeX) et exécuter la commande <code>mktexlsr</code>.</li>
2003-03-18 01:15:44 +01:00
</ul>
<h2>Documentation et aide</h2>
2009-09-20 12:27:14 +02:00
<p>Pour une documentation concernant l'écriture de classe et de
packages
<code>fntguide</code>, <code>usrguide</code>)
générale sur LaTeX
short introduction to LaTeX</em> (disponible en français
2003-03-18 01:15:44 +01:00
2009-09-20 12:27:14 +02:00
<p>Sur internet
2014-10-26 21:40:25 +01:00
newsgroup <code><a href="https://groups.google.com/forum/#!forum/fr.comp.text.tex">fr.comp.text.tex</a></code> et <code><a href="https://groups.google.com/forum/#!forum/comp.text.tex">comp.text.tex</a></code> auxquels on peut accéder <em>via</em> Google. Par
2009-09-20 12:27:14 +02:00
exemple
2014-10-26 21:40:25 +01:00
barre pour désigner une fonction indicatrice
en cherchant « <code>1 barre
indicatrice</code> ». C'est une source d'informations inépuisable.</p>
<p>Un autre site utile est <a href="https://tex.stackexchange.com/">le site
2014-10-26 21:48:46 +01:00
StackExchange dédié à TeX et LaTeX</a>.</p>
2003-03-18 01:15:44 +01:00
2009-09-27 22:00:55 +02:00
<div class="metainformation"> Auteur
2007-07-17 12:01:59 +02:00
</div>
2003-03-18 01:15:44 +01:00
</body>
</html>
