Debian Codegraph @

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

raw
1 % \iffalse meta-comment
2 %<*internal>
3 \iffalse
4 %</internal>
5 %<*readme>
6 %^^A To generate the readme, we make + into an ignored character!!
7 ----------------------------------------------------------------
8 cprotect --- verbatim in macro arguments
9 E-mail: [email protected]
10 Released under the LaTeX Project Public License v1.3c or later
11 See http://www.latex-project.org/lppl.txt
12 ----------------------------------------------------------------
13
14 A user of the cprotect.sty package can include verbatim text (\verb,
15 verbatim environment, ...) in the argument of any command,
16 including moving arguments. Including verbatim text in footnotes,
17 section titles (and other titles), etc. is as simple as typing
18 `\cpro+tect\footnote` instead of `\footnote`, etc.
19
20 A similar approach is taken for environments. Nesting of the
21 various environments is taken into account.
22
23 This is work in progress, all comments/bug reports are welcome!
24
25
26 The whole package can be built from the file `cprotect.dtx' by running
27
28 pdflatex cprotect.dtx
29 makeindex -s gglo.ist -o cprotect.gls cprotect.glo
30 makeindex -s gind.ist -o cprotect.ind cprotect.idx
31 pdflatex cprotect.dtx
32 pdflatex cprotect.dtx
33 mv README.txt README
34
35 The first run of pdflatex produces `cprotect.ins', `cprotect.sty',
36 `cprotect.pdf', and this file. The other commands are necessary for
37 the pdf to contain its index and glossary.
38
39
40 %</readme>
41 %<*internal>
42 \fi
43 \def\nameofplainTeX{plain}
44 \ifx\fmtname\nameofplainTeX\else
45 \expandafter\begingroup
46 \fi
47 %</internal>
48 %<*install>
49 \input docstrip.tex
50 \keepsilent
51 \askforoverwritefalse
52 \preamble
53 ----------------------------------------------------------------
54 cprotect --- verbatim in macro arguments
55 E-mail: [email protected]
56 Released under the LaTeX Project Public License v1.3c or later
57 See http://www.latex-project.org/lppl.txt
58 ----------------------------------------------------------------
59
60 \endpreamble
61 \postamble
62
63 Copyright (C) 2010-2011, 2026 by Bruno Le Floch <[email protected]>
64
65 This work may be distributed and/or modified under the
66 conditions of the LaTeX Project Public License (LPPL), either
67 version 1.3c of this license or (at your option) any later
68 version. The latest version of this license is in the file:
69
70 http://www.latex-project.org/lppl.txt
71
72 This work is "maintained" (as per LPPL maintenance status) by
73 Bruno Le Floch.
74
75 This work consists of the file cprotect.dtx
76 and the derived files cprotect.ins,
77 cprotect.pdf and
78 cprotect.sty.
79
80 \endpostamble
81 \usedir{tex/latex/cprotect}
82 \generate{
83 \file{\jobname.sty}{\from{\jobname.dtx}{package}}
84 }
85 %</install>
86 %<install>\endbatchfile
87 %<*internal>
88 \usedir{source/latex/cprotect}
89 \generate{
90 \file{\jobname.ins}{\from{\jobname.dtx}{install}}
91 }
92 \nopreamble\nopostamble
93 \usedir{doc/latex/cprotect}
94
95 \begingroup
96 \catcode`\+=9\relax
97 \generate{
98 \file{README.txt}{\from{\jobname.dtx}{readme}}
99 }
100 \endgroup
101
102 \ifx\fmtname\nameofplainTeX
103 \expandafter\endbatchfile
104 \else
105 \expandafter\endgroup
106 \fi
107 %</internal>
108 %<*package>
109 \NeedsTeXFormat{LaTeX2e}
110 \ProvidesPackage{cprotect}[2026/04/17 v1.0f (Bruno Le Floch)]
111 %</package>
112 %<*driver>
113 \documentclass[12pt]{ltxdoc}
114 \usepackage[T1]{fontenc}
115 \usepackage{cprotect}
116 \usepackage{amsmath}
117 \usepackage[margin=4cm]{geometry}
118 \usepackage{hyperref}
119 \EnableCrossrefs
120 \CodelineIndex
121 \RecordChanges
122 \begin{document}
123 \catcode`\^^@=9\relax %^^A We need an ignored character for later.
124 \DocInput{cprotect.dtx}
125 \end{document}
126 %</driver>
127 % \fi
128 %
129 % \CheckSum{0}
130 %
131 %
132 %\GetFileInfo{cprotect.sty}
133 %
134 %\DoNotIndex{\addtocounter,\advance,\afterassignment,\aftergroup,\arabic}
135 %\DoNotIndex{\begingroup,\closeout,\count,\csname,\def,\edef,\gdef,\else}
136 %\DoNotIndex{\endcsname,\endgroup,\expandafter,\fi,\ifnum,\ifthenelse,\ifx}
137 %\DoNotIndex{\immediate,\indexspace,\let,\newcommand,\newcounter,\newwrite}
138 %\DoNotIndex{\number}
139 %\DoNotIndex{\openout,\relax,\repeat,\RequirePackage,\setcounter,\string}
140 %\DoNotIndex{\stepcounter,\value,\WithSuffix,\(,\),\+,\/,\=,\@gobble}
141 %\DoNotIndex{\{}
142 %\DoNotIndex{\}}
143 %\DoNotIndex{\^}
144 %
145 %\cprotect\title{|{cprotect.sty}|\\
146 % |\verb|atim in |\macro| arguments\thanks{This file
147 % describes version \fileversion, last revised \filedate.}}
148 %\author{Bruno Le Floch\thanks{E-mail: [email protected]}}
149 %\date{Released \filedate}
150 %
151 %\maketitle
152 %
153 % \tableofcontents
154 % \changes{v1.0}{2010/12/30}{First version with documentation}
155 % \changes{v1.0b}{2011/01/01}{Filenames expanded much earlier: allows nesting.}
156 % \cprotect{\changes{v1.0b}{2011/01/01}}{Environments names were letter-only:
157 % now only control sequences are forbidden. Fixed by switching from
158 % |\catcode=11| to |12| when processing.}
159 % \cprotect[mmm]\changes{v1.0d}{2011/01/12}{|\cprotect| \oarg{spec} to
160 % cprotect a control sequence with the argument specification \meta{spec}}
161 % \changes{v1.0f}{2026/04/17}{Avoid \cs{arabic} for interoperability with polyglossia}
162 %
163 % \cprotect\section{Include \verb-\verb- anywhere!}
164 % \label{sec:intro}
165 %
166 % The |cprotect| package attempts to do something that should be
167 % impossible:\cprotect\footnote{The UK \TeX\ FAQ
168 % |http://www.tex.ac.uk/cgi-bin/texfaq2html| states:
169 % \begin{quote}
170 % So |\verb| and |\begin{verbatim}| have to assume that they are getting
171 % the first look at the parameter text; if they aren't, \TeX\ has already
172 % assigned category codes so that the verbatim command doesn't have a
173 % chance.
174 % \end{quote}
175 % The argument is quite sound, but it can be circumvented if one can change
176 % category codes once assigned, which we do.} it allows you to put verbatim
177 % in footnotes\cprotect\footnote{Like this one: \verb-!@#$%^&*()_+-.}, section
178 % titles, \ldots in a straightforward way. The section above was typeset using
179 % \begin{verbatim}
180 % \cprotect\section{Include\verb-\verb- anywhere!}\end{verbatim}
181 % and the footnote was
182 % \begin{verbatim}
183 % ...tes\cprotect\footnote{Like this one: \verb-!@#$%^&*()_+-.}\end{verbatim}
184 %
185 % More generally, let us assume that you want to use verbatim text in
186 % the argument of some macro |\cs| \marg{arg1}, and that this
187 % macro is normally allergic to verbatim. It probably has a good reason
188 % to be allergic, but using an auxiliary file, we can often solve the
189 % problem: if you want \marg{arg1} to contain verbatim, just write
190 % |\cprotect\cs| or |\cprotect{\cs}| instead of |\cs|.\cprotect\footnote{This
191 % solves most problems, for instance, verbatim text in section titles
192 % written as |\cprotect\section|\marg{title} appears correctly in the table
193 % of contents. However, there are still bugs in capitalized headers.}
194 % All the examples I give use very standard macros, but it should work
195 % with any macro.\cprotect\footnote{If you have a macro that works when it is
196 % not preceeded by |\cprotect|, but breaks down if you put |\cprotect| in
197 % front of it, I will be interested to know why.}
198 %
199 % Nesting is supported: \cs{cprotect} cannot appear in a command argument
200 % unless this command is itself \cs{cprotect}ed:
201 % \begin{verbatim}
202 % \cprotect\section{Title \cprotect\emph{emphasized} word}
203 % \end{verbatim}
204 %
205 % The first version of this package did not support macros with several
206 % arguments, nor macros with optional arguments. This new feature is
207 % accessed by giving an optional argument to \cs{cprotect}:
208 % \begin{verbatim}
209 % \cprotect[om]\section[Short title \verb-&^-]{Long title \verb-&^%$-}
210 % \end{verbatim}
211 % Each |o| stands for an optional argument (within |[]|), and |m| stands for
212 % a mandatory argument (within |{}|). For example, one can write
213 % \begin{verbatim}
214 % \[
215 % \cprotect[om]\sqrt[\verb-%c-]{\cprotect[mm]\frac{\verb-%a-}{\verb-%b-}}
216 % \]
217 % \end{verbatim}
218 % to typeset
219 % \[
220 % \cprotect[om]\sqrt[\verb-%c-]{\cprotect[mm]\frac{\verb-%a-}{\verb-%b-}}
221 % \]
222 % In fact, the |[om]| argument specifier is optional.
223 %
224 % Some commands will not accept reading from a file as a valid argument. For
225 % instance, the first argument of \cs{hyperlink} cannot be \cs{cprotect}-ed.
226 % Workaround: write |\cprotect{\hyperlink|\marg{arg1}|}|\marg{arg2}, in
227 % other words, \cs{cprotect} the combination of \cs{hyperlink} and its first
228 % argument. This trick can be tried when all else fails.
229 %
230 %
231 % \section{List of user commands}
232 % \label{sec:commandlist}
233 %
234 % \DescribeMacro{\cpro^^@tect}
235 % Possibly the single most useful command is |\cprotect|, used as
236 % |\cprotect| |\foo| \marg{arg1} or |\cprotect| \marg{cslist} \marg{arg1}.
237 % As described in the previous section, the first form behaves as
238 % |\foo| \marg{arg1}, and the second as \meta{cslist} \marg{arg1}.
239 % The difference is that the argument \marg{arg1} can now contain
240 % |\catcode| changes (e.g., induced by the |\verb| command and the
241 % |verbatim| environment). In fact, \marg{arg1} is written to a file, and
242 % then read again as the argument of |\foo|. So using the ideas behind
243 % |\cprotect|, one could in principle build weird macros that read their
244 % arguments several times, with different |\catcode|s in effect each time.
245 % The e-\TeX\ primitive \cs{scantokens} is most probably a better way to
246 % do these things, or you can try to use the experimental macro
247 % |\ReadVerbatimUntil|.
248 %
249 % \DescribeMacro{\cMakeRobust}
250 % If you find yourself using a |\cprotect\foo| combination frequently, and
251 % you try to define \cs{bar} to mean |\cprotect\foo|, you will run into
252 % trouble. The technical point is that I made \cs{cprotect} ``outer'',
253 % which prevents it from being nested in the argument of another command.
254 %
255 % However, the package provides \cs{icprotect}, which is a non-outer version
256 % of \cs{cprotect}. You can write
257 % \begin{verbatim}
258 % \outer\def\bar{\icprotect\foo}
259 % \end{verbatim}
260 % (I like to make \cs{bar} outer, to make sure that it does not get called
261 % from inside a macro argument. It is not necessary.)
262 %
263 % You can also use the typical
264 % \begin{verbatim}
265 % \let\oldfoo\foo
266 % \outer\def\foo{\icprotect\oldfoo}\end{verbatim}
267 % to redefine |\foo| itself instead of a new command |\bar|. The package
268 % provides a wrapper for this construction: |\cMakeRobust\foo| replaces |\foo|
269 % by a version which accepts verbatim. As a stupid example,
270 % \begin{verbatim}
271 % \newcommand{\expon}[1]{\mathrm{#1}^{#1}}
272 % \cMakeRobust{\expon}
273 % \(\expon{Hel\verb+|+o}\)\end{verbatim}
274 % produces
275 % \newcommand{\expon}[1]{\mathrm{#1}^{#1}}
276 % \cMakeRobust{\expon}
277 % \(\expon{Hel\verb+|+o}\), and the verbatim is treated correctly.
278 %
279 %
280 % \DescribeMacro{\cprotEnv}
281 % Some\cprotect\footnote{Todo: rethink \cs{cprotEnv}.}
282 % environments do not really behave as environment in that they
283 % read their argument before acting on it. One such example is |amsmath|'s
284 % |align| environment. For these cases, use |\cprotEnv| as follows. Simply
285 % put |\cprotEnv| |\begin| \marg{name} instead of |\begin| \marg{name}. For
286 % example,
287 % \begin{verbatim}
288 % \cprotEnv\begin{align}
289 % x&=\begin{cases}
290 % 1 &\text{if }\verb"@#%^&*"\\
291 % 2 &\text{otherwise}
292 % \end{cases}
293 % \end{align}\end{verbatim}
294 % gives
295 % \cprotEnv\begin{align}
296 % x&=\begin{cases}
297 % 1 &\text{if }\verb"@#%^&*"\\
298 % 2 &\text{otherwise}
299 % \end{cases}
300 % \end{align}
301 % Beware: the |align| environment does something weird at the measuring
302 % step, and \cs{cprotect} will not work very easily (see Section~\ref{sec:bugs}
303 % on bugs below).
304 %
305 % You can use |\CPTbegin| as a short-hand for |\cprotEnv\begin|, but this will
306 % fail when nesting the same environment twice (admittedly, this is rare): the
307 % inner nesting is distinguished by \emph{precisely} the characters
308 % \texttt{\string\begin\{\emph{name}\}}.
309 %
310 %
311 % \DescribeMacro{\ReadVerbatimUntil}
312 % Finally, an odd half-deprecated macro. We use all of the auxiliary macros
313 % that are involved in its construction, but not \cs{ReadVerbatimUntil}
314 % anymore (the code has to be rewritten to make things clearer.
315 %
316 % The aim of this command is to read a
317 % piece of text verbatim, until it reaches an end-marker.
318 % It then writes all that it has read to an auxiliary file for
319 % future use. The most naive approach has a major flaw when nesting is
320 % involved: when parsing |...{}}| for instance, with an end-marker of |}|, we
321 % often wish to stop at the \emph{second} closing bracket, not the first one.
322 % Thus, |\ReadVerbatimUntil| needs to be aware of a begin-marker. Also, for
323 % some applications we need to write things before and after the content
324 % read by |\ReadVerbatimUntil|. Finally, we want to do something once the
325 % file has been written, and possibly something before.
326 %
327 % The syntax is thus |\ReadVerbatimUntil| \oarg{arg1} \marg{arg2}
328 % |^begin|\-|text^end|\-|text^begin|\-|tag^end|\-|tag^|, followed by the text
329 % in which we look for |endtag|. The caret (|^|) can be any character.
330 % It delimits the four verbatim-like arguments of
331 % |\ReadVerbatimUntil|. The strings of letters |begintext|
332 % and |endtext| are pre- and ap-pended to the file. As mentionned before,
333 % |begintag| and |endtag| are used when reading the content, to determine
334 % how far |\ReadVerbatimUntil| should go. The mandatory argument
335 % \marg{arg2} is executed once the whole text has been stored to a file.
336 % Typically, \marg{arg2} involves reading the file one or more times,
337 % and acting on it in any way we like. The optional argument can be used for
338 % hacks such as changing where |cprotect| writes its files.
339 %
340 %
341 % \section{Technical points}
342 %
343 % [...] Will break if |^| does not have its usual catcode at the beginning
344 % and at the end of the \cs{cprotect}ed command.
345 %
346 % Also, will break if |^^E| or |^^L| change catcodes. This choice of symbols
347 % can be changed by setting the options |gobbling-escape =| \meta{letter}, and
348 % |gobbling-letter =| \meta{letter}. The defaults are |gobbling-escape = E| and
349 % |gobbling-letter = L|.
350 %
351 %
352 %
353 % \section{Known bugs/limitations}
354 % \label{sec:bugs}
355 %
356 % Incompatibility with |\pagestyle{headings}|: when a chapter title is put
357 % as a header, it gets upper-cased. If you did |\cprotect\chapter{...}| as
358 % usual, the title has been stored to a file, but now, the name of the file
359 % is capitalized, and \TeX\ cannot find it.
360 %
361 % Issues with nesting of |\cprotect| in |align| environments: the |align|
362 % environment is being too clever with counting braces in its argument.
363 % But we do nasty things to braces, such as |\let\foo{|\iffalse}\fi. This
364 % should in fact not be counted as a brace\cprotect\footnote{In some sense,
365 % it defines |\foo| to be an opening brace.}, but |align| has no way of knowing
366 % that. Thus, it expects a closing brace when there will be none. A workaround
367 % is to add \iffalse{\fi|\iffalse}\fi| in the body of the align environment,
368 % after any |\cprotect|. Also, the |align| environment itself should be
369 % protected. Here is an example (three |\cprotect|, hence three closing braces):
370 % \begin{verbatim}
371 % \cprotEnv\begin{align*}
372 % \sum\cprotect_{\verb"\k" = 1}\cprotect^{\verb"\N"} \verb"\k"
373 % = \cprotect\frac{\verb"\N"(\verb"\N"+1)}{2} \iffalse}}}\fi
374 % \end{align*} \end{verbatim}
375 % \cprotEnv\begin{align*}
376 % \sum\cprotect_{\verb"\k" = 1}\cprotect^{\verb"\N"} \verb"\k"
377 % = \cprotect\frac{\verb"\N"(\verb"\N"+1)}{2} \iffalse}}}\fi
378 % \end{align*}
379 %
380 % For commands with two or more arguments, it is only possible to put verbatim
381 % in one of the arguments (and the syntax is not great).
382 %
383 % The argument of any command that is prefixed with |\cprotect| has to have
384 % balanced braces, \emph{even when hidden inside verbatim environments, or
385 % behind a comment character}. For instance,
386 % \begin{verbatim}
387 % \cprotect\footnote{On the \verb:{: character} \end{verbatim}
388 % would fail: |\cprotect| would see the brace in |\verb:{:|, and count it
389 % as an opening tag, which then has to be closed. This is most likely
390 % to lead |\cprotect| to gobble the whole file before complaining. Similarly,
391 % \begin{verbatim}
392 % \cprotect\footnote{On the \verb:!: %should it be }?
393 % character}\end{verbatim}
394 % would only gobble until the closing brace in |%should it be }?|, and
395 % I am not sure what error would be produced.
396 %
397 % But we can use one ailment to cure the other! A correct way to typeset
398 % the first example is
399 % \begin{verbatim}
400 % \cprotect\footnote{On the \verb:{: character%}
401 % } \end{verbatim}
402 % if |%| is a comment character at the time it is read. A safer solution
403 % would be to use |\iffalse}\fi| instead of |%}|. It still requires to
404 % be sure that |\| is an escape character when this piece of code is read,
405 % and can lead to problems if the previous token is |\let| for instance.
406 %
407 %
408 %
409 % \section{The code}
410 % \label{sec:code}
411 %
412 %\StopEventually{\PrintChanges\PrintIndex}
413 %
414 % \begin{macrocode}
415 %<*package>
416 % \end{macrocode}
417 %
418 % \subsection{Setting up}
419 %
420 % We first load a few packages
421 % \begin{macrocode}
422 \RequirePackage{ifthen}
423 \RequirePackage{suffix}
424 % \end{macrocode}
425 %
426 % We borrow the idea of quark from |expl3|: |\CPT@qend| expands to
427 % itself, useful for |\ifx| comparisons.
428 % \begin{macrocode}
429 \def\CPT@qend{\CPT@qend}
430 \def\CPT@option@head#1=#2\CPT@qend{#1}
431 \def\CPT@option@tail#1=#2\CPT@qend{#2}
432 \DeclareOption*{%
433 \ifthenelse{%
434 \equal{gobbling-escape}{%
435 \expandafter\CPT@option@head\CurrentOption=\CPT@qend}%
436 }{%
437 \edef\CPT@gobbling@escape{%
438 \expandafter\CPT@option@tail\CurrentOption\CPT@qend
439 }%
440 }{%
441 \ifthenelse{%
442 \equal{gobbling-letter}{%
443 \expandafter\CPT@option@head\CurrentOption=\CPT@qend}%
444 }{%
445 \edef\CPT@gobbling@letter{%
446 \expandafter\CPT@option@tail\CurrentOption\CPT@qend
447 }%
448 }{%
449 \PackageError{cprotect}{Unknown option \CurrentOption}{}%
450 }%
451 }%
452 }
453 \def\CPT@gobbling@escape{E}
454 \def\CPT@gobbling@letter{L}
455 \ProcessOptions\relax
456 % \end{macrocode}
457 %
458 % Then we introduce the commands pertaining to writing
459 % files.\footnote{To be rewritten. For the moment, we use a new file
460 % each time cprotect is used. Thus, many files. But this is needed if
461 % people want to nest cprotect's.}
462 %
463 % We write files |\jobname-1.cpt|, |\jobname-2.cpt|, etc. in order.
464 % \begin{macrocode}
465 \newwrite\CPT@WriteOut
466 \newcounter{CPT@WriteCount}
467 \edef\CPT@filename{\jobname.cpt}
468 \newcommand{\CPT@Write}[1]{%
469 \immediate\openout\CPT@WriteOut=\CPT@filename%
470 \newlinechar`\^^M%
471 \immediate\write\CPT@WriteOut{#1}%
472 \immediate\closeout\CPT@WriteOut%
473 \expandafter\xdef\csname CPT@\CPT@filename\endcsname{%
474 \noexpand\scantokens{#1}%
475 }%
476 %\expandafter\gdef\csname \string\CPT@\CPT@filename\expandafter\endcsname\expandafter{%
477 % \expandafter\protect\csname CPT@\CPT@filename\endcsname}%
478 %\expandafter\show\csname \string\CPT@\CPT@filename\endcsname%
479 %\expandafter\show\csname CPT@\CPT@filename\endcsname%
480 }
481 % \end{macrocode}
482 %
483 %
484 % The next command changes all catcodes to ``other''. It was adapted from
485 % |filecontents.sty|.
486 % \begin{macrocode}
487 \newcommand{\makeallother}{%
488 \count0=0\relax
489 \loop
490 \catcode\count0=12\relax
491 \advance\count0 by 1\relax
492 \ifnum\count0<256
493 \repeat
494 }
495 % \end{macrocode}
496 %
497 %
498 % \begin{macro}{\CPT@gobbling@escape}
499 % \begin{macro}{\CPT@gobbling@letter}
500 % \changes{v1.0c}{Replaced \cs{relax} by |^^L|, with |L| customizable.}
501 % We make the active character |^^L| of charcode 11
502 % [letter...], and define it to expand
503 % to \cs{relax} (was hoping to make it
504 % invalid most of the time, but that fails) [...]. Also, failure if |^| is not
505 % of catcode ``superscript''.
506 %
507 % \cs{CPT@escape@hat@hat@L} contains the string of characters |\^^L|, with
508 % |L| replaced by the value of \cs{CPT@gobbling@letter}.
509 %
510 % \cs{CPT@hat@hat@E@hat@hat@L} contains the string of characters
511 % |^^E^^L| where |^^E| is the escape character, and |^^L| is the active
512 % charace.
513 %
514 % We define \cs{CPT@hat@hat@E@hat@hat@L} to be empty: it will simply
515 % be used to
516 % gobble the initial space at the beginning of environments and hide the
517 % end-of-line token that e\TeX\ inserts for every \cs{scantokens}.
518 %
519 % \begin{macrocode}
520 {
521 \catcode`\/=0
522 /catcode`/\=12
523 /catcode`/^=12
524 /xdef/CPT@escape@hat@hat@L{\^^/CPT@gobbling@letter/space}
525 /xdef/CPT@escape@hat@hat@E{\^^/CPT@gobbling@escape/space}
526 /xdef/CPT@hat@hat@E@hat@hat@L{%
527 ^^/CPT@gobbling@escape^^/CPT@gobbling@letter/space}
528 }
529 \expandafter\scantokens\expandafter{%
530 \expandafter\catcode\expandafter`\CPT@escape@hat@hat@E=0}
531 \expandafter\scantokens\expandafter{%
532 \expandafter\catcode\expandafter`\CPT@hat@hat@E@hat@hat@L=11}
533 \expandafter\scantokens\expandafter{%
534 \expandafter\def\CPT@hat@hat@E@hat@hat@L{}}
535 % \end{macrocode}
536 % \end{macro}
537 % \end{macro}
538 %
539 % \cprotect\subsection{|\ReadVerbatimUntil|}
540 % Both |\ReadVerbatimUntil| and its starred version (which we define using
541 % the |suffix.sty| package) take one optional argument \oarg{first-cs} and
542 % a mandatory argument \marg{final-cs}. The \meta{final-cs} is saved as
543 % |\CPT@commandatend| to be executed when we close the file (and the
544 % group).\cprotect\footnote{It is not a straightforward |\aftergroup|,
545 % because I want this to be executed after another |\aftergroup| that
546 % comes later.}
547 % \begin{macrocode}
548 \newcommand\ReadVerbatimUntil[2][]{%
549 \def\CPT@commandatend{#2}%
550 \begingroup #1%
551 \makeallother%
552 \CPT@setup}
553 \WithSuffix\newcommand\ReadVerbatimUntil*[2][]{%
554 \def\CPT@commandatend{#2}%
555 \begingroup #1%
556 \makeallother%
557 \CPT@starsetup}
558 % \end{macrocode}
559 %
560 % |\CPT@setup| reads the four ``verbatim'' arguments following
561 % \marg{final-cs}, and stores them in this order as macros |\CPT@preText|,
562 % |\CPT@postText|, |\CPT@begin|, and |\CPT@end|. The macros which read each
563 % of these arguments need to be defined inside |\CPT@setup|, because
564 % I don't want any constraint on the delimiter. I could write a single
565 % macro that gobbles all four arguments at once, but this would require
566 % a crazy number of |\expandafter|s, so instead I do it one by one.
567 %
568 % If the delimiter was given, say |^|, then we would define |\CPT@readBegin|
569 % as |\def \CPT@readBegin#1^{\def \CPT@begin{#1}\CPT@readEnd}|.
570 % But since |^| is not given explicitly, we need |\expandafter|s to
571 % expand it before the definition takes place. To avoid code repetition,
572 % I did it once and for all in the auxiliary macro |\CPT@def|. Note that
573 % a parameter of |##1| is somehow hidden inside |\CPT@def|, and that the
574 % |##1| inside the replacement text refer to the arguments of the
575 % |\CPT@read...| macros.
576 % \begin{macrocode}
577 \newcommand{\CPT@def}[2]{\expandafter\def\expandafter#1%
578 \expandafter##\expandafter1#2}
579 \newcommand{\CPT@setup}[1]{%
580 \def\CPT@delimiter{#1}%
581 \CPT@def\CPT@readPreText\CPT@delimiter{%
582 \def\CPT@preText{##1}\CPT@readPostText}%
583 \CPT@def\CPT@readPostText\CPT@delimiter{%
584 \def\CPT@postText{##1}\CPT@readBegin}%
585 \CPT@def\CPT@readBegin\CPT@delimiter{%
586 \def\CPT@begin{##1}\CPT@readEnd}%
587 \CPT@def\CPT@readEnd\CPT@delimiter{%
588 \def\CPT@end{##1}\CPT@readContent}%
589 \CPT@readPreText%
590 }
591 \newcommand{\CPT@starsetup}[1]{\CPT@setup#1#1#1}
592 % \end{macrocode}
593 % We also give the variant |\CPT@starsetup|, which has empty
594 % |\CPT@preText| and |\CPT@postText|.
595 %
596 % When |\CPT@setup| is expanded, it will call |\CPT@|\-|readPreText|,
597 % |\CPT@|\-|readPostText|, |\CPT@|\-|readBegin|, and |\CPT@|\-|readEnd|,
598 % and finish with |\CPT@|\-|readContent|, which we describe now.
599 %
600 %
601 % The counter |CPT@numB| will count
602 % the surplus of |begin-tag|s compared to |end-tag|s when we parse the text
603 % following |\CPT@readContent|. And |\CPT@store| is a macro that adds its
604 % argument to an other macro (I was too lazy to learn about token lists).
605 % The storage itself will be initialized later.
606 % \begin{macrocode}
607 \newcounter{CPT@numB}
608 \newcommand{\CPT@store}[1]{\edef\CPT@storage{\CPT@storage#1}}
609 % \end{macrocode}
610 %
611 % The macro |\CPT@readContent| is quite tricky: if the |begin-tag| and
612 % |end-tag| were one character, things would be easy: I would read one
613 % character at a time, and compare it to both |begin-tag| and |end-tag|,
614 % then either store it, and possibly increase or decrease |CPT@numB|, or
615 % decide that I am done if |CPT@numB| becomes negative.
616 %
617 % Unfortunately, I want to use |\ReadVerbatimUntil| for environments, in
618 % which case the |begin-tag| is |\begin{myenv}| and the |end-tag| is
619 % |\end{myenv}|. So two options:
620 % \begin{itemize}
621 % \item code a standard string searching algorithm... I did not feel
622 % like it, but it might lead to a regexp package later on;
623 % \item use \TeX's delimited parameters.
624 % \end{itemize}
625 % I did the latter, using |\CPT@def| again (we want to expand the string
626 % which delimits the parameter before doing the definition).
627 %
628 % The details are ugly:
629 % \begin{itemize}
630 % \item gobble until the first |end-tag|,\cprotect\footnote{This will fail for
631 % devious cases: if |begin-tag| is |abc| and |end-tag| is |bcd|, and
632 % |\CPT@readContent| is followed by |abcd...|: we will wrongly see
633 % |bcd| as an |end-tag|.} and insert a fake |begin-tag|, as well as the
634 % quark guard |\CPT@qend|,
635 % \item inside what we gobbled, gobble |begin-tag|s until reaching the fake
636 % one (marked by the quark guard).
637 % \item continue until we have one more |end-tag| than |begin-tag|.
638 % \end{itemize}
639 % \begin{macrocode}
640 \newcommand{\CPT@readContent}{%
641 \CPT@def\CPT@gobbleOneB\CPT@begin##2{%
642 \ifx\CPT@qend##2\CPT@store{##1}\addtocounter{CPT@numB}{-1}%
643 \else\CPT@store{##1\CPT@begin}\stepcounter{CPT@numB}%
644 \expandafter\CPT@gobbleOneB\expandafter##2\fi}%
645 %
646 \CPT@def\CPT@gobbleUntilE\CPT@end{%
647 \edef\CPT@tempi{##1\CPT@begin}%
648 \expandafter\CPT@gobbleOneB\CPT@tempi\CPT@qend%
649 \ifthenelse{\value{CPT@numB}<0}{%
650 \CPT@store{\CPT@postText}%
651 \CPT@Write{\CPT@storage}\endgroup%
652 \CPT@commandatend%
653 }{%
654 \CPT@store{\CPT@end}\CPT@gobbleUntilE%
655 }%
656 }%
657 \setcounter{CPT@numB}{0}%
658 \def\CPT@storage{\CPT@preText}%
659 \CPT@gobbleUntilE%
660 }
661 % \end{macrocode}
662 %
663 %
664 % \cprotect\subsection{For macros: |\cprotect| and friends}
665 %
666 % \begin{macro}{\cpro^^@tect}
667 % \changes{v1.0c}{2011/01/11}{Made \cs{cprotect} \cs{outer}, and introduced
668 % \cs{icprotect}.}
669 % Equipped with |\ReadVerbatimUntil|, we are ready for the more practical
670 % macros. |\cprotect| cheats: it uses |{| and |}| as a |begin-tag| and
671 % |end-tag|. This works most of the time, but fails in cases such as those
672 % presented in Section~\ref{sec:bugs} (in usual cases there are
673 % workarounds\cprotect\footnote{But I could definitely not have the contents of
674 % this |.dtx| file as a (huge) footnote in some document: since |{| and |}|
675 % change |\catcode|s, it is unlikely that the numbers balance correctly.}).
676 %
677 % We define |\cprotect| as |\outer|, as a check that it is the first
678 % to read its argument. A neat thing is that |\cprotect| will complain
679 % if it is nested inside anything, \cprotect\emph{except if the enclosing
680 % macro is itself |\cprotect|ed}.\footnote{In particular, the author of this
681 % documentation had to use a devious trick (namely, have an ignored character
682 % in the midst of the name) to include even the name of the macro in the left
683 % margin.}
684 %
685 % \begin{macrocode}
686 \outer\long\def\cprotect{\icprotect}
687 % \end{macrocode}
688 % Normally, one should always use |\cprotect|. In some rare cases, it can be necessary
689 % to overcome the |\outer|ness of |\cprotect|. For this we provide |\icprotect|,
690 % where |i| stands for |i|nternal.
691 %
692 % |\icprotect| \oarg{spec} \marg{\cs{cs}} takes as a mandatory argument the control sequence
693 % \cs{cs} that we are protecting, and as a first, optional, argument the argument specification
694 % of \cs{cs}, in the |xparse| style: |m| for mandatory arguments, |o| for optionals,
695 % etc.\cprotect\footnote{Todo: list all the arguments that are supported: for the moment,
696 % |o| and |m|.} \emph{\textbf{No spaces, i.e.,
697 % \texttt{[om]}, not \texttt{[o m]}!}}
698 % \begin{macrocode}
699 \newtoks\CPT@commandatend@toks
700 \newcommand{\icprotect}[2][om]{%
701 \def\CPT@argsig{#1}%
702 \def\CPT@cs{#2}%
703 \CPT@commandatend@toks{#2}%
704 \def\CPT@commandatend{\CPT@read@args}% used by RVU.
705 \CPT@commandatend%
706 }
707 \def\CPT@argsig@pop{%
708 \edef\CPT@argsig{\expandafter\@gobble\CPT@argsig}%
709 }
710 % \end{macrocode}
711 % \end{macro}
712 %
713 % Currently, \cs{CPT@read@args} is simply a synonym.
714 %
715 % \begin{macrocode}
716 %\newcommand\CPT@read@args{\CPT@read@m}
717 \newcommand\CPT@read@args{%
718 \ifx\CPT@argsig\empty
719 \expandafter\the\expandafter\CPT@commandatend@toks
720 \else
721 \expandafter\expandafter\expandafter\CPT@read@one
722 \expandafter\CPT@argsig\expandafter\CPT@qend%
723 \fi
724 }
725 \def\CPT@read@one#1#2\CPT@qend{%
726 \def\CPT@argsig{#2}%
727 \def\CPT@tempii{\csname CPT@read@#1\endcsname}% To make the \afterassignment simpler.
728 \afterassignment\CPT@tempii\let\CPT@next=%
729 }
730 % \end{macrocode}
731 %
732 %
733 % \subsubsection{Mandatory arguments}
734 %
735 %
736 % First, we learn how to parse mandatory arguments. We define \cs{CPT@read@m} to read a
737 % mandatory (braced) argument. Note the use of |\bgroup| in |\CPT@read@m|: if the argument
738 % of |\cs| starts with an opening brace, it has been read early, and its |\catcode| will
739 % still be |1|.\cprotect\footnote{I am not sure whether catcodes really matter
740 % in such an |\ifx|.}
741 %
742 % We check whether the next token is a brace or not:
743 % \begin{itemize}
744 % \item If it is, we discard the |{|, and the argument of \cs{cs} stops
745 % at the matching explicit closing brace |}|. (See \cs{CPT@read@mbeg} below,
746 % where |beg| stands for an opening brace.)
747 % \item If it is not, the argument of \cs{cs} is this token only, and there is
748 % no need for \cs{cprotect}ion (see \cs{CPT@read@mone} below).
749 % \end{itemize}
750 %
751 % \begin{macrocode}
752 \newcommand\CPT@read@m{%
753 \ifx\CPT@next\bgroup%
754 \expandafter\CPT@read@mbeg%
755 \else%
756 \expandafter\CPT@read@mone%
757 \fi%
758 }
759 \def\CPT@read@mone{\CPT@cs\CPT@next}
760 % \end{macrocode}
761 %
762 % Since |\ReadVerbatimUntil| makes everything into others, we need braces
763 % to be others when we define most macros in this Section. We thus need
764 % a few |\catcode| changes. Think of \(|{|\to|(|\) and \(|}|\to|)|\).
765 % \begin{macrocode}
766 \begingroup
767 \catcode`\{=12 \catcode`\}=12
768 \catcode`\(=1 \catcode`\)=2
769 \gdef\CPT@other@bgroup({)
770 \gdef\CPT@other@egroup(})
771 \endgroup
772 % \end{macrocode}
773 %
774 % \cs{CPT@read@mbeg} to read a braced mandatory argument once the begin-group symbol
775 % has been read.
776 % \begin{macrocode}
777 \def\CPT@read@mbeg{%
778 \stepcounter{CPT@WriteCount}%
779 \edef\CPT@filename{\jobname-\number\c@[email protected]}%
780 \expandafter\expandafter\expandafter\CPT@commandatend@toks
781 \expandafter\expandafter\expandafter{%
782 \expandafter\the
783 \expandafter\CPT@commandatend@toks
784 % Input a file:
785 \expandafter{%
786 \expandafter\protect
787 \expandafter\input
788 \CPT@filename
789 \relax
790 }%
791 % % Using \scantokens: requires '%' active.
792 % \expandafter{%
793 % \csname \string\CPT@\CPT@filename\endcsname
794 % \expandafter\protect
795 % \expandafter\csname CPT@\CPT@filename\endcsname
796 % }%
797 }%
798 %\showthe\CPT@commandatend@toks%
799 % \end{macrocode}
800 % We append |{\protect \input| \meta{file name}|relax}| at the end of the
801 % token list \cs{CPT@commandatend@toks}. Then we set \cs{CPT@commandatend}
802 % to be this token list. The role of \cs{CPT@commandatend} is to be executed
803 % once the matching |}| is found. Note the \cs{protect}, necessary for
804 % things to work well inside \cs{section}.
805 %
806 % Since we |\edef|ed, |\CPT@filename| contains the expanded version of the
807 % filename. We then use many |\expandafter|s in order to expand the filename
808 % now: we are then sure that the right file will be input as an argument of
809 % |\CPT@cs| (this is the |\cprotect|ed command).
810 %
811 % \begin{macrocode}
812 \begingroup%
813 \makeallother%
814 \def\CPT@preText{}%
815 \let\CPT@postText\CPT@hat@hat@E@hat@hat@L%
816 \let\CPT@begin\CPT@other@bgroup%
817 \let\CPT@end\CPT@other@egroup%
818 \CPT@readContent%
819 }%
820 % \end{macrocode}
821 %
822 %
823 % \cprotect\subsubsection{Optional (|o|) and delimited (|d**|) arguments}
824 %
825 % \cs{CPT@read@o} (for scanning standard optional arguments) is defined to be
826 % \cs{CPT@read@d[]}.
827 % \begin{macrocode}
828 \def\CPT@read@o{\CPT@read@d[]}
829 % \end{macrocode}
830 %
831 % Now for delimited arguments, \cs{CPT@read@d} takes two arguments (the two
832 % delimiters). If the next token, \cs{CPT@next} is the same \emph{character}
833 % as the opening delimiter |#1|, then we read the argument with
834 % \cs{CPT@read@d@beg}. Otherwise, we use \cs{CPT@read@d@none}.
835 % \begin{macrocode}
836 \def\CPT@read@d#1#2{%
837 \if\noexpand\CPT@next#1%
838 \expandafter\CPT@read@d@beg%
839 \else%
840 \expandafter\CPT@read@d@none%
841 \fi%
842 {#1}{#2}%
843 }
844 \def\CPT@read@d@none#1#2{%
845 \CPT@read@args\CPT@next%
846 }
847 % \end{macrocode}
848 %
849 % \cs{CPT@read@d@beg} to read a delimited argument once (if) the beginning
850 % symbol \cs{CPT@d@begin} has been found. The begin-tag and end-tag used by
851 % \cs{ReadVerbatimUntil} and its friends are here \cs{CPT@d@begin} and
852 % \cs{CPT@d@end}. Errata: replaced by |#1| and |#2|.
853 % \begin{macrocode}
854 \def\CPT@read@d@beg#1#2{%
855 \stepcounter{CPT@WriteCount}%
856 \edef\CPT@filename{\jobname-\number\c@[email protected]}%
857 \expandafter\expandafter\expandafter\CPT@commandatend@toks%
858 \expandafter\expandafter\expandafter{%
859 \expandafter\the%
860 \expandafter\CPT@commandatend@toks%
861 \expandafter #1%
862 \expandafter\protect%
863 \expandafter\input%
864 \CPT@filename%
865 \relax%
866 #2%
867 }%
868 % \end{macrocode}
869 %
870 % Since we |\edef|ed, |\CPT@filename| contains the expanded version of the
871 % filename. We then use many |\expandafter|s in order to expand
872 % \cs{CPT@d@begin}, \cs{CPT@d@end}, and \cs{CPT@filename}
873 % the filename now: we are then sure that the right file will be input as
874 % an argument of |\CPT@cs| (this is the |\cprotect|ed command).
875 %
876 % \begin{macrocode}
877 \begingroup%
878 \makeallother%
879 \def\CPT@preText{}%
880 \let\CPT@postText\CPT@hat@hat@E@hat@hat@L%
881 \def\CPT@begin{#1}%
882 \def\CPT@end{#2}%
883 \CPT@readContent%
884 }%
885 % \end{macrocode}
886 %
887 %
888 %
889 % Finally, the |\cMakeRobust| command is a mess, and could probably be improved,
890 % although... it works |:)|. We make the new command \cs{outer}, and use
891 % the inner version \cs{icprotect} of \cs{cprotect}.
892 % \begin{macrocode}
893 \newcommand{\cMakeRobust}[1]{%
894 \def\CPT@cs@name{\expandafter\@gobble\string#1}%
895 \expandafter\let\csname CPT@old@\CPT@cs@name\endcsname #1%
896 \expandafter\outer\expandafter\def\csname\CPT@cs@name\endcsname{%
897 \expandafter\icprotect\csname CPT@old@\CPT@cs@name\endcsname}%
898 }
899 % \end{macrocode}
900 %
901 %
902 % \cprotect\subsection{For Environments: |\cprotEnv\begin| and |\CPTbegin|}
903 %
904 % \DescribeMacro{\CPTbegin}
905 % We introduce the command |\CPTbegin|, which has a behaviour close to
906 % the behaviour of |\begin|. Namely, |\CPTbegin{env}| gobbles its argument
907 % until it sees the matching |\end|, and it writes what it gobbled to
908 % a file. It then inputs the file between |\begin{...}| and |\end{...}|,
909 % as we can see from the definition of |\CPT@commandatend|.
910 %
911 % As for the case of |\cprotect|, we need to setup the values of the four
912 % arguments of |\ReadVerbatimUntil| before reading the content. Since
913 % the |begin-tag| and |end-tag| depend on a parameter, it would be
914 % incredibly messy to try to expandafter the right things, so we
915 % define |\CPT@env@setup| to, well, setup the values of the four
916 % arguments of |\ReadVerbatimUntil|, and then skip directly to
917 % |\CPT@readContent|.
918 %
919 % \begin{macrocode}
920 \newcommand{\CPTbegin}[1]{%
921 \stepcounter{CPT@WriteCount}%
922 \edef\CPT@filename{\jobname-\number\c@[email protected]}%
923 \edef\CPT@commandatend{%
924 \noexpand\begin\noexpand{\noexpand#1\noexpand}%
925 \noexpand\expandafter\noexpand\protect%
926 \noexpand\expandafter\noexpand\input \CPT@filename\relax%
927 \noexpand\end\noexpand{\noexpand#1\noexpand}%
928 }%
929 % \end{macrocode}
930 % Here, we are defining |\CPT@commandatend| to be |\begin{#1}|
931 % |\expandafter| |\protect| |\expandafter| |\input| \meta{filename}
932 % |\end{#1}|, where \meta{filename} is |\CPT@filename|, fully expanded.
933 % Is there a cleaner way of doing that, given how far in the definition
934 % |\CPT@filename| is?
935 % \begin{macrocode}
936 \begingroup%
937 \CPT@env@setup{#1}%
938 \makeallother%
939 \CPT@readContent%
940 }
941 % \end{macrocode}
942 %
943 % As announced, |\CPT@env@setup|, defined with lots of catcode changes
944 % [\emph{this paragraph is not up to date}].
945 % Since the catcode of |\| changes, I need an extra escape character,
946 % which I take to be |/|. I use two groups so each group is opened and
947 % closed using the same escape character (this is technically irrelevant,
948 % but seems less messy).
949 % \begin{macrocode}
950 \newcommand{\CPT@otherify}[1]{%
951 \expandafter\expandafter\expandafter\@gobble
952 \expandafter\string\csname #1\endcsname
953 }
954 \newcommand{\CPT@env@setup}[1]{%
955 \def\CPT@temp{#1}%
956 \edef\CPT@temp{\CPT@otherify{#1}}%
957 \edef\CPT@temp{\expandafter\strip@prefix\meaning\CPT@temp}%
958 \expandafter\CPT@env@setup@\expandafter{\CPT@temp}%
959 }
960 \def\CPT@env@setup@#1{%
961 \let\CPT@preText\CPT@hat@hat@E@hat@hat@L%
962 \let\CPT@postText\CPT@hat@hat@E@hat@hat@L%
963 \edef\CPT@begin{\string\begin\string{#1\string}}%
964 \edef\CPT@end{\string\end\string{#1\string}}%
965 }
966 % \end{macrocode}
967 %
968 % A final piece of code is needed so that |\CPT|-environments can be
969 % nested: in order to be able to nest, we need |\ReadVerbatimUntil|
970 % to be aware that our environment has been opened when |\CPTbegin{foo}|
971 % or |\begin{foo}| appear in the text. Given the rules for delimited
972 % parameters in TeX, this is quite difficult. A workaround is to replace
973 % |\CPTbegin| by something that ends in |\begin| shuch as |\cprotEnv\begin|
974 % as defined below. Thus, for nesting to work, you need to prepend every
975 % one of your |env| environments with |\cprotEnv|.
976 % \begin{macrocode}
977 \def\cprotEnv\begin{\CPTbegin}
978 % \end{macrocode}
979 %
980 % \begin{macrocode}
981 %</package>
982 % \end{macrocode}
983 %\Finale
984 \endinput