% \iffalse
%<*never>
\documentclass{ltxdoc}

\usepackage[T1]{fontenc}
\usepackage[latin1]{inputenc}
\usepackage[frenchb,english]{babel}
\usepackage[]{geometry}
\usepackage{hotplug,hyperref}

\IfFileExists{parallel.sty}{%
\usepackage{parallel}
}{%
\newenvironment{Parallel}[2]{}{}
\let\ParallelLText\empty
\let\ParallelRText\empty
\let\ParallelPar\empty
\def\nopar{}
}

\ifx\nopar\undefined
  \makeatletter
  \let\@old\ParallelCheckOpenBrace
  \def\ParallelCheckOpenBrace{\@old\linewidth=\hsize}
  \makeatother
\fi
\newenvironment{ml}{\begin{Parallel}{.48\linewidth}{.48\linewidth}}{\end{Parallel}}
\def\eng{\selectlanguage{english}\ParallelLText}
\def\fra{\selectlanguage{frenchb}\ParallelRText}
\def\go{\ParallelPar}

\AtBeginDocument{\CodelineIndex\EnableCrossrefs}
\AtEndDocument{\PrintIndex}
\GetFileInfo{hotplug.sty}
\def\pack#1{\texttt{#1}}
\begin{document}
\def\docdate{2004/05/31}
\CheckSum{213}
\DocInput{hotplug.dtx}
\end{document}
%</never>
% \fi
% \iffalse meta-comment
%
% (c) 2004 Benjamin BAYART
% 
% \fi
% \CheckSum{5791}
%% \CharacterTable
%%  {Upper-case    \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
%%   Lower-case    \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
%%   Digits        \0\1\2\3\4\5\6\7\8\9
%%   Exclamation   \!     Double quote  \"     Hash (number) \#
%%   Dollar        \$     Percent       \%     Ampersand     \&
%%   Acute accent  \'     Left paren    \(     Right paren   \)
%%   Asterisk      \*     Plus          \+     Comma         \,
%%   Minus         \-     Point         \.     Solidus       \/
%%   Colon         \:     Semicolon     \;     Less than     \<
%%   Equals        \=     Greater than  \>     Question mark \?
%%   Commercial at \@     Left bracket  \[     Backslash     \\
%%   Right bracket \]     Circumflex    \^     Underscore    \_
%%   Grave accent  \`     Left brace    \{     Vertical bar  \|
%%   Right brace   \}     Tilde         \~}
%
% \title{\bfseries Hot plugging in a macro-definition\\
%                  Remplacement \`a chaud dans la d\'efinition d'une macro}
% \author{Benjamin \textsc{Bayart}\thanks{\texttt{bayartb@edgard.fdn.fr}}}
% \date{\filedate}
% \maketitle
% 
% \def\contentsname{Contents\\Table des mati\`eres}
% \tableofcontents
%
% \section{Foreword\\Introduction}
% 
% I'm French. I speak a few words of english. As most of the \TeX{} users
% are not french, I wrote (or tried to) the documentation in english.
% But this package is a bit tricky to use, with a lots of side effects,
% so I prefere to \emph{also} write the documentation in french. In case
% the french documentation states something, and the english one states
% the opposite, the french one is probably right, and you should send me an
% e-mail to help me improve my english.
% 
% \section{Hot plugging\\Remplacement \`a chaud}
% 
% \begin{ml}
% \eng{%
% The basic idea of this package is rather simple: you want to slightly
% modify a macro-command you didn't write (one from the kernel, or from
% a third party package). The usual way is that you copy the definition
% and change what you want to change. In some cases, there is no better
% solution. But in simple cases, there is a way to have a better solution.
% This package is to deal with the simple case.}
% 
% \fra{%
% L'id\'ee \`a la base de ce package est assez simple: tu souhaites
% modifier une macro dont tu n'es pas l'auteur (une macro du noyau \LaTeX,
% ou prise dans un autre package). La mani\`ere habituelle est de copier
% la d\'efinition de cette macro dans ton document, puis d'alt\'erer
% \`a loisir la copie. Dans les cas complexes, on ne peut pas faire
% autrement. Mais dans les cas simples, une m\'ethode plus \'el\'egante
% est possible. Ce package pr\'esente la m\'ethode \'el\'egante pour
% le cas simple.}
% \go
% 
% \eng{%
% This simple case is when the original macro (say |\bibliography|, the
% macro command which stand behin |\begin{bibliography}|) call one
% macro (say |\chapter|) and you want it to call another one
% (say |\section|). For this simple example, if you copy the definition,
% then your document might not work with another version of the class.
% With the \pack{hotplug} package, you can \emph{hotplug} the
% |\section| into |\bibliography| where was previously |\chapter|.}
% 
% \fra{%
% Le cas simple c'est quand la macro originale (mettons |\bibliography|,
% la macro qui se cache derri\`ere |\begin{bibliography}|) appelle
% une macro (disons |\chapter|) alors que tu veux qu'elle en appelle
% une autre (disons |\section|). Pour cet exemple simple, si tu copies
% la d\'efinition de |\bibliography|, ton document risque de ne plus
% compiler avec une autre version de la classe. Avec le package
% \pack{hotplug}, tu peux \emph{remplacer \`a chaud} le |\chapter|
% qui est dans |\bibliography| par |\section|.}
% \go
% 
% \eng{%
% To solve this problem, the solution can be:}
% 
% \fra{%
% Pour r\'esoudre ce probl\`eme, la solution pourra \^etre:}
% \go
% \end{ml}
%
% \bigskip
% \begin{verbatim}
% \HotReplace\bibliography\chapter\section
% \end{verbatim}
% 
% \section{File limit\\Nombre maximum de fichier}
% 
% \begin{ml}
% \eng{%
% During |\HotReplace| we need to have a write file descriptor
% available. If you give no options to the package, or the
% \texttt{file} option, which is the default, then a |\newwrite|
% will be issued. It you're getting short of such things (one can
% only have 16 |\newwrite| within \TeX, and \LaTeX\ already uses
% several), you can use the option |nofile|, then the macro
% |\HotFile| will be defined to use the file 15, which is choosen
% arbitrarily. You can then choose any other file which suits you
% more. It will be use \emph{only} during |\HotReplace|. It will be
% open, write and close during each single call to |\HotReplace|, so
% you can choose the file descriptor of \emph{any} file that is not
% used at the same time. For example, if you do your calls to
% |\HotReplace| \emph{before} the |\begin{document}|, then,
% you can call:}
% 
% \fra{%
% Durant le |\HotReplace|, on a besoin d'un descripteur de fichier
% en \'ecriture. Si tu ne passes pas d'option au package, ou
% l'option |file| qui est celle pas d\'efaut, le package fera appel
% \`a |\newwrite| pour se r\'eserver \emph{ad vitam et\ae{rnam}}
% un tel descripteur. Si tu n'en as plus assez (tu ne peux en avoir
% que 16 dans \TeX, et, \LaTeX\ en consomme d\'ej\`a quelques uns),
% tu peux utiliser l'option |nofile|, en pareil cas la macro
% |\HotFile| sera d\'efinie pour utiliser le descripteur num\'ero 15,
% arbitrairement choisi. Tu peux alors choisir n'importe quel
% autre descripteur qui te convienne. Il ne sera utilis\'e
% \emph{que} pendant |\HotReplace|. Il sera ouvert, \'ecrit, puis
% referm\'e, durant chacun des appels \`a |\HotReplace|, tu peux
% donc choisir n'importe quel descripteur qui n'est pas utilis\'e
% en m\^eme temps que tu fais tes remplacements. Par exmeple, si tu
% fais tes appels \`a |\HotReplace| \emph{avant} le |\begin{document}|,
% alors, tu peux faire:}
% \go
% \end{ml}
% 
% \begin{verbatim}
% \usepackage[nofile]{hotplug}
% \makeatletter
% \let\HotFile\ext@toc
% \makeatother
% \end{verbatim}
% \section{How it works\\Comment \c{c}a marche}
% 
% \begin{ml}
% \eng{%
% A technical point you might already know: suppose a |\toto|
% macro defined with:}
% 
% \fra{%
% Petit rappel technique: soit une commande |\toto| d\'efinie par:}
% \go
% \end{ml}
% 
% \bigskip
% \begin{verbatim}
% \def\toto(#1,#2){bla \bla bla}
% \end{verbatim}
% 
% \begin{ml}
% \eng{%
% The \TeX\ primitive |\meaning\toto| produces:}
% 
% \fra{%
% La primitive \TeX\ |\meaning\toto| produit:}
% \go
% \end{ml}
% 
% \begin{verbatim}
% macro:(#1,#2)->bla \bla bla
% \end{verbatim}
% 
% \begin{ml}
% \eng{%
% We will heavily use it.}
% 
% \fra{%
% On va abondament s'en servir.}
% \go
% \end{ml}
% 
% \section{Implementation\\Impl\'ementation}
% 
%    \begin{macrocode}
%<*hotplug>
\ProvidesPackage{hotplug}[2004/05/31 v1.00 Hot replace in a command def]
%</hotplug>
%    \end{macrocode}
% 
% \begin{macro}{\keep@prefix}
% \strut
% 
% \begin{ml}
% \eng{%
% The \LaTeX\ macro |\strip@prefix| reads the result of a |\meaning|
% and only keep the body of the macro (removing the arguments, it only
% keeps what is after |>|). In the same spirit, we define here a
% |\keep@prefix| which keeps this prefix.}
% 
% \fra{%
% La macro |\strip@prefix| de \LaTeX\ lit le genre de choses produites
% par |\meaning| et ne garde que le corps de la macro (tout ce qui
% est apr\`es le |>|). Dans le m\^eme esprit, on d\'efinit |\keep@prefix|
% qui garde la d\'efinition des arguments.}
% \go
% \end{ml}
% 
%    \begin{macrocode}
%<*hotplug>
\def\keep@prefix #1:#2->#3\finkeep{#2}
%</hotplug>
%    \end{macrocode}
% \end{macro}
% 
% \begin{macro}{\HotReplace}
% \strut
% 
% \begin{ml}
% \eng{%
% This macro will do the whole job. It uses a lot of |\expandafter|, thus
% it's almost impossible to read it. It will be commented in details, but
% remains hard to understand.}
% 
% \fra{%
% C'est cette macro qui fait tout le travail. Elle utilise \'enorm\'ement
% de |\expandafter|. Elle est donc presque illisible. Elle sera tr\`es
% comment\'ee, mais pas forc\'ement compr\'ehensible pour autant.}
% \go
% 
% \eng{%
% In the following explanations, we will suppose that the replace is}
% 
% \fra{%
% Dans les explications, on suppose qu'on fait le changement}
% \go
% \end{ml}
% 
% \begin{verbatim}
% \HotReplace\commande\from\to
% \end{verbatim}
% 
%    \begin{macrocode}
%<*hotplug>
\def\HotReplace#1#2#3{%
% Change #2 pour #3 dans #1
%    \end{macrocode}
% 
% \begin{ml}
% \eng{%
% We store the string |##1| in a token register.}
% 
% \fra{%
% On stocke la cha\^ine |##1| dans un registre de token.}
% \go
% \end{ml}
% 
%    \begin{macrocode}
  \@temptokena{##1}
%    \end{macrocode}
% 
% \begin{ml}
% \eng{%
% The following lines are hard to read. The first part expanded is
% |\string#2|, which produces |\from| as a string (not the token
% |\from|). Next is expanded the |\the\@temptokena| which produces
% the string |##1|. Finally, the affectation is donce. So, this is
% more or less similar to}
% 
% \fra{%
% Les lignes suivantes sont difficiles \`a lire. Le premier morceau
% ex\'ecut\'e est |\string#2|, qui produit |\from| sous forme d'une
% cha\^ine (pas le token |\from|). Ensuite est ex\'ecut\'e le
% |\the\@temptokena| qui produit la chaine |##1|. Enfin, l'affectation
% \`a lieu, c'est donc vaguement \'equivalent \`a}
% \go
% \end{ml}
% 
% \begin{verbatim}
% \@temptokena{##1\from##2\endHplug}
% \end{verbatim}
% 
% \begin{ml}
% \eng{\noindent
% with this restriction that we have the \emph{string} |\from|
% and the token |\endHplug|.}
% 
% \fra{\noindent
% \`a cette nuance qu'on a affaire \`a la cha\^ine |\from| et au
% token |\endHplug|.}
% \go
% \end{ml}
% 
%    \begin{macrocode}
  \expandafter\expandafter\expandafter\@temptokena
  \expandafter\expandafter\expandafter{%
   \expandafter\the
   \expandafter\@temptokena
   \string#2 ##2\endHplug}
%    \end{macrocode}
% 
% \begin{ml}
% \eng{%
% What we are trying to do is to define a macro which look like
% that:}
% 
% \fra{%
% Ce qu'on cherche \`a faire, c'est d\'efinir une macro qui soit de
% cette forme l\`a:}
% \go
% \end{ml}
% 
% \begin{verbatim}
% \def\preHplug#1\from#2\endHplug{\def\tmp@pre{#1}}
% \end{verbatim}
% 
% \begin{ml}
% \eng{\noindent
% where we have the string |\from|. Such that if this macro reads
% the body of |\commande|, as it is given by |\meaning| (it gives back
% a string), we will have in |\tmp@pre| all the part of the body
% that is before |\from|.}
% 
% \fra{\noindent
% o\`u l'on \`a la cha\^ine |\from|. De telle sorte que si cette
% macro lit le corps de |\commande|, tel qu'il est donn\'e par
% |\meaning| (la primitive renvoie un cha\^ine), on r\'ecup\`ere
% dans |\tmp@pre| toute la partie
% du corps de la macro qui se trouve avant |\from|.}
% \go
% 
% \eng{%
% The kind of argument expected by this macro is stored in |\@temptokena|,
% as we've seen before. So, those lines will do the job and define
% our strange |\preHplug|.}
% 
% \fra{%
% La forme d'argument attendue par cette macro est contenue dans
% |\@temptokena|, comme on vient de voir. Donc ces quelques lignes
% vont faire le boulot et d\'efinir notre |\preHplug|.}
% \go
% \end{ml}
% 
%    \begin{macrocode}
  \expandafter\def
  \expandafter\preHplug
  \the\@temptokena{\def\tmp@pre{##1}}
%    \end{macrocode}
% 
% \begin{ml}
% \eng{%
% Similarily, we build a second macro, but one which stores what is
% after |\from| in the body of |\commande|.}
% 
% \fra{%
% On cr\'ee une seconde macro sur le m\^eme mod\`ele mais qui
% garde tout ce qui se trouve apr\`es |\from| dans le corps
% de |\commande|.}
% \go
% \end{ml}
% 
%    \begin{macrocode}
  \expandafter\def
  \expandafter\postHplug
  \the\@temptokena{\def\tmp@post{##2}}
%    \end{macrocode}
%
% \begin{ml}
% \eng{%
% We now have two funny macros, |\preHplug| and |\postHplug|, which
% if called properly will cut the body of |\commande| in two
% pieces.}
% 
% \fra{%
% On se trouve donc \`a la t\^ete de deux macros |\preHplug| et
% |\postHplug| qui, convenablement appell\'ees, vont nous d\'ecouper
% le corps de |\commande| en deux morceaux.}
% \go
% 
% \eng{%
% We want to call something like}
% 
% \fra{%
% On cherche donc \`a appeler un truc du genre}
% \go
% \end{ml}
% 
% \begin{verbatim}
% \preHplug\strip@prefix\meaning\commande\endHplug
% \end{verbatim}
% 
% \begin{ml}
% \eng{\noindent
% to take the beginning of the body (and the same with |\post|),
% but it needs to be expanded in a strange order: first expand
% |\meaning|, which will produce the whole text, then |\strip@prefix|
% which will remove the part |macro:...->|, then finaly expand
% |\preHplug|. This is why there are so many |\expandafter|.}
% 
% \fra{\noindent
% pour r\'ecup\'erer le d\'ebut (et la m\^eme chose avec |\post|),
% mais il faut ex\'ecuter les choses dans un ordre bizare: d'abord
% |\meaning|, qui va produire le texte complet, puis |\strip@prefix|
% qui va retirer la partie |macro:...->|, puis enfin ex\'ecuter
% la macro |\preHplug|. C'est ce qu'on fait avec la multitude de
% |\expandafter|.}
% \go
% \end{ml}
% 
%    \begin{macrocode}
  \expandafter\expandafter
  \expandafter\preHplug
  \expandafter\strip@prefix
              \meaning#1\endHplug
%    \end{macrocode}
% 
% \begin{ml}
% \eng{%
% We now have in |\tmp@pre| the body of the macro |\commande| up to
% |\from|, without it. We do the same with |\postHplug| to get
% |\tmp@post|.}
% 
% \fra{%
% On a donc dans |\tmp@pre| le corps de la macro jusqu'\`a |\from|
% exclus. On fait le m\^eme appel, avec |\postHplug| pour r\'ecup\'erer
% |\tmp@post|.}
% \go
% \end{ml}
% 
%    \begin{macrocode}
  \expandafter\expandafter
  \expandafter\postHplug
  \expandafter\strip@prefix
              \meaning#1\endHplug
%    \end{macrocode}
% 
% \begin{ml}
% \eng{%
% We now want to get the kind of arguments expected by |\commande|,
% which is a bit easier: |\keep@prefix| have been previously defined
% to do that. It works a bit like |\preHplug| but was easier do define,
% the required delimiter in the arguments (namely the strings |:|
% and |->|) where already known, which is not the case for |\preHplug|
% where the delimiter (the string |\from|) was only learned recently.}
% 
% \fra{%
% On cherche maintenant \`a r\'ecup\'erer la forme d'argument
% attendue par |\commande|, c'est un tout petit peu plus simple,
% |\keep@prefix|, qui fonctionne un peu comme |\preHplug| a
% d\'ej\`a \'et\'e d\'efinie (on pouvait la d\'efinir avant,
% on connaissait les d\'elimiteurs n\'ecessaires dans ses arguments,
% ce qui n'est pas le cas pour |\preHplug|).}
% \go
% \end{ml}
% 
%    \begin{macrocode}
  \edef\tmp@args{\expandafter\keep@prefix\meaning#1\finkeep}
%    \end{macrocode}
% 
% \begin{ml}
% \eng{%
% We now have in |\tmp@args| the kind of arguments of |\commande|,
% in |\tmp@pre| the beginning of its definition, and in |\tmp@post|
% the end of its definition.}
% 
% \fra{%
% On a donc maintenant dans |\tmp@args| la forme d'arguments de
% |\commande|, dans |\tmp@pre| le d\'ebut de la d\'efinition, et
% dans |\tmp@post| la fin de cette d\'efinition.}
% \go
% 
% \eng{%
% We want \TeX\ to read a brand new definition of the macro,
% but now, it have been transformed in a string. It cannot
% anymore be transformed straightly in a real macro. For that
% purpose, we are going to write in a file the \emph{string}
% which defined the macro, and then ask \TeX\ to read this brand
% new file.}
% 
% \fra{%
% On veut que \TeX\ lise une nouvelle d\'efinition de la macro,
% mais maintenant que tout cela est sous forme de cha\^ines, \c{c}a
% n'a aucune chance de re-devenir facilement une vraie macro.
% Pour cette raison, on va \'ecrire le \emph{texte} de notre
% nouvelle d\'efinition dans un fichier, puis demande \`a \TeX\ de
% bien vouloir lire ce nouveau fichier.}
% \go
% 
% \eng{%
% We are going to write in a temporary file a string like}
% 
% \fra{
% On va \'ecrire dans un fichier temporaire la forme suivante}
% \go
% \end{ml}
% 
% \begin{verbatim}
% \def\commande\tmp@args{\tmp@pre\to\tmp@post}
% \end{verbatim}
% 
% \begin{ml}
% \eng{\noindent
% string in which all the macros a expanded to their definitions,
% except |\def|, |\commande|, and |\to|, and where the braces
% are kept.}
% 
% \fra{\noindent
% forme dans laquelle toutes les macros sont remplac\'ees par
% leur d\'efinition sauf |\def|, |\commande|, et |\to| et o\`u
% les accolades sont conserv\'ees.}
% \go
% 
% \eng{%
% First, we open the file:}
% 
% \fra{%
% On commence par ouvrir le fichier:}
% \go
% \end{ml}
% 
%    \begin{macrocode}
  \immediate\openout\HotFile hotplug.tmp\relax
%    \end{macrocode}
% 
% \begin{ml}
% \eng{%
% Then, we write, with |\noexpand| before the part to be kept
% unchanged (the three macros and the braces).}
% 
% \fra{%
% Puis on fait l'\'ecriture, en mettant des |\noexpand| devant
% tout ce qu'on souhaite conserver tel quel (les trois commandes
% et les deux accolades).}
% \go
% \end{ml}
% 
%    \begin{macrocode}
  \immediate\write\HotFile{%
    \noexpand\def
    \noexpand#1%
      \tmp@args\noexpand{\tmp@pre\noexpand#3\tmp@post\noexpand}}\relax
  \immediate\closeout\HotFile
%    \end{macrocode}
% 
% \begin{ml}
% \eng{%
% Now, the file contains \TeX\ code which, if read, will redefine
% |\commande| while changing the first appearance of |\from| by
% |\to|. So we do, and the job is ended.}
% 
% \fra{%
% Maintenant, le fichier contient du code \TeX\ qui, s'il \'etait lu
% red\'efinirait |\commande| en ayant remplac\'e la premi\`ere
% occurence de |\from| par |\to|. On va donc s'empresser de lire
% le fichier, et le tour sera jou\'e.}
% \go
% \end{ml}
% 
%    \begin{macrocode}
  \input{hotplug.tmp}
}
%</hotplug>
%    \end{macrocode}
% \end{macro}
% 
% 
% \begin{ml}
% \eng{%
% The last thing to be done is to allocate a write handle for our
% temporary file. Our file is \emph{really} temporary, since it is
% only used during the use of the macro itself. If you run short of
% files in your document (which is often my case), then you can
% bypass this by using any other file descriptor which is not
% used when you call |\HotReplace|.}
% 
% \fra{%
% Il ne nous reste plus qu'\`a d\'efinir le fichier temporaire dans
% lequel on \'ecrite. Ce fichier est \emph{vraiment} temporaire, il
% ne peut \^etre utilis\'e que pendant l'ex\'ecution de la macro
% |\HotReplace|. Si tu es as cours de fichiers (comme c'est souvent
% mon cas), alors du peux \'eviter cette allocation, et utiliser
% tout autre descripteur de fichier qui n'est pas utile pendant
% que tu utilises |\HotReplace|.}
% \go
% \end{ml}
% 
%    \begin{macrocode}
%<*hotplug>
\DeclareOption{nofile}{\hotfilefalse}
\DeclareOption{file}{\hotfilefalse}
\newif\ifhotfile
\hotfiletrue
\ProcessOptions
\ifhotfile
  \newwrite\HotFile
\else
  \chardef\HotFile15\relax
\fi
%</hotplug>
%    \end{macrocode}
% 
 
% \setcounter{IndexColumns}{2}
% \Finale
%
\endinput

