Debian Codegraph @

texmf-dist/source/latex/ted/ted.dtx

raw
1 %
2 % \iffalse /!\ this file contains non-ascii -- encoding is utf-8 /!\
3 %
4 % ted package by Manuel P\'egouri\'e-Gonnard <[email protected]>
5 % -----------------------------------------------------------
6 %
7 % This work may be distributed and/or modified under the conditions of
8 % the LaTeX Project Public License, either version 1.3c of this license
9 % or (at your option) any later version. The latest version of this
10 % license is in:
11 %
12 % http://www.latex-project.org/lppl.txt
13 %
14 % and version 1.3c or later is part of all distributions of LaTeX
15 % version 2006/05/20 or later.
16 %
17 % This work has the LPPL maintenance status `maintained'.
18 %
19 % The current maintainer of this work is Manuel P\'egouri\'e-Gonnard.
20 %
21 % This work consists of the file ted.dtx and the derived files ted.sty,
22 % ted.pdf and ted-fr.pdf.
23 %
24 %
25 %<*gobble>
26 \ProvidesFile{ted.dtx}
27 %</gobble>
28 %<package>\NeedsTeXFormat{LaTeX2e}
29 %<package>\ProvidesPackage{ted}
30 %<*package>
31 % \fi
32 % \ProvidesFile{ted.dtx}
33 [2008/03/07 v1.06 \space a token list editor \space (mpg)]
34 % \iffalse
35 %</package>
36 % \fi
37 % \CheckSum{816}
38 % \CharacterTable
39 % {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
40 % 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
41 % Digits \0\1\2\3\4\5\6\7\8\9
42 % Exclamation \! Double quote \" Hash (number) \#
43 % Dollar \$ Percent \% Ampersand \&
44 % Acute accent \' Left paren \( Right paren \)
45 % Asterisk \* Plus \+ Comma \,
46 % Minus \- Point \. Solidus \/
47 % Colon \: Semicolon \; Less than \<
48 % Equals \= Greater than \> Question mark \?
49 % Commercial at \@ Left bracket \[ Backslash \\
50 % Right bracket \] Circumflex \^ Underscore \_
51 % Grave accent \` Left brace \{ Vertical bar \|
52 % Right brace \} Tilde \~}
53 % \iffalse
54 %<*gobble>
55 \begingroup
56 %</gobble>
57 %<*batchfile>
58 \input docstrip
59 \keepsilent
60 \preamble
61
62 ted package by Manuel P\string\'egouri\string\'e-Gonnard %
63 <[email protected]>
64 This is a generated file. See ted.dtx for license information.
65
66 \endpreamble
67 \askforoverwritefalse
68 %\generate{\file{ted.ins}{\from{ted.dtx}{batchfile}}}
69 %\generate{\file{ted.drv}{\from{ted.dtx}{driver}}}
70 \generate{\file{ted.sty}{\from{ted.dtx}{package}}}
71 \generate{\file{ted-fr.drv}{\from{ted.dtx}{pilote}}}
72 %</batchfile>
73 %<*gobble>
74 \endgroup
75 %</gobble>
76 %<*driver|pilote>
77 \documentclass[oneside, a4paper]{ltxdoc}
78 \usepackage[utf8]{inputenc}
79 \usepackage[T1]{fontenc}
80 \usepackage{lmodern}
81 \usepackage[babel=true, expansion=false]{microtype}
82 \usepackage{fixltx2e}
83 \expandafter\newif\csname iffrenchdoc\endcsname % cachez ce if...
84 %<pilote>\frenchdoctrue
85 %</driver|pilote>
86 %<*gobble>
87 \iffrenchdoc
88 %</gobble>
89 %<*pilote>
90 \usepackage[lmargin=4.5cm, rmargin=3cm]{geometry}
91 \OnlyDescription
92 \usepackage[english, french]{babel}
93 \FrenchFootnotes \AddThinSpaceBeforeFootnotes
94 \newcommand*\eng[1]{\emph{\foreignlanguage{english}{#1}}}
95 \usepackage[bookmarks=false]{hyperref}
96 \hypersetup{%
97 pdftitle=L'extension ted
98 pdfsubject=Un éditeur de liste de lexèmes pour LaTeX2e}
99 %</pilote>
100 %<*gobble>
101 \else
102 %</gobble>
103 %<*driver>
104 \AlsoImplementation
105 \usepackage[english]{babel}
106 \usepackage[bookmarks=true, bookmarksnumbered=true, bookmarksopen=true,
107 bookmarksopenlevel=2]{hyperref}
108 \hypersetup{%
109 pdftitle=The ted package,
110 pdfsubject=A token list editor for LaTex2e}
111 \settowidth\MacroIndent{\rmfamily\scriptsize 000\ }
112 \setlength\MacroTopsep{0pt}
113 \setcounter{tocdepth}{1}
114 \usepackage[nohints, english]{minitoc}
115 \mtcsetpagenumbers{secttoc}{off}
116 \mtcsetrules{secttoc}{off}
117 \mtcsetdepth{secttoc}{3}
118 \setlength{\stcindent}{0pt}
119 \mtcsetfont{secttoc}{subsection}{\normalfont}
120 \newcommand\tocwithmini{%
121 \dosecttoc[n]
122 \setcounter{tocdepth}{1}\tableofcontents
123 \setcounter{tocdepth}{3}\faketableofcontents
124 }
125 %</driver>
126 %<*gobble>
127 \fi
128 %</gobble>
129 %<*driver|pilote>
130 \hypersetup{%
131 colorlinks=true, linkcolor=black, urlcolor=black,
132 pdfauthor=Manuel Pégourié-Gonnard}
133 \newcommand\pf{\textsf}
134 \newcommand\optstar{\meta{$*$}}
135 \newcommand\topcs[1]{\texorpdfstring{\cs{#1}}{#1}}
136 \begin{document}
137 \DocInput{ted.dtx}
138 \end{document}
139 %</driver|pilote>
140 %<*package>
141 % \fi
142 %
143 % \GetFileInfo{ted.dtx}
144 %
145 % \title{\iffrenchdoc L'extension \pf{ted}\else The \pf{ted} package\fi}
146 % \author{Manuel Pégourié-Gonnard\\
147 % \href{mailto:[email protected]}{[email protected]}}
148 % \date{\fileversion\ (\filedate)}
149 %
150 % \maketitle
151 % \iffrenchdoc\else \tocwithmini \fi
152 %
153 % \section{Introduction}
154 %
155 % \iffrenchdoc
156 %
157 % Le nom de l'extension \pf{ted} signifie \eng{token list editor}, soit
158 % en français \og éditeur de listes de lexèmes \fg{}. Comparé à
159 % \texttt{sed} dont son nom s'inspire, il n'est pas très puissant : il
160 % ne sait faire actuellement que deux choses avec les listes de lexèmes,
161 % à savoir les afficher en détail, et y opérer des substitutions.
162 % Toutefois, sa caractéristique principale est de travailler vraiment au
163 % niveau des lexèmes, et non des simples caractères.
164 %
165 % L'extension \pf{ted} est capable de faire des substitutions même à
166 % l'intérieur d'une paire d'accolades, et n'a pas de problèmes avec des
167 % lexèmes particuliers. En fait, elle est conçue pour fonctionner même
168 % avec des listes comportant des lexèmes très exotiques.
169 %
170 % \else
171 %
172 % Just like \texttt{sed} is a stream editor, \pf{ted} is a token list
173 % editor. Actually, it is not as powerful as \texttt{sed}, but its
174 % main feature is that it really works with tokens, not only characters.
175 % At the moment, it can do only two things with token lists: display it
176 % with full information on each token, and perform substitutions (that
177 % is, replacing every occurrence of a sublist with another token list).
178 %
179 % The \pf{ted} package can perform substitutions inside groups, and
180 % don't forbid any token in the lists. Actually, \pf{ted} is designed to
181 % work well even if strange tokens (that is, unusual (charcode,
182 % \cs{catcode}) pairs or tokens with a confusing \cs{meaning}) occur in
183 % the list.
184 %
185 % \fi
186 %
187 % \section{Usage}
188 %
189 % \iffrenchdoc
190 %
191 % L'extension \pf{ted} définit essentiellement deux macros publiques :
192 % \cs{Substitute} et \cs{ShowTokens}. La première est la raison d'être
193 % de \pf{ted}, mais au cours du développement de l'extension, la partie
194 % la plus difficile et intéressante a été d'être capable d'écrire la
195 % deuxième. J'ai donc décidé de la proposer à l'utilisateur, car je
196 % pense qu'elle peut être utile, soit pour déboguer du code, soit pour
197 % apprendre \TeX.
198 %
199 % \subsection{\topcs{Substitute}}
200 %
201 % \DescribeMacro{\Substitute}
202 % La syntaxe de \cs{Substitute} est la suivante.
203 % \begin{quote}
204 % \cs{Substitute}\optstar\oarg{sortie}\marg{entrée}\marg{de}\marg{vers}
205 % \end{quote}
206 % Commençons par l'usage le plus simple : sans étoile ni argument
207 % optionel. Sous cette forme, \cs{Substitute} remplace chaque occurrence
208 % de la sous-liste \meta{de} par \meta{vers} dans l'\meta{entrée}, et
209 % place le résultat dans le registre à lexèmes \cs{ted@toks}. Comme
210 % \cs{Substitute} est sans doute destiné à être utilisé par des auteurs
211 % de classe ou d'extensions, le |@| dans le nom de ce registre ne
212 % devrait pas poser de problèmes la plupart du temps.
213 %
214 % Quoi qu'il en soit, vous pouvez changer facilement le nom du registre
215 % utilisé pour la sortie avec l'argument optionnel en spécifiant le nom
216 % d'un registre à lexèmes dans \meta{sortie}. En fait, vous voulez
217 % peut-être que la sortie soit placée dans une macro et non un registre
218 % : dans ce cas, vous pouvez spécifier par exemple \cs{def}\cs{macro}
219 % (ou \cs{long}\cs{def}\cs{macro} etc.) comme argument optionnel. Dans
220 % tous les cas, \meta{sortie}|{trucs}| doit être une syntaxe légale
221 % d'affectation de |truc| dans la sortie. Bien sûr, si vous demandez à
222 % ce que la sortie soit placée dans une macro, vous devez veiller à ce
223 % qu'elle ne contienne pas de dièses (caractère de paramètre) mal
224 % placés. Exemples :
225 %
226 % \begin{quote}
227 % |\Substitute{a#b#c}{a}{A}|\\
228 % |\newtoks\vostoks \Substitute[\vostoks]{a#b#c}{a}{A}|\\
229 % |\Substitute[\def\votremacro]{a#b#c}{#}{##}|
230 % \end{quote}
231 %
232 % La version étoilée de \cs{Substitute} a pour but de vous simplifier la
233 % vie quand vous ne voulez pas spécifier explicitement une liste de
234 % lexèmes en entrée, mais plutôt utiliser le contenu d'une macro ou d'un
235 % registre, en développant une fois son premier argument obligatoire
236 % avant de commencer à travailler dessus. Ceci vous évite d'avoir à
237 % placer vous-même des \cs{expandafter}, surtout dans le cas ou vous
238 % souhaitez utiliser l'argument optionnel. Cette fois, l'usage est
239 % inversé par rapport à l'argument optionnel : c'est la cas d'une macro
240 % qui est le plus naturel. Pour un registre de lexèmes, vous devez
241 % écrire le \cs{the} vous même : ainsi, votre \meta{entrée} pourra être
242 % de la forme \cs{macro}, ou \cs{the}\cs{toksreg}, ou toute autre chose
243 % dont le 1-développement donne ce que vous voulez. Par exemple :
244 %
245 % \begin{quote}
246 % |\def\abc{abccdef} \newtoks\abctoks \abctoks{abc}|\\
247 % |\Substitute{\abc}{cc}{C} %| donne |\abc|\\
248 % |\Substitute*{\abc}{cc}{C} %| donne |abCdef|\\
249 % |\Substitute*{\the\abctoks}{cc}{C} %| aussi
250 % \end{quote}
251 %
252 % La version avec deux étoiles a aussi pour but de vous épargner la
253 % peine de contrôler vous-même le développement des arguments. Elle
254 % fonctionne comme la version étoilée simple, mais développe cette fois
255 % ses trois arguments obligatoires une fois avant de commencer à
256 % travailler. La même remarque que pour la version étoilée simple
257 % s'applique concernant les macros et les registres à lexèmes. J'espère
258 % que ces trois cas (de zéro à deux étoiles) couvriront la plupart des
259 % usage courants. Pour une gestion plus souple du développement des
260 % arguments, attendez \LaTeX$3$ !
261 %
262 % Le comportement de \cs{Substitute} devrait être évident la plupart du
263 % temps. Seul un cas particulier mérite sans doute une petite remarque :
264 % dans le cas ou la liste \meta{de} est vide, la liste \meta{vers} est
265 % insérée entre chaque paire de lexèmes de l'\meta{entrée} : en
266 % particulier elle n'est pas insérée au début ni à la fin. Par exemple,
267 % |\Substitute{abc}{}{1}| placera |a1b1c| dans \cs{ted@toks}.
268 %
269 % Enfin, il peut être utile de savoir qu'une fois que \cs{Substitute} a
270 % fini son travail, le nombre de substitutions effectuées est accessible
271 % dans le registre \cs{ted@count}. On peut ainsi s'en servir pour
272 % compter, par exemple, le nombre d'espaces (donc approximativement de
273 % mots) dans un texte, en faisant semblant d'opérer une substitution
274 % dessus.
275 %
276 % \subsection{\topcs{ShowTokens}}
277 %
278 % \DescribeMacro{\ShowTokens}
279 % La syntaxe de \cs{ShowTokens} est la suivante.
280 % \begin{quote}
281 % \cs{ShowTokens}\optstar\marg{liste}
282 % \end{quote}
283 % Dans sa forme simple, \cs{ShowTokens} se contente d'afficher la liste
284 % de lexèmes, un par ligne. Pour les lexèmes de type caractère,
285 % l'affichage comporte le caractère lui-même, suivi de l'indication de
286 % son code de catégorie sous la forme utilisée par \cs{show}. Je
287 % rappelle ci-dessous (table~\ref{cc}) pour la commodité du lecteur les
288 % différents \cs{catcode}s possibles dans une liste de lexème, ainsi
289 % qu'un exemple et la façon dont ils sont affichés par \cs{ShowTokens}.
290 %
291 % \begin{table}
292 % \begin{tabular}{rcl}
293 % 1 & |{| & |(begin-group character {)|\\
294 % 2 & |}| & |(end-group character })|\\
295 % 3 & |$| & |(math shift character $)|\\
296 % 4 & |&| & |(alignment tab character &)|\\
297 % 6 & |#| & |(macro parameter character #)|\\
298 % 7 & |^| & |(superscript character ^)|\\
299 % 8 & |_| & |(subscript character _)|\\
300 % 10 & | | & |(blank space )|\\
301 % 11 & |a| & |(the letter a)|\\
302 % 12 & |0| & |(the character 0)|\\
303 % 13 & |~| & |(active character=macro:->\nobreakspace {})|\\
304 % \end{tabular}
305 % \caption{Les \cs{catcode} : code, exemple, et description.}\label{cc}
306 % \end{table}
307 %
308 % Pour les séquence de contrôles et les caractères actifs, le (début du)
309 % \cs{meaning} est également affiché, sans dépasser les~$80$ colonnes de
310 % large afin de ne pas perturber l'affichage par ligne. Il s'agit bien
311 % sûr du sens courant au moment de l'appel à \cs{ShowTokens}.
312 %
313 % \DescribeMacro{\ShowTokensLogonly} \DescribeMacro{\ShowTokensOnline}
314 % Le comportement par défaut est d'afficher ces listes à la fois sur le
315 % terminal et dans le fichier log. Si vous préférez que l'affichage
316 % n'ait lieu que dans le fichier log, vous n'avez qu'à dire
317 % \cs{ShowTokensLogonly}. Si vous souhaitez ensuite revenir au
318 % comportement par défaut, dites seulement \cs{ShowTokensOnline}.
319 %
320 % La version étoilée de \cs{ShowTokens} fonctionne de la même façon que
321 % dans le cas de \cs{Substitute} en développant son argument une fois
322 % avant d'en commencer l'analyse. La même remarque que précédemment
323 % s'applique concernant les macros et les registres. Imaginons par
324 % exemple que vous vouliez vérifier, après la définition d'une macro,
325 % que vous avez bien les bons \cs{catcode}s :
326 %
327 % \begin{quote}
328 % |\begingroup \uccode`\~=32 \uppercase{\endgroup|\\
329 % | \def\macro{1~2}}|\\
330 % |\ShowTokens*{\macro} %| donne à l'écran : [...]\\
331 % |1 (the character 1)|\\
332 % | (active character=macro:-> )|\\
333 % |2 (the character 2)|
334 % \end{quote}
335 %
336 % \medskip
337 % J'aimerais conclure par la remarque suivante : au cours de la
338 % conception de \pf{ted}, j'ai vraiment essayé de ne faire aucune
339 % hypothèse sur les lexèmes présents dans la liste. Ainsi, vous pouvez
340 % utiliser librement des accolades, des dièses, des espaces, des
341 % \cs{par}, des \cs{if}s, des \cs{bgroup} ou \cs{egroup} dans toutes les
342 % listes de lexèmes. À ma connaissance à ce jour, la seule limitation
343 % est que les séquences de contrôle qui apparaissent ne doivent pas être
344 % (ou être \cs{let}-égales à) des macros intimes de \pf{ted},
345 % c'est-à-dire celles commençant par \cs{ted@@}.
346 %
347 % \begin{quote}
348 % Vous savez maintenant tout ce qu'il y a à savoir sur l'utilisation de
349 % \pf{ted}. Si vous souhaitez vous pencher sur son implémentation, il
350 % vous faudra lire les commentaires en anglais car je n'ai pas eu le
351 % courage de documenter mon code en deux langues.
352 % \end{quote}
353 %
354 % \begin{center}\large
355 % C'est tout pour cette fois ! \\
356 % Amusez-vous bien avec \LaTeX{} !
357 % \end{center}
358 %
359 % \else
360 %
361 % The \pf{ted} package provides two user macros: \cs{Substitute} and
362 % \cs{ShowTokens}. The first one is the primary goal of the package, but
363 % to be able to do the second was the more interesting part while
364 % writing the package. I made it into a user macro since I believe it
365 % can be useful for debugging things, or for learning \TeX.
366 %
367 % \subsection{\topcs{Substitute}}
368 %
369 % \DescribeMacro{\Substitute}
370 % The syntax of \cs{Substitute} is as follows.
371 % \begin{quote}
372 % \cs{Substitute}\optstar\oarg{output}\marg{input}\marg{from}\marg{to}
373 % \end{quote}
374 % Let's begin with the basics. Without star or optional argument, the
375 % \cs{Substitute} macro will replace each occurrence of the \meta{from}
376 % token list with \marg{to} in the \meta{input}, and put the result in
377 % the \cs{toks} register \cs{ted@toks}. This macro has a |@| in its
378 % name, but since I think the \cs{Substitute} macro will be essentially
379 % be used by class or package writers, this should be ok.
380 %
381 % Anyway, if you don't like this name, you can specify another one as
382 % \meta{output} using the optional argument. Your \meta{output} should
383 % be the name of a \cs{toks} register. If you want the output to be put
384 % in a macro, use \cs{def}\cs{macro} (or \cs{long}\cs{def}\cs{macro}
385 % or\ldots) as the optional argument. Anyway, \meta{output}\marg{stuff}
386 % must be a legal syntax for an assignment: using \cs{macro} as optional
387 % argument will not work (and may actually result in chaos). Of course,
388 % if you want your output to be placed in a macro, it should not contain
389 % improperly placed hash signs (that is, macro parameter tokens).
390 %
391 % \begin{quote}
392 % |\Substitute{a#b#c}{a}{A}|\\
393 % |\newtoks\yourtoks \Substitute[\yourtoks]{a#b#c}{a}{A}|\\
394 % |\Substitute[\def\yourmacro]{a#b#c}{#}{##}|
395 % \end{quote}
396 %
397 % The one-starred form of \cs{Substitute} is meant to help you when your
398 % \meta{input} is not an explicit token list, but the contents of either
399 % a macro or a \cs{toks} register, by expanding once its first mandatory
400 % argument before proceeding. It spares you the pain of using
401 % \cs{expandafter}s, especially in case you want to use the optional
402 % argument too. This time, things are reversed compared to the optional
403 % argument : using a macro instead of a toks register is easier.
404 % Actually, with the starred form, the first argument can be \cs{macro}
405 % or \cs{the}\cs{toksreg}, or anything whose one-time expansion is the
406 % token list you want \cs{Substitute} to act upon.
407 %
408 % \begin{quote}
409 % |\def\abc{abccdef} \newtoks\abctoks \abctoks{abc}|\\
410 % |\Substitute{\abc}{cc}{C} %| gives |\abc|\\
411 % |\Substitute*{\abc}{cc}{C} %| gives |abCdef|\\
412 % |\Substitute*{\the\abctoks}{cc}{C} %| too
413 % \end{quote}
414 %
415 % The two-starred form is also meant to avoid you trouble with
416 % development. It expands its three mandatory arguments once before
417 % executing. The remark about macros and \cs{toks} register still
418 % holds. I hope this three cases (from zero to two stars) will suffice
419 % for most purpose. For a better handling of arguments expansion, wait
420 % for \LaTeX$3$!
421 %
422 % The action of \cs{Substitute} is pretty obvious most of the time.
423 % Maybe a particular case needs some precision: when \meta{from} is
424 % empty, then the \meta{to} list gets inserted between each two tokens
425 % of the \cs{input}, but not before the first one. For example,
426 % \cs{Substitute}|{abc}{}{1}| puts |a1b1c| in \cs{ted@toks}.
427 %
428 % Finally, it may be useful to know that, after \cs{Subsitute} finished
429 % its job, it leaves the number of replaced occurrences in the count
430 % register \cs{ted@count}. This can be used, for example, to count
431 % spaces (hence words) in a text, by making a fake substitution on it.
432 %
433 % \subsection{\topcs{ShowTokens}}
434 %
435 % \DescribeMacro{\ShowTokens}
436 % The syntax of \cs{ShowTokens} is as follows.
437 % \begin{quote}
438 % \cs{ShowTokens}\optstar\marg{list}
439 % \end{quote}
440 % In its simple form, \cs{ShowTokens} just shows the list, one token per
441 % line. For characters tokens, its prints the character, and its
442 % category code in human-friendly form. For the sake of readability,
443 % here is (table~\ref{cc}) a reminder of the possible \cs{catcode}s,
444 % with an exemple and the way \cs{ShowTokens} displays them.
445 %
446 % \begin{table}
447 % \begin{tabular}{rcl}
448 % 1 & |{| & |(begin-group character {)|\\
449 % 2 & |}| & |(end-group character })|\\
450 % 3 & |$| & |(math shift character $)|\\
451 % 4 & |&| & |(alignment tab character &)|\\
452 % 6 & |#| & |(macro parameter character #)|\\
453 % 7 & |^| & |(superscript character ^)|\\
454 % 8 & |_| & |(subscript character _)|\\
455 % 10 & | | & |(blank space )|\\
456 % 11 & |a| & |(the letter a)|\\
457 % 12 & |0| & |(the character 0)|\\
458 % 13 & |~| & |(active character=macro:->\nobreakspace {})|\\
459 % \end{tabular}
460 % \caption{Possible \cs{catcode}s: code, example, and description.}\label{cc}
461 % \end{table}
462 %
463 % For control sequences and active characters, it
464 % also prints their current \cs{meaning} as a bonus, or only the
465 % beginning of it (ending with \cs{ETC.}) if it is more than one line
466 % ($80$ columns) long.
467 %
468 % \DescribeMacro{\ShowTokensLogonly}
469 % \DescribeMacro{\ShowTokensOnline}
470 % The default is to show this list both in the terminal and in the log
471 % file. If you don't want it to be printed on the terminal, just say
472 % \cs{ShowTokensLogonly}. If you change your mind latter, you can
473 % restore the default behaviour with \cs{ShowTokensOnline}.
474 %
475 % The starred form of \cs{ShowTokens} works the same as for
476 % \cs{Substitute}: it expands its argument once before analysing and
477 % displaying it. The same remarks hold: use \cs{macro} or
478 % \cs{the}\cs{toksreg} in the argument.
479 %
480 % \begin{quote}
481 % |\begingroup \uccode`\~=32 \uppercase{\endgroup|\\
482 % | \def\macro{1~2}}|\\
483 % |\ShowTokens*{\macro} %| prints on screen: [...]\\
484 % |1 (the character 1)|\\
485 % | (active character=macro:-> )|\\
486 % |2 (the character 2)|
487 % \end{quote}
488 %
489 % \medskip
490 % I would like to conclude with the following remark: I have really
491 % tried to make sure \pf{ted}'s macros will work fine even with the
492 % wierdest token list. In particular, you can freely use begin-group
493 % and end-group characters, hash signs, spaces, \cs{bgroup} and
494 % \cs{egroup}, \cs{par}, \cs{if}s, as well as exotic
495 % charcode-\cs{catcode} pairs in every argument of the macros. As far as
496 % I am aware, the only restriction is you should not use the very
497 % private macros of \pf{ted} (those beginning with \cs{ted@@}) in your
498 % token lists.
499 %
500 % \fi
501 %
502 % \StopEventually{}
503 %
504 % \section{Implementation}
505 %
506 % A important problem, when trying to substitute things in token lists,
507 % is to handle begin-group and end-group tokens, since they prevent us
508 % from to reading the tokens one by one, and tend to be difficult to
509 % handle individually. Two more kinds of tokens are special: the space
510 % tokens, since they\footnote{Actually, only tokens with charcode $32$
511 % and \cs{catcode}~$10$ (i.e. $32_{10}$ tokens) are concerned.} cannot
512 % be grabbed as the non-delimited argument of a macro, and the parameter
513 % tokens (hash signs), since they cannot be part of the delimiters in
514 % the parameter text of a macro. From now on, ``special tokens'' thus
515 % denotes tokens with \cs{catcode} $1$, $2$, $6$ or $10$.
516 %
517 % To get rid of these problems, the \cs{Substitute} command proceeds in
518 % three steps. First, encode the input, replacing all special tokens
519 % with nice control sequences representing them, then do the actual
520 % substitution, and finally decode the output, replacing the special
521 % control sequences with the initial special tokens.
522 %
523 % Encoding is the hard part. The idea is to try reading the tokens one
524 % by one; for this we have two means: using a macro with one
525 % non-delimited argument, or something like \cs{let}. The former doesn't
526 % work well with \cs{catcode}~$1$, $2$ or $10$ tokens, and the later do
527 % not see the name of the token (its character code, or its name for a
528 % CS). So we need to use both \cs{futurelet}, a ``grabbing'' macro with
529 % argument, and \cs{string} in order to scan the tokens. Actually, the
530 % encoding proceeds in two passes: in the first, we try and detect the
531 % special tokens, storing their character codes for later use, then do
532 % the actual encoding in the last pass.
533 %
534 % Decoding also processes the tokens one by one, and is simpler, since
535 % special cases are already detected. There is, however, a trick with
536 % groups since, when we encounter a begin-group character, we have to
537 % wait for the corresponding end-group before adding the whole thing to
538 % the output. There is also a simpler version of decoding, for
539 % \cs{ShowTokens}, for screen/log output, with no need to use this
540 % trick, since it only outputs \cs{catcode}-$12$ characters. Finally,
541 % the substitution part uses a macro with delimited argument, defined on
542 % the fly.
543 %
544 % The code is divided as follows.
545 % \par\vspace{-0.5\baselineskip}
546 % \secttoc
547 % \par\vspace{-0.5\baselineskip}
548 %
549 % \begin{macro}{\ted@toks}
550 % \begin{macro}{\ted@list}
551 % \begin{macro}{\ted@code}
552 % Before we begin, just allocate (or give a nice name to) a few
553 % registers.
554 % \begin{macrocode}
555 \@ifdefinable\ted@toks{\newtoks\ted@toks}
556 \@ifdefinable\ted@list{\let\ted@list\toks@}
557 \@ifdefinable\ted@code{\let\ted@code\count@}
558 \@ifdefinable\ted@count{\newcount\ted@count}
559 % \end{macrocode}
560 % \end{macro}
561 % \end{macro}
562 % \end{macro}
563 %
564 % \subsection{Encoding}
565 %
566 % \begin{macro}{\ted@encloop}
567 % \begin{macro}{\ted@encloop@}
568 % The two passes use the same loop for reading the input almost token
569 % by token. This loop grabs the next token through a
570 % \cs{futurelet}\ldots
571 % \begin{macrocode}
572 \newcommand\ted@encloop{%
573 \futurelet\@let@token
574 \ted@encloop@}
575 % \end{macrocode}
576 % \ldots then looks at it with some \cs{ifx} and \cs{ifcat} (non nested,
577 % since the token could be an \cs{if} itself), in order to distinguish
578 % between three cases: normal token, end reached, or special token. In
579 % the later case, remember which kind of special token it is, using a
580 % numeric code.
581 % \begin{macrocode}
582 \newcommand\ted@encloop@{%
583 \let\next\ted@do@normal
584 \ifx\@let@token\ted@@end
585 \let\next\ted@gobble@end
586 \fi
587 \ifcat\noexpand\@let@token##%
588 \ted@code0
589 \let\next\ted@do@special
590 \fi
591 \ifcat\noexpand\@let@token\@sptoken
592 \ted@code1
593 \let\next\ted@do@special
594 \fi
595 \ifcat\noexpand\@let@token\bgroup
596 \ted@code2
597 \let\next\ted@do@special
598 \fi
599 \ifcat\noexpand\@let@token\egroup
600 \ted@code3
601 \let\next\ted@do@special
602 \fi
603 \next}
604 % \end{macrocode}
605 % \end{macro}
606 % \end{macro}
607 % \begin{macro}{\ted@@end}
608 % \begin{macro}{\ted@gobble@end}
609 % Here we used the following to detect the end, then gobble it when
610 % reached.
611 % \begin{macrocode}
612 \newcommand\ted@@end{\ted@@end@}
613 % \end{macrocode}
614 % \begin{macrocode}
615 \@ifdefinable\ted@gobble@end{%
616 \def\ted@gobble@end\ted@@end{}}
617 % \end{macrocode}
618 % \end{macro}
619 % \end{macro}
620 %
621 % \begin{macro}{\ted@sanitize}
622 % \begin{macro}{\ted@@active}
623 % Now, this detection method, with \cs{futurelet} and \cs{ifcat}, is
624 % unable to distinguish the following three cases for potential special
625 % tokens: (i) a ``true'' (explicit) special token, (ii) a CS
626 % \cs{let}-equal to a special token, (iii) an active character
627 % \cs{let}-equal to a special token. While this is pre-scanning's job
628 % to detect the (ii) case, the (iii) can be easily got rid of by
629 % redefining locally all active characters.
630 % \begin{macrocode}
631 \count@\catcode\z@ \catcode\z@\active
632 \newcommand\ted@sanitize{%
633 \count@\z@ \@whilenum\count@<\@cclvi \do{%
634 \uccode\z@\count@
635 \uppercase{\let^^00\ted@@active}%
636 \advance\count@\@ne}}
637 \catcode\z@\count@
638 % \end{macrocode}
639 % \begin{macrocode}
640 \newcommand\ted@@active{\ted@@active@}
641 % \end{macrocode}
642 % This sanitizing macro also mark active characters by \cs{let}-ing them
643 % equal to \cs{ted@@active} in order to detect them easily later, for
644 % example while displaying on-screen token analysis. All operations
645 % (scanning, replacing, display and decoding) are going to happen inside
646 % a group where \cs{ted@sanitize} has been executed, so that active
647 % characters are no longer an issue. \end{macro} \end{macro}
648 %
649 % \begin{macro}{\ted@encode} \begin{macro}{\ted@do@normal}
650 % \begin{macro}{\ted@do@special} The \cs{ted@encode} macro is the master
651 % macro for encoding. It only initialise a few things and launches the
652 % two loops. We select one of the tree steps by \cs{let}-ing
653 % \cs{ted@do@normal} and \cs{ted@do@special} to the appropriate action.
654 % \begin{macrocode}
655 \newcommand\ted@encode[1]{%
656 \ted@list{}%
657 \let\ted@do@normal\ted@gobble@encloop
658 \let\ted@do@special\ted@scan@special
659 \ted@encloop#1\ted@@end
660 \ted@toks{}%
661 \let\ted@do@normal\ted@addtoks@encloop
662 \let\ted@do@special\ted@special@out
663 \ted@encloop#1\ted@@end
664 \ted@assert@listempty}
665 % \end{macrocode}
666 % \end{macro}
667 % \end{macro}
668 % \end{macro}
669 % \begin{macro}{\ted@assert@listempty}
670 % After the last loop, \cs{ted@list} should be empty. If it's not, it
671 % means something very weird happened during the encoding procedure. I
672 % hope the code below will never be executed :)
673 % \begin{macrocode}
674 \newcommand\ted@assert@listempty{%
675 \edef\next{\the\ted@list}%
676 \ifx\next\@empty \else
677 \PackageError{ted}{%
678 Assertion `\string\ted@list\space is empty' failed}{%
679 This should not happen. Please report this bug to the author.
680 \MessageBreak By the way, you're in trouble there... I'm sorry.}%
681 \fi}
682 % \end{macrocode}
683 % \end{macro}
684 %
685 % \subsubsection{Pre-scanning}
686 %
687 % \begin{macro}{\ted@gobble@encloop}
688 % For normal tokens, things are pretty easy: just gobble them!
689 % \begin{macrocode}
690 \newcommand\ted@gobble@encloop{%
691 \afterassignment\ted@encloop
692 \let\@let@token= }
693 % \end{macrocode}
694 % \end{macro}
695 % \begin{macro}{\ted@scan@special}
696 % For special tokens, it's harder. We must distinguish explicit
697 % character tokens from control sequences \cs{let}-equal to special
698 % tokens. For this, we use \cs{string}, then grab the next character to
699 % see whether its code is \cs{escapechar} or not. Actually, things are
700 % not this easy, for two reasons. First, we have to make sure the next
701 % character's code is not already \cs{escapechar} before the
702 % \cs{string}, by accident. For this purpose, we set \cs{escapechar}
703 % to~$0$ except if next character's code is also~$0$, in which case we
704 % prefer~$1$.
705 % \begin{macrocode}
706 \count@\catcode\z@ \catcode\z@ 12
707 \newcommand\ted@scan@special{%
708 \begingroup
709 \escapechar\if\@let@token^^00 \@ne \else \z@ \fi
710 \expandafter\ted@check@space\string}
711 \catcode\z@\count@
712 % \end{macrocode}
713 % \end{macro}
714 % \begin{macro}{\ted@check@space}
715 % \begin{macro}{\ted@check@space@}
716 % Second, we have to handle carefully the case of the next token being
717 % the $32_{10}$ token, since we cannot grab this one with a macro. We
718 % are in this case if and only if the token we just \cs{string}ed was a
719 % character token with code $32$, and it is enough to check if next
720 % token's \cs{catcode} is $10$ in order to detect it, since it will be
721 % $12$ otherwise. In order to check this, we use \cs{futurelet} again
722 % for pre-scanning.
723 % \begin{macrocode}
724 \newcommand\ted@check@space{%
725 \futurelet\@let@token
726 \ted@check@space@}
727 % \end{macrocode}
728 % \begin{macrocode}
729 \newcommand\ted@check@space@{%
730 \ifcat\@let@token\@sptoken
731 \endgroup
732 \ted@addlist{32}%
733 \expandafter\ted@gobble@encloop
734 \else
735 \expandafter\ted@list@special
736 \fi}
737 % \end{macrocode}
738 % \end{macro}
739 % \end{macro}
740 % \begin{macro}{\ted@list@special}
741 % Now that we got rid of this nasty space problem, we know for sure that
742 % the next token has \cs{catcode} $12$, so we can easily grab it as an
743 % argument, find its charcode, and decide whether the original token was
744 % a control sequence or not. Note the \cs{expandafter} over
745 % \cs{endgroup} trick, since we need to add the charcode to the list
746 % outside the group (opened for the modified \cs{escapechar}) though it
747 % was set inside.
748 % \begin{macrocode}
749 \newcommand*\ted@list@special[1]{%
750 \ted@code`#1\relax
751 \expandafter\expandafter\expandafter
752 \endgroup
753 \ifnum\ted@code=\escapechar
754 \ted@addlist{\m@ne}%
755 \else
756 \expandafter\ted@addlist\expandafter{\the\ted@code}%
757 \fi
758 \ted@encloop}
759 % \end{macrocode}
760 % \end{macro}
761 % \begin{macro}{\ted@addlist}
762 % Here we used the following macro to add an element to the list, which
763 % is space-separated.
764 % \begin{macrocode}
765 \newcommand*\ted@addlist[1]{%
766 \ted@list\expandafter{\the\ted@list#1 }}
767 % \end{macrocode}
768 % \end{macro}
769 %
770 % \subsubsection{Actually encoding}
771 %
772 % Remember that, before this last encoding pass, \cs{ted@encode} did the
773 % following:
774 % \begin{quote}
775 % \cs{let}\cs{ted@do@normal}\cs{ted@addtoks@encloop}\\
776 % \cs{let}\cs{ted@do@special}\cs{ted@special@out}
777 % \end{quote}
778 % \begin{macro}{\ted@addtoks@encloop}
779 % The first one is very easy : normal tokens are just grabbed as
780 % arguments and appended to the output, then the loop continues.
781 % \begin{macrocode}
782 \newcommand\ted@addtoks@encloop[1]{%
783 \ted@toks\expandafter{\the\ted@toks#1}%
784 \ted@encloop}
785 % \end{macrocode}
786 % \end{macro}
787 % \begin{macro}{\ted@special@out}
788 % Special tokens need to be encoded, but before, just check if they are
789 % really special: they aren't if the corresponding code is $-1$.
790 % \begin{macrocode}
791 \newcommand\ted@special@out{%
792 \ifnum\ted@list@read=\m@ne
793 \ted@list@advance
794 \expandafter\ted@cs@clean
795 \else
796 \expandafter\ted@special@encode
797 \fi}
798 % \end{macrocode}
799 % \end{macro}
800 % \begin{macro}{\ted@cs@clean}
801 % Even if the potentially special token was not a real one, we have work
802 % to do. Indeed, in the first pass we did break it using a \cs{string},
803 % and thus we introduced some foreign tokens in the stream. Most of them
804 % are not important since they have \cs{catcode}~$12$. Anyway, some of
805 % them may be space tokens : in this case we have extra $32$'s in our
806 % list. So, we need to check this before going any further.
807 % \begin{macrocode}
808 \newcommand\ted@cs@clean[1]{%
809 \expandafter\ted@add@toks{#1}%
810 \expandafter\ted@cscl@loop\string#1 \@nil}
811 % \end{macrocode}
812 % \end{macro}
813 % \begin{macro}{\ted@cscl@loop}
814 % We first add the CS to the output, then break it with a \cs{string} in
815 % order to look at its name with the following loop. It first grabs
816 % everything to the first space\ldots
817 % \begin{macrocode}
818 \@ifdefinable\ted@cscl@loop{%
819 \def\ted@cscl@loop#1 {%
820 \futurelet\@let@token
821 \ted@cscl@loop@}}
822 % \end{macrocode}
823 % \end{macro}
824 % \begin{macro}{\ted@cscl@loop@}
825 % \ldots and carefully look at the next token in order to know if we are
826 % finished or not.
827 % \begin{macrocode}
828 \newcommand\ted@cscl@loop@{%
829 \ifx\@let@token\@nil
830 \expandafter\ted@gobble@encloop
831 \else
832 \ted@list@advance
833 \expandafter\ted@cscl@loop
834 \fi}
835 % \end{macrocode}
836 % \end{macro}
837 %
838 % \begin{macro}{\ted@special@encode}
839 % Now, let's come back to the special tokens. As we don't need the token
840 % to encode it (we already know its \cs{catcode} from \cs{ted@code},
841 % and its charcode is stored in the list), we first gobble it in order
842 % to prepare for next iteration.
843 % \begin{macrocode}
844 \newcommand\ted@special@encode{%
845 \afterassignment\ted@special@encode@
846 \let\@let@token= }
847 % \end{macrocode}
848 % \end{macro}
849 % \begin{macro}{\ted@special@encode@}
850 % Then we encode it in two steps : first, create a control sequence with
851 % name \cs{ted@@}\meta{code}\meta{charcode}, where code is a digit
852 % denoting\footnote{I don't store the \cs{catcode} for two reasons:
853 % first, having a single digit is easier; second, having the true
854 % catcode would be useless (though it could maybe make the code more
855 % readable).} the \cs{catcode} of the special token, \ldots
856 % \begin{macrocode}
857 \newcommand\ted@special@encode@{%
858 \expandafter\ted@special@encode@@\expandafter{%
859 \csname ted@@\the\ted@code\ted@list@read\endcsname}}
860 % \end{macrocode}
861 % \end{macro}
862 % \begin{macro}{\ted@special@encode@@}
863 % \begin{macro}{\ted@@special}
864 % \ldots then, mark this CS as a special token encoding, in order to
865 % make it easier to detect later, add it to the output and loop again.
866 % \begin{macrocode}
867 \newcommand*\ted@special@encode@@[1]{%
868 \ted@list@advance
869 \let#1\ted@@special
870 \ted@addtoks@encloop{#1}}
871 % \end{macrocode}
872 % \begin{macrocode}
873 \newcommand\ted@@special{\ted@@special@}
874 % \end{macrocode}
875 % \end{macro}
876 % \end{macro}
877 %
878 % \begin{macro}{\ted@list@read}
879 % \begin{macro}{\ted@list@read@}
880 % Here we used the following macros in order to manage our charcode list.
881 % The reading one is fully expandable.
882 % \begin{macrocode}
883 \newcommand\ted@list@read{%
884 \expandafter\ted@list@read@\the\ted@list\@nil}
885 % \end{macrocode}
886 % \begin{macrocode}
887 \@ifdefinable\ted@list@read@{%
888 \def\ted@list@read@#1 #2\@nil{%
889 #1}}
890 % \end{macrocode}
891 % \end{macro}
892 % \end{macro}
893 % \begin{macro}{\ted@list@advance}
894 % \begin{macro}{\ted@list@advance@}
895 % Since it's expandable, it cannot change the list, so we need a
896 % separate macro to remove the first element from the list, once read.
897 % \begin{macrocode}
898 \newcommand\ted@list@advance{%
899 \expandafter\ted@list@advance@\the\ted@list\@nil}
900 % \end{macrocode}
901 % \begin{macrocode}
902 \@ifdefinable\ted@list@advance@{
903 \def\ted@list@advance@#1 #2\@nil{%
904 \ted@list{#2}}}
905 % \end{macrocode}
906 % \end{macro}
907 % \end{macro}
908 %
909 % \subsection{Decoding}
910 %
911 % \begin{macro}{\ted@add@toks}
912 % Main decoding macro is \cs{ted@decode}. It is again a loop, processing
913 % the token list one by one. For normal tokens, things are easy as
914 % always: just add them to the output, via
915 % \begin{macrocode}
916 \newcommand\ted@add@toks[1]{%
917 \ted@toks\expandafter{\the\ted@toks#1}}
918 % \end{macrocode}
919 % \end{macro}
920 % \begin{macro}{\ted@decode}
921 % Encoded special tokens are easily recognized, since they were \cs{let}
922 % equal to \cs{ted@@special}. In order to decode it, we use the name of
923 % the CS. The following macro uses \LaTeX-style \cs{if} in order to
924 % avoid potential nesting problems when \cs{ifs} are present in the
925 % token list being processed.
926 % \begin{macrocode}
927 \newcommand\ted@decode[1]{%
928 \ifx#1\ted@@end \expandafter\@gobble\else\expandafter\@firstofone\fi{%
929 \ifx#1\ted@@special
930 \expandafter\@firstoftwo
931 \else
932 \expandafter\@secondoftwo
933 \fi{%
934 \begingroup \escapechar\m@ne \expandafter\endgroup
935 \expandafter\ted@decode@special\string#1\@nil
936 }{%
937 \ted@add@toks{#1}}%
938 \ted@decode}}
939 % \end{macrocode}
940 % \end{macro}
941 % \begin{macro}{\ted@decode@special}
942 % The next macro should then gobble the |ted@@| part of the CS name, and
943 % use the last part as two numeric codes (here we use the fact that the
944 % first one is only a digit).
945 % \begin{macrocode}
946 \@ifdefinable\ted@decode@special{%
947 \begingroup\escapechar\m@ne \expandafter\endgroup\expandafter
948 \def\expandafter\ted@decode@special\string\ted@@#1#2\@nil{%
949 % \end{macrocode}
950 % It then proceeds according to the first code, building back the
951 % original token and adding it to the output. The first two kinds of
952 % tokens (macro parameter characters and blank spaces) are easily dealt
953 % with.
954 % \begin{macrocode}
955 \ifcase#1
956 \begingroup \uccode`##=#2 \uppercase{\endgroup
957 \ted@add@toks{##}}%
958 \or
959 \begingroup \uccode32=#2 \uppercase{\endgroup
960 \ted@add@toks{ }}%
961 \or
962 % \end{macrocode}
963 % For begin-group and end-group characters, we have a problem, since
964 % they are impossible to handle individually: we can only add a
965 % \meta{balanced text} to the output. So, when we find a begin-group
966 % character, we just open a group (a real one), and start decoding again
967 % inside the group, until we find the corresponding end-group character.
968 % Then, we enclose the local decoded list of tokens into the correct
969 % begin-group/end-group pair, and then add it to the output one group
970 % level below, using the \cs{expandafter}-over-\cs{endgroup} trick
971 % (essential here).
972 % \begin{macrocode}
973 \begingroup \ted@toks{}%
974 \uccode`{=#2
975 \or
976 \uccode`}=#2
977 \uppercase{\ted@toks\expandafter{\expandafter{\the\ted@toks}}}%
978 \expandafter\endgroup
979 \expandafter\ted@add@toks\expandafter{\the\ted@toks}%
980 \fi}}
981 % \end{macrocode}
982 % \end{macro}
983 %
984 % \subsection{Substitution}
985 %
986 % For this part, the idea\footnote{for which I am grateful to Jean-Côme
987 % Charpentier, who first taught me the clever use delimited arguments
988 % (and lots of other wonderful things) in \nolinkurl{fr.comp.text.tex}}
989 % is to use a macro whose first argument is delimited with the
990 % \meta{from} string, which outputs the first argument followed by the
991 % \meta{to} string, and loops. Obviously this macro has to be defined on
992 % the fly. All tokens lists need to be encoded first, and the output
993 % decoded at end. Since all this needs to happens inside a group (for
994 % \cs{ted@sanitize} and the marking up of special-characters control
995 % sequences), remember to ``export'' \cs{ted@toks} when done.
996 %
997 % \begin{macro}{\ted@Substitude}
998 % The main substitution macro is as follows. Arguments are \meta{input},
999 % \meta{from}, \meta{to}. \cs{ted@output} will be discussed later.
1000 % \begin{macrocode}
1001 \newcommand\ted@Substitute[3]{%
1002 \begingroup \ted@sanitize
1003 \ted@encode{#3}%
1004 \expandafter\ted@def@subsmac\expandafter{\the\ted@toks}{#2}%
1005 \ted@encode{#1}%
1006 \ted@subsmac
1007 \ted@toks\expandafter{\expandafter}%
1008 \expandafter\ted@decode\the\ted@toks\ted@@end
1009 \expandafter\endgroup
1010 \expandafter\ted@output\expandafter{\the\ted@toks}}
1011 % \end{macrocode}
1012 % \end{macro}
1013 % \begin{macro}{\ted@def@subsmac}
1014 % The actual iterative substitution macro is defined by the following
1015 % macro, whose arguments are the \meta{to} string, encoded, and the
1016 % plain \meta{from} string.
1017 % \begin{macrocode}
1018 \newcommand\ted@def@subsmac[2]{%
1019 \ted@encode{#2}%
1020 \long\expandafter\def\expandafter\ted@subsmac@loop
1021 \expandafter##\expandafter1\the\ted@toks##2{%
1022 \ted@add@toks{##1}%
1023 \ifx##2\ted@@end
1024 \expandafter\@firstoftwo
1025 \else
1026 \expandafter\@secondoftwo
1027 \fi{%
1028 \expandafter\ted@remove@nil\the\ted@toks
1029 }{%
1030 \global\advance\ted@count\@ne
1031 \ted@add@toks{#1}\ted@subsmac@loop##2}}%
1032 \expandafter\ted@def@subsmac@\expandafter{\the\ted@toks}}
1033 % \end{macrocode}
1034 % \end{macro}
1035 % \begin{macro}{\ted@def@subsmac@}
1036 % While we have the encoded \meta{from} string at hand, define the
1037 % start-loop macro.
1038 % \begin{macrocode}
1039 \newcommand\ted@def@subsmac@[1]{%
1040 \def\ted@subsmac{%
1041 \global\ted@count\z@
1042 \ted@toks\expandafter{\expandafter}%
1043 \expandafter\ted@subsmac@loop\the\ted@toks\ted@@nil#1\ted@@end}}
1044 % \end{macrocode}
1045 % \end{macro}
1046 % \begin{macro}{\ted@remove@nil}
1047 % You probably noticed the \cs{ted@@nil} after \cs{ted@toks} in the
1048 % above definition. This is to avoid problems while trying to
1049 % substitute something like ``AA'' in a list ending with ``A'' (new in
1050 % v1.05). We need to remove it when finished.
1051 % \begin{macrocode}
1052 \@ifdefinable\ted@remove@nil{%
1053 \long\def\ted@remove@nil#1\ted@@nil{%
1054 \ted@toks{#1}}}
1055 % \end{macrocode}
1056 % \end{macro}
1057 %
1058 % \subsection{Display}
1059 %
1060 % \begin{macro}{\ted@ShowTokens}
1061 % In order to display the tokens one by one, we first encode the string.
1062 % \begin{macrocode}
1063 \newcommand\ted@ShowTokens[1]{%
1064 \begingroup \ted@sanitize
1065 \ted@toks{#1}%
1066 \ted@typeout{--- Begin token decomposition of:}%
1067 \ted@typeout{\@spaces \the\ted@toks}%
1068 \ted@encode{#1}%
1069 \expandafter\ted@show@toks\the\ted@toks\ted@@end
1070 \endgroup
1071 \ted@typeout{--- End token decomposition.}}
1072 % \end{macrocode}
1073 % \end{macro}
1074 % \begin{macro}{\ted@show@toks}
1075 % Then we proceed, almost like decoding, iteratively, processing the
1076 % encoded tokens one by one. We detect control sequences the same way as
1077 % in pre-scanning. For our tests (and also for use in
1078 % \cs{ted@show@toks@}) we embed |#1| into \cs{ted@toks} in order to
1079 % nest the \cs{if}s without fear. There are four cases that need to be
1080 % typeset in different ways : active character, CS that represent a
1081 % special token, normal CS, normal character token. However, we need to
1082 % do one more test to detect the character tokens whose charcode is
1083 % $32$, before we apply \cs{string} to it in order to check if it was a
1084 % control sequence.
1085 % \begin{macrocode}
1086 \count@\catcode\z@ \catcode\z@ 12
1087 \newcommand\ted@show@toks[1]{%
1088 \ted@toks{#1}\expandafter
1089 \ifx\the\ted@toks\ted@@end \else\expandafter
1090 \ifx\the\ted@toks\ted@@active
1091 % \end{macrocode}
1092 % It's time to think about the following: we are inside a group where
1093 % all active characters were redefined, but we nonetheless want to
1094 % display their meaning. In order to do this, the display need to
1095 % actually happen after the current group is finished. For this we use
1096 % \cs{aftergroup} (with specialized macro for displaying each kind of
1097 % token).
1098 % \begin{macrocode}
1099 \aftergroup\ted@type@active
1100 \expandafter\aftergroup\the\ted@toks
1101 \else
1102 \if\expandafter\noexpand\the\ted@toks\@sptoken
1103 \aftergroup\ted@type@normal
1104 \expandafter\aftergroup\the\ted@toks
1105 \else
1106 \begingroup
1107 \escapechar\if\noexpand#1^^00 \@ne \else \z@ \fi
1108 \expandafter\expandafter\expandafter\ted@show@toks@
1109 \expandafter\string\the\ted@toks\@nil
1110 \fi
1111 \fi
1112 \expandafter\ted@show@toks
1113 \fi}
1114 \catcode\z@\count@
1115 % \end{macrocode}
1116 % \end{macro}
1117 % \begin{macro}{\ted@show@toks@}
1118 % Now test the remaining cases : special CS, normal CS, or normal
1119 % character.
1120 % \begin{macrocode}
1121 \@ifdefinable\ted@show@toks@{%
1122 \long\def\ted@show@toks@#1#2\@nil{%
1123 \expandafter\endgroup
1124 \ifnum`#1=\escapechar
1125 \expandafter\ifx\the\ted@toks\ted@@special
1126 \ted@show@special#2\@nil
1127 \else
1128 \aftergroup\ted@type@cs
1129 \expandafter\aftergroup\the\ted@toks
1130 \fi
1131 \else
1132 \aftergroup\ted@type@normal
1133 \expandafter\aftergroup\the\ted@toks
1134 \fi}}
1135 % \end{macrocode}
1136 % \end{macro}
1137 % \begin{macro}{\ted@show@special}
1138 % Let's begin our tour of specialized display macro with the most
1139 % important one: \cs{ted@show@special}. Displaying the special token
1140 % goes mostly the same way as decoding them, but is far easier, since we
1141 % don't need to care about groups: display is done with
1142 % \cs{catcode}~$12$ characters.
1143 % \begin{macrocode}
1144 \@ifdefinable\ted@show@special{%
1145 \begingroup\escapechar\m@ne \expandafter\endgroup
1146 \expandafter\def\expandafter\ted@show@special\string\ted@@#1#2\@nil{%
1147 \ifcase#1
1148 \aftergroup\ted@type@hash
1149 \or
1150 \aftergroup\ted@type@blank
1151 \or
1152 \aftergroup\ted@type@bgroup
1153 \or
1154 \aftergroup\ted@type@egroup
1155 \fi
1156 \begingroup \uccode`1#2
1157 \uppercase{\endgroup\aftergroup1}}}
1158 % \end{macrocode}
1159 % \end{macro}
1160 % \begin{macro}{\ted@type@hash}
1161 % \begin{macro}{\ted@type@blank}
1162 % \begin{macro}{\ted@type@bgroup}
1163 % \begin{macro}{\ted@type@egroup}
1164 % \begin{macro}{\ted@type@normal}
1165 % The four macros for special tokens are obvious. So is the macro for
1166 % normal tokens. By the way, \cs{ted@typeout} will be discussed in the
1167 % next section.
1168 % \begin{macrocode}
1169 \newcommand\ted@type@hash[1]{%
1170 \ted@typeout{#1 (macro parameter character #1)}}
1171 % \end{macrocode}
1172 % \begin{macrocode}
1173 \newcommand\ted@type@blank[1]{%
1174 \ted@typeout{#1 (blank space #1)}}
1175 % \end{macrocode}
1176 % \begin{macrocode}
1177 \newcommand\ted@type@bgroup[1]{%
1178 \ted@typeout{#1 (begin-group character #1)}}
1179 % \end{macrocode}
1180 % \begin{macrocode}
1181 \newcommand\ted@type@egroup[1]{%
1182 \ted@typeout{#1 (end-group character #1)}}
1183 % \end{macrocode}
1184 % \begin{macrocode}
1185 \newcommand\ted@type@normal[1]{%
1186 \ted@typeout{#1 (\meaning#1)}}
1187 % \end{macrocode}
1188 % \end{macro}
1189 % \end{macro}
1190 % \end{macro}
1191 % \end{macro}
1192 % \end{macro}
1193 % \begin{macro}{\ted@type@cs}
1194 % \begin{macro}{\ted@type@active}
1195 % For control sequences and active characters, we use more sophisticated
1196 % macros. Indeed, their \cs{meaning} can be quite long, and since it is
1197 % not so important (\pf{ted}'s work is lexical analysis, displaying the
1198 % \cs{meaning} is just an add-on), we cut it so that lines are shorter
1199 % than~$80$ colons, in order to save our one-token-a-line presentation.
1200 % \begin{macrocode}
1201 \newcommand\ted@type@cs[1]{%
1202 \ted@type@long{\string#1 (control sequence=\meaning#1}}%
1203 % \end{macrocode}
1204 % \begin{macrocode}
1205 \newcommand\ted@type@active[1]{%
1206 \ted@type@long{\string#1 (active character=\meaning#1}}%
1207 % \end{macrocode}
1208 % \end{macro}
1209 % \end{macro}
1210 % \begin{macro}{\ted@type@long}
1211 % Lines are cut and displayed by \cs{ted@type@long}. This macro uses a
1212 % loop, counting down how many columns remain on the current line. The
1213 % input need to be fully expanded first, and the output is stored in
1214 % \cs{ted@toks}.
1215 % \begin{macrocode}
1216 \newcommand\ted@type@long[1]{%
1217 \ted@toks{}%
1218 \ted@code72
1219 \edef\next{#1}%
1220 \expandafter\ted@tl@loop\next\@nil}
1221 % \end{macrocode}
1222 % \end{macro}
1223 % \begin{macro}{\ted@tl@loop}
1224 % The only difficult thing in this loop is to take care of space tokens.
1225 % For this we use again our \cs{futurelet} trick:
1226 % \begin{macrocode}
1227 \newcommand\ted@tl@loop{%
1228 \futurelet\@let@token
1229 \ted@tl@loop@}
1230 % \end{macrocode}
1231 % \end{macro}
1232 % \begin{macro}{\ted@tl@loop@}
1233 % \ldots then check what to do.
1234 % \begin{macrocode}
1235 \newcommand\ted@tl@loop@{%
1236 \ifx\@let@token\@nil
1237 \let\next\ted@tl@finish
1238 \else
1239 \advance\ted@code\m@ne
1240 \ifnum\ted@code<\z@
1241 \let\next\ted@tl@finish
1242 \else
1243 \ifx\@let@token\@sptoken
1244 \let\next\ted@tl@space
1245 \else
1246 \let\next\ted@tl@add
1247 \fi
1248 \fi
1249 \fi
1250 \next}
1251 % \end{macrocode}
1252 % \end{macro}
1253 % \begin{macro}{\ted@tl@add}
1254 % \begin{macro}{\ted@tl@space}
1255 % Normal characters are just grabbed and added without care, and spaces
1256 % are gobbled with a special macro which also add a space to the output.
1257 % \begin{macrocode}
1258 \newcommand*\ted@tl@add[1]{%
1259 \ted@toks\expandafter{\the\ted@toks #1}%
1260 \ted@tl@loop}
1261 % \end{macrocode}
1262 % \begin{macrocode}
1263 \@ifdefinable\ted@tl@space{%
1264 \expandafter\def\expandafter\ted@tl@space\space{%
1265 \ted@tl@add{ }}}
1266 % \end{macrocode}
1267 % \end{macro}
1268 % \end{macro}
1269 % \begin{macro}{\ted@tl@finish}
1270 % When the end has been reached (either because a \cs{@nil} was
1271 % encountered or because the line is almost full), it's time to
1272 % actually display the result. We add \cs{ETC.} at the end when the
1273 % full \cs{meaning} isn't displayed.
1274 % \begin{macrocode}
1275 \@ifdefinable\ted@tl@finish{%
1276 \def\ted@tl@finish#1\@nil{%
1277 \ifnum\ted@code<\z@
1278 \ted@typeout{\the\ted@toks\string\ETC.)}
1279 \else
1280 \ted@typeout{\the\ted@toks)}
1281 \fi}}
1282 % \end{macrocode}
1283 % \end{macro}
1284 %
1285 % \subsection{User macros}
1286 %
1287 % \begin{macro}{\ted@typeout}
1288 % Since we just discussed display, let's see the related user commands.
1289 % Output is done with
1290 % \begin{macrocode}
1291 \newcommand\ted@typeout{%
1292 \immediate\write\ted@outfile}
1293 % \end{macrocode}
1294 % \end{macro}
1295 % \begin{macro}{\ShowTokensOnline}
1296 % \begin{macro}{\ShowTokensLogonly}
1297 % allowing the user to choose between online display, or log output.
1298 % Default is online.
1299 % \begin{macrocode}
1300 \newcommand\ShowTokensOnline{%
1301 \let\ted@outfile\@unused}
1302 % \end{macrocode}
1303 % \begin{macrocode}
1304 \newcommand\ShowTokensLogonly{%
1305 \let\ted@outfile\m@ne}
1306 % \end{macrocode}
1307 % \begin{macrocode}
1308 \ShowTokensOnline
1309 % \end{macrocode}
1310 % \end{macro}
1311 % \end{macro}
1312 % \begin{macro}{\ShowTokens}
1313 % \begin{macro}{\ted@ShowTokens@exp}
1314 % The user macro for showing tokens is a simple call to the internal
1315 % macro, just expanding its argument once in its stared form.
1316 % \begin{macrocode}
1317 \newcommand\ShowTokens{%
1318 \@ifstar{\ted@ShowTokens@exp}{\ted@ShowTokens}}
1319 % \end{macrocode}
1320 % \begin{macrocode}
1321 \newcommand\ted@ShowTokens@exp[1]{%
1322 \expandafter\ted@ShowTokens\expandafter{#1}}
1323 % \end{macrocode}
1324 % \end{macro}
1325 % \end{macro}
1326 %
1327 % \begin{macro}{\Substitute}
1328 % \begin{macro}{\ted@Subs@star}
1329 % Now, the user macro for substitution. First, check how many stars
1330 % there are, if any, and set \cs{ted@subs@cmd} accordingly.
1331 % \begin{macrocode}
1332 \newcommand\Substitute{%
1333 \@ifstar
1334 {\ted@Subs@star}
1335 {\let\ted@Subs@cmd\ted@Substitute \ted@Subs}}
1336 % \end{macrocode}
1337 % \begin{macrocode}
1338 \newcommand\ted@Subs@star{%
1339 \@ifstar
1340 {\let\ted@Subs@cmd\ted@Subs@exp@iii \ted@Subs}
1341 {\let\ted@Subs@cmd\ted@Subs@exp@i \ted@Subs}}
1342 % \end{macrocode}
1343 % \end{macro}
1344 % \end{macro}
1345 % \begin{macro}{\ted@Subs@exp@i}
1346 % \begin{macro}{\ted@Subs@exp@iii}
1347 % Here are the intermediate macros that expand either the first or all
1348 % three arguments before calling \cs{ted@Substitute}.
1349 % \begin{macrocode}
1350 \newcommand\ted@Subs@exp@i{%
1351 \expandafter\ted@Substitute\expandafter}
1352 % \end{macrocode}
1353 % \begin{macrocode}
1354 \newcommand\ted@Subs@exp@iii[3]{%
1355 \begingroup
1356 \toks0{\ted@Substitute}%
1357 \toks2\expandafter{#1}%
1358 \toks4\expandafter{#2}%
1359 \toks6\expandafter{#3}%
1360 \xdef\ted@Subs@cmd{\the\toks0{\the\toks2}{\the\toks4}{\the\toks6}}%
1361 \endgroup
1362 \ted@Subs@cmd}
1363 % \end{macrocode}
1364 % \end{macro}
1365 % \end{macro}
1366 % \begin{macro}{\ted@Subs}
1367 % Now, the last macro checks and process the optional argument. Here we
1368 % set \cs{ted@output}, which will be used at the end of
1369 % \cs{ted@Substitute}.
1370 % \begin{macrocode}
1371 \newcommand\ted@Subs[1][\ted@toks]{%
1372 \def\ted@output{#1}%
1373 \ted@Subs@cmd}
1374 % \end{macrocode}
1375 % \end{macro}
1376 % \begin{macro}{\ted@output}
1377 % Finally set a default \cs{ted@output} for advanced users who may want
1378 % to use \cs{ted@Substitute} directly.
1379 % \begin{macrocode}
1380 \let\ted@output\ted@toks
1381 % \end{macrocode}
1382 % \end{macro}
1383 %
1384 % \bigskip
1385 % \begin{center}\Large
1386 % That's all folks!\\
1387 % Happy \TeX ing!
1388 % \end{center}
1389 %
1390 % \Finale
1391 %
1392 % \iffalse
1393 %</package>
1394 %<*batchfile>
1395 % \fi
1396 % \begingroup\obeyspaces
1397 % \typeout{*****************************************************}
1398 % \typeout{* *}
1399 % \typeout{* To finish the installation you have to move the *}
1400 % \typeout{* following file into a directory searched by TeX: *}
1401 % \typeout{* *}
1402 % \typeout{* ted.sty *}
1403 % \typeout{* *}
1404 % \typeout{* Documentation is in ted.dvi or ted.pdf *}
1405 % \typeout{* *}
1406 % \typeout{* To produce the french documentation, run *}
1407 % \typeout{* (pdf)latex ted-fr.drv *}
1408 % \typeout{* *}
1409 % \typeout{* Happy TeXing! *}
1410 % \typeout{* *}
1411 % \typeout{*****************************************************}
1412 % \endgroup
1413 % \iffalse
1414 %</batchfile>
1415 % \fi
1416 \endinput