This repository has been archived by the owner on Sep 27, 2019. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 0
/
faq-mac-prog.tex
3725 lines (3424 loc) · 136 KB
/
faq-mac-prog.tex
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
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
% $Id: faq-mac-prog.tex,v 1.35 2014/01/28 18:17:36 rf10 Exp rf10 $
\section{Macro programming}
\subsection{``Generic'' macros and techniques}
\Question[Q-linmacnames]{Non-letters in macro names}
New \LaTeX{} users are often suprised that macro definitions
containing non-letters, such as
\begin{quote}
\begin{verbatim}
\newcommand{\cul8r}{Goodbye!}
\end{verbatim}
\end{quote}
fail to compile. The reason is that the \TeX{} macro language, unlike
most programming languages, allows % ! loin break (twatbili)
\Qref*{nothing but letters in macro names}{Q-whatmacros}.
There are a number of techniques for defining a macro with a name like
\csx{cul8r}. Unfortunately, none of the techniques is particularly
good:
\begin{enumerate}
\item Use \csx{csname}\dots\csx{endcsname} to define and invoke the
macro:
\begin{quote}
\begin{narrowversion}
\begin{verbatim}
\expandafter\newcommand
\csname cul8r\endcsname{Goodbye!}
I said, ``\csname cul8r\endcsname''.
\end{verbatim}
\end{narrowversion}
\begin{wideversion}
\begin{verbatim}
\expandafter\newcommand\csname cul8r\endcsname{Goodbye!}
I said, ``\csname cul8r\endcsname''.
\end{verbatim}
\end{wideversion}
\end{quote}
\begin{description}
\item[Pro:] No unexpected side effects
\item[Con:] So verbose as to be unusable
\end{description}
\item Define a ``special-command generator'', and use the resulting
commands:
\begin{quote}
\begin{narrowversion}
\begin{verbatim}
\newcommand{\DefineRemark}[2]{%
\expandafter\newcommand
\csname rmk-#1\endcsname{#2}%
}
\newcommand{\Remark}[1]{%
\csname rmk-#1\endcsname%
}
...
\DefineRemark{cul8r}{Goodbye!}
...
I said, ``\Remark{cul8r}''.
\end{verbatim}
\end{narrowversion}
\begin{wideversion}
\begin{verbatim}
\newcommand{\DefineRemark}[2]{%
\expandafter\newcommand\csname rmk-#1\endcsname{#2}%
}
\newcommand{\Remark}[1]{\csname rmk-#1\endcsname}
...
\DefineRemark{cul8r}{Goodbye!}
...
\Remark{cul8r}
\end{verbatim}
\end{wideversion}
\end{quote}
\begin{description}
\item[Pro:] Straightforward to use, not too untidy
\item[Con:] It's hardly doing what we set out to do (experts will
see that you are defining a macro, but others likely won't)
\end{description}
\item Convince \TeX{} that ``\texttt{8}'' is a letter:
\begin{quote}
\begin{verbatim}
\catcode`8 = 11
\newcommand{\cul8r}{Goodbye!}
I said, ``\cul8r''.
\end{verbatim}
\end{quote}
\begin{description}
\item[Pro:] \csx{cul8r} can be used directly
\item[Con:] Likely to break other uses of ``\texttt{8}'' (such as
numbers or dimensions; so
\cmdinvoke{setlength}{\csx{paperwidth}}{8in} tells us:
\begin{quote}
\begin{verbatim}
! Missing number, treated as zero.
<to be read again>
8
\end{verbatim}
\end{quote}
\end{description}
As a general rule, changing category codes is something to use
\emph{in extremis}, after detailed examination of options. It is
conceivable that such drastic action could be useful for you, but
most ordinary users are well advised not even to try such a
technique.
\item Define a macro \csx{cul} which must always be followed by
``\texttt{8r}'':
\begin{quote}
\begin{verbatim}
\def\cul8r{Goodbye!}
I said, ``\cul8r''.
\end{verbatim}
\end{quote}
\begin{description}
\item[Pro:] \csx{cul8r} can be used directly
\item[Con~\#1:] Breaks if \csx{cul} is followed by anything other
than ``\texttt{8r}'', with a confusing diagnostic~---
\csx{cul99} produces:
\begin{quote}
\begin{wideversion}
\begin{verbatim}
! Use of \cul doesn't match its definition.
<*> \cul9
9
\end{verbatim}
\end{wideversion}
\begin{narrowversion}
\begin{verbatim}
! Use of \cul doesn't match its
definition.
<*> \cul9
9
\end{verbatim}
\end{narrowversion}
\end{quote}
(which would confuse someone who hadn't even realised there
\emph{was} a definition of \csx{cul} in the document).
\item[Con~\#2:] Silently redefines existing \csx{cul}, if any;
as a result, the technique cannot be used to define both a
\csx{cul8r} and, say, a \csx{cul123} macro in the same
document.
\end{description}
\end{enumerate}
Technique~3 is in fact commonly used~--- in a limited form~--- within
most \LaTeX{} packages and within \LaTeX{} itself. The convention is to
use ``\texttt{@}'' within the names of internal macros to hide them
from the user and thereby prevent naming conflicts. To this end,
\LaTeX{} automatically treats ``\texttt{@}'' as a letter while
processing classes and packages and as a non-letter while processing
the user's document. The key to this technique is the separation:
internally a non-letter is used for macro names, and the user doesn't
see anything of it, while the status remains ``frozen'' in all the
definitions created within the class or package. See % ! line break
\Qref[question]{\csx{@} and \texttt{@} in macro names}{Q-atsigns} for
more information.
Note that analogous use of technique~3 in this example would give us
\begin{quote}
\begin{verbatim}
\begingroup
\catcode`8 = 11
\gdef\cul8r{Goodbye!}
\gdef\later{\cul8r}
\endgroup
I said, ``\later''.
\end{verbatim}
\end{quote}
which works, but rather defeats the object of the exercise.
(\csx{later} has the ``frozen'' catcode for `8', even though the value
has reverted to normal by the time it's used; note, also, the use of
the primitive command \csx{gdef}, since \csx{newcommand} can't make a
macro that's available outside the group.)
\emph{Recommendation}: Either choose another mechanism (such as
\csx{DefineRemark} above), or choose another name for your macro, one
that contains only ordinary letters. A common approach is to use
roman numerals in place of arabic ones:
\begin{quote}
\begin{verbatim}
\newcommand{\culVIIIr}{Goodbye!}
\end{verbatim}
\end{quote}
which rather spoils the intent of the joke implicit in the example
\csx{cul8r}!
\LastEdit*{2009-06-03}
\Question[Q-repeat-num]{Repeating a command \emph{n} times}
\TeX{} was \emph{not} designed as a programming language, but there
are occasions when you want to repeat some part of your document, just
as parts of programs need to run several times. An obvious
example is \TeX{}-based drawing: \LaTeX{}'s \environment{picture}
environment and \Package{pgf} (at least) provide repeat facilities~---
they are useful for drawing repeating patterns. As a result,
``common'' programming techniques often have to be emulated using
obscure macro \TeX{}niques.
This answer deals with repeating an operation a given number of times;
repeating operations once for each of a set of objects is dealt with
in the answer \Qref*{repeating ``over a set''}{Q-repeat-set}.
Plain \TeX{} itself provides a \csx{loop} \dots{} \csx{repeat}
contruct, which enables you to repeat a command (or set of commands).
The syntax is simple enough, but it use of \TeX{} conditionals is
different enough that many people find it confusing.
\begin{quote}
\begin{verbatim}
\newcount\foo
\foo=10
\loop
\message{\the\foo}
\advance \foo -1
\ifnum \foo>0
\repeat
\end{verbatim}
\end{quote}
In this slightly tricky code, \csx{loop} starts the construct ended by
\csx{repeat}, but \csx{repeat} also ``serves as'' the \csx{fi} to the
\csx{ifnum}. The loop above prints the numbers from 10 down to 1 via
\TeX{} \csx{message} (i.e., on the console output).
The \Package{multido} package is also `generic' (usable both in
\plaintex{} and \LaTeX{}); it defines a command \csx{multido} with
three arguments:
\begin{quote}
% ! line break
\cmdinvoke{multido}{\meta{variables}}{\meta{repetitions}}{\meta{stuff to repeat}}
\end{quote}
When the macro is executing, the \meta{stuff to repeat} gets executed
\meta{repetitions} times; the \meta{variables} gives a list of
variables that can be used in \meta{stuff}. Each variable is a
composite of a command sequence and how it varies; so a variable
``\csx{iz}\texttt{=2+4}'' sets \csx{iz} to \texttt{2} first time
around, then \texttt{6} and \texttt{10} in the next two iterations,
and so on. (The variable \csx{iz} is an integer; variables with other
initial letters represent different data types.)
% [do these things matter?]
% The \LaTeXe{} kernel has commands \csx{@for} and \csx{@tfor}.
%
% The \LaTeX{}3 kernel includes the command |\prg_replicate:nn|; this
% information isn't much use unless you're a \LaTeX{}3 user.
Both current \LaTeX{} and (experimental) \LaTeX{}3 have iteration
commands for internal use and for package writers; their use is
probably not recommendable.
The \LaTeX{} distribution package \Package{ifthen} offers the macro
\csx{whiledo}:
\begin{quote}
\begin{verbatim}
\newcounter{ct}
...
\setcounter{ct}{1}
\whiledo {\value{ct} < 5}%
{%
\thect\
\stepcounter {ct}%
}
\end{verbatim}
\end{quote}
The \Package{forloop} package provides nothing but \csx{forloop}:
\begin{quote}
\begin{verbatim}
\newcounter{ct}
...
\forloop{ct}{1}{\value{ct} < 5}%
{%
\thect\
}
\end{verbatim}
\end{quote}
as you can see, the arguments are counter, starting value and
termination condition; an optional argument supplies a step value
(default step is 1).
The \LaTeX{} \environment{picture} environment has a simple command
for repeated drawing:
\begin{quote}
\begin{verbatim}
\multiput(x,y)(xstep,ystep){n}{obj}
\end{verbatim}
\end{quote}
which places \meta{obj} (intended to be a bit of picture)
\meta{n} times at positions (\meta{x}, \meta{y}),
(\meta{x}+\meta{xstep}, \meta{y}+\meta{ystep}),
(\meta{x}+2\meta{xstep}, \meta{y}+2\meta{ystep}) and so on, adding the
displacement again each time. The command was designed for use in
\environment{picture}, but it makes no check, and may even be used to
provide eccentric typesetting in a ``regular'' sentence, such as:
\begin{quote}
\begin{verbatim}
Here \multiput(0,0)(1,1){3}{we} are again.
\end{verbatim}
\end{quote}
with predictable (if not actually desirable) effect. It may be used
with nothing but an iterative calculation in the braced argument, in
which case its graphical capabilities have no effect.
The \Package{pgffor} package, which is part of the % ! line break
\Qref*{\Package{pgf} distribution}{Q-drawing}, also
provides iterations to support the needs of graphics. Its syntax is
in the style of common programming languages:
\begin{quote}
\begin{verbatim}
\usepackage{pgffor}
\newcommand{\cmd}{-x-}
...
\foreach \n in {1,...,4}{\cmd{}}
\end{verbatim}
\end{quote}
typesets ``\texttt{-x-\relax-x-\relax-x-\relax-x-}''
The \csx{foreach} command has the potential drawback that its repeated
unit is executed in a group, so that any calculations done within the
loop are lost (unless their result is made \csx{global}); however, it
does not `build in' its graphical origins (as \csx{multiput} does) so
its potential outside its own graphics environment ``home'' is more
clear.
%
%% can't convince myself that \naturalloop helps with anything
% The \Package{etextools} package provides \csx{naturalloop}, which
% repeats material according to a count argument that you give it.
%
%% this stuff removed, following the observation that the package's use
%% of \repeat is inconsistent with both plain tex and latex; pity --
%% it's a nice package apart from being totally unusable :-(
%
% The \Package{repeat} package provides a \csx{for} command that
% encompasses a lot of the above; for example:
% \begin{quote}
% \begin{verbatim}
% \input repeat
% \newcount\foo
% \repeat
% \for{foo} \from{1} \to{10} \do{x*}
% \end{verbatim}
% \end{quote}
% which will typeset \texttt{x*} ten times (the count \csx{foo} will
% end up with value 11).
%
% Note the \plaintex{} usage: \Package{repeat} is ``generic'' and
% defines commands that are comfortable to \plaintex{} users, while
% remaining usable by \LaTeX{} users.
%
% The complete syntax is given in the meta-expression:
% \begin{quote}
% \begin{verbatim}
% \repeat
% \for{var}
% \from{<start>} \by{<step>} \to{<end>}
% \downto{<end>} \until{<cond>} \while{<cond>}
% \do{<operate on something>}
% \end{verbatim}
% \end{quote}
% You must choose a consistent set of \csx{from}, \csx{by}, \csx{to},
% \csx{downto}, \csx{until} and \csx{while} (none is actually required,
% but of course any loop has to have \emph{some}).
% In summary, while it is certainly possible to write this sort of code as
% a private project (for example, using the \eTeX{} \csx{numexpr}
% primitive), one cannot deny that plenty of choice for the task is
% readily available.
%
% (the above ignore Pic\TeX{}, which almost certainly has similar
% functions, but in the absence of a manual\dots{})
\begin{ctanrefs}
%\item[etextools.sty]\CTANref{etextools}
\item[forarray.sty]\CTANref{forarray}
\item[forloop.sty]\CTANref{forloop}
\item[ifthen.sty]Distributed as part of \CTANref{latex}
\item[multido.sty]\CTANref{multido}
\item[pgffor.sty]Distributed as part of \CTANref{pgf}
%\item[repeat.tex]\CTANref{repeat}
\end{ctanrefs}
\LastEdit{2013-03-01}
\Question[Q-repeat-set]{Repeating something for each `thing' in a set}
As another question % line break!
(\Qref*{repeating something a given number of times}{Q-repeat-num})
explains, \TeX{} is not explicitly designed for `regular' programming
operations. As a result, we must resort to arcane tricks to do the
seemingly simple task of repeating an operation. This answer deals
with repeating an operation for each of a given set of objects.
The \Package{etoolbox} package provides iteration over a
comma-separated list of items, in its \csx{docsvlist} and
\csx{forcsvlist} commands; they are well-described in the package
documentation. The \Package{datatool} package manages ``databases''
(of its own definition) and you may iterate over entries in such a
database using the command \csx{DTLforeach}.
The \Package{forarray} package defines its own ``list'' and ``array''
structures, together with commands \csx{ForEach} and \csx{ForArray}
which enable a command to be executed for each element in a list or
array, respectively.
The \Package{dowith} defines a pair of macros \csx{DoWith} and
\csx{StopDoing} that process each ``thing'' between them; a trivial
example of use is:
\begin{quote}
\begin{verbatim}
\usepackage{dowith}
...
\begin{document}
\newcommand{\foo}[1]{\message{#1+}
\DoWith\foo a{BBB}c\StopDoing
\end{verbatim}
\end{quote}
which produces terminal output:
\begin{quote}
\begin{verbatim}
a+ BBB+ c+
\end{verbatim}
\end{quote}
so, the macros have found 3 ``things'', including one with braces
around it. (The interpolated spaces come from the primitive
\csx{message} command.)
The only constraint is that all commands in the enclosed stuff are
``expandable'' (which means, for example, that you may not use
commands with optional arguments).
From the same stable (as \Package{dowith}) comes the package
\Package{commado}, that provides commands \csx{DoWithCSL} (apply a
command to each element of a comma-separated-variable list) and
\csx{DoWithBasesExts} (apply a command to each of a set of files,
defined by base name and ``extension''). Use of these \csx{DoWith*}
macros is also expandable (if the command applied to the list elements
is itself expandable).
\begin{ctanrefs}
\item[commado.sty]\CTANref{commado}
\item[datatool.sty]\CTANref{datatool}
\item[dowith.sty]\CTANref{dowith}
\item[etoolbox.sty]\CTANref{etoolbox}
\item[filesdo.sty]Distributed with \CTANref{commado}
\end{ctanrefs}
\LastEdit{2013-02-20}
%See \url{http://tex.stackexchange.com/questions/16189/repeat-command-n-times}
%for details (do i need this any more?)
\Question[Q-findwidth]{Finding the width of a letter, word, or phrase}
Put the word in a box, and measure the width of the box. For example,
\begin{quote}
\begin{verbatim}
\newdimen\stringwidth
\setbox0=\hbox{hi}
\stringwidth=\wd0
\end{verbatim}
\end{quote}
Note that if the quantity in the \csx{hbox} is a phrase, the actual
measurement only approximates the width that the phrase will occupy in
running text, since the inter-word glue can be adjusted in paragraph
mode.
The same sort of thing is expressed in \LaTeX{} by:
\begin{quote}
\begin{verbatim}
\newlength{\gnat}
\settowidth{\gnat}{\textbf{small}}
\end{verbatim}
\end{quote}
This sets the value of the length command |\gnat| to the width of ``small''
in bold-face text.
\Question[Q-patch]{Patching existing commands}
In the general case (possibly sticking something in the middle of an
existing command) this is difficult. However, the common requirement,
to add some code at the beginning or the end of an existing command,
is conceptually quite easy. Suppose we want to define a version of a
command that does some small extension of its original definition: we
would naturally write:
\begin{quote}
\begin{verbatim}
\renewcommand{\splat}{\mumble\splat}
\end{verbatim}
\end{quote}
However, this would not work: a call to \csx{splat} would execute
\csx{mumble}, and then call the redefined \csx{splat} again; this is an
`unterminated recursion', that will quickly exhaust \TeX{}'s memory.
Fortunately, the \TeX{} primitive \csx{let} command comes to our
rescue; it allows us to take a ``snapshot'' of the current state of a
command, which we can then use in the redefinition of the command.
So:
\begin{quote}
\begin{verbatim}
\let\OldSmooth\smooth
\renewcommand{\smooth}{\mumble\OldSmooth}
\end{verbatim}
\end{quote}
effects the required patch, safely. Adding things at the end of a
command works similarly.
If \csx{smooth} takes arguments, one must pass them on:
\begin{quote}
\begin{wideversion}
\begin{verbatim}
\let\OldSmooth\smooth
\renewcommand{\smooth}[2]{\mumble\OldSmooth{#1}{#2}}
\end{verbatim}
\end{wideversion}
\begin{narrowversion}
\begin{verbatim}
\let\OldSmooth\smooth
\renewcommand{\smooth}[2]%
{\mumble\OldSmooth{#1}{#2}}
\end{verbatim}
\end{narrowversion}
\end{quote}
The situation is more difficult still if \csx{smooth} takes an
optional argument; the structure of the command is so complex that the
simple \csx{let} command does not retain the necessary detail. In
this case, we need the \Package{letltxmacro} package which knows about all
sorts of \LaTeX{} commands and how to replicate them. Suppose we have
a command defined as:
\begin{quote}
\begin{verbatim}
\newcommand{\rough}[1][\default]{...}
\end{verbatim}
\end{quote}
with an optional argument (substituted with \csx{default} if it's not
present) as well as an ordinary one. In this case we copy it using
\begin{quote}
\begin{verbatim}
\LetLtxMacro{\NewRough}{\rough}
\end{verbatim}
\end{quote}
and then repeat the technique we had above, with one extension:
\begin{quote}
\begin{verbatim}
\renewcommand{\rough}[1][\newdef]%
{\mumble\OldRough[{#1}]{#2}}
\end{verbatim}
\end{quote}
We see here that (for tedious argument-matching reasons) it is
necessary to provide braces arround the optional argument that is
being passed on.
The general case may be achieved in two ways. First, one can use the
\LaTeX{} command \csx{CheckCommand}; this compares an existing command
with the definition you give it, and issues a warning if two don't
match. Use is therefore:
\begin{quote}
|\CheckCommand{\complex}{|\meta{original definition}|}|\\
|\renewcommand{\complex}{|\meta{new definition}|}|
\end{quote}
This technique is obviously somewhat laborious, but if the original
command comes from a source that's liable to change under the control
of someone else, it does at least warn you that your patch is in
danger of going wrong.
Otherwise, \LaTeX{} users may use one of the \Package{patchcmd},
\Package{ted} or \Package{etoolbox} packages.
The \Package{patchcmd} package addresses a slightly simpler task, by
restricting the set of commands that you may patch; you mayn't patch
any command that has an optional argument, though it does deal with
the case of commands defined with \csx{DeclareRobustCommand}. The
package defines a \csx{patchcommand} command, that takes three
arguments: the command to patch, stuff to stick at the front of its
definition, and stuff to stick on the end of its definition. So,
after
\begin{quote}
\begin{verbatim}
\def\b{b}
\patchcmd\b{a}{c}
\end{verbatim}
\end{quote}
we will have a new version of \csx{b} defined as ``\texttt{abc}''.
The \Package{ted} package is a `token list editor', and provides a
command \csx{substitute} which will patch the
contents of a macro, putting the result in a token-list, or
(in the form \csx{Substitute*}) using the result to (re)define a
macro. The following example defines a simple macro, and then changes
its definition:
\begin{quote}
\begin{verbatim}
\newcommand{\myfont}%
{\Large\sffamily\selectfont}
\Substitute*[\renewcommand{\myfont}]{\myfont}%
{\Large\sffamily}{\huge\itshape}
\end{verbatim}
\end{quote}
The macro's definition is now:
\begin{quote}
\begin{verbatim}
\huge\itshape\selectfont
\end{verbatim}
\end{quote}
The package also offers a command \csx{ShowTokens}, which shows the
content of its argument, one token to a line, with details of the
token's category code, etc. This is recommended as a debugging tool.
The \Package{etoolbox} package (which provides user access to \eTeX{}'s
programming facilities) provides a command \csx{patchcmd} which is
very similar to \csx{Substitute}, except that it only replaces a
single instance of the token(s) in its search pattern. Since not all
commands may be patched in this way, \csx{patchcmd} takes extra
arguments for \emph{success} and \emph{failure} cases. The
package also provides commands that prepend (\csx{pretocmd}) or append
(\csx{apptocmd}) to the definition of a command. Not all commands may
be patched in this way; the package provides a command
\csx{ifpatchable} which checks the prerequisites, and checks that the
target command's body does indeed include the patch string you propose
to use. (The command \csx{ifpatchable*} omits the test on the patch
string.)
The \Package{regexpatch} package deals with cases that are
inaccessible with \Package{etoolbox}; it uses the regular expression
(pattern-matching) package \Package{l3regex} from the \LaTeX{}3
distribution to find the code you need to patch. The package also
``knows about'' robust commands and about
\Qref*{\Package{biblatex}}{Q-biblatex}.
Finally, we'll briefly consider a package that is (just about)
usable, but not really recommendable. \Package{Patch} gives you an
ingenious (and difficult to understand) mechanism, and comes as an
old-style \LaTeX{} documented macro file, which can no longer be
processed to \Qref*{produce formatted documentation, etc.\@}{Q-install-doc}.
Fortunately, the file (\File{patch.doc}) may be input directly, and
``documentation'' may found by reading the source of the package.
Roughly speaking, one gives the command a set of instructions
analogous to \ProgName{sed} substitutions, and it regenerates the
command thus amended. Unless you can't do your job any other way,
\Package{patch} is best avoided.
\begin{ctanrefs}
\item[etoolbox.sty]\CTANref{etoolbox}
\item[l3regex.sty]Distributed as part of \CTANref{l3experimental}[l3regex]
\item[letltxmacro.sty]Distributed as part of \CTANref{oberdiek}[letltxmacro]
\item[patch.doc]\CTANref{patch}
\item[patchcommand.sty]\CTANref{patchcmd}
\item[regexpatch.sty]\CTANref{regexpatch}
\item[ted.sty]\CTANref{ted}
\end{ctanrefs}
\LastEdit{2012-12-21}
\Question[Q-compjobnam]{Comparing the ``job name''}
The token \csx{jobname} amusingly produces a sequence of characters
whose category code is 12 (`other'), regardless of what the characters
actually are. Since one inevitably has to compare a macro with the
contents of another macro (using \csx{ifx}, somewhere) one needs to
create a macro whose expansion looks the same as the expansion of
\csx{jobname}. We find we can do this with \csx{meaning}, if we strip
the ``\csx{show} command'' prefix.
The full command looks like:
\begin{quote}
\begin{wideversion}
\begin{verbatim}
\def\StripPrefix#1>{}
\def\jobis#1{FF\fi
\def\predicate{#1}%
\edef\predicate{\expandafter\StripPrefix\meaning\predicate}%
\edef\job{\jobname}%
\ifx\job\predicate
}
\end{verbatim}
\end{wideversion}
\begin{narrowversion}
\begin{verbatim}
\def\StripPrefix#1>{}
\def\jobis#1{FF\fi
\def\predicate{#1}%
\edef\predicate{\expandafter\StripPrefix
\meaning\predicate}%
\edef\job{\jobname}%
\ifx\job\predicate
}
\end{verbatim}
\end{narrowversion}
\end{quote}
And it's used as:
\begin{quote}
\begin{verbatim}
\if\jobis{mainfile}%
\message{YES}%
\else
\message{NO}%
\fi
\end{verbatim}
\end{quote}
Note that the command \csx{StripPrefix} need not be defined if you're
using \LaTeX{}~--- there's already an % line break!
\Qref*{internal command}{Q-atsigns} \csx{strip@prefix} that you can
use.
\Question[Q-isitanum]{Is the argument a number?}
\TeX{}'s own lexical analysis doesn't offer the macro programmer
terribly much support: while category codes will distinguish letters
(or what \TeX{} currently thinks of as letters) from everything else,
there's no support for analysing numbers.
The simple-minded solution is to compare numeric characters with the
characters of the argument, one by one, by a sequence of direct tests,
and to declare the argument ``not a number'' if any character fails
all comparisons:
\begin{quote}
\begin{verbatim}
\ifx1#1
\else\ifx2#1
...
\else\ifx9#1
\else\isanumfalse
\fi\fi...\fi
\end{verbatim}
\end{quote}
which one would then use in a tail-recursing macro to gobble an
argument. One could do slightly better by assuming (pretty safely)
that the digits' character codes are consecutive:
\begin{quote}
\begin{verbatim}
\ifnum`#1<`0 \isanumfalse
\else\ifnum`#1>`9 \isanumfalse
\fi
\fi
\end{verbatim}
\end{quote}
again used in tail-recursion. However, these forms aren't very
satisfactory: getting the recursion ``right'' is troublesome (it has a
tendency to gobble spaces in the argument), and in any case \TeX{}
itself has mechanisms for reading numbers, and it would be nice to use
them.
Donald Arseneau's \Package{cite} package offers the following test
for an argument being a strictly positive integer:
\begin{quote}
\begin{verbatim}
\def\IsPositive#1{%
TT\fi
\ifcat_\ifnum0<0#1 _\else A\fi
}
\end{verbatim}
\end{quote}
which can be adapted to a test for a non-negative integer thus:
\begin{quote}
\begin{verbatim}
\def\IsNonNegative{%
\ifcat_\ifnum9<1#1 _\else A\fi
}
\end{verbatim}
\end{quote}
or a test for any integer:
\begin{quote}
\begin{verbatim}
\def\gobbleminus#1{\ifx-#1\else#1\fi}
\def\IsInteger#1{%
TT\fi
\ifcat_\ifnum9<1\gobbleminus#1 _\else A\fi
}
\end{verbatim}
\end{quote}
but this surely stretches the technique further than is reasonable.
If we don't care about the sign, we can use \TeX{} to remove the
entire number (sign and all) from the input stream, and then look at
what's left:
\begin{quote}
\begin{narrowversion}
\begin{verbatim}
\def\testnum#1{\afterassignment\testresult
\count255=0#1 \end}
\def\testresult#1\end{\ifx\end#1\end}
\end{verbatim}
\end{narrowversion}
\begin{wideversion}
\begin{verbatim}
\def\testnum#1{\afterassignment\testresult\count255=0#1 \end}
\def\testresult#1\end{\ifx\end#1\end\isanumtrue\else\isanumfalse\fi}
\end{verbatim}
\end{wideversion}
\end{quote}
(which technique is due to David Kastrup; the trick for avoiding the
errors, noted in an earlier version of this answer, was suggested by
Andreas Matthias).
In a later thread on the same topic, Michael Downes offered:
\begin{quote}
\begin{wideversion}
\begin{verbatim}
\def\IsInteger#1{%
TT\fi
\begingroup \lccode`\-=`\0 \lccode`+=`\0
\lccode`\1=`\0 \lccode`\2=`\0 \lccode`\3=`\0
\lccode`\4=`\0 \lccode`\5=`\0 \lccode`\6=`\0
\lccode`\7=`\0 \lccode`\8=`\0 \lccode`\9=`\0
\lowercase{\endgroup
\expandafter\ifx\expandafter\delimiter
\romannumeral0\string#1}\delimiter
}
\end{verbatim}
\end{wideversion}
\begin{narrowversion}
\begin{verbatim}
\def\IsInteger#1{%
TT\fi
\begingroup \lccode`\-=`\0 \lccode`+=`\0
\lccode`\1=`\0 \lccode`\2=`\0
\lccode`\3=`\0 \lccode`\4=`\0
\lccode`\5=`\0 \lccode`\6=`\0
\lccode`\7=`\0 \lccode`\8=`\0
\lccode`\9=`\0
\lowercase{\endgroup
\expandafter\ifx\expandafter\delimiter
\romannumeral0\string#1}\delimiter
}
\end{verbatim}
\end{narrowversion}
\end{quote}
which relies on \csx{romannumeral} producing an empty result if its
argument is zero. Sadly, this technique has the unfortunate property
that it accepts simple expressions such as `\texttt{1+2-3}'; this
could be solved by an initial \csx{gobbleminus}-like construction.
All the complete functions above are designed to be used in \TeX{}
conditionals written ``naturally''~--- for example:
\begin{quote}
\begin{verbatim}
\if\IsInteger{<subject of test>}%
<deal with integer>%
\else
<deal with non-integer>%
\fi
\end{verbatim}
\end{quote}
The \LaTeX{} \Class{memoir} class has an internal command of its own,
\cmdinvoke*{checkifinteger}{num}, that sets the conditional command
\csx{ifinteger} according to whether the argument was an integer.
Of course, all this kerfuffle would be (essentially) void if there was
a simple means of ``catching'' \TeX{} errors. Imagining an
error-catching primitive \csx{ifnoerror}, one might write:
\begin{quote}
\begin{verbatim}
\def\IsInteger#1{%
TT%
\ifnoerror
\tempcount=#1\relax
% carries on if no error
\expandafter\iftrue
\else
% here if there was an error
\expandafter\iffalse
\fi
}
\end{verbatim}
\end{quote}
thus using \TeX{}'s own integer-parsing code to do the check. It's a
pity that such a mechanism was never defined (it could be that it's
impossible to program within \TeX{}!).
\begin{ctanrefs}
\item[memoir.cls]\CTANref{memoir}
\end{ctanrefs}
\Question[Q-hash]{Defining macros within macros}
The way to think of this is that |##| gets replaced by |#| in just the
same way that |#1| gets replaced by `whatever is the first argument'.
So if you define a macro:
\begin{quote}
\begin{verbatim}
\newcommand\a[1]{+#1+#1+#1+}
\end{verbatim}
\end{quote}
or (using the \TeX{} primitive \csx{def}):
\begin{quote}
\begin{verbatim}
\def\a#1{+#1+#1+#1+}
\end{verbatim}
\end{quote}
and use it as \cmdinvoke{a}{b},
the macro expansion produces `+b+b+b+',
as most people would expect.
However, if we now replace part of the macro:
\begin{quote}
\begin{narrowversion}
\begin{verbatim}
\newcommand\a[1]{+#1+%
\newcommand\x[1]{xxx#1}}
\end{verbatim}
\end{narrowversion}
\begin{wideversion}
\begin{verbatim}
\newcommand\a[1]{+#1+\newcommand\x[1]{xxx#1}}
\end{verbatim}
\end{wideversion}
\end{quote}
then \cmdinvoke{a}{b} will give us the rather odd
\begin{quote}
+b+\cmdinvoke{newcommand}{x}[1]{xxxb}
\end{quote}
so that the new \csx{x} ignores its argument.
If we use the \TeX{} primitive:
\begin{quote}
\begin{verbatim}
\def\a#1{+#1+\def\x #1{xxx#1}}
\end{verbatim}
\end{quote}
\cmdinvoke{a}{b} will expand to `+b+|\def\x b{xxxb}|'. This
defines \csx{x} to be a macro \emph{delimited} by |b|, and taking no
arguments, which is surely not what was intended!
Actually, to define \csx{x} to take an argument, we need
\begin{quote}
\begin{narrowversion}
\begin{verbatim}
\newcommand\a[1]{+#1+%
\newcommand\x[1]{xxx##1}}
\end{verbatim}
\end{narrowversion}
\begin{wideversion}
\begin{verbatim}
\newcommand\a[1]{+#1+\newcommand\x[1]{xxx##1}}
\end{verbatim}
\end{wideversion}
\end{quote}
or, using the \TeX{} primitive definition:
\begin{quote}
\begin{verbatim}
\def\a#1{+#1+\def\x ##1{xxx##1}}
\end{verbatim}
\end{quote}
and \cmdinvoke{a}{b} will expand to
\begin{quote}
+b+|\def\x #1{xxx#1}|
\end{quote}
because |#1| gets replaced by `b'
and |##| gets replaced by |#|.
To nest a definition inside a definition inside a definition then you
need |####1|, doubling the number of |#| signs; and at the next level
you need 8~|#|s each time, and so on.
\Question[Q-spinmacro]{Spaces in macros}
It's very easy to write macros that produce space in the typeset
output where it's neither desired nor expected. Spaces introduced by
macros are particularly insidious because they don't amalgamate with
spaces around the macro (unlike consecutive spaces that you
type), so your output can have a single bloated space that proves
to be made up of two or even more spaces that haven't amalgamated.
And of course, your output can also have a space where none was wanted
at all.
Spaces are produced, inside a macro as elsewhere, by space or tab
characters, or by end-of-line characters. There are two basic rules
to remember when writing a macro: first, the rules for ignoring spaces
when you're typing macros are just the same as the rules that apply
when you're typing ordinary text, and second, rules for ignoring
spaces do \emph{not} apply to spaces produced while a macro is being
obeyed (``expanded'').
Spaces are ignored in vertical mode (between paragraphs), at the
beginning of a line, and after a command name. Since sequences of
spaces are collapsed into one, it `feels as if' spaces are ignored if
they follow another space. Space can have syntactic meaning after
certain sorts of non-braced arguments (e.g., \emph{count} and
\emph{dimen} variable assignments in \plaintex{}) and after certain
control words (e.g., in \csx{hbox} |to|, so again we have instances
where it `feels as if' spaces are being ignored when they're merely
working quietly for their living.
Consider the following macro, fairly faithfully adapted from one that
appeared on \Newsgroup{comp.text.tex}:
\begin{narrowversion}
\begin{quote}
\begin{verbatim}
\newcommand{\stline}[1]
{ \bigskip \makebox[2cm]{ \textbf{#1} } }
\end{verbatim}
\end{quote}
(the original appeared on a single line: it's wrapped here to fit in
the printed \acro{FAQ}'s narrow columns).
\nothtml{\noindent}
\end{narrowversion}
\begin{wideversion}
\begin{quote}
\begin{verbatim}
\newcommand{\stline}[1]{ \bigskip \makebox[2cm]{ \textbf{#1} } }
\end{verbatim}
\end{quote}
\end{wideversion}
The macro definition contains five spaces:
\begin{itemize}
\item after the opening |{| of the macro body; this space will be
ignored, not because ``because the macro appears at the start of a
line'', but rather because the macro was designed to operate between