| 1 |
% \iffalse |
| 2 |
%% |
| 3 |
%% suffix is part of the bigfoot bundle for critical typesetting |
| 4 |
%% Copyright 2002--2006 David Kastrup <[email protected]> |
| 5 |
%% |
| 6 |
%% The license notice and corresponding source code for this file are |
| 7 |
%% contained in suffix.dtx. |
| 8 |
%% |
| 9 |
% This program is free software; you can redistribute it and/or modify |
| 10 |
% it under the terms of the GNU General Public License as published by |
| 11 |
% the Free Software Foundation; either version 2 of the License, or |
| 12 |
% (at your option) any later version. |
| 13 |
% |
| 14 |
% This program is distributed in the hope that it will be useful, |
| 15 |
% but WITHOUT ANY WARRANTY; without even the implied warranty of |
| 16 |
% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
| 17 |
% GNU General Public License for more details. |
| 18 |
% |
| 19 |
% You should have received a copy of the GNU General Public License |
| 20 |
% along with this program; if not, write to the Free Software |
| 21 |
% Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA |
| 22 |
% \fi |
| 23 |
% \CheckSum{198} |
| 24 |
% \GetFileInfo{suffix.sty} |
| 25 |
% \author{David Kastrup\thanks{\href{mailto:[email protected]} |
| 26 |
% {Email: \texttt{[email protected]}}}} |
| 27 |
% \title{The \texttt{suffix} Package\\Version \fileversion} |
| 28 |
% \date{\filedate} |
| 29 |
% \maketitle |
| 30 |
% \section{Basics} |
| 31 |
% The \texttt{suffix} package has the purpose of making it easy to |
| 32 |
% define and maintain command variants like |\macro*| and even |
| 33 |
% |\macro\/| or similar. It requires e\TeX\ version~2 for its work. |
| 34 |
% The suffixes are fetched with |\futurelet|, so things like |\bgroup| |
| 35 |
% and |{| ^^A} |
| 36 |
% can't be distinguished. In addition, the efficiency depends on the |
| 37 |
% complexity of the suffix' definition, so you should preferably use |
| 38 |
% characters or short commands as a suffix. A suffixed command itself |
| 39 |
% counts as short for this purpose. How does a suffix definition look |
| 40 |
% like? |
| 41 |
% |
| 42 |
% \DescribeMacro{\WithSuffix} The general form is |
| 43 |
% \begin{quote} |
| 44 |
% |\WithSuffix|\meta{prefixed definition}\meta{macro}\meta{suffix}\dots |
| 45 |
% \end{quote} |
| 46 |
% where \meta{prefixed definition} is something like |\xdef|, |
| 47 |
% |\global\let| or similar. Recognised prefixes are |\global|, |
| 48 |
% |\long|, |\protected| (the latter is rarely useful, as the original |
| 49 |
% definition already is robust), and |\expandafter| (with its |
| 50 |
% `natural' meaning), specially recognized commands are |\gdef| and |
| 51 |
% |\xdef|. Other commands can be used as long as they are suitable as |
| 52 |
% an undelimited macro argument. This means they must either be a |
| 53 |
% single token like |\newcommand| or brace-enclosed like |
| 54 |
% |{\newcommand*}|. \meta{macro} can be a macro or an active |
| 55 |
% character. It should be a single token suitable for assignment with |
| 56 |
% |\let|. \meta{suffix} can be something like a single letter such as |
| 57 |
% |*| or |[|. |
| 58 |
% |
| 59 |
% For example, assume that a command |\snarf| already exists and we |
| 60 |
% want to define a variant |\snarf|\oarg{optarg}. Then we can do this |
| 61 |
% with |
| 62 |
% \begin{quote} |
| 63 |
% \cmd\WithSuffix|\long\def\snarf[#1]{|\meta{Definition using |
| 64 |
% \texttt{\#1}}|}| |
| 65 |
% \end{quote} |
| 66 |
% That's pretty much it. Oh, only when a command is recognised as |
| 67 |
% having a prefix |\global| or being |\xdef| or |gdef| will the |
| 68 |
% corresponding redefinitions be done globally. This is rarely a |
| 69 |
% concern. |
| 70 |
% |
| 71 |
% \DescribeMacro{\SuffixName} In case you need to refer to the control |
| 72 |
% sequence name used to refer to the suffixed macro, you can access it |
| 73 |
% as |
| 74 |
% \begin{quote} |
| 75 |
% |\csname|\cmd{\SuffixName}\meta{macro}\meta{suffix}|\endcsname| |
| 76 |
% \end{quote} |
| 77 |
% \DescribeMacro{\NoSuffixName} and if you need to refer to the |
| 78 |
% original unsuffixed macro, you can access it as |
| 79 |
% \begin{quote} |
| 80 |
% |\csname|\cmd{\NoSuffixName}\meta{macro}|\endcsname| |
| 81 |
% \end{quote} |
| 82 |
% \StopEventually{} |
| 83 |
% \section{The driver file for the documentation} |
| 84 |
% Installation is done by |bigfoot.ins|, so look there for more |
| 85 |
% information for that. Here comes the documentation driver. |
| 86 |
% \begin{macrocode} |
| 87 |
%<*driver> |
| 88 |
\documentclass{ltxdoc} |
| 89 |
\usepackage{hyperref} |
| 90 |
\usepackage{suffix} |
| 91 |
\begin{document} |
| 92 |
\OnlyDescription |
| 93 |
%<driver> \AlsoImplementation |
| 94 |
\DocInput{suffix.dtx} |
| 95 |
\end{document} |
| 96 |
%</driver> |
| 97 |
% \end{macrocode} |
| 98 |
% \section{Implementation} |
| 99 |
% First we announce the package and check for e\TeX~2. |
| 100 |
% \begin{macrocode} |
| 101 |
%<*style> |
| 102 |
\ProvidesPackage{suffix}[2006/07/15 1.5a Variant command support] |
| 103 |
\ifcase\ifx\eTeXversion\@undefined \@ne\fi |
| 104 |
\ifnum\eTeXversion<\tw@ \@ne\fi\z@ |
| 105 |
\else |
| 106 |
\PackageError{suffix}{This package requires eTeX version 2}% |
| 107 |
{You might try to use the `elatex' command.}% |
| 108 |
\fi |
| 109 |
% \end{macrocode} |
| 110 |
% \begin{macro}{\WithSuffix} |
| 111 |
% Then we define the \cmd{\WithSuffix} command. We use |
| 112 |
% \cmd{\@temptokena} to collect prefixes and let \cmd{\WSF@global} |
| 113 |
% to |\global| for global definitions. |
| 114 |
% |
| 115 |
% \begin{macrocode} |
| 116 |
\def\WithSuffix{\@temptokena{}\let\WSF@global\relax |
| 117 |
\WSF@sfx} |
| 118 |
% \end{macrocode} |
| 119 |
% \end{macro} |
| 120 |
% \begin{macro}{\WSF@sfx} |
| 121 |
% \begin{macro}{\WSF@append} |
| 122 |
% \begin{macro}{\WSF@gobblenext} |
| 123 |
% After checking all prefixes and stuff (we'll fill in this missing |
| 124 |
% link later), we add the defining command itself to the token list, |
| 125 |
% place \meta{macro} into \cmd{\reserved@a} and fetch \meta{suffix} |
| 126 |
% into \cmd{\reserved@b}. |
| 127 |
% \begin{macrocode} |
| 128 |
\long\def\WSF@sfx#1#2{\WSF@append{#1}\def\reserved@a{#2}% |
| 129 |
\afterassignment\WSF@decsuff \WSF@gobblenext} |
| 130 |
|
| 131 |
\def\WSF@append#1{\@temptokena\expandafter{\the\@temptokena#1}} |
| 132 |
|
| 133 |
\def\WSF@gobblenext{\let\reserved@b= } |
| 134 |
% \end{macrocode} |
| 135 |
% \end{macro} |
| 136 |
% \end{macro} |
| 137 |
% \end{macro} |
| 138 |
% \begin{macro}{\SuffixName} |
| 139 |
% \begin{macro}{\NoSuffixName} |
| 140 |
% While we are at it, let us define the macro names to use for |
| 141 |
% suffixed and unsuffixed \meta{macro}. |
| 142 |
% \begin{macrocode} |
| 143 |
\long\def\SuffixName#1{WSF:\string#1 \meaning} |
| 144 |
\def\NoSuffixName{WSF:\string} |
| 145 |
% \end{macrocode} |
| 146 |
% \end{macro} |
| 147 |
% \end{macro} |
| 148 |
% \begin{macro}{\WSF@decsuff} |
| 149 |
% We first check whether the macro has already been suffixed. If it |
| 150 |
% hasn't, we save a copy of it and redefine it in terms of |
| 151 |
% \cmd{\WSF@suffixcheck}. |
| 152 |
% \begin{macrocode} |
| 153 |
\def\WSF@decsuff{\ifcsname |
| 154 |
\expandafter\NoSuffixName\reserved@a\endcsname |
| 155 |
\else |
| 156 |
\WSF@global\expandafter\let\csname |
| 157 |
\expandafter\NoSuffixName\reserved@a |
| 158 |
\expandafter\endcsname \reserved@a |
| 159 |
\long\def\reserved@c##1{\WSF@global\protected\def |
| 160 |
##1{\WSF@suffixcheck##1}}% |
| 161 |
\expandafter\reserved@c\reserved@a |
| 162 |
\fi |
| 163 |
% \end{macrocode} |
| 164 |
% Once we have done that, we are ready for calling the definition |
| 165 |
% command on the suffixed \meta{macro}. |
| 166 |
% \begin{macrocode} |
| 167 |
\WSF@global |
| 168 |
\the\expandafter\@temptokena\csname |
| 169 |
\expandafter \SuffixName |
| 170 |
\reserved@a\reserved@b\endcsname} |
| 171 |
% \end{macrocode} |
| 172 |
% \end{macro} |
| 173 |
% \begin{macro}{\WSF@suffixcheck} |
| 174 |
% We now do the runtime code. This is |
| 175 |
% executed in a group of its own in order not to interfere with any |
| 176 |
% other macros. |
| 177 |
% \begin{macrocode} |
| 178 |
\def\WSF@suffixcheck#1{\begingroup\def\reserved@a{#1}% |
| 179 |
\futurelet\reserved@b\WSF@suffixcheckii} |
| 180 |
% \end{macrocode} |
| 181 |
% \end{macro} |
| 182 |
% \begin{macro}{\WSF@suffixcheckii} |
| 183 |
% After assigning the \meta{suffix} to \cmd{\reserved@b}, we split |
| 184 |
% into the case of known and unknown suffix. We don't code this |
| 185 |
% inline, since \cmd{\reserved@} in a false conditional might |
| 186 |
% confuse \TeX\ if it happens to be something like |\iffalse| |
| 187 |
% itself. |
| 188 |
% \begin{macrocode} |
| 189 |
\def\WSF@suffixcheckii{\ifcsname \expandafter\SuffixName |
| 190 |
\reserved@a\reserved@b\endcsname |
| 191 |
\expandafter |
| 192 |
\WSF@suffixcheckiii |
| 193 |
\else |
| 194 |
\expandafter |
| 195 |
\WSF@suffixcheckiv |
| 196 |
\fi} |
| 197 |
% \end{macrocode} |
| 198 |
% \end{macro} |
| 199 |
% \begin{macro}{\WSF@suffixcheckiii} |
| 200 |
% \begin{macro}{\WSF@suffixcheckiv} |
| 201 |
% Calling the macros is reasonably straightforward, we just have to |
| 202 |
% take care not to close the group at the wrong time. |
| 203 |
% \begin{macrocode} |
| 204 |
\def\WSF@suffixcheckiii{% |
| 205 |
\afterassignment\endgroup |
| 206 |
\expandafter\aftergroup |
| 207 |
\csname \expandafter \SuffixName\reserved@a\reserved@b\endcsname |
| 208 |
\WSF@gobblenext} |
| 209 |
|
| 210 |
\def\WSF@suffixcheckiv{% |
| 211 |
\expandafter\endgroup |
| 212 |
\csname \expandafter\NoSuffixName\reserved@a\endcsname} |
| 213 |
% \end{macrocode} |
| 214 |
% \end{macro} |
| 215 |
% \end{macro} |
| 216 |
% \begin{macro}{\WSF@sfx} |
| 217 |
% Now we just augment \cmd{WSF@sfx} to recognize all prefixes and |
| 218 |
% global commands: |
| 219 |
% \begin{macrocode} |
| 220 |
\WithSuffix\def\WSF@sfx\long{\WSF@append\long\WSF@sfx} |
| 221 |
\WithSuffix\def\WSF@sfx\global{\let\WSF@global\global\WSF@sfx} |
| 222 |
\WithSuffix\def\WSF@sfx\protected{\WSF@append\protected\WSF@sfx} |
| 223 |
\WithSuffix\def\WSF@sfx\expandafter{\expandafter\WSF@sfx\expandafter} |
| 224 |
\WithSuffix\edef\WSF@sfx\gdef{\let\WSF@global\global |
| 225 |
\expandafter\noexpand\csname\NoSuffixName\WSF@sfx\endcsname\def} |
| 226 |
\WithSuffix\edef\WSF@sfx\xdef{\let\WSF@global\global |
| 227 |
\expandafter\noexpand\csname\NoSuffixName\WSF@sfx\endcsname\edef} |
| 228 |
%</style> |
| 229 |
% \end{macrocode} |
| 230 |
%\end{macro} |
| 231 |
% \Finale |
| 232 |
% \endinput |
| 233 |
% Local Variables: |
| 234 |
% mode: doctex |
| 235 |
% TeX-master: "suffix.drv" |
| 236 |
% End: |