summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/cprotect
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2011-01-28 23:13:37 +0000
committerKarl Berry <karl@freefriends.org>2011-01-28 23:13:37 +0000
commitd708bf6768840e9e6d64ebdee9e6352df197816a (patch)
tree86f9f2e97e982d2334df8117ba7c0fce253c3dcb /Master/texmf-dist/source/latex/cprotect
parentc7356318aaf68da51bfe55c0f408b0d83cfd4416 (diff)
cprotect (28jan11)
git-svn-id: svn://tug.org/texlive/trunk@21209 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source/latex/cprotect')
-rw-r--r--Master/texmf-dist/source/latex/cprotect/cprotect.dtx633
-rw-r--r--Master/texmf-dist/source/latex/cprotect/cprotect.ins8
2 files changed, 495 insertions, 146 deletions
diff --git a/Master/texmf-dist/source/latex/cprotect/cprotect.dtx b/Master/texmf-dist/source/latex/cprotect/cprotect.dtx
index d8bc5495d28..eafe0d6d20d 100644
--- a/Master/texmf-dist/source/latex/cprotect/cprotect.dtx
+++ b/Master/texmf-dist/source/latex/cprotect/cprotect.dtx
@@ -3,9 +3,10 @@
\iffalse
%</internal>
%<*readme>
+%^^A To generate the readme, we make + into an ignored character!!
----------------------------------------------------------------
cprotect --- verbatim in macro arguments
-E-mail: bruno@le-floch.fr
+E-mail: blflatex@gmail.com
Released under the LaTeX Project Public License v1.3c or later
See http://www.latex-project.org/lppl.txt
----------------------------------------------------------------
@@ -14,7 +15,7 @@ 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.
+`\cpro+tect\footnote` instead of `\footnote`, etc.
A similar approach is taken for environments. Nesting of the
various environments is taken into account.
@@ -51,7 +52,7 @@ the pdf to contain its index and glossary.
\preamble
----------------------------------------------------------------
cprotect --- verbatim in macro arguments
-E-mail: bruno@le-floch.fr
+E-mail: blflatex@gmail.com
Released under the LaTeX Project Public License v1.3c or later
See http://www.latex-project.org/lppl.txt
----------------------------------------------------------------
@@ -59,7 +60,7 @@ See http://www.latex-project.org/lppl.txt
\endpreamble
\postamble
-Copyright (C) 2010 by Bruno Le Floch <bruno@le-floch.fr>
+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
@@ -90,9 +91,14 @@ and the derived files cprotect.ins,
}
\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
@@ -101,7 +107,7 @@ and the derived files cprotect.ins,
%</internal>
%<*package>
\NeedsTeXFormat{LaTeX2e}
-\ProvidesPackage{cprotect}[2010/12/30 v1.0 (Bruno Le Floch)]
+\ProvidesPackage{cprotect}[2011/01/27 v1.0e (Bruno Le Floch)]
%</package>
%<*driver>
\documentclass[12pt]{ltxdoc}
@@ -114,12 +120,13 @@ and the derived files cprotect.ins,
\CodelineIndex
\RecordChanges
\begin{document}
+ \catcode`\^^@=9\relax %^^A We need an ignored character for later.
\DocInput{cprotect.dtx}
\end{document}
%</driver>
% \fi
%
-% \CheckSum{244}
+% \CheckSum{0}
%
%
%\GetFileInfo{cprotect.sty}
@@ -144,47 +151,86 @@ and the derived files cprotect.ins,
%
% \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 will allow you to put verbatim in
-% footnotes\cprotect\footnote{Like this: \verb-!@#$%^&*()_+-.}
-% in a straightforward way. The section above was typeset using
+% 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: \verb-!@#$%^&*()_+-.}\end{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 solve the problem
-% entirely: if you want \marg{arg1} to contain verbatim, just write
+% 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.}
+% 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.}
%
-% Braces are useful if a macro has \emph{several} arguments, and you want
-% to put verbatim in the second one: then type
-% |\cprotect{\cs|\marg{arg1}|}|\marg{arg2}. If you want to put verbatim in
-% both arguments, well \ldots\ it is not implemented yet, but if you send
-% me an email saying why you need it, I will look into it (suggestions
-% are, as always, welcome).
+% 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{\cprotect}
+% \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
@@ -192,18 +238,31 @@ and the derived files cprotect.ins,
% 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 |\cprotect|, one could
-% in principle build weird macros that read their arguments several times,
-% with different |\catcodes| in effect each time. The macro
-% |\ReadVerbatimUntil| below gives a better way of doing that.
-%
+% 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, you
-% can simply define |\bar| to mean |\cprotect\foo|. It should work at least
-% most of the time. You can also use the typical
+% 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
-% \def\foo{\cprotect\oldfoo}\end{verbatim}
+% \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,
@@ -216,40 +275,48 @@ and the derived files cprotect.ins,
% \cMakeRobust{\expon}
% \(\expon{Hel\verb+|+o}\), and the verbatim is treated correctly.
%
+%
% \DescribeMacro{\cprotEnv}
-% Something similar to |\cprotect| exists for environments: |\cprotEnv|. Simply
-% put |\cprotEnv| |\body| \marg{name} instead of |\body| \marg{name}. For
+% 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}
+% 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}
+% x&=\begin{cases}
+% 1 &\text{if }\verb"@#%^&*"\\
+% 2 &\text{otherwise}
+% \end{cases}
% \end{align}
-% Note that unfortunately we need to put the |\verb| outside |\text|.
-% This is because currently, nesting of |\cprotect| and friends is not supported.
-%
+% 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: the inner nesting is
-% distinguished by \emph{precisely} the characters
-% \texttt{\textbackslash\ b e g i n \{ \emph{n a m e} \}}.
+% 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, the most powerful and the root of all these macros, from which
-% the package currently derives its name, is |\ReadVerbatimUntil|. 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
+% 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
@@ -266,11 +333,22 @@ and the derived files cprotect.ins,
% 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 is used for
-% hacks such as changing where |cprotect| writes his files.
+% 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}
%
@@ -279,16 +357,31 @@ and the derived files cprotect.ins,
% 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 issue seems
-% to arise because the |align| environment wants to fully expand it argument
-% once before typesetting 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 even comments}. For
-% instance,
+% 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
@@ -315,7 +408,7 @@ and the derived files cprotect.ins,
% \section{The code}
% \label{sec:code}
%
-%\StopEventually{\clearpage\PrintChanges\PrintIndex}
+%\StopEventually{\PrintChanges\PrintIndex}
%
% \begin{macrocode}
%<*package>
@@ -328,6 +421,38 @@ and the derived files cprotect.ins,
\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
@@ -338,37 +463,78 @@ and the derived files cprotect.ins,
% \begin{macrocode}
\newwrite\CPT@WriteOut
\newcounter{CPT@WriteCount}
+\edef\CPT@filename{\jobname.cpt}
\newcommand{\CPT@Write}[1]{%
- \stepcounter{CPT@WriteCount}%
- \immediate\openout\CPT@WriteOut=\jobname-%
- \arabic{CPT@WriteCount}.cpt%
+ \immediate\openout\CPT@WriteOut=\CPT@filename%
\newlinechar`\^^M%
\immediate\write\CPT@WriteOut{#1}%
\immediate\closeout\CPT@WriteOut%
- \aftergroup\CPT@setLastFileName%
+ \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%
}
-\newcommand{\CPT@setLastFileName}{%
- \def\CPT@lastFileName{\jobname-\arabic{CPT@WriteCount}.cpt}}
-\newcommand{\CPT@input@last}{%
- \expandafter\protect\expandafter\input
- \expandafter{\CPT@lastFileName}}
% \end{macrocode}
%
%
-% The next command changes all catcodes to letters. It was adapted from
+% The next command changes all catcodes to ``other''. It was adapted from
% |filecontents.sty|.
% \begin{macrocode}
-\newcommand{\makeallletters}{%
- \count0=0\relax %
- \loop %
- \catcode\count0=11\relax %
- \advance\count0 by 1\relax %
- \ifnum\count0<256 %
- \repeat %
+\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
@@ -381,12 +547,12 @@ and the derived files cprotect.ins,
\newcommand\ReadVerbatimUntil[2][]{%
\def\CPT@commandatend{#2}%
\begingroup #1%
- \makeallletters%
+ \makeallother%
\CPT@setup}
\WithSuffix\newcommand\ReadVerbatimUntil*[2][]{%
\def\CPT@commandatend{#2}%
\begingroup #1%
- \makeallletters%
+ \makeallother%
\CPT@starsetup}
% \end{macrocode}
%
@@ -431,14 +597,12 @@ and the derived files cprotect.ins,
% and finish with |\CPT@|\-|readContent|, which we describe now.
%
%
-% We borrow the idea of quark from |expl3|: |\CPT@qend| expands to
-% itself, useful for |\ifx| comparisons. The counter |CPT@numB| will count
+% 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}
-\def\CPT@qend{\CPT@qend}
\newcounter{CPT@numB}
\newcommand{\CPT@store}[1]{\edef\CPT@storage{\CPT@storage#1}}
% \end{macrocode}
@@ -498,72 +662,238 @@ and the derived files cprotect.ins,
%
% \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
+% 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.}).
%
-% The first argument of |\cprotect| is the control sequence |\cs| that we are
-% patching.
+% 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}
-\newcommand{\cprotect}[1]{\def\CPT@cs{#1}%
- \afterassignment\CPT@A\let\CPT@next}
+\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}
-% Then, we check whether the next token is a brace or not:
+% \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| stops
-% at the matching explicit closing brace |}|. (See |\CPT@n{| below...
-% yes, the name of the control sequence does contain the brace,
-% which is simply a letter, after all.)
-% \item If it is not, the argument of |\cs| is this token only: we insert
-% a brace after the token, and launch |\ReadVerbatimUntil|. Think of this
-% as inserting braces around the argument, and doing what we did in the
-% former case: discarding the opening brace. (See |\CPT@N| below.)
+% \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}
%
-% Since |\ReadVerbatimUntil| makes everything into letters, we need braces
-% to be letters when we define most macros in this Section. We thus need
+% \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`\{=11 \catcode`\}=11 \catcode`\+=11
+ \catcode`\{=12 \catcode`\}=12
\catcode`\(=1 \catcode`\)=2
- \gdef\CPT@A(%
- \ifx\CPT@next\bgroup%
- \expandafter\CPT@n{%
- \else%
- \expandafter\CPT@N%
- \fi)
- \gdef\CPT@n{(\ReadVerbatimUntil*(%
- \CPT@cs(\CPT@input@last))+{+}+)%
- \gdef\CPT@N(\expandafter\CPT@n{\CPT@next })%
+ \gdef\CPT@other@bgroup({)
+ \gdef\CPT@other@egroup(})
\endgroup
% \end{macrocode}
-% Note the use of |\bgroup| in |\CPT@A|: 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 use |+| as a delimiter for |\ReadVerbatimUntil|. No |begin-text|
-% nor |end-text|. |begin-tag| and |end-tag| are |{| and |}| as mentionned
-% before.
+% \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).
%
-% Once the matching |}| is found, we apply |\CPT@cs| (|\cs| stored) to
-% |\CPT@input@last|, aka the file where we saved the argument
-% (we add some protection so that things work well in |\section| and
-% similar situations).
+% \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 |:)|.
+% 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\def\csname\CPT@cs@name\endcsname{%
- \expandafter\cprotect\csname CPT@old@\CPT@cs@name\endcsname}%
+ \expandafter\outer\expandafter\def\csname\CPT@cs@name\endcsname{%
+ \expandafter\icprotect\csname CPT@old@\CPT@cs@name\endcsname}%
}
% \end{macrocode}
%
@@ -587,32 +917,51 @@ and the derived files cprotect.ins,
%
% \begin{macrocode}
\newcommand{\CPTbegin}[1]{%
- \def\CPT@commandatend{\begin{#1}\CPT@input@last\end{#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}%
- \makeallletters%
+ \makeallother%
\CPT@readContent%
}
% \end{macrocode}
%
-% As announced, |\CPT@env@setup|, defined with lots of catcode changes.
+% 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}
-\begingroup\catcode`\/=0
-/begingroup/catcode`/\=11
- /catcode`/{=11 /catcode`/}=11 /catcode`/-=11
- /catcode`/(=1 /catcode`/)=2
- /gdef/CPT@env@setup#1(%
- /def/CPT@preText(\relax )%
- /def/CPT@postText(\relax )%
- /def/CPT@begin(\begin{#1})%
- /def/CPT@end(\end{#1})%
- )
-/endgroup
-\endgroup
+\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
diff --git a/Master/texmf-dist/source/latex/cprotect/cprotect.ins b/Master/texmf-dist/source/latex/cprotect/cprotect.ins
index faa18f23a25..551c5a057d1 100644
--- a/Master/texmf-dist/source/latex/cprotect/cprotect.ins
+++ b/Master/texmf-dist/source/latex/cprotect/cprotect.ins
@@ -7,7 +7,7 @@
%% cprotect.dtx (with options: `install')
%% ----------------------------------------------------------------
%% cprotect --- verbatim in macro arguments
-%% E-mail: bruno@le-floch.fr
+%% E-mail: blflatex@gmail.com
%% Released under the LaTeX Project Public License v1.3c or later
%% See http://www.latex-project.org/lppl.txt
%% ----------------------------------------------------------------
@@ -18,7 +18,7 @@
\preamble
----------------------------------------------------------------
cprotect --- verbatim in macro arguments
-E-mail: bruno@le-floch.fr
+E-mail: blflatex@gmail.com
Released under the LaTeX Project Public License v1.3c or later
See http://www.latex-project.org/lppl.txt
----------------------------------------------------------------
@@ -26,7 +26,7 @@ See http://www.latex-project.org/lppl.txt
\endpreamble
\postamble
-Copyright (C) 2010 by Bruno Le Floch <bruno@le-floch.fr>
+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
@@ -50,7 +50,7 @@ and the derived files cprotect.ins,
}
\endbatchfile
%%
-%% Copyright (C) 2010 by Bruno Le Floch <bruno@le-floch.fr>
+%% 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