diff options
Diffstat (limited to 'obsolete/macros/latex209/contrib/multido/md-doc.tex')
-rw-r--r-- | obsolete/macros/latex209/contrib/multido/md-doc.tex | 459 |
1 files changed, 459 insertions, 0 deletions
diff --git a/obsolete/macros/latex209/contrib/multido/md-doc.tex b/obsolete/macros/latex209/contrib/multido/md-doc.tex new file mode 100644 index 0000000000..ed44f56a26 --- /dev/null +++ b/obsolete/macros/latex209/contrib/multido/md-doc.tex @@ -0,0 +1,459 @@ +%%%%%%%%%%%%%%%%%%%%%%%% md-doc.tex Version 1.0, 92/09/28 %%%%%%%%%%%%%%% + +%%%%%%%%%%%%%%%%%%%%%%%%% COPYING %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%% +%% COPYRIGHT 1992, by Timothy Van Zandt, tvz@Princeton.EDU +%% +%% Copying of part or all of this file is allowed under the following +%% conditions only: +%% (1) You may freely distribute unchanged copies of the file. Please +%% include the documentation when you do so. +%% (2) You may modify a renamed copy of the file, but only for personal +%% use or use within an organization. +%% (3) You may copy fragments from the file, for personal use or for +%% distribution, as long as credit is given where credit is due. +%% +%% You are NOT ALLOWED to take money for the distribution or use of +%% this file or modified versions or fragments thereof, except for +%% a nominal charge for copying etc. +%% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%% DESCRIPTION: %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%% +%% multido.tex contains a loop macro, \multido, that supports floating +%% point addition and has a nice interface. Among other things, it +%% is useful for pictures and putting numbers on axes. multido.tex +%% is compatible with most TeX macro packages. Name a copy of the file +%% multido.sty if you want to use as a LaTeX style option. +%% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%% GETTING MULTIDO %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%% +%% The complete multido.tex distribution is available in .tar.Z form from +%% the /pub directory at Princeton.EDU. multido.tex is also available +%% at various TeX archives. However, all you really need is multido.tex +%% and md-doc.tex. +%% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + + %%%%%%%%%%%%%%%%%%%%%%%%%% PRINTING THE DOCUMENTATION +%%%%%%%%%%%%%%%%%%%%%%%% %% +%% multido.tex is also distributed with the documentation already +%% typeset. Check the /pub directory at Princeton.EDU if you can +%% handle .tar.Z files. +%% +%% This file contains the Usage Notes, Run with LaTeX with or without NFSS. +%% +%% If you include the doc style option, the documented code +%% in multido.doc is also printed at the end. For this, +%% you must have the files doc.sty and gind.ist from Frank +%% Mittelbach's doc package (try the /soft/tex/latex-supported/doc +%% directory at ftp.uni-stuttgart.de ). This documented was originally +%% prepared using v1.7k (92/08/24) of doc.sty. +%% +%% To make an index on UNIX using makeindex, resolve cross-references and +%% give the command: +%% makeindex -s gind.ist multido.idx +%% and run the file again. The index is only for the documented code. +%% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +%%%%%%%%%%%%%%%%%%% BEGIN PREAMBLE %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%% +\documentstyle[12pt]{article} +\input multido.tex +\catcode`\@=11 +%% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +%%%%%%%%%%%%%%%%%%%%%%%% DOC? STUFF %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%% +%% Check whether doc.sty has been input. If not, code won't be printed. +%% \CodeLineIndex can only be used in preamble. Other code-specific +%% preamble stuff has been left to the end of this file. +%% +\@ifundefined{StopEventually}% + {\def\StopEventually{\end{document}}}% + {\CodelineIndex} +%% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +%%%%%%%%%%%%%%%%%%% PAGE PARAMETERS %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%% +\setlength{\parindent}{0pt} % paragraph indent +\setlength{\parskip}{4pt plus 1pt minus 1pt} +\setlength{\oddsidemargin}{4pc} +\setlength{\evensidemargin}{4pc} +\setlength{\topmargin}{-2.5pc} +\setlength{\headheight}{12pt} % height of running head +\setlength{\headsep}{20pt} % distance between header and text +\setlength{\textheight}{54pc} % height of text on page +\setlength{\textwidth}{35pc} % total width of a page +%% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +%%%%%%%%%%%%%%%%%%%%%%%% VERBATIM %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%% +%% This is good for examples, using \verb or whatever explicitly. +\def\Ex{\quote\tt} +\def\endEx{\endquote} +%% +%% In the verbatim environment, \trivlist is changed to \list, so that +%% verbatim code is offset from the left margin. +%% +\def\@verbatim{% + \list{}{} \item[]% + \leftskip\@totalleftmargin\rightskip\z@ + \parindent\z@\parfillskip\@flushglue + \@@par\leavevmode\parskip=\z@ + \def\par{\leavevmode\null\@@par}% + \obeylines + \let\do\@makeother \dospecials\catcode`\>=14\tt} +\def\endverbatim{\endlist} +%% +\def\m#1{{\rm\it #1}} % For just putting things in italics (m=>meta>) +\def\M#1{{\tt\{}\m{#1}{\tt\}}} % Argument is in italic, enclosed in tt braces. +\def\N#1{{\tt\string#1}} % For in-line macro names +\catcode`\>=13\def>{} % Now we can write \LaTeX> without problem. +%% +%% This is adapted from Mittelbach's doc.sty: +\def\MyShortVerb#1{% + \expandafter + \xdef\csname cc\string#1\endcsname{\the\catcode`#1}% + \begingroup + \catcode`\~\active \lccode`\~`#1% + \lowercase{% + \global\expandafter\let + \csname ac\string#1\endcsname~% + \gdef~{\verb~}}% + \endgroup + \global\catcode`#1\active} +%% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + + +%%%%%%%%%%%%%%%%%%%%%%%%%% SECTIONS %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%% +%% Section headings use customizable fonts, leave less space above +%% and below, and may overhang on left. +%% +\def\section{\@startsection{section}{1}{\sechang}{-3ex plus -1ex + minus -.2ex}{1.5ex plus .2ex}{\secfont}} +\def\subsection{\@startsection{subsection}{2}{\subsechang}{-2.75ex plus -1ex + minus -.2ex}{1.25ex plus .2ex}{\subsecfont}} +\newdimen\sechang +\newdimen\subsechang +\sechang=-.6in +\subsechang=-.375in +\def\secfont{\Large\bf} % Section headings +\def\subsecfont{\tt\large} % Subsection heading +%% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + + +%%%%%%%%%%%%%%%%%%%%%% DATES, VERSIONS AND TITLES %%%%%%%%%%%%%%%%%%%%%%%%%%% +%% +\def\expanddate#1/#2/#3/{\number#3{} \month=#2 \ifcase\month\or + January \or February \or March \or April \or May \or June \or + July \or August \or September \or October \or November \or December \fi + 19#1} +\def\thefiledate{\expandafter\expanddate\filedate/} +\date{Version \fileversion\\ \thefiledate} +\def\@maketitle{\newpage + \null + \begin{center} + {\Large\bf \@title \par} + \vskip 1.2em {\lineskip .5em + \begin{tabular}[t]{c}\@author\end{tabular}\par} + \vskip .8em {\@date}% + \end{center} + \par + \vskip .5em} +%% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +%%%%%%%%%%%%%%%%%%%%%%%%%%% PAGE STYLE %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%% +\pagestyle{myheadings} +\markright{Documentation for multido.tex \hfill + v.\fileversion\hskip 1em \thefiledate\hfill}% +%% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +%%%%%%%%%%%%%%%%%%%%%%%%% END PREAMBLE %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%% +\MyShortVerb\" +\catcode`\@=12 +\begin{document} +%% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\title{Documentation for multido.tex:\\[2pt] + A loop macro for Generic \protect\TeX} +\author{Timothy Van Zandt% + \thanks{Author's address: Department of Economics, Princeton University, + Princeton, NJ 08544-1021, USA. Internet: {\tt tvz@Princeton.EDU}}} +\maketitle + + +\section{Usage notes} + + "multido.tex"/"multido.sty" contains the \N\multido> macro, which is a loop +facility for Generic TeX. This macro happens to be useful for drawing +pictures, and was originally developed for the PSTricks +package,\footnote{PSTricks is an extensive collection of PostScript-based +macros for Generic TeX. It is available from the /pub directory at +Princeton.EDU, and \TeX> archives.} but you can use it for other purposes as +well. + + A special feature is support of fixed-point addition. For example, PSTricks +uses the \N\multido> to put numbers on axes, much like in the following +\LaTeX> example: + PSTricks uses "\multdo" internally to put numbers on axes, much like in this +\LaTeX> example: +\begin{verbatim}> +\setlength{\unitlength}{1cm} +\small +\begin{picture}(8,1)(0,-.5) +\put(0,0){\vector(1,0){8}} +\multido{\i=0+1,\n=0+0.25}{8}{% + \put(\i,-.1){\line(0,1){.2}} + \put(\i,-.2){\makebox[t](0,0){\n}}} +\end{picture} +\end{verbatim} +\begin{center}\leavevmode +\setlength{\unitlength}{1cm} +\small +\begin{picture}(8,1)(0,-.5) +\put(0,0){\vector(1,0){8}} +\multido{\i=0+1,\n=0+0.25}{8}{% + \put(\i,-.1){\line(0,1){.2}} + \put(\i,-.2){\makebox(0,0)[t]{\n}}} +\end{picture} +\end{center} + +The general syntax for \N\multido> is: +\begin{Ex} +"\multido"\M{variables}\M{repetitions}\M{stuff} +\end{Ex} + \m{stuff} is whatever you want repeated; it can be any balanced \TeX{} input. +\m{repetitions} is the number times \m{stuff} is repeated. + + The first argument is the interesting one. \m{variables} is a comma-separated +list of variable declarations.\footnote{Don't use commas to mark the decimal +point within the \protect\m{variables} argument, as they will be confused for +delimiters.} Each variable declaration is of the form: +\begin{center}\em + variable "=" initial value "+" increment +\end{center} + \m{variable} is a command sequence that can be used in \m{stuff}. It is +initially set to {\em initial value}, and is then incremented by {\em +increment} with each repetition. + + The first letter of the variable name determines the variable type. There are +four variable types: +\begin{description} + \item[Dimension (d or D)] The initial value and the increment should be +dimensions (lengths, in \LaTeX> parlance). The substitution text is a +dimension, with "sp" units. E.g., "\dx=4cm+5pt". + + \item[Number (n or N)] The initial value and increment should be integers or +numbers with the same number of digits to the right of the decimal. The one +exception is that it is always OK for the initial value to be an integer. +There can be at most 8 digits on each side of the decimal. The substitution +text is a number, with fixed-point addition. E.g., "\n=3+7.05", +"\Nx=5.30+-1.25". + + \item[Integer (i or I)] The initial value and increment should be integers. +This gives the same result as using a number variable, but it is faster. E.g., +"\I=2+-1". + + \item[Real (r or R)] The initial value and increment should be integers or +numbers with at most 4 digits on each side of the decimal. The substitution +text is a number, but with floating point addition and occasional small +errors. This gives a less satisfactory result than using a number variable, +but it is faster. E.g., "\ry=4.2+1.05". +\end{description} + + Here are some examples that illustrate how the substitution text is +determined: +\begin{quote} +"\multido{}{10}{\TeX\ }"\\[3pt] +\hbox to 2em{}\multido{}{10}{\TeX\ }{}\\[8pt] +"\multido{\d=2pt+3pt}{5}{\d, }"\\[3pt] +\hbox to 2em{}\multido{\d=2pt+3pt}{5}{\d, }{}\\[8pt] +"\multido{\n=2+3}{10}{\n, }"\\[3pt] +\hbox to 2em{}\multido{\n=2+3}{10}{\n, }{}\\[8pt] +"\multido{\i=2+3}{10}{\i, }"\\[3pt] +\hbox to 2em{}\multido{\i=2+-3}{10}{\i, }{}\\[8pt] +"\multido{\r=2+3.05}{6}{\r, }"\\[3pt] +\hbox to 2em{}\multido{\r=2+3.05}{6}{\r, }{}\\[8pt] +"\multido{\n=2.00+3.05}{8}{\n, }"\\[3pt] +\hbox to 2em{}\multido{\n=2.00+-3.05}{8}{\n, }{} +\end{quote} + +Here are some details about the choice of names: +\begin{itemize} + \item Your computer won't explode if you use names that conflict with \TeX> +internal commands, but you might want to check name conflicts if you get +inexplicable errors. The command "\MultidoCheckNames" can be useful in this +case. It causes \N\multido> to report an error whenever you use a variable +name that is already defined. But see the next item. + \item The whole \N\multido> loop is grouped. This means, e.g., that although +"\i" is a Plain \TeX{} command sequence (giving a dotless ``\i''), you can use +the variable "\i" if you do not use any dotless i's in \m{stuff} (and if you +do not use "\MultidoCheckNames"). +\end{itemize} + +Here are a few more details: +\begin{itemize} +\item \N\Multido> commands can be nested. + \item Spaces after a \N\multido> command are ignored. This makes \N\multido> +more hospitable for pictures. + \item Spaces between the various parts of the \m{variables} argument are +ignored. +\end{itemize} + + And finally here a few special features, some of which are of interest mainly +macro writers and other \TeX nicians: +\begin{itemize} + \item The material that is repeated is not grouped, so that you can insert +your own recursive routines. + \item There is a variant, "\mmultido", which works just like "\multido" +except that the variables are all incremented once before starting. + \item There are variants, "\Multido" and "\MMultido" of "\multido" and +"\mmultido", resp., that do not group the whole loop. This can be useful, +e.g., for making entries in an alignment environment. However, these cannot be +nested within any "\multido" macro. + \item If the number of repetitions is a negative number, the variables are +incremented backwards. + \item The count register "\multidocount" keeps track of the number of the +iterations. + \item The command "\multidostop" causes the "\multido" loop to quit at the +end of the current iteration. +\item Fixed point addition is performed by \N\FPadd> and \N\FPsub: +\begin{Ex} +"\FPadd"\M{num1}\M{num2}\M{cs}\\ +"\FPsub"\M{num1}\M{num2}\M{cs} +\end{Ex} + \m{num2}\/ is added to or subtracted from \m{num1}, and the answers is stored +in the command sequence given as the third argument. The rules about decimals +and so on that apply to number variables apply here as well. E.g., after +\begin{Ex} + "\FPsub{1.75}{-0.15}{\answer}" +\end{Ex} +the definition of "\answer" is 1.90. +\end{itemize} + +\clearpage + +%%%%%%%%%%%%%%%%%% STOP HERE IF DOC.STY NOT INPUT%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%% +\StopEventually{} +%% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +%%%%%%%%%%%%%%%%%% BEGIN CODE-SPECIFIC PREAMBLE %%%%%%%%%%%%%%%%%%%%%%%%%%%% +%% +\catcode`\@=11 +%% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +%%%%%%%%%%%%%%%%%% CHANGE TO MACRO ENVIRONMENTS %%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%% +%% A change to the doc.sty's macro environment. +%% Prints macro names like subsections, instead of as marginal notes. +%% Argument is comma separated list of macro names. +%% No nested macro environments. +%% +%% WHY: Don't need as many \begin{macro} ... \end{macro}. +%% Works even there isn't anything between \begin{macro} and +%% \begin{macrocode}. +%% +\newif\iffirst@macroname +\newif\ifnestedmacro +\def\macro{% + \ifnum\macro@level=\z@ + \def\next{\MakePrivateLetters \m@cro@}% + \else + \def\next{\@latexerr{Nested \string\begin{macro}}\@eha + \endgroup\end{macro}\macro@level=\z@\begin{macro}} + \fi + \next} +\def\m@cro@#1{% + \first@macronametrue + \m@@cro@@#1,\@nil,} +\def\m@@cro@@#1,{% + \def\@tempa{#1}\def\@tempb{\@nil}% + \ifx\@tempa\@tempb + \let\next\finishm@@cro@@ + \else + {\advance\c@CodelineNo\@ne\SpecialMainIndex{#1}\nobreak}% + \DoNotIndex{#1}% + \iffirst@macroname + \edef\saved@macronames{\string#1}% + \first@macronamefalse + \else + \def\comma{\noexpand\comma}% + \edef\saved@macronames{\saved@macronames\comma\string#1}% + \fi + \let\next\m@@cro@@ + \fi + \next} +\def\finishm@@cro@@{% + \advance\macro@level\@ne + \def\comma{{\rm, }}% + \subsection*{\tt\saved@macronames}} +%% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +%%%%%%%%%%%%%%%%%%%%%%% DO NOT INDEX %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%% +\DoNotIndex{\ ,\!,\[,\\,\],\^,\`,\{,\},\~} +\DoNotIndex{\@ifundefined,\@namedef,\@spaces,\@tempa,\@tempb} +\DoNotIndex{\@warning,\active} +\DoNotIndex{\begingroup,\catcode,\char,\csname,\def,\do} +\DoNotIndex{\docdate,\dospecials,\edef,\else,\endcsname,\endgroup} +\DoNotIndex{\expandafter,\fi,\filedate,\fileversion} +\DoNotIndex{\gdef,\if,\ifcat} +\DoNotIndex{\ifx,\immediate,\lccode,\let} +\DoNotIndex{\lowercase,\next,\noexpand} +\DoNotIndex{\relax,\space,\the} +\DoNotIndex{\toks@,\count@,\dimen@,\dimen@ii} +\DoNotIndex{\theatcode,\string,\t,\@empty,\@nil,\@nnil,\advance} +\DoNotIndex{\dimen@i,\@,\endinput,\errhelp,\errmessage,\global,ifnum} +\DoNotIndex{\p,\number,\newtoks,\ignorespaces,\message,\multido@temp} +\DoNotIndex{\newcount,\xdef,\z@,\@ne,\tw@,\number,\undefined,\ifnum} +%% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +%%%%%%%%%%%%%%%%%%%% OTHER DOC PARAMETERS %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%% +\setcounter{IndexColumns}{2} % two column index; + +%\DisableCrossrefs +\EnableCrossrefs + + \IndexPrologue{This index is only for the documented code. Underlined numbers +refer roughly to the line number of the entry's definition, and all others +indicate code lines where it is used.} +%% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +%%%%%%%%%%%%%%%%%%%% END CODE-SPECIFIC PREAMBLE %%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%% +\catcode`\@=12 +%% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\section{Documented code} + +\DocInput{multido.doc} + +\clearpage + +\PrintIndex + +\end{document} |