summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/cprotect
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
committerNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
commite0c6872cf40896c7be36b11dcc744620f10adf1d (patch)
tree60335e10d2f4354b0674ec22d7b53f0f8abee672 /macros/latex/contrib/cprotect
Initial commit
Diffstat (limited to 'macros/latex/contrib/cprotect')
-rw-r--r--macros/latex/contrib/cprotect/README31
-rw-r--r--macros/latex/contrib/cprotect/cprotect.dtx983
-rw-r--r--macros/latex/contrib/cprotect/cprotect.pdfbin0 -> 623268 bytes
3 files changed, 1014 insertions, 0 deletions
diff --git a/macros/latex/contrib/cprotect/README b/macros/latex/contrib/cprotect/README
new file mode 100644
index 0000000000..60114b711b
--- /dev/null
+++ b/macros/latex/contrib/cprotect/README
@@ -0,0 +1,31 @@
+----------------------------------------------------------------
+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
+`\cprotect\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.
+
diff --git a/macros/latex/contrib/cprotect/cprotect.dtx b/macros/latex/contrib/cprotect/cprotect.dtx
new file mode 100644
index 0000000000..eafe0d6d20
--- /dev/null
+++ b/macros/latex/contrib/cprotect/cprotect.dtx
@@ -0,0 +1,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 \ No newline at end of file
diff --git a/macros/latex/contrib/cprotect/cprotect.pdf b/macros/latex/contrib/cprotect/cprotect.pdf
new file mode 100644
index 0000000000..4c96f72d55
--- /dev/null
+++ b/macros/latex/contrib/cprotect/cprotect.pdf
Binary files differ