Debian Codegraph @

texmf-dist/source/latex/bigfoot/suffix.dtx

raw
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: