Debian Codegraph @

texmf-dist/doc/generic/multido/multido-doc.tex

raw
1 %% $Id: multido-doc.tex 317 2010-05-14 21:54:15Z herbert $
2 \documentclass[12pt]{article}
3 \usepackage{fp,multido}
4 \let\MDfv\fileversion
5 \usepackage{url}
6
7 \makeatletter
8
9 %% PAGE PARAMETERS:
10 \setlength{\parindent}{0pt} % paragraph indent
11 \setlength{\parskip}{4pt plus 1pt minus 1pt}
12 \setlength{\topmargin}{-2.5pc}
13 \setlength{\headheight}{12pt} % height of running head
14 \setlength{\headsep}{30pt} % distance between header and text
15 \setlength{\textheight}{54pc} % height of text on page
16 %%
17 %% DATES, VERSIONS AND TITLES:
18 %%
19 \def\expanddate#1/#2/#3/{\year=#1 \month=#2 \day=#3}
20 \begingroup
21 \expandafter\expanddate\filedate/
22 \xdef\thefiledate{\today}
23 \endgroup
24 \date{Version \fileversion\\ \thefiledate}
25 \def\@maketitle{%
26 \begin{center}
27 {\Large\bf \@title \par}
28 \vskip 1.2em {\lineskip .5em
29 \begin{tabular}[t]{c}\@author\end{tabular}\par}
30 \vskip .8em {\@date}%
31 \end{center}
32 \par
33 \vskip .5em}
34 %%
35 %% PAGE STYLE:
36 %%
37 \pagestyle{myheadings}
38 \markright{Documentation for multido.tex \hfill
39 v.\fileversion\hskip 1em \thefiledate\hfill}%
40 %%
41 %% VERBATIM:
42 %%
43 \begingroup
44 \catcode`\{=12 \catcode`\}=12
45 \catcode`\(=1 \catcode`\)=2
46 \catcode`\+=0 \catcode`\\=12
47 +gdef+|(\) % \| = character \
48 +gdef+{({) % \{ = character {
49 +gdef+}(}) % \} = character }
50 +endgroup
51 \def\Backslash{\protect\|}
52 %%
53 %% Define some functional font commands:
54 %%
55 \def\MainFont{\tt} % For macro definitions.
56 \def\UsageFont{\tt} % For in-line macro names.
57 \def\InlineFont{\tt} % For other in-line snipets of code.
58 \def\MetaFont{\rm\it} % For meta arguments.
59 %%
60 %% Short-cuts for font commands:
61 %%
62 \def\s#1{\string#1}
63 \def\t#1{{\InlineFont\string#1}} % For other in-line code.
64 \def\m#1{{\MetaFont #1\/}} % For just putting things in italics
65 \def\M#1{{\InlineFont\{\m{#1}\}}} % Arg is in italic, enclosed in tt braces.
66 \let\N\t % For in-line macro names.
67 \catcode`\<=13 \def<#1>{\m{#1}} % <meta>
68 %%
69 %% This is for listing macro definitions in a quote-like environment.
70 %%
71 \begingroup
72 \catcode`\[=1 \catcode`\]=2
73 \catcode`\{=13 \catcode`\}=12
74 \gdef\@MD[%
75 \catcode`\{=13 \catcode`\}=12
76 \def{##1}[\{[\MetaFont ##1]\}]]
77 \endgroup
78 \def\MD{%
79 \quote
80 \begingroup
81 \@MD
82 \def\end{\endgroup\end}%
83 \def\\{\@centercr\s}%
84 \MainFont
85 \s}
86 \def\endMD{\endquote}
87 %%
88 %% END PREAMBLE:
89 %%
90 \catcode`\"=13
91 \def"{\verb"}
92 \catcode`\@=12
93 \begin{document}
94 %%
95 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
96
97 \title{Documentation for multido.tex, version \MDfv:\\[2pt]
98 A loop macro for Generic \protect\TeX}
99 \author{Timothy Van Zandt%
100 \thanks{Author's address: Department of Economics, Princeton University,
101 Princeton, NJ 08544-1021, USA. Internet: \protect\url{[email protected]}.
102 This document was edited by Rolf Niepraschk \protect\url{[email protected]} and
103 Herbert Voss \protect\url{[email protected]} to get it run with LaTeX2e (2006-01-01)}}
104 \maketitle
105
106 "multido.tex"/"multido.sty" contains the \N\multido\ macro, which is a loop
107 facility for Generic TeX. This macro happens to be useful for drawing
108 pictures, and was originally developed for the PSTricks
109 package,\footnote{PSTricks is an extensive collection of PostScript-based
110 macros for Generic TeX. It is available from \url{CTAN://graphics/pstricks/}.}
111 but you can use it for other purposes as well.
112
113 A special feature is support of fixed-point addition. For example, PSTricks
114 uses the \N\multido\ to put numbers on axes, much like in the following
115 \LaTeX\ example:
116 \begin{verbatim}
117 \setlength{\unitlength}{1cm}
118 \small
119 \begin{picture}(8,1)(0,-.5)
120 \put(0,0){\vector(1,0){8}}
121 \multido{\i=0+1,\n=0+0.25}{8}{%
122 \put(\i,-.1){\line(0,1){.2}}
123 \put(\i,-.2){\makebox(0,0)[t]{\n}}}
124 \end{picture}
125 \end{verbatim}
126 \begin{center}
127 \setlength{\unitlength}{1cm}
128 \small
129 \begin{picture}(8,1)(0,-.5)
130 \put(0,0){\vector(1,0){8}}
131 \multido{\i=0+1,\n=0+0.25}{8}{%
132 \put(\i,-.1){\line(0,1){.2}}
133 \put(\i,-.2){\makebox(0,0)[t]{\n}}}
134 \end{picture}
135 \end{center}
136
137 The general syntax for \N\multido\ is:
138 \begin{MD}
139 \multido{variables}{repetitions}{stuff}
140 \end{MD}
141 <stuff> is whatever you want repeated; it can be any balanced \TeX\ input.
142 <repetitions> is the number times <stuff> is repeated.
143
144 The first argument is the interesting one. <variables> is a comma-separated
145 list of variable declarations.\footnote{Don't use commas to mark the decimal
146 point within the \protect<variables> argument, as they will be confused for
147 delimiters.} Each variable declaration is of the form:
148 \begin{center}\tt
149 <variable> = <initial value> + <increment>
150 \end{center}
151 <variable> is a command sequence that can be used in <stuff>. It is initially
152 set to <initial value>, and is then incremented by <increment> with each
153 repetition.
154
155 The first letter of the variable name determines the variable type. There are
156 four variable types:
157 \begin{description}
158 \item[Dimension (d or D)] The initial value and the increment should be
159 dimensions (lengths, in \LaTeX\ parlance). The substitution text is a
160 dimension, with "sp" units. E.g., "\dx=4cm+5pt".\footnote{For PSTricks users,
161 the unit is optional.}
162
163 \item[Number (n or N)] The initial value and increment should be integers or
164 numbers with the same number of digits to the right of the decimal. The one
165 exception is that it is always OK for the initial value to be an integer.
166 There can be at most 8 digits on each side of the decimal. The substitution
167 text is a number, with fixed-point addition. E.g., "\n=3+7.05",
168 "\Nx=5.30+-1.25".
169
170 \item[Integer (i or I)] The initial value and increment should be integers.
171 This gives the same result as using a number variable, but it is faster. E.g.,
172 "\I=2+-1".
173
174 \item[Real (r or R)] The initial value and increment should be integers or
175 numbers with at most 4 digits on each side of the decimal. The substitution
176 text is a number, but with floating point addition and occasional small
177 errors. This gives a less satisfactory result than using a number variable,
178 but it is faster. E.g., "\ry=4.2+1.05".
179 \end{description}
180
181 Here are some examples that illustrate how the substitution text is
182 determined:
183 \begin{quote}
184 "\multido{}{10}{\TeX\ }"\\[3pt]
185 \hbox to 2em{}\multido{}{10}{\TeX\ }{}\\[8pt]
186 "\multido{\d=2pt+3pt}{5}{\d, }"\\[3pt]
187 \hbox to 2em{}\multido{\d=2pt+3pt}{5}{\d, }{}\\[8pt]
188 "\multido{\n=2+3}{10}{\n, }"\\[3pt]
189 \hbox to 2em{}\multido{\n=2+3}{10}{\n, }{}\\[8pt]
190 "\multido{\i=2+-3}{10}{\i, }"\\[3pt]
191 \hbox to 2em{}\multido{\i=2+-3}{10}{\i, }{}\\[8pt]
192 "\multido{\r=2+3.05}{6}{\r, }"\\[3pt]
193 \hbox to 2em{}\multido{\r=2+3.05}{6}{\r, }{}\\[8pt]
194 "\multido{\n=2.00+-3.05}{8}{\n, }"\\[3pt]
195 \hbox to 2em{}\multido{\n=2.00+-3.05}{8}{\n, }{}
196 \end{quote}
197
198 Here are some details about the choice of names:
199 \begin{itemize}
200 \item Your computer won't explode if you use names that conflict with \TeX\
201 internal commands, but you might want to check name conflicts if you get
202 inexplicable errors. The command \N\MultidoCheckNames\ can be useful in this
203 case. It causes \N\multido\ to report an error whenever you use a variable
204 name that is already defined. But see the next item.
205 \item The whole \N\multido\ loop is grouped. This means, e.g., that although
206 "\i" is a Plain \TeX\ command sequence (giving a dotless ``\i''), you can use
207 the variable "\i" if you do not use any dotless i's in <stuff> (and if you do
208 not use \N\MultidoCheckNames).
209 \end{itemize}
210
211 Here are a few more details:
212 \begin{itemize}
213 \item \N\Multido\ commands can be nested.
214 \item Spaces after a \N\multido\ command are ignored. This makes \N\multido\
215 more hospitable for pictures.
216 \item Spaces between the various parts of the <variables> argument are
217 ignored.
218 \end{itemize}
219
220 And finally here a few special features, some of which are of interest mainly
221 macro writers and other \TeX nicians:
222 \begin{itemize}
223 \item The material that is repeated is not grouped, so that you can insert
224 your own recursive routines.
225 \item There is a variant, "\mmultido", which works just like "\multido" except
226 that the variables are all incremented once before starting.
227 \item If you use "\Multido" or "\MMultido" instead of "\multido" or
228 "\mmultido", resp., then the whole loop is not grouped. This can be useful,
229 e.g., for making entries in an alignment environment. However, these cannot be
230 nested within any "\multido" macro.
231 \item If the number of repetitions is a negative number, the variables are
232 incremented backwards.
233 \item The count register "\multidocount" keeps track of the number of current
234 iteration.
235 \item The command "\multidostop" causes the "\multido" loop to quit at the end
236 of the current iteration.
237 \item Fixed point addition is performed by \N\fpAdd\ and \N\fpSub:
238 \begin{MD}
239 \fpAdd{num1}{num2}{command}\\
240 \fpSub{num1}{num2}{command}
241 \end{MD}
242 <num2> is added to or subtracted from <num1>, and the answers is stored in the
243 command sequence given as the third argument. The rules about decimals and so
244 on that apply to number variables apply here as well. E.g., after
245 \begin{verbatim}
246 \fpSub{1.75}{-0.15}{\answer}
247 \end{verbatim}
248 \fpSub{1.75}{-0.15}{\answer}
249 the definition of "\answer" is \answer.
250 \end{itemize}
251
252 \subsection*{Changes:}
253
254 \begin{description}
255 \item[V1.1] Fixed bug in \N\FPadd\ that gave wrong answer for, e.g., $3.4 +
256 -0.2.$
257
258 \item[V1.2] Made unit optional for dimension variables when using PSTricks.
259
260 \item[V1.3] Now 0 repetitions really gets 0 repetitions. "\def\multido@"
261 changed to "\long\def\multido@".
262
263 % RN modification begin
264 %\end{description}
265 % RN modification end
266
267 \item[V1.4] Small change to make it compatible with PSTricks v0.93 and later.
268
269 \item[V1.41] Fix bug when using the fp-package (same macronames) and small
270 changes to this documentation (RN/HV)
271 \end{description}
272
273 \end{document}
274 %% END multido-doc