diff --git a/logiciels/latex/nouveau_package.tml b/logiciels/latex/nouveau_package.tml new file mode 100644 index 0000000..98b3c81 --- /dev/null +++ b/logiciels/latex/nouveau_package.tml @@ -0,0 +1,517 @@ +<?xml version="1.0" encoding="ISO-8859-1"?> +<!DOCTYPE html + PUBLIC "-//ENS/Tuteurs//DTD TML 1//EN" + "tuteurs://DTD/tml.dtd"> +<html> +<head> +<title>Son package</title> +</head> +<body> + +<h1>�crire son propre package</h1> + +<h2>Pourquoi ?</h2> + +<p> +D�finir son propre package permet :</p> + +<ul> +<li>de ne pas avoir � toujours ins�rer toujours les m�mes lignes : +<pre> +\usepackage[francais]{babel} +\usepackage[latin1]{inputenc} +\usepackage[T1]{fontenc} +\usepackage[dvips]{graphicx} +\usepackage{amsmath} +\usepackage{amssymb} +</pre> +</li> +<li>de ne pas avoir � red�finir toutes ses macros et aussi de gagner +du temps � force de s'habituer � ses commandes persos ;</li> +<li>d'avoir des documents coh�rents entre eux.</li> +</ul> + +<h2>Principe</h2> + +<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 :</p> + +<ul> +<li>de charger nos extensions pr�f�r�es ;</li> +<li>de d�finir nos commandes pr�f�r�es ;</li> +<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> +<b>%% Informations g�n�rales</b> +\NeedsTeXFormat{LaTeX2e}[1999/01/01] +\ProvidesPackage{mon_package}[2003/01/01] + +<b>%% Chargement des extensions</b> +\RequirePackage[dvips]{graphicx} + +<b>%% D�claration des options</b> +\DeclareOption{option}{...} +\DeclareOption*{...} +\ProcessOptions + +<b>%% D�finition des commandes</b> +\newcommand{\blabla}{Super commande} + +<b>%% Fin du package</b> +\endinput +</pre> + +<h3>Explications</h3> + +<ul> +<li><code><b>\NeedsTeXFormat{<formar>}[<version>]</b></code> : + informe TeX du format (LaTeX2e, donc refus de LaTeX2.09, plain TeX, + 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> + <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> + <li><code><b>\RequirePackage[<options>]{<package>}</b></code> : + �quivalent de <code>\usepackage</code> pour l'�criture d'un package + ou d'une classe, on peut passer des options au package comme + habituellement ;</li> + <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> + <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> + <li><code><b>\ProcessOptions</b></code> : ex�cute le code des options + pass�es, si cette commande n'existe pas dans le package les options + seront sans effet (bien prendre conscience que les declarations + n'ex�cutent pas de code!) ;</li> + <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> + <li><code><b>\endinput</b></code> : fin du package.</li> </ul> + +<h2>Exemple simple</h2> + +<p>Supposons qu'il m'arrive d'�crire des documents sans algorithmes et +d'autres avec. Lorsque j'en ai besoin je charge les packages +<code>algorithm</code> et <code>algorithmic</code> qui permettent de +mettre en forme des algorithmes, d'en faire une � liste des +algorithmes � et de les rendre flottants (voir la page...). Je peux +encore utiliser mon propre package pour g�rer ces cas, il suffit +d'introduire une option � algo � quand on a besoin des fonctionnalit�s +idoines. Voil� comment :</p> + +<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> +La commande <code>\newif\if<i>quelquechose</i></code> cr�e trois +commandes :</p> + +<ul> +<li><code><b>\if<i>quelquechose</i></b></code> � utiliser ainsi (la +partie � else � est facultative) +<pre> +\if<i>quelquechose</i> + <i>Code si oui</i> +\else + <i>Code si non</i> +\fi +</pre></li> +<li><code><b>\<i>quelquechose</i>true</b></code> + <code>\if<i>quelquechose</i></code> devient + �quivalent � <b>if true</b> ;</li> +<li><code><b>\<i>quelquechose</i>false</b></code> + <code>\if<i>quelquechose</i></code> devient + �quivalent � <b>if false</b>.</li> +</ul> + +<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 � algo � est +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 � algo � aura �t� pass�e dans +le fichier <code>.tex</code> :</p> + +<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> + +<p><b>Remarque :</b> notons que dans les packages � @ � est une lettre +(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 +dans des cas un peu exceptionnels. Dans un fichier <code>.tex</code>, +� <code>\if@algo</code> � aurait �t� interpr�t�e comme la commande +<code>\if</code> suivie de � @algo �.</p> + +<h2>Exemple moins simple, plus r�aliste</h2> + +<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> + +<p>On d�clare comme pr�c�demment deux options � normales � : +<code>algo</code> et <code>listings</code> mais quand on est face � +une option inconnue on la passe � babel, ainsi :</p> + +<pre> +\documentclass[a4paper]{article} +\usepackage[algo, listings, english, greek, francais]{mon_package} +\begin{document} + . + . + . +\end{document} +</pre> + +<p> +sera �quivalent � charger les modules d'algorithmiques, les modules de +d'�criture de programmes, et babel avec les options +<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 +<code><options></code> � la liste d'options qui seront pass�es +au package <code><package></code> lors de l'appel +<code>\RequirePackage{<package>}</code>. +</p> + +<p> +<b>Remarque :</b> les options d�clar�es avec +<code>\DeclareOption{...}{...}</code> peuvent �tre pass�es comme +<em>options globales</em> du document comme dans : +</p> + +<pre> +\documentclass[a4paper, algo, listings]{article} +\usepackage[english, greek, francais]{mon_package} +\begin{document} + . + . + . +\end{document} +</pre> + +<p> +En revanche les langages doivent �tre pass�s au package lui-m�me +(notamment babel n'a pas tent� de trouver un langage nomm� � a4paper � +ce qui aurait abouti � une erreur). +</p> + +<h3>Limitations</h3> + +<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 +<code>\DeclareOption{...}{...}</code> et d'autre part on ne peut pas +s'abstenir de passer au moins une option de langage au package.</p> + +<h2>Exemple (tr�s) compliqu�</h2> + +<h3>Pr�requis</h3> + +<ul> + + <li>Avoir lu la doc du package <code>keyval</code> de David Carliste (ou + peut-�tre prochainement une page tuteurs � ce sujet) ;</li> + + <li> <code><b>\@ifundefined{commande}<!-- + -->{<then>}{<else>}</b></code> : si + <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) ;</li> + + <li> <code><b>\PackageWarning{<package>}<!-- + -->{<texte>}</b></code> : produit un warning lors de la + compilation (par opposition � <code>\PackageError{...}{...}</code>) ;</li> + + <li> <code><b>\CurrentOption</b></code> : l'option en cours de + traitement ;</li> + + <li>le reste c'est du TeX, donc il ne vaut mieux pas s'attarder + dessus.</li> + +</ul> + +<h3>Listing g�n�ral</h3> + +<pre> +\NeedsTeXFormat{LaTeX2e}[1999/01/01] +\ProvidesPackage{mon_package}[2003/01/01] +\RequirePackage{keyval} + +<b>%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% Pour g�rer les deux types d'options : % +% 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> + +<b>%% Options �normales�</b> +\DeclareOption{foo}{<action foo>} +\DeclareOption{bar}{<action bar>} + +<b>%% Options pass�es sous forme key=val</b> +\define@key{mypack}{<key1>}{<action 1> d�pendant de #1} +\define@key{mypack}{<key2>}[<default>]<!-- + -->{<action 2> d�pendant de #1} + +\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, +<code>key1=value1</code> va ex�cuter le code <code><action 1></code> +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 +� <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 :</p> + +<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> + +<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> + +<h3>Exemple d'application</h3> + +<p>Si <code>mon_package</code> contient :</p> + +<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 +pass�e comme une option � part. + . + . +\end{document} +</pre> + +<p>ou encore ainsi :</p> + +<pre> +\documentclass[a4paper]{article} +\usepackage{mon_package} +\newcommand{\option}{\texttt} +\begin{document} + . +Babel charg� avec l'option \option{francais}. + . + . +\end{document} +</pre> + +<p> +L� encore les options de langages ne pourront pas �tre sp�cifi�es +globalement avec la commande <code>\documentclass</code>. (La raison en est +que les options globales qui ne correspondent pas � des options d�clar�es +avec <code>\DeclareOption</code> ne sont pas transmises � +<code>\DeclareOption*</code>.) +</p> + +<h2>Utiliser son package</h2> + +<p>Le package <code>mon_package</code> doit pouvoir �tre trouv� par LaTeX, +pour cela on peut :</p> + +<ul> +<li>mettre le fichier <code>mon_package</code> dans le m�me r�pertoire que +les fichier <code>.tex</code> qui l'utilisent ;</li> +<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 +<code>export TEXINPUTS=$HOME/texmf//:</code> (certaines distributions +permettent de cr�er un fichier ls-R gr�ce � la commande +<code>texhash</code>) ;</li> +<li>si l'on est root sur sa machine on peut le mettre dans l'arborescence +texmf classique (mais �a ne facilite pas des upgrades des distributions +LaTeX) et ex�cuter la commande <code>mktexlsr</code>.</li> +</ul> + +<h2>Documentation et aide</h2> + +<p>Pour une documentation concernant l'�criture de classe et de +packages : <code>clsguide</code> (� noter �galement les documentations +<code>fntguide</code>, <code>usrguide</code>) pour une documentation +g�n�rale sur LaTeX : <code>source2e</code> ou plus soft <em>The not so +short introduction to LaTeX</em> (disponible en fran�ais !).</p> + +<p>Sur internet : <a href="http://www.ctan.org/">CTAN</a>, les +newsgroup <code>fr.comp.text.tex</code> et <code>comp.text.tex</code> sur +lesquels on peut faire une recherche <em>via</em> Google. Par +exemple comment r�aliser le symbole � 1 � avec une double +barre pour d�signer une fonction indicatrice ? La r�ponse se trouve +sur Google, groupes et taper � <code>group:fr.comp.text.tex 1 barre +indicatrice</code> �. C'est une source d'informations in�puisable. +Sinon les tuteurs ou forum <code>ens.forum.informatique.tex</code>.</p> + + <div class="metainformation"> Auteur : Josselin Noirel + (16/03/2003)</div> + +</body> +</html>