summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/elatex/elatex.tex
blob: d6e83e53207a38d2f2be9b0584365cb22e3a98ee (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
% $Id: elatex.tex,v 1.1 2007/05/28 15:16:54 lehman stable $
% This is the source of elatex.pdf. This file is primarily included
% in the distribution for legal reasons. It will not compile as is
% because it depends on unpublished classes and packages.

\documentclass{latexdoc}
\usepackage[latin9]{inputenc}
\usepackage[american]{babel}
\usepackage[strict,style=american]{csquotes}
\MakeAutoQuote{«}{»}
\MakeAutoQuote*{<}{>}

\rcsid{$Id: elatex.tex,v 1.1 2007/05/28 15:16:54 lehman stable $}

\titlepage{%
  title={The \sty{elatex} package},
  subtitle={An \etex toolbox for class and package authors},
  url={http://www.ctan.org/tex-archive/macros/latex/contrib/elatex/},
  author={Philipp Lehman},
  email={plehman@gmx.net},
  revision={\rcsrevision},
  date={\rcstoday}}

\hypersetup{%
  pdftitle={The elatex package},
  pdfsubject={An e-TeX toolbox for class and package authors},
  pdfauthor={Philipp Lehman},
  pdfkeywords={tex, etex, latex, class, package}}

\makeatletter
\renewcommand*{\=}{\nobreak\hskip\z@skip-\hskip\z@skip}
\makeatother

\begin{document}

\printtitlepage
\tableofcontents

\section{Introduction}

\subsection{About}

The \sty{elatex} package is a toolbox of programming facilities geared primarily towards \latex class and package authors. It provides \latex frontends to some of the new primitives provided by \etex as well as some generic tools which are not strictly related to \etex but match the profile of this package. This package will not modify any part of the \latex kernel. Its name is not meant to imply that it patches \latex such that the kernel makes use of \etex facilities by default. The package is work in progress. At present, it provides facilities for macro definitions, expansion control, hook management, and macro patching.

\subsection{License}

Copyright \textcopyright\ 2007 Philipp Lehman. This package is author\=maintained. Permission is granted to copy, distribute and\slash or modify this software under the terms of the \lppl, version 1.3.\fnurl{http://www.ctan.org/tex-archive/macros/latex/base/lppl.txt} This software is provided <as is>, without warranty of any kind, either expressed or implied, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose.

\subsection[Contributions]{Contributions and feedback}

I started to work on this package when I found myself implementing the same tools and shorthands I had employed in previous \latex packages for yet another package. For the most part, the facilities provided by \sty{elatex} address my needs as a package author and future development is likely to be guided by these needs as well. Please note that I will not be able to address any feature requests. However, I am open to contributions by other class and package authors, provided that the contributed code is sufficiently generic, matches the profile of this package, and may be added to the package without requiring significant adaption.

\subsection{Acknowledgments}

The \ltxcmd{ifblank} test of this package is based on code by Donald Arseneau.

\section{User commands}
\label{use}

The facilities in this section are geared towards regular users as well as class and package authors.

\subsection{Definitions}
\label{use:def}

\begin{syntax}

\cmd{newrobustcmd}{command}[arguments][optarg default]{definition}

The syntax and behavior of this command is similar to \ltxcmd{newcommand} except that the newly defined \ltxarg{command} is robust. This command differs from the \ltxcmd{DeclareRobustCommand} command from the \latex kernel in that it issues an error rather than just an informational message if the \ltxarg{command} is already defined. Since it uses \etex's low-level protection mechanism rather than the corresponding high-level \latex facilities, it does not require an additional macro to implement the <robustness>. This command itself is also robust.

\cmd{renewrobustcmd}{command}[arguments][optarg default]{definition}

The syntax and behavior of this command is similar to \ltxcmd{renewcommand} except that the redefined \ltxarg{command} is robust. This command itself is also robust.

\cmd{providerobustcmd}{command}[arguments][optarg default]{definition}

The syntax and behavior of this command is similar to \ltxcmd{providecommand} except that the newly defined \ltxarg{command} is robust. Note that this command only provides a robust definition if the \ltxarg{command} is undefined. It will not make an already defined \ltxarg{command} robust. This command itself is robust.

\subsection{Patching}
\label{use:pat}

\cmd{robustify}{command}

Redefines a \ltxarg{command} such that it is robust without altering its syntax or definition. If the \ltxarg{command} has been defined with \ltxcmd{DeclareRobustCommand}, this will be detected automatically. \latex's high-level protection mechanism is replaced by the corresponding low-level \etex facility in this case. This command is robust and may only be used in the document preamble.

\end{syntax}

\section{Author commands}

The facilities in this section are geared towards class and package authors.

\subsection{Definitions}
\label{aut:def}

The facilities in this section are simple but frequently required shorthands which extend the scope of the \ltxcmd{@namedef} and \ltxcmd{@nameuse} macros from the \latex kernel.

\begin{syntax}

\cmd{csdef}{csname}<arguments>{definition}

Similar to the \tex primitive \ltxcmd{def} except that it takes a control sequence name as its first argument. This command is robust and corresponds to \ltxcmd{@namedef}.

\cmd{csgdef}{csname}<arguments>{definition}

Similar to the \tex primitive \ltxcmd{gdef} except that it takes a control sequence name as its first argument. This command is robust.

\cmd{csedef}{csname}<arguments>{definition}

Similar to the \tex primitive \ltxcmd{edef} except that it takes a control sequence name as its first argument. This command is robust.

\cmd{csxdef}{csname}<arguments>{definition}

Similar to the \tex primitive \ltxcmd{xdef} except that it takes a control sequence name as its first argument. This command is robust.

\cmd{protected@csedef}{csname}<arguments>{definition}

Similar to \ltxcmd{csedef} except that \latex's protection mechanism is temporarily enabled. To put it in other words: this command is similar to the \latex kernel command \ltxcmd{protected@edef} except that it takes a control sequence name as its first argument. This command is robust.

\cmd{protected@csxdef}{csname}<arguments>{definition}

Similar to \ltxcmd{csxdef} except that \latex's protection mechanism is temporarily enabled. To put it in other words: this command is similar to the \latex kernel command \ltxcmd{protected@xdef} except that it takes a control sequence name as its first argument. This command is robust.

\cmd{cslet}{csname}{command}

Similar to the \tex primitive \ltxcmd{let} except that the first argument is a control sequence name. This command is robust.

\cmd{letcs}{command}{csname}

Similar to the \tex primitive \ltxcmd{let} except that the second argument is a control sequence name. This command is robust.

\cmd{csletcs}{csname}{csname}

Similar to the \tex primitive \ltxcmd{let} except that both arguments are control sequence names. This command is robust.

\cmd{csuse}{csname}

Takes a control sequence name as its argument and forms a control sequence token. This command differs from the \ltxcmd{@nameuse} macro from the \latex kernel in that it expands to an empty string if the control sequence is undefined.

\end{syntax}

\subsection[Arithmetic]{Arithmetic definitions}
\label{aut:cal}

The facilities in this section permit calculations using macros rather than length registers and counters.

\begin{syntax}

\cmd{numdef}{command}{integer expression}

This command is similar to \ltxcmd{edef} except that the \ltxarg{integer expression} is processed with \ltxcmd{numexpr}. The \ltxarg{integer expression} may be any arbitrary code which is valid in this context. The definition assigned to \ltxarg{command} will be the result of that calculation. If the \ltxarg{command} is undefined, it will be initialized to <\texttt{0}> before the \ltxarg{integer expression} is processed.

\cmd{numgdef}{command}{integer expression}

Similar to \ltxcmd{numdef} except that the assignment is global.

\cmd{csnumdef}{csname}{integer expression}

Similar to \ltxcmd{numdef} except that it takes a control sequence name as its first argument.

\cmd{csnumgdef}{csname}{integer expression}

Similar to \ltxcmd{numgdef} except that it takes a control sequence name as its first argument.

\cmd{dimdef}{command}{dimen expression}

This command is similar to \ltxcmd{edef} except that the \ltxarg{dimen expression} is processed with \ltxcmd{dimexpr}. The \ltxarg{dimen expression} may be any arbitrary code which is valid in this context. The definition assigned to \ltxarg{command} will be the result of that calculation. If the \ltxarg{command} is undefined, it will be initialized to <\texttt{0pt}> before the \ltxarg{dimen expression} is processed.

\cmd{dimgdef}{command}{dimen expression}

Similar to \ltxcmd{dimdef} except that the assignment is global.

\cmd{csdimdef}{csname}{dimen expression}

Similar to \ltxcmd{dimdef} except that it takes a control sequence name as its first argument.

\cmd{csdimgdef}{csname}{dimen expression}

Similar to \ltxcmd{dimgdef} except that it takes a control sequence name as its first argument.

\cmd{gluedef}{command}{glue expression}

This command is similar to \ltxcmd{edef} except that the \ltxarg{glue expression} is processed with \ltxcmd{glueexpr}. The \ltxarg{glue expression} may be any arbitrary code which is valid in this context. The definition assigned to \ltxarg{command} will be the result of that calculation. If the \ltxarg{command} is undefined, it will be initialized to <\texttt{0pt plus 0pt minus 0pt}> before the \ltxarg{glue expression} is processed.

\cmd{gluegdef}{command}{glue expression}

Similar to \ltxcmd{gluedef} except that the assignment is global.

\cmd{csgluedef}{csname}{glue expression}

Similar to \ltxcmd{gluedef} except that it takes a control sequence name as its first argument.

\cmd{csgluegdef}{csname}{glue expression}

Similar to \ltxcmd{gluegdef} except that it takes a control sequence name as its first argument.

\cmd{mudef}{command}{muglue expression}

This command is similar to \ltxcmd{edef} except that the \ltxarg{muglue expression} is processed with \ltxcmd{muexpr}. The \ltxarg{muglue expression} may be any arbitrary code which is valid in this context. The definition assigned to \ltxarg{command} will be the result of that calculation. If the \ltxarg{command} is undefined, it will be initialized to <\texttt{0mu}> before the \ltxarg{muglue expression} is processed.

\cmd{mugdef}{command}{muglue expression}

Similar to \ltxcmd{mudef} except that the assignment is global.

\cmd{csmudef}{csname}{muglue expression}

Similar to \ltxcmd{mudef} except that it takes a control sequence name as its first argument.

\cmd{csmugdef}{csname}{muglue expression}

Similar to \ltxcmd{mugdef} except that it takes a control sequence name as its first argument.

\end{syntax}

\subsection[Expansion]{Expansion control}

The facilities in this section are useful to control expansion in an \ltxcmd{edef} or a similar context.

\begin{syntax}

\cmd{expandonce}{command}

This command expands \ltxarg{command} once and prevents further expansion of the replacement text.

\cmd{csexpandonce}{csname}

Similar to \ltxcmd{expandonce} except that it takes a control sequence name as its argument.

\cmd{protecting}{code}

This command applies \latex's protection mechanism, which normally requires prefixing each fragile command with \ltxcmd{protect}, to an entire chunk of arbitrary \ltxarg{code} or text. Its behavior depends on the current state of \ltxcmd{protect}. Note that the braces around \ltxarg{code} are mandatory even if it is a single token.

\end{syntax}

\subsection[Hooks]{Hook management}
\label{aut:hok}

The facilities in this section are intended for hook management. A <hook> in this context is a plain macro without any arguments and prefixes which is used to collect code to be executed later. These facilities may also be useful to patch simple macros by appending code to them. For more complex patching operations, see section \ref{aut:pat}. All commands in this section will initialize the hook if it is undefined.

\subsubsection{Appending code to a hook}
\label{aut:hok:app}

The facilities in this section append arbitrary code to a hook.

\begin{syntax}

\cmd{appto}{command}{code}

This command appends arbitrary \ltxarg{code} to a \ltxarg{command}. If the \ltxarg{code} contains any parameter characters, they need not be doubled. This command is robust.

\cmd{gappto}{command}{code}

Similar to \ltxcmd{appto} except that the assignment is global. This command may be used as a drop-in replacement for the \ltxcmd{g@addto@macro} command in the \latex kernel.

\cmd{eappto}{command}{code}

This command appends arbitrary \ltxarg{code} to a \ltxarg{command}. The \ltxarg{code} is expanded at definition\=time. Only the new \ltxarg{code} is expanded, the current definition of \ltxarg{command} is not. This command is robust.

\cmd{xappto}{command}{code}

Similar to \ltxcmd{eappto} except that the assignment is global.

\cmd{protected@eappto}{command}{code}

Similar to \ltxcmd{eappto} except that \latex's protection mechanism is temporarily enabled.

\cmd{protected@xappto}{command}{code}

Similar to \ltxcmd{xappto} except that \latex's protection mechanism is temporarily enabled.

\cmd{csappto}{csname}{code}

Similar to \ltxcmd{appto} except that it takes a control sequence name as its first argument.

\cmd{csgappto}{csname}{code}

Similar to \ltxcmd{gappto} except that it takes a control sequence name as its first argument.

\cmd{cseappto}{csname}{code}

Similar to \ltxcmd{eappto} except that it takes a control sequence name as its first argument.

\cmd{csxappto}{csname}{code}

Similar to \ltxcmd{xappto} except that it takes a control sequence name as its first argument.

\cmd{protected@cseappto}{command}{code}

Similar to \ltxcmd{protected@eappto} except that it takes a control sequence name as its first argument.

\cmd{protected@csxappto}{command}{code}

Similar to \ltxcmd{protected@xappto} except that it takes a control sequence name as its first argument.

\end{syntax}

\subsubsection{Prepending code to a hook}
\label{aut:hok:pre}

The facilities in this section <prepend> arbitrary code to a hook, \ie the code is inserted at the beginning of the hook rather than being added at the end.

\begin{syntax}

\cmd{preto}{command}{code}

Similar to \ltxcmd{appto} except that the \ltxarg{code} is <prepended>, \ie inserted at the beginning of the hook rather than being added at the end.

\cmd{gpreto}{command}{code}

Similar to \ltxcmd{preto} except that the assignment is global.

\cmd{epreto}{command}{code}

Similar to \ltxcmd{eappto} except that the \ltxarg{code} is <prepended>, \ie inserted at the beginning of the hook rather than being added at the end.

\cmd{xpreto}{command}{code}

Similar to \ltxcmd{epreto} except that the assignment is global.

\cmd{protected@epreto}{command}{code}

Similar to \ltxcmd{epreto} except that \latex's protection mechanism is temporarily enabled.

\cmd{protected@xpreto}{command}{code}

Similar to \ltxcmd{xpreto} except that \latex's protection mechanism is temporarily enabled.

\cmd{cspreto}{csname}{code}

Similar to \ltxcmd{preto} except that it takes a control sequence name as its first argument.

\cmd{csgpreto}{csname}{code}

Similar to \ltxcmd{gpreto} except that it takes a control sequence name as its first argument.

\cmd{csepreto}{csname}{code}

Similar to \ltxcmd{epreto} except that it takes a control sequence name as its first argument.

\cmd{csxpreto}{csname}{code}

Similar to \ltxcmd{xpreto} except that it takes a control sequence name as its first argument.

\cmd{protected@csepreto}{command}{code}

Similar to \ltxcmd{protected@epreto} except that it takes a control sequence name as its first argument.

\cmd{protected@csxpreto}{command}{code}

Similar to \ltxcmd{protected@xpreto} except that it takes a control sequence name as its first argument.

\end{syntax}

\subsection{Patching}
\label{aut:pat}

The facilities in this section are useful to hook into or modify existing code. All commands presented here preserve the number of arguments and the prefixes of the patched \ltxarg{command}. Note that the patching process involves detokenizing the \ltxarg{command} and retokenizing it under the current category code regime after patching. The category code of <@> is temporarily set to 11. If the definition of the \ltxarg{command} includes any tokens with non\=standard category codes, the respective category codes must be adjusted prior to patching. If the code to be replaced or inserted refers to the parameters of the \ltxarg{command} to be patched, the parameter characters need not be doubled when invoking one of the commands below. Note that \ltxcmd{outer} commands may not be patched.

\begin{syntax}

\cmd{patchcommand}[prefix]{command}{search}{replace}{success}{failure}

This command extracts the definition of a \ltxarg{command}, replaces \ltxarg{search} with \ltxarg{replace}, and reassembles the \ltxarg{command}. The pattern match is category code agnostic and matches the first occurence of the \ltxarg{search} string in the definition of the \ltxarg{command} to be patched. If an optional \ltxarg{prefix} is specified, it replaces the prefixes of the \ltxarg{command}. An empty \ltxarg{prefix} strips all prefixes from the \ltxarg{command}. This command executes \ltxarg{success} if patching succeeds, and \ltxarg{failure} otherwise. It is robust and may only be used in the document preamble. The assignment is local.

\cmd{ifpatchable}{command}{search}{true}{false}

This command executes \ltxarg{true} if the \ltxarg{command} is defined and the \ltxarg{search} pattern is found in its definition, and \ltxarg{false} otherwise. This command is robust and may only be used in the document preamble.

\cmd{apptocommand}{command}{code}

This command appends \ltxarg{code} to the definition of \ltxarg{command}. In contrast to the \ltxcmd{appto} command from section \ref{aut:hok:app}, this one may be used to patch a \ltxarg{command} which takes an arbitrary number of arguments. The \ltxarg{code} may refer to the parameters of the \ltxarg{command} in this case. This command is robust and may only be used in the document preamble. The assignment is local.

\cmd{pretocommand}{command}{code}

This command is similar to \ltxcmd{apptocommand} except that the \ltxarg{code} is <prepended>, \ie inserted at the beginning of the definition of \ltxarg{command}. In contrast to the \ltxcmd{preto} command from section \ref{aut:hok:app}, this one may be used to patch a \ltxarg{command} which takes an arbitrary number of arguments. The \ltxarg{code} may refer to the parameters of the \ltxarg{command} in this case. This command is robust and may only be used in the document preamble. The assignment is local.

\end{syntax}

\subsection{Tests}

\begin{syntax}

\cmd{ifdef}{command}{true}{false}

A \latex wrapper for the \etex primitive \ltxcmd{ifdefined}. This command expands to \ltxarg{true} if the \ltxarg{command} is defined, and to \ltxarg{false} otherwise. Note that the \ltxarg{command} is considered as defined even if its meaning is \ltxcmd{relax}.

\cmd{ifundef}{command}{true}{false}

Expands to \ltxarg{true} if the \ltxarg{command} is undefined, and to \ltxarg{false} otherwise. Apart from reversing the logic of the test, this command also differs from \ltxcmd{ifdef} in that the \ltxarg{command} is considered as undefined if its meaning is \ltxcmd{relax}.

\cmd{ifcsdef}{csname}{true}{false}

A \latex wrapper for the \etex primitive \ltxcmd{ifcsname}. This command expands to \ltxarg{true} if \ltxarg{csname} is defined, and to \ltxarg{false} otherwise. Note that \ltxarg{csname} is considered as defined even if its meaning is \ltxcmd{relax}.

\cmd{ifcsundef}{csname}{true}{false}

Expands to \ltxarg{true} if \ltxarg{csname} is undefined, and to \ltxarg{false} otherwise. Apart from reversing the logic of the test, this command also differs from \ltxcmd{ifcsdef} in that the \ltxarg{csname} is considered as undefined if its meaning is \ltxcmd{relax}. This command may be used as a drop-in replacement for the \ltxcmd{@ifundefined} test in the \latex kernel.

\cmd{ifblank}{string}{true}{false}

Expands to \ltxarg{true} if the \ltxarg{string} is blank (empty or spaces), and to \ltxarg{false} otherwise. The \ltxarg{string} is not expanded in the test.

\end{syntax}

\section{Revision history}

\begin{changelog}

\begin{release}{1.1}{2007-05-28}

\item Added \ltxcmd{protected@csedef}\see{aut:def}
\item Added \ltxcmd{protected@csxdef}\see{aut:def}
\item Added \ltxcmd{gluedef}\see{aut:cal}
\item Added \ltxcmd{gluegdef}\see{aut:cal}
\item Added \ltxcmd{csgluedef}\see{aut:cal}
\item Added \ltxcmd{csgluegdef}\see{aut:cal}
\item Added \ltxcmd{mudef}\see{aut:cal}
\item Added \ltxcmd{mugdef}\see{aut:cal}
\item Added \ltxcmd{csmudef}\see{aut:cal}
\item Added \ltxcmd{csmugdef}\see{aut:cal}
\item Added \ltxcmd{protected@eappto}\see{aut:hok:app}
\item Added \ltxcmd{protected@xappto}\see{aut:hok:app}
\item Added \ltxcmd{protected@cseappto}\see{aut:hok:app}
\item Added \ltxcmd{protected@csxappto}\see{aut:hok:app}
\item Added \ltxcmd{protected@epreto}\see{aut:hok:pre}
\item Added \ltxcmd{protected@xpreto}\see{aut:hok:pre}
\item Added \ltxcmd{protected@csepreto}\see{aut:hok:pre}
\item Added \ltxcmd{protected@csxpreto}\see{aut:hok:pre}
\item Fixed bug in \ltxcmd{newrobustcmd}\see{use:def}
\item Fixed bug in \ltxcmd{renewrobustcmd}\see{use:def}
\item Fixed bug in \ltxcmd{providerobustcmd}\see{use:def}

\end{release}

\begin{release}{1.0}{2007-05-07}

\item Initial public release

\end{release}

\end{changelog}

\end{document}