Debian Codegraph @

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

raw
1 % File: mfpic-doc.tex
2 % A part of mfpic 1.10 2012/12/03
3 %
4 % Documentation of mfpic macros
5 \documentclass[letterpaper]{article}
6
7 % Fonts:
8 % Body text: TimesRoman,
9 % Titles: CM Sans serif,
10 % Typewriter: LuxiMono.
11 \usepackage[T1]{fontenc}
12 \usepackage{mathptmx}
13 \usepackage[scaled]{luximono}
14 \renewcommand\sfdefault{cmss}
15 % Fake chapters (really sections):
16 \usepackage[chapters]{mfpdoc}
17 \pagestyle{mfpdoc}
18
19 \newcommand\sgn{\mathop{\mathrm{sgn}}\nolimits}
20
21 \usepackage{makeidx}
22 \makeindex
23
24 \usepackage{graphics}
25
26 \ifpdf
27 \expandafter\usepackage\expandafter
28 [\mfpHyOpts,pdfpagelabels=true,hyperindex]{hyperref}
29 \expandafter\pdfstringdefDisableCommands\expandafter
30 {\mfpHyDisable}
31 \fi
32
33 \stepcounter{secnumdepth}
34
35 \title{\Mfp{}: Pictures in \TeX{}\\ with Metafont and
36 MetaPost\thanks{Copywrite 2002--2012, Daniel H. Luecking}}
37
38
39 \author{%
40 Daniel H. Luecking%
41 \thanks{\email {[email protected]}: Communications regarding \mfp{}
42 should be sent to this author. Any first-person references in this
43 manual refer to Dr.~Luecking.}
44 \and Thomas E. Leathrum
45 \and Geoffrey Tobin}
46
47 \date{\mfpfiledate}
48
49 \begin{document}
50
51 \pagenumbering{roman}
52 \maketitle
53 \tableofcontents
54
55 \clearpage
56 \pagenumbering{arabic}
57
58 \chapter{Introduction}\label{introduction}
59 \thispagestyle{plain}
60
61
62 \section{Why?}\label{why}
63
64 Tom got the idea for \mfp{}%
65 \footnote{`\Mfp{}' is pronounced by spelling the first two letters:
66 `em-eff-pick'.}
67 mostly out of a feeling of frustration. Different output mechanisms for
68 printing or viewing \TeX{} DVI files each have their own ways to include
69 pictures. More often than not, there are provisions for including
70 graphic objects into a \prog{DVI} file using \TeX{} \cs{special}'s.
71 However, this technique seemed far from \TeX{}'s ideal of device
72 independence because different \TeX{} output drivers recognize different
73 \cs{special's}, and handle them in different ways.
74
75 \LaTeX{}'s \env{picture} environment has a hopelessly limited supply of
76 available objects to draw---if you want to draw a graph of a polynomial
77 curve, you're out of luck.
78
79 There was, of course, \PiCTeX{}, which was wonderfully flexible and
80 general, but its most obvious feature was its speed---or rather lack of
81 it. Processing a single picture in \PiCTeX{} (in those days) could often
82 take several seconds.
83
84 It occurred to Tom that it might be possible to take advantage of the
85 fact that \MF{} is \emph{designed} for drawing things. The result of
86 pursuing this idea was \mfp{}, a set of macros for \TeX{} and
87 \MF{} which incorporate \MF{}-drawn pictures into a \TeX{} file.
88
89 With the creation of \MP{} by John Hobby, and the almost universal
90 availability of free \PS{} interpreters like \GS, some \mfp{} users
91 wanted to run their \mfp{} output through \MP{}, to produce \PS{}
92 pictures. Moreover, users wanted to be able to use \pdfTeX{}, which did
93 not get along well with PK fonts, but was quite happy with \MP{}
94 pictures. So \MP{} support was added to \mfp{}. This got us a little bit
95 away from device independence, but many users were not much concerned
96 with that: they just wanted a convenient way to have text and pictures
97 described in the same document file.
98
99 With the extra capabilities of \PS{} (e.g., color) and the corresponding
100 abilities of \MP{}, there was a demand for some \mfp{} interface to
101 access them. Consequently, switches (options) have been added to access
102 some of them. When these are used, output files may no longer be
103 compatible with \MF{}.
104
105
106 \section{Who?}\label{author}
107
108 The original \mfp{} (and still the core of the current version) was written
109 primarily by Tom Leathrum during the late (northern hemisphere) spring
110 and summer of 1992, while at Dartmouth College. Different versions were
111 being written and tested for nearly two years after that, during which
112 time Tom finished his Ph.D. and took a job at Berry College, in Rome,
113 GA. Between fall of 1992 and fall of 1993, much of the development was
114 carried out by others. Those who helped most in this process are
115 credited in the Acknowledgements.
116
117 Somewhere in the mid 1990's the development passed to Geoffrey Tobin who
118 kept things going for several years.
119
120 The addition of \MP{} support was carried out by Dan Luecking around
121 1997--99. He is also responsible for all other additions and changes
122 since then, with help from Geoffrey and a few others mentioned in the
123 Acknowledgements.
124
125
126 \section{What?}\label{manifest}
127
128 See the \file{README} file for a list of files in the distribution and a
129 brief explanation of each. Only three are actually needed for full access
130 to \mfp{}'s capabilities: \file{mfpic.dtx}, \file{mfpic.ins} and
131 \file{grafbase.dtx}. Running \LaTeX{} on
132 \file{mfpic.ins} creates the only required files:
133 \begin{display}
134 \file{mfpic.tex} and \file{mfpic.sty}, the latter required only for
135 \LaTeX{}.\\
136 \file{grafbase.mf}, required only if \MF{} will be processing
137 figures.\\
138 \file{grafbase.mp}, \file{dvipsnam.mp} and \file{mfpicdef.tex}, needed
139 only if \MP{} will be the processor.
140 \end{display}
141 The README file also gives some guidence on the proper location for the
142 installation of these files.
143
144
145 \section{How?}\label{process}
146
147 Some guidance on writing files that contain \mfp{} figures can be found
148 in the accompanying file \file{mfpguide.pdf}. If you use \mfp{} to
149 produce \MP{} figures the process is straightforward: run \TeX{} (or
150 \LaTeX), then \MP{}, then \TeX{} again. If there are no errors, then
151 \prog{dvips} or other DVI-to-PS converter can be run to produce
152 viewable\slash printable output. You can also run \prog{dvipdfm(x)} to obtain PDF
153 output, or even use \pdfTeX{} instead of \TeX{} (or \pdfLaTeX{} instead
154 of \LaTeX{}) to get PDF output directly.
155
156 Here is an example of the process: for the sample file
157 \file{pictures.tex}, first run \TeX{} on it (or run \LaTeX{} on
158 \file{lapictures.tex}). You may see a message from \mfp{} that there is
159 no file \file{pics.1}, but \TeX{} will continue processing the file
160 anyway. When \TeX{} is finished, you will now have a file called
161 \file{pics.mp}. This is the \MP{} file containing the descriptions of
162 the pictures for \file{pictures.tex}. You need to run \MP{} on
163 \file{pics.mp} (Read your \MP{} manual to see how to do
164 this.%
165 \footnote{The document \textit{Some experiences on running Metafont
166 and MetaPost}, by Peter Wilson, can be useful for beginners. Fetch
167 \file{CTAN/info/metafp.pdf}. `\file{CTAN}' means the Comprehensive
168 \TeX{} Archive Network. You can find the mirror nearest you by
169 pointing your browser at \url{http://www.ctan.org/}\,.}) %
170 Typically, you just type
171 \begin{verbatim}
172 mpost pics.mp
173 \end{verbatim}
174
175 This usually produces files named%
176 \footnote{Recent \MP{} allows one to change the default names of the
177 output files. Current \mfp{} provides an interface to that
178 capability: see \cs{setfilenametemplate} on page
179 \pageref{setfilenametemplate}.}
180 \file{pics.1}, \file{pics.2}, etc., the number of files depending on the
181 version of \file{pictures.tex}. You then reprocess \file{pictures.tex}
182 with \TeX{} to produce a DVI file. This file can then be processed with
183 \prog{dvips} (for example) to produce \PS{} output which can be printed
184 or viewed. One can also process the DVI with \prog{dvipdfm(x)} to
185 produce a PDF file.
186
187 If \pdfTeX{} is used instead of \TeX{} on the second run, you should be
188 able to view the resulting PDF file immediately, without any further
189 processing.
190
191 If instead you use \mfp{} to produce \MF{} figures, things are a little
192 less straightforward. The process is \TeX{}, then \MF{}, then
193 \prog{gftopk}, then \TeX{} again. After this, \TeX{}'s DVI output ought
194 to be viewable and printable by most DVI viewers or printer drivers. For
195 a few \TeX{} systems there may be some prior setup needed. One needs to
196 convince \TeX{} and its output drivers to find \MF{}'s output files. You
197 should do whatever is necessary (perhaps nothing!) to insure that \TeX{}
198 looks in the current directory for \file{.tfm} files, and that your DVI
199 drivers look in the current directory for \file{.pk} files. There may
200 also be some setup needed to ensure that the \file{.pk} files are
201 created at a resolution that matches that of your printer and of your
202 DVI viewer. See the discussion in \file{mfpguide.pdf}.
203
204 If you want to test this process on the supplied sample files, edit
205 \file{pictures.tex} removing the \cs{usemetapost} command (or edit
206 \file{lapictures.tex}, removing the \opt{metapost} option). After that,
207 run \TeX{} on \file{pictures.tex} (or run \LaTeX{} on
208 \file{lapictures.tex}). You may see a message from \mfp{} that there is
209 no file \file{pics.tfm}, but \TeX{} will continue processing the file.
210 When \TeX{} is finished, you will now have a file called \file{pics.mf}.
211 This is the \MF{} file containing the descriptions of the pictures for
212 \file{pictures.tex}. You need to run \MF{} on \file{pics.mf}, with
213 \texttt{mode:=localfont} set up.
214 (Read your \MF{} manual to see how to do this.%
215 \footnote{If you are new to running \MF{}, the document
216 \textit{Metafont for Beginners}, by Geoffrey~Tobin, is a good
217 start. Fetch \file{CTAN/info/metafont-for-beginners.tex}.}) %
218 Typically, you just type
219 \begin{verbatim}
220 mf pics.mf
221 \end{verbatim}
222 or, to use a particular printer mode such as \texttt{ljfour}, possibly
223 something like
224 \begin{verbatim}
225 mf '\mode:=ljfour; input pics.mf'
226 \end{verbatim}
227 This produces a \file{pics.tfm} file and a GF file with a name something
228 like \file{pics.600gf}. The actual number may be different and the
229 extension may get truncated on some file systems. Then you run
230 \prog{gftopk} on the GF file to produce a PK font file. (Read your
231 \prog{gftopk} manual on how to do this.) Typically, you just run
232 \begin{verbatim}
233 gftopk pics.600gf
234 \end{verbatim}
235 (or possibly ``\verb$gftopk pics.600gf pics.600pk$'' or
236 ``\verb$gftopk pics.600gf pics.pk$'').
237
238 Now that you have the font (the \file{.pk} file) and font metric file (the
239 \file{.tfm}) generated by \MF{}, reprocess the file \file{pictures.tex}
240 with \TeX{}. The resulting DVI file should now be complete, and you should
241 be able to print and view it at your computer (assuming your viewer and
242 print driver have been set up to be able to find the PK font generated
243 from \file{pics.mf}).
244
245 It is not advisable to rely on automatic font generation to create the
246 \file{.tfm} and \file{.pk} files. (Different systems do this in
247 different ways, so here I will try to give a generic explanation.) The
248 reason: later editing of a figure will require new files to be built,
249 and most automatic systems will \emph{not} remake the files once they
250 have been created. This is not so much a problem with the \file{.tfm},
251 because \mfp{} never tries to load the font if the \file{.tfm} is absent
252 and therefore no automatic \file{.tfm}-making should ever be triggered.
253 However, if you forget to run \prog{gftopk}, then try to view your
254 resulting file, you may have to search your system and delete some
255 automatically generated \file{.pk} file (they can turn up in far-away
256 places) before you can see any later changes. It might be wise to write
257 a shell script (batch file) that runs both \MF{} and \prog{gftopk}. It
258 should also do some error checking and delete the \file{.tfm} if the
259 \file{.pk} file is not produced. That way, if anything goes wrong, the
260 \file{.dvi} will not contain the font (\mfp{} will draw a rectangle and
261 the figure number in place of the figure).
262
263 These processing steps---processing with \TeX{}, processing with
264 \MF{}\slash\prog{gftopk} or \MP{}, and reprocessing with \TeX{}---may not always be
265 necessary. In particular, if you change the \TeX{} document without
266 making any changes at all to the pictures, then there will be no need to
267 repeat the \MF{} or \MP{} steps.
268
269 There are also somewhat subtle circumstance under which you can skip the
270 second \TeX{} step after editing a figure if the file has already gone
271 through the above process. Delineating the exact cirumstances is rather
272 involved, so it is recommended that you always repeat the \TeX{} step if
273 you have made changes that affect any figure.
274
275 What makes \mfp{} work? When you run \TeX{} on the file
276 \file{pictures.tex}, the \mfp{} macros issue \TeX{} \cs{write} commands,
277 writing \MF{} (or \MP{}) commands to a file \file{pics.mf} (or
278 \file{pics.mp}). The user should never have to read or change the file
279 \file{pics.mf} directly---the \mfp{} macros take care of it.
280
281 The enterprising user can determine by examining the \mfp{} source and
282 the resulting \file{.mf} or \file{.mp} file, that \mfp{} drawing macros
283 translate almost directly into similar \MF{}\slash\MP{} commands,
284 defined in one of the files \file{grafbase.mf} or \file{grafbase.mp}.
285 The labels and captions, however, are placed on the graph by \TeX{}
286 using box placement techniques similar to those used in \LaTeX{}'s
287 \env{picture} environment (except when option \opt{mplabels} is in
288 effect, in which case the labels are written to the \file{.mp} file and
289 handled by \MP{}).
290
291 \smallskip
292 \emph{Note}: In this manual, when describing \mfp{} operations, we will
293 often refer to `\MF{}' when we really mean ``\MF{} or \MP{}''. This
294 will especially be the case whenever we need to refer to commands in the
295 two languages which are substantially the same, but occasionally we will
296 even talk about ``running \MF{}'' when we mean running one or the other
297 program \texttt{mf} or \texttt{mpost} to process the figures. If we need
298 to discriminate between the two processors, (for example when they have
299 different behavior) we will make the difference explicit.
300
301 A similar shorthand is used when referring to `\TeX{}'. It should not be
302 taken to mean ``plain \TeX{}'', but rather whatever version of \TeX{} is used
303 to process the source file: plain \TeX{}, \LaTeX{}, \pdfTeX{}, or
304 \pdfLaTeX{}. Also \AmSTeX{}, \prog{eplain} and some other variants. When
305 last tried, \mfp{} didn't work with \ConTeXt{}.
306
307 \clearpage
308 \chapter{Options.}\label{options}
309
310 There are several options to the \mfp{} package. These options can be
311 turned on with certain provided commands, but under \LaTeX{} they can
312 also be used in the standard \LaTeX{} \cs{usepackage} optional argument.
313 Some options can be switched off and on throughout the document. Here we
314 merely list them and provide a general description of their purpose.
315 More details may be found later in the discussion of the features
316 affected. The headings below give the option name, the alternative macro
317 and, if available, the command for turning off the option. Any option
318 in the \cs{usepackage} command not among those given below will be
319 passed on to the \prog{graphics} package, provided the \opt{metapost}
320 option has been used.
321
322 If the file \file{mfpic.cfg} exists, it will be input just before all
323 options are processed. You can create such a file containing an
324 \cs{ExecuteOptions} command to execute any options you would like to
325 have as default. Actual options to \cs{usepackage} will override these
326 defaults, of course. And so will any of the commands below.
327
328 Finally, if a file named \file{mfpic.usr} can be found, it will be input
329 at the end of the loading of \mfp{}. The user can create such a file
330 containing any of the commands of this section that he would like to
331 have as default, plus any other \TeX{} code.
332
333
334 \section{\opt{metapost}, \opt{metafont}, \cs{usemetapost}, \cs{usemetafont}.}%
335 \label{metapost}\index{metapost@\opt{metapost}}\index{usemetapost@\cs{usemetapost}}%
336 \index{metafont@\opt{metafont}}\index{usemetafont@\cs{usemetafont}}
337
338 The option \opt{metapost} or the command \cs{usemetapost} selects \MP{}
339 as the figure processor and makes specific features available. It
340 changes the extension used on the output file to `\file{.mp}' to signal
341 that it can no longer be processed with \MF{}. There is also a
342 \opt{metafont} option (command \cs{usemetafont}), but it is redundant,
343 as \MF{} is the default (for backward compatibility of files written
344 before \MP{} existed). Either command must come before the
345 \cs{opengraphsfile} command (see section~\ref{files}). They should not
346 be used together in the same document. (Actually they can, but one needs
347 to close one output file and open another. Moreover, it hasn't ever been
348 seriously tested, and it wasn't taken into consideration in writing most
349 of the macros.) If the command form \cs{usemetapost} is used in a
350 \LaTeXe{} document, it must come in the preamble. Because of the timing
351 of actions by the \prog{babel} package and by older versions of
352 \file{supp-pdf.tex} (input by \file{pdftex.def} in the \prog{graphics}
353 package), when \pdfLaTeX{} is used, \mfp{} should be loaded and
354 \cs{usemetapost} (if used) declared before \prog{babel} is loaded.
355
356
357 \section{\opt{mplabels}, \cs{usemplabels},
358 \cs{nomplabels}.}\label{mplabels}
359 \index{mplabels@\opt{mplabels}}%
360 \index{usemplabels@\cs{usemplabels}}%
361 \index{nomplabels@\cs{nomplabels}}
362
363 Causes all label creation commands to write their contents to the output
364 file. It effects only labels on the figure, not a caption added by the
365 \cs{tcaption} command (see section~\ref{text}). In this case labels are
366 handled by \MP{} and can be rotated. It requires \MP{}, and will be be
367 ignored without it (\MF{} cannot handle labels). Using this option
368 without the \opt{metapost} option may also produce an error message
369 either from \TeX{} or \MF{}. The command forms can be placed anywhere.
370 If used outside an mfpic environment, they affect all subsequent
371 \cs{tlabel} commands; inside an mfpic environment they affect all
372 \cs{tlabel} commands in that figure.
373
374 When this is in effect, the labels become part of the figure and, in the
375 default handling, they may be clipped off or covered up by later drawing
376 elements. But see the next section on the \opt{overlaylabels} option.
377 Labels added to a picture contribute to the bounding box even if
378 \opt{truebbox} is not in effect.
379
380 The user is responsible for adding the appropriate \mfc{verbatimtex}
381 header to the output file if necessary. For this purpose, there is the
382 \cs{mfpverbtex} command, see section~\ref{labels}. If the label text
383 contains only valid plain \TeX{} macros, there is generally no need for
384 a \mfc{verbatimtex} preamble at all. If you add a \mfc{verbatimtex}
385 preamble of \LaTeX{} code take care to make sure \MP{} calls \LaTeX{}
386 (for example, the \texttt{mpost} command may take an option for this
387 purpose, or an environmental variable named \texttt{TEX} may be set
388 equal to \texttt{latex} in the command shell of your operating system.).
389
390
391 \section{\opt{overlaylabels}, \cs{overlaylabels}, \cs{nooverlaylabels}.}
392 \label{overlaylabels}
393 \index{overlaylabels@\opt{overlaylabels}}%
394 \index{overlaylabels@\cs{overlaylabels}}%
395 \index{nooverlaylabels@\cs{nooverlaylabels}}
396
397 In the past, under \opt{mplabels} all text labels created by \cs{tlabel}
398 and its relatives were added to the picture by \MP{} \emph{as they
399 occurred}. This made them subject to later drawing commands: they could
400 be covered up, erased, or clipped. With this option (or after the
401 command \cs{overlaylabels}) text labels are saved in a separate place
402 from the rest of a picture. When a picture is completed, the labels that
403 were saved are added on top of it. This is the way labels always behave
404 under the \opt{metafont} option, because then \TeX{} must add the labels
405 and there is no possibility for special effects involving clipping or
406 erasing (at the \MF{} level).
407
408 With the \opt{metapost} option, but without \opt{mplabels} it has been
409 decided to keep the same behavior (and the same code) as under the
410 \opt{metafont} option. However, when \opt{mplabels} is used, there is
411 the possibility for special effects with text, and it has always been
412 the behavior before version 0.7 to simply place the labels as they
413 occurred. It turns out that placing the labels at the end is cleaner and
414 simpler to code, so I experimented with it and rejected it as a default,
415 but now offer it as an option. With this option, \mfp{} labels have
416 almost the same behavior with or without \opt{mplabels}.
417
418 The commands may be used anywhere. Outside a figure they affect all
419 subsequent figures, inside a figure they affect all subsequent text in
420 that figure. The commands and option are ignored under the metafont
421 option.
422
423
424 \section{\opt{truebbox}, \cs{usetruebbox}, \cs{notruebbox}.}%
425 \label{truebbox}%
426 \index{truebbox@\opt{truebbox}}%
427 \index{usetruebbox@\cs{usetruebbox}}%
428 \index{notruebbox@\cs{notruebbox}}
429
430 Normally \MP{} outputs an EPS file with the actual bounding box of the
431 figure. By default, \mfp{} \emph{overrides} this and sets the bounding
432 box to the dimensions specified by the \cs{mfpic} command that produced
433 it. (This used to be needed for \TeX{} is to handle \cs{tlabel} commands
434 correctly. Now, it is just for backward compatability, and for
435 compatability with \MF{}'s behavior.) It is reasonable to let \MP{} have
436 its way, and that is what this option does. If one of the command forms
437 is used in an \env{mfpic} environment, it affects only that environment,
438 otherwise it affects all subsequent figures. This option currently has
439 no effect with \MF{}, but should cause no errors.
440
441 This option is almost mandatory if you wish to use \prog{dvipdfm(x)} to
442 convert \TeX{}'s DVI output to PDF. Both \prog{dvipdfm} and
443 \prog{dvipdfmx} have a tendency to clip \MP{} figures to the stated
444 bounding box. Thus, anything running outside those bounds is lost.
445
446
447 \section{\opt{clip}, \cs{clipmfpic}, \cs{noclipmfpic}.}\label{clip}
448 \index{clip@\opt{clip}}%
449 \index{clipmfpic@\cs{clipmfpic}}%
450 \index{noclipmfpic@\cs{noclipmfpic}}
451
452 The \opt{clip} option causes all parts of the figure outside the
453 rectangle specified by the \cs{mfpic} command to be removed. The
454 commands can come anywhere. If issued inside an \env{mfpic} environment
455 they affect the current figure only. Otherwise all subsequent figures
456 are affected. Note: this is a rather rudimentary option. It has an often
457 unexpected interaction with truebbox. When both are in effect, \MP{}
458 will produce a bounding box that is the intersection of two rectangles:
459 the true one \emph{without clipping}, and the clipping rectangle (i.e.,
460 the one specified in the \cs{mfpic} command). It is possible for the
461 actual figure to be much smaller than this bounding box (even empty!).
462 This is a property of the \MP{} \gbc{clip} command and we know of no way
463 to avoid it.
464
465
466 \section{\opt{centeredcaptions}, \cs{usecenteredcaptions},
467 \cs{nocenteredcaptions}.}\label{centeredcaptions}
468 \index{centeredcaptions@\opt{centeredcaptions}}%
469 \index{usecenteredcaptions@\cs{usecenteredcaptions}}%
470 \index{nocenteredcaptions@\cs{nocenteredcaptions}}
471
472 The \opt{centeredcaptions} option causes multiline captions created by
473 \cs{tcaption} to have all lines centered. This has no effect on the
474 normal \LaTeX{} \cs{caption} command.%
475 \footnote{This writer [DHL] feels that \cs{tcaption} is too limited
476 and users ought to apply the caption by other means, such as
477 \LaTeX{}'s \cs{caption} command, outside the \env{mfpic}
478 environment.}%
479
480 The commands can be issued anywhere. If inside an \env{mfpic}
481 environment they should come before the \cs{tcaption} command and affect
482 only it, otherwise they affect all subsequent figures. They should not
483 be used in the argument of a \cs{tcaption} command.
484
485
486 \section{\opt{raggedcaptions}, \cs{useraggedcaptions},
487 \cs{noraggedcaptions}.}\label{raggedcaptions}
488 \index{raggedcaptions@\opt{raggedcaptions}}%
489 \index{useraggedcaptions@\cs{useraggedcaptions}}%
490 \index{noraggedcaptions@\cs{noraggedcaptions}}
491
492 The \opt{raggedcaptions} option causes multiline captions created by
493 \cs{tcaption} to have all lines ragged\-right. If \opt{centeredcaptions}
494 is on, both sides will be ragged. This option can be turned off with the
495 command \cs{noraggedcaptions}. This is the default: to have all lines
496 except the last justified. The last line is either centered or flush
497 left according to whether \opt{centeredcaptions} is on or off.
498
499 The commands can be issued anywhere. If inside an \env{mfpic}
500 environment they should come before the \cs{tcaption} command and affect
501 only it, otherwise they affect all subsequent figures. They should not
502 be used in the argument of a \cs{tcaption} command.
503
504
505 \section{\opt{debug}, \cs{mfpicdebugtrue},
506 \cs{mfpicdebugfalse}.}\label{debug}
507 \index{debug@\opt{debug}}%
508 \index{mfpicdebugtrue@\cs{mfpicdebugtrue}}%
509 \index{mfpicdebugfalse@\cs{mfpicdebugfalse}}
510
511 The \opt{debug} option causes \mfp{} to write a rather large amount of
512 information to the \file{.log} file and sometimes to the terminal. Debug
513 information generated by \file{mfpic.tex} \emph{while loading} is
514 probably of interest only to developers, but can be turned on by giving
515 a definition to the command \cs{mfpicdebug} prior to loading. Any
516 definition will work because \prog{mfpic} only checks whether it is
517 defined.
518
519
520 \section{\opt{clearsymbols}, \cs{clearsymbols}, \cs{noclearsymbols}.}
521 \index{clearsymbols@\opt{clearsymbols}}%
522 \index{clearsymbols@\cs{clearsymbols}}%
523 \index{noclearsymbols@\cs{noclearsymbols}}
524
525 \Mfp{} has two commands, \cs{point} and \cs{plotsymbol} that place a
526 small symbol at each of a list of points. The first can place either a
527 small filled disk or an open disk, the choice being dictated by the
528 setting of the boolean \cs{pointfilltrue} or \cs{pointfillfalse}. The
529 behavior of \cs{point} in the case of \cs{pointfillfalse} is to erase the
530 interior of the disk in addition to drawing its circumference.
531
532 The second command \cs{plotsymbol} can place a variety of shapes, some
533 open, some not. Its behavior before version 0.7 was to always draw the
534 shape without erasing the interior. Two other commands that placed these
535 symbols, \cs{plotnodes} and \cs{plot}, had the same behavior. With this
536 option, two of these, \cs{plotsymbol} and \cs{plotnodes}, will erase the
537 interior of the open symbols before drawing them. Thus
538 \cs{plotsymbol}\marg{SolidCircle} still works just like
539 \cs{pointfilltrue}\cs{point}, and now with this option
540 \cs{plotsymbol}\marg{Circle} behaves the same as
541 \cs{pointfillfalse}\cs{point}. The \cs{plot} command is unaffected by
542 this option.
543
544
545 \section{\opt{draft}, \opt{final}, \opt{nowrite}, \cs{mfpicdraft},
546 \cs{mfpicfinal}, \cs{mfpicnowrite}.}\label{draft}
547 \index{draft@\opt{draft}}%
548 \index{final@\opt{final}}%
549 \index{nowrite@\opt{nowrite}}%
550 \index{mfpicdraft@\cs{mfpicdraft}}%
551 \index{mfpicfinal@\cs{mfpicfinal}}%
552 \index{mfpicnowrite@\cs{mfpicnowrite}}
553
554 Under the \opt{metapost} option, the various macros that include the
555 \EPS{} files emit rather large amounts of confusing error messages when
556 the files don't exist (especially in \LaTeX{}). For this reason, before
557 each picture is placed, \mfp{} checks for the existence of the graphic
558 before trying to include it. However, on some systems checking for the
559 existence of a nonexistent file can be very slow because the entire
560 \TeX{} search path will need to be checked. Therefore, \mfp{} doesn't
561 even attempt any inclusion on the first run. The first run is detected
562 by the non-existence of \file{\meta{file}.1}, where \meta{file} is the
563 name given in the \cs{opengraphsfile} command (but see also
564 section~\ref{files}). These options can be used to override this
565 automatic detection. All the command versions \emph{should} come before
566 the \cs{opengraphsfile} command. The \cs{mfpicnowrite} command
567 \emph{must} come before it.
568
569 These options might be used if, for example, the first figure has an
570 error and is not created by \MP{}, but you would like \mfp{} to go
571 ahead and include the remaining figures. Then use \opt{final}. It can
572 also be used to override a \LaTeX{} global \opt{draft} option. Or if
573 \file{\meta{file}.1} exists, but other figures still have errors and you
574 would like several runs to be treated as first runs until \MP{} has
575 stopped issuing error messages, then use \opt{draft}. These commands
576 also work under the \opt{metafont} option, but time and error messages
577 are less of an issue then. If all the figures have been created and
578 debugged, some time might be saved (with either \opt{metafont} or
579 \opt{metapost}) by not writing the output file again, then \opt{nowrite}
580 can be used.
581
582
583 \section{\opt{mfpreadlog}, \cs{mfpreadlog}.}\label{readlog}
584 \index{mfpreadlog@\opt{mfpreadlog}}%
585 \index{mfpreadlog@\cs{mfpreadlog}}
586
587 From version 0.8, there exists a scheme to allow \MF{} or \MP{} to pass
588 information back to the \file{.tex} file. This is done by writing code
589 to the figure file requesting \MF{} to place that information in the
590 \file{.log} file it produces. This option instructs \mfp{} to read
591 through that log file line-by-line looking for such information. Since
592 such log files can be potentially quite lengthy, this is made an option.
593 If the command form \cs{mfpreadlog} is used, it must come before the
594 \cs{opengraphsfile} command, since that is when the file will be
595 examined. At the present time, the only \mfp{} facility that requires
596 this two-way communication is \cs{assignmfvalue} (see
597 subsection~\ref{misc}). If this is used, the filename given to
598 \cs{opengraphsfile} should not be the same as the \TeX{} source file in
599 which this occurs, as then the wrong \file{.log} may be read.
600
601
602 \section{Scoping Rules.}\label{scoping}
603
604 Some of these options merely change \TeX{} behavior, others write
605 information to the output file for \MF{} or \MP{}. Changes in \TeX{}
606 behavior obey the normal \TeX{} grouping rules, the information written
607 to the output file obeys \MF{} grouping rules. Since each \env{mfpic}
608 environment is both a \TeX{} group and (corresponds to) a \MF{} group,
609 the following always holds: use of one of the command forms inside of an
610 \env{mfpic} environment makes the change local to that environment.
611
612 An effort has been made (as of version 0.7) to make this universal. That
613 is, any of the commands listed above for turning options on and off will
614 be global when issued outside an \env{mfpic} environment. The debug
615 commands are exceptions; they obey all \TeX{} scoping rules.
616
617 We have also tried to make all other \mfp{} commands for changing the
618 various parameters follow this rule: local inside \env{mfpic}
619 environment, global outside. If this is ever untrue, and I don't
620 document that fact, please let me know.
621
622 The following are special:
623 \begin{display}
624 \cs{usemetapost}\index{usemetapost@\cs{usemetapost}},
625 \cs{usemetafont}\index{usemetafont@\cs{usemetafont}},
626 \cs{mfpicdraft}\index{mfpicdraft@\cs{mfpicdraft}},
627 \cs{mfpicfinal}\index{mfpicfinal@\cs{mfpicfinal}},
628 \cs{mfpicnowrite}\index{mfpicnowrite@\cs{mfpicnowrite}},\\
629 and \cs{mfpreadlog}\index{mfpreadlog@\cs{mfpreadlog}}.
630 \end{display}
631 \noindent Their effects are always global, partly because they should
632 occur prior to the initialization command \cs{opengraphsfile} (described
633 in section~\ref{files}). Note that \cs{usemetapost} may cause a file of
634 graphic inclusion macros to be input. If this command is issued inside a
635 group, some definitions in that file may be lost, breaking the graphic
636 inclusion code.
637
638
639 \clearpage
640 \chapter{\CMF{} and \CMP{} Data Types.}\label{types}
641
642 Since the arguments of most \mfp{} drawing commands are sent to \MF{} to
643 be interpreted, it's useful to know something about \MF{} concepts. In
644 this chapter we will discuss some of the data types \MF{} supports.
645 Even the casual user should know how coordinates and colors are treated
646 and so should at least skim the next two sections. The last
647 section can be read when the user wants to manipulate more complex
648 objects.
649
650 \CMF{} permits several different data types, and we will mainly be
651 concerned with six of these: \kw{numeric}, \kw{pair}, \kw{color} (\MP{}
652 only), \kw{path}, \kw{picture} and \kw{boolean}.%
653 \footnote{For the curious, there are a total of eight types (nine or
654 ten for \MP{}). The other three are \kw{string}, \kw{transform} and
655 \kw{pen}. \MF{} also permits expressions that produce nothing, which
656 is sometimes called the vacuous type, but doesn't allow (or need)
657 variables of this type.}
658 In \MP{} version 1.000, a tenth data type was added, \kw{cmykcolor}, and
659 the \kw{color} data type can be referred to as `\kw{rgbcolor}' if one
660 wants to emphasize the distinction.
661
662 A \emph{variable} is a symbolic name, which can be a single letter such
663 as \mfc{A}, or a descriptive name like \mfc{origin}. Any sequence of
664 letters and underscores is permitted as a variable name. Numeric indexes
665 are also allowed, provided all variables that differ only in the index
666 have the same type. Thus \mfc{A1}, \mfc{A2}, etc., might be variables
667 which are all of type \kw{pair}. Quite a lot more is permited for variable
668 names, but the rules are rather complex and easy to violate. \Mfp{} has
669 commands for creating both simple variables and indexed variables
670 (called \emph{arrays}) but the casual user can get quite a lot of use
671 out of \mfp{} without ever creating or using a \MF{} variable.
672
673 \CMF{} also has something akin to functions. For example, \mfc{sin(1.57)}
674 might represent a function named \mfc{sin} receiving the parameter
675 $1.57$ as input and returning the appropriate value. Functions
676 can take any number of parameters and return any of the data types that
677 \MF{} supports.%
678 \footnote{Including the vacuous type.}
679
680
681 \section{Numerics and pairs.}\label{pairs}
682
683 \CMF{} has \kw{numeric} quantities. These include lengths, such as the
684 radius of a circle, as well as dimension units such as \mfc{in} (inches)
685 and \mfc{pt} (points). In fact it understands all the same units that
686 \TeX{} does. These \kw{numeric} quantities can be constants (explicit
687 numbers) or variables (symbolic names). In fact, \mfc{in} and \mfc{pt}
688 are symbolic names for \kw{numeric} quantities.
689
690 \CMF{} also has \kw{pair} objects, which may be constants or variables.
691 Constants of type \kw{pair} have the form \mfc{($x$,$y$)} where $x$ and
692 $y$ are numbers, for example \mfc{(0,0)}. Pairs are two-dimensional
693 quantities used for representing either points or vectors in a
694 rectangular (Cartesian) coordinate system.
695
696 In this manual we often represent each pair by a brief name, such as
697 \meta{p} or \meta{v}, the meanings of which are usually obvious in the
698 context of the macro. These are intended to be replaced in actual use by
699 either a pair constant or variable. The succinctness of this notation
700 helps us to think geometrically rather than only of coordinates.
701
702
703 \section{Colors.}\label{MPcolors}
704
705 \CMP{} has the same concepts as \MF, but also has \kw{color} objects,
706 which may also be constants or variables. In recent MP{}, colors come in
707 two flavors: \kw{rgbcolor} and \kw{cmykcolor}. Constants of type
708 \kw{rgbcolor} have the form \mfc{($r$,$g$,$b$)} where $r$, $g$, and $b$
709 are numbers between $0$ and $1$ determining the relative proportions of
710 red, green and blue in the color (the `rgb' model). Constants of type
711 \kw{cmykcolor} have the form \mfc{($c$,$m$,$y$,$k$)} where $c$, $m$, $y$
712 and $k$ are numbers between $0$ and $1$ determining the relative
713 proportions of cyan, magenta, yellow and black in the color (the `cmyk'
714 model).
715
716 A color variable is a name, like \mfc{red}, \mfc{blue} (both predefined
717 rgb colors in \MP) or \gbc{magenta} (predefined by \mfp{} to be an rgb
718 color if \MP{} has version ${}<1.000$, a cmyk color if the version is at
719 least 1.000).
720
721
722 \section{Paths, pictures and booleans.}\label{paths}
723
724 Most of the things that \mfp{} is designed to draw are paths. Examples
725 of paths are circles, rectangles, other polygons, graphs of
726 functions and splines. Because we tend to want to draw these (or fill
727 them, or render them in other ways) we call the \mfp{} commands that
728 produce them \emph{figure macros}. Although they are much more complex
729 than numerics, pairs, or colors, they can still be stored in symbolic
730 names.
731
732 Normally in \mfp{} we want to create a picture, usually by rendering one
733 or more paths. It is possible in \MF{} to store a picture in a symbolic
734 name without actually drawing it. However, because of their complexity,
735 objects of type \kw{picture} require somewhat more care than paths or
736 other data types. Do not expect to use stored pictures in the same way
737 as stored paths. In fact, one should use \kw{picture} variables only in
738 those command that are explicitly designed for them. In \mfp{} to date
739 these are only \cs{tile...}\cs{endtile} and \cs{mfpimage} to store
740 pictures, and \cs{putmfpimage} to draw copies of one. There is also
741 \cs{tess}, but it is used only to fill a region with copies of a picture
742 created by \cs{tile}.
743
744 The \kw{boolean} data type is one of the values \mfc{true} or
745 \mfc{false}. Variables of type \kw{boolean} are symbolic names that can
746 take either of these two values. Usually these are used to influence the
747 behavior of some command by setting a relevant \kw{boolean} variable to
748 one or the other value.
749
750
751 \clearpage
752 \chapter{The Macros.}\label{macros}
753
754 Many of the commands of \mfp{} have optional arguments. These are
755 denoted just as in \LaTeX{}, with square brackets. Thus, the command for
756 drawing a circle can be given
757 \begin{verbatim}
758 \circle{(0,0),1}
759 \end{verbatim}
760 having only the mandatory argument, or
761 \begin{verbatim}
762 \circle[p]{(0,0),1}
763 \end{verbatim}
764 Whenever an optional argument is omitted, the behavior is equivalent to
765 some choice of the optional argument. In this example, the two forms
766 have exactly the same behavior, drawing a circle centered at $(0,0)$
767 with radius $1$. In this case we will say ``\oarg{p} is the
768 \emph{default}''. Another example is \cs{point}\marg{(1,0)} versus
769 \cs{point}\oarg{3pt}\marg{(1,0)}. They both place a dot at the point
770 $(1,0)$. The second one explicitly requests that it have diameter
771 \dim{3pt}; the first will examine the length command \cs{pointsize},
772 which the user can change, but it is initialized to \dim{2pt}. In this
773 case we will say ``the default is the value of \cs{pointsize},
774 \emph{initially} \dim{2pt}''.
775
776 If an \mfp{} command that takes an optional argument finds only empty
777 brackets (completely empty, no spaces), then it will use the default
778 value. This is useful for commands that have two optional arguments and
779 one wants the default value in the first one and some nondefault value
780 in the second. An optional argument should normally not contain any
781 spaces. Even when the argument contains more than one piece of data,
782 spaces should not separate the parts. In some cases this will cause no
783 harm, but it would be better to avoid doing it altogether, because there
784 are cases where it will cause wrong results or error messages.
785
786
787 \section{Files and Environments.}\label{files}
788
789 \begin{cd}\pagelabel{opengraphsfile}
790 \cs{opengraphsfile}\marg{\meta{file}}\\
791 \ $\ldots$\\
792 \cs{closegraphsfile}%
793 \index{opengraphsfile@\cs{opengraphsfile}}%
794 \index{closegraphsfile@\cs{closegraphsfile}}
795 \end{cd}
796
797 These macros open and close the \MF{} or \MP{} file which will contain
798 the pictures to be included in this document. The name of the file will
799 be \file{\meta{file}.mf} (or \file{\meta{file}.mp}). Do \emph{not}
800 specify the extension, which is added automatically.
801
802 \emph{Note}: This command may cause \file{\meta{file}.mf} or
803 \file{\meta{file}.mp} to be overwritten if it already exists, so be sure
804 to consider that when selecting the name. Repeating the running of
805 \TeX{} will overwrite the file created on previous runs, but that should
806 be harmless. For if no changes are made to \env{mfpic} environments, the
807 identical file will be recreated, and if changes have been made, then
808 you want the file to be replaced with the new version.
809
810 It is possible (but \emph{has not} been seriously tested) to close one
811 file and open another, and even to change between \opt{metapost} and
812 \opt{metafont} in between. If anything goes wrong with this, contact the
813 maintainer and it might be fixed in some later version.
814
815 There may be limitations on what can be used as a filename. As of \mfp{}
816 version 1.00, we have tried to permit \cs{jobname} as part of
817 \meta{file}. Thus we permit \TeX{} macros, but they should expand to
818 non-special characters. Permitting macros makes it essentially
819 impossible for the filename to contain the backslash and brace
820 characters. Also spaces are problematic. However other special \TeX{}
821 characters (for example: tilde, underscore and percent) can be used,
822 though that is not recommended.
823
824 \begin{cd}\pagelabel{mfpic}
825 \cs{mfpic}\oarg{\meta{xfactor}}\oarg{\meta{yfactor}}%
826 \marg{\meta{xmin}}\marg{\meta{xmax}}\marg{\meta{ymin}}\marg{\meta{ymax}}\\
827 \ $\ldots$\\
828 \cs{endmfpic}%
829 \index{mfpic@\cs{mfpic}}%
830 \index{endmfpic@\cs{endmfpic}}
831 \end{cd}
832
833 These macros open and close the \env{mfpic} environment%
834 \footnote{We use the term `environment' loosely. However, in
835 \LaTeX{} one may use an actual \env{mfpic} environment. See
836 page~\pageref{envusage}.}
837 in which the drawing macros make sense. While many \mfp{} commands can
838 be used inside or outside this environment, those that actually produce
839 visible output are required to be inside. The \cs{mfpic} macro also sets
840 up the local coordinate system for the picture. The \meta{xfactor} and
841 \meta{yfactor} parameters establish the length of a coordinate system
842 unit, as a multiple of the \TeX{} dimension \cs{mfpicunit}. If neither
843 is specified, both are taken to be 1 and each coordinate system unit is
844 1 \cs{mfpicunit}. If only one is specified, then they are assumed to be
845 equal. Note that some drawing commands require equal scales to work as
846 expected: if you try to draw a circle with different scales you will get
847 an ellipse.
848
849 The \meta{xmin} and \meta{xmax} parameters establish the lower
850 and upper bounds for the $x$-axis coordinates; similarly, \meta{ymin}
851 and \meta{ymax} establish the bounds for the $y$-axis. These bounds are
852 expressed in local units---in other words, the actual width of the
853 picture will be $(\meta{xmax}-\meta{xmin})\cdot\meta{xfactor}$ times
854 \cs{mfpicunit}, its height $(\meta{ymax}-\meta{ymin})\cdot\meta{yfactor}$
855 times \cs{mfpicunit}, and its depth zero.
856
857 Most of \mfp{}'s drawing macros accept parameters which are
858 \emph{coordinate pairs}. A coordinate pair is a pair of numbers $(x,y)$
859 enclosed in parentheses, with $\meta{xmin} \le x \le \meta{xmax}$ and
860 $\meta{ymin} \le y \le \meta{ymax}$.%
861 \footnote{These inequalities can be violated, usually causing
862 something to be drawn outside the designated borders of the figure.}
863 We will call these \emph{graph coordinates} and refer to the numbers $x$
864 and $y$ as being \emph{in graph units}. Things like the thickness of
865 lines and the lengths of arrowheads are required to be expressed in
866 actual lengths such as \dim{1pt} or \dim{3mm}. These will be referred to as
867 \emph{absolute} units.
868
869 One can scale all pictures uniformly by changing \cs{mfpicunit}, and
870 scale an individual picture by changing \meta{xfactor} and \meta{yfactor}.
871 After loading \mfp{}, \cs{mfpicunit} has the value \dim{1pt}. One
872 \texttt{pt} is a \emph{printer's point}, which equals 1/72.27 inches or
873 0.35146 millimeters.
874
875 \emph{Note}: Changing \cs{mfpicunit} or the optional parameters will
876 scale the coordinate system, but not the values of parameters that are
877 defined in absolute units. If you wish, you can set these to multiples
878 of \cs{mfpicunit}, but it is difficult (and almost certainly unwise) to
879 get the thickness of lines (for example) to scale along with the scale
880 parameters.
881
882 In addition to establishing the coordinate system, these scales and
883 bounds are used to establish the metric for the \MF{} character or
884 bounding box for the \MP{} figure described within the environment. If
885 any of these parameters are changed, the \file{.tfm} file (\MF{}) or the
886 bounding box (\MP{}) will be affected, so you will have to be sure to
887 reprocess the \TeX{} file after processing the \file{.mf} or \file{.mp}
888 file, even if no other changes are made in the figure.
889
890 The value of these 6 parameters to \cs{mfpic} are available within the
891 environment as macros: \cs{xfactor}, \cs{yfactor}, \cs{xmin}, \cs{xmax},
892 \cs{ymin} and \cs{ymax}.
893
894 \begin{cd}\pagelabel{mfpicnumber}
895 \cs{mfpicnumber}\marg{\meta{num}}%
896 \index{mfpicnumber@\cs{mfpicnumber}}
897 \end{cd}
898
899 Normally, \cs{mfpic} assigns the number 1 to the first \env{mfpic}
900 environment, after which the number is increased by one for each new
901 \env{mfpic} environment. This number is used internally to include the
902 picture. It is also transmitted to the output file where it is used as
903 the argument to a \gbc{beginmfpic} command. In \MF{} this number becomes
904 the position of the character in the font file, while in \MP{} it is
905 part of the name of the graphic file that is output. The above command
906 tells \mfp{} to ignore this sequence and number the next \env{mfpic}
907 figure with \meta{num} (and the one after that $\meta{num}+1$, etc.). It
908 is up to the user to make sure no number is repeated, as no checking is
909 done. Numbers greater than 255 may cause errors, as \TeX{} assumes that
910 characters are represented by numbers no larger than that. If the first
911 figure is to be numbered something other than $1$, then, under the
912 \opt{metapost} option, this command should come before
913 \cs{opengraphsfile}, as that command checks for the existence of the
914 first numbered figure to determine if there are figures to be included.
915
916 \begin{cd}\pagelabel{everymfpic}
917 \cs{everymfpic}\marg{\meta{commands}}\\
918 \cs{everyendmfpic}\marg{\meta{commands}}%
919 \index{everymfpic@\cs{everymfpic}}%
920 \index{everyendmfpic@\cs{everyendmfpic}}%
921 \end{cd}
922
923 These commands store the \meta{commands}. The first arranges for these
924 commands to be issued at the start of every \env{mfpic} environment and
925 the second arranges for its commands to be issued at the end of every
926 such environment. These could be any commands that make sense inside
927 that environment. The purpose of these commands is to save typing if
928 there is identical setup being performed in every picture.
929
930 \begin{cd}\pagelabel{envusage}
931 \cs{begin}\marg{mfpic}\texttt{...}\cs{end}\marg{mfpic}%
932 \index{begin@\cs{begin}\marg{mfpic}}
933 \end{cd}
934
935 In \LaTeX{} you may prefer to use \cs{begin}\marg{mfpic} and
936 \cs{end}\marg{mfpic} (instead of \cs{mfpic} and \cs{endmfpic}). This is
937 by no means required. The sample file \file{lapictures.tex} provided
938 with \mfp{} illustrates this use of an \env{mfpic} environment in
939 \LaTeX{}.
940
941 \medskip
942 One should be careful using \TeX{} groups inside \env{mfpic}
943 environments. These can be useful to limit the scope of declarations or
944 of changes to some variables. However, they do not limit the scope of
945 changes to the figure file that is being written, so there is a danger
946 that \TeX{} and \MF{} will have different values. There are also some
947 \mfp{} commands that need to be at the outermost level. Thus, grouping
948 should generally be avoided except for those groups provided by \mfp{}
949 commands.
950
951 \medskip
952 For the remainder of the macros, the numerical parameters are expressed
953 in graph units, the units of the local coordinate system specified by
954 \cs{mfpic}, unless otherwise indicated.
955
956
957 \section{Common objects.}\label{figures}
958
959 The \mfp{} macros that draw things can be roughly divided into two
960 classes.
961 \begin{enumerate}
962 \item Those that simply cause something to be drawn. Examples of these
963 are the \cs{point} command, which places a dot at a list of
964 coordinates, and \cs{gridlines}, which draw coordinate lines with
965 specified separation.
966 \item Those that both \emph{define} and draw a \emph{path}. The macros
967 \cs{circle}, \cs{rect}, and \cs{polyline} are examples of these.
968 \end{enumerate}
969
970 Macros of type 2 are referred to hereafter as \emph{figure macros}, for
971 lack of a better term. With them one can use \emph{prefix
972 macros}\index{prefix macro} to modify various aspects of the path and
973 how it is drawn. For example,
974 \begin{verbatim}
975 \polyline{(1,2),(3,4)}
976 \end{verbatim}
977 draws a line from $(1,2)$ to $(3,4)$, but
978 \begin{verbatim}
979 \dotted\polyline{(1,2),(3,4)}
980 \end{verbatim}
981 produces a dotted version, and
982 \begin{verbatim}
983 \arrow\polyline{(1,2),(3,4)}
984 \end{verbatim}
985 draws it with an arrowhead at the tip. This is not possible with
986 \cs{gridlines}, for example. As \mfp{} and the accompanying \MF{}
987 package \grafbase{} are currently written, prefix macros can only be
988 applied to single paths, and \cs{gridlines} produces a whole set of
989 lines. In this manual, as each macro is introduced, if it is a figure
990 macro, this will be explicitly stated.
991
992 Some commands depend on the value of separately defined parameters. all
993 these parameters are initialized when \mfp{} is loaded. In the following
994 descriptions we give the initial value of all the relevant parameters.
995 \Mfp{} provides commands to change any of these parameters. When \MP{}
996 output is selected, figures can be drawn in any color and several of the
997 above mentioned parameters are colors. For example, \gbc{drawcolor} is
998 the name of the default color used to draw curves, \gbc{headcolor} is
999 used when drawing arrowheads, etc. To save repetition: all special
1000 colors for figures are initialized to \mfc{black} except
1001 \mfc{background}, which is \mfc{white}.
1002
1003
1004 \subsection{Points, lines, and rectangles}\label{points}
1005
1006 \begin{cd}\pagelabel{point}
1007 \cs{point}\oarg{\meta{size}}\marg{\meta{$p_0$},\meta{$p_1$},$\ldots$}%
1008 \index{point@\cs{point}}
1009 \end{cd}
1010
1011 Draws small disks centered at the points specified in the list of
1012 ordered pairs. The optional argument \meta{size} is an absolute
1013 dimension that determines the diameter of the disks. The default is the
1014 \TeX{} dimension \cs{pointsize}, initially \dim{2pt}. The disks have a
1015 filled interior if the command \cs{pointfilltrue} has been issued (the
1016 initial behavior). After the command \cs{pointfillfalse}, \cs{point}
1017 commands will produce outlined circles with the interiors erased. The
1018 color of the circles is the value of the predefined variable
1019 \gbc{pointcolor}, and the color inside of the open circles is the value
1020 of the variable \mfc{background}.%
1021 \footnote{\MP{} cannot actually erase. The illusion of erasing is
1022 created by painting over with \mfc{background}.}
1023
1024 \begin{cd}\pagelabel{plotsymbol}
1025 \cs{plotsymbol}\oarg{\meta{size}}\marg{\meta{symbol}}%
1026 \marg{\meta{$p_0$},\meta{$p_1$},$\ldots$}%
1027 \index{plotsymbol@\cs{plotsymbol}}
1028 \end{cd}
1029
1030 Draws small symbols centered at the points \meta{$p_0$}, \meta{$p_1$},
1031 and so on. The symbols must be given by name, and the available symbols
1032 are:
1033 \begin{display}
1034 \gbc{Asterisk}\index{Asterisk@\gbc{Asterisk}},
1035 \gbc{Circle}\index{Circle@\gbc{Circle}},
1036 \gbc{Diamond}\index{Diamond@\gbc{Diamond}},
1037 \gbc{Square}\index{Square@\gbc{Square}},
1038 \gbc{Triangle}\index{Triangle@\gbc{Triangle}},
1039 \gbc{Star}\index{Star@\gbc{Star}},
1040 \gbc{SolidCircle}\index{SolidCircle@\gbc{SolidCircle}},\\
1041 \gbc{SolidDiamond}\index{SolidDiamond@\gbc{SolidDiamond}},
1042 \gbc{SolidSquare}\index{SolidSquare@\gbc{SolidSquare}},
1043 \gbc{SolidTriangle}\index{SolidTriangle@\gbc{SolidTriangle}},
1044 \gbc{SolidStar}\index{SolidStar@\gbc{SolidStar}},
1045 \gbc{Cross}\index{Cross@\gbc{Cross}}, and
1046 \gbc{Plus}\index{Plus@\gbc{Plus}}.
1047 \end{display}
1048 The names should be self-explanatory, the `\gbc{Solid}' ones are filled
1049 in, the others are outlines. Under \opt{metapost}, symbols are drawn in
1050 \gbc{pointcolor}. The \meta{size} defaults to \cs{pointsize} as in
1051 \cs{point} above. \gbc{Asterisk} consists of six line segments while
1052 \gbc{Star} is the standard five-pointed star formed from ten straight
1053 line segments. \gbc{Cross} is a $\times$ shape. The name
1054 `\cs{plotsymbol}' comes from the fact that the \cs{plot} command (see
1055 subsection~\ref{drawing}), which was written first, utilizes these same
1056 symbols. The command \cs{symbol} was already taken (standard \LaTeX{}).
1057
1058 While one would rarely want to use them for this purpose, the following
1059 symbols are also available:
1060 \begin{display}
1061 \gbc{Arrowhead}\index{Arrowhead@\gbc{Arrowhead}},
1062 \gbc{Crossbar}\index{Crossbar@\gbc{Crossbar}},
1063 \gbc{Leftbar}\index{Leftbar@\gbc{Leftbar}},
1064 \gbc{Rightbar}\index{Rightbar@\gbc{Rightbar}},
1065 \gbc{Lefthook}\index{Lefthook@\gbc{Lefthook}},
1066 \gbc{Righthook}\index{Righthook@\gbc{Righthook}},
1067 \gbc{Leftharpoon}\index{Leftharpoon@\gbc{Leftharpoon}},\\
1068 \gbc{Rightharpoon}\index{Rightharpoon@\gbc{Rightharpoon}}.
1069 \end{display}
1070 These are mainly intended for making arrows. See subsection~\ref{arrows}
1071 for a further description.
1072
1073 The difference between \cs{pointfillfalse}\cs{point} and
1074 \cs{plotsymbol}\marg{Circle} is that the inside of the circle will not
1075 be erased in the second version, so whatever else has already been drawn
1076 in that area will remain visible. This is the default (for backward
1077 compatibility), but that can be changed with the commands below.
1078
1079 \begin{cd}\pagelabel{clearsymbols}
1080 \cs{clearsymbols}\\
1081 \cs{noclearsymbols}%
1082 \index{clearsymbols@\cs{clearsymbols}}%
1083 \index{noclearsymbols@\cs{noclearsymbols}}
1084 \end{cd}
1085
1086 After the first of these two commands, subsequent \cs{plotsymbol}
1087 commands will draw the open symbols with their interiors erased. After
1088 the second, the default behavior (described above) will be restored.
1089 These commands have no effect on \cs{point}. \cs{plotnodes} (see
1090 subsection~\ref{drawing}) also responds to the settings made by these
1091 commands. The \cs{plot} command (also in subsection~\ref{drawing}) does
1092 not.
1093
1094 You can design your own `symbols'. See the discussion of arrowheads in
1095 subsection~\ref{arrows}, and of storing paths in
1096 subsection~\ref{transformation}.
1097
1098 \begin{cd}\pagelabel{pointdef}
1099 \cs{pointdef}\marg{\meta{name}}\texttt{(\meta{xcoord},\meta{ycoord})}%
1100 \index{pointdef@\cs{pointdef}}
1101 \end{cd}
1102
1103 Defines a symbolic name for an ordered pair and the coordinates it
1104 contains. \meta{name} is any legal \TeX{} command name \emph{without}
1105 the backslash; \meta{xcoord} and \meta{ycoord} are any numbers. For
1106 example, after the command \cs{pointdef}\marg{A}\texttt{(1,3)}, \cs{A}
1107 expands to \texttt{(1,3)}, while \cs{Ax} and \cs{Ay} expand to
1108 \texttt{1} and \texttt{3}, respectively. If \opt{mplabels} is in effect
1109 one can use \cs{A} to specify where to place a text label, but if \TeX{}
1110 is placing labels one must use \texttt{(\cs{Ax},\cs{Ay})}. In most
1111 other cases, one can use \cs{A} where a pair or point is required.
1112
1113 \begin{cd}\pagelabel{polyline}
1114 \cs{polyline}\marg{\meta{$p_0$},\meta{$p_1$},$\ldots$}\\
1115 \cs{lines}\marg{\meta{$p_0$},\meta{$p_1$},$\ldots$}%
1116 \index{polyline@\cs{polyline}}%
1117 \index{lines@\cs{lines}}
1118 \end{cd}
1119
1120 The figure macro \cs{polyline} produces connected line segments from
1121 \meta{$p_0$} to \meta{$p_1$}, and from there to \meta{$p_2$}, etc. The
1122 result is an open polygonal path through the specified points, in the
1123 specified order. The macro \cs{lines} is an alias for \cs{polyline}.
1124
1125 \begin{cd}\pagelabel{polygon}
1126 \cs{polygon}\marg{\meta{$p_0$},\meta{$p_1$},$\ldots$}\\
1127 \cs{closedpolyline}\marg{\meta{$p_0$},\meta{$p_1$},$\ldots$}%
1128 \index{polygon@\cs{polygon}}%
1129 \index{closedpolyline@\cs{closedpolyline}}
1130 \end{cd}
1131
1132 The figure macro \cs{polygon} produces a closed polygon with vertices
1133 at the specified points in the specified order. It works exactly like
1134 \cs{polyline} except the last point in the list is also joined to the
1135 first. The macro \cs{closedpolyline} is an alias for \cs{polygon}.
1136
1137 \begin{cd}\pagelabel{rect}
1138 \cs{rect}\marg{\meta{$p_0$},\meta{$p_1$}}%
1139 \index{rect@\cs{rect}}
1140 \end{cd}
1141
1142 This figure macro produces the closed rectangle with horizontal and
1143 vertical sides, having the points \meta{$p_0$} and \meta{$p_1$} as
1144 diagonally opposite corners. The same rectangle can be specified in four
1145 different ways: either pair of opposite corners in either order.
1146
1147 It is occasionally helpful to know that connected paths like those
1148 produced by \cs{polyline} or \cs{rect} have a \emph{start} and a
1149 \emph{finish} as well as \emph{sense} (or direction). The path produced
1150 by \cs{polyline} starts at the first listed point and ends at last,
1151 having the direction determined by the order of the points. For
1152 \cs{rect} the sense may be clockwise or anticlockwise depending on the
1153 corners used: it starts by moving horizontally from the first listed
1154 point. Several \mfp{} macros (such as those that add arrowheads) treat
1155 the beginning and the end of a path differently, or adjust their
1156 behavior according to the sense of the curve.
1157
1158 \begin{cd}\pagelabel{regpolygon}
1159 \cs{regpolygon}\marg{\meta{num}}\marg{\meta{name}}%
1160 \marg{\meta{eqn$_1$}}\marg{\meta{eqn$_2$}}%
1161 \index{regpolygon@\cs{regpolygon}}
1162 \end{cd}
1163
1164 This figure macro produces a closed regular polygon with \meta{num}
1165 sides. The second argument, \meta{name} is a symbolic name. It can be
1166 used to refer to the vertices later. The last two arguments should be
1167 equations that position two of the vertices or one vertex and the
1168 center. The center is referred to by \meta{name}\gbc{0} and the vertices
1169 by \meta{name}\gbc{1} \meta{name}\gbc{2}, etc., going anticlockwise
1170 around the polygon. The \meta{name} itself (without a number suffixed)
1171 will be a \MF{} variable assigned the value of \meta{num}. For example,
1172 \begin{verbatim}
1173 \regpolygon{5}{Kay}{Kay0=(0,1)}{Kay1=(2,0)}
1174 \end{verbatim}
1175 will produce a regular pentagon with its center at $(0,1)$ and its first
1176 vertex at $(2,0)$. One could later draw a star inside it with
1177 \begin{verbatim}
1178 \polygon{Kay1,Kay3,Kay5,Kay2,Kay4}
1179 \end{verbatim}
1180 Moreover, \gbc{Kay} will equal $5$. The name given becomes a \MF{}
1181 variable and care should be taken to make the name distinctive so as not
1182 to redefine some internal variable.
1183
1184
1185 \subsection{A word about list arguments}\label{list}
1186
1187 We have seen already four \mfp{} macros that take a mandatory argument
1188 consisting of an arbitrary number of coordinate pairs, separated by
1189 commas. There are many more, and some that take a comma-separated list
1190 of items of other types. If the lists are long, especially if they are
1191 generated by a program, it might be more convenient if one could simply
1192 refer to an external file for the data. This is possible, and one does
1193 it the following way: instead of \cs{polyline}\marg{\meta{list}}, one
1194 can write\index{datafile@\cs{datafile}}
1195 \begin{ex}
1196 \cs{polyline}\cs{datafile}\marg{\meta{filename}}
1197 \end{ex}
1198 where \meta{filename} is the full name of the file containing the data.
1199 The required format of this file and the details of this usage can be
1200 found in subsection~\ref{external}. This method is available for any
1201 command that takes a comma-separated list of data (of arbitrary length)
1202 as its last argument, \emph{with the exception of those commands that
1203 add text to the picture}. Examples of the latter are \cs{plottext} and
1204 \cs{axislabels} (subsection~\ref{text}).
1205
1206
1207 \subsection{Axes, axis marks, and grids}\label{axesthings}
1208
1209 \begin{cd}\pagelabel{axes}
1210 \cs{axes}\oarg{\meta{hlen}}\\
1211 \cs{xaxis}\oarg{\meta{hlen}}\\
1212 \cs{yaxis}\oarg{\meta{hlen}}%
1213 \index{axes@\cs{axes}}%
1214 \index{xaxis@\cs{xaxis}}%
1215 \index{yaxis@\cs{yaxis}}
1216 \end{cd}
1217
1218 These are retained for backward compatibility, but there are more
1219 flexible alternatives below. They draw $x$- and $y$-axes for the
1220 coordinate system. The command \cs{axes} is equivalent to \cs{xaxis}
1221 followed by \cs{yaxis} which produce the obvious. The $x$- and $y$-axes
1222 extend the full width and height of the \env{mfpic} environment. The
1223 optional \meta{hlen} sets the length of the arrowhead on each axis. The
1224 default is the value of the \TeX{} dimension \cs{axisheadlen}, initially
1225 \dim{5pt}. The shape of the arrowhead is determined as in the \cs{arrow}
1226 macro (section~\ref{modifier}). The color of the head is the value of
1227 \gbc{headcolor}, the shaft is \gbc{drawcolor}.
1228
1229 Unlike other commands that produce lines or curves, these do not respond
1230 to prefix macros. They always draw a solid line (with an arrowhead
1231 unless \cs{axisheadlen} is \dim{0pt}). They \emph{do} respond to changes
1232 in the pen thickness (see \cs{penwd} in section~\ref{parameters}) but
1233 that is pretty much the only possibility for variation.
1234
1235 \begin{cd}\pagelabel{axis}
1236 \cs{axis}\oarg{\meta{hlen}}\marg{\meta{one-axis}}\\
1237 \cs{doaxes}\oarg{\meta{hlen}}\marg{\meta{axis-list}}%
1238 \index{axis@\cs{axis}}%
1239 \index{doaxes@\cs{doaxes}}%
1240 \end{cd}
1241
1242 These produce any of 6 different axes. The parameter \meta{one-axis} can
1243 be \texttt{x} or \texttt{y}, to produce (almost) the equivalent of
1244 \cs{xaxis} and \cs{yaxis}; or it can be \texttt{l}, \texttt{b},
1245 \texttt{r}, or \texttt{t} to produce an axis on the border of the
1246 picture (left, bottom, right or top, respectively). \cs{doaxes} takes a
1247 list of any or all of the six letters (with either spaces or nothing in
1248 between) and produces the appropriate axes. Example:
1249 \cs{doaxes}\marg{lbrt}. The optional argument sets the length of the
1250 arrowhead. In the case of axes on the edges, the default is the value of
1251 \cs{sideheadlen}, which \mfp{} initializes to \dim{0pt}. For the $x$-
1252 and $y$-axis the default is \cs{axisheadlen} as in \cs{xaxis} and
1253 \cs{yaxis} above.
1254
1255 The commands \cs{axis}\marg{x}, \cs{axis}\marg{y}, and
1256 \cs{doaxes}\marg{xy} differ from the old \cs{xaxis}, \cs{yaxis} and
1257 \cs{axes} in that these new versions respond to prefix macros. The
1258 \cs{arrow} prefix previously mentioned is an exception: these macros add
1259 an arrowhead automatically. For example, the sequence
1260 \cs{dotted}\cs{axis}\marg{x} draws a dotted $x$-axis, but
1261 \cs{dotted}\cs{xaxis} produces a \MF{} error. A prefix macro applied to
1262 \cs{doaxes} generates no error, but only the first axis in the list will
1263 be affected.
1264
1265 \begin{cd}\pagelabel{axisline}
1266 \cs{axisline}\marg{\meta{one-axis}}\\
1267 \cs{border}%
1268 \index{axisline@\cs{axisline}}%
1269 \index{border@\cs{border}}%
1270 \end{cd}
1271
1272 These are figure macros that draw the line or lines that an \cs{axis}
1273 command would draw. An \cs{axis} command is almost the equivalent of
1274 \begin{display}
1275 \cs{arrow}\oarg{l\meta{hlen}}\cs{axisline}\marg{\meta{one-axis}}.
1276 \end{display}
1277 The \cs{axisline} command is provided as a figure macro for maximum
1278 flexibility. For example, one can use the star-form of the \cs{arrow}
1279 command if desired or decorate it with ones own choice of arrowhead (see
1280 subsection~\ref{arrows}).
1281
1282 Also a figure macro, \cs{border} produces the rectangle which, if drawn,
1283 is visibly the same as the four border \cs{axisline}\,s (without heads).
1284 It is a closed path and could easily be drawn with a \cs{rect} command,
1285 but the \cs{border} command automatically adjusts for the margins set by
1286 the commands below.
1287
1288 The side axes are drawn by default with a pen stroke along the very edge
1289 of the picture (as determined by the parameters to \cs{mfpic}). This can
1290 be changed with the command \cs{axismargin} described below.
1291
1292 Axes on the edges are drawn so that they don't cross each other.
1293 \cs{doaxes}\marg{lbrt}, for example, produces a perfect rectangle. If the
1294 $x$- and $y$-axis are drawn with \cs{axis} or \cs{doaxes}, then they
1295 will not cross the side axes. For this to work properly, all the
1296 following margin settings have to be done before the axes are drawn.
1297
1298 \begin{cd}\pagelabel{axismargin}
1299 \cs{axismargin}\marg{\meta{one-axis}}\marg{\meta{num}}\\
1300 \cs{setaxismargins}%
1301 \marg{\meta{num}}\marg{\meta{num}}\marg{\meta{num}}\marg{\meta{num}}\\
1302 \cs{setallaxismargins}\marg{\meta{num}}%
1303 \index{axismargin@\cs{axismargin}}%
1304 \index{setaxismargins@\cs{setaxismargins}}%
1305 \index{setallaxismargins@\cs{setallaxismargins}}%
1306 \end{cd}
1307
1308 The parameter \meta{one-axis} is one of the letters \texttt{l},
1309 \texttt{b}, \texttt{r}, or \texttt{ t}, and \cs{axismargin} causes the
1310 given axis to be shifted \emph{inward} by the \meta{num} specified (in
1311 \emph{graph} units). The second command \cs{setaxismargins} takes
1312 4 arguments, using them to set the margins starting with the left and
1313 proceeding anticlockwise. The last command sets all the axis margins to
1314 the same value.
1315
1316 A change to an axis margin affects not only the axis at that edge but
1317 also the three axes perpendicular to it. For example, if the margins are
1318 $M_{\mathrm{lft}}$, $M_{\mathrm{bot}}$, $M_{\mathrm{rt}}$ and
1319 $M_{\mathrm{top}}$, then \cs{axis}\marg{b} draws a line starting
1320 $M_{\mathrm{lft}}$ graph units from the left edge and ending
1321 $M_{\mathrm{rt}}$ units from the right edge. Of course, the entire line
1322 is $M_{\mathrm{bot}}$ units above the bottom edge. The margins are also
1323 respected by the $x$- and $y$-axis, but only when drawn with \cs{axis}.
1324 The old \cs{xaxis}, \cs{yaxis} and \cs{axes} ignore them.
1325
1326 Special effects can be achieved by lying to one axis about the other
1327 margins. That is, axes can be draw in separate commands with changes to
1328 the declared margins in between. Be aware that various other commands
1329 are affected by the margin values. Examples are the already mentioned
1330 \cs{border}, as well as \cs{grid} and \cs{gridlines}
1331 (page~\pageref{grid} in this subsection).
1332
1333 \begin{cd}\pagelabel{axismarks}
1334 \cs{xmarks}\oarg{\meta{len}}\marg{\meta{numberlist}}\\
1335 \cs{ymarks}\oarg{\meta{len}}\marg{\meta{numberlist}}\\
1336 \cs{lmarks}\oarg{\meta{len}}\marg{\meta{numberlist}}\\
1337 \cs{bmarks}\oarg{\meta{len}}\marg{\meta{numberlist}}\\
1338 \cs{rmarks}\oarg{\meta{len}}\marg{\meta{numberlist}}\\
1339 \cs{tmarks}\oarg{\meta{len}}\marg{\meta{numberlist}}\\
1340 \cs{axismarks}\marg{\meta{axis}}\oarg{\meta{len}}\marg{\meta{numberlist}}%
1341 \index{xmarks@\cs{xmarks}}%
1342 \index{tmarks@\cs{tmarks}}%
1343 \index{bmarks@\cs{bmarks}}%
1344 \index{ymarks@\cs{ymarks}}%
1345 \index{lmarks@\cs{lmarks}}%
1346 \index{rmarks@\cs{rmarks}}%
1347 \index{axismarks@\cs{axismarks}}
1348 \end{cd}
1349
1350 These macros place hash marks on the appropriate axes at the places
1351 indicated by the values in the list. The optional \meta{len} gives the
1352 length of the hash marks. If \meta{len} is not specified, the \TeX{}
1353 dimension \cs{hashlen}, initially \dim{4pt}, is used. The marks on the
1354 $x$- and $y$-axes are centered on the respective axis; the marks on the
1355 border axes are drawn to the inside. Both these behaviors can be
1356 changed (see below). The commands may be repeated as often as desired.
1357 (The timing of drawing commands can make a difference as outlined in
1358 appendix~\ref{mpconsiderations}.) The command \cs{axismarks}\marg{x} is
1359 equivalent to \cs{xmarks} and so on for each of the six axes. (I would
1360 have used the shorter name \cs{marks}, but that name was already taken
1361 by \eTeX{}.)
1362
1363 The \meta{numberlist} is normally a comma-separated list of numbers. In
1364 place of this, one can give a starting number, an increment and an
1365 ending number as in the following example:
1366 \begin{verbatim}
1367 \xmarks{-2 step 1 until 2}
1368 \end{verbatim}
1369 is the equivalent of
1370 \begin{verbatim}
1371 \xmarks{-2,-1,0,1,2}
1372 \end{verbatim}
1373
1374 One must use exactly the words \mfc{step} and \mfc{until}. Spaces are
1375 not needed unless a variable name is used in place of one of the
1376 numbers (see subsection~\ref{variables}). The number of spaces is not
1377 significant.%
1378 \footnote{Experienced \MF{} programmers may recognize that anything
1379 can be used that is permitted in \MF{}'s \meta{forloop} syntax. Thus
1380 the given example can also be reworded \cs{xmarks}\marg{-2 upto 2},
1381 or even \cs{xmarks}\marg{2 downto -2}. See subsection~\ref{loops}
1382 for more on for-loops in \mfp{}.} %
1383 Users of this syntax should be aware that if any of the numbers is not
1384 an integer then, because of natural round-off effects, the last value
1385 might be overshot and a mark not printed there. For example, to ensure
1386 that a mark is printed at the point $1.0$ on the $x$-axis, the second
1387 line below is better than the first.
1388 \begin{verbatim}
1389 \xmarks{0 step .2 until 1.0}
1390 \xmarks{0 step .2 until 1.1}
1391 \end{verbatim}
1392
1393 \begin{cd}\pagelabel{setaxismarks}
1394 \cs{setaxismarks}\marg{\meta{axis}}\marg{\meta{pos}}\\
1395 \cs{setbordermarks}\marg{\meta{lpos}}\marg{\meta{bpos}}\marg{\meta{rpos}}\marg{\meta{tpos}}\\
1396 \cs{setallbordermarks}\marg{\meta{pos}}\\
1397 \cs{setxmarks}\marg{\meta{pos}}\\
1398 \cs{setymarks}\marg{\meta{pos}}%
1399 \index{setaxismarks@\cs{setaxismarks}}%
1400 \index{setbordermarks@\cs{setbordermarks}}%
1401 \index{setallbordermarks@\cs{setallbordermarks}}%
1402 \index{setxmarks@\cs{setxmarks}}%
1403 \index{setymarks@\cs{setymarks}}%
1404 \end{cd}
1405
1406 These set the placement of the hash marks relative to the axis. The
1407 parameter \meta{axis} is one of the letters \texttt{x}, \texttt{y}, \texttt{l},
1408 \texttt{b}, \texttt{r}, or \texttt{t}, and \meta{pos} must be one of the literal
1409 words \gbc{inside}, \gbc{outside}, \gbc{centered}, \gbc{onleft},
1410 \gbc{onright}, \gbc{ontop} or \gbc{onbottom}. The second command takes
1411 four arguments and sets the position of the marks on each border. The
1412 third command sets the position on all four border axis to the same
1413 value. The last two commands are abbreviations for
1414 \cs{setaxismarks}\marg{x}\marg{\meta{pos}} and
1415 \cs{setaxismarks}\marg{y}\marg{\meta{pos}}, respectively.
1416
1417 Not all combinations make sense (for example, \gbc{ontop} for the right
1418 side axis). In these cases, no error message is produced. These words
1419 are actually \MF{} numeric variables and the variables \gbc{ontop} and
1420 \gbc{onleft}, for example, have the same value. Thus, using \gbc{ontop}
1421 for the right axis will have the same effect as \gbc{onleft}. Similarly,
1422 \gbc{onright} and \gbc{onbottom} are the same. The parameters
1423 \gbc{inside} and \gbc{outside} usually make no sense for the $x$- and
1424 $y$-axes, but if they are used then \gbc{inside} means \gbc{ontop} for
1425 the $x$-axis and \gbc{onright} for the $y$-axis.
1426
1427 \begin{cd}\pagelabel{grid}
1428 \cs{grid}\oarg{\meta{size}}\marg{\meta{xsep},\meta{ysep}}\\
1429 \cs{gridpoints}\oarg{\meta{size}}\marg{\meta{xsep},\meta{ysep}}\\
1430 \cs{lattice}\oarg{\meta{size}}\marg{\meta{xsep},\meta{ysep}}\\
1431 \cs{hgridlines}\marg{\meta{ysep}}\\
1432 \cs{vgridlines}\marg{\meta{xsep}}\\
1433 \cs{gridlines}\marg{\meta{xsep},\meta{ysep}}%
1434 \index{grid@\cs{grid}}%
1435 \index{gridpoints@\cs{gridpoints}}%
1436 \index{lattice@\cs{lattice}}%
1437 \index{vgridlines@\cs{vgridlines}}%
1438 \index{hgridlines@\cs{hgridlines}}%
1439 \index{gridlines@\cs{gridlines}}%
1440 \end{cd}
1441
1442 \cs{grid} draws a dot at every point for which the first coordinate is
1443 an integer multiple of the \meta{xsep} and the second coordinate is an
1444 integer multiple of \meta{ysep}. The diameter of the dot is determined
1445 by \meta{size}. The default is the value of \cs{griddotsize},
1446 initially \dim{0.5pt}. Under the \opt{metapost} option, the color of the
1447 dot is \gbc{pointcolor}. The commands \cs{gridpoints and \cs{lattice}}
1448 are synonyms for \cs{grid}.
1449
1450 \cs{hgridlines} draws the horizontal and \cs{vgridlines} the vertical
1451 lines through these same points. \cs{gridlines} draws both sets of
1452 lines. The thickness of the lines is set by \cs{penwd}. Authors are
1453 recommended to either reduce the pen width or change \gbc{drawcolor} to
1454 a lighter color for grid lines. Or omit them entirely: well-designed
1455 graphs usually don't need them and almost never should both horizontals
1456 and verticals be used.
1457
1458 The above commands draw their dots and lines within the margins set by the
1459 axis margin commands on page~\pageref{axismargin}.
1460
1461 \begin{cd}\pagelabel{plrgrid}
1462 \cs{plrgrid}\marg{\meta{rsep},\meta{anglesep}}\\
1463 \cs{gridarcs}\marg{\meta{rsep}}\\
1464 \cs{gridrays}\marg{\meta{anglesep}}\\
1465 \cs{plrpatch}\marg{\meta{rmin},\meta{rmax},\meta{rsep},%
1466 \meta{tmin},\meta{tmax},\meta{tsep}}\\
1467 \cs{plrgridpoints}\oarg{\meta{size}}\marg{\meta{rsep},\meta{anglesep}}%
1468 \index{plrgrid@\cs{plrgrid}}%
1469 \index{plrpatch@\cs{plrpatch}}%
1470 \index{gridarcs@\cs{gridarcs}}%
1471 \index{gridrays@\cs{gridrays}}%
1472 \index{plrgridpoints@\cs{plrgridpoints}}%
1473 \end{cd}
1474
1475 \cs{plrgrid} fills the graph with circular arcs and radial lines.
1476 \cs{gridarcs} draws only the arcs, \cs{gridrays} only the radial lines.
1477 \cs{plrgridpoints} places a dot (diameter \meta{size}) at all the places
1478 the rays and arcs would intersect. It takes an optional argument for the
1479 size of the dots, the default being \cs{griddotsize}, the same as the
1480 \cs{grid} command.
1481
1482 The arcs lie on circles centered at $(0,0)$ and the rays would all meet
1483 at $(0,0)$ if extended. The corresponding \MF{} commands actually draw
1484 just enough to cover the graph area and then clip them to the graph
1485 boundaries. If you don't want them clipped, use \cs{plrpatch}. Unlike
1486 the rectangular coordinate grid commands, these do not respect the axis
1487 margins (rectangular margins don't really belong with polar coordinates).
1488
1489 \cs{plrpatch} draws arcs with radii starting at \meta{rmin}, stepping by
1490 \meta{rsep} and ending with \meta{rmax}. Each arc goes from angle
1491 \meta{tmin} to \meta{tmax}. It also draws radial lines with angles
1492 starting at \meta{tmin}, stepping by \meta{tsep} and ending with
1493 \meta{tmax}. Each line goes from radius \meta{rmin} to \meta{rmax}. If
1494 $\meta{rmax}-\meta{rmin}$ doesn't happen to be a multiple of
1495 \meta{rsep}, the arc with radius \meta{rmax} is drawn anyway. The same
1496 is true of the line at angle \meta{tmax}, so that the entire boundary is
1497 always drawn.
1498
1499 If \meta{tsep} is larger than \meta{tmax}${}-{}$\meta{tmin}, then only
1500 the boundary rays will be drawn. If \meta{rsep} is larger than
1501 \meta{rmax}${}-{}$\meta{rmin}, then only the boundary arcs will be
1502 drawn.
1503
1504 The color used for rays and arcs is \gbc{drawcolor}, and for dots
1505 \gbc{pointcolor}. The advice about color and use of \cs{gridlines} holds
1506 for \cs{plrgrid} and its relatives as well.
1507
1508 \begin{cd}\pagelabel{vectorfield}
1509 \cs{vectorfield}\oarg{\meta{hlen}}\marg{\meta{xsp},\meta{ysp}}%
1510 \marg{\meta{formula}}\marg{\meta{restriction}}\\
1511 \cs{plrvectorfield}\oarg{\meta{hlen}}\marg{\meta{rsp},\meta{tsp}}%
1512 \marg{\meta{formula}}\marg{\meta{restriction}}%
1513 \index{vectorfield@\cs{vectorfield}}%
1514 \index{plrvectorfield@\cs{plrvectorfield}}
1515 \end{cd}
1516
1517 These commande draw a field of vectors (arrows). The optional argument
1518 is the length of the arrowhead, the default being the dimension
1519 \cs{headlen}, initially \dim{3pt}.
1520
1521 For \cs{vectorfield}, an arrow is drawn starting from each point $(x,y)$
1522 where $x$ is an integer multiple of \meta{xsp} and $y$ is an integer
1523 multiple of \meta{ysp}. The vector field is given by \meta{formula},
1524 which should be a pair-valued expression in the literal variables
1525 \mfc{x} and \mfc{y}. Typically that would be a pair of numeric
1526 expressions enclosed in parentheses and separated by a comma. The last
1527 argument is a boolean expression in the literal variables \mfc{x} and
1528 \mfc{y}, used to restrict the domain. That is, if the expression is
1529 false for some $(x,y)$, no arrow is drawn at that point. If you do not
1530 wish to restrict the domain, type \texttt{true} for the restriction.
1531
1532 For \cs{plrvectorfield}, an arrow is drawn starting from each point with
1533 polar coordinates $(r,\theta)$ if $r$ is an integer multiple of
1534 \meta{rsp} and $\theta$ is an integer multiple of \meta{tsp}. In this
1535 case, the \meta{formula} must be a pair-valued expression in the literal
1536 variables \mfc{r} and \mfc{t}. This should be (or produce) a pair of $x$
1537 and $y$ coorinates, not a polar coordinate pair. If you have formulas
1538 $R(r,\theta)$ for the length of each vector and $T(r,\theta)$ for the
1539 angle, then the following will convert to $(x,y)$ pairs:
1540 \begin{verbatim}
1541 {polar (R(r,t),T(r,t))}
1542 \end{verbatim}
1543 The last argument is as in \cs{vectorfield}, except it should depend on
1544 the literal variables \mfc{r} and \mfc{t}.
1545
1546 In either case, the arrow is not drawn if the starting point would lie
1547 outside the borders set with \cs{axismargins} and its relatives.
1548
1549 The following draws a rotational field, omitting the inside of the
1550 circle of radius $1$, where the arrows would be excessively long, and
1551 especially avoiding $(0,0)$ where the vector field is undefined.
1552 \begin{verbatim}
1553 \vectorfield[2.5pt]{.25,.25}{.5*(-y,x)/(x**2+y**2)}{x**2+y**2 >= 1}
1554 \end{verbatim}
1555 The following is the same field, represented by arrows whose locations
1556 are regularly spaced in polar coordinates.
1557 \begin{verbatim}
1558 \plrvectorfield[2.5pt]{.25,20}{polar(.5/r,t+90)}{r >= 1}
1559 \end{verbatim}
1560
1561
1562 \subsection{Circles, arcs and ellipses}\label{circles}
1563
1564 \begin{cd}\pagelabel{circle}
1565 \cs{circle}\oarg{\meta{format}}\marg{\meta{specification}}%
1566 \index{circle@\cs{circle}}%
1567 \end{cd}
1568
1569 This figure macro produces a circle. Starting with \mfp{} version 0.7,
1570 there are more than one way to specify a circle. In version 0.8 and
1571 later there are six ways, and one selects which one by giving
1572 \cs{circle} an optional argument that signals what data will be
1573 specified in the mandatory argument.
1574
1575 \begin{cd}
1576 \cs{circle}\oarg{p}\marg{\meta{$c$},\meta{$r$}}\\
1577 \cs{circle}\oarg{c}\marg{\meta{$c$},\meta{$p$}}\\
1578 \cs{circle}\oarg{t}\marg{\meta{$p_1$},\meta{$p_2$},\meta{$p_3$}}\\
1579 \cs{circle}\oarg{s}\marg{\meta{$p_1$},\meta{$p_2$},\meta{$\theta$}}\\
1580 \cs{circle}\oarg{r}\marg{\meta{$p_1$},\meta{$p_2$},\meta{$r$}}\\
1581 \cs{circle}\oarg{q}\marg{\meta{$p_1$},\meta{$p_2$},\meta{$r$}}%
1582 \index{circle@\cs{circle}}%
1583 \end{cd}
1584
1585 The optional arguments produce circles according to the following
1586 descriptions.
1587 %
1588 \begin{description}
1589 \item[\oarg{p}] The \textit{Polar form} is the default. The data in the
1590 mandatory argument should then be the center \meta{c} and radius
1591 \meta{r} of the circle. A negative radius is a mathematical error, but
1592 it is accepted. It produces the same circle, with the same sense, but
1593 the starting point (normally \meta{$r$} units to the right of the
1594 center) is \meta{$r$} units \emph{left} of the center.
1595
1596 \item[\oarg{c}] The \textit{center-point form}. In this case the data
1597 should be the center and one point on the circumference. The circle
1598 starts at the point and has an anticlockwise sense.
1599
1600 \item[\oarg{t}] The \textit{three-point form}. The data are three points
1601 that do not lie in a straight line. The circle starts at the first point
1602 and has the sense determined by the order of the points.
1603
1604 \item[\oarg{s}] The \textit{point-sweep form}. The data are two points on the
1605 circle, followed by the angle of arc between them. This circle starts at
1606 the first point and has a sense determined by the angle: anticlockwise
1607 for positive angles, clockwise for negative.
1608
1609 \item[\oarg{r}] The \textit{point-radius form}. The data are two points on the
1610 circle, followed by the radius. There are two circles with this data.
1611 The one that makes the angle from the first to the second point positive
1612 and less than $180$ degrees is produced. The sense of the circle is
1613 normally anticlockwise starting at the first point. Using a negative
1614 radius is a mathematical error, but this command just produces the other
1615 circle with the opposite sense.
1616
1617 \item[\oarg{q}] The \textit{alternative point-radius form}. The data are
1618 the same as for the \oarg{r} case, except the other circle is produced.
1619 That is, a circle starting at the first point, proceeding anticlockwise
1620 through an angle greater than $180$ degrees to the second point, then
1621 along the shorter arc to the first point. Again, a negative radius
1622 produces the other circle with clockwise sense.
1623 \end{description}
1624 %
1625 These optional arguments are also used in the \cs{arc} command (see
1626 below). The \cs{circle} command draws the whole circle of which the
1627 corresponding \cs{arc} command draws only a part.
1628
1629 \begin{cd}\pagelabel{arc}
1630 \cs{arc}\oarg{\meta{format}}\marg{\meta{specification}}\\
1631 \cs{arc*}\oarg{\meta{format}}\marg{\meta{specification}}%
1632 \index{arc@\cs{arc}}%
1633 \end{cd}
1634
1635 This figure macro produces a circular arc specified as determined by the
1636 \meta{format} optional parameter. As with \cs{circle}, the optional
1637 \meta{format} parameter determines the format of the other parameter, as
1638 indicated below. The user is responsible for ensuring that the parameter
1639 values make geometric sense. The starting point of each arc is at the
1640 first specified angle or point and the ending point is at the last one.
1641
1642 The star-form produces the complementary arc. That is, instead of the
1643 arc described below, it produces the rest of the circle from the ending
1644 point to the starting point of the arc described.
1645
1646 \begin{cd}
1647 \cs{arc}\oarg{s}\marg{\meta{$p_0$},\meta{$p_1$},\meta{$\theta$}}\\
1648 \cs{arc}\oarg{p}\marg{\meta{$c$},\meta{$\theta_1$},\meta{$\theta_2$},\meta{$r$}}\\
1649 \cs{arc}\oarg{a}\marg{\meta{$c$},\meta{$r$},\meta{$\theta_1$},\meta{$\theta_2$}}\\
1650 \cs{arc}\oarg{c}\marg{\meta{$c$},\meta{$p_1$},\meta{$\theta$}}\\
1651 \cs{arc}\oarg{t}\marg{\meta{$p_0$},\meta{$p_1$},\meta{$p_2$}}\\
1652 \cs{arc}\oarg{r}\marg{\meta{$p_0$},\meta{$p_1$},\meta{$r$}}\\
1653 \cs{arc}\oarg{q}\marg{\meta{$p_0$},\meta{$p_1$},\meta{$r$}}%
1654 \index{arc@\cs{arc}}%
1655 \end{cd}
1656
1657 The optional arguments produce arcs according to the following
1658 descriptions.
1659 \begin{description}
1660 \item[\oarg{s}] The \textit{point-sweep form} is the default format. It
1661 draws the circular arc starting from the point \meta{$p_0$}, ending at
1662 the point \meta{$p_1$}, and covering an arc angle of \meta{$\theta$}
1663 degrees, measured anticlockwise around the center of the circle. If,
1664 for example, the points \meta{$p_0$} and \meta{$p_1$} lie on a
1665 horizontal line with \meta{$p_0$} to the \emph{left}, and \meta{$\theta$}
1666 is between $0$~and $360$ (degrees), then the arc will sweep \emph{below} the
1667 horizontal line (in order for the arc to be anticlockwise). A
1668 negative value of \meta{$\theta$} gives a clockwise arc from \meta{$p_0$}
1669 to \meta{$p_1$}.
1670
1671 \item[\oarg{p}] The \textit{polar form} draws the arc of a circle with
1672 center \meta{$c$} starting at the angle \meta{$\theta_1$} and ending at
1673 the angle \meta{$\theta_2$}, with radius \meta{$r$}. Both angles are
1674 measured anticlockwise from the positive $x$ axis. If the first angle is
1675 less than the second, the arc has an anticlockwise sense, otherwise
1676 clockwise. A negative radius is a mathematical error, but the result is
1677 the arc on the opposite side of the circle, as if both angles were
1678 increased by $180$ degrees
1679
1680 \item[\oarg{a}] The alternative polar form differs from the polar form
1681 above only in the order of the arguments. This seems (to me) a more
1682 reasonable order, and matches the order \cs{sector} requires (see below).
1683 The \texttt{[p]} option is retained for backward compatibility.
1684
1685 \item[\oarg{c}] The \textit{center-point-angle form} draws the circular
1686 arc with center \meta{$c$}, starting at the point \meta{$p_1$}, and
1687 sweeping an angle of \meta{$\theta$} around the center from that point.
1688 This is the fundamental method for drawing arcs. All other methods are
1689 converted to this or the point-sweep method. Even the point sweep form
1690 is converted to this one for angles greater than 90 degrees.
1691
1692 \item[\oarg{t}] The \textit{three-point form} draws the circular arc
1693 which passes through all three points given, in the order given.
1694 Internally, this is converted to two applications of the point-sweep
1695 form.
1696
1697 \item[\oarg{r}] The \textit{point-radius form} draws an arc on the
1698 circle that \cs{circle}\oarg{r} would produce. The arc starts at the
1699 point \meta{$p_0$} and ends at \meta{$p_1$}. Of the two possible arcs on
1700 that circle, it produces the shorter one: the one with an angle $\theta$
1701 less than $180$ degrees measured anticlockwise around the center of the
1702 circle. A negative radius is a mathematical error, but the result is the
1703 short arc on the other circle with a clockwise sense.
1704
1705 \item[\oarg{q}] The \textit{alternative point-radius form} is the same
1706 as \oarg{r} except it produces the longer arc: the one with angle
1707 $\theta$ larger than $180$ degrees measured anticlockwise around the
1708 center of the circle. A negative radius is a mathematical error, but the
1709 result is the longer arc on the other circle with a clockwise sense.
1710 \end{description}
1711
1712 For both options \oarg{r} and \oarg{q} the angle is computed and then
1713 the point-sweep method is used. If the absolute value of the radius is
1714 less than half the distance between the points, then no such arc exists.
1715 In this case, the angle is just set equal to $\pm180$ degrees (as if the
1716 radius were changed to half the distance).
1717
1718 \begin{cd}\pagelabel{sector}
1719 \cs{sector}\marg{\meta{$c$},\meta{$r$},\meta{$\theta_1$},\meta{$\theta_2$}}%
1720 \index{sector@\cs{sector}}%
1721 \end{cd}
1722
1723 This figure macro produces the sector of the circle with center at the
1724 point \meta{$c$} and radius \meta{$r$}, from the angle \meta{$\theta_1$}
1725 to the angle \meta{$\theta_2$}. Both angles are measured in degrees
1726 anticlockwise from the direction parallel to the $x$ axis. The sector
1727 forms a closed path. \emph{Note}: \cs{sector} and \cs{arc}\oarg{p} have
1728 the same parameters, but \emph{in a different order}.%
1729 \footnote{This apparently was unintended, but we now have to live
1730 with it so as not to break existing \file{.tex} files.}
1731
1732
1733 \begin{cd}\pagelabel{ellipse}
1734 \cs{ellipse}\oarg{\meta{$\theta$}}\marg{\meta{$c$},\meta{$r_x$},\meta{$r_y$}}%
1735 \index{ellipse@\cs{ellipse}}%
1736 \end{cd}
1737
1738 This figure macro produces an ellipse with the $x$ radius \meta{$r_x$}
1739 and $y$ radius \meta{$r_y$}, centered at the point \meta{$c$}. The
1740 optional parameter \meta{$\theta$} provides a way of rotating the
1741 ellipse by \meta{$\theta$} degrees anticlockwise around its center.
1742 Ellipses may also be created by differentially scaling a circle and
1743 perhaps rotating the result. See subsection~\ref{transformation}.
1744
1745 \begin{cd}\pagelabel{fullellipse}
1746 \cs{fullellipse}\marg{\meta{$C$},\meta{$M_1$},\meta{$M_2$}}\\%
1747 \cs{halfellipse}\marg{\meta{$M_1$},\meta{$M_2$},\meta{$M_3$}}\\%
1748 \cs{quarterellipse}\marg{\meta{$M_1$},\meta{$A$},\meta{$M_2$}}%
1749 \index{fullellipse@\cs{fullellipse}}%
1750 \index{halfellipse@\cs{halfellipse}}%
1751 \index{quarterellipse@\cs{quarterellipse}}%
1752 \end{cd}
1753
1754 For any parallelogram there is a unique ellipse incribed in it which is
1755 tangent to the sides at their midpoints. The above allows one to obtain
1756 that ellipse and parts of it. The input to \cs{fullellipse} is the
1757 center \meta{$C$} of that parallelogram and the midpoints \meta{$M_1$}
1758 and \meta{$M_2$} of two adjacent sides. For $\cs{halfellipse}$, one
1759 supplies the midpoints \meta{$M_1$}, \meta{$M_2$}, and \meta{$M_3$} of
1760 three successive sides. Lastly, \cs{quarterellipse} requires the
1761 midpoints of two adjacents sides and the corner \meta{$A$} between them.
1762 Internally, a quarter-circle is transformed to produce the
1763 quarter-ellipse and the other two are built up out of two or four such
1764 quarter-ellipses.
1765
1766 The reasoning behind my choice of parameters is based on the anticipated
1767 use of these commands. For example, I wanted \cs{quarterellipse} to be
1768 used to round a corner represented by the three points $M_1$,
1769 $A$ and $M_2$. In order for the quarter-ellipse to have
1770 the same direction at $M_1$ and $M_2$ as the polygon $M_1AM_2$, the
1771 associated parallelogram has to have midpoints at $M_1$ and $M_2$.
1772
1773 \begin{cd}\pagelabel{plr}
1774 \cs{plr}\marg{(\meta{$r_0$},\meta{$\theta_0$}),%
1775 (\meta{$r_1$},\meta{$\theta_1$}), $\ldots$}%
1776 \index{plr@\cs{plr}}%
1777 \end{cd}
1778
1779 When dealing with arcs and circles, it is useful to work in polar
1780 coordinates. The macro \cs{plr} causes \MF{} to replace the specified
1781 list of polar coordinate pairs by the equivalent list of rectangular
1782 (cartesian) coordinate pairs. Through \cs{plr}, commands designed for
1783 rectangular coordinates can be applied to data represented in polar
1784 coordinates. It must be cautioned that this wholesale conversion of a
1785 list applies only to commands that take a list consisting of an
1786 arbitrary number of points, such as \cs{polyline}.
1787
1788 The effect of \cs{plr} is to apply a \MF{} command, \gbc{polar}, to each
1789 point in the list, producing a new list. This \MF{} command can also be
1790 used separately in any situation where a single \MF{} point is required. For
1791 example, to connect the point $(2,3)$ to the point with polar
1792 coordinates $(1, 135)$ write
1793 \begin{verbatim}
1794 \polyline{(2,3),polar(1,135)}
1795 \end{verbatim}
1796
1797 This last circle-producing macro I wrote for my own use. It produces a
1798 circle associated with the hyperbolic geometry of a disk or a
1799 half-plane.
1800
1801 \begin{cd}\pagelabel{pshcircle}
1802 \cs{pshcircle}\marg{\meta{center},\meta{radius}}\\
1803 \cs{pshcircle}*\marg{\meta{center},\meta{radius}}%
1804 \index{pshcircle@\cs{pshcircle}}%
1805 \end{cd}
1806
1807 This produces the circle whose hyperbolic center is at \meta{center} and
1808 whose pseudohyperbolic radius is \meta{radius}. This all takes place
1809 inside the circle with center $(0,0)$ and radius $1$ (the \emph{unit
1810 circle}). The \meta{center} is required to be inside the unit circle and
1811 the \meta{radius} is required to be less than $1$.
1812
1813 The star-form is for the \emph{upper half-plane}, which is the set of
1814 points with positive $y$-coordinate In this case, the \meta{center} must
1815 be in the upper half-plane and the \meta{radius} must still be less than
1816 $1$. If you are not versed in hyperbolic geometry, be warned that the
1817 actual diameter of the resulting circle is on the order of $2y/(1-R)$,
1818 where $R$ is the \meta{radius} and $y$ is the $y$-coordinate of
1819 \meta{center}. This can be quite large even for modest values of $R$ and
1820 $y$.
1821
1822 Finally, an arc-producing macro. This is also related to the hyperbolic
1823 geometry of a disk or a half-plane. The hyperbolic geometry includes a
1824 notion of distance that allow one to determine `shortest' path between
1825 two points. This shortest path is called a `geodesic' and it turns out
1826 (in the case of the upper half-plane or a disk) to be an arc of a
1827 circle: the unique circle that passes through both points and meets the
1828 boundary (of the half-plane or disk) at right angles.
1829
1830 \begin{cd}\pagelabel{hypergeodesic}
1831 \cs{hypergeodesic}\marg{$z_1$,$z_2$}\\
1832 \cs{hypergeodesic}*\marg{$z_1$,$z_2$}%
1833 \index{hypergeodesic@\cs{hypergeodesic}}%
1834 \end{cd}
1835
1836 This produces the hyperbolic geodesic from $z_1=(x_1,y_1)$ to
1837 $z_2=(x_2,y_2)$. For guaranteed results both points should be in the
1838 unit disk (i.e., $|z_1| < 1$ and $|z_2| < 1$) or, for the star form,
1839 both in the upper half-plane (i.e., $y_1 > 0$ and $y_2 > 0$). However,
1840 if these are not satisfied an arc of the circle described above will be
1841 drawn whenever not prevented by a numeric overflow. The star form
1842 produces the geodesic for points in the upper half-plane. The normal
1843 form produces the geodesic for points in the unit disk (inside of the
1844 circle of radius $1$ and center $(0,0)$). One can use transforms of
1845 these to get geodesics suitable for other disks and other half-planes.
1846
1847
1848 \subsection{Curves}\label{curves}
1849
1850 \begin{cd}\pagelabel{curve}
1851 \cs{curve}\oarg{\meta{tension}}\marg{\meta{$p_0$},\meta{$p_1$},$\ldots$}\\
1852 \cs{cyclic}\oarg{\meta{tension}}\marg{\meta{$p_0$},\meta{$p_1$},$\ldots$}\\
1853 \cs{closedcurve}\oarg{\meta{tension}}\marg{\meta{$p_0$},\meta{$p_1$},$\ldots$}%
1854 \index{curve@\cs{curve}}%
1855 \index{cyclic@\cs{cyclic}}
1856 \index{closedcurve@\cs{closedcurve}}%
1857 \end{cd}
1858
1859 These figure macros produce a smooth path through the specified points,
1860 in the specified order. It is `smooth' in two ways: it never changes
1861 direction abruptly (no `corners' or `cusps' on the curve), and it tries
1862 to make turns that are not too sharp. This latter property is acheived
1863 by specifying (to \MF{}) that the tangent to the curve at each listed
1864 point is to be parallel to the line from that point's predecessor to its
1865 successor. The \cs{cyclic} variant arranges for the last point to be
1866 connected (smoothly) to the first, and produces a closed \MF{} B\'ezier
1867 curve. The command \cs{closedcurve} is an alias for \cs{cyclic}.
1868
1869 The optional \meta{tension} influences \emph{how} smooth the curve is.
1870 The special value \mfc{infinity} (in fact, usually anything greater than
1871 about $10$), makes the curve not visibly different from a polyline. The
1872 higher the value of tension, the sharper the corners on the curve and
1873 the flatter the portions in between. \CMF{} requires the tension to be
1874 larger than $0.75$. The default value of the tension is $1$ when \mfp{} is
1875 loaded, but that can be changed with the following command.
1876
1877 \begin{cd}\pagelabel{settension}
1878 \cs{settension}\marg{\meta{num}}%
1879 \index{settension@\cs{settension}}
1880 \end{cd}
1881
1882 This sets the default tension for all commands that take an optional
1883 tension parameter.
1884
1885 \medskip
1886 Sometimes one would like a convex set of points to produce a convex
1887 curve. This will not always be the case with \cs{curve} or \cs{cyclic}.
1888 You can verify this with the following example, where the list of points
1889 traces a rectangle:
1890 \begin{verbatim}
1891 \cyclic{(0,0),(0,1),(1,1),(2,1),(2,0),(0,0)}
1892 \end{verbatim}
1893 To produce a convex curve, use one of the following:
1894
1895 \begin{cd}\pagelabel{convexcurve}
1896 \cs{convexcurve}\oarg{\meta{tension}}\marg{\meta{$p_0$},\meta{$p_1$},$\ldots$}\\
1897 \cs{convexcyclic}\oarg{\meta{tension}}\marg{\meta{$p_0$},\meta{$p_1$},$\ldots$}\\
1898 \cs{closedconvexcurve}\oarg{\meta{tension}}\marg{\meta{$p_0$},\meta{$p_1$},$\ldots$}%
1899 \index{convexcurve@\cs{convexcurve}}%
1900 \index{convexcyclic@\cs{convexcyclic}}%
1901 \index{closedconvexcurve@\cs{closedconvexcurve}}%
1902 \end{cd}
1903
1904 These figure macros can be used even if the list of points is not
1905 convex, and the result will be convex where possible. The third one is
1906 an alias for for the second one.
1907
1908 \medskip
1909 Occasionally it is necessary to specify a sequence of points with
1910 \emph{increasing} $x$-coordinates and draw a curve through them. One
1911 would then like the resulting curve both to be smooth \textit{and} to
1912 represent a function (that is, the curve always has increasing $x$
1913 coordinate, never turning leftward). This cannot be guaranteed with the
1914 \cs{curve} command unless the tension is \texttt{infinity}.
1915
1916 \begin{cd}\pagelabel{fcncurve}
1917 \cs{fcncurve}\oarg{\meta{tension}}\marg{($x_0$,$y_0$),($x_1$,$y_1$),$\ldots$}%
1918 \index{fcncurve@\cs{fcncurve}}%
1919 \end{cd}
1920
1921 This figure macro produces a curve through the points specified. If the
1922 points are listed with increasing (or decreasing) $x$ coordinates, the
1923 curve will also have increasing (resp., decreasing) $x$ coordinates. The
1924 \meta{tension} is a number greater than $1/3$ which controls how tightly
1925 the curve is drawn. Generally, the larger it is, the closer the curve is
1926 to the polyline through the points. The default tension is that set with
1927 \cs{settension}, initially $1$. For those who know something about
1928 \MF{}, this `tension' is not the same as the \MF{} notion of tension
1929 (the tension in the \cs{curve} command), but it functions in a similar
1930 fashion. In this case it can actually be any positive number, but only
1931 values greater than $1/3$ guarantee the property of never doubling back.
1932
1933 \begin{cd}\pagelabel{turtle}
1934 \cs{turtle}\marg{\meta{$p_0$},\meta{$v_1$},\meta{$v_2$},$\ldots$}%
1935 \index{turtle@\cs{turtle}}%
1936 \end{cd}
1937
1938 This figure macro produces a a sequence of line segments starting from
1939 the point \meta{$p_0$}, and extending along the (2-dimen\-sional vector)
1940 displacement \meta{$v_1$}. The next segment is from the previous
1941 segment's endpoint, along displacement \meta{$v_2$}. This continues for
1942 all listed displacements, a process similar to `turtle graphics'.
1943
1944
1945 \subsection{Bar charts and pie charts}\label{charts}
1946
1947 \begin{cd}\pagelabel{barchart}
1948 \cs{barchart}\oarg{\meta{start},\meta{sep},\meta{r}}%
1949 \marg{\meta{h-or-v}}\marg{\meta{list}}\\
1950 \cs{bargraph}\dots\\
1951 \cs{gantt}\dots\\
1952 \cs{histogram}\dots\\
1953 \cs{mfpbarchart}\dots\\
1954 \cs{mfpbargraph}\dots\\
1955 \cs{mfpgantt}\dots\\
1956 \cs{mfphistogram}\dots
1957 \index{barchart@\cs{barchart}}%
1958 \index{bargraph@\cs{bargraph}}%
1959 \index{histogram@\cs{histogram}}%
1960 \index{gantt@\cs{gantt}}%
1961 \end{cd}
1962
1963 The macro \cs{barchart} computes a bar chart or a Gantt chart. It does
1964 not draw the bars, but only defines their rectangular paths which the
1965 user may then draw or fill or both using the \cs{chartbar} macros (see
1966 below). Since bar charts have many names, \cs{bargraph} and
1967 \cs{histogram} are provided as synonyms. The macro \cs{gantt} is also a
1968 synonym; whether a Gantt chart or bar chart is created depends on the
1969 data.
1970
1971 Since \cs{barchart} never draws anything, there is no particular reason
1972 it needs to be inside an \env{mfpic} environment. Starting with version
1973 0.9 of \mfp{} this is no longer required, but the command name
1974 \cs{mfpbarchart} must be used outside (in case some other package also
1975 defines \cs{barchart}). One can use any of the four synonyms listed that
1976 start with `\cs{mfp}'. The commands to draw the bars are still required to
1977 be inside an \env{mfpic} environment.
1978
1979 \meta{h-or-v} should be \texttt{v} if you want the ends of the bars to
1980 be measured vertically from the $x$-axis, or \texttt{h} if they should
1981 be measured horizontally from the $y$-axis. \meta{list} should be a
1982 comma-separated list of numbers and ordered pairs giving the
1983 end(s) of each bar. A number $c$ is interpreted as the pair $(0,c)$; a
1984 pair $(a,b)$ is interpreted as an interval giving the ends of the bar
1985 (for Gantt diagrams). The rest of this description refers to the
1986 \texttt{h} case; the \texttt{v} case is analogous.
1987
1988 By default the bars are 1 graph unit high (thickness), from $y = n-1$ to
1989 $y = n$. Their width and location are determined by the data. The
1990 optional parameter consists of three numeric parameters separated by
1991 commas. \meta{start} is the $y$-coordinate of the bottom edge of the
1992 first bar, \meta{sep} is the distance between the bottom edges of
1993 successive bars, and \meta{r} is the fraction of \meta{sep} occupied by
1994 each bar. The default behavior corresponds to \texttt{[0,1,1]}. In
1995 general, bar number $n$ will be from $y = \meta{start} +
1996 (n-1)*\meta{sep}$ to $y = \meta{start} + (n-1 + \meta{r})*\meta{sep}$
1997
1998 Notice the bars are numbered in order from bottom to top. You can
1999 reverse them by making \meta{sep} negative, and making \meta{start} the
2000 top edge of the first bar.
2001
2002 The fraction \meta{r} should be between $-1$ and $1$. A negative value
2003 reverses the direction from the ``leading edge'' of the bar to the
2004 `trailing edge'. For example, if one bar chart is created with
2005 \begin{ex}
2006 \cs{barchart}\oarg{1,1,-.4}\marg{h}\marg{$\ldots$}
2007 \end{ex}
2008 and another with
2009 \begin{ex}
2010 \cs{barchart}\oarg{1,1,.4}\marg{h}\marg{$\ldots$}
2011 \end{ex}
2012 both having the same number of bars, then the first will have its first
2013 bar from $y = 1$ to $y = 1 -.4 = .6$, while the second will have its
2014 first bar on top of that one, from $1$ to $1 + .4$. Similarly the next
2015 bars will be above and below $y=2$, etc. This makes it easy to draw bars
2016 next to one another for comparison.
2017
2018 \begin{cd}\pagelabel{chartbar}
2019 \cs{chartbar}\marg{\meta{num}}\\
2020 \cs{graphbar}\marg{\meta{num}}\\
2021 \cs{histobar}\marg{\meta{num}}\\
2022 \cs{ganttbar}\marg{\meta{num}}%
2023 \index{chartbar@\cs{chartbar}}%
2024 \index{graphbar@\cs{graphbar}}%
2025 \index{histobar@\cs{histobar}}%
2026 \index{ganttbar@\cs{ganttbar}}%
2027 \end{cd}
2028
2029 The figure macro \cs{chartbar} (synonyms \cs{graphbar}, \cs{ganttbar},
2030 and \cs{histobar}) takes a number from $1$ to the number of elements in
2031 the list of data of the most recent \cs{barchart} command and produces
2032 the corresponding rectangular path computed by that command. This
2033 behaves just like any other figure macro, and the prefix macros from
2034 section~\ref{rendering} may be used to give adjacent bars contrasting
2035 colors, fills, etc.
2036
2037
2038 \begin{cd}\pagelabel{piechart}
2039 \cs{piechart}\oarg{\meta{dir}\meta{angle}}\marg{\meta{$c$},\meta{$r$}}%
2040 \marg{\meta{list}}\\
2041 \cs{mfppiechart}\dots
2042 \index{piechart@\cs{piechart}}%
2043 \end{cd}
2044
2045 The macro \cs{piechart} also does not draw anything, but computes the
2046 \cs{piewedge} regions described below. The first part of the optional
2047 parameter, \meta{dir}, is a single letter to indicate a direction:
2048 `\texttt{c}' for \emph{clockwise} or `\texttt{a}' for \emph{anticlockwise}.
2049 The \meta{angle} is the angle in degrees of the starting edge of the
2050 first wedge. The defaults correspond to \oarg{c90}, which means the
2051 first wedge starts at 12~o'clock and proceeds clockwise.
2052
2053 The first required argument contains the center \meta{$c$} and radius
2054 \meta{$r$} of the chart. The second required argument is the list of
2055 data: positive numbers separated by commas.
2056
2057 Since this command never actually draws anything, only defining the
2058 wedges, it makes sense to heave it available outside the drawing
2059 environment. Starting with version 0.9 of \mfp{} that is the case, but
2060 the command name is \cs{mfppiechart} (to avoid a name clash with some
2061 other package's \cs{piechart} command). The command to draw wedges
2062 (\cs{piewedge}, see below) is still required to be inside an \env{mfpic}
2063 environment.
2064
2065 \begin{cd}\pagelabel{piewedge}
2066 \cs{piewedge}\oarg{\meta{spec}\meta{trans}}\marg{\meta{num}}%
2067 \index{piewedge@\cs{piewedge}}%
2068 \end{cd}
2069
2070 This figure macro takes a number from $1$ to the number of elements in
2071 the list of data of the most recent \cs{piechart} command and produces
2072 the corresponding wedge-shaped path computed by that command. By
2073 default, the path is positioned as computed by that \cs{piechart}
2074 command, but The optional argument to \cs{piewedge} can override this.
2075 The parameter \meta{spec} is a single letter, which can be \texttt{x},
2076 \texttt{s} or \texttt{m}. The \texttt{x} stands for \emph{exploded} and
2077 it means the wedge is moved directly out from the center of the pie a
2078 distance \meta{trans}. \meta{trans} should then be a pure number and is
2079 interpreted as a distance in graph units. The \texttt{s} stands for
2080 \emph{shifted} and in this case \meta{trans} should be a pair of the
2081 form \texttt{(\meta{dx},\meta{dy})} indicating the wedge should be
2082 shifted \meta{dx} horizontally and \meta{dy} vertically (in graph
2083 units). The \texttt{m} stands for \emph{move to}, and \meta{trans} is
2084 then the absolute coordinates \texttt{(\meta{x},\meta{y})} in the graph
2085 where the point of the wedge should be placed.
2086
2087
2088 \subsection{Braces}
2089
2090 This figure is intended to group some graphical objects and label them.
2091
2092 \begin{cd}\pagelabel{gbrace}
2093 \cs{gbrace}\marg{\meta{$z_1$},\meta{C},\meta{$z_2$}}%
2094 \index{grbace@\cs{gbrace}}%
2095 \end{cd}
2096
2097 This figure macro creates the shape of a brace (i.e., a `$\}$') with its
2098 ends at \meta{$z_1$} and \meta{$z_2$} and its `center' cusp at
2099 \meta{C}. The three points must be expressed as ordered pairs or as
2100 \MF{} pair expressions, and must be separated by commas. The `width' of
2101 the brace (the distance from \meta{C} to the line through the other
2102 two points) is computed automatically and should not be $0$. The cusp of
2103 the brace will not necessarily be in the center of the brace. Users
2104 position it with their choice of \meta{C}. The cusp should not be
2105 positioned too close to one of the endpoints as this can distort the
2106 brace.
2107
2108
2109 \section{Colors in \mfp{}.}\label{colors}
2110
2111 \subsection{\CMP{} color functions}\label{mpcolors}
2112
2113 Because of changes to color handling with \MP{} 1.000, we will have to
2114 give two descriptions of some operations. For brevity, we will refer to
2115 \MP{} versions before the addition of the \kw{cmykcolor} data type as
2116 `early' \MP{} and the versions afterward as `recent' \MP{}. Early \MP{}
2117 actually ended with version 0.642. When development resumed, beta test
2118 versions began with 0.900. Any version 0.900 or later qualifies as
2119 `recent'.
2120
2121 In early \MP{}, the only \kw{color} data type is a triple of numbers
2122 like \mfc{(1,.5,.5)}, with the components between 0 and 1, representing
2123 red, green and blue levels, respectively. White is given by
2124 \mfc{(1,1,1)} and black by \mfc{(0,0,0)}. Recent \MP{} has the
2125 \kw{color} data type (refered to as either \kw{color} or \kw{rgbcolor})
2126 as well as the \kw{cmykcolor} type. A \kw{cmykcolor} is a quadruple of
2127 numbers like \mfc{(1,.2,0,.3)}, with components between 0 and 1
2128 representing levels of cyan, magenta, yellow and black. White is
2129 represented by \mfc{(0,0,0,0)}. While black can be obtained in several
2130 ways,\mfc{(0,0,0,1)} is the simplest.
2131
2132 \CMP{} also has \kw{color} variables (and \kw{cmykcolor} variables) and
2133 several have been predefined. The colors \mfc{red}, \mfc{green},
2134 \mfc{blue}, \mfc{white} and \mfc{black} are built in to \MP{} and are of
2135 type \kw{rgbcolor}. Colors \gbc{cyan}, \gbc{magenta} and \gbc{yellow}
2136 are defined by \mfp{}'s \MP{} support macros to be \kw{cmykcolor}. In
2137 addition, \mfp{} defines \gbc{grayscaleblack}, \gbc{grayscalewhite},
2138 \gbc{cmykblack}, \gbc{cmykwhite}, \gbc{rgbblack} and \gbc{rgbwhite}.
2139 These give black and white in the indicated data type (grayscale being a
2140 numeric: $0$ for black, $1$ for white).
2141
2142 All the names in the \LaTeX{} \prog{color} package's \file{dvipsnam.def}
2143 have also been predefined by \mfp{} as color variable names. Since \MP{}
2144 allows color expressions, colors may be added together (as long as they
2145 are the same type) and multiplied by numerics. Multiplication by a
2146 number between $0$ and $1$ darkens a \kw{rgbcolor}, but lightens a
2147 \kw{cmykcolor}.
2148
2149 Moreover, several \MP{} color functions have been defined in
2150 \file{grafbase.mp}. These have the same names as the color models.
2151 Strictly speaking, it is never necessary to use these in recent \MP{}.
2152 However, since \MF{} and early \MP{} don't have a data type consisting
2153 of quadruples, and \MF{} doesn't have one for triples, these functions
2154 allow the same \mfp{} code to be used for all three figure processors.
2155 These functions are defined to convert to a usable data type, (which may
2156 be ignored in \MF{}).
2157
2158 \begin{cd}
2159 \mfc{cmyk($c$,$m$,$y$,$k$)}%
2160 \index{cmyk@\mfc{cmyk($c$,$m$,$y$,$k$)}}
2161 \end{cd}
2162
2163 In early \MP{}, this converts a cmyk color specification to \MP{}'s
2164 native rgb. For example, the command \mfc{cmyk(1,0,0,0)} yields
2165 \mfc{(0,1,1)}, which is the rgb equivalent of cyan. In recent \MP{} this
2166 produces the \kw{cmykcolor} with the given components. That is,
2167 \gbc{cmyk(1,0,0,0)} simply produces $(1,0,0,0)$, the cmyk coding for
2168 cyan.
2169
2170 \begin{cd}
2171 \mfc{gray($g$)}%
2172 \index{gray@\mfc{gray($g$)}}
2173 \end{cd}
2174
2175 In early \MP{}, this converts a numeric $g$ (designating a level of
2176 gray) to the corresponding multiple of white: \mfc{($g$,$g$,$g$)}. In
2177 recent \MP{}, commands to draw paths or pictures in a particular color
2178 will accept a \kw{numeric} parameter instead of \kw{color} or
2179 \kw{cmykcolor}, so in recent \MP{} this command simply returns the given
2180 numeric $g$.
2181
2182 \begin{cd}
2183 \mfc{named(\meta{name})},
2184 \mfc{rgb($r$,$g$,$b$)}%
2185 \index{named@\mfc{named(\meta{name})}}%
2186 \index{rgb@\mfc{rgb($r$,$g$,$b$)}}
2187 \end{cd}
2188
2189 These are essentially no-ops. However; \mfc{rgb()} will truncate the
2190 arguments to the 0--1 range, and set an unknown argument to 0. An
2191 unknown \meta{name} is converted to \mfc{black} (in the appropriate
2192 color model if \meta{name} is an unknown color variable, otherwise rgb
2193 black).
2194
2195 \begin{cd}
2196 \mfc{RGB($R$,$G$,$B$)}%
2197 \index{RGB@\mfc{RGB($R$,$G$,$B$)}}
2198 \end{cd}
2199
2200 Converts an RGB color specification to rgb. It divides each component by
2201 255, and performs the same truncations as \gbc{rgb()}. The RGB model
2202 consists of a triple of numbers between 0 and 255. Originally, the model
2203 required they be integers. However, since they are converted to
2204 fractions anyway, it doesn't matter in this command.
2205
2206 \medskip
2207 As an example of the use of these functions, in early \MP{} one could
2208 conceivable write:
2209 %
2210 \begin{verbatim}
2211 \draw[0.5*RGB(255,0,0)+0.5*cmyk(1,0,0,0)]\circle{(0,0),1}
2212 \end{verbatim}
2213 %
2214 to have a circle drawn in a color halfway between red and cyan (which
2215 turns out to be the same as \gbc{gray(0.5)}). In recent \MP{}, however,
2216 this would be an error, as one cannot add two different data types
2217 (\kw{rgbcolor} and \kw{cmykcolor}). So \mfp{} supplies conversion functions.
2218
2219 \begin{cd}
2220 \mfc{makecmyk \meta{clr}}\\
2221 \mfc{makergb \meta{clr}}\\
2222 \mfc{makegray \meta{clr}}%
2223 \index{makecmyk@\mfc{makecmyk}}%
2224 \index{makergb@\mfc{makergb}}%
2225 \index{makegray@\mfc{makegray}}
2226 \end{cd}
2227
2228 In recent \MP{}, the \meta{clr} can be a known color name, a constant
2229 of type \kw{numeric}, \kw{rgbcolor}, or \kw{cmykcolor}, or the result of
2230 a color function. Then \mfc{makecmyk} returns the \kw{cmykcolor}
2231 equivalent, and \mfc{makergb} returns the \kw{rgbcolor} equivalent (a
2232 \kw{numeric} \meta{clr} is interpreted as a grayscale color). Unknown
2233 colors produce a black in the appropriate model. Then one can use
2234 %
2235 \begin{verbatim}
2236 \draw{.5*RGB(255,0,0) + .5*makergb cmyk(1,0,0,0)}\circle{(0,0),1}
2237 \end{verbatim}
2238 %
2239 If one has forgotton whether \mfc{RGB} returns an \kw{rgbcolor}, one
2240 could write \verb$makergb RGB(255,0,0)$ to be sure to get an
2241 \kw{rgbcolor}.
2242
2243 The first two commands are never necessary in early \MP{}, but they are
2244 still defined: they simply return the given color if it is a known
2245 argument of type \kw{color}, or apply the function \gbc{gray()} is it is
2246 \kw{numeric}, and return black for an unknown name.
2247
2248 The last one \gbc{makegray} converts any color to a numeric, and then
2249 returns either that number (recent \MP) or that multiple of \mfc{white}
2250 (early \MP). In \MF{}, all three pass the (presumably numeric) argument
2251 \meta{clr} unchanged.
2252
2253 All three functions return some version of black if \meta{clr} is not a
2254 color of some type, or has an unknown value.
2255
2256
2257 \subsection{Establishing \mfp{} default colors}\label{defaultcolors}
2258
2259 \begin{cd}\pagelabel{drawcolor}
2260 \cs{drawcolor}\oarg{\meta{model}}\marg{\meta{colorspec}}\\
2261 \cs{fillcolor}\oarg{\meta{model}}\marg{\meta{colorspec}}\\
2262 \cs{hatchcolor}\oarg{\meta{model}}\marg{\meta{colorspec}}\\
2263 \cs{pointcolor}\oarg{\meta{model}}\marg{\meta{colorspec}}\\
2264 \cs{headcolor}\oarg{\meta{model}}\marg{\meta{colorspec}}\\
2265 \cs{tlabelcolor}\oarg{\meta{model}}\marg{\meta{colorspec}}\\
2266 \cs{backgroundcolor}\oarg{\meta{model}}\marg{\meta{colorspec}}%
2267 \index{drawcolor@\cs{drawcolor}}%
2268 \index{fillcolor@\cs{fillcolor}}%
2269 \index{hatchcolor@\cs{hatchcolor}}%
2270 \index{pointcolor@\cs{pointcolor}}%
2271 \index{headcolor@\cs{headcolor}}%
2272 \index{tlabelcolor@\cs{tlabelcolor}}%
2273 \index{backgroundcolor@\cs{backgroundcolor}}%
2274 \end{cd}
2275
2276
2277 These macros set the default color for various drawing elements. Any
2278 curve (with one exception, those drawn by \cs{plotdata}), whether solid,
2279 dashed, dotted, or plotted in symbols, will be in the color set by
2280 \cs{drawcolor}. Set the color used by \cs{gfill} with \cs{fillcolor}.
2281 For all the hatching commands use \cs{hatchcolor}. For the \cs{point},
2282 and \cs{plotsymbol} commands, as well as \cs{gridpoints} and
2283 \cs{plrgridpoints}, use \cs{pointcolor}, and for arrowheads,
2284 \cs{headcolor}. One can set the color used by \cs{gclear} with
2285 \cs{backgroundcolor} (the same color will also be used in the interior
2286 of unfilled points that are drawn with \cs{point}) and, when
2287 \opt{mplabels} is in effect, the color of labels can be set with
2288 \cs{tlabelcolor}.
2289
2290 The optional \meta{model} may be one of \texttt{rgb}, \texttt{RGB},
2291 \texttt{cmyk}, \texttt{gray}, and \texttt{named}. The \meta{colorspec}
2292 depends on the model, as outlined below. Each of these commands sets a
2293 corresponding \MP{} color variable with the same name (except
2294 \cs{backgroundcolor} sets the color named \mfc{background}). Thus, after
2295 \texttt{drawcolor} has been set, one can issue the command
2296 \cs{fillcolor}\marg{drawcolor} to fill with the same color.
2297
2298 As previously discussed, all these colors are initially set to
2299 \mfc{black} except \mfc{background} is set to \mfc{white}.
2300
2301 If the optional \meta{model} argument is omitted, the color
2302 specification may be any expression recognized as a color by \MP{}. It
2303 is highly recommended (for portability) that one use either a predefined
2304 name or one of the color functions of the previous section.
2305
2306 When the optional \meta{model} is specified in the color setting
2307 commands, it determines the format of the color specification as in
2308 figure~\ref{fig:colorspecs}.
2309
2310 \begin{figure}[hbt]
2311 \halign{\quad\texttt{#}\hfil\quad&#\hfil\cr
2312 \omit\quad{\slshape Model:}\hfil& {\slshape Specification:}\cr
2313 rgb & Three numbers in the range 0 to 1 separated by commas.\cr
2314 RGB & Three numbers in the range 0 to 255 separated by commas.\cr
2315 cmyk & Four numbers in the range 0 to 1 separated by commas.\cr
2316 gray & One number in the range 0 to 1, with 0 indicating
2317 black, 1 white.\cr
2318 named & A \MP{} color variable name either predefined by
2319 \mfp{} or by the user.\cr}
2320 \caption{Color specifications}
2321 \label{fig:colorspecs}
2322 \end{figure}
2323
2324 \pagebreak[3]
2325 \Mfp{} translates the command:
2326 \begin{verbatim}
2327 \fillcolor[cmyk]{1,.3,0,.2}
2328 \end{verbatim}
2329 into the equivalent of:
2330 \begin{verbatim}
2331 \fillcolor{cmyk(1,.3,0,.2)}.
2332 \end{verbatim}
2333 Note that when the optional model is specified, the color specification
2334 must \emph{not} be enclosed in parentheses. Note also that each model
2335 name is the name of a color function described in the previous
2336 subsection. That is how the models are implemented internally. One sees
2337 from this that the optional argument is never necessary. It's there only
2338 to make the \LaTeX{} user comfortable.
2339
2340
2341 \subsection{Defining a color name}\label{colorname}
2342
2343 \begin{cd}\pagelabel{mfpdefinecolor}
2344 \cs{mfpdefinecolor}\marg{\meta{name}}\marg{\meta{model}}\marg{\meta{colorspec}}%
2345 \index{mfpdefinecolor@\cs{mfpdefinecolor}}
2346 \end{cd}
2347
2348 This defines a color variable \meta{name} for later use, either in the
2349 commands \cs{drawcolor}, etc., or in the optional parameters to
2350 \cs{draw}, etc. The name can be used alone or in the \texttt{named} model.
2351 The mandatory \meta{model} and \meta{colorspec} are as above.
2352
2353 \medskip
2354 A final caution, the colors of an \mfp{} figure are stored in the
2355 \file{.mp} output file, and are not related to colors used or defined by
2356 any \LaTeX{} package (such as \prog{color} or \prog{xcolor}). In
2357 particular a color defined only by \LaTeX{}'s \cs{definecolor} command
2358 will remain unknown to \mfp{}. Conversely, \LaTeX{} commands will not
2359 recognize any color defined only by \cs{mfpdefinecolor}.
2360
2361
2362 \subsection{\CMF{} colors}\label{MFcolor}
2363
2364 \CMF{} was never meant to understand colors, but it certainly can be
2365 taught the difference between black and white and, to a limited extent,
2366 various grays. Starting with version 0.7, \mfp{} will not generate
2367 an error when a color-changing command is used under the \opt{metafont}
2368 option. Instead, when possible, the variables that represent colors in
2369 \MP{} will be converted to a numeric value between 0 and 1 in \MF{}. When
2370 possible (for example, when a region is filled) the numeric will be
2371 interpreted as a gray level and shading (see subsection~\ref{filling})
2372 will be used to approximate the gray. In other cases (drawing or dashing
2373 of curves, placing of points or symbols, filling with a pattern of hatch
2374 lines) the number will be interpreted as black or white: a value less
2375 than 1 will cause the figure to be rendered in black, while a value
2376 equal to 1 (white) will cause pixels corresponding to the figure to be
2377 erased.
2378
2379 This depends on adhering to certain restrictions. \CMF{}'s syntax
2380 does not recognize a triple of numbers as any sort of data structure,
2381 but it does allow \emph{commands} to have any number of parameters in
2382 parentheses. So colors must be specified using the color commands such
2383 as \gbc{rgb(1,1,0)} or color names such as \gbc{yellow}, and never as a
2384 bare triple. Also, as currently written, the color names defined in
2385 \file{dvipsnam.mp} are not defined in \MF{}. With these provisions the
2386 same \mfp{} code can often produce either gray scale \MF{} pictures or
2387 \MP{} color pictures depending only on the \opt{metapost} option.
2388
2389 The commands \cs{shade} and \cs{gfill}\oarg{gray(.75)} (see
2390 subsection~\ref{filling} for their meaning) will produce a similar shade
2391 of gray, but there is a difference. The first simply adds small dots on
2392 top of whatever is already drawn. The second, however, tries to simulate
2393 the \MP{} effect, which is to cover up whatever is previously drawn.
2394 Therefore, it first erases all affected pixels before adding the dots to
2395 simulate gray. In particular, \cs{gfill}\oarg{white} should have the
2396 same effect as \cs{gclear}.
2397
2398
2399 \section{Modifying the figures.}\label{modifier}
2400
2401 Some \mfp{} macros operate by \emph{modifying} a figure macro: if you
2402 want to turn an open arc into a closed figure by adding a straight line,
2403 you can write:
2404 \begin{ex}
2405 \cs{lclosed}\cs{arc}\marg{(0,0),(1,0),45}.
2406 \end{ex}
2407 These are always prefixed to some figure drawing command, and apply only
2408 to the next following figure macro provided that only other prefix
2409 commands intervene. This is a rather long section, but even more
2410 modification prefixes are documented in subsection~\ref{transformation}.
2411
2412 The combination of a modifying macro, followed by a figure macro, can
2413 usually be thought of as a new figure macro, to which further prefixes
2414 might be prepended.
2415
2416 More precisely: all prefix macros have an \emph{input} path, an
2417 \emph{output} path, and a \emph{side effect}. The input is the path that
2418 is output by the \emph{following} prefix or figure macro. The output is
2419 either the same as the input or a modification of it. The side effect
2420 might be a drawing or filling of the path or the addition of an
2421 arrowhead.
2422
2423 We list here a classifications of prefix and figure macros that is
2424 useful for understanding the \mfp{} system.
2425
2426 \begin{description}
2427
2428 \item[Figure macros.] These\index{figure macro} take no input path; they
2429 must come last in a sequence. They output the path they were
2430 designed to produce. Examples are \cs{circle}, \cs{rect} and
2431 \cs{polygon}. If they have no prefixes, or are preceded only by
2432 appending macros (see next), they invoke a default rendering of the
2433 path (usually a drawing as a solid stroke) as the side effect.
2434
2435 \item[Appending macros] These\index{prefix macro} pass their input
2436 unchanged as their output. Their side effect is the appending of
2437 some object such as an arrow head or tail. Currently only the
2438 various prefix macros whose names begin with \texttt{arrow} are
2439 appending macros (see subsection~\ref{arrows}). But \cs{reverse},
2440 which technically modifies a path and has no side effect, is coded
2441 as an appending macro so that it will work correctly with arrows.
2442 Think of it as `appending' a new direction.
2443
2444 \item[Rendering macros] These\index{prefix macro} pass their
2445 input unchanged as their output. They have the side effect of adding
2446 or subtracting ink from a picture in the shape of the input path.
2447 Examples are \cs{draw}, \cs{dotted}, \cs{gfill} and \cs{gclip}.
2448
2449 \item[Modifying macros] These\index{prefix macro} output the result of
2450 applying their intended modification to the input path. Examples are
2451 macros that close the path if it was open, macros that apply a
2452 transformation such as a rotation, and macros that return only a
2453 part of a path. If they have no prefixes, or are preceded only by
2454 appending macros (see above), they also invoke a default rendering
2455 of the output path (usually a drawing as a solid stroke of the
2456 modified path) as the side effect.
2457
2458 \end{description}
2459
2460
2461 \subsection{Closure of paths}\label{closure}
2462
2463 It should be pointed out that the closure macros will leave already
2464 closed paths unchanged, so it is always safe to add one when uncertain.
2465 Moreover, if the path is not closed but the endpoints are identical,
2466 \cs{lclosed} and \cs{bclosed} will close it without adding any path segment.
2467
2468
2469 \begin{cd}\pagelabel{lclosed}
2470 \cs{lclosed}$\ldots$\\
2471 \cs{bclosed}\oarg{\meta{tens}}$\ldots$\\
2472 \cs{sclosed}\oarg{\meta{tens}}$\ldots$%
2473 \index{lclosed@\cs{lclosed}}
2474 \index{bclosed@\cs{bclosed}}%
2475 \index{sclosed@\cs{sclosed}}
2476 \end{cd}
2477
2478 These modifying macros all turn an open path into a closed one. If the
2479 path is already closed, they do nothing.
2480
2481 \cs{lclosed} makes an open path into a closed path by adding a line
2482 segment between the endpoints of the path. In the special case where
2483 the path ends exactly where it begins, all \cs{lclosed} does is change
2484 the type of the path from open to closed.
2485
2486 The \cs{bclosed} macro is similar to \cs{lclosed}, except that it closes
2487 an open path smoothly by drawing a B\'ezier curve. A B\'ezier is \MF{}'s
2488 natural way of connecting points into a curve, and \cs{bclosed} is the
2489 simplest and most efficient closure next to \cs{lclosed}. Moreover it
2490 usually gives a reasonably aesthetic result. Sometimes, however, one
2491 might wish a tighter connection. If that is the case, use the optional
2492 argument with a value of the tension \meta{tens} greater than $1$, the
2493 default. The command \cs{settension} (see subsection~\ref{curves}) can
2494 be used to change the default.
2495
2496 \cs{sclosed} closes the curve by mimicking the definition of the
2497 \cs{curve} command. That command tries to force the curve to pass
2498 through the $n$th point in a direction parallel to the line from point
2499 $(n-1)$ to point $(n+1)$. In order to close a curve in this way, the
2500 direction at the two endpoints often has to be changed, and this changes
2501 the shape of the first and last segments of the curve. Use \cs{bclosed}
2502 if you don't wish this to happen. However, \cs{sclosed}\cs{curve}
2503 produces a result almost identical to \cs{cyclic} given the same points
2504 and tension values. The optional tension argument is as in the
2505 \cs{bclosed} command.
2506
2507 There are two other closure commands but, because they are associated
2508 with particular types of paths (splines), we delay their discussion
2509 until those are discussed (subsection~\ref{splines}).
2510
2511 \begin{cd}\pagelabel{makesector}
2512 \cs{makesector}\cs{arc}[\meta{fmt}]\marg{\meta{spec}}%
2513 \index{makesector@\cs{makesector}}
2514 \end{cd}
2515
2516 The modifying macro \cs{makesector} can be applied to any path, but its
2517 name makes sense (and its action is predictable) only if that path is an
2518 arc. It appends line segments from the center of the arc's circle to the
2519 ends of the arc, producing a closed path. It is useful if one doesn't
2520 know where the center of the arc is (a required parameter of
2521 \cs{sector}). It works by selecting the first point, a middle point, and
2522 the last point of the following path, then calculates the center of the
2523 circle through those three points.
2524
2525
2526 \subsection{Reversal, connection and other path modifications}%
2527 \label{reversal}
2528
2529 \begin{cd}\pagelabel{reverse}
2530 \cs{reverse}$\ldots$\\
2531 \cs{reversepath}\ldots%
2532 \index{reverse@\cs{reverse}}
2533 \index{reversepath@\cs{reversepath}}
2534 \end{cd}
2535
2536 This modifies the following path by reversing its sense. This will
2537 affect the direction of arrows: bi-directional arrows can be coded with
2538 \cs{arrow}\cs{reverse}\cs{arrow}$\ldots$, where the leftmost \cs{arrow}
2539 prefix applies to the \emph{reversed} path. The order of endpoints for
2540 a \env{connect} environment will also be affected. The command
2541 \cs{reversepath} is exactly the same. It has been added (in vresion 1.10) to
2542 more closely match the names of other modification macros (see
2543 subsection~\ref{transformation}).
2544
2545 \begin{cd}\pagelabel{connect}
2546 \cs{connect} $\ldots$ \cs{endconnect}%
2547 \index{connect@\cs{connect}}%
2548 \index{endconnect@\cs{endconnect}}
2549 \end{cd}
2550
2551 The macro \cs{connect} produces a connected path by joining all the
2552 paths following it up to the matching \cs{endconnect} command. Line
2553 segments are added from the end of one path to the start of the next.
2554 The whole group acts as one figure macro, permitting any prefix macros
2555 to come before.
2556
2557 In \LaTeX{}, instead of this pair of macros, an environment named
2558 \env{connect} may be used. For example
2559 \begin{verbatim}
2560 \lclosed
2561 \begin{connect}
2562 \curve{(2,1),(1,2),(0,1)}
2563 \polyline{(0,0),(2,0)}
2564 \end{connect}
2565 \end{verbatim}
2566 produces a closed figure consisting of one smooth curve and three line
2567 segments: the segment produced by \cs{polyline}, the segment added by
2568 the \env{connect} environment, and the segment added by \cs{lclosed}.
2569
2570
2571 \begin{cd}\pagelabel{partpath}
2572 \cs{partpath}\marg{\meta{frac1},\meta{frac2}}\dots\\
2573 \cs{subpath}\marg{\meta{num1},\meta{num2}}\dots\\
2574 \cs{trimpath}\marg{\meta{dim$_1$},\meta{dim$_2$}}\dots\\
2575 \cs{trimpath}\marg{\meta{dim}}\dots%
2576 \index{partpath@\cs{partpath}}%
2577 \index{subpath@\cs{subpath}}%
2578 \index{trimpath@\cs{trimpath}}%
2579 \end{cd}
2580
2581 These macros modify the following path by producing only a part of it. In
2582 \cs{partpath} the parameters \meta{frac1} and \meta{frac2} should be
2583 numbers between 0 and 1. The path produced travels the same course as
2584 the path that follows, but starts at the point that is the fraction
2585 \meta{frac1} of the original length along it, and ends at the point
2586 \meta{frac2} of its original length. If \meta{frac1} is greater than
2587 \meta{frac2}, the sense of the path is reversed. In \cs{subpath}, the
2588 two numbers should be between 0 and the number of B\'ezier segments in
2589 the path. This is mainly for experienced \MF{}ers and provides an \mfp{}
2590 interface to \MF{}'s `\mfc{subpath}' operation.
2591
2592 The \cs{trimpath} macro takes two dimensions separated by commas and
2593 trims those lengths off the initial and terminal ends of the following path.
2594 Alternatively, it takes one dimension and and trims that length off of
2595 both ends. If any of \meta{dim$_1$}, \meta{dim$_2$} or \meta{dim} is
2596 missing, it is taken to be \dim{0pt}. This works by finding the points of
2597 intersection between the path and circles around the endpoints with the given
2598 dimensions as radii. If the path is shorter than either dimension, it
2599 will not intersect either circle and nothing will be trimmed. Similar
2600 problems can occur, at one end or the other, if the path is shorter than
2601 the sum of the dimensions.
2602
2603 \begin{cd}\pagelabel{parallelpath}
2604 \cs{parallelpath}\marg{\meta{dist}}$\ldots$
2605 \index{parallelpath@\cs{parallelpath}}
2606 \end{cd}
2607
2608 This modifying macro takes the following path and returns a path that
2609 follows beside it, keeping a fixed distance \meta{dist} to the left. If
2610 \meta{dist} is negative, it keeps to the right. Left or right is from
2611 the point of view of a traveller following the given path from start to
2612 finish. The distance is a pure number in \emph{graph} coordinates. Note:
2613 this should be compared to the first optional argument of
2614 \cs{doubledraw} (see subsection~\ref{drawing}), which requires an
2615 absolute dimension like \dim{2pt}, even though it is implemented using
2616 the internal code of \cs{parallelpath}.
2617
2618 The calculation of the parallel path is approximate and rather
2619 inefficient. It is likely to produce inexplicable small loops where it
2620 tries to follow the inside of tight turns (radius less than
2621 \meta{dist}). Actual corners, (which might be thought of as turns of
2622 radius $0$) are usually detected and dealt with in a reasonable manner.
2623 However, if the path is made up of segments of length \meta{dist} or
2624 less, this is unlikely to work correctly at all.
2625
2626 \begin{cd}\pagelabel{arccomplement}
2627 \cs{arccomplement}\dots%
2628 \index{arccomplement@\cs{arccomplement}}
2629 \end{cd}
2630
2631 This macro, to work properly, must be followed by an arc of a circle. It
2632 produces the complementary arc. That is, it produces the circular arc,
2633 which would, if appended to the following arc, complete the circle. The
2634 complementary arc will have the same direction, clockwise or
2635 anticlockwise, as the original. The arc that follows doesn't have to be
2636 produced by \cs{arc}, as in the following example:
2637 \begin{ex}
2638 \cs{draw}\oarg{blue}\cs{arccomplement}\\
2639 \ \cs{draw}\oarg{red}\cs{partpath}\marg{0,.333}\\
2640 \ \cs{circle}\marg{(0,0),1}
2641 \end{ex}
2642 This will draw 1/3 of this circle in red and the rest of it in blue.
2643
2644 \CMF{} cannot check if a path is really a circular arc. The \MF{} code,
2645 like that of \cs{makesector} (see subsection~\ref{closure}), selects
2646 three key points on the arc, then it produces the rest of the circle
2647 much the same way as the internal code of \cs{arc}\oarg{t} (the three
2648 point option for \cs{arc}). Thus, it will produce \emph{some} arc from
2649 the end of any following path to its beginning (or a straight line if
2650 the three chosen points happen to lie in a straight line). However, the
2651 result needn't bear any significant relation to the original path.
2652
2653 \begin{cd}\pagelabel{interpolatepath}
2654 \cs{interpolatepath}\marg{\meta{frac},\meta{path1}}\dots
2655 \index{interpolatepath@\cs{interpolatepath}}
2656 \end{cd}
2657
2658 This modifying macro takes the following path (call it \meta{path0}) and
2659 computes a new path that is \meta{frac} of the way ``between'' it and
2660 the argument \meta{path1}. The argument \meta{path1} would usually be
2661 the name of a \MF{} path variable used to store a figure (see \cs{store}
2662 from subsection~\ref{transformation}). However it can actually be any
2663 legal \MF{} path expression. The argument \meta{frac} is a number. If
2664 \meta{frac} is $0$, nothing is done and the following path \meta{path0}
2665 is produced; if \meta{frac} is $1$, then the argument \meta{path1} is
2666 produced. For values of \meta{frac} between $0$ and $1$ the resulting
2667 path is somewhere between the two. Numbers larger than $1$ or less than
2668 $0$ produce an extrapolated path. An ordered pair can be supplied
2669 instead of the argumant \meta{path1}: it will be interpreted as a
2670 trivial path. If \meta{path0} (the following figure) is closed and if
2671 \meta{path1} is an ordered pair or a closed path, then the resulting
2672 path will also be closed. Otherwise it will not be.
2673
2674 What this command actually interpolates are the key points of the paths
2675 and the directions of travel at those key points. Therefore, if the two
2676 paths are visually very similar but have very different node structure,
2677 then the interpolated path can be quite unexpectedly different from both
2678 of them. For example
2679 \begin{verbatim}
2680 \store{ABC}\circle{(0,0),1}
2681 \interpolatepath{.5,ABC}\reverse\circle{(0,0),1}
2682 \end{verbatim}
2683 produces a straight line from $(1,0)$ to $(-1,0)$ (and back again).
2684
2685
2686
2687 \subsection{Arrows}\label{arrows}
2688
2689 \begin{cd}\pagelabel{arrow}
2690 \cs{arrow}\oarg{l\meta{headlen}}\oarg{r\meta{rotate}}%
2691 \oarg{b\meta{backset}}\oarg{c\meta{color}}$\ldots$\\
2692 \cs{arrow*}\oarg{l\meta{headlen}}\oarg{r\meta{rotate}}%
2693 \oarg{b\meta{backset}}\oarg{c\meta{color}}$\ldots$%
2694 \index{arrow@\cs{arrow}}
2695 \end{cd}
2696
2697 This macro adds an arrowhead at the endpoint of the open path (or at the
2698 last key point of the closed path) that follows. The optional parameter
2699 \meta{headlen} determines the length of the arrowhead. The default is
2700 the value of the \TeX{} dimension \cs{headlen}, initially \dim{3pt}. The
2701 optional parameter \meta{rotate} allows the arrowhead to be rotated
2702 anticlockwise around its point an angle of \meta{rotate} degrees. The
2703 default is 0. The optional parameter \meta{backset} allows the arrowhead
2704 to be ``set back'' from its original point, thus allowing (for example)
2705 double arrowheads. This parameter is in the form of a \TeX{}
2706 dimension---its default value is \dim{0pt}. If an arrowhead is both
2707 rotated and set back, it is set back in the direction after the
2708 rotation. The optional \meta{color} defaults to \gbc{headcolor},
2709 initially black. The optional parameters may appear in any order, the
2710 indicated key character determining the meaning of a parameter. The key
2711 letter \texttt{l} for `length' can be replaced by \texttt{s} for `size'.
2712
2713 There is also a star-form: If \cs{arrow} is called as \cs{arrow*}, then
2714 any part of the tip of the following curve that lies outside the
2715 arrowhead shape is clipped off. Imagine a rectangle with one side
2716 connecting the ends of the barbs and the opposite side passing through
2717 the tip. Everything in that rectangle outside the arrowhead is erased,
2718 so be careful using this (also see comments about \MP{}'s method of
2719 `erasing' in the description of \cs{gclear} in
2720 \cs{}subsection~\ref{filling}). One use of this is adding an arrowhead
2721 to a figure rendered with \cs{doubledraw} (see the next section) or with
2722 a rather large pen diameter (see section~\ref{parameters}).
2723
2724 For the star-form to work, the head has to be added after the path is
2725 drawn. What this means in practice is that the \cs{arrow*} command must
2726 come before any drawing command in the list of prefixes. This is because
2727 prefix macros add their elements to the result of everything that
2728 follows. If you \cs{store} a curve in a path variable (see
2729 subsection~\ref{transformation}), and draw the path and the arrowhead in
2730 separate commands, then the arrow command must come \emph{after} the
2731 drawing command.
2732
2733 \begin{cd}\pagelabel{arrowhead}
2734 \cs{arrowhead}\marg{\meta{symbol}}\oarg{l\meta{length}}\oarg{r\meta{rotate}}%
2735 \oarg{b\meta{backset}}\oarg{c\meta{color}}$\ldots$\\
2736 \cs{arrowmid}\marg{\meta{symbol}}\oarg{l\meta{length}}\oarg{r\meta{rotate}}%
2737 \oarg{f\meta{fraction}}\oarg{c\meta{color}}$\ldots$\\
2738 \cs{arrowtail}\marg{\meta{symbol}}\oarg{l\meta{length}}\oarg{r\meta{rotate}}%
2739 \oarg{f\meta{forward}}\oarg{c\meta{color}}$\ldots$%
2740 \index{arrowhead@\cs{arrowhead}}%
2741 \index{arrowmid@\cs{arrowmid}}%
2742 \index{arrowtail@\cs{arrowtail}}
2743 \end{cd}
2744
2745 These macros add some sort of symbol at different locations along a
2746 path. The first adds an arrowhead, but the head can be any appropriately
2747 designed symbol. It has been arranged that any of the symbols usable in
2748 \cs{plotsymbol} (see subsection~\ref{points}) can be used: you can have
2749 \gbc{Diamond}- or \gbc{Asterisk}-tipped arrows. The special symbol
2750 \gbc{Arrowhead} produces the same shape as the head in the \cs{arrow}
2751 command. In total eight special \meta{symbols} have been made available,
2752 intended for use with \cs{arrowhead}, \cs{arrowmid} and \cs{arrowtail}.
2753 Here is a list and description of all these symbols.
2754 \begin{description}
2755 \item[\gbc{Arrowhead}] The\index{Arrowhead@\gbc{Arrowhead}} shape that
2756 would be drawn at the end of a path by \cs{arrow}.
2757 \item[\gbc{Leftharpoon}] The\index{Leftharpoon@\gbc{Leftharpoon}} left
2758 half of \gbc{Arrowhead}.
2759 \item[\gbc{Rightharpoon}] The\index{Rightharpoon@\gbc{Rightharpoon}}
2760 right half of \gbc{Arrowhead}.
2761 \item[\gbc{Crossbar}] A\index{Crossbar@\gbc{Crossbar}} short
2762 line crossing the path perpendicularly unless rotated.
2763 \item[\gbc{Leftbar}] Essentially\index{Leftbar@\gbc{Leftbar}} the left
2764 half of \gbc{Crossbar}.
2765 \item[\gbc{Rightbar}] The\index{Rightbar@\gbc{Rightbar}} right half.
2766 \item[\gbc{Lefthook}] An\index{Lefthook@\gbc{Lefthook}} open
2767 semicircle with its open face in the direction of the path, added to
2768 the left side of the path.
2769 \item[\gbc{Righthook}] Like\index{Righthook@\gbc{Righthook}}
2770 \gbc{Lefthook} but on the right side.
2771 \end{description}
2772 Here `left' and `right' are from the point of view of an observer facing
2773 in the direction of the path.
2774
2775 If the symbol is a closed path (see subsection~\ref{closure} for the
2776 difference between a closed path and one that merely looks closed), the
2777 head will be filled, otherwise its outline will be drawn. Thus
2778 \cs{arrowhead}\marg{Diamond} draws an outline, and
2779 \cs{arrowhead}\marg{SolidDiamond} draws a filled shape because
2780 \gbc{Diamond} has been left open, while \gbc{SolidDiamond} has been
2781 defined to be closed.
2782
2783 It is possible, to get an outline drawn with the inside erased: just
2784 place the solid version with color \mfc{background} (usually the same as
2785 \mfc{white}) and then the outline version. This can produce a pleasing
2786 result. But recall that the prefix macro nearest the figure macro is
2787 executed first. For example:
2788 %
2789 \begin{verbatim}
2790 \arrowmid{Circle}\arrowmid{SolidCircle}[cwhite]\polyline{(0,0),(1,1)}
2791 \end{verbatim}
2792
2793 The symbol is always rotated so that it points in the direction of the
2794 path (for this purpose, all symbols are initially assumed to point
2795 straight upward) before the \oarg{r\meta{rotate}} parameter is applied.
2796
2797 There is a star-form \cs{arrowhead*} that behaves like \cs{arrow*} (when
2798 possible). The optional arguments are exactly as in \cs{arrow}, with the
2799 same defaults for all of them.
2800
2801 The second command, \cs{arrowmid}, places the symbol somewhere between
2802 the start and the end of the path. In this case the optional parameter
2803 \oarg{f\meta{fraction}} gives the location of the symbol as a fraction
2804 of the length of the path. The default is \oarg{f0.5}, which places it
2805 approximately in the middle. The other optional arguments have the same
2806 meaning as for \cs{arrowhead}. As with \cs{arrowhead}, the symbol is
2807 rotated to `point' in the direction of the path before the
2808 \oarg{r\meta{rotate}} is applied.
2809
2810 The third command \cs{arrowtail} places the symbol at the start of the
2811 path. Otherwise it behaves as the other two commands, except the option
2812 \oarg{f\meta{forward}} is an amount to shift the symbol forward from
2813 that first point.
2814
2815 One might be tempted to use \cs{arrowmid} with the \meta{fraction} equal
2816 to $1$ or $0$ to get arrowheads or tails. This will work sometimes.
2817 However, some shapes have a `tip', that is, a particular point
2818 designated as the tip of the arrowhead. The \cs{arrowhead} and
2819 \cs{arrowtail} commands pay attention to this, while \cs{arrowmid} does
2820 not. Also, \cs{arrowmid} has no star-form.
2821
2822 You can design your own \meta{symbol} for these commands: use \cs{store}
2823 to store a path in a path variable (see
2824 subsection~\ref{transformation}). These commands assume that the length
2825 is $1$, that the symbol `points' up and that the `tip' (the `pointy
2826 end') is at $(0,0)$ (unless the pair variable \meta{symbol}\gbc{.tip} is
2827 defined, in which case that is taken to be the tip). So draw your symbol
2828 pointing up with its tip at $(0,0)$ and its length equal to $1$ (graph
2829 unit). For example the following produces a solid head with a common
2830 shape:
2831 \begin{verbatim}
2832 \store{myAH}\polygon{(-.5,-1)(0,0),(0.5,-1),(0,-.7)}
2833 \arrowhead{myAH}\arc{(-10,0),(10,0),90}
2834 \end{verbatim}
2835 If you replace the \cs{polygon} above with \cs{polyline}:
2836 \begin{verbatim}
2837 \store{myAH}\polyline{(-.5,-1)(0,0),(0.5,-1),(0,-.7),(-.5,-1)}
2838 \end{verbatim}
2839 the path will not be closed and so the arrowhead will not be filled in.
2840
2841 To make the star-form work with such self-defined symbols, one must also
2842 define a closed path \gbc{myAH.clear} that gives the region to be
2843 erased. In the above example:
2844 \begin{verbatim}
2845 \store{myAH.clear}\polygon{(-.5,-1),(-.5,0),(.5,0),(.5,-1),(0,-.7)}
2846 \end{verbatim}
2847
2848
2849 \section{Rendering figures.}\label{rendering}
2850
2851 When \mfp{} is loaded, the initial way in which figures are drawn is
2852 with a solid outline. That is, \cs{polyline}\marg{(1,0),(1,1),(0,0)} will
2853 draw two solid lines connecting the points. It is possible to establish
2854 a different default (see \cs{setrender} in subsection~\ref{default}),
2855 however that default is used only when no explicit rendering prefix is
2856 present. That is, when the macros in this section are used, any
2857 previously established default is overridden.
2858
2859 \begin{cd}\pagelabel{norender}
2860 \cs{norender}$\ldots$%
2861 \index{norender@\cs{norender}}%
2862 \end{cd}
2863
2864 This causes the following path not to be rendered at all. This can be
2865 used to override \mfp{}'s automatic rendering rules. See
2866 section~\ref{transformation}, page~\pageref{norenderexample} for an
2867 example where one might need to do this.
2868
2869
2870 \subsection{Drawing}\label{drawing}
2871
2872 \begin{cd}\pagelabel{draw}
2873 \cs{draw}\oarg{\meta{color}}$\ldots$%
2874 \index{draw@\cs{draw}}
2875 \end{cd}
2876
2877 Draws the subsequent path using a solid outline. For an example: to both
2878 draw a curve and hatch its interior, \cs{draw}\cs{hatch} must be used.
2879 The default for \meta{color} is \gbc{drawcolor}.
2880
2881 To save repetition, the color used for the following commands is also
2882 \gbc{drawcolor}:\\
2883 \cs{dashed}, \cs{dotted}, \cs{doubledraw}, \cs{plot}, \cs{plotnodes},
2884 and \cs{gendashed},
2885
2886 \begin{cd}\pagelabel{doubledraw}
2887 \cs{doubledraw}\oarg{\meta{sep}}\oarg{\meta{color}}$\ldots$
2888 \index{doubledraw@\cs{doubledraw}}
2889 \end{cd}
2890
2891 This rendering macro draws the path with a double line. The default
2892 separation (distance between centers of the two penstrokes) is twice the
2893 pen diameter. This normally leaves one line thickness of white space
2894 between. You can change this with the \oarg{\meta{sep}} argument. In
2895 order to make the space between the lines transparent, this command is
2896 implemented by calculating two curves that are parallel to the given
2897 curve and drawing those. For technical reasons, that calculation is
2898 rather lengthy so this is somewhat inefficient and users of slow
2899 machines might want to avoid it. See also comments at \cs{parallelpath}
2900 in subsection~\ref{reversal}.
2901
2902 \begin{cd}\pagelabel{dashed}
2903 \cs{dashed}\oarg{\meta{length},\meta{space}}$\ldots$%
2904 \index{dashed@\cs{dashed}}
2905 \end{cd}
2906
2907 This rendering macro draws dashed segments along the path specified.
2908 The default length of the dashes is the value of the \TeX{} dimension
2909 \cs{dashlen}, initially \dim{4pt}. The default space between the dashes
2910 is the value of the \TeX{} dimension \cs{dashspace}, initially
2911 \dim{4pt}. The dashes and the spaces between may be increased or
2912 decreased by as much as $1/n$ of their value, where $n$ is the number of
2913 spaces appearing in the curve, in order to have the proper dashes at the
2914 ends. The dashes at the ends are half of \cs{dashlen} long.
2915
2916 \begin{cd}\pagelabel{dotted}
2917 \cs{dotted}\oarg{\meta{size},\meta{space}}$\ldots$%
2918 \index{dotted@\cs{dotted}}
2919 \end{cd}
2920
2921 This rendering macro draws dots along the specified path. The default
2922 size of the dots is the value of the \TeX{} dimension \cs{dotsize},
2923 initially \dim{0.5pt}. The default space between the dots is the value
2924 of the \TeX{} dimension \cs{dotspace}, initially \dim{3pt}. The size of
2925 the spaces may be adjusted as in \cs{dashed}.
2926
2927 \begin{cd}\pagelabel{plot}
2928 \cs{plot}\oarg{\meta{size},\meta{space}}\marg{\meta{symbol}}$\ldots$%
2929 \index{plot@\cs{plot}}
2930 \end{cd}
2931
2932 Similar to \cs{dotted}, this rendering macro draws copies of
2933 \meta{symbol} along the path. Possible symbols are those listed under
2934 \cs{plotsymbol} in subsection~\ref{points}. The default \meta{size} is
2935 \cs{pointsize} (initially \dim{2pt}) and the default \meta{space} is
2936 \cs{symbolspace} (initially \dim{5pt}).
2937
2938 \begin{cd}\pagelabel{plotnodes}
2939 \cs{plotnodes}\oarg{\meta{size}}\marg{\meta{symbol}}$\ldots$%
2940 \index{plotnodes@\cs{plotnodes}}
2941 \end{cd}
2942
2943 This rendering macro places a symbol at each \emph{node} of the path
2944 that follows. Possible symbols are those listed under \cs{plotsymbol} in
2945 subsection~\ref{points}. A node is one of the points through which \MF{}
2946 draws its curve. If one of the macros \cs{polyline}\marg{$\ldots$} or
2947 \cs{curve}\marg{$\ldots$} follows, each of the points listed is a node.
2948 In the \cs{datafile} command (subsection~\ref{external}), each of the
2949 data points in the file is a node. In the function macros
2950 (subsection~\ref{plotting}) the points corresponding to \meta{min},
2951 \meta{max} and each step in between are nodes. The optional \meta{size}
2952 defaults to \cs{pointsize}. If the command \cs{clearsymbols} has been
2953 issued then the interiors of the open symbols are erased. The effect of
2954 something like the following is rather nice:
2955 \begin{verbatim}
2956 \clearsymbols
2957 \plotnodes{Circle}\draw\polyline{...}
2958 \end{verbatim}
2959 This will first draw the polyline with solid lines, and then the points
2960 listed will be plotted as open circles with the portion of the lines
2961 inside the circles erased. One sees a series of open circles connected
2962 one to the next by line segments
2963
2964
2965 \begin{cd}\pagelabel{dashpattern}
2966 \cs{dashpattern}\marg{\meta{name}}%
2967 \marg{\meta{len1},\meta{len2},$\ldots$,\meta{len2k}}%
2968 \index{dashpattern@\cs{dashpattern}}
2969 \end{cd}
2970
2971 For more general dash patterns than \cs{dashed} and \cs{dotted} provide,
2972 \mfp{} offers a generalized dashing command. Before using it, one must
2973 first establish a named dashing pattern with the above command. The
2974 \meta{name} can be any sequence of letters and underscores. Try to make
2975 it distinctive to avoid undoing some internal variable. \meta{len1}
2976 through \meta{len2k} are an even number of lengths. The odd ones
2977 determine the lengths of dashes, the even ones the lengths of spaces. A
2978 dash of length \texttt{0pt} means a dot. An alternating dot-dash pattern
2979 can be specified with
2980 \begin{verbatim}
2981 \dashpattern{dotdash}{0pt,4pt,3pt,4pt}
2982 \end{verbatim}
2983 \emph{Note}: Since pens have some thickness, dashes look a little
2984 longer, and spaces a little shorter, than the numbers suggest. If one
2985 wants dashes and spaces with the same length, one needs to take the size
2986 desired and increase the spaces by the thickness of the drawing pen
2987 (normally) \dim{0.5pt}) and decrease the dashes by the same amount.%
2988 \footnote{Experienced \MP{} users could also set the \mfc{linecap}
2989 variable to \mfc{butt}.}
2990
2991 If \cs{dashpattern} is used with an odd number of entries, a space of
2992 length \dim{0pt} is appended. This makes the last dash in one copy of
2993 the pattern abut the first dash in the next copy.
2994
2995 \begin{cd}\pagelabel{gendashed}
2996 \cs{gendashed}\marg{\meta{name}}$\ldots$%
2997 \index{gendashed@\cs{gendashed}}
2998 \end{cd}
2999
3000 Once a dashing pattern name has been defined, it can be used in this
3001 figure macro to draw the curve that follows it. Using a name not
3002 previously defined will cause the curve to be drawn with a solid line,
3003 and generate a \MF{} warning, but \TeX{} will not complain. If all the
3004 dimensions in a dash pattern are 0, \cs{gendashed} responds by drawing a
3005 solid curve. The same is true if the pattern has only one entry.
3006
3007 \begin{cd}\pagelabel{zigzag}
3008 \cs{zigzag}\marg{\meta{start},\meta{end},\meta{wl},\meta{amp}}\dots\\
3009 \cs{sinewave}\oarg{\meta{tens}}%
3010 \marg{\meta{start},\meta{end},\meta{wl},\meta{amp}}\dots%
3011 \index{zigzag@\cs{zigzag}}%
3012 \index{sinewave@\cs{sinewave}}
3013 \end{cd}
3014
3015 These figure macros both draw a solid line that crosses from one
3016 side of the path to the other. The \cs{zigzag} makes a jagged result
3017 while the \cs{sinewave} makes a smooth one. The optional argument of
3018 \cs{sinewave} is a `tension' and controls how smooth the result is. The
3019 default tension is $1$. Higher values make a less smooth path, and
3020 values of 10 or so produce a result almost indistinguishable from
3021 \cs{zigzag}. Tension is required to be greater than $3/4$.
3022
3023 The mandatory arguments consists of four dimensions separated by a comma.
3024 The rendering produced by these macros actually follow the path a little
3025 way at the start and end of the path. This is controlled by the
3026 dimensions \meta{start} and \meta{end}.
3027
3028 The third dimension, \meta{wl}, is the distance from one `peak' to the
3029 next (the `wavelength'). The second, \meta{amp}, is the maximum distance
3030 to either side of the true path (the `amplitude'). Reasonable values of
3031 \meta{wl} and \meta{amp} are \dim{8pt} and \dim{2pt}, respectively.
3032 These proportions (4 to 1) causes the zigzag and the sinewave to cross
3033 the path at an angle of about 45 degrees, a rather pleasant result.
3034 Those sizes are close to optimal: too much smaller and the rendering
3035 just looks like a fuzzy line, too much larger, and bends in the path
3036 will distort the zigzagging.
3037
3038 The zigzags zig to the left first if \meta{amp} is positive, to the
3039 right if it is negative. For closed curves, the beginning and end are
3040 constructed to meet smoothly. It is always arranged that there are an
3041 equal number of left zigs and right zags, so the \meta{wl} is only
3042 approximate.
3043
3044
3045 \begin{cd}\pagelabel{corkscrew}
3046 \cs{corkscrew}\oarg{\meta{tens}}%
3047 \marg{\meta{start},\meta{end},\meta{wl},\meta{amp}}\dots\\%
3048 \cs{coil}\oarg{\meta{tens}}%
3049 \marg{\meta{start},\meta{end},\meta{wl},\meta{amp}}\dots%
3050 \index{corkscrew@\cs{corkscrew}}%
3051 \index{coil@\cs{coil}}
3052 \end{cd}
3053
3054 This rendering macro draws a coil or corkscrew that coils around a
3055 given path, something like this: \includegraphics{coil.mps} (the red
3056 dots show the actual path). The \meta{tens} is a tension option that
3057 controls how `loopy' the result will be (the higher the number the more
3058 jagged). The mandatory argument contains four explicit dimensions. The
3059 first two, \meta{start} and \meta{end} are as in \cs{zigzag}. The
3060 \meta{wl} is the distance from one loop to the next, and \meta{amp} is
3061 the distance from the true path to the tops (or bottoms) of the
3062 loops. If \meta{amp} is positive, the tip of the loop is to the left
3063 of the path, if negative it is to the right. The example at the start of
3064 this paragraph was drawn using the following code:
3065 \begin{verbatim}
3066 \mfpic{0}{33}{0}{6.4}
3067 \dotsize=1pt
3068 \drawcolor{red}
3069 \dotted\polyline{(0,3.2),(33,3.2)}
3070 \drawcolor{black}
3071 \coil[1.5]{3pt,3pt,4.8pt,3.2pt}\polyline{(0,3.2),(33,3.2)}
3072 \endmfpic
3073 \end{verbatim}
3074
3075
3076 \subsection{Shading, filling, erasing, clipping, hatching}\label{filling}
3077
3078 For the purposes of this section, a distinction must be made in the
3079 figure macros between `open' and `closed' paths. A path that merely
3080 returns to its starting point is \emph{not} automatically closed; such a
3081 path might be open and may need to be explicitly closed, for example by
3082 \cs{lclosed}. The (already) closed paths are those that have
3083 `\texttt{closed}' or `\texttt{cyclic}' in their name plus:
3084 \begin{display}
3085 \cs{belowfcn}, \cs{border}, \cs{btwnfcn}, \cs{btwnplrfcn},
3086 \cs{chartbar} (and its aliases),\\
3087 \cs{circle}, \cs{ellipse}, \cs{fullellipse}, \cs{levelcurve},
3088 \cs{makesector},\cs{piewedge},\\ \cs{plrregion},
3089 \cs{polygon}, \cs{pshcircle}. \cs{rect}, \cs{regpolygon},
3090 \cs{sector}, \cs{tlabelcircle},\\
3091 \cs{tlabelellipse}, \cs{tlabeloval}, and \cs{tlabelrect}.
3092 \end{display}
3093
3094 The macros of this section can all be used to fill (or unfill) the
3095 interior of closed paths, even if the paths cross themselves. Filling an
3096 open curve is technically an error, but the \MF{} code responds by
3097 drawing the path and not doing any filling. Note that these macros
3098 override the default rendering, so if you want some sort of fill pattern
3099 \emph{and} an outline drawn, you need an explicit prefix for both.
3100
3101 \begin{cd}\pagelabel{gfill}
3102 \cs{gfill}\oarg{\meta{color}}$\ldots$%
3103 \index{gfill@\cs{gfill}}
3104 \end{cd}
3105
3106 This rendering macro fills in the subsequent closed path. Under \MP{} it
3107 fills with \meta{color}, which defaults to
3108 \index{fillcolor@\gbc{fillcolor}}\gbc{fillcolor}. Under \MF{} it
3109 approximates the color with a shade of gray, clears the interior, and
3110 then fills with a pattern of black and white pixels simulating gray.
3111
3112 \begin{cd}\pagelabel{gclear}
3113 \cs{gclear}$\ldots$%
3114 \index{gclear@\cs{gclear}}
3115 \end{cd}
3116
3117 This rendering macro erases everything \emph{inside} the subsequent
3118 closed path (except text labels under some circumstances, see
3119 section~\ref{mplabels} and \ref{overlaylabels}). Under \MP{} it actually
3120 fills with the predefined color named \mfc{background}. Since
3121 \mfc{background} is normally \mfc{white}, and so are most actual
3122 backgrounds, this is usually indistinguishable from clearing. However,
3123 if an \env{mfpic} environment utilzes \emph{background text} (see
3124 subsection~\ref{text}), part of the background text may appear to be
3125 `erased'. Unfortunately, there is little that can be done about this.
3126
3127 \begin{cd}\pagelabel{gclip}
3128 \cs{gclip}$\ldots$%
3129 \index{gclip@\cs{gclip}}
3130 \end{cd}
3131
3132 This rendering macro erases everything \emph{outside} the subsequent
3133 closed path from the picture (except text labels under some
3134 circumstances, see section~\ref{mplabels} and \ref{overlaylabels}). Note
3135 that this is a true erasing, even in \MP{}.
3136
3137 \begin{cd}\pagelabel{shade}
3138 \cs{shade}\oarg{\meta{shadesp}}$\ldots$%
3139 \index{shade@\cs{shade}}
3140 \end{cd}
3141
3142 This rendering macro shades the interior of the subsequent closed path
3143 with dots. The diameter of the dots is the \MF{} variable \mfc{shadewd},
3144 set by the macro \cs{shadewd}\marg{\meta{size}}. Normally this is
3145 \dim{0.5bp}. The optional argument specifies the spacing between (the
3146 centers of) the dots, which defaults to the \TeX{} dimension
3147 \cs{shadespace}, initially \dim{1pt}. If \mfc{shadewd} is larger than
3148 \cs{shadespace}, the closed path is filled with black, as if with
3149 \cs{gfill}. Under \MP{} this macro actually fills the path's interior
3150 with a shade of gray. The shade to use is computed based on
3151 \cs{shadespace} and \mfc{shadewd}. The default values of these
3152 parameters correspond to a gray level of about 78\% of white.%
3153 \footnote{If \cs{shadewd} is $w$ and \cs{shadespace} is $s$, then
3154 the level of gray is $1 - (.88w/s)^2$, where $0$ denotes black and
3155 $1$ white.} %
3156 The \MF{} version attempts to optimize the dots to the pixel grid
3157 corresponding to the printers resolution (to avoid generating dither
3158 lines). Because this involves rounding, it will happen that values of
3159 \cs{shadespace} that are relatively close and at the same time close to
3160 \mfc{shadewd} produce exactly the same shade. Most of the time, however,
3161 values of \cs{shadespace} that differ by at least 20\% will produce
3162 different patterns. The actual behavior for particular values of the
3163 parameters and particular printer resolutions cannot be predicted, and
3164 we even make no guarantee it will not change from one version of \mfp{}
3165 to another.
3166
3167 \begin{cd}\pagelabel{polkadot}
3168 \cs{polkadot}\oarg{\meta{space}}$\ldots$%
3169 \index{polkadot@\cs{polkadot}}
3170 \end{cd}
3171
3172 This rendering macro fills the interior of a closed path with large
3173 dots. This is almost what \cs{shade} does, but there are several
3174 differences. \cs{shade} is intended solely to simulate a gray fill in
3175 \MF{} where the only color is black. So it is optimized for small dots
3176 aligned to the pixel grid (in \MF{}). In \MP{} \cs{shade} only fills with
3177 gray and is intended merely for compatibility. The macro \cs{polkadot}
3178 is intended for large dots in any color, and so it optimizes spacing (a
3179 nice hexagonal array) and makes no attempt to align at the pixel level.
3180 The \meta{space} defaults to the \TeX{} dimension \cs{polkadotspace},
3181 initially \dim{10pt}. The diameter of the dots is the value of the \MF{}
3182 variable \mfc{polkadotwd}, which can be set with
3183 \cs{polkadotwd}\marg{\meta{size}}, and is initially \dim{5bp}. The dots
3184 are colored with \index{fillcolor@\gbc{fillcolor}}\gbc{fillcolor}. In
3185 \MF{}, nonblack values of \gbc{fillcolor} will produce shaded dots.
3186
3187 \begin{cd}\pagelabel{thatch}
3188 \cs{thatch}\oarg{\meta{hatchsp},\meta{angle}}\oarg{\meta{color}}$\ldots$%
3189 \index{thatch@\cs{thatch}}
3190 \end{cd}
3191
3192 This rendering macro fills a closed path with equally spaced parallel
3193 lines at the specified angle. The thickness of the lines is set by the
3194 macro \cs{hatchwd}. In the optional argument, \meta{hatchsp} specifies
3195 the space between lines, which defaults to the \TeX{} dimension
3196 \cs{hatchspace}, initially \dim{3pt}. The \meta{angle} defaults to 0.
3197 The \meta{color} defaults to \gbc{hatchcolor}. If \cs{hatchspace} is
3198 less than the line thickness, the closed path is filled with
3199 \meta{color}, as if with \cs{gfill}. If the first optional argument
3200 appears, both parts must be present, separated by a comma. For the color
3201 argument to be present, the other optional argument must also be
3202 present. However, if one wishes only to override the default color one
3203 can use an empty first optional argument (completely empty, no spaces or
3204 comma).
3205
3206 An angle of $0$ yields horizontal lines, nonzero angles indicate
3207 rotations from horizontal where, as usual, positive angles indicate
3208 anticlockwise rotation.
3209
3210 \begin{cd}\pagelabel{hatch}
3211 \cs{lhatch}\oarg{\meta{hatchsp}}\oarg{\meta{color}}$\ldots$\\
3212 \cs{rhatch}\oarg{\meta{hatchsp}}\oarg{\meta{color}}$\ldots$\\
3213 \cs{hatch}\oarg{\meta{hatchsp}}\oarg{\meta{color}}$\ldots$\\
3214 \cs{xhatch}\oarg{\meta{hatchsp}}\oarg{\meta{color}}$\ldots$%
3215 \index{lhatch@\cs{lhatch}}%
3216 \index{rhatch@\cs{rhatch}}%
3217 \index{hatch@\cs{hatch}}%
3218 \index{xhatch@\cs{xhatch}}%
3219 \end{cd}
3220
3221 These rendering macros are just \cs{thatch} with predefined values of
3222 the angle. \cs{lhatch} fills the region with left slanted lines (from
3223 upper left to lower right). It is exactly the same as
3224 \begin{display}
3225 \cs{thatch}\oarg{\meta{hatchsp},-45}\oarg{\meta{color}}$\ldots$
3226 \end{display}
3227
3228 \cs{rhatch} draws right slanted lines (lower left to upper right). It is
3229 exactly the same as
3230 \begin{display}
3231 \cs{thatch}\oarg{\meta{hatchsp},45}\oarg{\meta{color}}$\ldots$
3232 \end{display}
3233
3234 \cs{hatch} (\cs{xhatch} is a synonym) draws lines in a cross-hatched
3235 pattern. It is exactly the same as \cs{rhatch} followed by \cs{lhatch}
3236 using the same \meta{hatchsp} and \meta{color}.
3237
3238 Hatching should normally be used very sparingly, or never if
3239 alternatives are available (color, shading). However, hatching on top of
3240 another filling macro is a common way to fill in \emph{two} regions in
3241 such a way that the overlap area is clearly evident. Hatching is at
3242 least less garish than polkadots.
3243
3244 \begin{cd}\pagelabel{gradient}
3245 \cs{gradient}\marg{\meta{clrfcn},\meta{width},\meta{angle}}$\ldots$%
3246 \index{gradient@\cs{gradient}}%
3247 \end{cd}
3248
3249 Neither \MP{} nor \MF{} can do true gradients, but this rendering macro
3250 obtains a good approximation by filling adjacent narrow strips in a
3251 range of colors. The argument \meta{width} is the width of those strips,
3252 and it should be specified in absolute units, \meta{angle} is the angle
3253 of these strips (horizontal being $0$ degrees). The first argument
3254 takes a little explanation.
3255
3256 The \meta{clrfcn} should be the name of a function, say \mfc{gr},
3257 such that \mfc{gr(t)} returns a color\footnote{It can also return a
3258 number between $0$ and $1$, which will result in shades of gray.} for
3259 any value of $t$ from $0$ to $1$ (inclusive). Such a function can be
3260 defined with \cs{fdef} (see subsection~\ref{defining}). The first strip
3261 will have the color returned for \mfc{t}${}=0$ and the last will have
3262 the color returned for \mfc{t}${}=1$. One kind of gradient fill is
3263 obtained by a simple interpolation between two colors in the same model:
3264 \begin{verbatim}
3265 \fdef{gr}{t}{(1-t)*red + t*blue}
3266 \gradient{gr,3pt,45}\circle{(0,0),1}
3267 \end{verbatim}
3268 This example will start the gradient with red and end it with blue. For
3269 an angle of $0$ the starting color is at the bottom and the ending color
3270 at the top, for other angles simply rotate that description. The above
3271 circle will be red at the lower right and blue at the upper left.
3272
3273 This type of gradient is called an \emph{axial} gradient. The following
3274 is another kind, based on a color function of \emph{two} variables over
3275 an area.
3276
3277 \begin{cd}\pagelabel{areagradient}
3278 \cs{areagradient}\marg{\meta{clrfcn},\meta{h-dim},\meta{v-dim}}$\ldots$%
3279 \index{areagradient@\cs{areagradient}}%
3280 \end{cd}
3281
3282 Instead of filling with strips of different colors, \cs{areagradient}
3283 fills with ``pixels'' of different colors. These are rectangles that
3284 have size \meta{h-dim} by \meta{v-dim}, which values must be specified
3285 in absolute units. These rectangles are filled with the color determined
3286 by \meta{clrfcn}. This must be a function of \emph{two} parameters that
3287 returns a color for values of these parameters from $0$ to $1$
3288 (inclusive). For example,
3289 \begin{verbatim}
3290 \fdef{agr}{t,u}%
3291 {(1-t)(1-u)*white + (1-t)*u*red + t*(1-u)*green + t*u*blue}
3292 \gradient{agr,3pt,4pt}\rect{(0,0),(1,2)}
3293 \end{verbatim}
3294 The color returned for $(0,0)$ is at the lower left and the color
3295 returned for $(1,1)$ is at the upper right. In the above example, the
3296 rectangle will be white at the lower left, red at the upper left, green
3297 at the lower right and blue at the upper right.
3298
3299 Our last gradient is something like the first, but in polar coordinates.
3300 The colors vary with the distance from a center point.
3301
3302 \begin{cd}\pagelabel{radialgradient}
3303 \cs{radialgradient}\marg{\meta{clrfcn},\meta{width},\meta{center}}$\ldots$%
3304 \index{radialgradient@\cs{radialgradient}}%
3305 \end{cd}
3306
3307 This gradient fills with concentric circular strips whose center is
3308 \meta{center} and whose thickness is \meta{width}. The \meta{clrfcn} is
3309 as in \cs{gradient}. The circle of radius \meta{width} and center
3310 \meta{center} is filled with the color returned for parameter value $0$.
3311 The largest concentric circular strip is filled with the color returned
3312 for parameter value $1$.
3313
3314 These commands all initially compute a bounding figure for the curve. In
3315 the first case it is a rotated rectangle, in the second case an upright
3316 rectangle, and in the third case a circle centered at the given point.
3317 The interiors of the rectangles are considered to have coordinates
3318 $(t,u)$ that vary from $(0,0)$ at the lower left to $(1,1)$ at the upper
3319 right. The inside of the circle is considered to have the polar
3320 coordinate $r$ ranging from $0$ at the center to $1$ at the boundary.
3321 The relevant coordinate(s) are fed to the specified \meta{clrfcn} and
3322 the returned color is used to fill the relevant portion of the rectangle
3323 or circle. The whole picture is then clipped to the boundaries of the
3324 given closed curve and the result added to the picture.
3325
3326 The process is somewhat wasteful of memory in \MP{}, as each strip or
3327 pixel's path is kept in memory and written to the output file. This can
3328 be quite large for \cs{areagradient} if the pixel dimensions are too
3329 small. For example, covering a one inch square with pixels 1 point on
3330 each side takes over 5000 paths and the resulting EPS is over 100,000
3331 bytes in size. I would recommend dimensions on the order of 2 to 3
3332 points. Larger dimensions are not as visually appealing, and smaller
3333 dimensions waste memory with little improvement in appearence.
3334
3335 This command works in \MF{} using a \meta{clrfcn} that returns numeric
3336 values in the range $0$ to $1$. The result is much like
3337 \cs{gfill}\oarg{\meta{clr}} (see the beginning of this section) except
3338 the dots simulating a gray fill will vary in size corresponding to the
3339 \meta{clrfcn}. The result will be disappointing unless there is
3340 considerable contrast between the lightest and darkest grays of the
3341 gradient. Therefore, it is recommended that the color function cover the
3342 entire range from $0$ to $1$ (black to white). There are no particular
3343 memory problems with gradients in \MF{}, at least no more so than gray
3344 fills.
3345
3346
3347 \subsection{Changing the default rendering}\label{default}
3348
3349 \emph{Rendering} is the process of converting a geometric description
3350 into a drawing. In \MF{}, this means producing a bitmap (\MF{} stores
3351 these in \mfc{picture} variables), either by stroking (drawing) a path
3352 using a particular pen), or by filling a closed path. In \MP{} it means
3353 producing a \PS{} description of penstrokes and fills (with possible
3354 clipping).
3355
3356 \begin{cd}\pagelabel{setrender}
3357 \cs{setrender}\marg{\meta{\TeX{} commands}}%
3358 \index{setrender@\cs{setrender}}
3359 \end{cd}
3360
3361 Initially, \mfp{} uses the \cs{draw} command (stroking) as the default
3362 operation when a figure is to be rendered. However, this can be changed
3363 to any combination of \mfp{} rendering commands or indeed any \TeX{}
3364 commands, by using the \cs{setrender} command. This redefinition is
3365 local when it occurs inside an \env{mfpic} environment, so there it can
3366 be enclosed in braces to restrict its range. Outside an \env{mfpic}
3367 environment it is a global redefinition.
3368
3369 For example, suppose one uses \cs{setrender}\marg{\cs{dashed}\cs{shade}}
3370 in a \env{mfpic} environment. If the command \cs{circle}\marg{(0,0),1}
3371 occurs later in that environment, it will produce a shaded circle with a
3372 dashed outline. If an explicit rendering prefix is given in a drawing
3373 command, it will override this default.
3374
3375
3376 \subsection{Examples}\label{examples}
3377
3378 It may be instructive, for the purpose of understanding the syntax of
3379 \emph{shape-modifier and rendering prefixes}, to consider two examples:
3380 \begin{ex}
3381 \cs{draw}\cs{gfill}\oarg{red}\cs{lclosed}\cs{polyline}\marg{$\ldots$}
3382 \end{ex}
3383 which fills inside a polygon and draws its outline; and
3384 \begin{ex}
3385 \cs{gfill}[red]\cs{lclosed}\cs{draw}\cs{polyline}\marg{$\ldots$}
3386 \end{ex}
3387 which draws all of the outline \emph{except} the line segment supplied
3388 by \cs{lclosed}, then fills the interior. Thus, in the first case the
3389 path is first defined (by \cs{polyline}), then closed, then the resulting closed
3390 path is filled, and finally drawn. In the second case the order is:
3391 defined, drawn, closed, filled. In particular, what is drawn in the
3392 second case is the path not yet closed. It should also be pointed out
3393 that in the last case, the fill is placed last and will cover half
3394 the thickness of the previously drawn outline.
3395
3396
3397 \section{Functions and Plotting.}\label{functions}
3398
3399 In the following macros, expressions like $f(\mathtt{x})$ or $g(\mathtt{t})$
3400 stand for any legal \MF{} expression, in which the only unknown
3401 variables are those indicated (\texttt{x} in the first case, and \texttt{t} in
3402 the second).
3403
3404
3405 \subsection{Defining functions}\label{defining}
3406
3407 \begin{cd}\pagelabel{fdef}
3408 \cs{fdef}\marg{\meta{fcn}}\marg{\meta{param1},\meta{param2},$\ldots$}%
3409 \marg{\meta{mf-expr}}%
3410 \index{fdef@\cs{fdef}}
3411 \end{cd}
3412
3413 Defines a \MF{} function \meta{fcn} of the parameters \meta{param1},
3414 \meta{param2}, $\ldots$, by the \MF{} expression \meta{mf-expr} in which
3415 the only free parameters are those named. The return type of the
3416 function is the same as the type of the expression. What is allowed for
3417 the function name \meta{fcn} is more restrictive than \MF{}'s rule for
3418 variable names. Roughly speaking, it should consist of letters and
3419 underscore characters only. (In particular, for those who know what
3420 this means, the name should have no suffixes.) Try to make the name
3421 distinctive to avoid redefining internal \MF{} commands.
3422
3423 The expression \meta{mf-expr} is passed directly into the corresponding
3424 \MF{} macro and interpreted there, so \MF{}'s rules for algebraic
3425 expressions apply. If \cs{fdef} occurs inside an \env{mfpic}
3426 environment, it is local to that environment, otherwise it is available
3427 to all subsequent \env{mfpic} environments.
3428
3429 As an example, after \cs{fdef}\marg{myfcn}\marg{s,t}\marg{s*t-t}, any
3430 place below where a \MF{} expression is required, you can use
3431 \mfc{myfcn(2,3)} to mean \mfc{2*3-3} and \mfc{myfcn(x,x)} to mean
3432 \mfc{x*x-x}.
3433
3434 Operations available include \mfc{+}, \mfc{-}, \mfc{*}, \mfc{/}, and
3435 \mfc{**} (\mfc{x**y}$=x^y$), with `\mfc{(}' and `\mfc{)}' for grouping.
3436 Functions already available include the standard \MF{} functions
3437 \mfc{round}, \mfc{floor}, \mfc{ceiling}, \mfc{abs}, \mfc{sqrt},
3438 \mfc{sind}, \mfc{cosd}, \mfc{mlog}, and \mfc{mexp}. Note that in \MF{}
3439 the operations \mfc{*} and \mfc{**} have the same level of precedence,
3440 so \mfc{x*y**z} means $(xy)^z$. Use parentheses liberally!
3441
3442 (\textit{Notes:} The \MF{} trigonometric functions \mfc{sind} and
3443 \mfc{cosd} take arguments in degrees; \mfc{mlog(x)}$=256\ln x$, and
3444 \mfc{mexp} is its inverse.) You can also define the function \meta{fcn}
3445 by cases, using the \MF{} conditional expression
3446 \begin{ex}
3447 \mfc{if~\meta{boolean}:~\meta{expr}~elseif
3448 \meta{boolean}:~$\ldots$~else:~\meta{expr}~fi}.
3449 \end{ex}
3450 Relations available for the \meta{boolean} part of the expression
3451 include \mfc{=}, \mfc{<}, \mfc{>}, \mfc{<=}, \mfc{<>} and \mfc{>=}.
3452
3453 Complicated functions can be defined by a compound expression, which is
3454 a series of \MF{} statements, followed by an expression, all enclosed
3455 between \mfc{begingroup} and \mfc{endgroup}. The \cs{fdef} command
3456 automatically supplies these grouping commands around the definition so
3457 if the entire \meta{mf-expr} is one such compound expression the user
3458 need not type them. \CMF{} functions can call \MF{} functions, even
3459 recursively.
3460
3461 Many common functions have been predefined in \file{grafbase}, which is
3462 a package of \MF{} macros that implement \prog{mfpic}'s drawing. These
3463 include the rest of the trig functions \mfc{tand}, \mfc{cotd}, \mfc{secd},
3464 \mfc{cscd}, which take angles in degrees, plus variants \mfc{sin},
3465 \mfc{cos}, \mfc{tan}, \mfc{cot}, \mfc{sec}, and \mfc{csc}, which take
3466 angles in radians. Some inverse trig functions are also available, the
3467 following produce angles in degrees: \mfc{asin}, \mfc{acos}, and
3468 \mfc{atan}, and the following in radians: \mfc{invsin}, \mfc{invcos},
3469 \mfc{invtan}. The exponential and hyperbolic functions: \mfc{exp},
3470 \mfc{sinh}, \mfc{cosh}, \mfc{tanh}, \mfc{coth}, \mfc{sech}, and
3471 \mfc{csch}; and some of their inverses: \mfc{ln} (or \mfc{log}),
3472 \mfc{asinh}, \mfc{acosh}, and \mfc{atanh} are also defined.
3473
3474 There are also two conversion functions: \gbc{radians(t)} produces the
3475 number of radians in \mfc{t} degrees and \gbc{degrees(t)} produces the
3476 number of degrees in \mfc{t} radians. In these expressions the special
3477 variable \gbc{pi} produces $\pi$, accurate to roughly 5 decimals.
3478 (\CMF{} and \MP{} provide accuracy only to $\pm2^{-17} = \pm
3479 .76\times10^{-5}$.)
3480
3481 The integer functions \gbc{gcd(m,n)} and \gbc{lcm(m,n)} produce the
3482 greatest common divisor and least common multiple of two integers
3483 \gbc{m} and \gbc{n}.
3484
3485
3486 \subsection{Plotting functions}\label{plotting}
3487
3488 The plotting macros take two or more arguments. They have an optional
3489 first argument, \meta{spec}, which determines whether a function is
3490 drawn smooth (as a \MF{} B\'ezier curve), or polygonal (as line
3491 segments)---if \meta{spec} is \texttt{p}, the function will be
3492 polygonal. Otherwise the \meta{spec} should be \texttt{s}, followed by
3493 an optional positive number no smaller than 0.75. In this case the
3494 function will be smooth with a tension equal to the number. See the
3495 \cs{curve} command (subsection~\ref{curves}) for an explanation of
3496 tension. The default \meta{spec} depends on the purpose of the macro.
3497
3498 One compulsory argument contains three values \meta{min}, \meta{max} and
3499 \meta{step} separated by commas. The independent variable of a function
3500 starts at the value \meta{min} and steps by \meta{step} until reaching
3501 \meta{max}. If (\meta{max}${}-{}$\meta{min})/\meta{step} is not a whole
3502 number, the nearest whole number of equal steps are used. One may have
3503 to experiment with the size of \meta{step}, since \MF{} merely connects
3504 the points corresponding to these steps with what \emph{it} considers to
3505 be a smooth curve. Smaller \meta{step} gives better accuracy, but too
3506 small may cause the curve to exceed \MF{}'s capacity or slow down its
3507 processing. Increasing the tension may help keep the curve in line, but
3508 at the expense of reduced smoothness.
3509
3510 There are one or more subsequent arguments, each of which is a \MF{}
3511 function or expression as described above. All the macros are figure
3512 macros, defining a path to which prefixes may be applied.
3513
3514 \begin{cd}\pagelabel{function}
3515 \cs{function}\oarg{\meta{spec}}\marg{\meta{$x_{\mathrm{min}}$},%
3516 \meta{$x_{\mathrm{max}}$},\meta{$\Delta x$}}%
3517 \marg{$f(\mathtt{x})$}%
3518 \index{function@\cs{function}}
3519 \end{cd}
3520
3521 This figure macro produces an approximation to the graph of $y = f(x)$,
3522 where $f$ is a \MF{} numeric function or expression of one numeric
3523 argument, which must be denoted by a literal \texttt{x}. The default
3524 \meta{spec} is \texttt{s}. For example
3525 \begin{verbatim}
3526 \function{0,pi,pi/10}{sin x}
3527 \end{verbatim}
3528 draws the graph of $\sin x$ between 0 and $\pi$.
3529
3530 \begin{cd}\pagelabel{parafcn}
3531 \cs{parafcn}\oarg{\meta{spec}}\marg{\meta{$t_{\mathrm{min}}$},%
3532 \meta{$t_{\mathrm{max}}$},\meta{$\Delta t$}}%
3533 \marg{($x(\mathtt{t}), y(\mathtt{t})$)}\\
3534 \cs{parafcn}\oarg{\meta{spec}}\marg{\meta{$t_{\mathrm{min}}$},%
3535 \meta{$t_{\mathrm{max}}$},\meta{$\Delta t$}}%
3536 \marg{\meta{pair-fcn}}%
3537 \index{parafcn@\cs{parafcn}}
3538 \end{cd}
3539
3540 This figure macro produces the parametric path determined by the last
3541 argument. This can be a pair of expressions $x(\mathtt{t})$ and
3542 $y(\mathtt{t})$ enclosed in parentheses and separated by a comma, with
3543 the literal variable \texttt{t}. Alternatively, the last argument can be
3544 a \MF{} function or expression in \texttt{t} that returns a pair.%
3545 \footnote{There are very few of these. \CMF{} provides
3546 \codebox{dir t}, which is essentially
3547 \codebox{(cosd t, sind t)}. \Mfp{} adds \codebox{cis t} which
3548 is \codebox{(cos t, sin t)}.}
3549 The default \meta{spec} is \texttt{s}. For example
3550 \begin{verbatim}
3551 \parafcn{0,1,.1}{(2t, t+t*t)}
3552 \end{verbatim}
3553 plots a smooth parabola from $(0,0)$ to $(2,2)$.
3554
3555 \begin{cd}\pagelabel{plrfcn}
3556 \cs{plrfcn}\oarg{\meta{spec}}\marg{\meta{$\theta_{\mathrm{min}}$},%
3557 \meta{$\theta_{\mathrm{max}}$},\meta{$\Delta\theta$}}%
3558 \marg{$f(\mathtt{t})$}%
3559 \index{plrfcn@\cs{plrfcn}}
3560 \end{cd}
3561
3562 This figure macro produces the graph of the polar coordinate equation
3563 $r=f(\theta)$, where $f$ is a \MF{} numeric function or expression of
3564 one numeric argument, and $\theta$ varies from
3565 \meta{$\theta_{\mathrm{min}}$} to \meta{$\theta_{\mathrm{max}}$} in
3566 steps of \meta{$\Delta\theta$}. Each $\theta$ value is interpreted as an
3567 angle measured in \emph{degrees}. In the expression $f(\mathtt{t})$, the
3568 unknown \texttt{t} stands for $\theta$. The default \meta{spec} is
3569 \texttt{s}. For example
3570 \begin{verbatim}
3571 \plrfcn{0,90,5}{sind (2t)}
3572 \end{verbatim}
3573 draws one loop of a 4-petal rosette. Note that this function demands the
3574 variable \mfc{t} be in degrees. The range and step size must be in
3575 degrees and the function must operate on the numeric variable \gbc{t} in
3576 degrees. If one needs to measure angles in radians, use the conversion
3577 functions \gbc{degrees()} and \gbc{radians()}, as follows:
3578 \begin{verbatim}
3579 \plrfcn{0,degrees(pi/2),degrees(pi/36)}{sin (radians(2t))}
3580 \end{verbatim}
3581
3582
3583 \begin{cd}\pagelabel{btwnfcn}
3584 \cs{btwnfcn}\oarg{\meta{spec}}\marg{\meta{$x_{\mathrm{min}}$},%
3585 \meta{$x_{\mathrm{max}}$},\meta{$\Delta x$}}%
3586 \marg{$f(\mathtt{x})$}\marg{$g(\mathtt{x})$}\\
3587 \cs{btwnplrfcn}\oarg{\meta{spec}}\marg{\meta{$\theta_{\mathrm{min}}$},%
3588 \meta{$\theta_{\mathrm{max}}$},\meta{$\Delta \theta$}}%
3589 \marg{$f(\mathtt{t})$}\marg{$g(\mathtt{t})$}%
3590 \index{btwnfcn@\cs{btwnfcn}}%
3591 \index{btwnplrfcn@\cs{btwnplrfcn}}
3592 \end{cd}
3593
3594 These are figure macros. The first one produces a closed path
3595 surrounding the region between the graphs of the two functions. The
3596 second one does the same for two polar functions. That is (in both
3597 cases), the path follows the first function (in order or increasing $x$
3598 or $\theta$), thence along the straight line to the \emph{end} of the
3599 second one, thence backwards along the second function (decreasing $x$
3600 or $\theta$) and finally along the straight line to the start. The last
3601 two mandatory arguments, the functions, are specified exactly as in
3602 \cs{function} and \cs{plrfcn}, being numeric functions of one numeric
3603 argument \texttt{x} or \texttt{t}. Unlike the previous function macros,
3604 the default \meta{spec} is \texttt{p}---these macros are intended to be
3605 used for shading between drawn functions, a task for which smoothness is
3606 usually unnecessary. For example, the first line below
3607 \begin{verbatim}
3608 \shade\btwnfcn{0,1,.1}{0}{x - x**2}
3609 \btwnplrfcn[s]{-30,30,5}{1}{2*cosd 2t}
3610 \end{verbatim}
3611 shades the area between the $x$-axis and the given parabola. The second
3612 draws the boundary of the region between the circle $r = 1$ and one loop
3613 of the rosette $r = 2\cos 2\theta$.
3614
3615 Note: the effect of \cs{btwnfcn} could also be accomplished with
3616 \begin{ex}
3617 \cs{lclosed}\cs{connect}\\
3618 \cs{function}\marg{\meta{$x_{\mathrm{min}}$},%
3619 \meta{$x_{\mathrm{max}}$},\meta{$\Delta x$}}\marg{$f(\mathtt{x})$}\\
3620 \cs{reverse}\cs{function}\marg{\meta{$x_{\mathrm{min}}$},%
3621 \meta{$x_{\mathrm{max}}$},\meta{$\Delta x$}}\marg{$g(\mathtt{x})$}\\
3622 \cs{endconnect}
3623 \end{ex}
3624 \cs{lclosed} was described in subsection~\ref{closure} and the
3625 \cs{connect}\dots\cs{endconnect} pair was described in
3626 subsection~\ref{reversal}.
3627
3628 \begin{cd}\pagelabel{belowfcn}
3629 \cs{belowfcn}\oarg{\meta{spec}}%
3630 \marg{\meta{$x_{\mathrm{min}}$},\meta{$x_{\mathrm{max}}$},%
3631 \meta{$\Delta x$}}\marg{$f(\mathtt{x})$}\\
3632 \cs{plrregion}\oarg{\meta{spec}}%
3633 \marg{\meta{$\theta_{\mathrm{min}}$},\meta{$\theta_{\mathrm{max}}$},%
3634 \meta{$\Delta\theta$}}\marg{$f(\mathtt{t})$}%
3635 \index{belowfcn@\cs{belowfcn}}%
3636 \index{plrregion@\cs{plrregion}}
3637 \end{cd}
3638
3639 These figure macros produce identical results to \cs{btwnfcn} and
3640 \cs{btwnplrfcn} when the first function is just $0$. They are, however,
3641 much more efficient. The first of these, \cs{belowfcn}, produces the
3642 path surrounding the region bounded by the $x$-axis, the graph of
3643 $y=f(x)$ and the two vertical lines $x=x_{\mathrm{min}}$ and $x =
3644 x_{\mathrm{max}}$. (The region is not actually \emph{below} $y = f(x)$
3645 unless $f(x) \ge 0$ throughout the interval.) The second produces the
3646 path surrounding the region bounded by the polar function $r =
3647 f(\theta)$ and the two rays $\theta=\theta_{\mathrm{min}}$ and
3648 $\theta=\theta_{\mathrm{max}}$.
3649
3650 The arguments of these command are the same as the nonclosed versions,
3651 \cs{function} and \cs{plrfcn}, except the default for the optional
3652 agument is \texttt{[p]}. Again, this is because it is mainly for
3653 shading. However, drawing the boundary is often needed:
3654 \begin{verbatim}
3655 \shade\plrregion{0,90,5}{sind (2t)}
3656 \plrregion[s]{0,90,5}{sind (2t)}
3657 \end{verbatim}
3658 shades one loop of the 4-petal rosette, and then draws it.
3659
3660 The next sets of macros are similar to the previous function plotting
3661 macros, but don't fit the \meta{max}, \meta{min} \meta{step} model for
3662 the first argument. For the first (\cs{levelcurve}) this is a limitation
3663 of the task being performed. For the others (\cs{DEgraph},
3664 \cs{DEtrajectory}) it is a design choice.
3665
3666 \begin{cd}\pagelabel{levelcurve}
3667 \cs{levelcurve}\oarg{\meta{spec}}\marg{\meta{seed},\meta{step}}
3668 \marg{\meta{inequality}}%
3669 \index{levelcurve@\cs{levelcurve}}
3670 \end{cd}
3671
3672 This figure macro produces a level curve of some function $F(x,y)$.
3673 There are three requirements on the parameters for this to work
3674 correctly. First, in order to obtain the curve satisfying $F(x,y) = C$,
3675 the \marg{\meta{inequality}} must be either \verb${F(x,y) > C}$ or
3676 \verb${F(x,y) < C}$.%
3677 \footnote{A non-strict inequality such as \mfc{>=} can be
3678 used, but the result will not be significantly different.}
3679 Second, the level curve must surround the point given by the \meta{seed}
3680 paramter, and third, the inequality must be true at this seed point.
3681
3682 The command works by searching rightward from \meta{seed} until it
3683 encounters the first point on the level curve. It then tries to find a
3684 nearby point on the level curve and joins it to the first one, and
3685 continues similarly until it finds it has returned near the starting
3686 point. The meaning of ``nearby point on the level curve'' is the
3687 intersection of the level curve with a circle of radius \meta{step}
3688 centered at the previously found point. If the region defined by the
3689 inequality extends beyond the bounds of the picture (as set by the
3690 \cs{mfpic} command), the region is truncated and the resulting curve
3691 will follow along the picture's border.
3692
3693 Since the algorithm only approximates the level set, a tolerance (how
3694 close the points are to actually being \emph{on} the level curve) is
3695 chosen which gives two decimal places more accuracy than \meta{step}.
3696 The value of \meta{step} is interpreted in \emph{graph} units and
3697 so should be a pure number. The \oarg{\meta{spec}} is either \oarg{p},
3698 in which case the calculated points are joined with straight lines, or
3699 \oarg{s\meta{tension}} as in \cs{function}. The default is
3700 \oarg{s}: a smooth curve with the current default tension.
3701
3702 In general, choosing a \meta{step} that corresponds to a few millimeters
3703 works reasonably well. For example, if the graph unit is 1cm (for
3704 example, \cs{mfpicunit=1cm} and no scaling is used), then
3705 \meta{step}${}= 0.5$ might be a reasonable first choice. If the level
3706 set is reasonably smooth and \oarg{s} is used, then the result will
3707 match the actual curve to within .005cm, which is approximately .14pt,
3708 which is less than half the thickness of the standard pen used to draw
3709 it.
3710
3711 Be warned that there is a limit: there should not be more than 2000
3712 steps in the completed curve. In a figure which is 10-by-10 graph units,
3713 a level curve without too much oscillation would probably be less than
3714 80 units in length and a step size of .04 would probably produce under
3715 2000 steps. This should be accurate enough for most purposes. If you
3716 \emph{really} need more, the value of the \MF{} variable
3717 \verb$max_points$ must be changed. This can be done with
3718 \cs{setmfvariable} (see section~\ref{variables}).
3719
3720 As a special case, if \meta{step} is 0, the maximum of width and height
3721 of the figure (as given by the arguments to the \env{mfpic} environment)
3722 is divided by 100. For example, in a 5-by-10 graph, giving a step size
3723 of $0$ will actually select \meta{step}${}= 10/100 = 0.1$.
3724
3725 The algorithm used will produce imprecise results if there are two
3726 points on the curve closer than \meta{step} in straight-line distance,
3727 but much further apart when measured along the curve.
3728
3729 \begin{cd}\pagelabel{DEgraph}
3730 \cs{DEgraph}\oarg{\meta{spec}}%
3731 \marg{\meta{$x_0$},\meta{$y_0$},\meta{$\Delta s$},\meta{$N$}}%
3732 \marg{$f(\mathtt{x},\mathtt{y})$}\\
3733 \cs{DEtrajectory}\oarg{\meta{spec}}%
3734 \marg{\meta{$p_0$},\meta{$\Delta s$},\meta{$N$}}%
3735 \marg{$\mathbf{F}(\mathtt{x},\mathtt{y},\mathtt{t})$}%
3736 \index{DEgraph@\cs{DEgraph}}%
3737 \index{DEtrajectory@\cs{DEtrajectory}}%
3738 \end{cd}
3739
3740 The first of these plots the graph of the solution of the differential
3741 equation
3742 $$
3743 \frac{dy}{dx} = f(x,y)\,,\quad y(x_0) = y_0\,.
3744 $$
3745 The \meta{$\Delta s$} parameter is a step size and the \meta{$N$}
3746 parameter is the number of steps. The step size is \emph{not} an
3747 increment in the $x$ variable. Rather is is (roughly) the distance from
3748 one point to the next along the graph as \MF{} computes them. That is,
3749 \MF{} computes using a variable $x$-step $\Delta x$, chosen so that
3750 $\sqrt{\Delta x^2 + \Delta y^2}$ is approximately \meta{$\Delta s$}. The
3751 algorithm used is a modified 4-step Ringe-Kutta method.
3752
3753 The second macro, \cs{DEtrajectory} draws the path traced by the
3754 solution $(x(t),y(t))$ of
3755 $$
3756 \left( \frac{dx}{dt},\frac{dy}{dt} \right) = \mathbf{F}(x,y,t)\,,
3757 \quad (x(0),y(0)) = p_0\,.
3758 $$
3759 This is not a \emph{graph}, since the dependence on $t$ cannot be shown
3760 in two dimensions (a third dimension would be needed). The parameter
3761 \meta{$p_0$} should be an ordered pair of numbers, the \meta{$\Delta s$} and
3762 \meta{$N$} are as for \cs{DEgraph}. The function $\mathbf{F}(x,y,t)$
3763 should be either a pair-valued expression or an ordered pair of numeric
3764 expressions. The variables must be literally \texttt{x}, \texttt{y} and
3765 \texttt{t}. The expressions do not have to explicitly depend on these
3766 variables. In fact, the \cs{DEgraph} macro is implemented using the same
3767 internal macro as \cs{DEtrajectory} with $\mathbf{F}(x,y,t) = (1,
3768 f(x,y))$ and $p_0 = (x_0,y_0)$.
3769
3770 Notice that the trajectory starts at $t=0$. If you need some other
3771 starting value $t=a$, then replace $t$ in the formula for
3772 $\mathbf{F}(x,y,t)$ with $(t+a)$.
3773
3774 It is possible to use a negative value of $\Delta s$ in both these
3775 macros. For \cs{DEgraph} this produces the graph to the left of $x=x_0$,
3776 and for \cs{DEtrajectory} it produces the trajectory with time running
3777 backward. For the latter, it is also equivalent to replacing
3778 $\mathbf{F}(x,y,t)$ by its negative.
3779
3780 The purpose of making \meta{$\Delta s$} a distance rather than an
3781 $x$-increment or a $t$-increment (as the Runge-Kutta method is taught in
3782 the usual mathematics courses) is stability: even very simple
3783 differential equations can have graphs the tend to $\infty$ in finite
3784 time. These macros, however, never travel more than a distance $N\Delta
3785 s$ from the starting point.
3786
3787 If you want to use \mfp{} to illustrate the results of the standard
3788 Runge-Kutta method or other methods, you can use the \prog{mfpic4ode}
3789 package. That package also includes the Euler method and the two-step
3790 Runge-Kutta method. It loads \mfp{} if it has not already been loaded.
3791 Like \mfp{}, it works in plain \TeX{} (with \verb$\input mfpic4ode$) or
3792 \LaTeX{} (with \verb$\usepackage{mfpic4ode}$).
3793
3794
3795 \subsection{Plotting external data files}\label{external}
3796
3797 \begin{cd}\pagelabel{datafile}
3798 \cs{datafile}\oarg{\meta{spec}}\marg{\meta{file}}\\
3799 \cs{smoothdata}\oarg{\meta{tension}}\\
3800 \cs{unsmoothdata}%
3801 \index{datafile@\cs{datafile}}%
3802 \index{smoothdata@\cs{smoothdata}}%
3803 \index{unsmoothdata@\cs{unsmoothdata}}
3804 \end{cd}
3805
3806 The figure macro \cs{datafile} produces a curve connecting the points
3807 listed in the file \meta{file}. (The context makes it clear whether this
3808 meaning of \cs{datafile} or that of subsection~\ref{list} is meant.) The
3809 \meta{spec} may be \texttt{p} to produce a polygonal path, or \texttt{s}
3810 followed by a tension value (as in \cs{curve}) to produce a smooth path.
3811 If no \meta{spec} is given, the default is initially \texttt{p}, but
3812 \cs{smoothdata} may be used to change this. Thus, after the command
3813 \cs{smoothdata}\oarg{\meta{tension}} the default \oarg{\meta{spec}} is
3814 changed to \oarg{s\meta{tension}}. If the tension parameter is not
3815 supplied it defaults to \mfc{1.0} (or the value set by the
3816 \cs{settension} command if one has been used).
3817
3818 The command \cs{unsmoothdata} restores the default \oarg{\meta{spec}} to
3819 \oarg{p}.
3820
3821 By default, each non-blank line in the file is assumed to contain at
3822 least two numbers, separated by whitespace (blanks or tabs). The first
3823 two numbers on each line are assumed to represent the $x$- and
3824 $y$-coordinates of a point. Initial blank lines in the file are ignored,
3825 as are comments. The comment character in the data file is assumed to be
3826 \texttt{\%}, but it can be reset using \cs{mfpdatacomment} (below). Any
3827 blank line other than at the start of the file causes the curve to
3828 terminate. The \cs{datafile} command may be preceded by any of the
3829 prefix commands, so that, for example, a closed curve could be formed
3830 with \cs{lclosed}\cs{datafile}\marg{data.dat}.
3831
3832 The \index{datafile@\cs{datafile}}\cs{datafile} command has another use,
3833 independent of the above description. We saw in subsection~\ref{list}
3834 that any \mfp{} command (other than one that prints text labels) that
3835 takes as its last argument a list of points (or numerical values)
3836 separated by commas, can have that list replaced with a reference to an
3837 external data file. For example, if a file \file{ptlist.dat} contains
3838 two or more numerical values per line separated by whitespace, then one
3839 can draw a dot at each of the points corresponding to the first pair of
3840 numbers on each line with the following.
3841 \begin{verbatim}
3842 \point\datafile{ptlist.dat}
3843 \end{verbatim}
3844 In fact there is no essential difference between `\cs{datafile}\oarg{p}'
3845 and `\cs{polyline}\cs{datafile}', and no difference between
3846 `\cs{datafile}\oarg{s}' and `\cs{curve}\cs{datafile}'.
3847 Here is the full list (omitting aliases) of \mfp{} macros that allow
3848 this usage of \cs{datafile}\index{datafile@\cs{datafile}}:
3849
3850 \begin{itemize}
3851 \raggedright
3852 \item Numeric data:
3853 \cs{barchart}, \cs{dashpattern}, \cs{numericarray},
3854 \cs{piechart}, and all the axis marks commands.
3855 \item Point or vector data:
3856 \cs{cbeziers}, \cs{closedcbeziers}, \cs{closedcomputedspline},
3857 \cs{closedcspline}, \cs{closedmfbezier}, \cs{closedqbeziers},
3858 \cs{closedqspline}, \cs{computedspline}, \cs{convexcurve},
3859 \cs{convexcyclic}, \cs{cspline}, \cs{curve}, \cs{cyclic},
3860 \cs{fcncurve}, \cs{fcnspline}, \cs{mfbezier},
3861 \cs{periodicfcnspline}, \cs{plotsymbol}, \cs{point}, \cs{polygon},
3862 \cs{polyline}, \cs{putmfpimage}, \cs{qbeziers}, \cs{qspline},
3863 \cs{turtle}, and \cs{pairarray}.
3864 \end{itemize}
3865 In addition \cs{setarray} and \cs{globalsetarray} (with the numeric or
3866 pair data type) allow this usage.
3867
3868 \begin{cd}\pagelabel{mfpdatacomment}
3869 \cs{mfpdatacomment}\cs{}\meta{char}%
3870 \index{mfpdatacomment@\cs{mfpdatacomment}}
3871 \end{cd}
3872
3873 Changes \meta{char} to a comment character and changes the usual \TeX{}
3874 comment character \texttt{\%} to an ordinary character \emph{while reading a
3875 datafile for drawing}.
3876
3877 \begin{cd}\pagelabel{using}
3878 \cs{using}\marg{\meta{in-pattern}}\marg{\meta{out-pattern}}%
3879 \index{using@\cs{using}}
3880 \end{cd}
3881
3882 Used to change the assumptions about the format of the data file. For
3883 example, if there are four numbers on each line separated by commas, to
3884 plot the third against the second (in that order) you can say
3885 \cs{using}\marg{\#1,\#2,\#3,\#4}\marg{(\#3,\#2)}. This means the
3886 following: Everything on a line up to the first comma is assigned to
3887 parameter \texttt{\#1}, everything from there up to the second comma is
3888 assigned to parameter \texttt{\#2}, etc. Everything from the third comma
3889 to the end of line is assigned to \texttt{\#4}. When the line is
3890 processed by \TeX{} a \MF{} pair is produced representing a point on the
3891 curve. \CMF{} pair expressions can be used in the output portion of
3892 \cs{using}. For example \cs{using}\marg{\#1,\#2,\#3}\marg{(\#2,\#1)/10}
3893 or even \cs{using}\marg{\#1 \#2 \#3}\marg{polar(\#1,\#2)} if the data
3894 are polar coordinates. The default assumptions of the \cs{datafile}
3895 command (numbers separated by spaces, with the first two determining the
3896 $(x,y)$ pair) corresponds to the following setting.
3897 \begin{verbatim}
3898 \using{#1 #2 #3}{(#1,#2)}
3899 \end{verbatim}
3900 The \cs{using} command cannot normally be used in the replacement text
3901 of another command. Or rather, it can be so used, but then each
3902 \texttt{\#} has to be doubled. If a \cs{using} declaration occurs in an
3903 \env{mfpic} environment it is local to that environment. Otherwise it
3904 affects all subsequent ones.
3905
3906 \begin{cd}\pagelabel{sequence}
3907 \cs{sequence}%
3908 \index{sequence@\cs{sequence}}
3909 \end{cd}
3910
3911 As a special case, you can plot any number against its sequence
3912 position, with something like
3913 \cs{using}\marg{\#1 \#2}\marg{(\cs{sequence},\#1)}. Here, the macro
3914 \cs{sequence} will take on the values \texttt{1}, \texttt{2}, etc. as
3915 lines are read from the file.
3916
3917 \begin{cd}\pagelabel{usingpairdefault}
3918 \cs{usingpairdefault}\\
3919 \cs{usingnumericdefault}%
3920 \index{usingpairdefault@\cs{usingpairdefault}}%
3921 \index{usingnumericdefault@\cs{usingnumericdefault}}
3922 \end{cd}
3923
3924 The command \cs{usingpairdefault} restores the above described default
3925 for pair data. The command \cs{usingnumericdefault} is the equivalent of
3926 \cs{using}\marg{\#1 \#2}\marg{\#1}, a useful default for numeric data.
3927
3928 Note that the default value of \cs{using} appears to reference three
3929 arguments. If there are only two numbers on a line separated by
3930 whitespace, this will still work because of \TeX{}'s argument matching
3931 rules. \TeX{}'s file reading mechanism normally converts the EOL to a
3932 space, but there are exceptions so \mfp{} internally adds a space at
3933 the end of each line read in to be on the safe side. Then the default
3934 definition of \cs{using} reads everything up to the first space as
3935 \texttt{\#1} (whitespace is normally compressed to a single space by
3936 \TeX{}'s reading mechanism), then everything to the second space (the one
3937 added at the end of the line, perhaps) is \texttt{\#2}, then everything
3938 to the EOL is \texttt{\#3}. This might assign an empty argument to
3939 \texttt{\#3}, but it is discarded anyway.
3940
3941 If the numerical data contain percentages with explicit \texttt{\%} signs,
3942 then choose another comment character with \cs{mfpdatacomment}. This
3943 will change \texttt{\%} to an ordinary character \emph{in the data file}.
3944 However, in your \cs{using} command it would still be read as a comment.
3945 The following allows one to overcome this.
3946
3947 \begin{cd}\pagelabel{makepercentother}
3948 \cs{makepercentother}\\
3949 \cs{makepercentcomment}%
3950 \index{makepercentother@\cs{makepercentother}}%
3951 \index{makepercentcomment@\cs{makepercentcomment}}
3952 \end{cd}
3953
3954 Here is an example or their use:
3955 \begin{verbatim}
3956 \makepercentother
3957 \using{#1% #2 #3}{(#1/100,#2)}
3958 \makepercentcomment
3959 \end{verbatim}
3960
3961 Here is an analysis of the meaning of this example: everything in a
3962 line, up to the first percent followed by a space is assigned to
3963 parameter \texttt{\#1}, everything from there to the next space is
3964 assigned to \texttt{\#2} and the rest of the line (which may be empty)
3965 is \texttt{\#3}. On the output side in the above example, the percentage
3966 is divided by 100 to convert it to a fraction, and plotted against the
3967 second parameter. Note: normal comments should not be used between
3968 \cs{makepercentother} and \cs{makepercentcomment}, for obvious reasons.
3969 Moreover, the above construction will fail inside the argument of
3970 another command.
3971
3972 \begin{cd}\pagelabel{plotdata}
3973 \cs{plotdata}\oarg{\meta{spec}}\marg{\meta{file}}%
3974 \index{plotdata@\cs{plotdata}}
3975 \end{cd}
3976
3977 This plots several curves from a single file. The \meta{spec} and the
3978 command \cs{smoothdata} have the same effect on each curve as in the
3979 \cs{datafile} command. The data for each curve is a succession of
3980 nonblank lines separated from the data for the next curve by a single
3981 blank line. A \emph{pair} of successive blank lines is treated as the
3982 end of the data. No prefix macros are permitted in front of
3983 \cs{plotdata}.
3984
3985 Each successive curve in the data file is drawn differently. By default,
3986 the first is drawn as a solid line the next dashed, the third dotted,
3987 etc., through a total of six different line types. A \cs{gendashed}
3988 command is used with predefined dash patterns named \mfc{dashtype0}
3989 through \mfc{dashtype5}. This behavior can be changed with:
3990
3991 \begin{cd}\pagelabel{coloredlines}
3992 \cs{coloredlines}\\
3993 \cs{pointedlines}\\
3994 \cs{datapointsonly}\\
3995 \cs{dashedlines}%
3996 \index{coloredlines@\cs{coloredlines}}%
3997 \index{pointedlines@\cs{pointedlines}}%
3998 \index{datapointsonly@\cs{datapointsonly}}%
3999 \index{dashedlines@\cs{dashedlines}}
4000 \end{cd}
4001
4002 The command \cs{coloredlines} causes \cs{plotdata} to use the rendering
4003 command \cs{draw} with a color option that cycles through eight
4004 different colors starting with black (hey! black is a color too). The
4005 command \cs{pointedlines} causes \cs{plotdata} to use the rendering
4006 command \cs{plot}, cycling through nine symbols. The command
4007 \cs{datapointsonly} causes \cs{plotdata} to use the rendering command
4008 \cs{plotnodes}, cycling through the same nine symbols. The data points
4009 become the nodes of the paths created and so only the data points are
4010 plotted. The command \cs{dashedlines} restores the default. See
4011 appendix~\ref{styles} for the details on the actual dash patterns,
4012 colors and symbols used.
4013
4014 The command \cs{coloredlines} will produce a warning under the
4015 \opt{metafont} option and substitute \cs{dashedlines}. Under the
4016 \opt{metapost} option, this is the sole exception to the general rule
4017 that all curves are drawn in \gbc{drawcolor} by default: the
4018 \cs{plotdata} command after \cs{coloredlines} has been issued.
4019
4020 Note that \mfp{} always creates a path internally. It is possible that
4021 your data is not path-like and what you want is a scatter-plot. Simply
4022 use \cs{datapointsonly} and the effect is the same: \MP{} builds a
4023 polygonal path connecting all the points in your file, but when it plots
4024 the path, it only places a dot (or other symbol) at each data point.
4025
4026 If, for some reason, you do not like the default starting line style
4027 (say you want to start with a color other than black), you can use one
4028 of the following commands.
4029
4030 \begin{cd}\pagelabel{mfplinetype}
4031 \cs{mfplinetype}\marg{\meta{num}}, or\\
4032 \cs{mfplinestyle}\marg{\meta{num}}%
4033 \index{mfplinetype@\cs{mfplinetype}}%
4034 \index{mfplinestyle@\cs{mfplinestyle}}
4035 \end{cd}
4036
4037 Here \meta{num} is a non-negative number, less than the number of
4038 different drawing types available. The four previous commands reset the
4039 number to 0, so if you use one of them, issue \cs{mfplinetype}
4040 \emph{after} it. The different line styles are numbered starting from
4041 $0$. If two or more \cs{plotdata} commands are used in the same
4042 \env{mfpic} environment, the numbering in each continues where the one
4043 before left off (unless you issue one of the commands above in between).
4044 \cs{mfplinestyle} means the same as \cs{mfplinetype}, and is included
4045 for compatibility. See appendix~\ref{styles} to find out what dash pattern,
4046 color or symbol corresponds to each number by default. The commands
4047 below can be used to change the default dashes, colors, or symbols.
4048
4049 \begin{cd}\pagelabel{reconfigureplot}
4050 \cs{reconfigureplot}\marg{dashes}\marg{\meta{pat$_1$},\dots,\meta{pat$_n$}}\\
4051 \cs{reconfigureplot}\marg{colors}\marg{\meta{clr$_1$},\dots,\meta{clr$_n$}}\\
4052 \cs{reconfigureplot}\marg{symbols}\marg{\meta{symb$_1$},\dots,\meta{symb$_n$}}%
4053 \index{reconfigureplot@\cs{reconfigureplot}}
4054 \end{cd}
4055
4056 The first argument of \cs{reconfigureplot} is the rendering method to be
4057 changed: \texttt{dashes}, \texttt{colors} or \texttt{symbols}. The
4058 second argument is a list of dash patterns, colors, or symbols. The dash
4059 patterns should be names of patterns defined through the use of
4060 \cs{dashpattern}. The colors can be any color names already known to
4061 \MP{}, or color names defined using \cs{mfpdefinecolor}.
4062 The symbols can be any of those listed with the \cs{plotsymbol} command
4063 (see subsection~\ref{points}), or any known \MF{} path variable. The
4064 colors can also be \MP{} color constants or expressions, and the symbols
4065 can be expressions of type path. In recent \MP{} these `colors' can be
4066 \kw{numeric} (selecting gray), \kw{rgbcolor} or \kw{cmykcolor}. Within a
4067 \env{mfpic} environment, the changes made are local to that environment.
4068 Outside, they affect all subsequent environments.
4069
4070 Using \cs{reconfigureplot}\marg{colors} under the \opt{metafont} option
4071 will have no effect, but may produce an error from \MF{} unless the
4072 colors used conform to the guidelines in subsection~\ref{MFcolor}.
4073 This also holds for \cs{defaultplot}\marg{colors} (below).
4074
4075 \begin{cd}\pagelabel{defaultplot}
4076 \cs{defaultplot}\marg{dashes}\\
4077 \cs{defaultplot}\marg{colors}\\
4078 \cs{defaultplot}\marg{symbols}
4079 \index{defaultplot@\cs{defaultplot}}
4080 \end{cd}
4081
4082 The command \cs{defaultplot} restores the built-in defaults for the
4083 indicated method of rendering in \cs{plotdata}.
4084
4085 The commands \cs{using}, \cs{mfpdatacomment} and \cs{sequence} have the
4086 same meaning here (for \cs{plotdata}) as they do for \cs{datafile}
4087 (above). The sequence numbering for \cs{sequence} starts over with each
4088 new curve.
4089
4090
4091 \section{Labels and Captions.}\label{labels}
4092
4093 \subsection{Setting text}\label{text}
4094
4095 If option \opt{metafont} is in effect macros \cs{tlabel}, \cs{tlabels},
4096 \cs{axislabels} and \cs{tcaption} do not affect the \MF{} file
4097 (\file{\meta{file}.mf}) at all, but are added to the picture by \TeX{}. If
4098 \opt{metapost} is in effect but \opt{mplabels} is not, they do not
4099 affect the \MP{} file. In these cases, if these macros are the only
4100 changes or additions to your document, there is no need to repeat the
4101 processing with \MF{} or \MP{} nor the reprocessing with \TeX{} in order
4102 to complete your \TeX{} document.
4103
4104 \begin{cd}\pagelabel{tlabel}
4105 \cs{tlabel}\oarg{\meta{just}}\parg{\meta{x},\meta{y}}\marg{\meta{labeltext}}\\
4106 \cs{tlabel}\oarg{\meta{just}}\marg{\meta{pair-list}}\marg{\meta{label text}}\\
4107 \cs{tlabels}\marg{\meta{params$_1$} \meta{params$_2$} $\ldots$}%
4108 \index{tlabel@\cs{tlabel}}%
4109 \index{tlabels@\cs{tlabels}}
4110 \end{cd}
4111
4112 These place \TeX{} text or math on the graph. The special form
4113 \cs{tlabels} (note the plural) essentially just applies \cs{tlabel} to
4114 each set of parameters listed in its argument. That is, each
4115 \meta{params$_k$} is a valid set of parameters for a \cs{tlabel}
4116 command. These can be separated by spaces, newlines, or nothing at all.
4117 They should \emph{not} be separated by blank lines.
4118
4119 The last required parameter is ordinary \TeX{} text. The pair
4120 \parg{\meta{x},\meta{y}} gives the coordinates of a point in the graph
4121 where the text will be placed. It may optionally be enclosed in braces,
4122 \verb${$ and \verb$}$. If braces are used, any number of coordinate
4123 pairs may be listed, separated by commas. This is what is meant by
4124 \meta{pair-list} in the above syntax. If \opt{mplabels} is in effect,
4125 the \meta{pair-list} can be any list of expressions recognized as a pair
4126 by \MP{}.
4127
4128 The optional parameter \oarg{\meta{just}} specifies the
4129 \emph{justification}, the relative placement of the label with respect
4130 to the point with coordinates \parg{\meta{x},\meta{y}}. It is a
4131 two-character sequence in which the first character is one of \texttt{t}
4132 (top), \texttt{c} (center), \texttt{b} (bottom), or \texttt{B}
4133 (Baseline), to specify vertical placement, and the second character is
4134 one of \texttt{l} (left), \texttt{c} (center), or \texttt{r} (right), to
4135 specify horizontal placement. These letters specify what part of the
4136 \emph{text} is to be placed at the given point, so \texttt{r} puts the
4137 right end of the text there---which means the text will be left of the
4138 point. The default justification is \oarg{Bl}: the left end of the
4139 baseline of the text is placed at the coordinates.
4140
4141 When \opt{mplabels} is in effect, the two characters may optionally be
4142 followed by a number, specifying an angle in degrees to rotate the text
4143 about the point \parg{\meta{x},\meta{y}}. If the angle is supplied
4144 without \opt{mplabels} it is ignored after a warning. If the angle is
4145 absent, there is no rotation. Note that the rotation takes place after
4146 the placement and uses the given point as the center of rotation. For
4147 example, \oarg{cr} will place the text left of the point, while
4148 \oarg{cr180} will rotate it around to the right side of the point (and
4149 upsidedown, of course).
4150
4151 There should be no spaces before, between, or after the first two
4152 characters. However the number, if present, is only required to be a
4153 valid \MP{} numerical expression containing no bracket characters; as
4154 such, it may contain some spaces (e.g., around operations as in
4155 \texttt{45 + 30}).
4156
4157 A multiline \cs{tlabel} may be specified by explicit line breaks, which
4158 are indicated by the \bbsl{} command or the \cs{cr} command. This is a
4159 very rudimentary feature. By default it left justifies the lines and
4160 causes \cs{tlabel} to redefine \bbsl. One can center a line by putting
4161 \cs{hfil} as the first thing in the line, and right justify by putting
4162 \cs{hfill} there (these are \TeX{} primitives). Redefining \bbsl{} can
4163 interfere with \LaTeX{}'s definition. For better control in \LaTeX{} use
4164 \cs{shortstack} inside the label (or a \env{tabular} environment or some
4165 other environment which always initializes \bbsl{} with its own
4166 definition).
4167
4168 If the label goes beyond the bounds of the graph in any direction, the
4169 space reserved for the graph is expanded to make room for it. (Note:
4170 this behavior is very much different from that of the \LaTeX{}
4171 \env{picture} environment.)
4172
4173 If the \opt{mplabels} option is in effect, \cs{tlabel} will write a
4174 \mfc{btex $\ldots$ etex} group to the output file, allowing \MP{} to
4175 arrange for typesetting the label. Normally, the label becomes part of
4176 the picture, rather than being laid on top of it, and can be covered up
4177 by any filling macros that follow, or clipped off by \cs{gclip}.
4178 However, under the \opt{overlaylabels} option (or after the command
4179 \cs{overlaylabels}), labels are saved and added to the picture at the
4180 very end. This may prevent some special effects, but it makes the
4181 behavior of labels much more consistent through all the 12 permissable
4182 settings of the options \opt{metapost}, \opt{mplabels}, \opt{clip}, and
4183 \opt{truebbox}.
4184
4185 There is another command, \cs{startbacktext}, which also save the labels
4186 and adds them later, but \emph{under} the rest of the picture as
4187 background text. Thus, they will not be clipped, but may be covered up.
4188 Since erasing regions with \cs{gclear} actually covers up those regions
4189 with white, labels saved as background text may appear to have portions
4190 erased.
4191
4192 \begin{cd}\pagelabel{everytlabel}
4193 \cs{everytlabel}\marg{\meta{\TeX{}-code}}%
4194 \index{everytlabel@\cs{everytlabel}}
4195 \end{cd}
4196
4197 One problem with multiline \cs{tlabel}s is that each line of their
4198 contents constitutes a separate group. This makes it difficult to change
4199 the \cs{baselineskip} (for example) inside a label. The command
4200 \cs{everytlabel} saves it's contents in a token register and the code is
4201 issued in each \cs{tlabel}, as the last thing before the actual line(s)
4202 of text. Any switch you want to apply to every line can be supplied. For
4203 example
4204 \begin{verbatim}
4205 \everytlabel{\bf\baselineskip 10pt}
4206 \end{verbatim}
4207 will make every line of every \cs{tlabel}'s text come out bold with 10
4208 point baselines. The effect of \cs{everytlabel} is local to the
4209 \env{mfpic} environment, if it is issued inside one. Note that each line
4210 of a tlabel is wrapped in a box, but the commands of \cs{everytlabel}
4211 are outside all of them, so no actual text should be produced by the
4212 contents of \cs{everytlabel}.
4213
4214 Using \cs{tlabel} without an optional argument is equivalent to
4215 specifying \oarg{Bl}. Use the following command to change this
4216 behavior.
4217
4218 \begin{cd}\pagelabel{tlabeljustify}
4219 \cs{tlabeljustify}\marg{\meta{just}}%
4220 \index{tlabeljustify@\cs{tlabeljustify}}
4221 \end{cd}
4222
4223 After this command the placement of all subsequent labels without
4224 optional argument will be as specified in this command. For example,
4225 \cs{tlabeljustify}\marg{cr45} would cause all subsequent \cs{tlabel}
4226 commands lacking an optional argument to be placed as if the argument
4227 \oarg{cr45} were used in each. If \opt{mplabels} is not in effect at the
4228 time of this command, the rotation part will be saved in case that
4229 option is turned on later, but a warning message will be issued. If
4230 \opt{mplabels} is not turned on later, that rotation will be ignored by
4231 \cs{tlabel}.
4232
4233 \begin{cd}\pagelabel{tlabeloffset}
4234 \cs{tlabeloffset}\marg{\meta{hlen}}\marg{\meta{vlen}}\\
4235 \cs{tlpointsep}\marg{\meta{len}}\\
4236 \cs{tlpathsep}\marg{\meta{len}}\\
4237 \cs{tlabelsep}\marg{\meta{len}}%
4238 \index{tlabeloffset@\cs{tlabeloffset}}%
4239 \index{tlabelsep@\cs{tlabelsep}}%
4240 \index{tlpathsep@\cs{tlpathsep}}%
4241 \index{tlpointsep@\cs{tlpointsep}}
4242 \end{cd}
4243
4244 The first command causes all subsequent \cs{tlabel} commands to shift
4245 the label right by \meta{hlen} and up by \meta{vlen} (negative lengths
4246 cause it to be shifted left and down, respectively).
4247
4248 The \cs{tlpointsep} command causes labels to be shifted by the given
4249 amount in a direction that depends on the optional positioning
4250 parameter. For example, if the first letter is \texttt{t} the label is
4251 shifted down by the amount \meta{len} and if the second letter is
4252 \texttt{l} it is also shifted right. In all cases it is shifted
4253 \emph{away} from the point of placement (unless the dimension is
4254 negative). If \texttt{c} or \texttt{B} is the first parameter, no
4255 vertical shift takes place, and if \texttt{c} is the second, there is no
4256 horizontal shift. This is intended to be used in cases where something
4257 has been drawn at that particular point, in order to separate the text
4258 from the drawing.
4259
4260 Prior to version 0.8, this separation also defined the separation
4261 between the label and those curves designed to frame the label
4262 such as \cs{tlabelrect} (subsection~\ref{surrounding}). Now the two
4263 separations are independent and \cs{tlpathsep} is used to set the
4264 separation between the label and such paths.
4265
4266 For backward compatability, the command \cs{tlabelsep} is still
4267 available and sets both separations to the same value.
4268
4269 \begin{cd}\pagelabel{axislabels}
4270 \cs{axislabels}\marg{\meta{axis}}\oarg{\meta{just}}%
4271 \marg{\marg{\meta{text$_1$}}\meta{$n_1$},%
4272 \marg{\meta{text$_2$}}\meta{$n_2$},$\ldots$}%
4273 \index{axislabels@\cs{axislabels}}
4274 \end{cd}
4275
4276 This command places the given \TeX{} text (\meta{text$_k$}) at the given
4277 positions (\meta{$n_k$}) on the given axis, \meta{axis}, which must be a
4278 single letter and one of \texttt{l}, \texttt{b}, \texttt{r}, \texttt{t},
4279 \texttt{x}, or \texttt{y}. The text is placed as in \cs{tlabels}
4280 (including the taking into account of \cs{tlpointsep} and
4281 \cs{tlableoffset}), except that the default justification depends on the
4282 axis (the settings of \cs{tlabeljustify} are ignored). In the case of
4283 the border axes, the default is to place the label outside the axis and
4284 centered. So, for example, for the bottom axis it is \oarg{tc}. The
4285 defaults for the $x$- and $y$-axis are below and left, respectively. The
4286 optional \meta{just} can be used to change this. For example, to place
4287 the labels \emph{inside} the left border axis, use \oarg{cl}. If
4288 \opt{mplabels} is in effect, rotations can be included in the
4289 justification parameter. For example, to place the text strings
4290 `first', `second' and `third' just below the positions 1, 2 and 3
4291 on the $x$-axis, rotated so they read upwards at a 90 degree angle, one
4292 can use \cs{axislabels}\marg{x}\oarg{cr90}\marg{\marg{first}1,
4293 \marg{second}2, \marg{third}3}.
4294
4295 \begin{cd}\pagelabel{plottext}
4296 \cs{plottext}\oarg{\meta{just}}\marg{\meta{text}}\marg{($x_0$,$y_0$),
4297 ($x_1$,$y_1$), $\ldots$}%
4298 \index{plottext@\cs{plottext}}
4299 \end{cd}
4300
4301 Similar in effect to \cs{point} and \cs{plotsymbol}, \cs{plottext}
4302 places a copy of \meta{text} at each of the listed points. Since \mfp{}
4303 version 0.9, when \cs{tlabel} was enhanced to allow lists of points, it
4304 is implemented by an equivalent \cs{tlabel} command and is only kept for
4305 backward compatibility. It differs from \cs{tlabel} when the optional
4306 argument is absent: the default justification is \oarg{cc} regardless of
4307 the setting of \cs{tlabeljustify}.
4308
4309 \begin{cd}\pagelabel{mfpverbtex}
4310 \cs{mfpverbtex}\marg{\meta{\TeX{}-cmds}}%
4311 \index{mfpverbtex@\cs{mfpverbtex}}
4312 \end{cd}
4313
4314 This writes a \mfc{verbatimtex} block to the \file{.mp} file. It makes
4315 sense only if the \opt{mplabels} option is used and so only for \MP{}.
4316 The \meta{\TeX{}-cmds} in the argument are written to the \file{.mp}
4317 file, preceded by the \MP{} command \mfc{verbatimtex} and followed by
4318 \mfc{etex}. Line breaks within the \meta{\TeX{}-cmd} are preserved.
4319 There is also a linebreak between the end of \meta{\TeX-cmds} and the
4320 \mfc{etex}. The \cs{mfpverbtex} command must come before any \cs{tlabel}
4321 that is to be affected by it. Any settings common to all \env{mfpic}
4322 environments should be in a \cs{mfpverbtex} command preceding all such
4323 environments.
4324
4325 It may be issued at any point after \mfp{} is loaded, and any number of
4326 times. If it is issued after \cs{opengraphsfile}, its contents are
4327 immediately written to the \file{.mp} file. If it is issued before
4328 \cs{opengraphsfile}, its contents are saved and written when the file is
4329 opened (successive uses being cummulative). In this case its contents
4330 will precede the boilerplate \TeX{} code that \mfp{} writes. If you wish
4331 to redefine some of that code, you need to use \cs{mfpverbtex} after
4332 \cs{opengraphsfile}.
4333
4334 Because of the way \MP{} handles \mfc{verbatimtex} material, the effects
4335 cannot be constrained by any grouping unless one places \TeX{} grouping
4336 commands within \meta{\TeX{}-cmds}. However, \mfp{} itself places
4337 grouping commands into the output file at the beginning and end of each
4338 picture, so definitions written by a \cs{mfpverbtex} are local to any
4339 picture in which it occurs. Prior to version 0.8, \mfp{} did not write
4340 comments that occured within the \meta{\TeX{}-cmds}. Now they will be
4341 preserved, and can be used to place the `\verb$%&latex$' line that some
4342 \TeX{} distributions permit as a signal that latex should be run to
4343 produce the labels.
4344
4345 This command attempts a near-verbatim writing of the \meta{\TeX{}-cmds}
4346 and, as with all verbatim-like commands, it should not be used in the
4347 argument of another command.
4348
4349 \begin{cd}\pagelabel{backtext}
4350 \cs{startbacktext} \dots \cs{stopbacktext}%
4351 \index{startbacktext@\cs{startbacktext}}%
4352 \index{stopbacktext@\cs{stopbacktext}}
4353 \end{cd}
4354
4355 When \TeX{} adds labels (\cs{nomplabels}) they have to be positioned
4356 either on top of a complete figure, or placed under a complete figure.
4357 The most reasonable choice (and happily the easiest to implement) is to
4358 put them on top. When \MP{} is placing labels (option \opt{mplabel}) the
4359 same can be forced with the option \opt{overlaylabels}, but otherwise
4360 they are placed as they occur, with later drawing commands perhaps
4361 putting their results on top of the labels or clipping parts of them off.
4362
4363 Sometimes it is useful to place some label as a background (not on top),
4364 and yet not have it clipped by later commands. The effect of the command
4365 \cs{startbacktext} is that \cs{tlabel} commands are saved in a special
4366 place until the command \cs{stopbacktext}. Then, at \cs{endmfpic} the
4367 rest of the figure is simply place on top of them. Since labels in \MP{}
4368 files can only consist of characters from some font, if one wants to
4369 include a graphic in the background (for example, via
4370 \cs{includegraphics}), one needs to switch off \opt{mplabels}:
4371 \begin{verbatim}
4372 \nomplabels
4373 \startbacktext
4374 \tlabel[cc](0,0){\includegraphics{mygraph}}
4375 \stopbacktext
4376 \usemplabels
4377 \end{verbatim}
4378 As with other labels, it is permitted to switch \opt{mplabels} off and
4379 on while creating background text. If there are both kinds of labels
4380 within the background text area the ones handled by \TeX{} will be
4381 further back than the ones handled by \MP{}. Within a given type,
4382 earlier ones are further back than later ones.
4383
4384 \Mfp{} normally uses a naming scheme like \cs{cmd} \dots \cs{endcmd} and
4385 tries to arrange that \env{cmd} can be used as an environment. As
4386 currently written, the extra grouping added by \cs{begin}\marg{cmd} and
4387 \cs{end}\marg{cmd} would break the code that implements background text,
4388 so we have named these in a different way to avoid suggesting this
4389 possiblity. There should be at most one of these pairs in any
4390 \env{mfpic} environment. It can occur anywhere in the environment, but
4391 the two commands must not be inside any grouping.
4392
4393 Under the \opt{metapost} option, the \cs{gclear} command doesn't really
4394 clear a space, but rather paints the space over with white. Any
4395 background text will not be visible through such `holes'. This is a
4396 limitation of \MP{}.
4397
4398 \begin{cd}\pagelabel{tcaption}
4399 \cs{tcaption}\oarg{\meta{maxwd},\meta{linewd}}\marg{\meta{caption text}}%
4400 \index{tcaption@\cs{tcaption}}
4401 \end{cd}
4402
4403 Places a \TeX{} caption at the bottom of the graph. (Not to be confused
4404 with \LaTeX{}'s similar \cs{caption} command.) The macro will
4405 automatically break lines which are too much wider than the graph---if
4406 the \cs{tcaption} line exceeds \meta{maxwd} times the width of the
4407 graph, then lines will be broken to form lines at most \meta{linewd}
4408 times the width of the graph. The default settings for \meta{maxwd} and
4409 \meta{linewd} are 1.2 and 1.0, respectively. \cs{tcaption} may typeset
4410 its argument twice (as might \LaTeX{}'s \cs{caption}), the first time as
4411 a single line to test its width, then again if that was too wide.
4412 Therefore, the user is advised \emph{not} to include any global
4413 assignments in the caption text.
4414
4415 If the \cs{tcaption} and graph have different widths, the two are
4416 centered relative to each other. If the \cs{tcaption} takes multiple
4417 lines, then the default is to set lines both left- and right-justified
4418 (except for the last line) with no indentation on the first line. If the
4419 option \opt{raggedcaptions} is in effect, the lines are only
4420 left-justified and ragged on the right. Finally, if the option
4421 \opt{centeredcaptions} is in effect, each line of the caption will be
4422 centered (under \opt{raggedcaptions} they will be ragged on both sides).
4423
4424 In a \cs{tcaption}, explicit line breaks may be specified by using the
4425 \bbsl{} command. The separation between the bottom of the picture and
4426 the caption can be changed by increasing or decreasing the skip
4427 \cs{mfpiccaptionskip}\index{mfpiccaptionskip@\cs{mfpiccaptionskip}}
4428 (a `rubber' length in Lamport's terminology).
4429
4430 Many \mfp{} users find the \cs{tcaption} command too limiting (one
4431 cannot, for example, place the caption to the side of the figure). It is
4432 common to use some other method (such as \LaTeX{}'s \cs{caption} command
4433 in a \env{figure} environment). The dimensions \cs{mfpicheight} and
4434 \cs{mfpicwidth} (see section~\ref{parameters}) might be a convenience
4435 for plain \TeX{} users who want to roll their own caption macros.
4436
4437
4438 \subsection{Curves surrounding text}\label{surrounding}
4439
4440 \begin{cd}\pagelabel{tlabelrect}
4441 \cs{tlabelrect}\oarg{\meta{rad}}\oarg{\meta{just}}%
4442 \meta{pair}\marg{\meta{text}}\\
4443 \cs{tlabelrect*...}%
4444 \index{tlabelrect@\cs{tlabelrect}}
4445 \end{cd}
4446
4447 This figure macro and the following two methods of surounding a bit of
4448 text with a curve share some common characteristics which will be
4449 described here. The commands all take an optional argument that can
4450 modify the shape of the curve. After that come arguments exactly as for
4451 the \cs{tlabel} command except that only a single point is permitted,
4452 not a list. (So \meta{pair} is either of the form
4453 \parg{\meta{x},\meta{y}} or the same enclosed in braces, or for
4454 \opt{mplabels} a pair expression in braces.) After processing the
4455 surrounding curve, a \cs{tlabel} is applied to those arguments unless a
4456 \texttt{*} is present. In order for the second optional argument (the
4457 optional justification argument for the \cs{tlabel} command) to be
4458 recognized as the second, the first optional argument must also be
4459 present. An empty first optional argument is permitted, causing the
4460 default value to be used. The default for the justification argument is
4461 \texttt{cc}, for compatibility with past \mfp{} versions, in which these
4462 commands all centered the figure around the point and no justification
4463 parameter existed. This default can be changed with the
4464 \cs{tlpathjustify} command below.
4465
4466 The plain rectangle version produces a frame separated from the text on
4467 all sides by the amount defined with \cs{tlpathsep}. All other versions
4468 produce the smallest described curve that contains this rectangle.
4469
4470 These commands may be preceded by prefix macros (see the sections
4471 \ref{modifier}~and \ref{rendering}, above). They all have a
4472 `star-form' which produces the curve but omits placing the text.
4473 All have the effect of rendering the path \emph{before} placing any
4474 text. For example, \cs{gclear}\cs{tlabelrect}\dots\ will clear the
4475 rectangle and then place the following text in the cleared space.
4476
4477 The optional argument of \cs{tlabelrect}, \meta{rad}, is a dimension,
4478 defaulting to \dim{0pt}, that produces rounded corners made from
4479 quarter-circles of the given radius. If the corners are rounded, the
4480 sides are expanded slightly so the resulting shape still encompasses the
4481 rectangle mentioned above. There is one special case for the optional
4482 argument \meta{rad}: if the keyword `\texttt{roundends}' is used instead
4483 of a dimension, the radius will be chosen to make the nearest quarter
4484 circles just meet, so the narrow side of the rectangle is a half circle.
4485
4486 \begin{cd}\pagelabel{tlabeloval}
4487 \cs{tlabeloval}\oarg{\meta{mult}}\oarg{\meta{just}}%
4488 \meta{pair}\marg{\meta{text}}\\
4489 \cs{tlabeloval*...}%
4490 \index{tlabeloval@\cs{tlabeloval}}
4491 \end{cd}
4492
4493 This figure macro is similar to \cs{tlabelrect}, except it produces an
4494 ellipse. The ellipse is calculated to have the same ratio of width to
4495 height as the rectangle mentioned above. The optional \meta{mult} is a
4496 multiplier that increases or decreases this ratio. Values of \meta{mult}
4497 larger than 1 increase the width and decrease the height.
4498
4499 \begin{cd}\pagelabel{tlabelellipse}
4500 \cs{tlabelellipse}\oarg{\meta{ratio}}\oarg{\meta{just}}%
4501 \meta{pair}\marg{\meta{text}}\\
4502 \cs{tlabelellipse*...}\\
4503 \cs{tlabelcircle}\oarg{\meta{just}}\meta{pair}\marg{\meta{text}}\\
4504 \cs{tlabelcircle*...}%
4505 \index{tlabelellipse@\cs{tlabelellipse}}%
4506 \index{tlabelcircle@\cs{tlabelcircle}}
4507 \end{cd}
4508
4509 This figure macro produces the smallest ellipse centered at the point
4510 that encompasses the rectangle defined above, and that has a ratio of
4511 width to height equal to \meta{ratio}, then places the text. The default
4512 ratio is $1$, which produces a circle. We also provide the command
4513 \cs{tlabelcircle}, which takes only the \oarg{\meta{just}} optional
4514 argument. Internally, it just processes any \texttt{*} and calls
4515 \cs{tlabelellipse} with parameter 1.
4516
4517 In the above \cs{tlabel...} curves, the optional parameter should be
4518 positive. If it is zero, all the curves silently revert to
4519 \cs{tlabelrect}. If it is negative, it is silently accepted. In the case
4520 of \cs{tlabelrect} this causes the quarter-circles at the corners to be
4521 indented rather than convex. In the other cases, there is no visible
4522 effect, but in all cases the sense of the curve is reversed.
4523
4524 \begin{cd}\pagelabel{tlpathjustify}
4525 \cs{tlpathjustify}\marg{\meta{just}}%
4526 \index{tlpathjustify@\cs{tlpathjustify}}
4527 \end{cd}
4528
4529 This can be used to change the default justification for \cs{tlabelrect}
4530 and friends. The \meta{just} parameter is exactly as in
4531 \cs{tlabeljustify} in subsection~\ref{text}.
4532
4533
4534 \section{Saving and Reusing an \mfp{} Picture.}\label{saving}
4535
4536 These commands have been changed from versions prior to 0.3.14 in order
4537 to behave more like the \LaTeX{}'s \cs{savebox}, and also to allow the
4538 reuse of an allocated box. Past files that use \cs{savepic} will have to
4539 be edited to add \cs{newsavepic} commands that allocate the \TeX{}
4540 boxes.
4541
4542 \begin{cd}\pagelabel{newsavepic}
4543 \cs{newsavepic}\marg{\meta{picname}}\\
4544 \cs{savepic}\marg{\meta{picname}}\\
4545 \cs{usepic}\marg{\meta{picname}}%
4546 \index{newsavepic@\cs{newsavepic}}%
4547 \index{savepic@\cs{savepic}}%
4548 \index{usepic@\cs{usepic}}
4549 \end{cd}
4550
4551 \cs{newsavepic} allocates a box (like \LaTeX{}'s \cs{newsavebox}) in which
4552 to save a picture. As in \cs{newsavebox}, \meta{picname} is a control
4553 sequence. Example: \cs{newsavepic}\marg{\cs{foo}}. In a \LaTeX{}
4554 document, \cs{newsavepic} is actually defined to be \cs{newsavebox}.
4555
4556 \cs{savepic} saves the \emph{next} \cs{mfpic} picture in the named box,
4557 which should have been previously allocated with \cs{newsavepic}. (This
4558 command should not be used \emph{inside} an \env{mfpic} environment.)
4559 The next picture will not be placed, but saved in the box for later use.
4560 This is primarily intended as a convenience. One \emph{could} use
4561 \begin{ex}
4562 \cs{savebox}\marg{\meta{picname}}\marg{\meta{entire \env{mfpic}
4563 environment}},
4564 \end{ex}
4565 but \cs{savepic} avoids having to place the \env{mfpic} environment in
4566 braces, and avoids one extra level of \TeX{} grouping. It also avoids
4567 reading the entire \env{mfpic} environment as a parameter, which would
4568 nullify \mfp{}'s efforts to preserve line breaks in parameters
4569 written to the \MF{} output file. If you repeat \cs{savepic} with the
4570 same \meta{picname}, the old contents are replaced with the next
4571 picture.
4572
4573 \cs{usepic} copies the picture that had been saved in the named box.
4574 This may be repeated as often as liked to create multiple copies of one
4575 picture. The \cs{usepic} command is essentially a clone of the \LaTeX{}
4576 \cs{usebox} command. Since the contents of the saved picture are only
4577 defined during the \TeX{} run, \cs{usebox} cannot be used in the
4578 \TeX-commands argument of the \cs{tlabel} command while \opt{mplabels}
4579 is in effect.
4580
4581
4582 \section{Picture Frames.}\label{frames}
4583
4584 When \TeX{} is run but before \MF{} or \MP{} has been run on the output
4585 file, \mfp{} detects that the \file{.tfm} file is missing or that
4586 the first \MP{} figure file \file{\meta{file}.1} is missing. In these
4587 cases, the \env{mfpic} environment draws only a rectangular frame with
4588 dimensions equal to the nominal size of the picture, containing the
4589 figure number (and any text placed by \cs{tlabel} and its relatives
4590 without \opt{mplabels} in effect). The command(s) used internally to do
4591 this are made available to the user.
4592
4593 \begin{cd}\pagelabel{mfpframe}
4594 \cs{mfpframe}\oarg{\meta{fsep}}%
4595 \meta{ material-to-be-framed }%
4596 \cs{endmfpframe}\\
4597 \cs{mfpframed}\oarg{\meta{fsep}}\marg{\meta{material-to-be-framed}}%
4598 \index{mfpframed@\cs{mfpframed}}%
4599 \index{endmfpframe@\cs{endmfpframe}}%
4600 \index{mfpframe@\cs{mfpframe}}
4601 \end{cd}
4602
4603 These commands surround their contents with a rectangular frame
4604 consisting of lines with thickness \cs{mfpframethickness} separated from
4605 the contents by the \meta{fsep} if specified, otherwise by the value of
4606 the dimension \cs{mfpframesep}. The default value of the \TeX{}
4607 dimensions \cs{mfpframesep} and \cs{mfpframethickness} are \dim{2pt} and
4608 \dim{0.4pt}, respectively. The \cs{mfpframe} $\ldots$ \cs{endmfpframe}
4609 version is preferred around \env{mfpic} environments or verbatim
4610 material since it avoids reading the enclosed material before
4611 appropriate \cs{catcode} changes go into effect. In \LaTeX{}, one can
4612 also use environment syntax: \cs{begin}\marg{mfpframe} $\ldots$
4613 \cs{end}\marg{mfpframe}.
4614
4615 An alternative way to frame \env{mfpic} pictures is to save them with
4616 \cs{savepic} (see previous section) and issue a corresponding
4617 \cs{usepic} command inside any framing environment or command of the user's
4618 choice or devising.
4619
4620
4621 \section{Affine Transforms.}\label{transforms}
4622
4623 Coordinate transformations that keep parallel lines in parallel are
4624 called \emph{affine transforms}. These include translation, rotation,
4625 reflection, scaling and skewing (slanting). For the \MF{} coordinate
4626 system only (that is, for paths, but not for \cs{tlabel} nor
4627 \cs{tcaption}) \mfp{} provides the ability to apply \MF{} affine
4628 transforms.
4629
4630
4631 \subsection{Transforming the \MF{} coordinate system}\label{affine}
4632
4633 \begin{cd}\pagelabel{coords}
4634 \cs{coords} \dots \cs{endcoords}%
4635 \index{coords@\cs{coords}}%
4636 \index{endcoords@\cs{endcoords}}
4637 \end{cd}
4638
4639 All affine transforms are restricted to the innermost enclosing
4640 \cs{coords}$\ldots$\cs{endcoords} pair. If there is \emph{no} such
4641 enclosure, then the transforms will apply to the rest of the \env{mfpic}
4642 environment. In \LaTeX{}, one can use the environment named
4643 \env{coords}.
4644
4645 \medskip
4646 \noindent Transforms provided by \mfp{}:
4647
4648 \nobreak
4649 \begin{cd}\pagelabel{applyT}%
4650 \begin{tabular}[b]{@{}ll@{}}
4651 \cs{rotate}\marg{\meta{$\theta$}}%
4652 \index{rotate@\cs{rotate}}%
4653 & Rotate around origin by \meta{$\theta$} degrees.\\
4654 \cs{rotatearound}\marg{\meta{$p$}}\marg{\meta{$\theta$}}%
4655 \index{rotatearound@\cs{rotatearound}}%
4656 & Rotate around point \meta{$p$} by \meta{$\theta$} degrees.\\
4657 \cs{turn}\oarg{\meta{p}}\marg{\meta{$\theta$}}%
4658 \index{turn@\cs{turn}}%
4659 & Rotate around point \meta{p} (origin is default) by
4660 \meta{$\theta$}.\\
4661 \cs{reflectabout}\marg{\meta{$p_1$}}\marg{\meta{$p_1$}}%
4662 \index{reflectabout@\cs{reflectabout}}%
4663 & Reflect in the line through points \meta{$p_1$} and \meta{$p_2$}.\\
4664 \cs{mirror}\marg{\meta{$p_1$}}\marg{\meta{$p_2$}}%
4665 \index{mirror@\cs{mirror}}%
4666 & Same as \cs{reflectabout}.\\
4667 \cs{shift}\marg{\meta{v}}%
4668 \index{shift@\cs{shift}}%
4669 & Shift origin by the vector \meta{v}.\\
4670 \cs{scale}\marg{\meta{s}}%
4671 \index{scale@\cs{scale}}%
4672 & Scale uniformly by a factor of \meta{s}.\\
4673 \cs{xscale}\marg{\meta{s}}%
4674 \index{xscale@\cs{xscale}}%
4675 & Scale only the $x$ coordinates by a factor of \meta{s}.\\
4676 \cs{yscale}\marg{\meta{s}}%
4677 \index{yscale@\cs{yscale}}%
4678 & Scale only the $y$ coordinates by a factor of \meta{s}.\\
4679 \cs{zscale}\marg{\meta{pair}}%
4680 \index{zscale@\cs{zscale}}%
4681 & Scale by the length of vector \meta{v}, and rotate by its
4682 angle.\\
4683 \cs{xslant}\marg{\meta{s}}%
4684 \index{xslant@\cs{xslant}}%
4685 & Skew in $x$ direction by the multiple \meta{s} of $y$.\\
4686 \cs{yslant}\marg{\meta{s}}%
4687 \index{yslant@\cs{yslant}}%
4688 & Skew in $y$ direction by the multiple \meta{s} of $x$.\\
4689 \cs{zslant}\marg{\meta{pair}}%
4690 \index{zslant@\cs{zslant}}%
4691 & See \mfc{zslanted} in \file{grafbase.dtx}.\\
4692 \cs{boost}\marg{\meta{$\chi$}}%
4693 \index{boost@\cs{boost}}%
4694 & Special relativity boost by $\chi$, see \mfc{boost} in
4695 \file{grafbase.dtx}.\\
4696 \cs{xyswap}%
4697 \index{xyswap@\cs{xyswap}}%
4698 & Exchange the values of $x$ and $y$.\\
4699 \cs{applyT}\marg{\meta{transformer}}%
4700 \index{applyT@\cs{applyT}}%
4701 & Apply the \meta{transformer}.
4702 \end{tabular}
4703 \end{cd}
4704
4705 \cs{applyT} is for \MF{} hackers. Any code is permitted that satisfies
4706 \MF{}'s syntax for a \meta{transformer} (see D.~E.~Knuth, ``The
4707 \MF{}book'', page~73), although no effort is made to correctly write
4708 \TeX{} special characters nor to preserve linebreaks in the code.
4709
4710 When any of these commands is issued, the effect is to transform all
4711 subsequent figures (within the enclosing \env{coords} or \env{mfpic}
4712 environment). In particular, attention may need to be paid to whether
4713 these transformations move (part of) the figure outside the space
4714 allotted by the \cs{mfpic} command parameters.
4715
4716 A not-so-obvious point is that if several of these transformations are
4717 applied in succession, then the most recent is applied first, so that
4718 figures are transformed as if the transformations were applied in the
4719 reverse order of their occurrence. This is similar to the application of
4720 prefix macros (as well as application of transformations in mathematics:
4721 $S T z$ usually means to apply $S$ to the result of $T z$).
4722
4723 Finally, some of these may not produce what the unwary user might expect
4724 if the \env{mfpic} environment was started with unequal scaling. For
4725 example, in such a case a rotated rectangle will not have right angles
4726 unless the rotation is by a multiple of 90 degrees. The reason for this:
4727 the scaling given by the \cs{mfpic} command is applied last and
4728 slanted lines subjected to unequal horizontal and verical scaling will
4729 change have their angles changed.
4730
4731
4732 \subsection{Transforming paths}\label{transformation}
4733
4734 In the previous section we discussed transformations of the \MF{}
4735 coordinate system. Those macros affect the \emph{drawing} of paths and
4736 other figures, but do not change the actual paths. We will explain the
4737 distinction after introducing two macros for storing and reusing
4738 figures.
4739
4740 \begin{cd}\pagelabel{store}
4741 \cs{store}\marg{\meta{path variable}}\marg{\meta{path}}\\
4742 \cs{store}\marg{\meta{path variable}}\meta{path}%
4743 \index{store@\cs{store}}
4744 \end{cd}
4745
4746 This stores the following \meta{path} in the specified \MF{} \meta{path
4747 variable}. Any valid \MF{} symbolic token will do, in particular, any
4748 sequence of letters and underscores. You should be careful to make the
4749 name distinctive to avoid overwriting the definition of some internal
4750 variable. The stored path may later be used as a figure macro
4751 using \cs{mfobj} (below). The \meta{path} may be any of the figure
4752 macros (such as \cs{curve}\marg{(0,0),(1,0),(1,1)}) or the result of
4753 modifying it. For example:
4754 \begin{verbatim}
4755 \store{pth}\lclosed\reverse\curve{(0,0),(1,0),(1,1)}
4756 \end{verbatim}
4757
4758 In fact, \cs{store} is a prefix macro that does nothing to the following
4759 curve except store it. It acts as a rendering macro with a null
4760 rendering, so the curve is not made visible unless other rendering
4761 macros appear before or after it. It allows the following path to be an
4762 argument, that is, enclosed in braces. This is solely to support files
4763 written for past \mfp{} versions in which \cs{store} was \emph{not}
4764 defined as a prefix macro.
4765
4766 One use of \cs{store} is to create a shorthand for a path that is
4767 otherwise long and tedious to type. Another is to create `symbols' or
4768 `arrowheads' for use in \cs{plotsymbol}, \cs{arrowhead} and related
4769 commands.
4770
4771 \begin{cd}\pagelabel{mfobj}
4772 \cs{mfobj}\marg{\meta{path expression}}\\
4773 \cs{mpobj}\marg{\meta{path expression}}%
4774 \index{mfobj@\cs{mfobj}}%
4775 \index{mpobj@\cs{mpobj}}
4776 \end{cd}
4777
4778 This figure macro produces the path represented by \meta{path
4779 expression}, which is either a path variable in which a path was
4780 previously stored, or a valid \MF{} expression combining such variables
4781 and constant paths. This allows the use of path variables or
4782 expressions as figure macros, permitting all prefix operations, etc..
4783 Here are some examples of the use of \cs{store} and \cs{mfobj}.
4784
4785 \nobreak
4786 \begin{verbatim}
4787 \store{my_f}{\cyclic{...}} % Store a closed curve.
4788 \dotted\mfobj{my_f} % Now draw it dotted,
4789 \hatch\mfobj{my_f} % and hatch its interior
4790 % Create two symbols
4791 % one outline:
4792 \store{MyTriang}{\polyline{(-.5,-.5),(.5,-.5),(0,.5),(-.5,-.5)}
4793 % one solid:
4794 \store{MySolidTriang}\polygon{(-.5,-.5),(.5,-.5),(0,.5)}
4795 % Use them as symbols:
4796 \plotsymbols{MyTriang}{(0,0),(2,2)}
4797 \arrowmid{MySolidTriang}\polyline{(1,1),(0,2)}
4798 \end{verbatim}
4799
4800 \emph{Note}: If a stored path has the same starting point as ending
4801 point, but is \emph{not} closed then it will behave like \texttt{Circle}
4802 (for example) when used in \cs{plotsymbol}: only its outline is drawn,
4803 and its interior is erased when \opt{clearsymbols} is in effect. If a
4804 closed path is stored, it behaves like \texttt{SolidCircle}: it is not
4805 drawn, but rather filled. If a path is stored that satisfies neither, it
4806 behaves like \texttt{Asterisk}, being simply drawn in all circumstances.
4807
4808 The two forms \cs{mfobj} and \cs{mpobj} are absolutely equivalent; they
4809 differ only in spelling.
4810
4811 It should be noted that every \mfp{} figure is implicitly stored in the
4812 object \gbc{curpath}. So you can use \cs{mfobj}\marg{curpath} and get
4813 the path defined by the most recently completed figure macro (possibly
4814 modified by prefixes).
4815
4816 Getting back to coordinate transforms, if one changes the coordinate
4817 system and then stores and draws a curve, say by
4818 \begin{verbatim}
4819 \coords
4820 \rotate{45 deg}
4821 \store{xx}{\rect{(0,0),(1,1)}}
4822 \dashed\mfobj{xx}
4823 \endcoords
4824 \end{verbatim}
4825 one will get a transformed picture, but the object \cs{mfobj}\marg{xx}
4826 will contain the simple, unrotated rectangular path and drawing it later
4827 (outside the \env{coords} environment) will prove that. This is because
4828 the \texttt{coords} environment works at the drawing level, not at the
4829 definition level.
4830
4831 In oversimplified terms, \cs{dashed} invokes the transformation, but not
4832 \cs{store}. More precisely, the rendering macros have the side effect of
4833 adding ink to the page (or subtracting it). To know where to place this
4834 ink, a calculation is performed that translates graph coordinates to
4835 actual positions. The above transforms work by modify the parameters
4836 used in that calculation. On the other hand, \cs{store} merely stores
4837 the output of the immediately following prefix or figure macro. See the
4838 beginning of section~\ref{modifier} for a discussion of input, output
4839 and side effects of \mfp{} prefix and figure macros.
4840
4841 The following transformation prefixes provide a means of actually
4842 creating and storing a transformed path. In the terms just discussed,
4843 their input is a path, their output is the transformed path, and they
4844 have no side effects.
4845
4846 \begin{cd}\pagelabel{shiftpath}
4847 \cs{rotatepath}\marg{\meta{$p$},\meta{$\theta$}}$\ldots$\\
4848 \cs{shiftpath}\marg{\meta{v}}$\ldots$\\
4849 \cs{scalepath}\marg{\meta{$p$},\meta{s}}$\ldots$\\
4850 \cs{xscalepath}\marg{\meta{x},\meta{s}}$\ldots$\\
4851 \cs{yscalepath}\marg{\meta{y},\meta{s}}$\ldots$\\
4852 \cs{slantpath}\marg{\meta{y},\meta{s}}$\ldots$\\
4853 \cs{xslantpath}\marg{\meta{y},\meta{s}}$\ldots$\\
4854 \cs{yslantpath}\marg{\meta{x},\meta{s}}$\ldots$\\
4855 \cs{reflectpath}\marg{\meta{$p_1$},\meta{$p_2$}}$\ldots$\\
4856 \cs{xyswappath}$\ldots$\\
4857 \cs{transformpath}\marg{\meta{transformer}}$\ldots$%
4858 \index{rotatepath@\cs{rotatepath}}%
4859 \index{shiftpath@\cs{shiftpath}}%
4860 \index{scalepath@\cs{scalepath}}%
4861 \index{xscalepath@\cs{xscalepath}}%
4862 \index{yscalepath@\cs{yscalepath}}%
4863 \index{slantpath@\cs{slantpath}}%
4864 \index{xslantpath@\cs{xslantpath}}%
4865 \index{yslantpath@\cs{yslantpath}}%
4866 \index{reflectpath@\cs{reflectpath}}%
4867 \index{xyswappath@\cs{xyswappath}}%
4868 \index{transformpath@\cs{transformpath}}
4869 \end{cd}
4870
4871 These are modifying macros that all return the result of applying an
4872 affine transformation to the following path. They differ in the
4873 transformation applied and the data needed in the mandatory argument. I
4874 have found them extremely useful, and better than \env{coords}
4875 environments when I need to draw a figure, together with several
4876 slightly different versions of it. If \cs{store} is used just before one
4877 of these prefixes, it stores the transformed path rather than the
4878 original.
4879
4880 \cs{rotatepath} rotates the following path by \meta{$\theta$} degrees
4881 about point \meta{$p$}.
4882
4883 \cs{shiftpath} shifts the following path by the vector \meta{v}.
4884
4885 \cs{scalepath} scales (magnifies or shrinks) the following path by the
4886 factor \meta{s}, in such a way that the point \meta{$p$} is kept fixed.
4887 That is
4888 \begin{verbatim}
4889 \scalepath{(0,0),2}\rect{(0,0),(1,1)}
4890 \end{verbatim}
4891 is essentially the same as \cs{rect}\marg{(0,0),(2,2)}, while
4892 \begin{verbatim}
4893 \scalepath{(1,1),2}\rect{(0,0),(1,1)}
4894 \end{verbatim}
4895 is the same as \cs{rect}\marg{(-1,-1),(1,1)}. In both cases the
4896 rectangle is doubled in size. In the first case the lower left corner
4897 stays the same, while in the second case the the upper right corner
4898 stays the same.
4899
4900 \cs{xscalepath} is similar to \cs{scalepath}, but only the $x$-direction
4901 is scaled, and all points with first coordinate equal to \meta{x} remain
4902 fixed. \cs{yscalepath} is similar, except the $y$-direction is affected.
4903
4904 \cs{slantpath} applies a slant transformation to the following path,
4905 keeping points with second coordinate equal to \meta{y} fixed. That is,
4906 a point $p$ on the path is moved right by an amount proportional to the
4907 height of $p$ above the line $y={}$\meta{y}, with $s$ being the
4908 proportionality factor. Points below that line move left. Vertical lines
4909 in the path will acquire a slope of $1/s$, while horizontal lines stay
4910 horizontal.
4911
4912 \cs{xslantpath} is an alias for \cs{slantpath}
4913
4914 \cs{yslantpath} is similar to \cs{xslantpath}, but exchanges the roles
4915 of $x$ and $y$ coordinates.
4916
4917 \cs{reflectpath} returns the mirror image of the following path, where
4918 the line determined by the points \meta{$p_1$} and \meta{$p_2$} is the
4919 mirror.
4920
4921 \cs{xyswappath} returns the path with the roles of $x$ and $y$
4922 exchanged. This is similar in some respects to
4923 \cs{reflectpath}\marg{(0,0),(1,1)}, and produces the same result if the
4924 $x$ and $y$ scales of the picture are the same. However,
4925 \cs{reflectpath} compensates for such different scales (so the path
4926 shape remains the same), while \cs{xyswappath} does not. However, after
4927 a swap, verticals become horizontal and horizontals become vertical.
4928 (It is impossible, when the scales are different, for an affine transform
4929 to both preserve shape and exchange horizontal and vertical lines.)
4930
4931 This compensation for different scales is also done for \cs{rotatepath},
4932 so the resulting path always has the same shape after the rotation as
4933 before. None of the other path transformation prefixes compensate for
4934 different scales, and none of the coordinate system transformations of
4935 the previous subsection do it.
4936
4937 For \MF{} or \MP{} power users, \cs{transformpath} can take any
4938 `transformer' and transform the following path with it. Here, a
4939 \emph{transformer} is the same as in the previous section. Examples are
4940 \mfc{scaled}, \mfc{shifted(1,1)}, and \mfc{rotatedabout(0,1)}. Note that
4941 using this last transformer with \cs{transformpath} is almost like
4942 \cs{rotatepath}\marg{(0,1)}, but it does not compensate for different
4943 scales.
4944
4945 All these prefixes change only the path that follows, not any rendering
4946 of it that follows. For example:
4947 \begin{verbatim}
4948 \gfill\rotatepath{(0,0),90}\dashed\rect{(0,0),(1,1)}
4949 \end{verbatim}
4950 will not produce a rotated dashed rectangle. Rather the original
4951 rectangle will be dashed, and the rotated rectangle will be filled.
4952
4953 One complication is the handling of the default rendering. One expects
4954 \begin{verbatim}
4955 \rect{(0,0),(1,1)}
4956 \end{verbatim}
4957 to draw a rectangle, and
4958 \begin{verbatim}
4959 \rotatepath{(0,0),45}\rect{(0,0),(1,1)}
4960 \end{verbatim}
4961 to draw a rotated rectangle (but not the original). That is, a
4962 transformation + figure is treated as if it were a single figure. But
4963 what would one expect in the following?
4964 \begin{verbatim}
4965 \rotatepath{(0,0),45}\dashed\rect{(0,0),(1,1)}
4966 \end{verbatim}
4967 What one will get is the original dashed and the rotated one with the
4968 default rendering (typically drawn with solid lines). That is, these
4969 prefixes cannot see the renderings that occur later in the sequence.
4970 They add the default rendering as if those didn't exist. If something
4971 other than this is desired, one can either rearrange the prefixes or add
4972 a \phantomsection\label{norenderexample}\cs{norender} in appropriate
4973 places. For example, to add a shifted arrowhead without drawing the
4974 shifted path:
4975 \begin{verbatim}
4976 \arrow\norender\shiftpath{(0,1)}\arrow\draw\lines{(0,0),(8,8)}
4977 \end{verbatim}
4978
4979
4980 \section{Parameters.}\label{parameters}
4981
4982 There are many parameters in \mfp{} which the user can modify to
4983 obtain different effects, such as different arrowhead size or shape.
4984 Most of these parameters have been described already in the context of
4985 macros they modify, but they are all described together here.
4986
4987 Many of the parameters are stored by \TeX{} as dimensions, and so are
4988 available even if there is no \MF{} file open; changes to them are not
4989 subject to the usual \TeX{} rules of scope however: they are local
4990 only to \env{mfpic} environments if set inside one, otherwise
4991 they are global. This is for consistency: other parameters are stored by
4992 \MF{} (so the macros to change them will have no effect unless a \MF{}
4993 file is open) and the changes are subject to \MF{}'s rules of scope---to
4994 the \mfp{} user, this means that changes inside the \cs{mfpic} $\ldots$
4995 \cs{endmfpic} environment are local to that environment, but other
4996 \TeX{} groupings have no effect on scope. Some commands (notably those
4997 that set the axismargins and \cs{tlabel} parameters) change both \TeX{}
4998 parameters and \MF{} parameters, and it is important to keep them
4999 consistent.
5000
5001 There are a few parameters that do obey \TeX{} grouping, but only inside
5002 \env{mfpic} environments. These are noted where the parameter is
5003 described.
5004
5005 All parameters are initialized when \prog{mfpic} is loaded. We give the
5006 initial value or state in each of these descriptions.
5007
5008 \begin{cd}\pagelabel{mfpicunit}
5009 \cs{mfpicunit}%
5010 \index{mfpicunit@\cs{mfpicunit}}
5011 \end{cd}
5012
5013 This dimension stores the basic unit length for \mfp{} pictures. The $x$
5014 and $y$ scales in the \cs{mfpic} macro are multiples of this unit. The
5015 initial value is \dim{1pt}. It is global outside an \env{mfpic}
5016 environment. Changes made to it inside an \env{mfpic} environment have
5017 no effect and are lost at the end of the environment.
5018
5019 \begin{cd}\pagelabel{pointsize}
5020 \cs{pointsize}%
5021 \index{pointsize@\cs{pointsize}}
5022 \end{cd}
5023
5024 This dimension stores the diameter of the circle drawn by the
5025 \cs{point} macro and the diameter of the symbols drawn by \cs{plot},
5026 \cs{plotsymbol} and \cs{plotnodes}. The initial value is \dim{2pt}.
5027
5028 \begin{cd}\pagelabel{pointfilltrue}
5029 \cs{pointfilltrue}, \cs{pointfillfalse}%
5030 \index{pointfilltrue@\cs{pointfilltrue}}%
5031 \index{pointfillfalse@\cs{pointfillfalse}}
5032 \end{cd}
5033
5034 This \TeX{} boolean switch determines whether the circle drawn by
5035 \cs{point} will be filled or open (outline drawn, inside erased).
5036 The initial state is \texttt{true}: filled. This value is local to any \TeX{}
5037 group inside an \env{mfpic} environment. Outside such it is global.
5038
5039 \begin{cd}\pagelabel{drawpen}
5040 \cs{pen}\marg{\meta{size}}\\
5041 \cs{drawpen}\marg{\meta{size}}\\
5042 \cs{penwd}\marg{\meta{size}}%
5043 \index{pen@\cs{pen}}%
5044 \index{drawpen@\cs{drawpen}}%
5045 \index{penwd@\cs{penwd}}
5046 \end{cd}
5047
5048 These commands establishes the width of the normal drawing pen (that is,
5049 the thickness of lines, whether solid or dashed). The initial value is
5050 \dim{0.5bp}. This width is stored by \MF{}. This has no effect on the
5051 size of dots for \cs{dotted}, \cs{shade}, \cs{grid}, etc. It also has no
5052 effect on the lines drawn for hatching. There exist three aliases for
5053 this command, the first two to maintain backward compatibility, the last
5054 one for consistency with other dimension changing commands. Publishers
5055 generally recommended authors to use at least a width of one-half point
5056 for drawings submitted for publication.
5057
5058 \begin{cd}\pagelabel{shadewd}
5059 \cs{shadewd}\marg{\meta{diam}}%
5060 \index{shadewd@\cs{shadewd}}
5061 \end{cd}
5062
5063 This command sets the diameter of the dots used in the shading macro.
5064 The drawing and hatching pens are unaffected by this. The initial value
5065 is \dim{0.5bp}, and the value is stored by \MF{}.
5066
5067 \begin{cd}\pagelabel{hatchwd}
5068 \cs{hatchwd}\marg{\meta{size}}%
5069 \index{hatchwd@\cs{hatchwd}}
5070 \end{cd}
5071
5072 This sets the line thickness used in the hatching macros. The drawing
5073 pen and shading dots are unaffected by this. The initial value is
5074 \dim{0.5bp}, and the value is stored by \MF{}.
5075
5076 \begin{cd}\pagelabel{polkadotwd}
5077 \cs{polkadotwd}\marg{\meta{diam}}%
5078 \index{polkadotwd@\cs{polkadotwd}}
5079 \end{cd}
5080
5081 This sets the diameter of the dots used in the \cs{polkadot} macro. The
5082 initial value is \dim{5bp}, and the value is stored by \MF{}.
5083
5084 \begin{cd}\pagelabel{headlen}
5085 \cs{headlen}%
5086 \index{headlen@\cs{headlen}}
5087 \end{cd}
5088
5089 This dimension stores the length of the arrowhead drawn by the
5090 \cs{arrow} macro. The initial value is \dim{3pt}.
5091
5092 \begin{cd}\pagelabel{axisheadlen}
5093 \cs{axisheadlen}%
5094 \index{axisheadlen@\cs{axisheadlen}}
5095 \end{cd}
5096
5097 This dimension stores the length of the arrowhead drawn by the
5098 \cs{axes}, \cs{xaxis} and \cs{yaxis} macros, and by the macros \cs{axis}
5099 and \cs{doaxes} when applied to the parameters \texttt{x} and
5100 \texttt{y}. The initial value is \dim{5pt}.
5101
5102 \begin{cd}\pagelabel{sideheadlen}
5103 \cs{sideheadlen}%
5104 \index{sideheadlen@\cs{sideheadlen}}
5105 \end{cd}
5106
5107 This dimension stores the length of the arrowhead drawn by the \cs{axis}
5108 and \cs{doaxes} macros when applied to \texttt{l}, \texttt{b},
5109 \texttt{r} or \texttt{t}. The initial value is \dim{0pt} (that is, the
5110 default is not to put arrowheads on border axes).
5111
5112 \begin{cd}\pagelabel{headshape}
5113 \cs{headshape}\marg{\meta{ratio}}\marg{\meta{tension}}\marg{\meta{filled}}%
5114 \index{headshape@\cs{headshape}}
5115 \end{cd}
5116
5117 This establishes the shape of the \gbc{Arrowhead} drawn by the
5118 \cs{arrow...} and \cs{axes} macros. It also establishes the shape of
5119 \gbc{Leftharpoon} and \gbc{Rightharpoon}. The value of \meta{ratio} is
5120 the ratio of the width of the arrowhead to its length; \meta{tension} is
5121 the tension of the B\'ezier curves; and \meta{filled} is a \MF{} boolean
5122 value indicating whether the arrowheads are to be filled (if \mfc{true})
5123 or open. The initial values are $1$, $1$, and \mfc{false}, respectively.
5124 Setting \meta{tension} to the literal keyword `\mfc{infinity}' will make
5125 the sides of the arrowheads straight lines. The harpoon heads are
5126 arranged to be exactly half of the full arrowhead. The \meta{ratio},
5127 \meta{tension} and \meta{filled} values are stored by \MF{}.
5128
5129 After \cs{headshape} is used, the symbols \gbc{Arrowhead},
5130 \gbc{Leftharpoon}, and \gbc{Rightharpoon} take on the new shape if used
5131 in one of the \cs{plot...} commands.
5132
5133 \begin{cd}\pagelabel{dashlen}
5134 \cs{dashlen}, \cs{dashspace}%
5135 \index{dashlen@\cs{dashlen}}
5136 \end{cd}
5137
5138 These dimensions store, respectively, the length of dashes and the
5139 length of spaces between dashes, for lines drawn by the \cs{dashed}
5140 macro. The \cs{dashed} macro may adjust the dashes and the spaces
5141 between by as much as $1/n$ of their value, where $n$ is the number of
5142 spaces appearing in the curve, in order not to have partial dashes at
5143 the ends. The initial values are both \dim{4pt}. The dashes will
5144 actually be longer (and the spaces shorter) by the thickness of the pen
5145 used when they are drawn.
5146
5147 \begin{cd}\pagelabel{dashlineset}
5148 \cs{dashlineset}, \cs{dotlineset}%
5149 \index{dashlineset@\cs{dashlineset}}%
5150 \index{dotlineset@\cs{dotlineset}}
5151 \end{cd}
5152
5153 These macros provide shorthands for certain settings of the \cs{dashlen}
5154 and \cs{dashspace} dimensions. The macro \cs{dashlineset} sets both
5155 values to \dim{4pt}, while \cs{dotlineset} sets \cs{dashlen} to
5156 \dim{1pt} and \cs{dashspace} to \dim{2pt}. They are kept mainly for
5157 backward compatibility.
5158
5159 \begin{cd}\pagelabel{hashlen}
5160 \cs{hashlen}%
5161 \index{hashlen@\cs{hashlen}}
5162 \end{cd}
5163
5164 This dimension stores the length of the axis hash marks drawn by the
5165 \cs{xmarks} and \cs{ymarks} macros. The initial value is \dim{4pt}.
5166
5167 \begin{cd}\pagelabel{shadespace}
5168 \cs{shadespace}%
5169 \index{shadespace@\cs{shadespace}}
5170 \end{cd}
5171
5172 This dimension establishes the spacing between dots drawn by the
5173 \cs{shade} macro. The initial value is \dim{1pt}.
5174
5175 \begin{cd}\pagelabel{darkershade}
5176 \cs{darkershade}, \cs{lightershade}%
5177 \index{darkershade@\cs{darkershade}}%
5178 \index{lightershade@\cs{lightershade}}
5179 \end{cd}
5180
5181 These macros both multiply the \cs{shadespace} dimension by constant
5182 factors, $5/6=.833333$ and $6/5=1.2$ respectively, to provide convenient
5183 standard settings for several levels of shading. Under \MF{} it is
5184 possible that using one of these macros can have no visible effect. See
5185 the discussion of the \cs{shade} macro in subsection~\ref{filling}.
5186
5187 \begin{cd}\pagelabel{polkadotspace}
5188 \cs{polkadotspace}%
5189 \index{polkadotspace@\cs{polkadotspace}}
5190 \end{cd}
5191
5192 This dimension establishes the spacing between the centers of the dots
5193 used for the macro \cs{polkadot}. The initial value is \dim{10pt}.
5194
5195 \begin{cd}\pagelabel{dotsize}
5196 \cs{dotsize}, \cs{dotspace}%
5197 \index{dotsize@\cs{dotsize}}\index{dotspace@\cs{dotspace}}%
5198 \end{cd}
5199
5200 These \TeX{} dimensions establishes the size and spacing between the
5201 centers of the dots used in the \cs{dotted} macro. The initial values
5202 are \dim{0.5pt} and \dim{3pt}.
5203
5204 \begin{cd}\pagelabel{griddotsize}
5205 \cs{griddotsize}%
5206 \index{griddotsize@\cs{griddotsize}}%
5207 \end{cd}
5208
5209 This dimension gives the default sizes of dots in the \cs{grid} and
5210 \cs{plrgridpoints} commands. The initial value is \dim{0.5pt}
5211
5212 \begin{cd}\pagelabel{symbolspace}
5213 \cs{symbolspace}%
5214 \index{symbolspace@\cs{symbolspace}}
5215 \end{cd}
5216
5217 Similar to \cs{dotspace}, this \TeX{} dimension establishes the space
5218 between the centers of symbols placed by the macro
5219 \cs{plot}\marg{\meta{symbol}}$\ldots\,$. Its initial value is \dim{5pt}.
5220
5221 \begin{cd}\pagelabel{hatchspace}
5222 \cs{hatchspace}%
5223 \index{hatchspace@\cs{hatchspace}}
5224 \end{cd}
5225
5226 This dimension establishes the spacing between lines drawn by the
5227 \cs{hatch} macro. The initial value is \dim{3pt}.
5228
5229 \begin{cd}
5230 \cs{tlpointsep}\marg{\meta{separation}}\\
5231 \cs{tlpathsep}\marg{\meta{separation}}\\
5232 \cs{tlabelsep}\marg{\meta{separation}}%
5233 \index{tlpointsep@\cs{tlpointsep}}%
5234 \index{tlpathsep@\cs{tlpathsep}}%
5235 \index{tlabelsep@\cs{tlabelsep}}
5236 \end{cd}
5237
5238 The first macro establishes the separation between a label and its
5239 nominal position. It affects text written with any of the commands
5240 \cs{tlabel}, \cs{tlabels}, \cs{axislabels} or \cs{plottext}. The second
5241 sets the separation between the text and the curve defined by the
5242 commands \cs{tlabelrect}, \cs{tlabeloval} or \cs{tlabelellipse}. The
5243 third sets both of these separations to the same value. It is for
5244 backward compatibility: in the past there was only one dimension used
5245 for both purposes. The initial value of each is \dim{0pt}. The values
5246 are stored by both \TeX{} and \MF{}.
5247
5248 \begin{cd}
5249 \cs{tlabeloffset}\marg{\meta{hlen}}\marg{\meta{vlen}}%
5250 \index{tlabeloffset@\cs{tlabeloffset}}
5251 \end{cd}
5252
5253 This macro establishes a uniform offset that applies to all labels. It
5254 affects text written with any of the commands \cs{tlabel}, \cs{tlabels},
5255 \cs{axislabels} or \cs{plottext}. The initial state is to have both
5256 horizontal and vertical offsets of \dim{0pt}. The values are stored by
5257 both \TeX{} and \MF{}.
5258
5259 \begin{cd}\pagelabel{mfpdataperline}
5260 \cs{mfpdataperline}%
5261 \index{mfpdataperline@\cs{mfpdataperline}}
5262 \end{cd}
5263
5264 When \mfp{} is reading from data files and writing to the output file,
5265 this macro stores the maximum number of data points that will be written
5266 on a single line in the output file. Its initial definition is
5267 \cs{def}\cs{mfpdataperline}\marg{5}. Any such definition (or
5268 redefinition) obeys \emph{all} \TeX{} groupings.
5269
5270 \begin{cd}\pagelabel{mfpicheight}
5271 \cs{mfpicheight}, \cs{mfpicwidth}%
5272 \index{mfpicheight@\cs{mfpicheight}}%
5273 \index{mfpicwidth@\cs{mfpicwidth}}
5274 \end{cd}
5275
5276 These dimensions store the height and width of the figure created by the
5277 most recently completed \env{mfpic} environment. This might perhaps be
5278 of interest to hackers or to aid in precise positioning of the graphics.
5279 They are meant to be read-only: the \cs{endmfpic} command globally sets
5280 them equal to the height and width of the picture, but \mfp{} does not
5281 otherwise make any use of them. As they are not to be changed, grouping
5282 is irrelevent, but when \mfp{} sets them, it does so globally. These are
5283 set even if the picture is saved with \cs{savepic}. If they are needed
5284 for the corresponding \cs{usepic}, and that occurs after another
5285 \env{mfpic} environment, they should be copied to other length commands
5286 right after the \env{mfpic} environment that set them.
5287
5288 \begin{cd}\pagelabel{mfpiccaptionskip}
5289 \cs{mfpiccaptionskip}%
5290 \index{mfpiccaptionskip@\cs{mfpiccaptionskip}}
5291 \end{cd}
5292
5293 This skip register (`rubber length' in \LaTeX) stores the space between
5294 a picture and the caption produced with \cs{tcaption}. It is local to
5295 all \TeX{} groups. If changed inside an \env{mfpic} environment it will
5296 affect only the \cs{tcaption} command in that picture. It's initial
5297 setting is \cs{medskipamount}, producing the same space as a
5298 \cs{medskip}.
5299
5300
5301 \section{For Advanced Users.}\label{advanced}
5302
5303 \subsection{Splines}\label{splines}
5304
5305 \begin{cd}\pagelabel{qspline}
5306 \cs{qspline}\marg{\meta{list}}\\
5307 \cs{closedqspline}\marg{\meta{list}}\\
5308 \cs{cspline}\marg{\meta{list}}\\
5309 \cs{closedcspline}\marg{\meta{list}}%
5310 \index{qspline@\cs{qspline}}%
5311 \index{closedqspline@\cs{closedqspline}}%
5312 \index{cspline@\cs{cspline}}%
5313 \index{closedcspline@\cs{closedcspline}}%
5314 \end{cd}
5315
5316 These figure macros use alternative ways of defining curves. In each case,
5317 \meta{list} is a comma separated list of ordered pairs. These represent
5318 not the points the curve passes through, but the \emph{control points}.
5319 The first two produce quadratic B-splines and the last two produce cubic
5320 B-splines. If you don't know what B-splines are, or don't know what
5321 control points are, it is recommended you not use these commands.
5322
5323 For \cs{qspline}, the curve will pass through the midpoints of the line
5324 segments joining the points in the list, tangent to that line segment.
5325
5326 For the \cs{cspline}, the list also defines line segments. Divide these
5327 into equal thirds at two points on each segment. Connect these
5328 \emph{division points only} to obtain line segments. Each \emph{odd
5329 numbered} segment is the middle third of one of the original line
5330 segments. The \cs{cspline} curve passes through the midpoint of each
5331 \emph{even numbered} line segment, tangent to it.
5332
5333 \begin{cd}\pagelabel{computedspline}
5334 \cs{computedspline}\marg{\meta{list}}\\
5335 \cs{closedcomputedspline}\marg{\meta{list}}%
5336 \index{computedspline@\cs{computedspline}}%
5337 \index{closedcomputedspline@\cs{closedcomputedspline}}%
5338 \end{cd}
5339
5340 These figure macros both produce cubic splines. For these you \emph{do}
5341 provide the list of points the curves are to pass through. They become
5342 the nodes, and then the control points are computed from them. The nodes
5343 do not uniquely determine the control points so extra equations are
5344 required. For the first version, the extra equations give the path zero
5345 curvature at the endpoints (a \emph{relaxed} spline). For the closed
5346 version, the extra equations are those that close the curve smoothly.
5347 The portions of the spline that connect one node to the next are
5348 parametrized cubic B\'eziers, they are computed so that the first and
5349 second derivatives (with respect to the parameter) of adjacent curves
5350 match at the common node.
5351
5352 \begin{cd}\pagelabel{fcnspline}
5353 \cs{fcnspline}\marg{\meta{list}}\\
5354 \cs{periodicfcnspline}\marg{\meta{list}}%
5355 \index{fcnspline@\cs{fcnspline}}%
5356 \index{periodicfcnspline@\cs{periodicfcnspline}}%
5357 \end{cd}
5358
5359 These figure macros use cubic spline equations (as in
5360 \cs{computedspline} above) to produce a smooth graph of a function based
5361 on a list of points with increasing $x$-values. See \cs{fcncurve} in
5362 section~\ref{curves} for another way to do this. As in the computed
5363 splines, above, the spline equations at the nodes do not provide
5364 sufficient information to compute all control points. In the basic
5365 version, \cs{fcnspline}, extra equations produce a graph with zero
5366 curvature at the endpoints (a relaxed spline), while the periodic
5367 version uses equations that make the first and second derivatives at the
5368 last point match those at the first point.
5369
5370 \begin{cd}\pagelabel{cbclosed}
5371 \cs{cbclosed}$\ldots$\\
5372 \cs{qbclosed}$\ldots$%
5373 \index{cbclosed@\cs{cbclosed}}%
5374 \index{qbclosed@\cs{qbclosed}}
5375 \end{cd}
5376
5377 These are modifying macros that close the following path. The first
5378 closes with a cubic B-spline, the second with a quadratic B-spline. They
5379 will close any given curve, but the command \cs{cbclosed} is meant to
5380 close a cubic B-spline (see above). That is, \cs{cbclosed}\cs{cspline}
5381 should produce the same result as \cs{closedcspline} with the same
5382 argument. The corresponding statements are true of \cs{qbclosed}: it is
5383 meant to close a quadratic B-spline and \cs{qbclosed}\cs{qspline} should
5384 produce the same result as \cs{closedqspline} with the same argument.
5385
5386
5387 \subsection{B\'eziers}
5388
5389 The power user, having noticed that \cs{curve} and \cs{cyclic} insert
5390 some direction modifiers into the path created, may have decided that
5391 there is no \mfp{} command to create a simple \MF{} default style path,
5392 for example \mfc{(1,1)..(0,1)..(0,0)..cycle}. If so, he or she has forgotten
5393 about \cs{mfobj}: the command
5394 \begin{verbatim}
5395 \mfobj{(1,1)..(0,1)..(0,0)..cycle}
5396 \end{verbatim}
5397 will produce, in the \file{.mf} file, exactly this path, but surround it
5398 with the \TeX{} wrapping needed to make \mfp{}'s prefix macro system work.
5399 However, the syntax of more complicated paths can be extremely lengthy,
5400 so we offer this interface:
5401
5402 \begin{cd}\pagelabel{mfbezier}
5403 \cs{mfbezier}\oarg{\meta{tens}}\marg{\meta{list}}\\
5404 \cs{closedmfbezier}\oarg{\meta{tens}}\marg{\meta{list}}%
5405 \index{mfbezier@\cs{mfbezier}}%
5406 \index{closedmfbezier@\cs{closedmfbezier}}
5407 \end{cd}
5408
5409 These figure macros uses the \MF{} path join operator `\mfc{..tension
5410 \meta{tens}..}' to connect the points in the list. If the tension option
5411 \oarg{\meta{tens}} is omitted, the value set by \cs{settension}
5412 (initially 1) is used. One can get a cyclic path by prepending
5413 \cs{bclosed} (with matching tension option), but it will not produce the
5414 same result as \cs{closedmfbezier}. These are cubic B\'ezier's (but you
5415 know that if you are a power user). Quadratic B\'eziers (as in
5416 \LaTeX{}'s picture environment) can be obtained with the following:
5417
5418 \begin{cd}\pagelabel{qbeziers}
5419 \cs{qbeziers}\marg{\meta{list}}\\
5420 \cs{closedqbeziers}\marg{\meta{list}}%
5421 \index{qbeziers@\cs{qbeziers}}%
5422 \index{closedqbeziers@\cs{closedqbeziers}}
5423 \end{cd}
5424
5425 These figure macros produce \emph{quadratic} B\'ezier curves, the
5426 equivalent of a sequence of \LaTeX{} \cs{qbezier} commands. Note the
5427 plural forms, to distinguish the first from the \LaTeX{} command, and to
5428 indicate that they can draw a \emph{series} of quadratic B\'eziers.
5429
5430 In the \meta{list}, the first, third, fifth, etc., are the points to
5431 connect, while the second, fourth, etc., are the control points. The
5432 open version requires an ending point, and so needs an odd number of
5433 points in the list. The closed version assumes the first point is the
5434 ending, and so requires an even number in the list. If the number of
5435 ponts is wrong, no error is produced: the last point is simply repeated
5436 to get the required number.
5437
5438 The curve will not automatically be smooth; that depends on the choice
5439 of the control points.
5440
5441 \begin{cd}\pagelabel{cbeziers}
5442 \cs{cbeziers}\marg{\meta{list}}\\
5443 \cs{closedcbeziers}\marg{\meta{list}}%
5444 \index{cbeziers@\cs{cbeziers}}%
5445 \index{closedcbeziers@\cs{closedcbeziers}}
5446 \end{cd}
5447
5448 These figure macros produce a series of \emph{cubic} B\'ezier curves. In
5449 the \meta{list}, the first, fourth, seventh, etc., are the points to
5450 connect, while the second and third, fifth and sixth, etc., are pairs of
5451 control points. The closed version uses the starting point as the ending
5452 point, and so needs a number of points divisible by $3$ ($n=3k$). The
5453 open version requires an explicitly given ending node (so $n=3k+1$).
5454 If the number of ponts is wrong, no error is produced: the last point
5455 or last two points are simply repeated to get the required number.
5456
5457 The curves will not automatically be smooth; that depends on the choice
5458 of the control points. Cubic B\'eziers are how curves are represented in
5459 PostScript files, and how a number of vector drawing programs represent
5460 curves.
5461
5462
5463 \subsection{Raw \MF{} code}\label{mfcode}
5464
5465 \begin{cd}\pagelabel{mfsrc}
5466 \cs{mfsrc}\marg{\meta{metafont code}}\\
5467 \cs{mfcmd}\marg{\meta{metafont code}}\\
5468 \cs{mflist}\marg{\meta{metafont code}}%
5469 \index{mfsrc@\cs{mfsrc}}%
5470 \index{mfcmd@\cs{mfcmd}}%
5471 \index{mflist@\cs{mflist}}%
5472 \end{cd}
5473
5474 These all write the \meta{metafont code} directly to the \MF{} file,
5475 using a \TeX{} \cs{write} command. Line breaks within \meta{metafont
5476 code} are preserved.%
5477 \footnote{Under most circumstances, but not if the command (plus its
5478 argument) is part of the argument of another macro.} %
5479 Almost all the \mfp{} drawing macros invoke one of these. Because of the
5480 way \TeX{} reads and processes macro arguments, not all drawing macros
5481 preserve line breaks (nor do they all need to). However, the ones that
5482 operate on long lists of pair or numeric data (for example, \cs{point},
5483 \cs{curve}, etc.), do preserve line breaks in that data. The difference
5484 in these is minor: \cs{mfsrc} writes its argument without change,
5485 \cs{mfcmd} appends a semicolon (`\mfc{;}') to the code, while
5486 \cs{mflist} surrounds its argument with parentheses and then appends a
5487 semicolon.
5488
5489 Using these can have some rather bizarre consequences, though, so it is
5490 not recommended to the unwary. It is, however, currently the only way to
5491 make use of \MF{}'s equation solving ability. Here's an oversimplified
5492 example:
5493 \begin{verbatim}
5494 \mfpic[20]{-0.5}{1.5}{0}{1.5}
5495 \mfsrc{z1=(0,0);
5496 z2-z3=(1,2);
5497 z2+2z3=(1,-1);} % z2=(1,1), z3=(0,-1)
5498 \arc[t]{z1,z2,z3}
5499 \endmfpic
5500 \end{verbatim}
5501
5502 Check out the sample \file{forfun.tex} for a more extensive example. It
5503 should produce the word `\textsf{mfpic}' in blue, outlined in green in a
5504 box with yellow background.
5505
5506
5507 \subsection{Creating \MF{} variables}\label{variables}
5508
5509 \begin{cd}\pagelabel{setmfvariable}
5510 \cs{setmfvariable}\marg{\meta{type}}\marg{\meta{name}}\marg{\meta{value}}\\
5511 \cs{setmpvariable}\marg{\meta{type}}\marg{\meta{name}}\marg{\meta{value}}\\
5512 \cs{globalsetmfvariable}\marg{\meta{type}}\marg{\meta{name}}\marg{\meta{value}}\\
5513 \cs{globalsetmpvariable}\marg{\meta{type}}\marg{\meta{name}}\marg{\meta{value}}\\
5514 \cs{setmfnumeric}\marg{\meta{name}}\marg{\meta{value}}\\
5515 \cs{setmfpair} \marg{\meta{name}}\marg{\meta{value}}\\
5516 \cs{setmfboolean}\marg{\meta{name}}\marg{\meta{value}}\\
5517 \cs{setmfcolor} \marg{\meta{name}}\marg{\meta{value}}%
5518 \index{setmfvariable@\cs{setmfvariable}}%
5519 \index{setmpvariable@\cs{setmpvariable}}%
5520 \index{globalsetmfvariable@\cs{globalsetmfvariable}}%
5521 \index{globalsetmpvariable@\cs{globalsetmpvariable}}%
5522 \index{setmfnumeric@\cs{setmfnumeric}}%
5523 \index{setmfpair@\cs{setmfpair}}%
5524 \index{setmfboolean@\cs{setmfboolean}}%
5525 \index{setmfcolor@\cs{setmfcolor}}%
5526 \end{cd}
5527
5528 These formerly internal \mfp{} macros can be use to define symbolic
5529 names for any \MF{} or \MP{} variable type. The last four are
5530 abbreviations for the first used with an appropriate value for
5531 \meta{type}. For example,
5532 \cs{setmfvariable}\marg{pair}\marg{X}\marg{(2,0)} can be abbreviated
5533 \cs{setmfpair}\marg{X}\marg{(2,0)}. Note that these overwrite any
5534 variable with the specified \meta{name}. For certain internal names,
5535 \MF{} will issue an error, but usually the variable is silently
5536 redefined.
5537
5538 The commands \cs{setmpvariable} and \cs{globalsetmpvariable} (note the
5539 \texttt{mp} instead of \texttt{mf}) are just alternative spellings . You
5540 can use either spelling with either the \opt{metafont} or \opt{metapost}
5541 option.
5542
5543 The \meta{value} must be a constant of the appropriate type or a \MF{}
5544 expression returning the appropriate type. It can also be (or include)
5545 other variables previously defined. The \cs{setmfcolor} command has been
5546 enhanced so that in recent \MP{} the \meta{value} can be any of the
5547 three types of colors \MP{} allows: \kw{numeric} (for grayscale color),
5548 \kw{rgbcolor} or \kw{cmykcolor}. The data type of \meta{value} will be
5549 examined, and the variable \meta{name} will be declared to be a variable
5550 of the appropriate type. The same is true of
5551 \cs{setmfvariable}\marg{color}.
5552
5553 As an example of their use, since dimensions are numeric data types in
5554 \MF{}, the command
5555 \begin{verbatim}
5556 \setmfnumeric{my_spc}{5pt}
5557 \setmfnumeric{my_dia}{.8pt}
5558 \end{verbatim}
5559 would set the \MF{} variables \verb$my_spc$ and \verb$my_dia$ to the
5560 values \texttt{5pt} and \texttt{.8pt}, respectively. After that, these
5561 variables can be used in any \emph{drawing} command where a dimension is
5562 required:
5563 \begin{verbatim}
5564 \plot[my_dia,my_spc]{Triangle}\rect{(0,0),(1,1)}
5565 \end{verbatim}
5566 will plot the rectangle with small triangles of diameter \dim{.8pt},
5567 spaced \dim{5pt} apart.
5568
5569 The knowledgeable user may realize that \mfc{path} and \gbc{picture} are
5570 \MF{} data types, and may want use them in \cs{setmfvariable}. It is
5571 also true that at some level, \mfp{} figure macros produce a path and
5572 \cs{mfpimage} produces a picture. However, \mfp{} commands cannot be
5573 used in the value portion of \cs{setmfvariable}. The \TeX{} code that
5574 most \mfp{} commands produce would be meaningless to \MF{}. You can
5575 store the path produced by figure macros with \cs{store}, and store
5576 pictures in variables with \cs{mfpimage} or even \cs{tile}.
5577
5578 With the obvious exception of the \cs{globalsetmfvariable} command, these
5579 commands define the variable locally. That is, the variable will revert
5580 to any previous definition (or become undefined) at the end of the
5581 \env{mfpic} environment it is defined in. It is in fact local to any
5582 \MF{} group. In \mfp{}, only \cs{connect} {\dots} \cs{endconnect},
5583 \cs{mfpimage} {\dots} \cs{endmfpimage}, and \cs{mfpic} {\dots}
5584 \cs{endmfpic} create \MF{} groups in the graph file.
5585
5586 A warning about variable names. \CMF{} and \MP{} allow multi-part
5587 variable names like `\mfc{arrowhead length}' or `\mfc{X.r}' The part
5588 after the first space or `.' is called a \mfc{suffix}. In \MF{},
5589 variable settings are global unless explicitly made local. The code of
5590 the \cs{set...} commands does make the variable setting local. However,
5591 \MF{} syntax forbids this localization when a variable name has a
5592 suffix. Moreover, if you localize a variable, \MF{} will localize all
5593 variables with that name plus any suffix. Even more, localizing a
5594 variable renders all variables with the same name plus suffix locally
5595 undefined. The command \cs{globalsetmfvariable} simply omits the
5596 localization part, so suffixes are permitted, but it cannot `globalize'
5597 something that has previously been localized within the same group.
5598
5599 For example, suppose you use the example code in subsection~\ref{arrows}
5600 and define a custom arrowhead path \gbc{myAH} and the corresponding
5601 clearing path \gbc{myAH.clear}. Suppose now you try to make this head
5602 the default for the \cs{arrow} command by doing the following.
5603 \begin{verbatim}
5604 \setmfvariable{path}{Arrowhead}{myAH}
5605 \end{verbatim}
5606 Then this assignments is local and makes \gbc{Arrowhead.clear} undefined
5607 (locally). You cannot use \cs{setmfvariable} to define
5608 \gbc{Arrowhead.clear}; that will produce an error from \MF{}. You need
5609 to do
5610 \begin{verbatim}
5611 \setmfvariable{path}{Arrowhead}{myAH}
5612 \globalsetmfvariable{path}{Arrowhead.clear}{myAH.clear}
5613 \end{verbatim}
5614 and \emph{both} assignments will be local. To make both assignments
5615 global, use the global version in both.
5616
5617
5618 \begin{cd}\pagelabel{patharr}
5619 \cs{patharr}\marg{\meta{name}}$\ldots$\cs{endpatharr}%
5620 \index{patharr@\cs{patharr}}%
5621 \index{endpatharr@\cs{endpatharr}}
5622 \end{cd}
5623
5624 This pair of macros, acting as an environment, accumulate all enclosing
5625 paths, in order, into a path array named \meta{name}. A path array is a
5626 collection of paths with a common base name indexed by integers from 1
5627 to the number of paths. Any path in the array can be accessed by means
5628 of \cs{mfobj}. For example, after
5629 \begin{verbatim}
5630 \patharr{pa}
5631 \rect{(0,0),(1,1)} \circle{(.5,.5), .5}
5632 \endpatharr
5633 \end{verbatim}
5634 then \cs{mfobj}\marg{pa[1]} refers to the rectangle and
5635 \cs{mfobj}\marg{pa[2]} refers to the circle. In case explicit numbers
5636 are used, \MF{} allows \gbc{pa1} as an abbreviation for \gbc{pa[1]}.
5637 However, if a numeric variable or some expression is used (e.g.,
5638 \gbc{pa[n+1]}) the square brackets are required.
5639
5640 This command can only be used in an \env{mfpic} environment. For this
5641 reason, the definitions it makes are global.
5642
5643 \emph{Note}: In \LaTeX{}, this pair of macros can be used in the form of a
5644 \LaTeX{}-style environment called \env{patharr}---as in
5645 \cs{begin}\marg{patharr}$\ldots$\cs{end}\marg{patharr}.
5646
5647 \begin{cd}\pagelabel{setarray}
5648 \cs{setarray}\marg{\meta{type}}\marg{\meta{var}}\marg{\meta{list}}\\
5649 \cs{globalsetarray}\marg{\meta{type}}\marg{\meta{var}}\marg{\meta{list}}\\
5650 \cs{pairarray}\marg{\meta{var}}\marg{\meta{list-of-points}}\\
5651 \cs{numericarray}\marg{\meta{var}}\marg{\meta{list-of-numbers}}\\
5652 \cs{colorarray}\marg{\meta{var}}\marg{\meta{list-of-colors}}\\
5653 \cs{rgbcolorarray}\marg{\meta{var}}\marg{\meta{list-of-rgbcolors}}\\
5654 \cs{cmykcolorarray}\marg{\meta{var}}\marg{\meta{list-of-cmykcolors}}%
5655 \index{setarray@\cs{setarray}}%
5656 \index{globalsetarray@\cs{globalsetarray}}%
5657 \index{pairarray@\cs{pairarray}}%
5658 \index{numericarray@\cs{numericarray}}%
5659 \index{colorarray@\cs{colorarray}}%
5660 \index{rgbcolorarray@\cs{rgbcolorarray}}%
5661 \index{cmykcolorarray@\cs{cmykcolorarray}}
5662 \end{cd}
5663
5664 These enable the simultaneous definition of variables.
5665 For example, after
5666 \begin{verbatim}
5667 \pairarray{X}{(0,1),(1,1),(0,0),(1,0)}
5668 \end{verbatim}
5669 the variables \mfc{X1}, \mfc{X2}, \mfc{X3}, and \mfc{X4} are equal to
5670 the given points in that order. And then
5671 \begin{verbatim}
5672 \polyline{X1,X2,X3,X4}
5673 \end{verbatim}
5674 will draw the lines connecting these four points. The index may
5675 optionally be put in square brackets and may be separated from the name
5676 by any number of spaces. That is, \verb$\polyline{X[1],X[2]}$ and
5677 \verb$\polyline{X 1,X 2}$ are the same as \verb$\polyline{X1,X2}$ to
5678 \MF{}. If a numeric \emph{expression} is used instead of an explicit
5679 number, square brackets \emph{must} surround it: \gbc{X[1+1]},
5680 \gbc{X[2]}, \gbc{X2} and \codebox{X 2} are all the same. For all these
5681 array commands, the variable \gbc{X} by itself (not followed by any
5682 digit or brackets) becomes a numeric variable equal to the number of
5683 elements in the array. Except for \cs{globalsetarray}, the arrays are
5684 defined locally if these commands occur in an \env{mfpic} environment,
5685 global otherwise.
5686
5687 Array variables may be used only where the values are processed only by
5688 \MF{} or \MP{}, they are unknown to \TeX{}. In particular, they cannot be
5689 used in commands that position text unless \opt{mplabels} is in effect.
5690 Variables may be used in the \meta{list} parameters of commands,
5691 but they must have been previously defined or otherwise known to \MF{}.
5692
5693 Since arrays must all be variables of the same type, one cannot mix rgb
5694 and cmyk colors. The \verb$\colorarray$ command requires rgb colors (for
5695 compatibility with early \MP{}).
5696
5697 Several commands in \mfp{} define arrays of objects that can be used in
5698 other commands. The main ones are \cs{regpolygon}, \cs{piechart} and
5699 \cs{barchart}. These arrays are always global (either because their
5700 use is restricted to an \env{mfpic} environment or for backward
5701 compatibility with the time when they were so restricted).
5702
5703 Using \cs{regpolygon}\marg{\meta{num}}\marg{X}\marg{...}\marg{...} causes a
5704 pair array named \gbc{X} to be defined having \meta{num} elements (and
5705 the additional pair \gbc{X0} for the center). This is in addition to
5706 creating the actual figure. The variable \gbc{X} alone becomes a numeric
5707 equated to \meta{num}.
5708
5709 Using \cs{piechart} (or \cs{mfppiechart}) causes the following arrays to
5710 become defined (or redefined):
5711 \begin{itemize}
5712 \item \gbc{piewedge}, a path array describing the wedges of the chart.
5713 To access \gbc{piewedge[1]}, for example, one could use
5714 \cs{mfobj}\marg{piewedge[1]}. This is almost exactly the
5715 same as the \mfp{} command \cs{piewdge}\marg{1} without
5716 optional arguments.
5717 \item \gbc{pieangle}, a numeric array, gives the starting angles of
5718 the wedges.
5719 \item \gbc{piedirection}, a pair array, gives the unit vectors
5720 pointing from the center of the piechart through middles of the
5721 wedges. For example, if \cs{pieangle1} is 0 and \gbc{pieangle2}
5722 is 90 degrees, then \gbc{piedirection1} is $(\cos 45,\sin 45)$,
5723 the unit vector whose angle is $45$ degrees.
5724 \end{itemize}
5725
5726 Using \cs{barchart} (or \cs{mfpbarchart} or any of its aliases) causes
5727 the following arrays to become defined (or redefined). The exact meaning
5728 depends on whether bars are horizontal or vertical. The following
5729 describes horizontal bars; exchange the roles of $x$ and $y$ if they are
5730 vertical (also change `right' to `top', etc.):
5731 \begin{itemize}
5732 \item \gbc{barstart}, a numeric array, gives the position on the
5733 $y$-axis of the leading edge of the bars.
5734 \item \gbc{barbegin}, numeric, gives the $x$-coordinate of the
5735 leftmost end of the bars.
5736 \item \gbc{barend}, numeric, gives the $x$-coordinate of the rightmost
5737 end of the bars.
5738 \item \gbc{chartbar}, a path array, gives the actual bars. For
5739 example, \gbc{chartbar2} is the rectangle with opposite corners
5740 \gbc{(barbegin2,barstart2)} and \gbc{(barend2,barstart2+barwd)},
5741 where the numeric variable \gbc{barwd} is the thickness of the
5742 bar (which is a height for horizontal bars).
5743 \item \gbc{barlength}, the same as \gbc{barend}. This is for backward
5744 compatibility; the name was chosen at a time when all the bars
5745 had one side on an axis.
5746 \end{itemize}
5747
5748
5749 \subsection{Miscelaneous pair expressions}\label{pairexpressions}
5750
5751 A useful \MF{} operator that produces points is the intermediation
5752 operator, whose syntax is
5753 \begin{cd}
5754 \texttt{(\meta{num})[\meta{$p_1$},\meta{$p_2$}]}
5755 \end{cd}
5756 That is, a number or numeric expression in parentheses followed by
5757 literal brackets (this is \emph{not} an optional argument) containing
5758 two points or pair expressions separated by a comma. It returns an
5759 intermediate point on the line through \meta{$p_1$} and \meta{$p_2$}.
5760 The formula for the returned value is $p_1 + \mbox{\meta{num}}(p_2 -
5761 p_1)$. The midpoint is obtained with $\mbox{\meta{num}} = .5$. If the
5762 \meta{num} is a pure number, the parentheses can be omitted, but they
5763 are required if it is any other numeric expression. Values of \meta{num}
5764 larger than 1 or less than zero produce points on the line that lie
5765 outside the segment from $p_1$ to $p_2$. This operator can also be
5766 applied to numbers or (in \MP{}) to colors (of the same type). So that
5767 \codebox{(2/3)[3,6] = 5} and \codebox{.7[green,blue] = (0,.3,.7)}. See
5768 section~\ref{colors} for a description of colors in \MP{} and \MF{}.
5769
5770 \begin{cd}
5771 \gbc{pathpoint(\meta{frac},\meta{name})}
5772 \end{cd}
5773 This is another useful \MF{} command. It requires a number, \meta{frac},
5774 and the \emph{name} of a previously defined \MF{} path variable.
5775 (Defined, for example, using \cs{store}; see
5776 subsection~\ref{transformation}). It returns the point on the path that
5777 is approximately that fraction of the path's length from the start of
5778 the path. For example to draw a line from $(0,0)$ to the midpoint of an
5779 arc, do the following:
5780 \begin{verbatim}
5781 \store{myarc}\draw\arc{(1,0),(0,2),90}
5782 \polyline{(0,0), pathpoint(.5,myarc)}
5783 \end{verbatim}
5784 \CMF{} has no general command for calculating the lengths of paths;
5785 \CMP{} does, but it is quite slow. Thus neither program has an efficient
5786 method for finding the described point, so \mfp{} uses \MF\slash\MP{} macros
5787 that are faster, but less accurate than they could be. Still, the
5788 results should (except in pathological cases) be accurate to within a
5789 couple of percent of the length of the path. If they are not, adjust the
5790 value of the fraction. These remarks about accuracy also hold for any
5791 other command (such as \cs{partpath} in subsection~\ref{reversal}) that
5792 take the fraction of a path length as a parameter.
5793
5794 The \gbc{pathpoint} command is not a basic \MF{} command, but is defined
5795 by the \prog{grafbase} macros that accompany \mfp{}.
5796
5797 \MF{} pairs can conveniently be viewed as complex numbers. So
5798 \file{grafbase} also contains some functions useful in complex analysis
5799 (my research field). In what follows \gbc{a}, \gbc{z} and \gbc{w} denote
5800 pair variables or constants, and each function interprets them as
5801 complex numbers. Also \gbc{t} denotes an angle in radians. There are
5802 both numeric and pair valued functions, the type of each is noted after
5803 the description:
5804
5805 \def\Arg{\mathop{\mathrm{Arg}}}
5806
5807 \noindent
5808 \begin{tabular}{@{}lp{4.2in}}
5809 \gbc{Arg z} & The principle argument of $z$ in radians (numeric).\\
5810 \gbc{Log z} & The principle logarithm of $z$ (pair).\\
5811 \gbc{cis t} & $(\cos t, \sin t)$, same as \gbc{dir degrees(t)} (pair).\\
5812 \gbc{zexp w} & The complex exponential, $e^w$ (pair).\\
5813 \gbc{zsqrt w} & The (principal) complex square root: that $z$ with
5814 $-\pi/2 \le \Arg z \le \pi/2$ and $z^2 = w$ (pair).\\
5815 \gbc{sgn z} & The signum, $\sgn (0,0) = (0,0)$ otherwise
5816 $\sgn z = z/|z|$ (pair).\\
5817 \gbc{conj z} & The complex conjugate, $\bar z$ (pair).\\
5818 \gbc{Moebius(a) z} & The M\"obius transformation $(z+a)/(1+\bar{a}z)$ (pair)\\
5819 \gbc{pshdist(z,w)} & The pseudohyperbolic distance between $z$ and
5820 $w$: $|z-w| / |1-\bar{w}z|$ (numeric).\\
5821 \gbc{kelvin(z)} & The Kelvin transform $1/\bar z$ (pair)
5822 \end{tabular}
5823
5824 \CMF{} will happily add and subtract pairs but to multiply and divide
5825 complex numbers requires new operations. These are given by \codebox{(z
5826 zmul w)} and \codebox{(z zdiv w)}. They operate on pairs and produce
5827 pairs.
5828
5829
5830 \subsection{Manipulating \MF{} picture variables}
5831
5832 \begin{cd}\pagelabel{tile}
5833 \cs{tile}\marg{\meta{tilename},\meta{unit},\meta{wd},\meta{ht},\meta{clip}}\\
5834 \ \meta{\mfp{} drawing commands}\\
5835 \cs{endtile}%
5836 \index{tile@\cs{tile}}%
5837 \index{endtile@\cs{endtile}}
5838 \end{cd}
5839
5840 In this environment, all drawing commands contribute to a \emph{tile}. A
5841 \emph{tile} is a rectangular picture which may be used to fill the
5842 interior of closed paths. Actually, a tile is a composite object. After
5843 \cs{tile}\marg{Nick, ... } $\ldots$ \cs{endtile} a picture variable
5844 \gbc{Nick.pic} is created as well as numeric variable \gbc{Nick.wd} and
5845 \gbc{Nick.ht}. These are needed by the \cs{tess} command, below.
5846
5847 The units of drawing are given by \meta{unit}, which should be an
5848 explicit dimension (like \dim{1pt} or \dim{.2in}). The tile's horizontal
5849 dimensions are $0$ to $\meta{wd}\cdot\meta{unit}$ and its vertical
5850 dimensions $0$ to $\meta{ht}\cdot\meta{unit}$, so \meta{wd} and
5851 \meta{ht} should be pure numbers. If \meta{clip} is \mfc{true} then the
5852 drawing is clipped to be within the tile's boundary.
5853
5854 By using this macro, you can design your own fill patterns (to use them,
5855 see the \cs{tess} macro below), but see the warning about memory use by
5856 the \cs{tess} command. The \meta{tilename} is globally defined by this
5857 command.
5858
5859 \begin{cd}\pagelabel{tess}
5860 \cs{tess}\marg{\meta{tilename}}$\ldots$%
5861 \index{tess@\cs{tess}}
5862 \end{cd}
5863
5864 This rendering macro tiles the interior of a closed path with a
5865 tessellation comprised of copies of the \emph{tile} specified by
5866 \meta{tilename}. The tile must have been previously created by
5867 \cs{tile}\marg{\meta{tilename}, ... }. Tiling an open curve is
5868 technically an error, but the \MF{} code responds by drawing the path
5869 and not doing any tiling. The \MF{} code places shifted copies of the
5870 tile picture in a rectangular grid sufficient to cover the region, then
5871 clips it to the closed path before drawing it.
5872
5873 Tiling large regions with complicated tiles can exceed the capacity of
5874 some versions of \MP{}. There is less of a problem with \MF{}. This is not
5875 because \MF{} has greater capacity, but because of the natural
5876 difference between bitmaps and vector graphics.
5877
5878 In \MP{}, the tiles are copied with whatever color they are given when
5879 they are defined. They can be multicolored.
5880
5881 Before version 0.8, \cs{tile} was the only way to create a picture
5882 variable, and the only way to draw this picture was with the \cs{tess}
5883 command. Now we have the following command to place multiple copies of
5884 a picture:
5885
5886 \begin{cd}\pagelabel{putmfpimage}
5887 \cs{putmfpimage}\marg{\meta{name}}\marg{\meta{list}}%
5888 \index{putmfpimage@\cs{putmfpimage}}
5889 \end{cd}
5890
5891 This take the name of a picture variable and copies the picture at each
5892 location in the \meta{list}, which should be a comma-separated list of
5893 coordinate pairs in graph coordinates. The picture is copied so that its
5894 \emph{reference point} is placed at each of the locations. The reference
5895 point of a picture created with \cs{tile} is its lower left corner.
5896
5897 \begin{cd}\pagelabel{mfpimage}
5898 \cs{mfpimage}\oarg{\meta{refpt}}\marg{\meta{picname}}\\
5899 \ \meta{\mfp{} drawing commands}\\
5900 \cs{endmfpimage}%
5901 \index{mfpimage@\cs{mfpimage}}%
5902 \index{endmfpimage@\cs{endmfpimage}}
5903 \end{cd}
5904
5905 This is another way to create a picture variable. The drawing commands
5906 within the \env{mfpimage} environment contribute not to the current
5907 \mfp{} picture, but rather to the picture variable named in \meta{picname}.
5908 Otherwise, they operate exactly as they would outside this environment,
5909 using the same coordinate system and the same default values of all
5910 parameters, etc. (unlike the \env{tile} environment, which defines its
5911 own coordinate system). The picture is created with its reference point
5912 at the point \meta{refpt} given in the optional argument. The default is
5913 \texttt{(0,0)}. For example:
5914 \begin{verbatim}
5915 \mfpimage[(1,1)]{Jan}
5916 \fill\rect{(0,0),(1,1)}
5917 \fill\rect{(1,1),(2,2)}
5918 \rect{(0,0),(2,2)}
5919 \endmfpimage
5920 \end{verbatim}
5921 produces a simple 2-by-2 chessboard with its reference point at the
5922 center point $(1,1)$. One can then write something like
5923 \begin{verbatim}
5924 \putmfpimage{Jan}{(1,1),(3,1),(1,3),(3,3)}
5925 \end{verbatim}
5926 to get a 4-by-4 chessboard: the picture \mfc{Jan} copied with its
5927 center at each of the listed points.
5928
5929 The behavior of \cs{tlabel} in an \env{mfpimage} environment depends on
5930 the setting. If \opt{mplabels} is turned off, then labels are added by
5931 \TeX{} and are \emph{not} included as part of the named \MF{} or \MP{}
5932 picture variable. They are placed on the current picture as if the
5933 \env{mfpimage} environment were not there at all. If \opt{mplabels} is
5934 turned on and \opt{overlaylabels} is also turned on, or if the
5935 \env{mfpimage} environment is between \cs{startbacktext} and
5936 \cs{stopbacktext}, then the labels will be saved and placed when the
5937 \env{mfpic} environment ends and \emph{not} added to the named picture
5938 variable. Thus, to include text labels in the named picture variable,
5939 you must have \opt{mplabels} on, \opt{overlaylabels} off, and
5940 \env{mfpimage} outside any \cs{startbacktext}\slash\cs{stopbacktext}.
5941
5942 The picture created by \cs{mfpimage} is locally defined. That is, it
5943 becomes undefined at the end of the current \env{mfpic} environment. If
5944 one needs it to be global, one can use \cs{globalsetmfvariable} (see
5945 subsection~\ref{variables}) to copy it to another variable. For example.
5946 the command
5947 \begin{verbatim}
5948 \globalsetmfvariable{picture}{Dan}{Jan}
5949 \end{verbatim}
5950 would make \gbc{Dan} globally defined to be equal to the current value
5951 of the picture \gbc{Jan}. Note that picture variables can consume a lot
5952 of \MF{}'s memory. Copying one variable to another doubles the amount of
5953 memory, at least until the end of the \env{mfpic} environment.
5954
5955 You can use \cs{putmfpimage} inside a \env{mfpimage} environment,
5956 provided the picture being placed has been previously defined. Nesting a
5957 \env{mfpimage} inside another has not been tested at all and so is not
5958 recommended. But if it works, the inner image would be local to the
5959 environment created by the outer one, and so would be of limited use.
5960 One can use the \LaTeX{} environment construct \cs{begin}\marg{mfpimage}
5961 $\ldots$ \cs{end}\marg{mfpimage} in a LaTeX document instead of
5962 \cs{mfpimage} $\ldots$ \cs{endmfpimage}.
5963
5964
5965 \subsection{\CMF{} loops}\label{loops}
5966
5967 All the \mfp{} loop commands create a loop (in the \MF{} language) in
5968 the output file. The \MF{} commands in that loop are executed repeatedly
5969 by \MF{} or \MP{}. From the point of view of \TeX{}, however each
5970 command occurs only once. Starting with version 0.9, these loops can be
5971 created inside or outside the \env{mfpic} drawing environment. If
5972 outside, they must not contain any drawing commands, but can contain
5973 commands that set variables, perform computations, etc.
5974
5975 \begin{cd}\pagelabel{mfpfor}
5976 \cs{mfpfor}\marg{\meta{for-loop header}}\\
5977 \ \meta{\mfp{} commands}\\
5978 \cs{endmfpfor}%
5979 \index{mfpfor@\cs{mfpfor}}%
5980 \index{endmfpfor@\cs{endmfpfor}}
5981 \end{cd}
5982
5983 This creates a for-loop in the \MF{} output file. The \cs{mfpfor} writes
5984 the start of the loop and \cs{endmfpfor} writes the end. Any code
5985 written in the output file between them is executed repeatedly by
5986 \MF{}, according to the information in \meta{for-loop header}. There are
5987 two types of headers possible, illustrated by the following examples.
5988 \begin{verbatim}
5989 \mfpfor{center = (0,0), (1,0), (0,1)}
5990 \gfill\circle{center,1}
5991 \endmfpfor
5992 \end{verbatim}
5993 This example will fill three circles of radius 1 with centers at the
5994 three given points. This type of header has the format
5995 \begin{display}
5996 \mfc{\meta{variable} = \meta{list}}
5997 \end{display}
5998 where \meta{variable} should be a simple variable name and \meta{list}
5999 is a comma separated list of items of the appropriate data type. In the
6000 above, \gbc{center} is equated to pairs, but in the following
6001 \begin{verbatim}
6002 \mfpfor{radius = 1,3,4}
6003 \dotted\circle{(0,0),radius}
6004 \endmfpfor
6005 \end{verbatim}
6006 \gbc{radius} gets numeric values.
6007
6008 The other type of header uses a stepped variable:
6009 \begin{verbatim}
6010 \mfpfor{level = 3 step 2 until 9}
6011 \circle{(0,0),sqrt(level)}
6012 \endmfpfor
6013 \end{verbatim}
6014 This will cause the \MF{} variable \gbc{level} to step through the
6015 values 3, 5, 7 and 9 and the circles with radius $\sqrt{3}$, $\sqrt{5}$,
6016 etc. will be drawn. This type of header has the format
6017 \begin{display}
6018 \mfc{\meta{variable} = \meta{start} step \meta{delta} until \meta{stop}}
6019 \end{display}
6020 where \meta{variable} is as before, while \meta{start}, \meta{delta} and
6021 \meta{stop} are numeric values. If \meta{delta} is positive the loop is
6022 skipped entirely if \meta{stop} is less than \meta{start}. Otherwise the
6023 loop is executed successively with the variable equal to \meta{start},
6024 then $\meta{start} + \meta{delta}$ then $\meta{start} + 2\meta{delta}$,
6025 etc., as long as the variable is not greater than \meta{stop}. The
6026 behavior is similar if \meta{delta} is negative, except the loop is
6027 repeated only as long as the variable is not less than \meta{stop}. If
6028 \meta{delta} is \mfc{0}, then the \MF{} run will generate an error.
6029
6030 Note that the index variable (\gbc{center} and \gbc{radius} in the above
6031 two examples) is a temporary \MF{} variable. If \opt{mplabels} is turned
6032 on, this variable will work as expected in the \emph{location} parameter
6033 of a \cs{tlabel} command, but if it is used in the \emph{label} part, it
6034 will be interpreted as \TeX{} code and printed as is. The index variable
6035 reverts to its previous state outside the loop. That is, if it existed
6036 before the loop, it regains its previous value after the loop, and if it
6037 was undefined before the loop, it is again undefined after.
6038
6039 The single word `\mfc{upto}' can be used as an abbreviation for
6040 ``\codebox{step 1 until}'' and `\mfc{downto}' for ``\codebox{step -1 until}''
6041 in for-loop headers. Spaces are not significant in for-loop headers,
6042 except to distinguish the keywords (e.g. \mfc{step}) from variable names
6043 that might be used (e.g., for \meta{start}).
6044
6045 \begin{cd}\pagelabel{mfpwhile}
6046 \cs{mfpwhile}\marg{\meta{condition}}\\
6047 \ \meta{\mfp{} commands}\\
6048 \cs{endmfpwhile}%
6049 \index{mfpwhile@\cs{mfpwhile}}%
6050 \index{endmfpwhile@\cs{endmfpwhile}}
6051 \end{cd}
6052
6053 The \meta{condition} should be an expression that can be either true or
6054 false about a \MF{} variable that changes at some time during the loop
6055 body. The loop body is executed (by \MF) as long as the condition is
6056 true. Example:
6057 \begin{verbatim}
6058 \setmfvariable{numeric}{R}{20}
6059 \mfpwhile{R > 1}
6060 \rect{(0,0), (R,3R)}
6061 \mfcmd{R:=R/2}
6062 \endmfpwhile
6063 \end{verbatim}
6064 There are no \mfp{} commands to \emph{systematically} change a variable,
6065 so in this example we have resorted to directly writing a \MF{} assignment
6066 command via \cs{mfcmd} (see subsection~\ref{mfcode} above) that reduces
6067 \mfc{R} by half. The loop will be executed with \mfc{R} having the
6068 successive values $20$, $10$, $5$, $2.5$, and $1.25$. The resulting
6069 picture could have been achieved with \cs{mfpfor} using this list of
6070 values.
6071
6072 \begin{cd}\pagelabel{mfploop}
6073 \cs{mfploop}\\
6074 \ \meta{\mfp{} commands}\\
6075 \cs{mfpuntil}\marg{\meta{condition}}\\
6076 \ \meta{\mfp{} commands}\\
6077 \cs{endmfploop}%
6078 \index{mfploop@\cs{mfploop}}%
6079 \index{mfpuntil@\cs{mfpuntil}}%
6080 \index{endmfploop@\cs{endmfploop}}%
6081 \end{cd}
6082
6083 The body of this loop will be repeated until the \meta{condition}
6084 becomes true. The condition should be some expression that can be either
6085 true or false about a variable that changes during the loop execution.
6086 It should eventually become true. If an \env{mfploop} environment does
6087 not contain an \cs{mfpuntil} command, then the \cs{endmfploop} command
6088 will generate a warning message. If the warning is ignored, and the user
6089 has not otherwise arranged for loop termination,%
6090 \footnote{Perhaps by means of \cs{mfsrc} commands. It is because of
6091 this possibility that only a warning is produced and not an error.
6092 If the warning becomes annoying, adding \cs{mfpuntil\marg{false}} to
6093 the loop will silence it. This command will never break the loop
6094 because the condition \mfc{false} (of course) never becomes true.}
6095 the \file{.mf} file will contain an infinite loop. The \cs{mfpuntil}
6096 command will break the loop at whatever point it occurs. Example:
6097 \begin{verbatim}
6098 \setmfvariable{numeric}{R}{20}
6099 \mfploop
6100 \mfcmd{R:=R/2}
6101 \mfpuntil{R <= 1}
6102 \rect{(0,0), (R,3R)}
6103 \endmfploop
6104 \end{verbatim}
6105 This will draw rectangles with $R$ equal to $10$, $5$, $2.5$, and
6106 $1.25$. On the next execution of the loop the condition \mfc{R<=1} is
6107 true, and the break occurs before the next rectangle is drawn. Note that
6108 any \cs{mfpwhile} could be encoded with \cs{mfploop}. In fact, the code
6109 written to the output file by
6110 \begin{display}
6111 \cs{mfpwhile}\marg{\meta{condition}}
6112 \end{display}
6113 is identical to that written by
6114 \begin{display}
6115 \cs{mfploop}\cs{mfpuntil}\marg{not \meta{condition}}
6116 \end{display}
6117
6118 The command \cs{mfpuntil} can also be used in \env{mfpfor} and
6119 \env{mfpwhile} environments to break the loop prematurely when the given
6120 condition becomes true.
6121
6122 All three of these loop structures bracket the inner code in a \TeX{}
6123 group. In a \LaTeX{} document, the usual \cs{begin}\slash\cs{end} style can
6124 be used. For example,
6125 \begin{verbatim}
6126 \begin{mfpfor}{radius = 1,3,4}
6127 \circle{(0,0),radius}
6128 \end{mfpfor}
6129 \end{verbatim}
6130
6131 Just to be clear: in all the examples, what is written to the figure
6132 file is a \emph{single} circle or rectangle drawing command, bracketed
6133 by code that causes \MF{} to execute it several times with different
6134 values for the variable. From \TeX{}'s point of view, there is only one
6135 \mfp{} drawing command.
6136
6137
6138 \subsection{Miscellaneous}\label{misc}
6139
6140 \begin{cd}\pagelabel{mfmode}
6141 \cs{mfmode}\marg{\meta{mode-name}}\\
6142 \cs{mfresolution}\marg{\meta{DPI}}%
6143 \end{cd}
6144
6145 When working with \MF{}, the code in \file{grafbase.mf} needs to know
6146 the resolution at which to make the font with all the figures. If the
6147 wrong resolution is assumed, the figure may end up appearing wrongly
6148 scaled or have other problems (especially with shading). If your DVI
6149 viewing/printing program and the file \file{modes.mf} are correctly
6150 configured, nothing may need to be done. If not, as a last resort, you
6151 can set the \MF{} mode or the \MF{} resolution in your \file{.tex} file
6152 with these commands. If you don't know what that means, ask a guru, but
6153 then you should probably be using \MP{} and not \MF{}.
6154
6155 Note that this is a \emph{last resort}. The code in \file{grafbase.mf}
6156 first checks if \mfc{mode} has been defined, then checks if
6157 \mfc{localfont} is defined and only then checks if the resolution has
6158 been set by this method (if all three fail, it uses a value of 600 DPI).
6159
6160 \begin{cd}\pagelabel{noship}
6161 \cs{noship}\\%
6162 \cs{stopshipping}\\%
6163 \cs{resumeshipping}%
6164 \index{noship@\cs{noship}}%
6165 \index{stopshipping@\cs{stopshipping}}%
6166 \index{resumeshipping@\cs{resumeshipping}}
6167 \end{cd}
6168
6169 \cs{stopshipping} turns off character shipping (by \MF{} to the TFM and
6170 GF files, or by \MP{} to appropriate \EPS{} output file) until
6171 \cs{resumeshipping} occurs. If you want just one character not shipped,
6172 just use \cs{noship} inside that \env{mfpic} environment. This is useful
6173 if all one wishes to do in the current \env{mfpic} environment is to
6174 make tiles (see above) or define picture variables with \cs{mfpimage} or
6175 path arrays with \cs{patharr}. While \cs{mfpimage} defines the picture
6176 locally, one can globally copy it to another variable with
6177 \cs{globalsetmfvariable} (see subsection~\ref{variables}).
6178
6179 \begin{cd}\pagelabel{assignmfvalue}
6180 \cs{assignmfvalue}\marg{\meta{\TeX{}-macro}}\marg{\meta{MF-expr}}\\
6181 \cs{assignmpvalue}\marg{\meta{\TeX{}-macro}}\marg{\meta{MF-expr}}\\
6182 \cs{globalassignmfvalue}\marg{\meta{\TeX{}-macro}}\marg{\meta{MF-expr}}\\
6183 \cs{globalassignmpvalue}\marg{\meta{\TeX{}-macro}}\marg{\meta{MF-expr}}%
6184 \index{assignmfvalue@\cs{assignmfvalue}}%
6185 \index{assignmpvalue@\cs{assignmpvalue}}%
6186 \index{globalassignmfvalue@\cs{globalassignmfvalue}}%
6187 \index{globalassignmpvalue@\cs{globalassignmpvalue}}%
6188 \end{cd}
6189
6190 The command names spelled with `\texttt{mp}' are no different than the
6191 ones spelled with `\texttt{mf}'. You can use either spelling with
6192 either the \opt{metafont} or \opt{metapost} option.
6193
6194 These commands causes the \meta{MF-expr} to be written to the output
6195 file for \MF{} to evaluate. The resulting value is then written to the
6196 \file{.log} file of that \MF{} run. On the next \TeX{} run, if
6197 \opt{mfpreadlog} (see section~\ref{readlog}) is in effect, the macro
6198 \meta{\TeX{}-macro} will be defined to produce the resulting value. For
6199 example:
6200 \begin{verbatim}
6201 \setmfnumeric{s}{2}
6202 \assignmfvalue{\val}{exp s}
6203 \tlabel(1,2){$e^s = \val$}
6204 \end{verbatim}
6205 After \MF{} is run and then \TeX{} run a second time, \cs{val} will
6206 acquire the definition `7.38905', the value of \gbc{exp s} when
6207 \gbc{s=2} (i.e., $e^2$, correct to at least the fourth decimal place).
6208 If \opt{mplabels} is in effect, the correct label is written to the
6209 figure file only during this second run, and a second \MP{} run will be
6210 required. In many cases (when using \pdfTeX{}, for example, or when the
6211 label changes the figure dimensions), a third \TeX{} run will be
6212 required to make the figure correct when it is included in the document.
6213
6214 Before \MF{} is run to evaluate the expression, the macro produces
6215 `???'. Thus, it cannot be used in places where a number is needed (as in
6216 the position arguments of a \cs{tlabel} command). Note also that if a
6217 command defined by \cs{assignmfvalue} is used in a tlabel with
6218 \opt{mplabels} in effect, then \opt{mplabels} must be in effect during
6219 the \cs{assignmfvalue} command as well.
6220
6221 The `\texttt{global}' version makes the definition of the
6222 \meta{\TeX{}-macro} global, surviving the current group. In particular,
6223 it can be used in other pictures. The plain versions create commands
6224 that are only locally defined. Past versions of this manual stated that
6225 you can say
6226 \begin{display}
6227 \cs{global}\cs{assignmfvalue}
6228 \end{display}
6229 to define the macro globally. This turns out not to be true in all
6230 cases. If a global definition is needed, use the global versions above.
6231
6232 Because of the asynchronous nature of the definition process, using
6233 \cs{assignmfvalue} with the same macro name more than once in the same
6234 \env{mfpic} environment will not work. The macro becomes defined
6235 upon reading the logfile during the execution of \cs{opengraphsfile},
6236 and it will end up with the last definition encountered. (The same is
6237 true for uses outside \env{mfpic} environments: the macro acquires the
6238 last such definition.) Moreover, the definition is associated to a
6239 picture by number. Which means that reordering the environments or
6240 changing the numbering by any means will require the \TeX{}-\MF{}-\TeX{}
6241 sequence (or more) to be repeated.
6242
6243 If the \meta{\TeX{}-macro} is already defined, no warning will be issued
6244 and the command will be redefined, so be careful in the name chosen.
6245 If \opt{mplabels} is turned off when \cs{assignmfvalue} is used, but
6246 turned on before the \meta{\TeX{}-macro} is used in a \cs{tlabel}
6247 command, the macro definition will not be written to the \file{.mp}
6248 file, and either an error message, or incorrect label will result
6249 when \MP{} tries to make the tlabel.
6250
6251 The concept and much of the code for \cs{assignmfvalue} came from Werner
6252 Lemberg. However, I have rewritten it substantially to conform to \mfp{}
6253 conventions and so any errors are my responsibility.
6254
6255 \begin{cd}\pagelabel{cutoffafter}
6256 \cs{cutoffafter}\marg{\meta{obj}}\dots\\
6257 \cs{cutoffbefore}\marg{\meta{obj}}\dots\\
6258 \index{cutoffafter@\cs{cutoffafter}}%
6259 \index{cutoffbefore@\cs{cutoffbefore}}%
6260 \end{cd}
6261
6262 These prefix macros modify the following path by cutting part of it off.
6263 They take an `object' (a variable in which a path was
6264 previously stored using \cs{store}) and uses it to trim off one end of the
6265 following path. \cs{cutoffbefore} cuts off the part of the path
6266 \emph{before} its first intersection with the object, while
6267 \cs{cutoffafter} cuts off the part \emph{after} the last intersection.
6268 If the path does not intersect the object, nothing is cut off. If the
6269 object and the path intersect in more than one point, as little as
6270 possible (usually%
6271 \footnote{\MF{}'s methods for finding the `first' point of
6272 intersection do not always find the actual first one.}) %
6273 is cut off. This is reliable only when there is a unique point of
6274 intersection.
6275
6276 These macros can be used to create a curve that starts or ends
6277 right at another figure without having to know the point where the two
6278 curves intersect.
6279
6280 \begin{cd}\pagelabel{random}
6281 \cs{randomlines}\marg{\meta{maxshift}}\dots\\
6282 \cs{randomizepath}\marg{\meta{maxshift}, \meta{weirdness}}\dots
6283 \index{randomizepath@\cs{randomizepath}}%
6284 \index{randomlines@\cs{randomlines}}
6285 \end{cd}
6286
6287 These modify the following path by applying random shifts to the nodes
6288 of a path. The first one, \cs{randomlines} then simply connects those
6289 new points by straight lines, while the second one also applies
6290 randomization to the control vectors. The \meta{maxshift} argument is
6291 either a positive number (in graph units) that limits the distance a
6292 node can be moved, or it is an ordered pair of positive numbers, in
6293 which case the first limits the horizontal distance and the second
6294 limits the vertical. If \meta{maxshift} is larger than the distance
6295 between nodes, cusps or loops are likely in the result.
6296
6297 For \cs{randomizepath} the \meta{weirdness} parameter controls how the
6298 control vectors are modified. Roughly speaking the control vectors are
6299 randomly rotated up to $30\langle\mathit{weirdness}\rangle$ degrees and
6300 randomly scaled up or down by a factor of
6301 $2^{\langle\mathit{weirdness}\rangle}$. (A ``control vector'' is a
6302 vector pointing from a node to one of its control points.) However, this
6303 is done in a way that preserves smoothness at each node where the path
6304 is smooth. Values of \meta{weirdness} greater than 1 are probably much
6305 too weird.
6306
6307 \begin{cd}\pagelabel{brownianmotion}
6308 \cs{brownianmotion}\marg{\meta{start},\meta{num},\meta{scale}}\\%
6309 \cs{browniangraph}\marg{\meta{num},\meta{scale}}\\%
6310 \cs{randomwalk}\marg{\meta{start},\meta{num},\meta{scale}}%
6311 \index{brownianmotion@\cs{brownianmotion}}%
6312 \index{browniangraph@\cs{browniangraph}}%
6313 \index{randomwalk@\cs{randomwalk}}
6314 \end{cd}
6315
6316 These figure macros build a few standard kinds of random paths. The
6317 \cs{brownianmotion} path starts at the point \meta{start}, then proceeds
6318 in a straight line in a random direction a random distance. This is
6319 repeated \meta{num} times to form a polyline. The random process used is
6320 a Gaussian in each coordinate, scaled so that the random distance has a
6321 standard deviation equal to \meta{scale}. Thus, \meta{start} is a
6322 coordinate pair in graph coordinates, \meta{num} is a positive whole
6323 number and \meta{scale} is a positive real number (in graph units). In
6324 rare cases, the random distance can become quite large, but on average
6325 it will be about $0.56\times{}$\meta{scale}. The size of the resultant
6326 path (its bounding box) can also be, in rare cases, quite large, but it
6327 is usually on the order of $\sqrt{\meta{num}}$ times \meta{scale}.
6328
6329 The second path, \cs{browniangraph}, represents the graph of a
6330 one-dimensional Brownian motion. It is random only in the vertical
6331 direction as the rightward motion represents the uniform passage of
6332 time. It starts at $(0,0)$ and the \meta{scale} is both the constant
6333 rightward step as well as the standard deviation for the $y$-coordinate.
6334 Users will need to apply a shift if they want to change the starting
6335 point, and a vertical scaling if they want a scale factor different from
6336 the step size.
6337
6338 Despite their names, the paths produced are technically not Brownian
6339 motion, but rather `Gaussian random walks'. However, for small
6340 \meta{scale} and large \meta{num} they can be used to approximate
6341 Brownian motion.
6342
6343 Finally, \cs{randomwalk} is just like \cs{brownianmotion} except that
6344 only the direction is random. The distance is always equal to
6345 \meta{scale}.%
6346 \footnote{This is only one kind of an infinite variety of possible
6347 random walks. See \url{http://en.wikipedia.org/wiki/Random_walk} for a
6348 discussion. \Mfp{} implementation of other kinds is left to the
6349 interested user (for example, using \cs{turtle} with random
6350 displacements).}
6351
6352 There can be a problem with the size of \meta{num} in these three
6353 macros. Numbers greater than a certain \MF/\MP{} parameter called
6354 \verb$max_points$ (see the discussing at \cs{levelcurve} in
6355 section~\ref{plotting}) will produce an error from \MF{} or \MP{}. But
6356 also sharp turns will take up space in something called the
6357 \emph{rounding table}. This has no bearing on \MP{}, and in \MF{} it
6358 only matters if the parameter \mfc{autorounding} is positive. \Mfp{}
6359 leaves \mfc{autorounding} at the default of $2$, since this value makes
6360 drawings in \MF{} look best. In this case, the value of \meta{num}
6361 should be less than about $500$.
6362
6363 \begin{cd}\pagelabel{mftitle}
6364 \cs{mftitle}\marg{\meta{title}}%
6365 \index{mftitle@\cs{mftitle}}
6366 \end{cd}
6367
6368 Write the string \meta{title} to the \MF{} file, and use it as a \MF{}
6369 message. (See \textit{The \MF{}book}, chapter 22, page 187, for two uses of
6370 this.)
6371
6372 \begin{cd}\pagelabel{tmtitle}
6373 \cs{tmtitle}\marg{\meta{title}}%
6374 \index{tmtitle@\cs{tmtitle}}
6375 \end{cd}
6376
6377 Write the text \meta{title} to the \TeX{} document, and to the log file,
6378 and use it implicitly in \cs{mftitle}. This macro forms a local group
6379 around its argument.
6380
6381 \medskip
6382
6383 Since \TeX{} is limited to 256 dimension registers, and since dimensions
6384 are so important to typesetting and drawing, it is common to use up all
6385 256 when drawing packages are loaded. Therefore \mfp{} uses font
6386 dimensions to store dimension values. The following is the command that
6387 handles the allocation of these dimensions.
6388
6389 \begin{cd}\pagelabel{newfdim}
6390 \cs{newfdim}\marg{\meta{fdim}}%
6391 \index{newfdim@\cs{newfdim}}
6392 \end{cd}
6393
6394 This create a new global font dimension named \meta{fdim}, which is a
6395 \TeX{} control sequence (with backslash). It can be used almost like
6396 an ordinary \TeX{} dimension. One exception is that the \TeX{} commands
6397 \cs{advance}, \cs{multiply} and \cs{divide} cannot be applied directly
6398 to font dimensions (nor \LaTeX{}'s \cs{addtolength}); however, the font
6399 dimension can be copied to a temporary \TeX{} dimension register, which
6400 can then be manipulated and copied back (using \cs{setlength} in \LaTeX{},
6401 if desired). Another exception is that all changes to a font dimension
6402 are global in scope. Also beware that \cs{newfdim} uses font dimensions
6403 from a single font, the \file{dummy} font, which most \TeX{} systems
6404 ought to have. (You'll know if yours doesn't, because \mfp{} will fail
6405 upon loading!) Also, implementations of \TeX{} differ in the number of
6406 font dimensions allowed per font. \Mfp{} currently uses font dimensions
6407 23 through 52, which should be OK.
6408
6409 Almost all of \mfp{}'s basic dimension parameters are font dimensions.
6410 We arrange for them to be local to \env{mfpic} environments by saving
6411 their values at the start and restoring them at the end.
6412
6413 \begin{cd}\pagelabel{setmfpicgraphic}
6414 \cs{setmfpicgraphic}\marg{\meta{filename}}%
6415 \index{setmfpicgraphic@\cs{setmfpicgraphic}}
6416 \end{cd}
6417
6418 This is the command that is invoked to place the graphic created. See
6419 appendix~\ref{graphics} for a discussion of its use and its default
6420 definition. It is a user-level macro so that it can be redefined in
6421 unusual cases. It operates on the output of the following macro:
6422
6423 \begin{cd}\pagelabel{setfilename}
6424 \cs{setfilename}\marg{\meta{file}}\marg{\meta{num}}%
6425 \index{setfilename@\cs{setfilename}}
6426 \end{cd}
6427
6428 \Mfp's figure inclusion code ultimately executes
6429 \cs{setmfpicgraphic} on the result of applying \cs{setfilename} to two
6430 arguments: the file name specified in the \cs{opengraphsfile} command
6431 and the number of the current picture. Normally \cs{setfilename} just
6432 puts them together with the `\texttt{.}' separator (because that is
6433 usually the way \MP{} names its output), but this can be redefined if
6434 the \MP{} output undergoes further processing or conversion to another
6435 format in which the name is changed. Any redefinition of
6436 \cs{setfilename} must come before \cs{opengraphsfile} because that
6437 command tests for the existence of the first figure. After any
6438 redefinition, \cs{setfilename} must be a macro with two arguments that
6439 creates the actual filename from the above two parts. It should also be
6440 completely expandable. See the appendices, subsection~\ref{graphics} for
6441 further dicussion.
6442
6443 \begin{cd}\pagelabel{setfilenametemplate}
6444 \cs{setfilenametemplate}\marg{\meta{template}}%
6445 \index{setfilenametemplate@\cs{setfilenametemplate}}
6446 \end{cd}
6447
6448 With the \opt{metapost} option, when you write
6449 \cs{opengraphsfile}\marg{figs}, a file \file{figs.mp} is created. By
6450 default, running \MP{} on it results in files named \file{figs.1},
6451 \file{figs.2}, etc. Recent \MP{} allows the output filenames to be
6452 modified. As of \mfp{} version 1.00, you can do this to some extent from
6453 your \file{.tex} file. One needs to define a template that tells \MP{}
6454 how to construct the output file name from the `jobname' and the figure
6455 number. This is done with the above command. In \meta{template} you can
6456 put any plain characters, plus the two special tokens: \verb$\_$ and
6457 \verb$\#$. Each figure's filename is constructed by replacing these
6458 tokens with the \MP{} jobname and the figure number, respectively. For
6459 example, with the jobname \file{figs},
6460 \begin{verbatim}
6461 \setfilenametemplate{my\_-\#.mps}
6462 \end{verbatim}
6463 will cause the figure files to have names \file{myfigs-1.mps},
6464 \file{myfigs-2.mps}, etc., instead of the defaults. \Mfp{} adjusts the
6465 definition of \cs{setfilename} accordingly, so that the correct
6466 filenames are used.
6467
6468 Do not use this command unless you know your version of \MP{} is recent
6469 enough to have this capability. Under the \opt{metafont} option, this
6470 command is simply ignored, but \mfp{} has no way of checking the \MP{}
6471 version on its own.
6472
6473 If you are using \LaTeX{}, the \verb$\includegraphics$ command requires
6474 that the included figure file be recognized as \MP{} output. In practice,
6475 this usually means its extension \emph{must} be \texttt{.mps}. As an
6476 exception, it may also be the current figure number (the default if
6477 \verb$\setfilenametemplate$ is not used), because \mfp{} has always
6478 arranged for that to be recognized. The user may also issue a
6479 \verb$\DeclareGraphicsRule$ command to get other extensions recognized.
6480 See the documentation of the \prog{graphics} package.
6481
6482
6483 \begin{cd}\pagelabel{preparemfpicgraphic}
6484 \cs{preparemfpicgraphic}\marg{\meta{filename}}%
6485 \index{preparemfpicgraphic@\cs{preparemfpicgraphic}}
6486 \end{cd}
6487
6488 This command is automatically invoked before \cs{setmfpicgraphic} to
6489 make any preparations needed. The default definition is to do nothing
6490 except when the \prog{graphics} package is used. That package provides
6491 no clean way to determine the bounding box of the graphic after it is
6492 included. Since \mfp{} needs this information, this command redefines an
6493 internal command of the \prog{graphics} package to make the data
6494 available. If \cs{setmfpicgraphic} is redefined then this may also have
6495 to be redefined.
6496
6497 \begin{cd}\pagelabel{getmfpicoffset}
6498 \cs{getmfpicoffset}\marg{\meta{filename}}%
6499 \index{getmfpicoffset@\cs{getmfpicoffset}}
6500 \end{cd}
6501
6502 This command is automatically invoked after \cs{setmfpicgraphic} to
6503 store the offset of the lower left corner of the figure in the macros
6504 \cs{mfpicllx} and \cs{mfpiclly}. If \cs{setmfpicgraphic} is redefined
6505 then this may also have to be redefined.
6506
6507 \begin{cd}\pagelabel{ifmfpmpost}
6508 \cs{ifmfpmpost}%
6509 \index{ifmfpmpost@\cs{ifmfpmpost}}
6510 \end{cd}
6511
6512 Users wishing to write code that adjusts its behavior to the graph file
6513 processor can use this to test which option is in effect. The macro
6514 \cs{usemetapost} sets it true and \cs{usemetafont} sets it false. There
6515 are no commands \cs{mfpmposttrue} nor \cs{mfpmpostfalse}, since the user
6516 should not be changing the setting once it is set: a great deal of
6517 \mfp{} internal code depends on them, and on keeping them consistent
6518 with the \cs{opengraphsfile} commands reading of these booleans.
6519
6520 \begin{cd}\pagelabel{mfpicversion}
6521 \cs{mfpicversion}%
6522 \index{mfpicversion@\cs{mfpicversion}}
6523 \end{cd}
6524
6525 This expands to the current \mfp{} version multiplied by 100. At this
6526 writing, it produces `\texttt{\mfpicversion}' because the version is
6527 \mfpversion. It can be used to test the version:
6528 \begin{verbatim}
6529 \ifx\mfpicversion\undefined \def\mfpicversion{0}\fi
6530 \ifnum\mfpicversion<70 ... \else ... \fi
6531 \end{verbatim}
6532 \cs{mfpicversion} was added in version 0.7.
6533
6534
6535 Most of \mfp{}'s commands have arguments with parts delimited by commas
6536 and parentheses. In most cases this is no problem because they are
6537 written unchanged to the \file{.mf} and there they are parsed just fine.
6538 Some commands' arguments, however, have to be parsed by both \TeX{} and
6539 \MF{}. Examples are \cs{tlabel} (sometimes, under \opt{mplabels}), and
6540 \cs{pointdef}. One might be tempted to use \MP{} expressions there and
6541 that works fine as long as they do not contain commas or parentheses. In
6542 such cases, they can sometimes be enclosed in braces to prevent \TeX{}
6543 seeing these elements as delimiters, but sometimes these braces might
6544 get written to the \file{.mf} (or \file{.mp}) output and cause a \MF{}
6545 (\MP{}) error. In such cases the following work-around might be possible:
6546 \begin{verbatim}
6547 \def\identity#1{#1}
6548 \pointdef{A}(\identity{angle (1,2)},3)
6549 \rect{(0,0),\A}
6550 \end{verbatim}
6551
6552 The braces prevent \TeX{}'s argument parsing from seeing the first comma
6553 as a delimiter, but upon writing to the \file{.mf}, any \cs{identity}
6554 commands are expanded and only the contents appear in the output. (\TeX{}
6555 parses the argument to assign meanings to \cs{Ax} and \cs{Ay}.)
6556
6557 If the \prog{babel} package is loaded with certain options, the comma
6558 may become a special character. In that case, one may need to deactivate
6559 babel shorthands before some \mfp{} code. One might use \cs{everymfpic}
6560 to do this in every \env{mfpic} environment. In some cases, one may need
6561 to reactivate babel shorthands insided \cs{tlabel}, and one might use
6562 \cs{everytlabel} for this purpose. See your \prog{babel} documentation
6563 for the commands to do these things.
6564
6565 \clearpage
6566
6567 \def\sectionmark#1{\markright {\thesection\quad#1}}%
6568 \def\subsectionmark#1{}
6569 \def\subsubsectionmark#1{}
6570 \thispagestyle{plain}
6571 \chapter{Appendices}\label{appendices}
6572
6573
6574 \section{Acknowledgements.}\label{acknowledgements}
6575
6576 Tom would like to thank all of the people at Dartmouth as well as out in
6577 the network world for testing \mfp{} and sending him back
6578 comments. He would particularly like to thank:
6579
6580 Geoffrey Tobin
6581 for his many suggestions, especially about cleaning up the \MF{} code,
6582 enforcing dimensions, fixing the dotted line computations, and speeding
6583 up the shading routines (through this process, Geoffrey and Tom managed
6584 to teach each other many of the subtleties of \MF{}), and for keeping
6585 track of \mfp{} for nearly a year while Tom finished his thesis;
6586
6587 Bryan Green
6588 for his many suggestions, some of which (including his rewriting the
6589 \cs{tcaption} macro) ultimately led to the current version's ability to
6590 put graphs in-line or side-by-side; and
6591
6592 Uwe Bonnes and
6593 Jarom\'\i r Kuben,
6594 who worked out rewrites of \mfp{} during Tom's working hiatus and who
6595 each contributed several valuable ideas.
6596
6597 Some credit also belongs to
6598 Anthony Stark,
6599 whose work on a FIG to \MF{} converter has had a serious impact on the
6600 development of many of \mfp{}'s capabilities.
6601
6602 Finally, Tom would like to thank
6603 Alan Vlach,
6604 the other \TeX{}nician at Berry College, for helping him decide on the
6605 format of many of the macros, and for helping with testing.
6606
6607 \medskip
6608 Dan Luecking would like to echo Tom's thanks to all of the above,
6609 especially Geoffrey Tobin and Jarom\'\i r Kuben. And to add the names
6610 Taco Hoekwater, for comments, advice and suggestions, Werner Lemberg,
6611 for the \cs{assignmfvalue} command, and Zaimi Sami~Alex for suggestions.
6612
6613 But mostly, he'd like to thank Tom Leathrum for starting it all.
6614
6615
6616 \section{Changes History.}\label{changes}
6617
6618 See the file \file{changes.txt} for a somewhat sporadic history of
6619 changes to \mfp{}. See the file \file{README} for changes added since
6620 the previous version, and for any known problems.
6621
6622
6623 %\clearpage
6624 \section{Summary of Options.}\label{summary}
6625
6626 Unless otherwise stated, any of the command forms will be local to the
6627 current \env{mfpic} environment if used inside. Otherwise it will affect
6628 all later environments.
6629
6630 \medskip
6631 % \shortstack doesn't allow [t] aligment:
6632 \def\stack#1{{\tabular[t]{@{}l@{}}#1\endtabular}}
6633
6634 % Use halign so it will break over 2 pages
6635 {\openup\jot
6636 \halign to \textwidth
6637 {#\hfil\quad\tabskip0ptplus 1fil&
6638 #\hfil\quad&
6639 \vtop{\parindent0pt\rightskip0pt plus 1fil\relax
6640 \hsize.5\hsize\normalbaselines
6641 \strut#\strut}\tabskip0pt \cr
6642 \textsc{Option}:& \textsc{Command form(s)}:& \textsc{Restrictions}:\cr
6643 \noalign{\smallskip\hrule\smallskip}
6644 \opt{metapost}&
6645 \cs{usemetapost}&
6646 Command must come before \cs{opengraphsfile}.
6647 Incompatible with \opt{metafont} option.\cr
6648 \opt{metafont}&
6649 \cs{usemetafont}&
6650 The default. Command must come before
6651 \cs{opengraphsfile}. Incompatible with \opt{metapost}
6652 option. \cr
6653 \opt{mplabels}&
6654 \stack{\cs{usemplabels},\\ \cs{nomplabels}}&
6655 Requires \opt{metapost}. If command is used inside an
6656 \env{mfpic} environment, it should come before
6657 \cs{tlabel} commands to be affected. \cr
6658 \opt{overlaylabels}&
6659 \stack{\cs{overlaylabels},\\ \cs{nooverlaylabels}}&
6660 Has no effect without \opt{metapost}. \cr
6661 \opt{truebbox}&
6662 \stack{\cs{usetruebbox},\\ \cs{notruebbox}}&
6663 Has no effect without \opt{metapost}. \cr
6664 \opt{clip}&
6665 \stack{\cs{clipmfpic},\\ \cs{noclipmfpic}}&
6666 No restrictions. \cr
6667 \opt{clearsymbols}&
6668 \stack{\cs{clearsymbols},\\ \cs{noclearsymbols}}&
6669 No restrictions. \cr
6670 \stack{\opt{centeredcaptions}\\ \opt{raggedcaptions}}&
6671 \stack{\cs{usecenteredcaptions},\\ \cs{nocenteredcaptions}\\
6672 \cs{useraggedcaptions},\\ \cs{noraggedcaptions}}&
6673 If command is used inside an \env{mfpic} environment, it
6674 should come before the \cs{tcaption} command.\cr
6675 \opt{debug}&
6676 \stack{\cs{mfpicdebugtrue},\\\cs{mfpicdebugfalse}}&
6677 To turn on debugging while \file{mfpic.tex} is loading,
6678 issue \cs{def}\cs{mfpicdebug}\marg{true}.\cr
6679 \stack{\opt{draft}\\ \opt{final}\\ \opt{nowrite}}&
6680 \stack{\cs{mfpicdraft}\\ \cs{mfpicfinal}\\ \cs{mfpicnowrite}}&
6681 Should not be used together. Command forms should come
6682 before \cs{opengraphsfile} \cr
6683 \opt{mfpreadlog}&
6684 \cs{mfpreadlog}&
6685 Needed for \cs{assignmfvalue}. Must occur before
6686 \cs{opengraphsfile}. \cr
6687 }}
6688
6689
6690 %\clearpage
6691 \section{Plotting Styles for \cs{plotdata}.}\label{styles}
6692
6693 When \cs{plotdata} passes from one curve to the next, it increments a
6694 counter and uses that counter to select a dash pattern, color, or
6695 symbol. It uses predefined dash patterns named \mfc{dashtype0} through
6696 \mfc{dashtype5}, or predefined colors named \mfc{colortype0} through
6697 \mfc{colortype7}, or predefined symbols named \mfc{pointtype0} through
6698 \mfc{pointtype8}. Here follows a description of each of these variables.
6699 These variables must not be used in the second argument of
6700 \cs{reconfigureplot}, whose purpose is to redefine these variables.
6701
6702 \medskip
6703 Under \cs{dashedlines}, we have the following dash patterns:
6704
6705 \medskip
6706 \begin{tabular}{@{}lll}
6707 \textsc{Name}&\textsc{Pattern}&\textsc{Meaning}\cr
6708 \hline
6709 \vbox to 10pt{}%
6710 \mfc{dashtype0}& \dim{0bp} & solid line \\
6711 \mfc{dashtype1}& \dim{3bp,4bp} & dashes \\
6712 \mfc{dashtype2}& \dim{0bp,4bp} & dots \\
6713 \mfc{dashtype3}& \dim{0bp,4bp,3bp,4bp} & dot-dash \\
6714 \mfc{dashtype4}& \dim{0bp,4bp,3bp,4bp,0bp,4bp}& dot-dash-dot \\
6715 \mfc{dashtype5}& \dim{0bp,4bp,3bp,4bp,3bp,4bp}& dot-dash-dash
6716 \end{tabular}
6717
6718 \medskip
6719 Under \cs{coloredlines}, we have the following colors. Except for
6720 \mfc{black} and \mfc{red}, each color is altered as indicated. This is
6721 an attempt to make the colors more equal in visibility against a white
6722 background. (The success of this attempt varies greatly with the output
6723 or display device.) Four of the eight colors use the cmyk model
6724 when the \MP{} version is at least $1.000$.
6725
6726 \medskip
6727 \begin{tabular}{@{}llll}
6728 \textsc{Name}&\textsc{Color}&\textsc{(r,g,b)}&\textsc{(c,m,y,k)}\\
6729 \hline
6730 \vbox to 10pt{}%
6731 \mfc{colortype0}& black & $( 0, 0, 0)$&(0,0,0,1)\\
6732 \mfc{colortype1}& red & $( 1, 0, 0)$&\\
6733 \mfc{colortype2}& blue & $( .2, .2, 1)$&\\
6734 \mfc{colortype3}& orange & $(.66,.34, 0)$&\\
6735 \mfc{colortype4}& green & $( 0, .8, 0)$&\\
6736 \mfc{colortype5}& magenta& $(.85, 0,.85)$&(0,.85,0,.15)\\
6737 \mfc{colortype6}& cyan & $( 0,.85,.85)$&(.85,0,0,.15)\\
6738 \mfc{colortype7}& yellow & $(.85,.85, 0)$&(0,0,.85,.15)\\
6739 \end{tabular}
6740
6741 \medskip
6742
6743 Under \cs{pointedlines} and \cs{datapointsonly}, the following symbols
6744 are used. Internally each is referred to by the numeric name, but they
6745 are identical to the more descriptive name. Syntactically, all are \MF{}
6746 path variables. (The order changed between versions 0.6 and 0.7.)
6747
6748 \medskip
6749 \begin{tabular}{@{}ll}
6750 \textsc{Name}&\textsc{Description}\\
6751 \hline
6752 \vbox to 10pt{}%
6753 \mfc{pointtype0}& \mfc{Circle} \\
6754 \mfc{pointtype1}& \mfc{Cross} \\
6755 \mfc{pointtype2}& \mfc{SolidDiamond} \\
6756 \mfc{pointtype3}& \mfc{Square} \\
6757 \mfc{pointtype4}& \mfc{Plus} \\
6758 \mfc{pointtype5}& \mfc{Triangle} \\
6759 \mfc{pointtype6}& \mfc{SolidCircle} \\
6760 \mfc{pointtype7}& \mfc{Star} \\
6761 \mfc{pointtype8}& \mfc{SolidTriangle}
6762 \end{tabular}
6763
6764
6765 \section{Special Considerations When Using \CMF{}.}\label{mfconsiderations}
6766
6767 The most important restriction in \MF{} is on the size of a picture.
6768 Coordinates in \MF{} ultimately refer to pixel units in the font that is
6769 output. These are required to be less than 4096, so an absolute limit on
6770 the size of a picture is whatever length a row of 4095 pixels is. In
6771 fonts prepared for a LaserJet4 (600 DPI), this means 6.825 inches
6772 (17.3355cm). For a 1200 DPI pronter, the limit is 3.4125 inches.
6773
6774 A similar limit holds for numbers input, and the values of variables:
6775 \MF{} will return an error for `\mfc{sin 4096}'. Intermediate values
6776 can be greater (\mfc{sin (2*2048)} will cause no error), but final,
6777 stored results are subject to the limit. An \mfp{} example that
6778 generated an error recently was:
6779 \begin{verbatim}
6780 \mfpicunit 1mm
6781 \mfpic[10]{-3}{7}{-3.5}{5}
6782 \function{-4.5,4,.1}{x*x}
6783 \endmfpic
6784 \end{verbatim}
6785 The problem was the value of $4.5*4.5 = 20.25$: after multiplying by the
6786 \cs{mfpic} scaling factor, the \cs{mfpicunit} in inches, and the DPI
6787 value, this produces $20.25\times10\times0.03937\times600 > 4783$ pixel
6788 units. The error did not occur at the point of creating the font, but
6789 merely at the point of storing the path in an internal variable for
6790 manipulation and drawing. Thus, the fact that this particular picture
6791 was clipped to a much smaller size for printing did not help.
6792
6793 In \MP{}, the limit on numeric values is only 8 times as high: $32768$.
6794 However, that is independent of printer resolution and is interpreted as
6795 \PS{} points (\TeX{}'s `big points'). At $72$ points to the inch, this
6796 allows figures to be about 12.64 yards (11.56$\,$m).
6797
6798
6799 \section{Special Considerations When Using \CMP{}.}\label{mpconsiderations}
6800
6801 \subsection{Required support}
6802
6803 To use \mfp{} with \MP{}, the following support is needed (besides a
6804 working \MP{} installation):
6805
6806 \medskip\noindent
6807 \begin{tabular}{@{}lp{4.2in}}
6808 \TeX{} format &support needed\\
6809 \hline
6810 plain \TeX{} &The file \file{epsf.tex} or \file{epsf.sty}\\
6811 \LaTeX{}209 &(No longer supported, but plain \TeX{} methods
6812 might work)\\
6813 \LaTeX{} &The package \prog{graphics} or \prog{graphicx}\\
6814 \pdfLaTeX{} &The package \prog{graphics} or
6815 \prog{graphicx} with option \opt{pdftex}\\
6816 plain \pdfTeX{} &\raggedright The files \file{supp-pdf.mkii} or
6817 \file{supp-pdf.tex} and (possibly)
6818 \file{supp-mis.tex}\tabularnewline
6819 In all cases &\raggedright The files \file{grafbase.mp},
6820 \file{dvipsnam.mp} and \file{mfpicdef.tex} plus,
6821 of course, \file{mfpic.tex} (and \file{mfpic.sty}
6822 for \LaTeX{})
6823 \end{tabular}
6824
6825 \medskip
6826 The files \file{grafbase.mp} and \file{dvipsnam.mp} should be in a
6827 directory searched by \MP{}. If \MP{} cannot find the
6828 file \file{grafbase.mp}, then by default it will try to input
6829 \file{grafbase.mf}, which is generally fatal (and always futile).
6830
6831 The remaining files should be in directories searched by the appropriate
6832 \TeX{} variant. The file \file{mfpicdef.tex} is input by \TeX{} when
6833 \MP{} is processing labels in \file{.mp} files created by \mfp{}. The
6834 user is free to add commands of his own to that file, but be warned that
6835 updates to \mfp{} will overwrite it. Better to create ones own file (say
6836 \file{mydefs.tex}) and arrange its input via
6837 \verb$\mfpverbtex{\input mydefs.tex}$
6838
6839 In case \pdfLaTeX{} is used, the \prog{graphics} package is given the
6840 \opt{pdftex} option. This option requires the file \file{pdftex.def}
6841 which currently inputs one of the \file{supp-pdf} files. Early versions
6842 of \file{supp-pdf.tex} will input \file{supp-mis.tex}. These three files
6843 should be supplied with most \TeX{} installations.%
6844 \footnote{They are part of the Con\TeX{}t distribuition. At this writing,
6845 these files, plus a few others, can also be found at\\
6846 \file{CTAN/graphics/metapost/contrib/tools/mptopdf/tex/context/base/}.} %
6847 Older versions had some bugs in connection with the \prog{babel}
6848 package. One workaround was to load the \prog{graphics} package and
6849 \mfp{} before \prog{babel}.
6850
6851 If the user loads one of the above required files or packages before the
6852 \mfp{} macros are loaded then \mfp{} will not reload them. \Mfp{} will
6853 load whichever one it decides is required. In the \LaTeXe{} case, \mfp{}
6854 will load the \prog{graphics} package. If the user wishes
6855 \prog{graphicx}, then that package must be loaded before \mfp{}.
6856
6857
6858 \subsection{\CMP{} is not \MF{}}
6859
6860 \PS{} is not a pixel oriented language and so neither is \MP{}. The model
6861 for drawing objects is completely different between \MF{} and \MP{}, and
6862 so one cannot always expect the same results. \CMP{} support in
6863 \mfp{} was carefully written so that files successfully printed
6864 with \mfp{} using \MF{} would be just as successfully printed
6865 using \MP{}. Nevertheless, it frequently chokes on files that make use of
6866 the \cs{mfsrc} command for writing code directly to the \file{.mf} file.
6867 While \file{grafbase.mp} is closely based on \file{grafbase.mf}, some of
6868 the code had to be completely rewritten.
6869
6870 Pictures in \MP{} are stored as (possibly nested) sequences of objects,
6871 where objects are things like points, paths, contours, sub-pictures,
6872 etc. In \MF{}, pictures are stored as a grid of pixels. Pictures that are
6873 relatively simple in one program might be very complex in the other and
6874 even exceed memory allocated for their storage. Two examples are the
6875 \cs{polkadot} and \cs{hatch} commands. When the polkadot space and size
6876 are both too small, a \cs{polkadot}-ed region has been known to exceed
6877 \MP{} capacity, while being well within \MF{} capacity. In \MP{} the
6878 memory consumed by \cs{hatch} goes up in direct proportion to the linear
6879 dimensions of the figure being hatched, while in \MF{} it goes up in
6880 proportion to the area (except in horizontal hatching), and then the
6881 reverse can happen, with \MF{}'s capacity exeeded far sooner that \MP{}'s.
6882
6883 In \MP{} it is important to note that each
6884 prefix modifies the result of the entire following sequence. In essence
6885 prefixes can be viewed as being applied in the opposite order to their
6886 occurrence. Example:
6887 \begin{verbatim}
6888 \dashed\gfill\rect{(0,0),(1,1)}
6889 \end{verbatim}
6890 This adds the dashed outline to the filled rectangle. That is, first the
6891 rectangle is defined, then it is filled, then the outline is drawn in
6892 dashed lines. This makes a difference when colors other than black are
6893 used. Drawing is done with the center of the virtual pen stroked along
6894 the boundary curve(s), so half of its width falls inside the
6895 rectangle. On the other hand, filling is done right up to the boundary.
6896 In this example, the dashed lines are drawn on top of part of the fill.
6897 In the reverse order, the fill would cover part of the dashed outline.
6898
6899
6900 \subsection{Graphic inclusion}\label{graphics}
6901
6902 It may be impossible to completely cater to all possible methods of
6903 graphic inclusions with automatic tests. The macro that is invoked
6904 to include the \PS{} graphic is \cs{setmfpicgraphic} and the user
6905 may (carefully!) redefine this to suit special circumstances. Actually,
6906 \mfp{} runs the following sequence:
6907
6908 \begin{ex}
6909 \cs{preparemfpicgraphic}\marg{\meta{filename}}\\
6910 \cs{setmfpicgraphic}\marg{\meta{filename}}\\
6911 \cs{getmfpicoffset}\marg{\meta{filename}}%
6912 \index{preparemfpicgraphic@\cs{preparemfpicgraphic}}%
6913 \index{setmfpicgraphic@\cs{setmfpicgraphic}}%
6914 \index{getmfpicoffset@\cs{getmfpicoffset}}
6915 \end{ex}
6916
6917 The following are the default definitions for \cs{setmfpicgraphic}:
6918
6919 \medskip\noindent
6920 \begin{tabular}{@{}ll}
6921 plain \TeX{}&
6922 \cs{def}\cs{setmfpicgraphic}\texttt{\#1}\marg{\cs{epsfbox}%
6923 \marg{\#1}}\\
6924 \LaTeX{}209& (No longer supported, but likely the plain \TeX{}
6925 definition will be selected.)\\
6926 \LaTeX{}&
6927 \cs{def}\cs{setmfpicgraphic}\texttt{\#1}\marg{\cs{includegraphics}%
6928 \marg{\#1}}\\
6929 \pdfLaTeX{}&
6930 \cs{def}\cs{setmfpicgraphic}\texttt{\#1}\marg{\cs{includegraphics}%
6931 \marg{\#1}}\\
6932 \pdfTeX{}&
6933 \cs{def}\cs{setmfpicgraphic}\texttt{\#1}\marg{\cs{convertMPtoPDF}%
6934 \marg{\#1}\marg{1}\marg{1}}
6935 \end{tabular}
6936
6937 \medskip
6938 Moreover, since \MP{} by default writes files with numeric extensions,
6939 we add code to each figure, so that these graphics are correctly
6940 recognized as \EPS{} or \prog{MPS}. For example, to the figure with
6941 extension \file{.1}, we add the equivalent of one of the following
6942 \begin{itemize}
6943 \item[] \cs{DeclareGraphicsRule}\marg{.1}\marg{eps}\marg{.1}\marg{} in
6944 \LaTeXe{}.
6945 \item[] \cs{DeclareGraphicsRule}\marg{.1}\marg{mps}\marg{.1}\marg{} in
6946 \pdfLaTeX{}.
6947 \end{itemize}
6948
6949 After running the command \cs{setmfpicgraphic}, \mfp{} runs
6950 \cs{getmfpicoffset} to store the lower left corner of the bounding box
6951 of the figure in two macros \cs{mfpicllx} and \cs{mfpiclly}. All the
6952 above versions of \cs{setmfpicgraphic} (except \cs{includegraphics})
6953 make this information available; the definition of \cs{getmfpicoffset}
6954 merely copies it into these two macros. What \mfp{} does in the
6955 case of \cs{includegraphics} is to modify (locally) the definition of an
6956 internal command of the \prog{graphics} package so that it copies the
6957 information to those macros, and then \cs{getmfpicoffset} does nothing.
6958 This internal modification is accomplished by the macro
6959 \cs{preparemfpicgraphic}. Changes to \cs{setmfpicgraphic} might require
6960 changing either or both of \cs{preparemfpicgraphic} and
6961 \cs{getmfpicoffset}. All three of these commands are fed the graphic's
6962 file name as the only argument, although only \cs{setmfpicgraphic}
6963 currently does anything with it.
6964
6965 One possible reason for wanting to redefine \cs{setmfpicgraphic} might
6966 be to rescale all pictures. This is \emph{definitely not} a good idea. A
6967 good deal of \mfp{}'s figure placemant code assumes that the size of the
6968 figure is consistent with the coordinate system set up by the \cs{mfpic}
6969 command. With \opt{mplabels} plus \opt{truebbox} it might work, but
6970 (i)~it has \emph{not} been considered in writing the \mfp{} code,
6971 (ii)~it will then scale all the text as well as the figure, and (iii)~it
6972 will scale all line thickness, which should normally be a design choice
6973 independent of the size of a picture. To rescale all pictures, one need
6974 only change \cs{mfpicunit} and rerun \TeX{} and \MP{}.
6975
6976 A better reason might be to allow the conversion of your \MP{} figures
6977 to some other format. Then redefining \cs{setmfpicgraphic} could enable
6978 including the appropriate file in the appropriate format.
6979
6980 The filename argument mentioned above is actually the result obtained by
6981 running the macro \cs{setfilename}\index{setfilename@\cs{setfilename}}.
6982 The command \cs{setfilename} gets two arguments: the name of the \MP{}
6983 output file (set in the \cs{opengraphsfile} command) without extension,
6984 and the number of the picture. The default definition of
6985 \cs{setfilename} merely inserts a dot between the two arguments.%
6986 \footnote{Unless modified by \cs{setfilenametemplate}, of course.
6987 See subsection~\ref{misc}.}
6988 That is \cs{setfilename}\marg{fig}\marg{1} produces \file{fig.1}. You
6989 can redefine this behavior also. Any changes to \cs{setfilename} must
6990 come after the \mfp{} macros are input and before the
6991 \cs{opengraphsfile} command. Any changes to \cs{setmfpicgraphic} must
6992 come after the \mfp{} macros are input and before any \cs{mfpic}
6993 commands, but it is best to place it before the \cs{opengraphsfile}
6994 command.
6995
6996 As \mfp{} is currently written, \cs{setfilename} must be
6997 \emph{completely expandable}, which means it should contain no
6998 definitions, no assignments such as \cs{setcounter}, and no
6999 calculations.%
7000 \footnote{But appropriate use of \cs{numexpr} (in \eTeX) for
7001 calculations is probably OK.}
7002 To test whether a proposed definition is completely
7003 expandable, put
7004 \begin{verbatim}
7005 \message{***\setfilename{file}{1}***}
7006 \end{verbatim}
7007 after the definition in a \file{.tex} file and view the result on the
7008 terminal or in the \file{.log} file. You should see only your expected
7009 filename between the asterisks.
7010
7011
7012 \section{\prog{Mfpic} and the Rest of the World.}
7013
7014 \subsection{The literature}
7015
7016 This author has personal knowledge of one mathematical article
7017 which definitely uses \mfp{} to create diagrams, and that is this
7018 author's joint paper with J.~Duncan and C.~M.~McGregor: \textit{On the
7019 value of pi for norms in $\mathbf{R}^2$} in the College Mathematics
7020 Journal, vol.~35, pages 84--92. Oddly enough, it was McGregor and not I
7021 who chose to use \mfp{} for the illustrations.
7022
7023 There also exists a book that makes use of \mfp{}: \textit{Introduction
7024 to functional equations: theory and problem solving strategies for
7025 mathematical competitions and beyond} by Costas Efthimiou,
7026 MSRI/Mathematical Circles Library, vol. 6, 2011.
7027
7028 There are at least two major publications where \mfp{} has garnered more
7029 than a cursory mention. The most up-to-date is a section in \textit{The
7030 \LaTeX{} Graphics Companion} by Michel Goossens, Sebastian Rahtz and
7031 Frank Mittelbach. It describes a version prior to the introduction of
7032 \MP{} support, but it correctly describes a subset of its current
7033 commands and abilities. \textit{The \LaTeX{} Companion} (Second Edition)
7034 mentions \mfp{}, but only in its annotation of the bibliography entry
7035 for \textit{\TeX{} Unbound} (see below).
7036
7037 The other is \textit{\TeX{} Unbound} by Alan Hoenig, which contains a
7038 chapter on \mfp{}. Unfortunately, it describes a version that was
7039 replaced in 1996 with version 0.2.10.9. The following summarizes the
7040 differences between the description%
7041 \footnote{While I'm at it: \textit{\TeX{} Unbound} occasionally
7042 refers to \mfp{} using a logo-like formatting in which the `MF' is
7043 in a special font and the `I' is lowered. This `logo' may suggest
7044 a relationship between \mfp{} and \PiCTeX{}. There is no such
7045 relationship, and there is no official logo-like designation for
7046 \mfp{}.} %
7047 found in Chapter 15 and \mfp{} versions 0.2.10.9 through the
7048 current one:
7049
7050 \cs{wedge} is now renamed \cs{sector} to avoid conflict with the \TeX{}
7051 command of the same name. The syntax is slightly different from that
7052 given for \cs{wedge}:
7053 \begin{ex}
7054 \cs{sector}\marg{(\meta{x},\meta{y}), \meta{radius}, \meta{angle1},
7055 \meta{angle2}}
7056 \end{ex}
7057
7058 The macro \cs{plr}\marg{(\meta{$r_0$},\meta{$\theta_0$}),%
7059 (\meta{$r_1$},\meta{$\theta_1$}),$\ldots$} is now used to convert polar
7060 coordinate pairs to rectangular coordinates and the commands
7061 \cs{plrcurve}, \cs{plrcyclic}, \cs{plrlines} and \cs{plrpoint} were
7062 dropped from \mfp{}. Now use
7063 \begin{ex}
7064 \cs{curve}\marg{\cs{plr}\marg{(\meta{$r_0$},\meta{$\theta_0$}),%
7065 (\meta{$r_1$},\meta{$\theta_1$}),$\ldots$}}
7066 \end{ex}
7067 instead of
7068 \begin{ex}
7069 \cs{plrcurve}\marg{(\meta{$r_0$},\meta{$\theta_0$}),%
7070 (\meta{$r_1$},\meta{$\theta_1$}),$\ldots$}
7071 \end{ex}
7072 and similarly for \cs{plrcyclic}, \cs{plrlines} and \cs{plrpoint}.
7073
7074 \cs{fill} is now renamed \cs{gfill} to avoid conflict with the \LaTeX{}
7075 command of the same name.
7076
7077 \cs{rotate}, which rotates a following figure about a point, is now
7078 renamed \cs{rotatepath} to avoid confusion with a similar name for a
7079 transformation (see below).
7080
7081 \cs{white} is now renamed \cs{gclear} because \cs{white} is too likely
7082 to be chosen for, or confused with, a color command.
7083
7084 \smallskip
7085 The following affine transform commands were changed from a third person
7086 indicative form (which could be confused with a plural noun) to an
7087 imperative form:
7088
7089 \begin{ex}
7090 \begin{tabular}{@{}ll}
7091 Old name: & New name:\\
7092 \cs{boosts} & \cs{boost}\\
7093 \cs{reflectsabout} & \cs{reflectabout}\\
7094 \cs{rotatesaround} & \cs{rotatearound}\\
7095 \cs{rotates} & \cs{rotate}\\
7096 \cs{scales} & \cs{scale}\\
7097 \cs{shifts} & \cs{shift}\\
7098 \cs{xscales} & \cs{xscale}\\
7099 \cs{xslants} & \cs{xslant}\\
7100 \cs{xyswaps} & \cs{xyswap}\\
7101 \cs{yscales} & \cs{yscale}\\
7102 \cs{yslants} & \cs{yslant}\\
7103 \cs{zscales} & \cs{zscale}\\
7104 \cs{zslants} & \cs{zslant}
7105 \end{tabular}
7106 \end{ex}
7107
7108 \cs{caption} and \cs{label} are now renamed \cs{tcaption} and
7109 \cs{tlabel} to avoid conflict with the \LaTeX{} commands.
7110
7111 \cs{mfcmd} was renamed \cs{mfsrc} for clarity, and (in version 0.7) a
7112 new \cs{mfcmd} was defined, which is pretty much the same except it appends
7113 a semicolon to its argument.
7114
7115 \smallskip
7116 There is a misprint: \cs{axisheadlin} should be \cs{axisheadlen}.
7117
7118 Finally, the \LaTeX{} template on page 496 is no longer the only
7119 possiblity: recent \mfp{} may be loaded with \cs{usepackage}.
7120
7121
7122 \subsection{Other programs}
7123
7124 There exists a program, \prog{fig2mfpic} that produces \mfp{} code as
7125 output. The code produced (as of this writing) is somewhat old and
7126 mostly incompatible with the description in this manual. Fortunately, it
7127 is accompanied by the appropriate versions of files \file{mfpic.tex} and
7128 \file{grafbase.mf}. Unfortunately, the names conflict with the current
7129 filenames and so they should only be used in circumstances where no
7130 substitution will occur, say in a local directory together with the
7131 other sources for the document being produced. Moreover, the
7132 documentation in this manual may not apply to the code produced. However
7133 the information in \textit{\TeX{} Unbound} may apply.
7134
7135 There exist a package, \prog{circuit\_macros}, that can produce a
7136 variety of output formats, one of which is \mfp{} code. One writes a
7137 file (don't ask me what it consists of) and apparently processes it with
7138 \prog{m4} and then (perhaps) \prog{dpic} to produce the output. The
7139 \mfp{} code produced appears to be compatible with the current \mfp{}.
7140
7141 \renewcommand\mfpindexheading{%
7142 \section{Index of commands, options and parameters.}}
7143
7144 \let\oldcs\cs
7145 \renewcommand{\cs}[1]{\leavevmode\mytt{\llap{\char`\\}#1}}
7146
7147 \renewcommand\headingprefix[1]{\textbf{\large #1}}
7148 \InputIfFileExists{\jobname.ind}{}{\mfpindexheading}
7149
7150 \let\cs\oldcs
7151
7152 \columnseprule 0pt
7153 \columnsep 35pt
7154 \twocolumn[\section{List of commands by type.}]
7155 \parindent0pt
7156 \parskip0pt plus .3pt\relax
7157 \makeatletter
7158 \renewcommand\@idxitem{\par\hangindent 10\p@}
7159 \let\item\@idxitem
7160 \makeatother
7161
7162
7163 \subsection{Figures}
7164
7165 \item \cs{arc}, \pageref{arc}
7166 \item \cs{axis}, \pageref{axis}
7167 \item \cs{axisline}, \pageref{axisline}
7168 \item \cs{belowfcn}, \pageref{belowfcn}
7169 \item \cs{border}, \pageref{axisline}
7170 \item \cs{brownianmotion}, \pageref{brownianmotion}
7171 \item \cs{browniangraph}, \pageref{brownianmotion}
7172 \item \cs{btwnfcn}, \pageref{btwnfcn}
7173 \item \cs{btwnplrfcn}, \pageref{btwnfcn}
7174 \item \cs{cbeziers}, \cs{closedcbeziers}, \pageref{cbeziers}
7175 \item \cs{chartbar}, \pageref{chartbar}
7176 \item \cs{circle}, \pageref{circle}
7177 \item \cs{computedspline},\\
7178 \cs{closedcomputedspline}, \pageref{computedspline}
7179 \item \cs{convexcurve}, \cs{closedconvexcurve}, \pageref{convexcurve}
7180 \item \cs{convexcyclic}, \pageref{convexcurve}
7181 \item \cs{cspline}, \cs{closedcspline}, \pageref{qspline}
7182 \item \cs{curve}, \cs{closedcurve}, \pageref{curve}
7183 \item \cs{cyclic}, \pageref{curve}
7184 \item \cs{datafile}, \pageref{datafile}
7185 \item \cs{DEgraph}, \pageref{DEgraph}
7186 \item \cs{DEtrajectory}, \pageref{DEgraph}
7187 \item \cs{ellipse}, \pageref{ellipse}
7188 \item \cs{fcncurve}, \pageref{fcncurve}
7189 \item \cs{fcnspline}, \pageref{fcnspline}
7190 \item \cs{fullellipse}, \pageref{fullellipse}
7191 \item \cs{function}, \pageref{function}
7192 \item \cs{ganttbar}, \pageref{chartbar}
7193 \item \cs{gbrace}, \pageref{gbrace}
7194 \item \cs{graphbar}, \pageref{chartbar}
7195 \item \cs{halfellipse}, \pageref{fullellipse}
7196 \item \cs{histobar}, \pageref{chartbar}
7197 \item \cs{hypergeodesic}, \pageref{hypergeodesic}
7198 \item \cs{levelcurve}, \pageref{levelcurve}
7199 \item \cs{lines}, \pageref{polyline}
7200 \item \cs{mfbezier}, \cs{closedmfbezier}, \pageref{mfbezier}
7201 \item \cs{mfobj}, \cs{mpobj}, \pageref{mfobj}
7202 \item \cs{parafcn}, \pageref{parafcn}
7203 \item \cs{periodicfcnspline}, \pageref{fcnspline}
7204 \item \cs{piewedge}, \pageref{piewedge}
7205 \item \cs{plrfcn}, \pageref{plrfcn}
7206 \item \cs{plrregion}, \pageref{belowfcn}
7207 \item \cs{polygon}, \pageref{polygon}
7208 \item \cs{polyline}, \pageref{polyline}
7209 \item \cs{pshcircle}, \pageref{pshcircle}
7210 \item \cs{qbeziers}, \cs{closedqbeziers}, \pageref{qbeziers}
7211 \item \cs{quarterellipse}, \pageref{fullellipse}
7212 \item \cs{qspline}, \cs{closedqspline}, \pageref{qspline}
7213 \item \cs{randomwalk}, \pageref{brownianmotion}
7214 \item \cs{rect}, \pageref{rect}
7215 \item \cs{regpolygon}, \pageref{regpolygon}
7216 \item \cs{sector}, \pageref{sector}
7217 \item \cs{tlabelcircle}, \pageref{tlabelellipse}
7218 \item \cs{tlabelellipse}, \pageref{tlabelellipse}
7219 \item \cs{tlabeloval}, \pageref{tlabeloval}
7220 \item \cs{tlabelrect}, \pageref{tlabelrect}
7221 \item \cs{turtle}, \pageref{turtle}
7222
7223
7224 \subsection{Renderings}
7225
7226 \item \cs{areagradient}, \pageref{areagradient}
7227 \item \cs{corkscrew}, \pageref{corkscrew}
7228 \item \cs{dashed}, \pageref{dashed}
7229 \item \cs{dotted}, \pageref{dotted}
7230 \item \cs{doubledraw}, \pageref{doubledraw}
7231 \item \cs{draw}, \pageref{draw}
7232 \item \cs{gclear}, \pageref{gclear}
7233 \item \cs{gclip}, \pageref{gclip}
7234 \item \cs{gendashed}, \pageref{gendashed}
7235 \item \cs{gfill}, \pageref{gfill}
7236 \item \cs{gradient}, \pageref{gradient}
7237 \item \cs{hatch}, \pageref{hatch}
7238 \item \cs{lhatch}, \pageref{hatch}
7239 \item \cs{plot}, \pageref{plot}
7240 \item \cs{plotdata}, \pageref{plotdata}
7241 \item \cs{plotnodes}, \pageref{plotnodes}
7242 \item \cs{polkadot}, \pageref{polkadot}
7243 \item \cs{radialgradient}, \pageref{radialgradient}
7244 \item \cs{rhatch}, \pageref{hatch}
7245 \item \cs{sinewave}, \pageref{zigzag}
7246 \item \cs{shade}, \pageref{shade}
7247 \item \cs{tess}, \pageref{tess}
7248 \item \cs{thatch}, \pageref{thatch}
7249 \item \cs{xhatch}, \pageref{hatch}
7250 \item \cs{zigzag}, \pageref{zigzag}
7251
7252
7253 \subsection{Arrows}
7254
7255 \item \cs{arrow}, \pageref{arrow}
7256 \item \cs{arrowhead}, \pageref{arrowhead}
7257 \item \cs{arrowmid}, \pageref{arrowhead}
7258 \item \cs{arrowtail}, \pageref{arrowhead}
7259
7260
7261 \subsection{Modifying figures}
7262
7263 \item \cs{bclosed}, \pageref{lclosed}
7264 \item \cs{cbclosed}, \pageref{cbclosed}
7265 \item \cs{connect}, \cs{endconnect}, \pageref{connect}
7266 \item \cs{cutoffafter}, \pageref{cutoffafter}
7267 \item \cs{cutoffbefore}, \pageref{cutoffafter}
7268 \item \cs{interpolatepath}, \pageref{interpolatepath}
7269 \item \cs{lclosed}, \pageref{lclosed}
7270 \item \cs{makesector}, \pageref{makesector}
7271 \item \cs{parallelpath}, \pageref{parallelpath}
7272 \item \cs{partpath}, \pageref{partpath}
7273 \item \cs{qbclosed}, \pageref{cbclosed}
7274 \item \cs{randomizepath}, \pageref{random}
7275 \item \cs{randomlines}, \pageref{random}
7276 \item \cs{reflectpath}, \pageref{shiftpath}
7277 \item \cs{reverse}, \pageref{reverse}
7278 \item \cs{reversepath}, \pageref{reverse}
7279 \item \cs{rotatepath}, \pageref{shiftpath}
7280 \item \cs{scalepath}, \pageref{shiftpath}
7281 \item \cs{sclosed}, \pageref{lclosed}
7282 \item \cs{shiftpath}, \pageref{shiftpath}
7283 \item \cs{slantpath}, \pageref{shiftpath}
7284 \item \cs{subpath}, \pageref{partpath}
7285 \item \cs{transformpath}, \pageref{shiftpath}
7286 \item \cs{trimpath}, \pageref{partpath}
7287 \item \cs{xscalepath}, \pageref{shiftpath}
7288 \item \cs{xslantpath}, \pageref{shiftpath}
7289 \item \cs{xyswappath}, \pageref{shiftpath}
7290 \item \cs{yscalepath}, \pageref{shiftpath}
7291 \item \cs{yslantpath}, \pageref{shiftpath}
7292
7293
7294 \subsection{Lengths}
7295
7296 \item \cs{axisheadlen}, \pageref{axisheadlen}
7297 \item \cs{dashlen}, \pageref{dashlen}
7298 \item \cs{dotsize}, \pageref{dotsize}
7299 \item \cs{dotspace}, \pageref{dotsize}
7300 \item \cs{griddotsize}, \pageref{griddotsize}
7301 \item \cs{hashlen}, \pageref{hashlen}
7302 \item \cs{hatchspace}, \pageref{hatchspace}
7303 \item \cs{headlen}, \pageref{headlen}
7304 \item \cs{mfpiccaptionskip}, \pageref{mfpiccaptionskip}
7305 \item \cs{mfpicheight}, \pageref{mfpicheight}
7306 \item \cs{mfpicunit}, \pageref{mfpicunit}
7307 \item \cs{mfpicwidth}, \pageref{mfpicheight}
7308 \item \cs{pointsize}, \pageref{pointsize}
7309 \item \cs{polkadotspace}, \pageref{polkadotspace}
7310 \item \cs{shadespace}, \pageref{shadespace}
7311 \item \cs{sideheadlen}, \pageref{sideheadlen}
7312 \item \cs{symbolspace}, \pageref{symbolspace}
7313
7314
7315 \subsection{Coordinate transformation}
7316
7317 \item \cs{applyT}, \pageref{applyT}
7318 \item \cs{boost}, \pageref{applyT}
7319 \item \cs{coords}, \cs{endcoords}, \pageref{coords}
7320 \item \cs{mirror}, \pageref{applyT}
7321 \item \cs{reflectabout}, \pageref{applyT}
7322 \item \cs{rotate}, \pageref{applyT}
7323 \item \cs{rotatearound}, \pageref{applyT}
7324 \item \cs{scale}, \pageref{applyT}
7325 \item \cs{shift}, \pageref{applyT}
7326 \item \cs{turn}, \pageref{applyT}
7327 \item \cs{xscale}, \pageref{applyT}
7328 \item \cs{xslant}, \pageref{applyT}
7329 \item \cs{xyswap}, \pageref{applyT}
7330 \item \cs{yscale}, \pageref{applyT}
7331 \item \cs{yslant}, \pageref{applyT}
7332 \item \cs{zscale}, \pageref{applyT}
7333 \item \cs{zslant}, \pageref{applyT}
7334
7335
7336 \subsection{Symbols, axes, grids, marks}
7337
7338 \item \cs{axes}, \pageref{axes}
7339 \item \cs{axis}, \pageref{axis}
7340 \item \cs{axismarks}, \pageref{axismarks}
7341 \item \cs{bmarks}, \pageref{axismarks}
7342 \item \cs{doaxes}, \pageref{axis}
7343 \item \cs{grid}, \pageref{grid}
7344 \item \cs{gridarcs}, \pageref{plrgrid}
7345 \item \cs{gridlines}, \pageref{grid}
7346 \item \cs{gridpoints}, \pageref{grid}
7347 \item \cs{gridrays}, \pageref{plrgrid}
7348 \item \cs{hgridlines}, \pageref{grid}
7349 \item \cs{lattice}, \pageref{grid}
7350 \item \cs{lmarks}, \pageref{axismarks}
7351 \item \cs{plotsymbol}, \pageref{plotsymbol}
7352 \item \cs{plrgridpoints}, \pageref{plrgrid}
7353 \item \cs{plrgrid}, \pageref{plrgrid}
7354 \item \cs{plrpatch}, \pageref{plrgrid}
7355 \item \cs{plrvectorfield}, \pageref{vectorfield}
7356 \item \cs{point}, \pageref{point}
7357 \item \cs{putmfpimage}, \pageref{putmfpimage}
7358 \item \cs{rmarks}, \pageref{axismarks}
7359 \item \cs{tmarks}, \pageref{axismarks}
7360 \item \cs{vectorfield}, \pageref{vectorfield}
7361 \item \cs{vgridlines}, \pageref{grid}
7362 \item \cs{xaxis}, \pageref{axes}
7363 \item \cs{xmarks}, \pageref{axismarks}
7364 \item \cs{yaxis}, \pageref{axes}
7365 \item \cs{ymarks}, \pageref{axismarks}
7366
7367
7368 \subsection{Symbol names}
7369
7370 \item \gbc{Arrowhead}, \pageref{arrowhead}
7371 \item \gbc{Asterisk}, \pageref{plotsymbol}
7372 \item \gbc{Circle}, \pageref{plotsymbol}
7373 \item \gbc{Crossbar}, \pageref{arrowhead}
7374 \item \gbc{Cross}, \pageref{plotsymbol}
7375 \item \gbc{Diamond}, \pageref{plotsymbol}
7376 \item \gbc{Leftbar}, \pageref{arrowhead}
7377 \item \gbc{Leftharpoon}, \pageref{arrowhead}
7378 \item \gbc{Lefthook}, \pageref{arrowhead}
7379 \item \gbc{Plus}, \pageref{plotsymbol}
7380 \item \gbc{Rightbar}, \pageref{arrowhead}
7381 \item \gbc{Rightharpoon}, \pageref{arrowhead}
7382 \item \gbc{Righthook}, \pageref{arrowhead}
7383 \item \gbc{SolidCircle}, \pageref{plotsymbol}
7384 \item \gbc{SolidDiamond}, \pageref{plotsymbol}
7385 \item \gbc{SolidSquare}, \pageref{plotsymbol}
7386 \item \gbc{SolidStar}, \pageref{plotsymbol}
7387 \item \gbc{SolidTriangle}, \pageref{plotsymbol}
7388 \item \gbc{Square}, \pageref{plotsymbol}
7389 \item \gbc{Star}, \pageref{plotsymbol}
7390 \item \gbc{Triangle}, \pageref{plotsymbol}
7391
7392
7393 \subsection{Setting options}
7394
7395 \item \cs{clearsymbols}, \pageref{clearsymbols}
7396 \item \cs{clipmfpic}, \pageref{clip}
7397 \item \cs{mfpicdebugfalse}, \pageref{debug}
7398 \item \cs{mfpicdebugtrue}, \pageref{debug}
7399 \item \cs{mfpicdraft}, \pageref{draft}
7400 \item \cs{mfpicfinal}, \pageref{draft}
7401 \item \cs{mfpicnowrite}, \pageref{draft}
7402 \item \cs{mfpreadlog}, \pageref{readlog}
7403 \item \cs{nocenteredcaptions}, \pageref{centeredcaptions}
7404 \item \cs{noclearsymbols}, \pageref{clearsymbols}
7405 \item \cs{noclipmfpic}, \pageref{clip}
7406 \item \cs{nomplabels}, \pageref{mplabels}
7407 \item \cs{nooverlaylabels}, \pageref{overlaylabels}
7408 \item \cs{noraggedcaptions}, \pageref{raggedcaptions}
7409 \item \cs{notruebbox}, \pageref{truebbox}
7410 \item \cs{overlaylabels}, \pageref{overlaylabels}
7411 \item \cs{usecenteredcaptions}, \pageref{centeredcaptions}
7412 \item \cs{usemetafont}, \pageref{metapost}
7413 \item \cs{usemetapost}, \pageref{metapost}
7414 \item \cs{usemplabels}, \pageref{mplabels}
7415 \item \cs{useraggedcaptions}, \pageref{raggedcaptions}
7416 \item \cs{usetruebbox}, \pageref{truebbox}
7417
7418
7419 \subsection{Setting values}
7420
7421 \item \cs{axismargin}, \pageref{axismargin}
7422 \item \cs{darkershade}, \pageref{darkershade}
7423 \item \cs{dashlineset}, \pageref{dashlineset}
7424 \item \cs{dashpattern}, \pageref{dashpattern}
7425 \item \cs{dotlineset}, \pageref{dashlineset}
7426 \item \cs{drawpen}, \pageref{drawpen}
7427 \item \cs{globalsetmfvariable}, \pageref{setmfvariable}
7428 \item \cs{hatchwd}, \pageref{hatchwd}
7429 \item \cs{headshape}, \pageref{headshape}
7430 \item \cs{lightershade}, \pageref{darkershade}
7431 \item \cs{mfpicnumber}, \pageref{mfpicnumber}
7432 \item \cs{mfplinestyle}, \pageref{mfplinetype}
7433 \item \cs{mfplinetype}, \pageref{mfplinetype}
7434 \item \cs{pen}, \pageref{drawpen}
7435 \item \cs{penwd}, \pageref{drawpen}
7436 \item \cs{polkadotwd}, \pageref{polkadotwd}
7437 \item \cs{setallaxismargins}, \pageref{axismargin}
7438 \item \cs{setallbordermarks}, \pageref{setaxismarks}
7439 \item \cs{setaxismargins}, \pageref{axismargin}
7440 \item \cs{setaxismarks}, \pageref{setaxismarks}
7441 \item \cs{setbordermarks}, \pageref{setaxismarks}
7442 \item \cs{setmfboolean}, \pageref{setmfvariable}
7443 \item \cs{setmfcolor}, \pageref{setmfvariable}
7444 \item \cs{setmfnumeric}, \pageref{setmfvariable}
7445 \item \cs{setmfpair}, \pageref{setmfvariable}
7446 \item \cs{setmfvariable}, \pageref{setmfvariable}
7447 \item \cs{settension}, \pageref{settension}
7448 \item \cs{setxmarks}, \pageref{setaxismarks}
7449 \item \cs{setymarks}, \pageref{setaxismarks}
7450 \item \cs{shadewd}, \pageref{shadewd}
7451
7452
7453 \subsection{Setting colors}
7454
7455 \item \cs{backgroundcolor}, \pageref{drawcolor}
7456 \item \cs{drawcolor}, \pageref{drawcolor}
7457 \item \cs{fillcolor}, \pageref{drawcolor}
7458 \item \cs{hatchcolor}, \pageref{drawcolor}
7459 \item \cs{headcolor}, \pageref{drawcolor}
7460 \item \cs{mfpdefinecolor}, \pageref{mfpdefinecolor}
7461 \item \cs{pointcolor}, \pageref{drawcolor}
7462 \item \cs{tlabelcolor}, \pageref{drawcolor}
7463
7464
7465 \subsection{Defining arrays}
7466
7467 \item \cs{barchart}, \pageref{barchart}
7468 \item \cs{bargraph}, \pageref{barchart}
7469 \item \cs{colorarray}, \pageref{setarray}
7470 \item \cs{gantt}, \pageref{barchart}
7471 \item \cs{globalsetarray}, \pageref{setarray}
7472 \item \cs{histogram}, \pageref{barchart}
7473 \item \cs{mfpbarchart}, \pageref{barchart}
7474 \item \cs{mfpbargraph}, \pageref{barchart}
7475 \item \cs{mfpgantt}, \pageref{barchart}
7476 \item \cs{mfphistogram}, \pageref{barchart}
7477 \item \cs{mfppiechart}, \pageref{piechart}
7478 \item \cs{numericarray}, \pageref{setarray}
7479 \item \cs{pairarray}, \pageref{setarray}
7480 \item \cs{patharr}, \cs{endpatharr}, \pageref{patharr}
7481 \item \cs{piechart}, \pageref{piechart}
7482 \item \cs{setarray}, \pageref{setarray}
7483
7484
7485 \subsection{Changing behavior}
7486
7487 \item \cs{coloredlines}, \pageref{coloredlines}
7488 \item \cs{dashedlines}, \pageref{coloredlines}
7489 \item \cs{datapointsonly}, \pageref{coloredlines}
7490 \item \cs{defaultplot}, \pageref{defaultplot}
7491 \item \cs{everytlabel}, \pageref{everytlabel}
7492 \item \cs{everymfpic}, \cs{everyendmfpic}, \pageref{everymfpic}
7493 \item \cs{makepercentcomment}, \pageref{makepercentother}
7494 \item \cs{makepercentother}, \pageref{makepercentother}
7495 \item \cs{mfpdatacomment}, \pageref{mfpdatacomment}
7496 \item \cs{mfpdataperline}, \pageref{mfpdataperline}
7497 \item \cs{mfpverbtex}, \pageref{mfpverbtex}
7498 \item \cs{noship}, \pageref{noship}
7499 \item \cs{pointedlines}, \pageref{coloredlines}
7500 \item \cs{pointfillfalse}, \cs{pointfilltrue}, \pageref{pointfilltrue}
7501 \item \cs{reconfigureplot}, \pageref{reconfigureplot}
7502 \item \cs{resumeshipping}, \pageref{noship}
7503 \item \cs{setrender}, \pageref{setrender}
7504 \item \cs{smoothdata}, \pageref{datafile}
7505 \item \cs{stopshipping}, \pageref{noship}
7506 \item \cs{tlabeljustify}, \pageref{tlabeljustify}
7507 \item \cs{tlabeloffset}, \pageref{tlabeloffset}
7508 \item \cs{tlabelsep}, \pageref{tlabeloffset}
7509 \item \cs{tlpathjustify}, \pageref{tlpathjustify}
7510 \item \cs{tlpathsep}, \pageref{tlabeloffset}
7511 \item \cs{tlpointsep}, \pageref{tlabeloffset}
7512 \item \cs{unsmoothdata}, \pageref{datafile}
7513 \item \cs{using}, \pageref{using}
7514 \item \cs{usingnumericdefault}, \pageref{usingpairdefault}
7515 \item \cs{usingpairdefault}, \pageref{usingpairdefault}
7516
7517
7518 \subsection{Files and environments}
7519
7520 \item \cs{closegraphsfile}, \pageref{opengraphsfile}
7521 \item \cs{mfpframe}, \cs{endmfpframe}, \pageref{mfpframe}
7522 \item \cs{mfpic}, \cs{endmfpic}, \pageref{mfpic}
7523 \item \cs{opengraphsfile}, \pageref{opengraphsfile}
7524 \item \cs{setfilename}, \pageref{setfilename}
7525 \item \cs{setfilenametemplate}, \pageref{setfilenametemplate}
7526
7527
7528 \subsection{Text}
7529
7530 \item \cs{axislabels}, \pageref{axislabels}
7531 \item \cs{plottext}, \pageref{plottext}
7532 \item \cs{startbacktext}, \pageref{backtext}
7533 \item \cs{stopbacktext}, \pageref{backtext}
7534 \item \cs{tcaption}, \pageref{tcaption}
7535 \item \cs{tlabel}, \pageref{tlabel}
7536 \item \cs{tlabels}, \pageref{tlabel}
7537
7538
7539 \subsection{Miscellaneous}
7540
7541 \item \cs{assignmfvalue}, \cs{assignmpvalue}, \pageref{assignmfvalue}
7542 \item \cs{fdef}, \pageref{fdef}
7543 \item \cs{getmfpicoffset}, \pageref{getmfpicoffset}
7544 \item \cs{globalassignmfvalue},\\
7545 \cs{globalassignmpvalue}, \pageref{assignmfvalue}
7546 \item \cs{ifmfpmpost}, \pageref{ifmfpmpost}
7547 \item \cs{mfcmd}, \pageref{mfsrc}
7548 \item \cs{mflist}, \pageref{mfsrc}
7549 \item \cs{mfmode}, \pageref{mfmode}
7550 \item \cs{mfpfor}, \cs{endmfpfor}, \pageref{mfpfor}
7551 \item \cs{mfpframed}, \pageref{mfpframe}
7552 \item \cs{mfpicversion}, \pageref{mfpicversion}
7553 \item \cs{mfpimage}, \cs{endmfpimage}, \pageref{mfpimage}
7554 \item \cs{mfploop}, \cs{endmfploop}, \pageref{mfploop}
7555 \item \cs{mfpuntil}, \pageref{mfploop}
7556 \item \cs{mfpwhile}, \cs{endmfpwhile}, \pageref{mfpwhile}
7557 \item \cs{mfresolution}, \pageref{mfmode}
7558 \item \cs{mfsrc}, \pageref{mfsrc}
7559 \item \cs{mftitle}, \pageref{mftitle}
7560 \item \cs{newfdim}, \pageref{newfdim}
7561 \item \cs{newsavepic}, \pageref{newsavepic}
7562 \item \cs{plr}, \pageref{plr}
7563 \item \cs{pointdef}, \pageref{pointdef}
7564 \item \cs{preparemfpicgraphic}, \pageref{preparemfpicgraphic}
7565 \item \cs{savepic}, \pageref{newsavepic}
7566 \item \cs{sequence}, \pageref{sequence}
7567 \item \cs{setmfpicgraphic}, \pageref{setmfpicgraphic}
7568 \item \cs{store}, \pageref{store}
7569 \item \cs{tile}, \cs{endtile}, \pageref{tile}
7570 \item \cs{tmtitle}, \pageref{tmtitle}
7571 \item \cs{usepic}, \pageref{newsavepic}
7572
7573
7574 \end{document}
7575