summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/drac/drac-en.dtx
blob: 332d27026bfc722d43eac85649131eaccc4e09e1 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
% \iffalse meta-comment
%-*- coding: iso-8859-15 -*-
% --------------------------------------------------------------------
% 
% Copyright (C) 2004, 2008 by Josselin Noirel et Yvon Henel 
% 
% Y. Henel dit « le TeXnicien de surface » 
% <le.texnicien.de.surface@wanadoo.fr>
%
% --------------------------------------------------------------------
% 
% This file may be distributed and/or modified under the conditions of
% the LaTeX Project Public License, either version 1.2 of this license
% or (at your option) any later version. The latest version of this
% license is in: 
%
%    <URL: http://www.latex-project.org/lppl.txt >
%
% and version 1.2 or later is part of all distributions of LaTeX
% version 1999/12/01 or later. 
%
% --------------------------------------------------------------------
% \fi
%
% \iffalse
%<package>\NeedsTeXFormat{LaTeX2e}[1999/12/01]
%<package>\def\fileversion{v1}
%<package>\def\filedate{2008/08/14}
%<package>\def\fileinfo{fichier drac.sty par J. Noirel et Y. Henel}
%<package>\ProvidesPackage{drac}
%<package>   [\filedate\space\fileversion\space\fileinfo]
%
%<*driver>
\documentclass[a4paper]{ltxdoc}
\usepackage{drac}
\usepackage{url,array}        
\usepackage[latin1]{inputenc} 
\usepackage[T1]{fontenc}
\IfFileExists{lmodern.sty}{\usepackage{lmodern}}{}
\usepackage{ifpdf}
\usepackage{textcomp}
\usepackage{calc, xspace} % c'est pour moi (TdS) !
\let\cs=\relax
\DeclareRobustCommand*{\cs}[1]{{\normalfont\ttfamily\char`\\#1}}
\renewcommand*{\meta}[1]{{\normalfont\textlangle{\itshape #1\/}\textrangle}}
\newcommand*{\fctt}{{\normalfont\ttfamily fr.comp.text.tex}}
\makeatletter
\DoNotIndex{\@tempa,\@tempb,\@tempc,\csname,\endcsname,\noexpand,\def,^^A
  \edef,\ifx,\else,\endinput,\expandafter,\fi,\let,\newcommand,\relax,^^A
  \string,\@ifstar}
\makeatother
\usepackage[frenchb,english]{babel}
% comment out the following line to obtain the full code with explanations
\OnlyDescription
\EnableCrossrefs         
\CodelineIndex
\RecordChanges
\newcommand\BOP{\discretionary{}{}{}}
\begin{document}
\DocInput{drac-en.dtx}
\end{document}
%</driver>
% \fi
% \CheckSum{68}
%
% \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         \~}
%
% \changes{v0}{2004/04/22}{Missed to be the 1st public version}
% \changes{v0.1}{2004/05/17}{Almost have been the 1st public version}
% \changes{v0.1}{2004/05/17}{Introduces \cs{ReDeclareRobActChar}}
% \changes{v1}{2008/08/14}{First public version}
% \GetFileInfo{drac.sty}
%
% \title{The \textsf{drac} package\thanks{This document corresponds to
%     the file \textsf{drac}~\fileversion, dated \filedate.}}
% \author{Josselin Noirel and Yvon Henel}
%
% \maketitle
% \begin{abstract}
%   This package provides \cs{DeclareRobustActChar} and
%   \cs{Re}\BOP|Declare|\BOP|Rob|\BOP|Act|\BOP|Char| macros.
%
%   One uses \cs{DeclareRobustActChar} as \cs{DeclareRobustCommand}
%   but the macro \cs{protect}s the active character when it appears
%   in a moving argument, see~\path{ltdefns.dtx} in
%   \path{/latex/base/}.
%
%   \cs{ReDeclareRobActChar} redefines the active character,
%   previously defined with \cs{DeclareRobustActChar}, the way
%   \cs{renewcommand} does for usual commands.
% \end{abstract}
% \begin{otherlanguage}{french}
% \begin{abstract}
%   Ce module définit \cs{DeclareRobustActChar} et
%   \cs{ReDeclareRobActChar}.
%
%   Vous devriez avoir obtenu, avec ce document, les fichiers
%   \path{drac-fr.dtx} et \path{drac-fr.pdf} qui donnent la version
%   française de cette documentation.
% \end{abstract}
% \end{otherlanguage}
%
% \tableofcontents
% 
% \section{Introduction}
% \begingroup\footnotesize{}
% 
% When the macro appeared on \fctt{} in the thread ``la question à
% 100~euros\footnote{The 100~euro question.}'', dated
% \oldstylenums{8}th april \oldstylenums{2004}, its name was
% \cs{DeclareRobustActiveCharacter} which had the advantage to be
% totally descriptive but one drawback viz.\ it was really long. To
% alleviate the pains of the typist but \emph{mainly} to avoid a
% complete mess in the index of this document, I have taken it upon
% myself to rename it \cs{DeclareRobustActChar}.
% 
% When reading the above mentioned thread, one can easily see that I
% ---{i\@. e\@.} Yvon Henel, \TeX nicien de surface--- just asked for
% code which was provided, very friendly and efficiently, by Josselin
% Noirel.  
% 
% I played a bit with Josselin's code but some months later life hit
% me hard which would not have been a surprise if I had really
% understood the classical wisdom I have been educated in during
% my younger days. But ``the light, which experience gives, is a
% lantern on the stern, which shines only on the waves behind us'' as
% wrote Samuel Taylor Coleridge. Thence when Josselin, who was rather
% busy as a student, sent me with an email in February
% \oldstylenums{2005} a second version where \cs{ReDeclareRobActChar}
% appeared I was in no state to benefit from it. 
% 
% Then time, the great healer, did fly\dots I'm back to the world and
% Josselin has left for other shores. 
% 
% The code exists and works. So instead of leaving it to rot somewhere
% on my hard disk and for I have spent somme hours to update my own
% packages I have decided to launch \texttt{drac} on the vast ocean of
% life. I just provide the wrapping and push the tiny thing on the
% nearest CTAN server. 
% 
% I do suppose that one understood that I can't promise to maintain
% the following code I hardly understand and that only because of the
% comments given by Josselin. So now is the time to let Josselin be
% at the helm\dots and the keyboard. 
% 
% \hspace*{\stretch{4}}Le \TeX nicien de surface\hspace*{\stretch{1}}
%
% \endgroup
% 
% \section{Usage}
% 
% This command has the usual syntax of the \cs{newcommand} and
% friends: it accepts a starred form depending on wether the active
% character accepts \cs{long} arguments (\emph{i.e.} an argument could
% contain a paragraph ending) or not; next comes the active character;
% an optionnal number of arguments, an optionnal argument which is the
% optionnal value of the first argument, and then the actual
% definition. Here are the valid syntaxes:
% ^^A
% \begin{list}{}{\ttfamily\leftmargin=\leftmargini}\item
% \cs{DeclareRobustActChar}\marg{active character}[\(n\)]\%\\
% \ \ \oarg{default value of the first argument}\marg{definition}\par
% \cs{DeclareRobustActChar}\marg{active character}[\(n\)]\marg{definition}\par
% \cs{DeclareRobustActChar}\marg{active character}\marg{definition}\par
% \cs{DeclareRobustActChar}*\marg{active character}[\(n\)]\%\\
% \ \ \oarg{default value of the first argument}\marg{definition}\par
% \cs{DeclareRobustActChar}*\marg{active character}[\(n\)]\marg{definition}\par
% \cs{DeclareRobustActChar}*\marg{active character}\marg{definition}
% \end{list}
% ^^A
% Then one will be able to use the active character in moving
% arguments (in the arguments of \cs{caption} for instance) and in
% other cases which demand robust commands
% (\cs{protected@edef},\cs{protected@write}, and so on).
% 
% Similarly \cs{ReDeclareRobActChar} has the same syntax than
% \cs{renewcommand} so here are the possible syntaxes:
% ^^A
% \begin{list}{}{\ttfamily\leftmargin=\leftmargini}\item
% \cs{ReDeclareRobActChar}\marg{active character}[\(n\)]\%\\
% \ \ \oarg{default value of the first argument}\marg{definition}\par
% \cs{ReDeclareRobActChar}\marg{active character}[\(n\)]\marg{definition}\par
% \cs{ReDeclareRobActChar}\marg{active character}\marg{definition}\par
% \cs{ReDeclareRobActChar}*\marg{active character}[\(n\)]\%\\
% \ \ \oarg{default value of the first argument}\marg{definition}\par
% \cs{ReDeclareRobActChar}*\marg{active character}[\(n\)]\marg{definition}\par
% \cs{ReDeclareRobActChar}*\marg{active character}\marg{definition}
% \end{list}
% ^^A
% \StopEventually{\PrintChanges\PrintIndex}
%
% \section{The code}
% \begin{macro}{\DeclareRobustActChar}
%   We begin whith the definition of \cs{DeclareRobustActChar} (which
%   does not make a lot in fact).
% ^^A
%    \begin{macrocode}
% \iffalse
%<*package>
% \fi
\newcommand*{\DeclareRobustActChar}{
  \@ifstar{%
    \def\@tempc{\newcommand*}\@declarerobustactchar}{%
    \def\@tempc{\newcommand}\@declarerobustactchar}%
}
%    \end{macrocode}
% \end{macro}
% ^^A
% \begin{macro}{\ReDeclareRobActChar}
% And immediately we define \cs{ReDeclareRobActChar} (which, as the
% preceding one does not make a lot but slightly differently.)
% ^^A
%    \begin{macrocode}
\newcommand*{\ReDeclareRobActChar}{\@ifstar{%
    \def\@tempc{\renewcommand*}\@declarerobustactchar}{%
    \def\@tempc{\renewcommand}\@declarerobustactchar}%
}
%    \end{macrocode}
% ^^A
% \cs{@ifstar} checks the presence of a star and \cs{@tempc} is
% defined accordingly. \cs{@tempc} will in its time undertake the
% definition. Then \cs{@declarerobustactchar} is summoned.
% \end{macro}
% \begin{macro}{\@declarerobustactchar}
% Here comes the macro which does work:
% \cs{@declarerobustactchar}.  It takes an argument which is the
% active character (which is supposed to be \emph{already} active 
% when\cs{DeclareRobustActChar} is called in).
% ^^A
%    \begin{macrocode}
\newcommand*{\@declarerobustactchar}[1]{%
%    \end{macrocode}
% ^^A
% The present values of \cs{protect} and \cs{@typeset@protect} are
% preserved to be restored later.
% ^^A
%    \begin{macrocode}
  \let\@tempa=\protect
  \let\@tempb=\@typeset@protect
%    \end{macrocode}
% ^^A
% \cs{protect} and \cs{@typeset@protect} are defined as equivalent to 
% \cs{relax} for them not to `move' during the process of expansion in 
% \cs{edef}.  
% ^^A
%    \begin{macrocode}
  \let\protect=\relax
  \let\@typeset@protect\relax % Should be the case
%    \end{macrocode}
% ^^A
% The active character is defined. Caution: if the character is not
% active when one uses \cs{DeclareRobustActChar} there is a
% considerable risk of making \TeX{} growls about an `inaccessible'
% command. The \meta{active character} is defined as:
% ^^A
% \begin{flushleft}\begin{tabular}{@{}l@{}l@{}}
% \meta{active character} $\stackrel{\mathrm{def}}{\equiv}$ \hskip0pt &
% \cs{ifx}\cs{protect}\cs{@typeset@protect} \\
%    & \ttfamily\ \ \cs{expandafter}\cs{DRAC@real@\meta{active character}} \\
%    & \cs{else} \\
%    & \ttfamily\ \ \cs{protect}\meta{active character} \\
%    & \cs{fi} \\
% \end{tabular}\end{flushleft}
% ^^A
% The \cs{ifx} test enables us to know whether we are in the context
% of a moving argument or not. The result of the test is `true' if it
% is not the case; then \cs{DRAC@real@\meta{active character}} is
% executed: it is the effecting command which will contain in some
% time the \meta{definition} to which we were refering above.  When
% the test is `false', because we are in the context of a moving
% argument we simply \cs{protect} the \meta{active character} and put
% it back.  The \cs{expandafter} is there to make the chunk of code
% `\cs{else}\linebreak[0]\dots\linebreak[0]\cs{fi}' disappear.
% ^^A
%    \begin{macrocode}
  \edef#1{%
    \noexpand\ifx\protect\@typeset@protect
      \noexpand\expandafter
      \expandafter\noexpand
      \csname DRAC@real@\string#1\endcsname 
    \noexpand\else   
      \protect       
      \noexpand#1%
    \noexpand\fi
  }%
%    \end{macrocode}
% ^^A
% The initial values of \cs{protect} and \cs{@typeset@protect} are
% restored. 
% ^^A
%    \begin{macrocode}
  \let\protect=\@tempa
  \let\@typeset@protect=\@tempb
%    \end{macrocode}
% ^^A
% Now we define with \cs{newcommand} ---~by means of \cs{@tempc}, do
% you remember?~--- the effecting command \cs{DRAC@read@\meta{active
%     character}}. It is the use of \cs{newcommand} which enables us
% to protect the syntax. But one will note that it prevents, in
% particular, the redifinition of the command (in other words this
% package might still be improved).
% ^^A
%    \begin{macrocode}
  \expandafter\@tempc\csname DRAC@real@\string#1\endcsname
}
%    \end{macrocode}
% ^^A
% ``THE END''
% ^^A
%    \begin{macrocode}
\endinput
%    \end{macrocode}
% \end{macro}
% \iffalse
%</package>
% \fi
% ^^A
% \section{Bugs and restrictions}
% No known bugs at present. The restrictions are numerous: this
% package has no pretence.
% 
% It can \emph{a priori} work with commands as well but we advise you to
% use \cs{DeclareRobustCommand} instead in such a case.
% \Finale
\endinput
%%% Local Variables: 
%%% mode: doctex
%%% TeX-master: t
%%% fill-column: 70
%%% End: