summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/cprotect/cprotect.dtx
blob: eafe0d6d20db0cfab37eb1842601689d67fb459b (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
% \iffalse meta-comment
%<*internal>
\iffalse
%</internal>
%<*readme>
%^^A To generate the readme, we make + into an ignored character!!
----------------------------------------------------------------
cprotect --- verbatim in macro arguments
E-mail: blflatex@gmail.com
Released under the LaTeX Project Public License v1.3c or later
See http://www.latex-project.org/lppl.txt
----------------------------------------------------------------

A user of the cprotect.sty package can include verbatim text (\verb,
verbatim environment, ...) in the argument of any command, 
including moving arguments. Including verbatim text in footnotes, 
section titles (and other titles), etc. is as simple as typing 
`\cpro+tect\footnote` instead of `\footnote`, etc. 

A similar approach is taken for environments. Nesting of the 
various environments is taken into account.

This is work in progress, all comments/bug reports are welcome!


The whole package can be built from the file `cprotect.dtx' by running

pdflatex cprotect.dtx
makeindex -s gglo.ist -o cprotect.gls cprotect.glo
makeindex -s gind.ist -o cprotect.ind cprotect.idx
pdflatex cprotect.dtx
pdflatex cprotect.dtx
mv README.txt README

The first run of pdflatex produces `cprotect.ins', `cprotect.sty',
`cprotect.pdf', and this file. The other commands are necessary for
the pdf to contain its index and glossary.


%</readme>
%<*internal>
\fi
\def\nameofplainTeX{plain}
\ifx\fmtname\nameofplainTeX\else
  \expandafter\begingroup
\fi
%</internal>
%<*install>
\input docstrip.tex
\keepsilent
\askforoverwritefalse
\preamble
----------------------------------------------------------------
cprotect --- verbatim in macro arguments
E-mail: blflatex@gmail.com
Released under the LaTeX Project Public License v1.3c or later
See http://www.latex-project.org/lppl.txt
----------------------------------------------------------------

\endpreamble
\postamble

Copyright (C) 2010-2011 by Bruno Le Floch <blflatex@gmail.com>

This work may be distributed and/or modified under the
conditions of the LaTeX Project Public License (LPPL), either
version 1.3c of this license or (at your option) any later
version.  The latest version of this license is in the file:

http://www.latex-project.org/lppl.txt

This work is "maintained" (as per LPPL maintenance status) by
Bruno Le Floch.

This work consists of the file  cprotect.dtx
and the derived files           cprotect.ins,
                                cprotect.pdf and
                                cprotect.sty.

\endpostamble
\usedir{tex/latex/cprotect}
\generate{
  \file{\jobname.sty}{\from{\jobname.dtx}{package}}
}
%</install>
%<install>\endbatchfile
%<*internal>
\usedir{source/latex/cprotect}
\generate{
  \file{\jobname.ins}{\from{\jobname.dtx}{install}}
}
\nopreamble\nopostamble
\usedir{doc/latex/cprotect}

\begingroup
\catcode`\+=9\relax
\generate{
  \file{README.txt}{\from{\jobname.dtx}{readme}}
}
\endgroup

\ifx\fmtname\nameofplainTeX
  \expandafter\endbatchfile
\else
  \expandafter\endgroup
\fi
%</internal>
%<*package>
\NeedsTeXFormat{LaTeX2e}
\ProvidesPackage{cprotect}[2011/01/27 v1.0e (Bruno Le Floch)]
%</package>
%<*driver>
\documentclass[12pt]{ltxdoc}
\usepackage[T1]{fontenc}
\usepackage{cprotect}
\usepackage{amsmath}
\usepackage[margin=4cm]{geometry}
\usepackage{hyperref}
\EnableCrossrefs
\CodelineIndex
\RecordChanges
\begin{document}
  \catcode`\^^@=9\relax %^^A We need an ignored character for later.
  \DocInput{cprotect.dtx}
\end{document}
%</driver>
% \fi
% 
% \CheckSum{0}
%
%
%\GetFileInfo{cprotect.sty}
%
%\DoNotIndex{\addtocounter,\advance,\afterassignment,\aftergroup,\arabic}
%\DoNotIndex{\begingroup,\closeout,\count,\csname,\def,\edef,\gdef,\else}
%\DoNotIndex{\endcsname,\endgroup,\expandafter,\fi,\ifnum,\ifthenelse,\ifx}
%\DoNotIndex{\immediate,\indexspace,\let,\newcommand,\newcounter,\newwrite}
%\DoNotIndex{\openout,\relax,\repeat,\RequirePackage,\setcounter,\string}
%\DoNotIndex{\stepcounter,\value,\WithSuffix,\(,\),\+,\/,\=,\@gobble}
%\DoNotIndex{\{}
%\DoNotIndex{\}}
%\DoNotIndex{\^}
%
%\cprotect\title{|{cprotect.sty}|\\
%  |\verb|atim in |\macro| arguments\thanks{This file
%    describes version \fileversion, last revised \filedate.}}
%\author{Bruno Le Floch\thanks{E-mail: bruno@le-floch.fr}}
%\date{Released \filedate}
%
%\maketitle
%
% \tableofcontents
% \changes{v1.0}{2010/12/30}{First version with documentation}
% \changes{v1.0b}{2011/01/01}{Filenames expanded much earlier: allows nesting.}
% \cprotect{\changes{v1.0b}{2011/01/01}}{Environments names were letter-only:
%   now only control sequences are forbidden. Fixed by switching from 
%   |\catcode=11| to |12| when processing.}
% \cprotect[mmm]\changes{v1.0d}{2011/01/12}{|\cprotect| \oarg{spec} to 
%   cprotect a control sequence with the argument specification \meta{spec}}
% 
% 
% \cprotect\section{Include \verb-\verb- anywhere!}
% \label{sec:intro}
% 
% The |cprotect| package attempts to do something that should be 
% impossible:\cprotect\footnote{The UK \TeX\ FAQ 
%   |http://www.tex.ac.uk/cgi-bin/texfaq2html| states:
%   \begin{quote}
%     So |\verb| and |\begin{verbatim}| have to assume that they are getting
%     the first look at the parameter text; if they aren't, \TeX\ has already 
%     assigned category codes so that the verbatim command doesn't have a
%     chance. 
%   \end{quote}
%   The argument is quite sound, but it can be circumvented if one can change
%   category codes once assigned, which we do.} it allows you to put verbatim
% in footnotes\cprotect\footnote{Like this one: \verb-!@#$%^&*()_+-.}, section
% titles, \ldots in a straightforward way. The section above was typeset using
% \begin{verbatim}
% \cprotect\section{Include\verb-\verb- anywhere!}\end{verbatim}
% and the footnote was
% \begin{verbatim}
% ...tes\cprotect\footnote{Like this one: \verb-!@#$%^&*()_+-.}\end{verbatim}
%
% More generally, let us assume that you want to use verbatim text in
% the argument of some macro |\cs| \marg{arg1}, and that this 
% macro is normally allergic to verbatim. It probably has a good reason
% to be allergic, but using an auxiliary file, we can often solve the 
% problem: if you want \marg{arg1} to contain verbatim, just write
% |\cprotect\cs| or |\cprotect{\cs}| instead of |\cs|.\cprotect\footnote{This 
% solves most problems, for instance, verbatim text in section titles
% written as |\cprotect\section|\marg{title} appears correctly in the table
% of contents. However, there are still bugs in capitalized headers.}
% All the examples I give use very standard macros, but it should work
% with any macro.\cprotect\footnote{If you have a macro that works when it is
% not preceeded by |\cprotect|, but breaks down if you put |\cprotect| in
% front of it, I will be interested to know why.}
%
% Nesting is supported: \cs{cprotect} cannot appear in a command argument
% unless this command is itself \cs{cprotect}ed:
% \begin{verbatim}
% \cprotect\section{Title \cprotect\emph{emphasized} word}
% \end{verbatim}
% 
% The first version of this package did not support macros with several
% arguments, nor macros with optional arguments. This new feature is 
% accessed by giving an optional argument to \cs{cprotect}:
% \begin{verbatim}
% \cprotect[om]\section[Short title \verb-&^-]{Long title \verb-&^%$-}
% \end{verbatim}
% Each |o| stands for an optional argument (within |[]|), and |m| stands for
% a mandatory argument (within |{}|). For example, one can write
% \begin{verbatim}
% \[
% \cprotect[om]\sqrt[\verb-%c-]{\cprotect[mm]\frac{\verb-%a-}{\verb-%b-}}
% \]
% \end{verbatim}
% to typeset
% \[
% \cprotect[om]\sqrt[\verb-%c-]{\cprotect[mm]\frac{\verb-%a-}{\verb-%b-}}
% \]
% In fact, the |[om]| argument specifier is optional.
%
% Some commands will not accept reading from a file as a valid argument. For
% instance, the first argument of \cs{hyperlink} cannot be \cs{cprotect}-ed.
% Workaround: write |\cprotect{\hyperlink|\marg{arg1}|}|\marg{arg2}, in
% other words, \cs{cprotect} the combination of \cs{hyperlink} and its first
% argument. This trick can be tried when all else fails.
%
% 
% \section{List of user commands}
% \label{sec:commandlist}
% 
% \DescribeMacro{\cpro^^@tect}
% Possibly the single most useful command is |\cprotect|, used as
% |\cprotect| |\foo| \marg{arg1} or |\cprotect| \marg{cslist} \marg{arg1}.
% As described in the previous section, the first form behaves as
% |\foo| \marg{arg1}, and the second as \meta{cslist} \marg{arg1}. 
% The difference is that the argument \marg{arg1} can now contain 
% |\catcode| changes (e.g., induced by the |\verb| command and the
% |verbatim| environment). In fact, \marg{arg1} is written to a file, and 
% then read again as the argument of |\foo|. So using the ideas behind
% |\cprotect|, one could in principle build weird macros that read their
% arguments several times, with different |\catcode|s in effect each time.
% The e-\TeX\ primitive \cs{scantokens} is most probably a better way to
% do these things, or you can try to use the experimental macro 
% |\ReadVerbatimUntil|.
% 
% \DescribeMacro{\cMakeRobust}
% If you find yourself using a |\cprotect\foo| combination frequently, and 
% you try to define \cs{bar} to mean |\cprotect\foo|, you will run into 
% trouble. The technical point is that I made \cs{cprotect} ``outer'',
% which prevents it from being nested in the argument of another command.
% 
% However, the package provides \cs{icprotect}, which is a non-outer version
% of \cs{cprotect}. You can write
% \begin{verbatim}
% \outer\def\bar{\icprotect\foo}
% \end{verbatim}
% (I like to make \cs{bar} outer, to make sure that it does not get called
% from inside a macro argument. It is not necessary.)
% 
% You can also use the typical 
% \begin{verbatim}
% \let\oldfoo\foo
% \outer\def\foo{\icprotect\oldfoo}\end{verbatim}
% to redefine |\foo| itself instead of a new command |\bar|. The package
% provides a wrapper for this construction: |\cMakeRobust\foo| replaces |\foo|
% by a version which accepts verbatim. As a stupid example,
% \begin{verbatim}
% \newcommand{\expon}[1]{\mathrm{#1}^{#1}}
% \cMakeRobust{\expon}
% \(\expon{Hel\verb+|+o}\)\end{verbatim}
% produces
% \newcommand{\expon}[1]{\mathrm{#1}^{#1}}
% \cMakeRobust{\expon}
% \(\expon{Hel\verb+|+o}\), and the verbatim is treated correctly.
%
% 
% \DescribeMacro{\cprotEnv}
% Some\cprotect\footnote{Todo: rethink \cs{cprotEnv}.}
% environments do not really behave as environment in that they 
% read their argument before acting on it. One such example is |amsmath|'s
% |align| environment. For these cases, use |\cprotEnv| as follows. Simply
% put |\cprotEnv| |\begin| \marg{name} instead of |\begin| \marg{name}. For
% example, 
% \begin{verbatim}
% \cprotEnv\begin{align}
%   x&=\begin{cases}
%     1 &\text{if }\verb"@#%^&*"\\
%     2 &\text{otherwise}
%   \end{cases}
% \end{align}\end{verbatim}
% gives
% \cprotEnv\begin{align}
%   x&=\begin{cases}
%     1 &\text{if }\verb"@#%^&*"\\
%     2 &\text{otherwise}
%   \end{cases}
% \end{align}
% Beware: the |align| environment does something weird at the measuring 
% step, and \cs{cprotect} will not work very easily (see Section~\ref{sec:bugs}
% on bugs below).
% 
% You can use |\CPTbegin| as a short-hand for |\cprotEnv\begin|, but this will 
% fail when nesting the same environment twice (admittedly, this is rare): the
% inner nesting is distinguished by \emph{precisely} the characters 
% \texttt{\string\begin\{\emph{name}\}}.
% 
%
% \DescribeMacro{\ReadVerbatimUntil}
% Finally, an odd half-deprecated macro. We use all of the auxiliary macros
% that are involved in its construction, but not \cs{ReadVerbatimUntil} 
% anymore (the code has to be rewritten to make things clearer.
% 
% The aim of this command is to read a
% piece of text verbatim, until it reaches an end-marker.
% It then writes all that it has read to an auxiliary file for
% future use. The most naive approach has a major flaw when nesting is 
% involved: when parsing |...{}}| for instance, with an end-marker of |}|, we
% often wish to stop at the \emph{second} closing bracket, not the first one.
% Thus, |\ReadVerbatimUntil| needs to be aware of a begin-marker. Also, for
% some applications we need to write things before and after the content 
% read by |\ReadVerbatimUntil|. Finally, we want to do something once the 
% file has been written, and possibly something before. 
%
% The syntax is thus |\ReadVerbatimUntil| \oarg{arg1} \marg{arg2}
% |^begin|\-|text^end|\-|text^begin|\-|tag^end|\-|tag^|, followed by the text
% in which we look for |endtag|. The caret (|^|) can be any character.
% It delimits the four verbatim-like arguments of 
% |\ReadVerbatimUntil|. The strings of letters |begintext| 
% and |endtext| are pre- and ap-pended to the file. As mentionned before, 
% |begintag| and |endtag| are used when reading the content, to determine
% how far |\ReadVerbatimUntil| should go. The mandatory argument 
% \marg{arg2} is executed once the whole text has been stored to a file.
% Typically, \marg{arg2} involves reading the file one or more times,
% and acting on it in any way we like. The optional argument can be used for 
% hacks such as changing where |cprotect| writes its files.
%
% 
% \section{Technical points}
%
% [...] Will break if |^| does not have its usual catcode at the beginning 
% and at the end of the \cs{cprotect}ed command.
% 
% Also, will break if |^^E| or |^^L| change catcodes. This choice of symbols
% can be changed by setting the options |gobbling-escape =| \meta{letter}, and 
% |gobbling-letter =| \meta{letter}. The defaults are |gobbling-escape = E| and 
% |gobbling-letter = L|. 
% 
% 
%
% \section{Known bugs/limitations}
% \label{sec:bugs}
%
% Incompatibility with |\pagestyle{headings}|: when a chapter title is put
% as a header, it gets upper-cased. If you did |\cprotect\chapter{...}| as
% usual, the title has been stored to a file, but now, the name of the file
% is capitalized, and \TeX\ cannot find it.
% 
% Issues with nesting of |\cprotect| in |align| environments: the |align|
% environment is being too clever with counting braces in its argument. 
% But we do nasty things to braces, such as |\let\foo{|\iffalse}\fi. This
% should in fact not be counted as a brace\cprotect\footnote{In some sense,
% it defines |\foo| to be an opening brace.}, but |align| has no way of knowing
% that. Thus, it expects a closing brace when there will ba none. A workaround
% is to add \iffalse{\fi|\iffalse}\fi| in the body of the align environment, 
% after any |\cprotect|. Also, the |align| environment itself should be 
% protected. Here is an example (three |\cprotect|, hence three closing braces):
% \begin{verbatim}
% \cprotEnv\begin{align*}
% \sum\cprotect_{\verb"\k" = 1}\cprotect^{\verb"\N"} \verb"\k" 
% = \cprotect\frac{\verb"\N"(\verb"\N"+1)}{2} \iffalse}}}\fi 
% \end{align*} \end{verbatim}
% \cprotEnv\begin{align*}
% \sum\cprotect_{\verb"\k" = 1}\cprotect^{\verb"\N"} \verb"\k" 
% = \cprotect\frac{\verb"\N"(\verb"\N"+1)}{2} \iffalse}}}\fi 
% \end{align*}
%
% For commands with two or more arguments, it is only possible to put verbatim
% in one of the arguments (and the syntax is not great).
%
% The argument of any command that is prefixed with |\cprotect| has to have 
% balanced braces, \emph{even when hidden inside verbatim environments, or 
% behind a comment character}. For instance, 
% \begin{verbatim}
% \cprotect\footnote{On the \verb:{: character} \end{verbatim}
% would fail: |\cprotect| would see the brace in |\verb:{:|, and count it 
% as an opening tag, which then has to be closed. This is most likely 
% to lead |\cprotect| to gobble the whole file before complaining. Similarly,
% \begin{verbatim}
% \cprotect\footnote{On the \verb:!: %should it be }?
% character}\end{verbatim}
% would only gobble until the closing brace in |%should it be }?|, and 
% I am not sure what error would be produced.
%
% But we can use one ailment to cure the other! A correct way to typeset 
% the first example is
% \begin{verbatim}
% \cprotect\footnote{On the \verb:{: character%}
% } \end{verbatim}
% if |%| is a comment character at the time it is read. A safer solution 
% would be to use |\iffalse}\fi| instead of |%}|. It still requires to
% be sure that |\| is an escape character when this piece of code is read,
% and can lead to problems if the previous token is |\let| for instance.
%
%
% 
% \section{The code}
% \label{sec:code}
% 
%\StopEventually{\PrintChanges\PrintIndex}
%
%    \begin{macrocode}
%<*package>
%    \end{macrocode}
%    
% \subsection{Setting up}
%
% We first load a few packages
%    \begin{macrocode}
\RequirePackage{ifthen}
\RequirePackage{suffix}
%    \end{macrocode}
% 
% We borrow the idea of quark from |expl3|: |\CPT@qend| expands to
% itself, useful for |\ifx| comparisons. 
%    \begin{macrocode}
\def\CPT@qend{\CPT@qend}
\def\CPT@option@head#1=#2\CPT@qend{#1}
\def\CPT@option@tail#1=#2\CPT@qend{#2}
\DeclareOption*{%
  \ifthenelse{%
    \equal{gobbling-escape}{%
      \expandafter\CPT@option@head\CurrentOption=\CPT@qend}%
  }{%
    \edef\CPT@gobbling@escape{%
      \expandafter\CPT@option@tail\CurrentOption\CPT@qend
    }%
  }{%
    \ifthenelse{%
      \equal{gobbling-letter}{%
        \expandafter\CPT@option@head\CurrentOption=\CPT@qend}%
    }{%
      \edef\CPT@gobbling@letter{%
        \expandafter\CPT@option@tail\CurrentOption\CPT@qend
      }%
    }{%
      \PackageError{cprotect}{Unknown option \CurrentOption}{}%
    }%
  }%
}
\def\CPT@gobbling@escape{E}
\def\CPT@gobbling@letter{L}
\ProcessOptions\relax
%    \end{macrocode}
%
% Then we introduce the commands pertaining to writing 
% files.\footnote{To be rewritten. For the moment, we use a new file
%   each time cprotect is used. Thus, many files. But this is needed if
%   people want to nest cprotect's.}
%
% We write files |\jobname-1.cpt|, |\jobname-2.cpt|, etc. in order.
%    \begin{macrocode}
\newwrite\CPT@WriteOut
\newcounter{CPT@WriteCount}
\edef\CPT@filename{\jobname.cpt}
\newcommand{\CPT@Write}[1]{%
  \immediate\openout\CPT@WriteOut=\CPT@filename%
  \newlinechar`\^^M%
  \immediate\write\CPT@WriteOut{#1}%
  \immediate\closeout\CPT@WriteOut%
  \expandafter\xdef\csname CPT@\CPT@filename\endcsname{%
    \noexpand\scantokens{#1}%
  }%
  %\expandafter\gdef\csname \string\CPT@\CPT@filename\expandafter\endcsname\expandafter{%
  %  \expandafter\protect\csname CPT@\CPT@filename\endcsname}%
  %\expandafter\show\csname \string\CPT@\CPT@filename\endcsname%
  %\expandafter\show\csname CPT@\CPT@filename\endcsname%
}
%    \end{macrocode}
% 
%
% The next command changes all catcodes to ``other''. It was adapted from
% |filecontents.sty|.
%    \begin{macrocode}
\newcommand{\makeallother}{%
  \count0=0\relax 
  \loop 
  \catcode\count0=12\relax 
  \advance\count0 by 1\relax 
  \ifnum\count0<256 
  \repeat 
}
%    \end{macrocode}
% 
%
% \begin{macro}{\CPT@gobbling@escape}
% \begin{macro}{\CPT@gobbling@letter}
% \changes{v1.0c}{Replaced \cs{relax} by |^^L|, with |L| customizable.}
% We make the active character |^^L| of charcode 11
% [letter...], and define it to expand
% to \cs{relax} (was hoping to make it
% invalid most of the time, but that fails) [...]. Also, failure if |^| is not
% of catcode ``superscript''.
% 
% \cs{CPT@escape@hat@hat@L} contains the string of characters |\^^L|, with
% |L| replaced by the value of \cs{CPT@gobbling@letter}.
%
% \cs{CPT@hat@hat@E@hat@hat@L} contains the string of characters
% |^^E^^L| where |^^E| is the escape character, and |^^L| is the active 
% charace.
%
% We define \cs{CPT@hat@hat@E@hat@hat@L} to be empty: it will simply
% be used to 
% gobble the initial space at the beginning of environments and hide the 
% end-of-line token  that e\TeX\ inserts for every \cs{scantokens}.
%
%    \begin{macrocode}
{
  \catcode`\/=0
  /catcode`/\=12
  /catcode`/^=12
  /xdef/CPT@escape@hat@hat@L{\^^/CPT@gobbling@letter/space}
  /xdef/CPT@escape@hat@hat@E{\^^/CPT@gobbling@escape/space}
  /xdef/CPT@hat@hat@E@hat@hat@L{%
    ^^/CPT@gobbling@escape^^/CPT@gobbling@letter/space}
}
\expandafter\scantokens\expandafter{%
  \expandafter\catcode\expandafter`\CPT@escape@hat@hat@E=0}
\expandafter\scantokens\expandafter{%
  \expandafter\catcode\expandafter`\CPT@hat@hat@E@hat@hat@L=11}
\expandafter\scantokens\expandafter{%
  \expandafter\def\CPT@hat@hat@E@hat@hat@L{}}
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
% \cprotect\subsection{|\ReadVerbatimUntil|}
% Both |\ReadVerbatimUntil| and its starred version (which we define using 
% the |suffix.sty| package) take one optional argument \oarg{first-cs} and
% a mandatory argument \marg{final-cs}. The \meta{final-cs} is saved as
% |\CPT@commandatend| to be executed when we close the file (and the 
% group).\cprotect\footnote{It is not a straightforward |\aftergroup|, 
% because I want this to be executed after another |\aftergroup| that 
% comes later.}
%    \begin{macrocode}
\newcommand\ReadVerbatimUntil[2][]{%
  \def\CPT@commandatend{#2}%
  \begingroup #1%
  \makeallother%
  \CPT@setup}
\WithSuffix\newcommand\ReadVerbatimUntil*[2][]{%
  \def\CPT@commandatend{#2}%
  \begingroup #1%
  \makeallother%
  \CPT@starsetup}
%    \end{macrocode}
% 
% |\CPT@setup| reads the four ``verbatim'' arguments following 
% \marg{final-cs}, and stores them in this order as macros |\CPT@preText|,
% |\CPT@postText|, |\CPT@begin|, and |\CPT@end|. The macros which read each 
% of these arguments need to be defined inside |\CPT@setup|, because
% I don't want any constraint on the delimiter. I could write a single
% macro that gobbles all four arguments at once, but this would require
% a crazy number of |\expandafter|s, so instead I do it one by one.
%
% If the delimiter was given, say |^|, then we would define |\CPT@readBegin|
% as |\def \CPT@readBegin#1^{\def \CPT@begin{#1}\CPT@readEnd}|.
% But since |^| is not given explicitly, we need |\expandafter|s to 
% expand it before the definition takes place. To avoid code repetition,
% I did it once and for all in the auxiliary macro |\CPT@def|. Note that
% a parameter of |##1| is somehow hidden inside |\CPT@def|, and that the
% |##1| inside the replacement text refer to the arguments of the 
% |\CPT@read...| macros.
%    \begin{macrocode}
\newcommand{\CPT@def}[2]{\expandafter\def\expandafter#1%
  \expandafter##\expandafter1#2}
\newcommand{\CPT@setup}[1]{%
  \def\CPT@delimiter{#1}%
  \CPT@def\CPT@readPreText\CPT@delimiter{%
       \def\CPT@preText{##1}\CPT@readPostText}%
  \CPT@def\CPT@readPostText\CPT@delimiter{%
       \def\CPT@postText{##1}\CPT@readBegin}%
  \CPT@def\CPT@readBegin\CPT@delimiter{%
       \def\CPT@begin{##1}\CPT@readEnd}%
  \CPT@def\CPT@readEnd\CPT@delimiter{%
       \def\CPT@end{##1}\CPT@readContent}%
  \CPT@readPreText%
}
\newcommand{\CPT@starsetup}[1]{\CPT@setup#1#1#1}
%    \end{macrocode}
% We also give the variant |\CPT@starsetup|, which has empty
% |\CPT@preText| and |\CPT@postText|.
% 
% When |\CPT@setup| is expanded, it will call |\CPT@|\-|readPreText|, 
% |\CPT@|\-|readPostText|, |\CPT@|\-|readBegin|, and |\CPT@|\-|readEnd|,
% and finish with |\CPT@|\-|readContent|, which we describe now.
% 
%
% The counter |CPT@numB| will count
% the surplus of |begin-tag|s compared to |end-tag|s when we parse the text 
% following |\CPT@readContent|. And |\CPT@store| is a macro that adds its
% argument to an other macro (I was too lazy to learn about token lists).
% The storage itself will be initialized later.
%    \begin{macrocode}
\newcounter{CPT@numB}
\newcommand{\CPT@store}[1]{\edef\CPT@storage{\CPT@storage#1}}
%    \end{macrocode}
% 
% The macro |\CPT@readContent| is quite tricky: if the |begin-tag| and 
% |end-tag| were one character, things would be easy: I would read one
% character at a time, and compare it to both |begin-tag| and |end-tag|,
% then either store it, and possibly increase or decrease |CPT@numB|, or
% decide that I am done if |CPT@numB| becomes negative.
%
% Unfortunately, I want to use |\ReadVerbatimUntil| for environments, in
% which case the |begin-tag| is |\begin{myenv}| and the |end-tag| is
% |\end{myenv}|. So two options: 
% \begin{itemize}
% \item code a standard string searching algorithm... I did not feel 
%   like it, but it might lead to a regexp package later on;
% \item use \TeX's delimited parameters.
% \end{itemize}
% I did the latter, using |\CPT@def| again (we want to expand the string
% which delimits the parameter before doing the definition).
%
% The details are ugly: 
% \begin{itemize}
% \item gobble until the first |end-tag|,\cprotect\footnote{This will fail for 
%     devious cases: if |begin-tag| is |abc| and |end-tag| is |bcd|, and 
%     |\CPT@readContent| is followed by |abcd...|: we will wrongly see
%     |bcd| as an |end-tag|.} and insert a fake |begin-tag|, as well as the
%   quark guard |\CPT@qend|,
% \item inside what we gobbled, gobble |begin-tag|s until reaching the fake
%   one (marked by the quark guard).
% \item continue until we have one more |end-tag| than |begin-tag|.
% \end{itemize}
%    \begin{macrocode}
\newcommand{\CPT@readContent}{%
  \CPT@def\CPT@gobbleOneB\CPT@begin##2{%
    \ifx\CPT@qend##2\CPT@store{##1}\addtocounter{CPT@numB}{-1}%
    \else\CPT@store{##1\CPT@begin}\stepcounter{CPT@numB}%
    \expandafter\CPT@gobbleOneB\expandafter##2\fi}%
  % 
  \CPT@def\CPT@gobbleUntilE\CPT@end{%
    \edef\CPT@tempi{##1\CPT@begin}%
    \expandafter\CPT@gobbleOneB\CPT@tempi\CPT@qend%
    \ifthenelse{\value{CPT@numB}<0}{%
      \CPT@store{\CPT@postText}%
      \CPT@Write{\CPT@storage}\endgroup%
      \CPT@commandatend%
    }{%
      \CPT@store{\CPT@end}\CPT@gobbleUntilE%
    }%
  }%
  \setcounter{CPT@numB}{0}%
  \def\CPT@storage{\CPT@preText}%
  \CPT@gobbleUntilE%
}
%    \end{macrocode}
%
% 
% \cprotect\subsection{For macros: |\cprotect| and friends}
%
% \begin{macro}{\cpro^^@tect}
% \changes{v1.0c}{2011/01/11}{Made \cs{cprotect} \cs{outer}, and introduced
%   \cs{icprotect}.}
% Equipped with |\ReadVerbatimUntil|, we are ready for the more practical 
% macros. |\cprotect| cheats: it uses |{| and |}| as a |begin-tag| and 
% |end-tag|. This works most of the time, but fails in cases such as those
% presented in Section~\ref{sec:bugs} (in usual cases there are 
% workarounds\cprotect\footnote{But I could definitely not have the contents of
% this |.dtx| file as a (huge) footnote in some document: since |{| and |}|
% change |\catcode|s, it is unlikely that the numbers balance correctly.}).
% 
% We define |\cprotect| as |\outer|, as a check that it is the first 
% to read its argument. A neat thing is that |\cprotect| will complain
% if it is nested inside anything, \cprotect\emph{except if the enclosing 
% macro is itself |\cprotect|ed}.\footnote{In particular, the author of this
% documentation had to use a devious trick (namely, have an ignored character
% in the midst of the name) to include even the name of the macro in the left
% margin.}
%
%    \begin{macrocode}
\outer\long\def\cprotect{\icprotect}
%    \end{macrocode}
% Normally, one should always use |\cprotect|. In some rare cases, it can be necessary
%  to overcome the |\outer|ness of |\cprotect|. For this we provide |\icprotect|,
% where |i| stands for |i|nternal. 
% 
% |\icprotect| \oarg{spec} \marg{\cs{cs}} takes as a mandatory argument the control sequence
% \cs{cs} that we are protecting, and as a first, optional, argument the argument specification
% of \cs{cs}, in the |xparse| style: |m| for mandatory arguments, |o| for optionals, 
% etc.\cprotect\footnote{Todo: list all the arguments that are supported: for the moment, 
% |o| and |m|.} \emph{\textbf{No spaces, i.e.,
% \texttt{[om]}, not \texttt{[o m]}!}}
%    \begin{macrocode}
\newtoks\CPT@commandatend@toks
\newcommand{\icprotect}[2][om]{%
  \def\CPT@argsig{#1}%
  \def\CPT@cs{#2}%
  \CPT@commandatend@toks{#2}%
  \def\CPT@commandatend{\CPT@read@args}% used by RVU.
  \CPT@commandatend%
}
\def\CPT@argsig@pop{%
  \edef\CPT@argsig{\expandafter\@gobble\CPT@argsig}%
}
%    \end{macrocode}
% \end{macro}
%
% Currently, \cs{CPT@read@args} is simply a synonym.
% 
%    \begin{macrocode}
 %\newcommand\CPT@read@args{\CPT@read@m}
\newcommand\CPT@read@args{%
  \ifx\CPT@argsig\empty
  \expandafter\the\expandafter\CPT@commandatend@toks
  \else
  \expandafter\expandafter\expandafter\CPT@read@one 
  \expandafter\CPT@argsig\expandafter\CPT@qend%
  \fi
}
\def\CPT@read@one#1#2\CPT@qend{%
  \def\CPT@argsig{#2}%
  \def\CPT@tempii{\csname CPT@read@#1\endcsname}% To make the \afterassignment simpler.
  \afterassignment\CPT@tempii\let\CPT@next=%
}
%    \end{macrocode}
% 
%
% \subsubsection{Mandatory arguments}
%
%
% First, we learn how to parse mandatory arguments. We define \cs{CPT@read@m} to read a
% mandatory (braced) argument. Note the use of |\bgroup| in |\CPT@read@m|: if the argument
% of |\cs| starts with an opening brace, it has been read early, and its |\catcode| will 
% still be |1|.\cprotect\footnote{I am not sure whether catcodes really matter
% in such an |\ifx|.}
%
% We check whether the next token is a brace or not: 
% \begin{itemize}
% \item If it is, we discard the |{|, and the argument of \cs{cs} stops
%     at the matching explicit closing brace |}|. (See \cs{CPT@read@mbeg} below,
%     where |beg| stands for an opening brace.)
% \item If it is not, the argument of \cs{cs} is this token only, and there is
%   no need for \cs{cprotect}ion (see \cs{CPT@read@mone} below).
% \end{itemize}
%
%    \begin{macrocode}
\newcommand\CPT@read@m{%
  \ifx\CPT@next\bgroup%
  \expandafter\CPT@read@mbeg%
  \else%
  \expandafter\CPT@read@mone%
  \fi%
}
\def\CPT@read@mone{\CPT@cs\CPT@next}
%    \end{macrocode}
% 
% Since |\ReadVerbatimUntil| makes everything into others, we need braces
% to be others when we define most macros in this Section. We thus need
% a few |\catcode| changes. Think of \(|{|\to|(|\) and \(|}|\to|)|\).
%    \begin{macrocode}
\begingroup
  \catcode`\{=12 \catcode`\}=12 
  \catcode`\(=1 \catcode`\)=2
  \gdef\CPT@other@bgroup({)
  \gdef\CPT@other@egroup(})
\endgroup
%    \end{macrocode}
%
% \cs{CPT@read@mbeg} to read a braced mandatory argument once the begin-group symbol
% has been read. 
%    \begin{macrocode}
\def\CPT@read@mbeg{%
  \stepcounter{CPT@WriteCount}%
  \edef\CPT@filename{\jobname-\arabic{CPT@WriteCount}.cpt}%
  \expandafter\expandafter\expandafter\CPT@commandatend@toks
  \expandafter\expandafter\expandafter{%
    \expandafter\the
    \expandafter\CPT@commandatend@toks
    % Input a file:
    \expandafter{%
      \expandafter\protect 
      \expandafter\input 
      \CPT@filename 
      \relax
    }%
    % % Using \scantokens: requires '%' active.
    % \expandafter{%
    %   \csname \string\CPT@\CPT@filename\endcsname
    %   \expandafter\protect
    %   \expandafter\csname  CPT@\CPT@filename\endcsname
    % }%
  }%
  %\showthe\CPT@commandatend@toks%
%    \end{macrocode}
% We append |{\protect \input| \meta{file name}|relax}| at the end of the 
% token list \cs{CPT@commandatend@toks}. Then we set \cs{CPT@commandatend}
% to be this token list. The role of \cs{CPT@commandatend} is to be executed
% once the matching |}| is found. Note the \cs{protect}, necessary for
% things to work well inside \cs{section}.
%
% Since we |\edef|ed, |\CPT@filename| contains the expanded version of the
% filename. We then use many |\expandafter|s in order to expand the filename
% now: we are then sure that the right file will be input as an argument of
% |\CPT@cs| (this is the |\cprotect|ed command).
% 
%    \begin{macrocode}
  \begingroup%
  \makeallother%
  \def\CPT@preText{}%
  \let\CPT@postText\CPT@hat@hat@E@hat@hat@L%
  \let\CPT@begin\CPT@other@bgroup%
  \let\CPT@end\CPT@other@egroup%
  \CPT@readContent%
}%
%    \end{macrocode}
%
%
% \cprotect\subsubsection{Optional (|o|) and delimited (|d**|) arguments}
% 
% \cs{CPT@read@o} (for scanning standard optional arguments) is defined to be 
% \cs{CPT@read@d[]}.
%    \begin{macrocode}
\def\CPT@read@o{\CPT@read@d[]}
%    \end{macrocode}
% 
% Now for delimited arguments, \cs{CPT@read@d} takes two arguments (the two 
% delimiters). If the next token, \cs{CPT@next} is the same \emph{character} 
% as the opening delimiter |#1|, then we read the argument with 
% \cs{CPT@read@d@beg}. Otherwise, we use \cs{CPT@read@d@none}.
%    \begin{macrocode}
\def\CPT@read@d#1#2{%
  \if\noexpand\CPT@next#1%
  \expandafter\CPT@read@d@beg%
  \else%
  \expandafter\CPT@read@d@none%
  \fi%
  {#1}{#2}%
}
\def\CPT@read@d@none#1#2{%
  \CPT@read@args\CPT@next%
}
%    \end{macrocode}
% 
% \cs{CPT@read@d@beg} to read a delimited argument once (if) the beginning
% symbol \cs{CPT@d@begin} has been found. The begin-tag and end-tag used by 
% \cs{ReadVerbatimUntil} and its friends are here \cs{CPT@d@begin} and
% \cs{CPT@d@end}. Errata: replaced by |#1| and |#2|.
%    \begin{macrocode}
\def\CPT@read@d@beg#1#2{%
  \stepcounter{CPT@WriteCount}%
  \edef\CPT@filename{\jobname-\arabic{CPT@WriteCount}.cpt}%
  \expandafter\expandafter\expandafter\CPT@commandatend@toks%
  \expandafter\expandafter\expandafter{%
    \expandafter\the%
    \expandafter\CPT@commandatend@toks%
    \expandafter #1%
      \expandafter\protect% 
      \expandafter\input% 
      \CPT@filename% 
      \relax%
    #2%
  }%
%    \end{macrocode}
% 
% Since we |\edef|ed, |\CPT@filename| contains the expanded version of the
% filename. We then use many |\expandafter|s in order to expand
% \cs{CPT@d@begin}, \cs{CPT@d@end}, and \cs{CPT@filename} 
% the filename now: we are then sure that the right file will be input as
% an argument of |\CPT@cs| (this is the |\cprotect|ed command).
% 
%    \begin{macrocode}
  \begingroup%
  \makeallother%
  \def\CPT@preText{}%
  \let\CPT@postText\CPT@hat@hat@E@hat@hat@L%
  \def\CPT@begin{#1}%
  \def\CPT@end{#2}%
  \CPT@readContent%
}%
%    \end{macrocode}
%
%
%
% Finally, the |\cMakeRobust| command is a mess, and could probably be improved,
% although... it works |:)|. We make the new command \cs{outer}, and use 
% the inner version \cs{icprotect} of \cs{cprotect}.
%    \begin{macrocode}
\newcommand{\cMakeRobust}[1]{%
  \def\CPT@cs@name{\expandafter\@gobble\string#1}%
  \expandafter\let\csname CPT@old@\CPT@cs@name\endcsname #1%
  \expandafter\outer\expandafter\def\csname\CPT@cs@name\endcsname{%
    \expandafter\icprotect\csname CPT@old@\CPT@cs@name\endcsname}%
}
%    \end{macrocode}
%
%
% \cprotect\subsection{For Environments: |\cprotEnv\begin| and |\CPTbegin|}
%   
%   \DescribeMacro{\CPTbegin}
%   We introduce the command |\CPTbegin|, which has a behaviour close to
%   the behaviour of |\begin|. Namely, |\CPTbegin{env}| gobbles its argument
%     until it sees the matching |\end|, and it writes what it gobbled to
%   a file. It then inputs the file between |\begin{...}| and |\end{...}|,
%   as we can see from the definition of |\CPT@commandatend|.
%   
%   As for the case of |\cprotect|, we need to setup the values of the four
%   arguments of |\ReadVerbatimUntil| before reading the content. Since 
%   the |begin-tag| and |end-tag| depend on a parameter, it would be 
%   incredibly messy to try to expandafter the right things, so we 
%   define |\CPT@env@setup| to, well, setup the values of the four 
%   arguments of |\ReadVerbatimUntil|, and then skip directly to 
%   |\CPT@readContent|.
%
%    \begin{macrocode}
\newcommand{\CPTbegin}[1]{%
  \stepcounter{CPT@WriteCount}%
  \edef\CPT@filename{\jobname-\arabic{CPT@WriteCount}.cpt}%
  \edef\CPT@commandatend{%
    \noexpand\begin\noexpand{\noexpand#1\noexpand}%
      \noexpand\expandafter\noexpand\protect%
      \noexpand\expandafter\noexpand\input \CPT@filename\relax%
    \noexpand\end\noexpand{\noexpand#1\noexpand}%
  }%
%    \end{macrocode}
% Here, we are defining |\CPT@commandatend| to be |\begin{#1}| 
% |\expandafter| |\protect| |\expandafter| |\input| \meta{filename}
% |\end{#1}|, where \meta{filename} is |\CPT@filename|, fully expanded.
% Is there a cleaner way of doing that, given how far in the definition
% |\CPT@filename| is? 
%    \begin{macrocode}
  \begingroup%
  \CPT@env@setup{#1}%
  \makeallother%
  \CPT@readContent%
}
%    \end{macrocode}
%
% As announced, |\CPT@env@setup|, defined with lots of catcode changes 
% [\emph{this paragraph is not up to date}]. 
% Since the catcode of |\| changes, I need an extra escape character,
% which I take to be |/|. I use two groups so each group is opened and
% closed using the same escape character (this is technically irrelevant,
% but seems less messy).
%    \begin{macrocode}
\newcommand{\CPT@otherify}[1]{%
  \expandafter\expandafter\expandafter\@gobble
  \expandafter\string\csname #1\endcsname
}
\newcommand{\CPT@env@setup}[1]{%
  \def\CPT@temp{#1}%
  \edef\CPT@temp{\CPT@otherify{#1}}%
  \edef\CPT@temp{\expandafter\strip@prefix\meaning\CPT@temp}%
  \expandafter\CPT@env@setup@\expandafter{\CPT@temp}%
}
\def\CPT@env@setup@#1{%
  \let\CPT@preText\CPT@hat@hat@E@hat@hat@L%
  \let\CPT@postText\CPT@hat@hat@E@hat@hat@L%
  \edef\CPT@begin{\string\begin\string{#1\string}}%
  \edef\CPT@end{\string\end\string{#1\string}}%
}
%    \end{macrocode}
%
% A final piece of code is needed so that |\CPT|-environments can be
% nested: in order to be able to nest, we need |\ReadVerbatimUntil| 
% to be aware that our environment has been opened when |\CPTbegin{foo}|
% or |\begin{foo}| appear in the text. Given the rules for delimited
% parameters in TeX, this is quite difficult. A workaround is to replace
% |\CPTbegin| by something that ends in |\begin| shuch as |\cprotEnv\begin|
% as defined below. Thus, for nesting to work, you need to prepend every
% one of your |env| environments with |\cprotEnv|.
%    \begin{macrocode}
\def\cprotEnv\begin{\CPTbegin}
%    \end{macrocode}
%
%    \begin{macrocode}
%</package>
%    \end{macrocode}
%\Finale
\endinput