diff options
Diffstat (limited to 'Master/texmf-dist/doc/generic/mfpic/mfpic-doc.tex')
-rw-r--r-- | Master/texmf-dist/doc/generic/mfpic/mfpic-doc.tex | 7123 |
1 files changed, 7123 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/generic/mfpic/mfpic-doc.tex b/Master/texmf-dist/doc/generic/mfpic/mfpic-doc.tex new file mode 100644 index 00000000000..bee22641385 --- /dev/null +++ b/Master/texmf-dist/doc/generic/mfpic/mfpic-doc.tex @@ -0,0 +1,7123 @@ +%%% File: mfpic-doc.tex +%%% A part of mfpic 1.00 2009/09/22 +%%% +% Documentation of mfpic macros +\documentclass[letterpaper]{article} + +% Fonts: TimesRoman, CM Sans serif, and LuxiMono for TeX commands. +\usepackage[T1]{fontenc} +\usepackage{mathptmx} +\usepackage[scaled=.85]{luximono} +\renewcommand\sfdefault{cmss} +\newcommand\sgn{\mathop{\mathrm{sgn}}\nolimits} +% Fake chapters (really sections): +\usepackage[chapters]{mfpdoc} +\pagestyle{mfpdoc} + +\usepackage{makeidx} +\makeindex + +\usepackage{graphics} + +\ifpdf +\expandafter\usepackage\expandafter + [\mfpHyOpts,pdfpagelabels=true,hyperindex]{hyperref} +\expandafter\pdfstringdefDisableCommands\expandafter + {\mfpHyDisable} +\fi + +\stepcounter{secnumdepth} + +\title{\Mfp{}: Pictures in \TeX{}\\ with Metafont and +MetaPost\thanks{Copywrite 2002--2006, Daniel H. Luecking}} + + +\author{% +Daniel H. Luecking% + \thanks{\email {luecking@uark.edu}: Communications regarding \mfp{} + should be sent to this author. Any first-person references in this + manual refer to Dr.~Luecking.} +\and Dr Thomas E. Leathrum +\and Geoffrey Tobin} + +\date{\mfpdate} + +\begin{document} + +\pagenumbering{roman} +\maketitle +\tableofcontents + +\clearpage +\pagenumbering{arabic} + +\chapter{Introduction}\label{introduction} +\thispagestyle{plain} + +\section{Why?}\label{why} + +Tom got the idea for \mfp{}% + \footnote{`\Mfp{}' is pronounced by spelling the first two letters: + `em-eff-pick'.} +mostly out of a feeling of frustration. Different output mechanisms for +printing or viewing \TeX{} DVI files each have their own ways to include +pictures. More often than not, there are provisions for including +graphic objects into a \prog{DVI} file using \TeX{} \cs{special}'s. +However, this technique seemed far from \TeX{}'s ideal of device +independence because different \TeX{} output drivers recognize different +\cs{special's}, and handle them in different ways. + +\LaTeX{}'s \env{picture} environment has a hopelessly limited supply of +available objects to draw---if you want to draw a graph of a polynomial +curve, you're out of luck. + +There was, of course, \PiCTeX{}, which was wonderfully flexible and +general, but its most obvious feature was its speed---or rather lack of +it. Processing a single picture in \PiCTeX{} (in those days) could often +take several seconds. + +It occurred to Tom that it might be possible to take advantage of the +fact that \MF{} is \emph{designed} for drawing things. The result of +pursuing this idea was \mfp{}, a set of macros for \TeX{} and +\MF{} which incorporate \MF{}-drawn pictures into a \TeX{} file. + +With the creation of \MP{} by John Hobby, and the almost universal +availability of free \PS{} interpreters like \GS, some \mfp{} users +wanted to run their \mfp{} output through \MP{}, to produce \PS{} +pictures. Moreover, users wanted to be able to use \pdfTeX{}, which did +not get along well with PK fonts, but was quite happy with \MP{} +pictures. So \MP{} support was added to \mfp{}. This got us a little bit +away from device independence, but many users were not much concerned +with that: they just wanted a convenient way to have text and pictures +described in the same document file. + +With the extra capabilities of \PS{} (e.g., color) and the corresponding +abilities of \MP{}, there was a demand for some \mfp{} interface to +access them. Consequently, switches (options) have been added to access +some of them. When these are used, output files may no longer be +compatible with \MF{}. + +\section{Who?}\label{author} + +The original \mfp{} (and still the core of the current version) was written +primarily by Tom Leathrum during the late (northern hemisphere) spring +and summer of 1992, while at Dartmouth College. Different versions were +being written and tested for nearly two years after that, during which +time Tom finished his Ph.D. and took a job at Berry College, in Rome, +GA. Between fall of 1992 and fall of 1993, much of the development was +carried out by others. Those who helped most in this process are +credited in the Acknowledgements. + +Somewhere in the mid 1990's the development passed to Geoffrey Tobin who +kept things going for several years. + +The addition of \MP{} support was carried out by Dan Luecking around +1997--99. He is also responsible for all other additions and changes +since then, with help from Geoffrey and a few others mentioned in the +Acknowledgements. + +\section{What?}\label{manifest} + +See the \file{README} file for a list of files in the distribution and a +brief explanation of each. Only four are actually needed for full access +to \mfp{}'s capabilities: \file{mfpic.dtx}, \file{mfpic.ins}, +\file{grafbase.dtx} and \file{mfppatch.tex}. Running \LaTeX{} on +\file{mfpic.ins} creates the only required files: +\begin{display} + \file{mfpic.tex} and \file{mfpic.sty}, the latter required only for + \LaTeX{}.\\ + \file{grafbase.mf}, required only if \MF{} will be processing + figures.\\ + \file{grafbase.mp} and \file{dvipsnam.mp}, needed only if \MP{} will + be the processor.\\ + \file{mfppatch.tex} is used to distribute simple bug fixes. It does + nothing after a major update, but if it is not installed and a + previous one is, a warning will be issued. +\end{display} +The README file also gives some guidence on the proper location for the +installation of these files. + +\section{How?}\label{process} + +Some guidance on writing files that contain \mfp{} figures can be found +in the accompanying file \file{mfpguide.pdf}. If you use \mfp{} to +produce \MP{} figures the process is straightforward: run \TeX{} (or +\LaTeX), then \MP{}, then \TeX{} again. If there are no errors, then +\prog{dvips} or other DVI-to-PS converter can be run to produce +viewable\slash printable output. You can also run \prog{dvipdfm(x)} to obtain PDF +output, or even use \pdfTeX{} instead of \TeX{} (or \pdfLaTeX{} instead +of \LaTeX{}) to get PDF output directly. + +Here is an example of the process: for the sample file +\file{pictures.tex}, first run \TeX{} on it (or run \LaTeX{} on +\file{lapictures.tex}). You may see a message from \mfp{} that there is +no file \file{pics.1}, but \TeX{} will continue processing the file +anyway. When \TeX{} is finished, you will now have a file called +\file{pics.mp}. This is the \MP{} file containing the descriptions of +the pictures for \file{pictures.tex}. You need to run \MP{} on +\file{pics.mp} (Read your \MF{} manual to see how to do +this.% + \footnote{The document \textit{Some experiences on running Metafont + and MetaPost}, by Peter Wilson, can be useful for beginners. Fetch + \file{CTAN/info/metafp.pdf}. `\file{CTAN}' means the Comprehensive + \TeX{} Archive Network. You can find the mirror nearest you by + pointing your browser at \file{http://www.ctan.org/}.}) % +Typically, you just type +\begin{verbatim} +mpost pics.mp +\end{verbatim} +(or possibly "\verb$mp pics.mp$", but try \verb$mpost$ first). + +This produces files \file{pics.1}, \file{pics.2}, etc., the number of +files depending on the version of \file{pictures.tex}. You then +reprocess \file{pictures.tex} with \TeX{} to produce a DVI file. This +file can then be processed with \prog{dvips} (for example) to produce +\PS{} output which can be printed or viewed. One can also process the +DVI with \prog{dvipdfm(x)} to produce a PDF file. + +If \pdfTeX{} is used instead of \TeX{} on the second run, you should be +able to view the resulting PDF file immediately, without any further +processing. + +If instead you use \mfp{} to produce \MF{} figures, things are a little +less straightforward. The process is \TeX{}, then \MF{}, then +\prog{gftopk}, then \TeX{} again. After this, \TeX{}'s DVI output ought +to be viewable and printable by most DVI viewers or printer drivers. For +a few \TeX{} systems there may be some prior setup needed. One needs to +convince \TeX{} and its output drivers to find \MF{}'s output files. You +should do whatever is necessary (perhaps nothing!) to insure that \TeX{} +looks in the current directory for \file{.tfm} files, and that your DVI +drivers look in the current directory for \file{.pk} files. There may +also be some setup needed to ensure that the \file{.pk} files are +created at a resolution that matches that of your printer and of your DVI +viewer. See the discussion in \file{mfpguide.pdf}. + +If you want to test this process on the supplied sample files, edit +\file{pictures.tex} removing the \cs{usemetapost} command (or edit +\file{lapictures.tex}, removing the \opt{metapost} option). After that, +run \TeX{} on \file{pictures.tex} (or run \LaTeX{} on +\file{lapictures.tex}). You may see a message from \mfp{} that there is +no file \file{pics.tfm}, but \TeX{} will continue processing the file. +When \TeX{} is finished, you will now have a file called \file{pics.mf}. +This is the \MF{} file containing the descriptions of the pictures for +\file{pictures.tex}. You need to run \MF{} on \file{pics.mf}, with +\texttt{mode:=localfont} set up. +(Read your \MF{} manual to see how to do this.% + \footnote{If you are new to running \MF{}, the document + \textit{Metafont for Beginners}, by Geoffrey~Tobin, is a good + start. Fetch \file{CTAN/info/metafont-for-beginners.tex}.}) % +Typically, you just type +\begin{verbatim} +mf pics.mf +\end{verbatim} +or, to use a particular printer mode such as \texttt{ljfour}, possibly +something like +\begin{verbatim} +mf '\mode:=ljfour; input pics.mf' +\end{verbatim} +This produces a \file{pics.tfm} file and a GF file with a name something +like \file{pics.600gf}. The actual number may be different and the +extension may get truncated on some file systems. Then you run +\prog{gftopk} on the GF file to produce a PK font file. (Read your +\prog{gftopk} manual on how to do this.) Typically, you just run +\begin{verbatim} +gftopk pics.600gf +\end{verbatim} +(or possibly ``\verb$gftopk pics.600gf pics.600pk$'' or +``\verb$gftopk pics.600gf pics.pk$''). + +Now that you have the font (the \file{.pk} file) and font metric file (the +\file{.tfm}) generated by \MF{}, reprocess the file \file{pictures.tex} +with \TeX{}. The resulting DVI file should now be complete, and you should +be able to print and view it at your computer (assuming your viewer and +print driver have been set up to be able to find the PK font generated +from \file{pics.mf}). + +It is not advisable to rely on automatic font generation to create the +\file{.tfm} and \file{.pk} files. (Different systems do this in +different ways, so here I will try to give a generic explanation.) The +reason: later editing of a figure will require new files to be built, +and most automatic systems will \emph{not} remake the files once they +have been created. This is not so much a problem with the \file{.tfm}, +because \mfp{} never tries to load the font if the \file{.tfm} is absent +and therefore no automatic \file{.tfm}-making should ever be triggered. +However, if you forget to run \prog{gftopk}, then try to view your +resulting file, you may have to search your system and delete some +automatically generated \file{.pk} file (they can turn up in far-away +places) before you can see any later changes. It might be wise to write +a shell script (batch file) that runs both \MF{} and \prog{gftopk}. It +should also do some error checking and delete the \file{.tfm} if the +\file{.pk} file is not produced. That way, if anything goes wrong, the +\file{.dvi} will not contain the font (\mfp{} will draw a rectangle and +the figure number in place of the figure). + +These processing steps---processing with \TeX{}, processing with +\MF{}\slash\prog{gftopk} or \MP{}, and reprocessing with \TeX{}---may not always be +necessary. In particular, if you change the \TeX{} document without +making any changes at all to the pictures, then there will be no need to +repeat the \MF{} or \MP{} steps. + +There are also somewhat subtle circumstance under which you can skip the +second \TeX{} step after editing a figure if the file has already gone +through the above process. Delineating the exact cirumstances is rather +involved, so it is recommended that you always repeat the \TeX{} step if +you have made changes that affect any figure. + +What makes \mfp{} work? When you run \TeX{} on the file +\file{pictures.tex}, the \mfp{} macros issue \TeX{} \cs{write} commands, +writing \MF{} (or \MP{}) commands to a file \file{pics.mf} (or +\file{pics.mp}). The user should never have to read or change the file +\file{pics.mf} directly---the \mfp{} macros take care of it. + +The enterprising user can determine by examining the \mfp{} source and +the resulting \file{.mf} or \file{.mp} file, that \mfp{} drawing macros +translate almost directly into similar \MF{}\slash\MP{} commands, +defined in one of the files \file{grafbase.mf} or \file{grafbase.mp}. +The labels and captions, however, are placed on the graph by \TeX{} +using box placement techniques similar to those used in \LaTeX{}'s +\env{picture} environment (except when option \opt{mplabels} is in +effect, in which case the labels are written to the \file{.mp} file and +handled by \MP{}). + +\smallskip +\emph{Note}: In this manual, when describing \mfp{} operations, we will +often refer to ``\MF{}'' when we really mean ``\MF{} or \MP{}''. This +will especially be the case whenever we need to refer to commands in the +two languages which are substantially the same, but occasionally we will +even talk about ``running \MF{}'' when we mean running one or the other +program \texttt{mf} or \texttt{mpost} to process the figures. If we need +to discriminate between the two processors, (for example when they have +different behavior) we will make the difference explicit. + +A similar shorthand is used when referring to ``\TeX{}''. It should not be +taken to mean ``plain \TeX{}'', but rather whatever version of \TeX{} is used +to process the source file: plain \TeX{}, \LaTeX{}, \pdfTeX{}, or +\pdfLaTeX{}. Also \AmSTeX{}, \prog{eplain} and some other variants. When +last tried, \mfp{} didn't work with \ConTeXt{}. + +\clearpage +\chapter{Options.}\label{options} + +There are several options to the \mfp{} package. These options can be +turned on with certain provided commands, but under \LaTeX{} they can +also be used in the standard \LaTeX{} \cs{usepackage} optional argument. +Some options can be switched off and on throughout the document. Here we +merely list them and provide a general description of their purpose. +More details may be found later in the discussion of the features +affected. The headings below give the option name, the alternative macro +and, if available, the command for turning off the option. Any option +in the \cs{usepackage} command not among those given below will be +passed on to the \prog{graphics} package, provided the \opt{metapost} +option has been used. + +If the file \file{mfpic.cfg} exists, it will be input just before all +options are processed. You can create such a file containing an +\cs{ExecuteOptions} command to execute any options you would like to +have as default. Actual options to \cs{usepackage} will override these +defaults, of course. And so will any of the commands below. + +If a file named \file{mfpic.usr} can be found, it will be input at the +end of the loading of \mfp{}. The user can create such a file containing +any of the commands of this section that he would like to have as +default. + +Finally, if the file \file{mfppatch.tex} can be found, it will be input +slightly before the end of loading \mfp{}. It is part of the \mfp{} +distribution, and will be used to implement minor corrections when bugs +are found. The user should \emph{not} modify this file unless +he really knows what he is doing. + +\section{\opt{metapost}, \opt{metafont}, \cs{usemetapost}, \cs{usemetafont}.}% +\label{metapost}\index{metapost@\opt{metapost}}\index{usemetapost@\cs{usemetapost}}% +\index{metafont@\opt{metafont}}\index{usemetafont@\cs{usemetafont}} + +The option \opt{metapost} or the command \cs{usemetapost} selects \MP{} +as the figure processor and makes specific features available. It +changes the extension used on the output file to `\file{.mp}' to signal +that it can no longer be processed with \MF{}. There is also a +\opt{metafont} option (command \cs{usemetafont}), but it is redundant, +as \MF{} is the default (for backward compatibility of files written +before \MP{} existed). Either command must come before the +\cs{opengraphsfile} command (see section~\ref{files}). They should not +be used together in the same document. (Actually they can, but one needs +to close one output file and open another. Moreover, it hasn't ever been +seriously tested, and it wasn't taken into consideration in writing most +of the macros.) If the command form \cs{usemetapost} is used in a +\LaTeXe{} document, it must come in the preamble. Because of the timing +of actions by the \prog{babel} package and by older versions of +\file{supp-pdf.tex} (input by \file{pdftex.def} in the \prog{graphics} +package), when \pdfLaTeX{} is used, \mfp{} should be loaded and +\cs{usemetapost} (if used) declared before \prog{babel} is loaded. + + +\section{\opt{mplabels}, \cs{usemplabels}, +\cs{nomplabels}.}\label{mplabels} +\index{mplabels@\opt{mplabels}}% +\index{usemplabels@\cs{usemplabels}}% +\index{nomplabels@\cs{nomplabels}} + +Causes all label creation commands to write their contents to the output +file. It effects only labels on the figure, not a caption added by the +\cs{tcaption} command (see section~\ref{text}). In this case labels are +handled by \MP{} and can be rotated. It requires \MP{}, and will be be +ignored without it (\MF{} cannot handle labels). Using this option +without the \opt{metapost} option may also produce an error message +either from \TeX{} or \MF{}. The command forms can be placed anywhere. +If used outside an mfpic environment, they affect all subsequent +\cs{tlabel} commands; inside an mfpic environment they affect all +\cs{tlabel} commands in that figure. + +When this is in effect, the labels become part of the figure and, in the +default handling, they may be clipped off or covered up by later drawing +elements. But see the next section on the \opt{overlaylabels} option. +Labels added to a picture contribute to the bounding box even if +\opt{truebbox} is not in effect. + +The user is responsible for adding the appropriate \mfc{verbatimtex} +header to the output file if necessary. For this purpose, there is the +\cs{mfpverbtex} command, see section~\ref{labels}. If the label text +contains only valid plain \TeX{} macros, there is generally no need for +a \mfc{verbatimtex} preamble at all. If you add a \mfc{verbatimtex} +preamble of \LaTeX{} code take care to make sure \MP{} calls \LaTeX{} +(for example, the \texttt{mpost} command may take an option for this +purpose, or an environmental variable named \texttt{TEX} may be set +equal to \texttt{latex} in the command shell of your operating system.). + +\section{\opt{overlaylabels}, \cs{overlaylabels}, \cs{nooverlaylabels}.} +\label{overlaylabels} +\index{overlaylabels@\opt{overlaylabels}}% +\index{overlaylabels@\cs{overlaylabels}}% +\index{nooverlaylabels@\cs{nooverlaylabels}} + +In the past, under \opt{mplabels} all text labels created by \cs{tlabel} +and its relatives were added to the picture by \MP{} \emph{as they +occurred}. This made them subject to later drawing commands: they could +be covered up, erased, or clipped. With this option (or after the +command \cs{overlaylabels}) text labels are saved in a separate place +from the rest of a picture. When a picture is completed, the labels that +were saved are added on top of it. This is the way labels always behave +under the \opt{metafont} option, because then \TeX{} must add the labels +and there is no possibility for special effects involving clipping or +erasing (at the \MF{} level). + +With the \opt{metapost} option, but without \opt{mplabels} it has been +decided to keep the same behavior (and the same code) as under the +\opt{metafont} option. However, when \opt{mplabels} is used, there is +the possibility for special effects with text, and it has always been +the behavior before version 0.7 to simply place the labels as they +occurred. It turns out that placing the labels at the end is cleaner and +simpler to code, so I experimented with it and rejected it as a default, +but now offer it as an option. With this option, \mfp{} labels have +almost the same behavior with or without \opt{mplabels}. + +The commands may be used anywhere. Outside a figure they affect all +subsequent figures, inside a figure they affect all subsequent text in +that figure. The commands and option are ignored under the metafont +option. + +\section{\opt{truebbox}, \cs{usetruebbox}, +\cs{notruebbox}.}\label{truebbox} +\index{truebbox@\opt{truebbox}}% +\index{usetruebbox@\cs{usetruebbox}}% +\index{notruebbox@\cs{notruebbox}} + +Normally \MP{} outputs an EPS file with the actual bounding box of the +figure. By default, \mfp{} \emph{overrides} this and sets the bounding +box to the dimensions specified by the \cs{mfpic} command that produced +it. (This used to be needed for \TeX{} is to handle \cs{tlabel} commands +correctly. Now, it is just for backward compatability, and for +compatability with \MF{}'s behavior.) It is reasonable to let \MP{} have +its way, and that is what this option does. If one of the command forms +is used in an \env{mfpic} environment, it affects only that environment, +otherwise it affects all subsequent figures. This option currently has +no effect with \MF{}, but should cause no errors. + +This option is almost mandatory if you wish to use \prog{dvipdfm(x)} to +convert \TeX{}'s DVI output to PDF. Both \prog{dvipdfm} and +\prog{dvipdfmx} have a tendency to clip \MP{} figures to the stated +bounding box. Thus, anything running outside those bounds is lost. + + +\section{\opt{clip}, \cs{clipmfpic}, \cs{noclipmfpic}.}\label{clip} +\index{clip@\opt{clip}}% +\index{clipmfpic@\cs{clipmfpic}}% +\index{noclipmfpic@\cs{noclipmfpic}} + +Causes all parts of the figure outside the rectangle specified by the +\cs{mfpic} command to be removed. The commands can come anywhere. If +issued inside an \env{mfpic} environment they affect the current figure +only. Otherwise all subsequent figures are affected. Note: this is a +rather rudimentary option. It has an often unexpected interaction with +truebbox. When both are in effect, \MP{} will produce a bounding box +that is the intersection of two rectangles: the true one \emph{without +clipping}, and the clipping rectangle (i.e., the one specified in the +\cs{mfpic} command). It is possible for the actual figure to be much +smaller than this bounding box (even empty!). This is a property of the +\MP{} \gbc{clip} command and we know of no way to avoid it. + + +\section{\opt{centeredcaptions}, \cs{usecenteredcaptions}, +\cs{nocenteredcaptions}.}\label{centeredcaptions} +\index{centeredcaptions@\opt{centeredcaptions}}% +\index{usecenteredcaptions@\cs{usecenteredcaptions}}% +\index{nocenteredcaptions@\cs{nocenteredcaptions}} + +Causes multiline captions created by \cs{tcaption} to have all lines +centered. This has no effect on the normal \LaTeX{} \cs{caption} +command.% + \footnote{This writer [DHL] feels that \cs{tcaption} is too limited + and users ought to apply the caption by other means, such as + \LaTeX{}'s \cs{caption} command, outside the \env{mfpic} + environment.}% + +The commands can be issued anywhere. If inside an \env{mfpic} +environment they should come before the \cs{tcaption} command and affect +only it, otherwise they affect all subsequent figures. They should not +be used in the argument of a \cs{tcaption} command. + +\section{\opt{raggedcaptions}, \cs{useraggedcaptions}, +\cs{noraggedcaptions}.}\label{raggedcaptions} +\index{raggedcaptions@\opt{raggedcaptions}}% +\index{useraggedcaptions@\cs{useraggedcaptions}}% +\index{noraggedcaptions@\cs{noraggedcaptions}} + +Causes multiline captions created by \cs{tcaption} to have all lines +raggedright. If \opt{centeredcaptions} is on, both sides will be ragged. +The command \cs{noraggedcaptions} restores the default: all lines except +the last justified. The last is either centered or flush left according +to whether \opt{centeredcaptions} is on or off. + +The commands can be issued anywhere. If inside an \env{mfpic} +environment they should come before the \cs{tcaption} command and affect +only it, otherwise they affect all subsequent figures. They should not +be used in the argument of a \cs{tcaption} command. + +\section{\opt{debug}, \cs{mfpicdebugtrue}, +\cs{mfpicdebugfalse}.}\label{debug} +\index{debug@\opt{debug}}% +\index{mfpicdebugtrue@\cs{mfpicdebugtrue}}% +\index{mfpicdebugfalse@\cs{mfpicdebugfalse}} + +Causes \mfp{} to write a rather large amount of information to the +\file{.log} file and sometimes to the terminal. Debug information +generated by \file{mfpic.tex} \emph{while loading} is probably of +interest only to developers, but can be turned on by giving a definition +to the command \cs{mfpicdebug} prior to loading. Any definition will +work because \prog{mfpic} only checks whether it is defined. + +\section{\opt{clearsymbols}, \cs{clearsymbols}, \cs{noclearsymbols}.} +\index{clearsymbols@\opt{clearsymbols}}% +\index{clearsymbols@\cs{clearsymbols}}% +\index{noclearsymbols@\cs{noclearsymbols}} + +\Mfp{} has two commands, \cs{point} and \cs{plotsymbol} that place a +small symbol at each of a list of points. The first can place either a +small filled disk or an open disk, the choice being dictated by the +setting of the boolean \cs{pointfilltrue} or \cs{pointfillfalse}. The +behavior of \cs{point} in the case of \cs{pointfillfalse} is to erase the +interior of the disk in addition to drawing its circumference. + +The second command \cs{plotsymbol} can place a variety of shapes, some +open, some not. Its behavior before version 0.7 was to always draw the +shape without erasing the interior. Two other commands that placed these +symbols, \cs{plotnodes} and \cs{plot}, had the same behavior. With this +option, two of these, \cs{plotsymbol} and \cs{plotnodes}, will erase the +interior of the open symbols before drawing them. Thus +\cs{plotsymbol}\marg{SolidCircle} still works just like +\cs{pointfilltrue}\cs{point}, and now with this option +\cs{plotsymbol}\marg{Circle} behaves the same as +\cs{pointfillfalse}\cs{point}. The \cs{plot} command is unaffected by +this option. + + +\section{\opt{draft}, \opt{final}, \opt{nowrite}, \cs{mfpicdraft}, + \cs{mfpicfinal}, \cs{mfpicnowrite}.}\label{draft} +\index{draft@\opt{draft}}% +\index{final@\opt{final}}% +\index{nowrite@\opt{nowrite}}% +\index{mfpicdraft@\cs{mfpicdraft}}% +\index{mfpicfinal@\cs{mfpicfinal}}% +\index{mfpicnowrite@\cs{mfpicnowrite}} + +Under the \opt{metapost} option, the various macros that include the +\EPS{} files emit rather large amounts of confusing error messages when +the files don't exist (especially in \LaTeX{}). For this reason, before +each picture is placed, \mfp{} checks for the existence of the graphic +before trying to include it. However, on some systems checking for the +existence of a nonexistent file can be very slow because the entire +\TeX{} search path will need to be checked. Therefore, \mfp{} doesn't +even attempt any inclusion on the first run. The first run is detected +by the non-existence of \file{\meta{file}.1}, where \meta{file} is the +name given in the \cs{opengraphsfile} command (but see also +section~\ref{files}). These options can be used to override this +automatic detection. All the command versions \emph{should} come before +the \cs{opengraphsfile} command. The \cs{mfpicnowrite} command +\emph{must} come before it. + +These options might be used if, for example, the first figure has an +error and is not created by \MP{}, but you would like \mfp{} to go +ahead and include the remaining figures. Then use \opt{final}. It can +also be used to override a \LaTeX{} global \opt{draft} option. Or if +\file{\meta{file}.1} exists, but other figures still have errors and you +would like several runs to be treated as first runs until \MP{} has +stopped issuing error messages, then use \opt{draft}. These commands +also work under the \opt{metafont} option, but time and error messages +are less of an issue then. If all the figures have been created and +debugged, some time might be saved (with either \opt{metafont} or +\opt{metapost}) by not writing the output file again, then \opt{nowrite} +can be used. + +\section{\opt{mfpreadlog}, \cs{mfpreadlog}.}\label{readlog} +\index{mfpreadlog@\opt{mfpreadlog}}% +\index{mfpreadlog@\cs{mfpreadlog}} + +From version 0.8, there exists a scheme to allow \MF{} or \MP{} to pass +information back to the \file{.tex} file. This is done by writing code +to the figure file requesting \MF{} to place that information in the +\file{.log} file it produces. This option instructs \mfp{} to +read through that log file line-by-line looking for such information. +Since such log files can be potentially quite lengthy, this is made an +option. If the command form \cs{mfpreadlog} is used, it must come before +the \cs{opengraphsfile} command, since that is when the file will be +examined. At the present time, the only \mfp{} facility that requires +this two-way communication is \cs{assignmfvalue} (see +subsection~\ref{misc}). If this is used, the filename given to +\cs{opengraphsfile} should not be the same as the \TeX{} source file in +which this occurs, as then the wrong \file{.log} may be read. + + +\section{Scoping Rules.}\label{scoping} + +Some of these options merely change \TeX{} behavior, others write +information to the output file for \MF{} or \MP{}. Changes in \TeX{} +behavior obey the normal \TeX{} grouping rules, the information written +to the output file obeys \MF{} grouping rules. Since each \env{mfpic} +environment is both a \TeX{} group and (corresponds to) a \MF{} group, +the following always holds: use of one of the command forms inside of an +\env{mfpic} environment makes the change local to that environment. + +An effort has been made (as of version 0.7) to make this universal. That +is, any of the commands listed above for turning options on and off will +be global when issued outside an \env{mfpic} environment. The debug +commands are exceptions; they obey all \TeX{} scoping rules. + +We have also tried to make all other \mfp{} commands for changing the +various parameters follow this rule: local inside \env{mfpic} +environment, global outside. If this is ever untrue, and I don't +document that fact, please let me know. + +The following are special: +\begin{display} +\cs{usemetapost}\index{usemetapost@\cs{usemetapost}}, +\cs{usemetafont}\index{usemetafont@\cs{usemetafont}}, +\cs{mfpicdraft}\index{mfpicdraft@\cs{mfpicdraft}}, +\cs{mfpicfinal}\index{mfpicfinal@\cs{mfpicfinal}}, +\cs{mfpicnowrite}\index{mfpicnowrite@\cs{mfpicnowrite}},\\ +and +\cs{mfpreadlog}\index{mfpreadlog@\cs{mfpreadlog}}. +\end{display} +\noindent Their effects are always global, partly because they should +occur prior to the initialization command \cs{opengraphsfile} (described +in section~\ref{files}). Note that \cs{usemetapost} may cause a file of +graphic inclusion macros to be input. If this command is issued inside a +group, some definitions in that file may be lost, breaking the graphic +inclusion code. + + +\clearpage +\chapter{\CMF{} and \CMP{} Data Types.}\label{types} + +Since the arguments of most \mfp{} drawing commands are sent to \MF{} to +be interpreted, it's useful to know something about \MF{} concepts. In +this chapter we will discuss some of the data types \MF{} supports. +Even the casual user should know how coordinates and colors are treated +and so should at least skim the next two sections. The last +section can be read when the user wants to manipulate more complex +objects. + +\CMF{} permits several different data types, and we will mainly be +concerned with six of these: \kw{numeric}, \kw{pair}, \kw{color} (\MP{} +only), \kw{path}, \kw{picture} and \kw{boolean}.% + \footnote{For the curious, there are a total of eight types (nine or + ten for \MP{}). The other three are \kw{string}, \kw{transform} and + \kw{pen}. \MF{} also permits expressions that produce nothing, which + is sometimes called the vacuous type, but doesn't allow (or need) + variables of this type.} +In \MP{} version 1.000, a tenth data type was added, \kw{cmykcolor}, and +the \kw{color} data type can be referred to as `\kw{rgbcolor}' when a +distinction is necessary. + +A \emph{variable} is a symbolic name, which can be a single letter such +as \mfc{A}, or a descriptive name like \mfc{origin}. Any sequence of +letters and underscores is permitted as a variable name. Numeric indexes +are also allowed, provided all variables that differ only in the index +have the same type. Thus \mfc{A1}, \mfc{A2}, etc., might be variables +which are all of type \kw{pair}. Quite a lot more is permited for variable +names, but the rules are rather complex and easy to violate. \Mfp{} has +commands for creating both simple variables and indexed variables +(called \emph{arrays}) but the casual user can get quite a lot of use +out of \mfp{} without ever creating or using a \MF{} variable. + +\CMF{} also has something akin to functions. For example, \mfc{sin(1.57)} +might represent a function named \mfc{sin} receiving the parameter +$1.57$ as input and returning the appropriate value. Functions +can take any number of parameters and return any of the data types that +\MF{} supports.% + \footnote{Including the vacuous type.} + + +\section{Numerics and pairs.}\label{pairs} + +\CMF{} has \kw{numeric} quantities. These include lengths, such as the +radius of a circle, as well as dimension units such as \mfc{in} (inches) +and \mfc{pt} (points). In fact it understands all the same units that +\TeX{} does. These \kw{numeric} quantities can be constants (explicit +numbers) or variables (symbolic names). In fact, \mfc{in} and \mfc{pt} +are symbolic names for \kw{numeric} quantities. + +\CMF{} also has \kw{pair} objects, which may be constants or variables. +Constants of type \kw{pair} have the form \mfc{($x$,$y$)} where $x$ and +$y$ are numbers, for example \mfc{(0,0)}. Pairs are two-dimensional +quantities used for representing either points or vectors in a +rectangular (Cartesian) coordinate system. + +In this manual we often represent each pair by a brief name, such as +\meta{p} or \meta{v}, the meanings of which are usually obvious in the +context of the macro. These are intended to be replaced in actual use by +either a pair constant or variable. The succinctness of this notation +helps us to think geometrically rather than only of coordinates. + + +\section{Colors.}\label{MPcolors} + +\CMP{} has the same concepts as \MF, but also has \kw{color} objects, +which may also be constants or variables. In recent MP{}, colors come in +two flavors: \kw{rgbcolor} and \kw{cmykcolor}. Constants of type +\kw{rgbcolor} have the form \mfc{($r$,$g$,$b$)} where $r$, $g$, and $b$ +are numbers between $0$ and $1$ determining the relative proportions of +red, green and blue in the color (the `rgb' model). Constants of type +\kw{cmykcolor} have the form \mfc{($c$,$m$,$y$,$k$)} where $c$, $m$, $y$ +and $k$ are numbers between $0$ and $1$ determining the relative +proportions of cyan, magenta, yellow and black in the color (the `cmyk' +model). + +A color variable is a name, like \mfc{red}, \mfc{blue} (both predefined +rgb colors in \MP) or \gbc{magenta} (predefined by \mfp{} to be an rgb +color if \MP{} has version ${}<1.000$, a cmyk color if the version is at +least 1.000). + + +\section{Paths, pictures and booleans.}\label{paths} + +Most of the things that \mfp{} is designed to draw are paths. Examples +of paths are circles, rectangles, other polygons, graphs of +functions and splines. Because we tend to want to draw these (or fill +them, or render them in other ways) we call the \mfp{} commands that +produce them \emph{figure macros}. Although they are much more complex +than numerics, pairs, or colors, they can still be stored in symbolic +names. + +Normally in \mfp{} we want to create a picture, usually by rendering one +or more paths. It is possible in \MF{} to store a picture in a symbolic +name without actually drawing it. However, because of their complexity, +objects of type \kw{picture} require somewhat more care than paths or +other data types. Do not expect to use stored pictures in the same way +as stored paths. In fact, one should use \kw{picture} variables only in +those command that are explicitely designed for them. In \mfp{} to date +these are only \cs{tile...}\cs{endtile} and \cs{mfpimage} to store +pictures, and \cs{putmfpimage} to draw copies of one. There is also +\cs{tess}, but it is used only to fill a region with copies of a picture +created by \cs{tile}. + +The \kw{boolean} data type is one of the values \mfc{true} or +\mfc{false}. Variables of type \kw{boolean} are symbolic names that can +take either of these two values. Usually these are used to influence the +behavior of some command by setting a relevant \kw{boolean} variable to +one or the other value. + + +\clearpage +\chapter{The Macros.}\label{macros} + +Many of the commands of \mfp{} have optional arguments. These are +denoted just as in \LaTeX{}, with square brackets. Thus, the command for +drawing a circle can be given +\begin{verbatim} +\circle{(0,0),1} +\end{verbatim} +having only the mandatory argument, or +\begin{verbatim} +\circle[p]{(0,0),1} +\end{verbatim} +Whenever an optional argument is omitted, the behavior is equivalent to +some choice of the optional argument. In this example, the two forms +have exactly the same behavior, drawing a circle centered at $(0,0)$ +with radius $1$. In this case we will say ``\oarg{p} is the +\emph{default}''. Another example is \cs{point}\marg{(1,0)} versus +\cs{point}\oarg{3pt}\marg{(1,0)}. They both place a dot at the point +$(1,0)$. The second one explicitly requests that it have diameter +\dim{3pt}; the first will examine the length command \cs{pointsize}, +which the user can change, but it is initialized to \dim{2pt}. In this +case we will say ``the default is the value of \cs{pointsize}, +\emph{initially} \dim{2pt}''. + +If an \mfp{} command that takes an optional argument finds only empty +brackets (completely empty, no spaces), then it will use the default +value. This is useful for commands that have two optional arguments and +one wants the default value in the first one and some nondefault value +in the second. An optional argument should normally not contain any +spaces. Even when the argument contains more than one piece of data, +spaces should not separate the parts. In some cases this will cause no +harm, but it would be better to avoid doing it altogether, because there +are cases where it will cause wrong results or error messages. + + +\section{Files and Environments.}\label{files} + +\begin{cd}\pagelabel{opengraphsfile} +\cs{opengraphsfile}\marg{\meta{file}}\\ + \ $\ldots$\\ +\cs{closegraphsfile}% +\index{opengraphsfile@\cs{opengraphsfile}}% +\index{closegraphsfile@\cs{closegraphsfile}} +\end{cd} + +These macros open and close the \MF{} or \MP{} file which will contain +the pictures to be included in this document. The name of the file will +be \file{\meta{file}.mf} (or \file{\meta{file}.mp}). Do \emph{not} +specify the extension, which is added automatically. + +\emph{Note}: This command may cause \file{\meta{file}.mf} or +\file{\meta{file}.mp} to be overwritten if it already exists, so be sure +to consider that when selecting the name. Repeating the running of +\TeX{} will overwrite the file created on previous runs, but that should +be harmless. For if no changes are made to \env{mfpic} environments, the +identical file will be recreated, and if changes have been made, then +you want the file to be replaced with the new version. + +It is possible (but \emph{has not} been seriously tested) to close one +file and open another, and even to change between \opt{metapost} and +\opt{metafont} in between. If anything goes wrong with this, contact the +maintainer and it might be fixed in some later version. + +There may be limitations on what can be used as a filename. As of \mfp{} +version \mfpversion, we have tried to permit \cs{jobname} as part of +\meta{file}. Thus we permit \TeX{} macros, but they should expand to +non-special characters. Permitting macros makes it essentially +impossible for the filename to contain the backslash and brace +characters. Also spaces are problematic. However other special \TeX{} +characters (for example: tilde, underscore and percent) can be used, +though that is really not recommended. + +\begin{cd}\pagelabel{mfpic} +\cs{mfpic}\oarg{\meta{xfactor}}\oarg{\meta{yfactor}}% + \marg{\meta{xmin}}\marg{\meta{xmax}}\marg{\meta{ymin}}\marg{\meta{ymax}}\\ + \ $\ldots$\\ +\cs{endmfpic}% +\index{mfpic@\cs{mfpic}}% +\index{endmfpic@\cs{endmfpic}} +\end{cd} + +These macros open and close the \env{mfpic} environment% + \footnote{We use the term `environment' loosely. However, in + \LaTeX{} one may use an actual \env{mfpic} environment. See + page~\pageref{envusage}.} +in which the drawing macros make sense. While many \mfp{} commands can +be used inside or outside this environment, those that actually produce +visible output are required to be inside. The \cs{mfpic} macro also sets +up the local coordinate system for the picture. The \meta{xfactor} and +\meta{yfactor} parameters establish the length of a coordinate system +unit, as a multiple of the \TeX{} dimension \cs{mfpicunit}. If neither +is specified, both are taken to be 1 and each coordinate system unit is +1 \cs{mfpicunit}. If only one is specified, then they are assumed to be +equal. Note that some drawing commands require equal scales to work as +expected: if you try to draw a circle with different scales you will get +an ellipse. + +The \meta{xmin} and \meta{xmax} parameters establish the lower +and upper bounds for the $x$-axis coordinates; similarly, \meta{ymin} +and \meta{ymax} establish the bounds for the $y$-axis. These bounds are +expressed in local units---in other words, the actual width of the +picture will be $(\meta{xmax}-\meta{xmin})\cdot\meta{xfactor}$ times +\cs{mfpicunit}, its height $(\meta{ymax}-\meta{ymin})\cdot\meta{yfactor}$ +times \cs{mfpicunit}, and its depth zero. + +Most of \mfp{}'s drawing macros accept parameters which are +\emph{coordinate pairs}. A coordinate pair is a pair of numbers $(x,y)$ +enclosed in parentheses, with $\meta{xmin} \le x \le \meta{xmax}$ and +$\meta{ymin} \le y \le \meta{ymax}$.% + \footnote{These inequalities can be violated, usually causing + something to be drawn outside the designated borders of the figure.} +We will call these \emph{graph coordinates} and refer to the numbers $x$ +and $y$ as being \emph{in graph units}. Things like the thickness of +lines and the lengths of arrowheads are required to be expressed in +actual lengths such as \dim{1pt} or \dim{3mm}. These will be referred to as +\emph{absolute} units. + +One can scale all pictures uniformly by changing \cs{mfpicunit}, and +scale an individual picture by changing \meta{xfactor} and \meta{yfactor}. +After loading \mfp{}, \cs{mfpicunit} has the value \dim{1pt}. One +\texttt{pt} is a \emph{printer's point}, which equals 1/72.27 inches or +0.35146 millimeters. + +\emph{Note}: Changing \cs{mfpicunit} or the optional parameters will +scale the coordinate system, but not the values of parameters that are +defined in absolute units. If you wish, you can set these to multiples +of \cs{mfpicunit}, but it is difficult (and almost certainly unwise) to +get the thickness of lines (for example) to scale along with the scale +parameters. + +In addition to establishing the coordinate system, these scales and +bounds are used to establish the metric for the \MF{} character or +bounding box for the \MP{} figure described within the environment. If +any of these parameters are changed, the \file{.tfm} file (\MF{}) or the +bounding box (\MP{}) will be affected, so you will have to be sure to +reprocess the \TeX{} file after processing the \file{.mf} or \file{.mp} +file, even if no other changes are made in the figure. + +The value of these 6 parameters to \cs{mfpic} are available within the +environment as macros: \cs{xfactor}, \cs{yfactor}, \cs{xmin}, \cs{xmax}, +\cs{ymin} and \cs{ymax}. + +\begin{cd}\pagelabel{mfpicnumber} +\cs{mfpicnumber}\marg{\meta{num}}% +\index{mfpicnumber@\cs{mfpicnumber}} +\end{cd} + +Normally, \cs{mfpic} assigns the number 1 to the first \env{mfpic} +environment, after which the number is increased by one for each new +\env{mfpic} environment. This number is used internally to include the +picture. It is also transmitted to the output file where it is used as +the argument to a \gbc{beginmfpic} command. In \MF{} this number becomes +the position of the character in the font file, while in \MP{} it is the +extension on the graphic file that is output. The above command tells +\mfp{} to ignore this sequence and number the next \env{mfpic} +figure with \meta{num} (and the one after that $\meta{num}+1$, etc.). It +is up to the user to make sure no number is repeated, as no checking is +done. Numbers greater than 255 may cause errors, as \TeX{} assumes that +characters are represented by 8-bit numbers. If the first figure is to +be numbered something other than $1$, then, under the \opt{metapost} +option, this command should come before \cs{opengraphsfile}, as that +command checks for the existence of the first numbered figure to +determine if there are figures to be included. + +\begin{cd}\pagelabel{everymfpic} +\cs{everymfpic}\marg{\meta{commands}}\\ +\cs{everyendmfpic}\marg{\meta{commands}}% +\index{everymfpic@\cs{everymfpic}}% +\index{everyendmfpic@\cs{everyendmfpic}}% +\end{cd} + +These commands store the \meta{commands}. The first arranges for these +commands to be issued first thing in every \env{mfpic} environment and +the second arranges for its commands to be issued as the last thing in +every such environment. These could be any commands that make sense +inside that environment. Their purpose is mainly to save typing if there +is identical setup being performed in every picture. + +\begin{cd}\pagelabel{envusage} +\cs{begin}\marg{mfpic}\texttt{...}\cs{end}\marg{mfpic}% +\index{begin@\cs{begin}\marg{mfpic}} +\end{cd} + +In \LaTeX{} you may prefer to use \cs{begin}\marg{mfpic} and +\cs{end}\marg{mfpic} (instead of \cs{mfpic} and \cs{endmfpic}). This is +by no means required. The sample file \file{lapictures.tex} provided +with \mfp{} illustrates this use of an \env{mfpic} environment in +\LaTeX{}. + +\medskip +A word about \TeX{} groups inside \env{mfpic} environments. These can be +useful to limit the scope of declarations or of changes to some +variables. However, they do not limit the scope of changes to the figure +file that is being written, so there is a danger that \TeX{} and \MF{} +will have different values. There are also some \mfp{} command that need +to be at the outermost level. Thus, grouping should generaly be avoided +except for those groups provided by \mfp{} commands. + +\medskip +For the remainder of the macros, the numerical parameters are expressed +in graph units, the units of the local coordinate system specified by +\cs{mfpic}, unless otherwise indicated. + +\section{Common objects.}\label{figures} + +The \mfp{} macros that draw things can be roughly divided into two +classes. +\begin{enumerate} + \item Those that simply cause something to be drawn. Examples of these + are the \cs{point} command, which places a dot at a list of + coordinates, and \cs{gridlines}, which draw coordinate lines with + specified separation. + \item Those that both \emph{define} and draw a \emph{path}. The macros + \cs{circle}, \cs{rect}, and \cs{polyline} are examples of these. +\end{enumerate} + +Macros of type 2 are referred to hereafter as \emph{figure macros}, for +lack of a better term. With them one can use \emph{prefix +macros}\index{prefix macro} to modify various aspects of the path and +how it is drawn. For example, +\begin{verbatim} +\polyline{(1,2),(3,4)} +\end{verbatim} +draws a line from $(1,2)$ to $(3,4)$, but +\begin{verbatim} +\dotted\polyline{(1,2),(3,4)} +\end{verbatim} +produces a dotted version, and +\begin{verbatim} +\arrow\polyline{(1,2),(3,4)} +\end{verbatim} +draws it with an arrowhead at the tip. This is not possible with +\cs{gridlines}, for example. As \mfp{} and the accompanying \MF{} +package \grafbase{} are currently written, prefix macros can only be +applied to single paths, and \cs{gridlines} produces a whole set of +lines. In this manual, as each macro is introduced, if it is a figure +macro, this will be explicitly stated. + +Some commands depend on the value of separately defined parameters. all +these parameters are initialized when \mfp{} is loaded. In the following +descriptions we give the initial value of all the relevant parameters. +\Mfp{} provides commands to change any of these parameters. When \MP{} +output is selected, figures can be drawn in any color and several of the +above mentioned parameters are colors. For example, \gbc{drawcolor} is +the name of the default color used to draw curves, \gbc{headcolor} is +used when drawing arrowheads, etc. To save repetition: all special +colors for figures are initialized to \mfc{black} except +\mfc{background}, which is \mfc{white}. + + +\subsection{Points, lines, and rectangles}\label{points} + +\begin{cd}\pagelabel{point} +\cs{point}\oarg{\meta{size}}\marg{\meta{$p_0$},\meta{$p_1$},$\ldots$}% +\index{point@\cs{point}} +\end{cd} + +Draws small disks centered at the points specified in the list of +ordered pairs. The optional argument \meta{size} is an absolute +dimension that determines the diameter of the disks. The default is the +\TeX{} dimension \cs{pointsize}, initially \dim{2pt}. The disks have a +filled interior if the command \cs{pointfilltrue} has been issued (the +initial behavior). After the command \cs{pointfillfalse}, \cs{point} +commands will produce outlined circles with the interiors erased. The +color of the circles is the value of the predefined variable +\gbc{pointcolor}, and the color inside of the open circles is the value +of the variable \mfc{background}.% + \footnote{\MP{} cannot actually erase. The illusion of erasing is + created by painting over with \mfc{background}.} + +\begin{cd}\pagelabel{plotsymbol} +\cs{plotsymbol}\oarg{\meta{size}}\marg{\meta{symbol}}% +\marg{\meta{$p_0$},\meta{$p_1$},$\ldots$}% +\index{plotsymbol@\cs{plotsymbol}} +\end{cd} + +Draws small symbols centered at the points \meta{$p_0$}, \meta{$p_1$}, +and so on. The symbols must be given by name, and the available symbols +are: +\begin{display} +\gbc{Asterisk}\index{Asterisk@\gbc{Asterisk}}, +\gbc{Circle}\index{Circle@\gbc{Circle}}, +\gbc{Diamond}\index{Diamond@\gbc{Diamond}}, +\gbc{Square}\index{Square@\gbc{Square}}, +\gbc{Triangle}\index{Triangle@\gbc{Triangle}}, +\gbc{Star}\index{Star@\gbc{Star}}, +\gbc{SolidCircle}\index{SolidCircle@\gbc{SolidCircle}},\\ +\gbc{SolidDiamond}\index{SolidDiamond@\gbc{SolidDiamond}}, +\gbc{SolidSquare}\index{SolidSquare@\gbc{SolidSquare}}, +\gbc{SolidTriangle}\index{SolidTriangle@\gbc{SolidTriangle}}, +\gbc{SolidStar}\index{SolidStar@\gbc{SolidStar}}, +\gbc{Cross}\index{Cross@\gbc{Cross}} and +\gbc{Plus}\index{Plus@\gbc{Plus}}. +\end{display} +The names should be self-explanatory, the `\gbc{Solid}' ones are filled +in, the others are outlines. Under \opt{metapost}, symbols are drawn in +\gbc{pointcolor}. The \meta{size} defaults to \cs{pointsize} as in +\cs{point} above. \gbc{Asterisk} consists of six line segments while +\gbc{Star} is the standard five-pointed star formed from ten straight +line segments. \gbc{Cross} is a $\times$ shape. The name +`\cs{plotsymbol}' comes from the fact that the \cs{plot} command (see +subsection~\ref{drawing}), which was written first, utilizes these same +symbols. The command \cs{symbol} was already taken (standard \LaTeX{}). + +While one would rarely want to use them for this purpose, the following +symbols are also available: +\begin{display} +\gbc{Arrowhead}\index{Arrowhead@\gbc{Arrowhead}}, +\gbc{Crossbar}\index{Crossbar@\gbc{Crossbar}}, +\gbc{Leftbar}\index{Leftbar@\gbc{Leftbar}}, +\gbc{Rightbar}\index{Rightbar@\gbc{Rightbar}}, +\gbc{Lefthook}\index{Lefthook@\gbc{Lefthook}}, +\gbc{Righthook}\index{Righthook@\gbc{Righthook}}, +\gbc{Leftharpoon}\index{Leftharpoon@\gbc{Leftharpoon}},\\ +\gbc{Rightharpoon}\index{Rightharpoon@\gbc{Rightharpoon}}. +\end{display} +These are mainly intended for making arrows. See subsection~\ref{arrows} +for a further description. + +The difference between \cs{pointfillfalse}\cs{point}$\ldots$ and +\cs{plotsymbol}\marg{Circle}$\ldots$ is that the inside of the circle +will not be erased in the second version, so whatever else has already +been drawn in that area will remain visible. This is the default (for +backward compatibility), but that can be changed with the commands +below. + +\begin{cd}\pagelabel{clearsymbols} +\cs{clearsymbols}\\ +\cs{noclearsymbols}% +\index{clearsymbols@\cs{clearsymbols}}% +\index{noclearsymbols@\cs{noclearsymbols}} +\end{cd} + +After the first of these two commands, subsequent \cs{plotsymbol} +commands will draw the open symbols with their interiors erased. After +the second, the default behavior (described above) will be restored. +These commands have no effect on \cs{point}. \cs{plotnodes} (see +subsection~\ref{drawing}) also responds to the settings made by these +commands. The \cs{plot} command (also in subsection~\ref{drawing}) does +not. + +You can design your own `symbols'. See the discussion of arrowheads in +subsection~\ref{arrows}, and of storing paths in +subsection~\ref{transformation}. + +\begin{cd}\pagelabel{pointdef} +\cs{pointdef}\marg{\meta{name}}\texttt{(\meta{xcoord},\meta{ycoord})}% +\index{pointdef@\cs{pointdef}} +\end{cd} + +Defines a symbolic name for an ordered pair and the coordinates it +contains. \meta{name} is any legal \TeX{} command name \emph{without} +the backslash; \meta{xcoord} and \meta{ycoord} are any numbers. For +example, after the command \cs{pointdef}\marg{A}\texttt{(1,3)}, \cs{A} +expands to \texttt{(1,3)}, while \cs{Ax} and \cs{Ay} expand to +\texttt{1} and \texttt{3}, respectively. If \opt{mplabels} is in effect +one can use \cs{A} to specify where to place a text label, but if \TeX{} +is placing labels one must use \texttt{ (\cs{Ax},\cs{Ay})}. In most +other cases, one can use \cs{A} where a pair or point is required. + +\begin{cd}\pagelabel{polyline} +\cs{polyline}\marg{\meta{$p_0$},\meta{$p_1$},$\ldots$}\\ +\cs{lines}\marg{\meta{$p_0$},\meta{$p_1$},$\ldots$}% +\index{polyline@\cs{polyline}}% +\index{lines@\cs{lines}} +\end{cd} + +The figure macro \cs{polyline} produces connected line segments from +\meta{$p_0$} to \meta{$p_1$}, and from there to \meta{$p_2$}, etc. The +result is an open polygonal path through the specified points, in the +specified order. The macro \cs{lines} is an alias for \cs{polyline}. + +\begin{cd}\pagelabel{polygon} +\cs{polygon}\marg{\meta{$p_0$},\meta{$p_1$},$\ldots$}\\ +\cs{closedpolyline}\marg{\meta{$p_0$},\meta{$p_1$},$\ldots$}% +\index{polygon@\cs{polygon}}% +\index{closedpolyline@\cs{closedpolyline}} +\end{cd} + +The figure macro \cs{polygon} produces a closed polygon with vertices +at the specified points in the specified order. It works exactly like +\cs{polyline} except the last point in the list is also joined to the +first. The macro \cs{closedpolyline} is an alias for \cs{polygon}. + +\begin{cd}\pagelabel{rect} +\cs{rect}\marg{\meta{$p_0$},\meta{$p_1$}}% +\index{rect@\cs{rect}} +\end{cd} + +This figure macro produces the closed rectangle with horizontal and +vertical sides, having the points \meta{$p_0$} and \meta{$p_1$} as +diagonally opposite corners. The same rectangle can be specified in four +different ways: either pair of opposite corners in either order. + +It is occasionally helpful to know that connected paths like those +produced by \cs{polyline} or \cs{rect} have a \emph{start} and an +\emph{end} as well as \emph{sense} (or direction). The path produced by +\cs{polyline} starts at the first listed point and ends at last, having +the direction determined by the order of the points. For \cs{rect} the +sense may be clockwise or anticlockwise depending on the corners used: +it starts by moving horizontally from the first listed point. +Several \mfp{} macros (such as those that add arrowheads) treat the +beginning and the end of a path differently, or adjust their behavior +according to the sense of the curve. + +\begin{cd}\pagelabel{regpolygon} +\cs{regpolygon}\marg{\meta{num}}\marg{\meta{name}}% + \marg{\meta{eqn$_1$}}\marg{\meta{eqn$_2$}}% +\index{regpolygon@\cs{regpolygon}} +\end{cd} + +This figure macro produces a closed regular polygon with \meta{num} +sides. The second argument, \meta{name} is a symbolic name. It can be +used to refer to the vertices later. The last two arguments should be +equations that position two of the vertices or one vertex and the +center. The center is referred to by \meta{name}\gbc{0} and the vertices +by \meta{name}\gbc{1} \meta{name}\gbc{2}, etc., going anticlockwise +around the polygon. The \meta{name} itself (without a number suffixed) +will be a \MF{} variable assigned the value of \meta{num}. For example, +\begin{verbatim} +\regpolygon{5}{Kay}{Kay0=(0,1)}{Kay1=(2,0)} +\end{verbatim} +will produce a regular pentagon with its center at $(0,1)$ and its first +vertex at $(2,0)$. One could later draw a star inside it with +\begin{verbatim} +\polygon{Kay1,Kay3,Kay5,Kay2,Kay4} +\end{verbatim} +Moreover, \gbc{Kay} will equal $5$. The name given becomes a \MF{} +variable and care should be taken to make the name distinctive so as not +to redefine some internal variable. + + +\subsection{A word about list arguments}\label{list} + +We have seen already four \mfp{} macros that take a mandatory argument +consisting of an arbitrary number of coordinate pairs, separated by +commas. There are many more, and some that take a comma-separated list +of items of other types. If the lists are long, especially if they are +generated by a program, it might be more convenient if one could simply +refer to an external file for the data. This is possible, and one does +it the following way: instead of \cs{polyline}\marg{\meta{list}}, one +can write\index{datafile@\cs{datafile}} +\begin{ex} + \cs{polyline}\cs{datafile}\marg{\meta{filename}} +\end{ex} +where \meta{filename} is the full name of the file containing the data. +The required format of this file and the details of this usage can be +found in subsection~\ref{external}. This method is available for any +command that takes a comma-separated list of data (of arbitrary length) +as its last argument, \emph{with the exception of those commands that +add text to the picture}. Examples of the latter are \cs{plottext} and +\cs{axislabels} (subsection~\ref{text}). + + +\subsection{Axes, axis marks, and grids}\label{axesthings} + +\begin{cd}\pagelabel{axes} +\cs{axes}\oarg{\meta{hlen}}\\ +\cs{xaxis}\oarg{\meta{hlen}}\\ +\cs{yaxis}\oarg{\meta{hlen}}% +\index{axes@\cs{axes}}% +\index{xaxis@\cs{xaxis}}% +\index{yaxis@\cs{yaxis}} +\end{cd} + +These are retained for backward compatibility, but there are more +flexible alternatives below. They draw $x$- and $y$-axes for the +coordinate system. The command \cs{axes} is equivalent to \cs{xaxis} +followed by \cs{yaxis} which produce the obvious. The $x$- and $y$-axes +extend the full width and height of the \env{mfpic} environment. The +optional \meta{hlen} sets the length of the arrowhead on each axis. The +default is the value of the \TeX{} dimension \cs{axisheadlen}, initially +\dim{5pt}. The shape of the arrowhead is determined as in the \cs{arrow} +macro (section~\ref{modifier}). The color of the head is the value of +\gbc{headcolor}, the shaft is \gbc{drawcolor}. + +Unlike other commands that produce lines or curves, these do not respond +to prefix macros. They always draw a solid line (with an arrowhead +unless \cs{axisheadlen} is \dim{0pt}). They \emph{do} respond to changes +in the pen thickness (see \cs{penwd} in section~\ref{parameters}) but +that is pretty much the only possibility for variation. + +\begin{cd}\pagelabel{axis} +\cs{axis}\oarg{\meta{hlen}}\marg{\meta{one-axis}}\\ +\cs{doaxes}\oarg{\meta{hlen}}\marg{\meta{axis-list}}% +\index{axis@\cs{axis}}% +\index{doaxes@\cs{doaxes}}% +\end{cd} + +These produce any of 6 different axes. The parameter \meta{one-axis} can +be \texttt{x} or \texttt{y}, to produce (almost) the equivalent of +\cs{xaxis} and \cs{yaxis}; or it can be \texttt{l}, \texttt{b}, +\texttt{r}, or \texttt{t} to produce an axis on the border of the +picture (left, bottom, right or top, respectively). \cs{doaxes} takes a +list of any or all of the six letters (with either spaces or nothing in +between) and produces the appropriate axes. Example: +\cs{doaxes}\marg{lbrt}. The optional argument sets the length of the +arrowhead. In the case of axes on the edges, the default is the value of +\cs{sideheadlen}, which \mfp{} initializes to \dim{0pt}. For the $x$- +and $y$-axis the default is \cs{axisheadlen} as in \cs{xaxis} and +\cs{yaxis} above. + +The commands \cs{axis}\marg{x}, \cs{axis}\marg{y}, and +\cs{doaxes}\marg{xy} differ from the old \cs{xaxis}, \cs{yaxis} and +\cs{axes} in that these new versions respond to prefix macros. The +\cs{arrow} prefix previously mentioned is an exception: these macros add +an arrowhead automatically. For example, the sequence +\cs{dotted}\cs{axis}\marg{x} draws a dotted $x$-axis, but +\cs{dotted}\cs{xaxis} produces a \MF{} error. A prefix macro applied to +\cs{doaxes} generates no error, but only the first axis in the list will +be affected. + +\begin{cd}\pagelabel{axisline} +\cs{axisline}\marg{\meta{one-axis}}\\ +\cs{border}% +\index{axisline@\cs{axisline}}% +\index{border@\cs{border}}% +\end{cd} + +These are figure macros that draw the line or lines that an \cs{axis} +command would draw. An \cs{axis} command is almost the equivalent of +\begin{display} +\cs{arrow}\oarg{l\meta{hlen}}\cs{axisline}\marg{\meta{one-axis}}. +\end{display} +The \cs{axisline} command is provided as a figure macro for maximum +flexibility. For example, one can use the star-form of the \cs{arrow} +command if desired or decorate it with ones own choice of arrowhead (see +subsection~\ref{arrows}). + +Also a figure macro, \cs{border} produces the rectangle which, if drawn, +is visibly the same as the four border \cs{axisline}\,s (without heads). +It is a closed path and could easily be drawn with a \cs{rect} command, +but the \cs{border} command automatically adjusts for the margins set by +the commands below. + +The side axes are drawn by default with a pen stroke along the very edge +of the picture (as determined by the parameters to \cs{mfpic}). This can +be changed with the command \cs{axismargin} described below. + +Axes on the edges are drawn so that they don't cross each other. +\cs{doaxes}\marg{lbrt}, for example, produces a perfect rectangle. If the +$x$- and $y$-axis are drawn with \cs{axis} or \cs{doaxes}, then they +will not cross the side axes. For this to work properly, all the +following margin settings have to be done before the axes are drawn. + +\begin{cd}\pagelabel{axismargin} +\cs{axismargin}\marg{\meta{one-axis}}\marg{\meta{num}}\\ +\cs{setaxismargins}% + \marg{\meta{num}}\marg{\meta{num}}\marg{\meta{num}}\marg{\meta{num}}\\ +\cs{setallaxismargins}\marg{\meta{num}}% +\index{axismargin@\cs{axismargin}}% +\index{setaxismargins@\cs{setaxismargins}}% +\index{setallaxismargins@\cs{setallaxismargins}}% +\end{cd} + +The parameter \meta{one-axis} is one of the letters \texttt{l}, +\texttt{b}, \texttt{r}, or \texttt{ t}, and \cs{axismargin} causes the +given axis to be shifted \emph{inward} by the \meta{num} specified (in +\emph{graph} units). The second command \cs{setaxismargins} takes +4 arguments, using them to set the margins starting with the left and +proceeding anticlockwise. The last command sets all the axis margins to +the same value. + +A change to an axis margin affects not only the axis at that edge but +also the three axes perpendicular to it. For example, if the margins are +$M_{\mathrm{lft}}$, $M_{\mathrm{bot}}$, $M_{\mathrm{rt}}$ and +$M_{\mathrm{top}}$, then \cs{axis}\marg{b} draws a line starting +$M_{\mathrm{lft}}$ graph units from the left edge and ending +$M_{\mathrm{rt}}$ units from the right edge. Of course, the entire line +is $M_{\mathrm{bot}}$ units above the bottom edge. The margins are also +respected by the $x$- and $y$-axis, but only when drawn with \cs{axis}. +The old \cs{xaxis}, \cs{yaxis} and \cs{axes} ignore them. + +Special effects can be achieved by lying to one axis about the other +margins. That is, axes can be draw in separate commands with changes to +the declared margins in between. Be aware that various other commands +are affected by the margin values. Examples are the already mentioned +\cs{border}, as well as \cs{grid} and \cs{gridlines} +(page~\pageref{grid} in this subsection). + +\begin{cd}\pagelabel{axismarks} +\cs{xmarks}\oarg{\meta{len}}\marg{\meta{numberlist}}\\ +\cs{ymarks}\oarg{\meta{len}}\marg{\meta{numberlist}}\\ +\cs{lmarks}\oarg{\meta{len}}\marg{\meta{numberlist}}\\ +\cs{bmarks}\oarg{\meta{len}}\marg{\meta{numberlist}}\\ +\cs{rmarks}\oarg{\meta{len}}\marg{\meta{numberlist}}\\ +\cs{tmarks}\oarg{\meta{len}}\marg{\meta{numberlist}}\\ +\cs{axismarks}\marg{\meta{axis}}\oarg{\meta{len}}\marg{\meta{numberlist}}% +\index{xmarks@\cs{xmarks}}% +\index{tmarks@\cs{tmarks}}% +\index{bmarks@\cs{bmarks}}% +\index{ymarks@\cs{ymarks}}% +\index{lmarks@\cs{lmarks}}% +\index{rmarks@\cs{rmarks}}% +\index{axismarks@\cs{axismarks}} +\end{cd} + +These macros place hash marks on the appropriate axes at the places +indicated by the values in the list. The optional \meta{len} gives the +length of the hash marks. If \meta{len} is not specified, the \TeX{} +dimension \cs{hashlen}, initially \dim{4pt}, is used. The marks on the +$x$- and $y$-axes are centered on the respective axis; the marks on the +border axes are drawn to the inside. Both these behaviors can be +changed (see below). The commands may be repeated as often as desired. +(The timing of drawing commands can make a difference as outlined in +appendix~\ref{mpconsiderations}.) The command \cs{axismarks}\marg{x} is +equivalent to \cs{xmarks} and so on for each of the six axes. (I would +have used the shorter name \cs{marks}, but that name was already taken +by \eTeX{}.) + +The \meta{numberlist} is normally a comma-separated list of numbers. In +place of this, one can give a starting number, an increment and an +ending number as in the following example: +\begin{verbatim} +\xmarks{-2 step 1 until 2} +\end{verbatim} +is the equivalent of +\begin{verbatim} +\xmarks{-2,-1,0,1,2} +\end{verbatim} + +One must use exactly the words \mfc{step} and \mfc{until}. Spaces are +not needed unless a variable name is used in place of one of the +numbers (see subsection~\ref{variables}). The number of spaces is not +significant.% + \footnote{Experienced \MF{} programmers may recognize that anything + can be used that is permitted in \MF{}'s \meta{forloop} syntax. Thus + the given example can also be reworded \cs{xmarks}\marg{-2 upto 2}, + or even \cs{xmarks}\marg{2 downto -2}. See subsection~\ref{loops} + for more on for-loops in \mfp{}.} % +Users of this syntax should be aware that if any of the numbers is not +an integer then, because of natural round-off effects, the last value +might be overshot and a mark not printed there. For example, to ensure +that a mark is printed at the point $1.0$ on the $x$-axis, the second +line below is better than the first. +\begin{verbatim} +\xmarks{0 step .2 until 1.0} +\xmarks{0 step .2 until 1.1} +\end{verbatim} + +\begin{cd}\pagelabel{setaxismarks} +\cs{setaxismarks}\marg{\meta{axis}}\marg{\meta{pos}}\\ +\cs{setbordermarks}\marg{\meta{lpos}}\marg{\meta{bpos}}\marg{\meta{rpos}}\marg{\meta{tpos}}\\ +\cs{setallbordermarks}\marg{\meta{pos}}\\ +\cs{setxmarks}\marg{\meta{pos}}\\ +\cs{setymarks}\marg{\meta{pos}}% +\index{setaxismarks@\cs{setaxismarks}}% +\index{setbordermarks@\cs{setbordermarks}}% +\index{setallbordermarks@\cs{setallbordermarks}}% +\index{setxmarks@\cs{setxmarks}}% +\index{setymarks@\cs{setymarks}}% +\end{cd} + +These set the placement of the hash marks relative to the axis. The +parameter \meta{axis} is one of the letters \texttt{x}, \texttt{y}, \texttt{l}, +\texttt{b}, \texttt{r}, or \texttt{t}, and \meta{pos} must be one of the literal +words \gbc{inside}, \gbc{outside}, \gbc{centered}, \gbc{onleft}, +\gbc{onright}, \gbc{ontop} or \gbc{onbottom}. The second command takes +four arguments and sets the position of the marks on each border. The +third command sets the position on all four border axis to the same +value. The last two commands are abbreviations for +\cs{setaxismarks}\marg{x}\marg{\meta{pos}} and +\cs{setaxismarks}\marg{y}\marg{\meta{pos}}, respectively. + +Not all combinations make sense (for example, +\cs{setaxismarks}\marg{r}\marg{ontop}). In these cases, no error message +is produced: \gbc{ontop} and \gbc{onleft} give the same results, as do +\gbc{onbottom} and \gbc{onright}. The parameters \gbc{inside} and +\gbc{outside} make no sense for the $x$- and $y$-axes, but if they are +used then \gbc{inside} means \gbc{ontop} for the $x$-axis and +\gbc{onright} for the $y$-axis. These words are actually \MF{} numeric +variables and the variables \gbc{ontop} and \gbc{onleft}, for example, +have the same value. + +\begin{cd}\pagelabel{grid} +\cs{grid}\oarg{\meta{size}}\marg{\meta{xsep},\meta{ysep}}\\ +\cs{gridpoints}\oarg{\meta{size}}\marg{\meta{xsep},\meta{ysep}}\\ +\cs{lattice}\oarg{\meta{size}}\marg{\meta{xsep},\meta{ysep}}\\ +\cs{hgridlines}\marg{\meta{ysep}}\\ +\cs{vgridlines}\marg{\meta{xsep}}\\ +\cs{gridlines}\marg{\meta{xsep},\meta{ysep}}% +\index{grid@\cs{grid}}% +\index{gridpoints@\cs{gridpoints}}% +\index{lattice@\cs{lattice}}% +\index{vgridlines@\cs{vgridlines}}% +\index{hgridlines@\cs{hgridlines}}% +\index{gridlines@\cs{gridlines}}% +\end{cd} + +\cs{grid} draws a dot at every point for which the first coordinate is +an integer multiple of the \meta{xsep} and the second coordinate is an +integer multiple of \meta{ysep}. The diameter of the dot is determined +by \meta{size}. The default is the value of \cs{griddotsize}, +initially \dim{0.5pt}. Under the \opt{metapost} option, the color of the +dot is \gbc{pointcolor}. The commands \cs{gridpoints and \cs{lattice}} +are synonyms for \cs{grid}. + +\cs{hgridlines} draws the horizontal and \cs{vgridlines} the vertical +lines through these same points. \cs{gridlines} draws both sets of +lines. The thickness of the lines is set by \cs{penwd}. Authors are +recommended to either reduce the pen width or change \gbc{drawcolor} to +a lighter color for grid lines. Or omit them entirely: well-designed +graphs usually don't need them and almost never should both horizontals +and verticals be used. + +The above commands draw their dots and lines within the margins set by the +axis margin commands on page~\pageref{axismargin}. + +\begin{cd}\pagelabel{plrgrid} +\cs{plrgrid}\marg{\meta{rsep},\meta{anglesep}}\\ +\cs{gridarcs}\marg{\meta{rsep}}\\ +\cs{gridrays}\marg{\meta{anglesep}}\\ +\cs{plrpatch}\marg{\meta{rmin},\meta{rmax},\meta{rsep},% + \meta{tmin},\meta{tmax},\meta{tsep}}\\ +\cs{plrgridpoints}\oarg{\meta{size}}\marg{\meta{rsep},\meta{anglesep}}% +\index{plrgrid@\cs{plrgrid}}% +\index{plrpatch@\cs{plrpatch}}% +\index{gridarcs@\cs{gridarcs}}% +\index{gridrays@\cs{gridrays}}% +\index{plrgridpoints@\cs{plrgridpoints}}% +\end{cd} + +\cs{plrgrid} fills the graph with circular arcs and radial lines. +\cs{gridarcs} draws only the arcs, \cs{gridrays} only the radial lines. +\cs{plrgridpoints} places a dot (diameter \meta{size}) at all the places +the rays and arcs would intersect. It takes an optional argument for the +size of the dots, the default being \cs{griddotsize}, the same as the +\cs{grid} command. + +The arcs lie on circles centered at $(0,0)$ and the rays would all meet +at $(0,0)$ if extended. The corresponding \MF{} commands actually draw +just enough to cover the graph area and then clip them to the graph +boundaries. If you don't want them clipped, use \cs{plrpatch}. Unlike +the rectangular coordinate grid commands, these do not respect the axis +margins (rectangular margins don't really belong with polar coordinates). + +\cs{plrpatch} draws arcs with radii starting at \meta{rmin}, stepping by +\meta{rsep} and ending with \meta{rmax}. Each arc goes from angle +\meta{tmin} to \meta{tmax}. It also draws radial lines with angles +starting at \meta{tmin}, stepping by \meta{tsep} and ending with +\meta{tmax}. Each line goes from radius \meta{rmin} to \meta{rmax}. If +$\meta{rmax}-\meta{rmin}$ doesn't happen to be a multiple of +\meta{rsep}, the arc with radius \meta{rmax} is drawn anyway. The same +is true of the line at angle \meta{tmax}, so that the entire boundary is +always drawn. + +If \meta{tsep} is larger than \meta{tmax}${}-{}$\meta{tmin}, then only +the boundary rays will be drawn. If \meta{rsep} is larger than +\meta{rmax}${}-{}$\meta{rmin}, then only the boundary arcs will be +drawn. + +The color used for rays and arcs is \gbc{drawcolor}, and for dots +\gbc{pointcolor}. The advice about color and use of \cs{gridlines} holds +for \cs{plrgrid} and its relatives as well. + +\begin{cd}\pagelabel{vectorfield} +\cs{vectorfield}\oarg{\meta{hlen}}\marg{\meta{xsp},\meta{ysp}}% +\marg{\meta{formula}}\marg{\meta{restriction}}\\ +\cs{plrvectorfield}\oarg{\meta{hlen}}\marg{\meta{rsp},\meta{tsp}}% +\marg{\meta{formula}}\marg{\meta{restriction}}% +\index{vectorfield@\cs{vectorfield}}% +\index{plrvectorfield@\cs{plrvectorfield}} +\end{cd} + +These commande draw a field of vectors (arrows). The optional argument +is the length of the arrowhead, the default being the dimension +\cs{headlen}, initially \dim{3pt}. + +For \cs{vectorfield}, an arrow is drawn starting from each point $(x,y)$ +where $x$ is an integer multiple of \meta{xsp} and $y$ is an integer +multiple of \meta{ysp}. The vector field is given by \meta{formula}, +which should be a pair-valued expression in the literal variables +\mfc{x} and \mfc{y}. Typically that would be a pair of numeric +expressions enclosed in parentheses and separated by a comma. The last +argument is a boolean expression in the literal variables \mfc{x} and +\mfc{y}, used to restrict the domain. That is, if the expression is +false for some $(x,y)$, no arrow is drawn at that point. If you do not +wish to restrict the domain, type \texttt{true} for the restriction. + +For \cs{plrvectorfield}, an arrow is drawn starting from each point with +polar coordinates $(r,\theta)$ if $r$ is an integer multiple of +\meta{rsp} and $\theta$ is an integer multiple of \meta{tsp}. In this +case, the \meta{formula} must be a pair-valued expression in the literal +variables \mfc{r} and \mfc{t}. This should be (or produce) a pair of $x$ +and $y$ coorinates, not a polar coordinate pair. If you have formulas +$R(r,\theta)$ for the length of each vector and $T(r,\theta)$ for the +angle, then the following will convert to $(x,y)$ pairs: +\begin{verbatim} +{polar (R(r,t),T(r,t))} +\end{verbatim} +The last argument is as in \cs{vectorfield}, except it should depend on +the literal variables \mfc{r} and \mfc{t}. + +In either case, the arrow is not drawn if the starting point would lie +outside the borders set with \cs{axismargins} and its relatives. + +The following draws a rotational field, omitting the inside of the +circle of radius $1$, where the arrows would be excessively long, and +especially avoiding $(0,0)$ where the vector field is undefined. +\begin{verbatim} +\vectorfield[2.5pt]{.25,.25}{.5*(-y,x)/(x**2 + y**2)}{x**2 + y**2 >= 1} +\end{verbatim} +The following is the same field, represented by arrows whose locations +are regularly spaced in polar coordinates. +\begin{verbatim} +\plrvectorfield[2.5pt]{.25,20}{polar(.5/r,t+90)}{r >= 1} +\end{verbatim} + + +\subsection{Circles, arcs and ellipses}\label{circles} + +\begin{cd}\pagelabel{circle} +\cs{circle}\oarg{\meta{format}}\marg{\meta{specification}}% +\index{circle@\cs{circle}}% +\end{cd} + +This figure macro produces a circle. Starting with \mfp{} version 0.7, +there are more than one way to specify a circle. In version 0.8 and +later there are six ways, and one selects which one by giving +\cs{circle} an optional argument that signals what data will be +specified in the mandatory argument. + +\begin{cd} +\cs{circle}\oarg{p}\marg{\meta{$c$},\meta{$r$}}\\ +\cs{circle}\oarg{c}\marg{\meta{$c$},\meta{$p$}}\\ +\cs{circle}\oarg{t}\marg{\meta{$p_1$},\meta{$p_2$},\meta{$p_3$}}\\ +\cs{circle}\oarg{s}\marg{\meta{$p_1$},\meta{$p_2$},\meta{$\theta$}}\\ +\cs{circle}\oarg{r}\marg{\meta{$p_1$},\meta{$p_2$},\meta{$r$}}\\ +\cs{circle}\oarg{q}\marg{\meta{$p_1$},\meta{$p_2$},\meta{$r$}}% +\index{circle@\cs{circle}}% +\end{cd} + +The optional arguments produce circles according to the following +descriptions. +% +\begin{description} +\item[\oarg{p}] The \textit{Polar form} is the default. The data in the +mandatory argument should then be the center \meta{c} and radius +\meta{r} of the circle. A negative radius is a mathematical error, but +it is accepted. It produces the same circle, with the same sense, but +the starting point (normally \meta{$r$} units to the right of the +center) is \meta{$r$} units \emph{left} of the center. + +\item[\oarg{c}] The \textit{center-point form}. In this case the data +should be the center and one point on the circumference. The circle +starts at the point and has an anticlockwise sense. + +\item[\oarg{t}] The \textit{three-point form}. The data are three points +that do not lie in a straight line. The circle starts at the first point +and has the sense determined by the order of the points. + +\item[\oarg{s}] The \textit{point-sweep form}. The data are two points on the +circle, followed by the angle of arc between them. This circle starts at +the first point and has a sense determined by the angle: anticlockwise +for positive angles, clockwise for negative. + +\item[\oarg{r}] The \textit{point-radius form}. The data are two points on the +circle, followed by the radius. There are two circles with this data. +The one that makes the angle from the first to the second point positive +and less than $180$ degrees is produced. The sense of the circle is +normally anticlockwise starting at the first point. Using a negative +radius is a mathematical error, but this command just produces the other +circle with the opposite sense. + +\item[\oarg{q}] The \textit{alternative point-radius form}. The data are +the same as for the \oarg{r} case, except the other circle is produced. +That is, a circle starting at the first point, proceeding anticlockwise +through an angle greater than $180$ degrees to the second point, then +along the shorter arc to the first point. Again, a negative radius +produces the other circle with clockwise sense. +\end{description} +% +These optional arguments are also used in the \cs{arc} command (see +below). The \cs{circle} command draws the whole circle of which the +corresponding \cs{arc} command draws only a part. + +\begin{cd}\pagelabel{arc} +\cs{arc}\oarg{\meta{format}}\marg{\meta{specification}}\\ +\cs{arc*}\oarg{\meta{format}}\marg{\meta{specification}}% +\index{arc@\cs{arc}}% +\end{cd} + +This figure macro produces a circular arc specified as determined by the +\meta{format} optional parameter. As with \cs{circle}, the optional +\meta{format} parameter determines the format of the other parameter, as +indicated below. The user is responsible for ensuring that the parameter +values make geometric sense. The starting point of each arc is at the +first specified angle or point and the ending point is at the last one. + +The star-form produces the complementary arc. That is, instead of the +arc described below, it produces the rest of the circle from the ending +point to the starting point of the arc described. + +\begin{cd} +\cs{arc}\oarg{s}\marg{\meta{$p_0$},\meta{$p_1$},\meta{$\theta$}}\\ +\cs{arc}\oarg{p}\marg{\meta{$c$},\meta{$\theta_1$},\meta{$\theta_2$},\meta{$r$}}\\ +\cs{arc}\oarg{a}\marg{\meta{$c$},\meta{$r$},\meta{$\theta_1$},\meta{$\theta_2$}}\\ +\cs{arc}\oarg{c}\marg{\meta{$c$},\meta{$p_1$},\meta{$\theta$}}\\ +\cs{arc}\oarg{t}\marg{\meta{$p_0$},\meta{$p_1$},\meta{$p_2$}}\\ +\cs{arc}\oarg{r}\marg{\meta{$p_0$},\meta{$p_1$},\meta{$r$}}\\ +\cs{arc}\oarg{q}\marg{\meta{$p_0$},\meta{$p_1$},\meta{$r$}}% +\index{arc@\cs{arc}}% +\end{cd} + +The optional arguments produce arcs according to the following +descriptions. +\begin{description} +\item[\oarg{s}] The \textit{point-sweep form} is the default format. It +draws the circular arc starting from the point \meta{$p_0$}, ending at +the point \meta{$p_1$}, and covering an arc angle of \meta{$\theta$} +degrees, measured anticlockwise around the center of the circle. If, +for example, the points \meta{$p_0$} and \meta{$p_1$} lie on a +horizontal line with \meta{$p_0$} to the \emph{left}, and \meta{$\theta$} +is between $0$~and $360$ (degrees), then the arc will sweep \emph{below} the +horizontal line (in order for the arc to be anticlockwise). A +negative value of \meta{$\theta$} gives a clockwise arc from \meta{$p_0$} +to \meta{$p_1$}. + +\item[\oarg{p}] The \textit{polar form} draws the arc of a circle with +center \meta{$c$} starting at the angle \meta{$\theta_1$} and ending at +the angle \meta{$\theta_2$}, with radius \meta{$r$}. Both angles are +measured anticlockwise from the positive $x$ axis. If the first angle is +less than the second, the arc has an anticlockwise sense, otherwise +clockwise. A negative radius is a mathematical error, but the result is +the arc on the opposite side of the circle, as if both angles were +increased by $180$ degrees + +\item[\oarg{a}] The alternative polar form differs from the polar form +above only in the order of the arguments. This seems (to me) a more +reasonable order, and matches the order \cs{sector} requires (see below). +The p option is retained for backward compatibility. + +\item[\oarg{c}] The \textit{center-point-angle form} draws the circular +arc with center \meta{$c$}, starting at the point \meta{$p_1$}, and +sweeping an angle of \meta{$\theta$} around the center from that point. +This is the fundamental method for drawing arcs. All other methods are +converted to this or the point-sweep method. Even the point sweep form +is converted to this one for angles greater than 90 degrees. + +\item[\oarg{t}] The \textit{three-point form} draws the circular arc +which passes through all three points given, in the order given. +Internally, this is converted to two applications of the point-sweep +form. + +\item[\oarg{r}] The \textit{point-radius form} draws an arc on the +circle that \cs{circle}\oarg{r} would produce. The arc starts at the +point \meta{$p_0$} and ends at \meta{$p_1$}. Of the two possible arcs on +that circle, it produces the shorter one that covers an angle $\theta$ +from $0$ to $180$ degrees measured anticlockwise around the center +of the circle. A negative radius is a mathematical error, but the result +is the short arc on the other circle with a clockwise sense. + +\item[\oarg{q}] The \textit{alternative point-radius form} is the same as +\oarg{r} except it produces the longer arc, that covers an angle +$\theta$ between $180$ and $360$ degrees measured anticlockwise around +the center of the circle. A negative radius is a mathematical error, but +the result is the longer arc on the other circle with a clockwise sense. +\end{description} + +For both options \oarg{r} and \oarg{q} the angle is computed and then +the point-sweep method is used. If the absolute value of the radius is +less than half the distance between the points, then no such arc exists. +In this case, the angle is just set equal to $\pm180$ degrees (as if the +radius were changed to half the distance). + +\begin{cd}\pagelabel{sector} +\cs{sector}\marg{\meta{$c$},\meta{$r$},\meta{$\theta_1$},\meta{$\theta_2$}}% +\index{sector@\cs{sector}}% +\end{cd} + +This figure macro produces the sector of the circle with center at the +point \meta{$c$} and radius \meta{$r$}, from the angle \meta{$\theta_1$} +to the angle \meta{$\theta_2$}. Both angles are measured in degrees +anticlockwise from the direction parallel to the $x$ axis. The sector +forms a closed path. \emph{Note}: \cs{sector} and \cs{arc}\oarg{p} have +the same parameters, but \emph{in a different order}.% + \footnote{This apparently was unintended, but we now have to live + with it so as not to break existing \file{.tex} files.} + + +\begin{cd}\pagelabel{ellipse} +\cs{ellipse}\oarg{\meta{$\theta$}}\marg{\meta{$c$},\meta{$r_x$},\meta{$r_y$}}% +\index{ellipse@\cs{ellipse}}% +\end{cd} + +This figure macro produces an ellipse with the $x$ radius \meta{$r_x$} +and $y$ radius \meta{$r_y$}, centered at the point \meta{$c$}. The +optional parameter \meta{$\theta$} provides a way of rotating the +ellipse by \meta{$\theta$} degrees anticlockwise around its center. +Ellipses may also be created by differentially scaling a circle and +perhaps rotating the result. See subsection~\ref{transformation}. + + +When dealing with arcs and circles, it is useful to work in polar +coordinates: + +\begin{cd}\pagelabel{plr} +\cs{plr}\marg{(\meta{$r_0$},\meta{$\theta_0$}),% + (\meta{$r_1$},\meta{$\theta_1$}), $\ldots$}% +\index{plr@\cs{plr}}% +\end{cd} + +The macro \cs{plr} causes \MF{} to replace the specified list of polar +coordinate pairs by the equivalent list of rectangular (cartesian) +coordinate pairs. Through \cs{plr}, commands designed for rectangular +coordinates can be applied to data represented in polar coordinates. It +must be cautioned that this wholesale conversion of a list applies only +to commands that take a list consisting of an arbitrary number of +points, such as \cs{polyline}. + +The effect of \cs{plr} is to apply a \MF{} command, \gbc{polar}, to each +point in the list, producing a new list. This \MF{} command can also be +used separately in any situation where a single \MF{} point is required. For +example, to connect the point $(2,3)$ to the point with polar +coordinates $(1, 135)$ write +\begin{verbatim} +\polyline{(2,3),polar(1,135)} +\end{verbatim} + +This last circle-producing macro I wrote for my own use. It produces a +circle associated with the hyperbolic geometry of a disk or a +half-plane. + +\begin{cd}\pagelabel{pshcircle} +\cs{pshcircle}\marg{\meta{center},\meta{radius}}\\ +\cs{pshcircle}*\marg{\meta{center},\meta{radius}}% +\index{pshcircle@\cs{pshcircle}}% +\end{cd} + +This produces the circle whose hyperbolic center is at \meta{center} and +whose pseudohyperbolic radius is \meta{radius}. This all takes place +inside the circle with center $(0,0)$ and radius $1$ (the \emph{unit +circle}). The \meta{center} is required to be inside the unit circle and +the \meta{radius} is required to be less than $1$. + +The star-form is for the \emph{upper half-plane}, which is the set of +points with positive $y$-coordinate In this case, the \meta{center} must +be in the upper half-plane and the \meta{radius} must still be less than +$1$. If you are not versed in hyperbolic geometry, be warned that the +actual diameter of the resulting circle is on the order of $2y/(1-R)$, +where $R$ is the \meta{radius}. This can be quite large even for modest +values of $R$ and $y$. + + +\subsection{Curves}\label{curves} + +\begin{cd}\pagelabel{curve} +\cs{curve}\oarg{\meta{tension}}\marg{\meta{$p_0$},\meta{$p_1$},$\ldots$}\\ +\cs{cyclic}\oarg{\meta{tension}}\marg{\meta{$p_0$},\meta{$p_1$},$\ldots$}\\ +\cs{closedcurve}\oarg{\meta{tension}}\marg{\meta{$p_0$},\meta{$p_1$},$\ldots$}% +\index{curve@\cs{curve}}% +\index{cyclic@\cs{cyclic}} +\index{closedcurve@\cs{closedcurve}}% +\end{cd} + +These figure macros produce a smooth path through the specified points, +in the specified order. It is `smooth' in two ways: it never changes +direction abruptly (no `corners' or `cusps' on the curve), and it tries +to make turns that are not too sharp. This latter property is acheived +by specifying (to \MF{}) that the tangent to the curve at each listed +point is to be parallel to the line from that point's predecessor to its +successor. The \cs{cyclic} variant arranges for the last point to be +connected (smoothly) to the first, and produces a closed \MF{} B\'ezier +curve. The command \cs{closedcurve} is an alias for \cs{cyclic}. + +The optional \meta{tension} influences \emph{how} smooth the curve is. +The special value \mfc{infinity} (in fact, usually anything greater than +about $10$), makes the curve not visibly different from a polyline. The +higher the value of tension, the sharper the corners on the curve and +the flatter the portions in between. \CMF{} requires the tension to be +larger than $0.75$. The default value of the tension is $1$ when \mfp{} is +loaded, but that can be changed with the following command. + +\begin{cd}\pagelabel{settension} +\cs{settension}\marg{\meta{num}}% +\index{settension@\cs{settension}} +\end{cd} + +This sets the default tension for all commands that take an optional +tension parameter. + +Sometimes one would like a convex set of points to produce a convex +curve. This will not always be the case with \cs{curve} or \cs{cyclic}. +You can verify this with the following example, where the list of points +traces a rectangle: +\begin{verbatim} +\cyclic{(0,0),(0,1),(1,1),(2,1),(2,0),(0,0)} +\end{verbatim} +To produce a convex curve, use one of the following: + +\begin{cd}\pagelabel{convexcurve} +\cs{convexcurve}\oarg{\meta{tension}}\marg{\meta{$p_0$},\meta{$p_1$},$\ldots$}\\ +\cs{convexcyclic}\oarg{\meta{tension}}\marg{\meta{$p_0$},\meta{$p_1$},$\ldots$}\\ +\cs{closedconvexcurve}\oarg{\meta{tension}}\marg{\meta{$p_0$},\meta{$p_1$},$\ldots$}% +\index{convexcurve@\cs{convexcurve}}% +\index{convexcyclic@\cs{convexcyclic}}% +\index{closedconvexcurve@\cs{closedconvexcurve}}% +\end{cd} + +These figure macros can be used even if the list of points is not +convex, and the result will be convex where possible. The third one is +an alias for for the second one. + +\medskip +Occasionally it is necessary to specify a sequence of points with +\emph{increasing} $x$-coordinates and draw a curve through them. One +would then like the resulting curve both to be smooth \textit{and} to +represent a function (that is, the curve always has increasing $x$ +coordinate, never turning leftward). This cannot be guaranteed with the +\cs{curve} command unless the tension is \texttt{infinity}. + +\begin{cd}\pagelabel{fcncurve} +\cs{fcncurve}\oarg{\meta{tension}}\marg{($x_0$,$y_0$),($x_1$,$y_1$),$\ldots$}% +\index{fcncurve@\cs{fcncurve}}% +\end{cd} + +This figure macro produces a curve through the points specified. If the +points are listed with increasing (or decreasing) $x$ coordinates, the +curve will also have increasing (resp., decreasing) $x$ coordinates. The +\meta{tension} is a number greater than $1/3$ which controls how tightly +the curve is drawn. Generally, the larger it is, the closer the curve is +to the polyline through the points. The default tension is that set with +\cs{settension}, initially $1$. For those who know something about +\MF{}, this `tension' is not the same as the \MF{} notion of tension +(the tension in the \cs{curve} command), but it functions in a similar +fashion. In this case it can actually be any positive number, but only +values greater than $1/3$ guarantee the property of never doubling back. + +\begin{cd}\pagelabel{turtle} +\cs{turtle}\marg{\meta{$p_0$},\meta{$v_1$},\meta{$v_2$},$\ldots$}% +\index{turtle@\cs{turtle}}% +\end{cd} + +This figure macro produces a a sequence of line segments starting from +the point \meta{$p_0$}, and extending along the (2-dimen\-sional vector) +displacement \meta{$v_1$}. The next segment is from the previous +segment's endpoint, along displacement \meta{$v_2$}. This continues for +all listed displacements, a process similar to `turtle graphics'. + + +\subsection{Bar charts and pie charts}\label{charts} + +\begin{cd}\pagelabel{barchart} +\cs{barchart}\oarg{\meta{start},\meta{sep},\meta{r}}% + \marg{\meta{h-or-v}}\marg{\meta{list}}\\ +\cs{bargraph}\dots\\ +\cs{gantt}\dots\\ +\cs{histogram}\dots\\ +\cs{mfpbarchart}\dots\\ +\cs{mfpbargraph}\dots\\ +\cs{mfpgantt}\dots\\ +\cs{mfphistogram}\dots +\index{barchart@\cs{barchart}}% +\index{bargraph@\cs{bargraph}}% +\index{histogram@\cs{histogram}}% +\index{gantt@\cs{gantt}}% +\end{cd} + +The macro \cs{barchart} computes a bar chart or a Gantt chart. It does +not draw the bars, but only defines their rectangular paths which the +user may then draw or fill or both using the \cs{chartbar} macros (see +below). Since bar charts have many names, \cs{bargraph} and +\cs{histogram} are provided as synonyms. The macro \cs{gantt} is also a +synonym; whether a Gantt chart or bar chart is created depends on the +data. + +Since \cs{barchart} never draws anything, there is no particular reason +it needs to be inside an \env{mfpic} environment. Starting with version +0.9 of \mfp{} this is no longer required, but the command name +\cs{mfpbarchart} must be used outside (in case some other package also +defines \cs{barchart}). One can use any of the four synonyms listed that +start with `\cs{mfp}'. The command to draw the bars is still required to +be inside an \env{mfpic} environment. + +\meta{h-or-v} should be \texttt{v} if you want the ends of the bars to +be measured vertically from the $x$-axis, or \texttt{h} if they should +be measured horizontally from the $y$-axis. \meta{list} should be a +comma-separated list of numbers and ordered pairs giving the +end(s) of each bar. A number $c$ is interpreted as the pair $(0,c)$; a +pair $(a,b)$ is interpreted as an interval giving the ends of the bar +(for Gantt diagrams). The rest of this description refers to the +\texttt{h} case; the \texttt{v} case is analogous. + +By default the bars are 1 graph unit high (thickness), from $y = n-1$ to +$y = n$. Their width and location are determined by the data. The +optional parameter consists of three numeric parameters separated by +commas. \meta{start} is the $y$-coordinate of the bottom edge of the +first bar, \meta{sep} is the distance between the bottom edges of +successive bars, and \meta{r} is the fraction of \meta{sep} occupied by +each bar. The default behavior corresponds to \texttt{[0,1,1]}. In +general, bar number $n$ will be from $y = \meta{start} + +(n-1)*\meta{sep}$ to $y = \meta{start} + (n-1 + \meta{r})*\meta{sep}$ + +Notice the bars are numbered in order from bottom to top. You can +reverse them by making \meta{sep} negative, and making \meta{start} the +top edge of the first bar. + +The fraction \meta{r} should be between $-1$ and $1$. A negative value +reverses the direction from the `leading edge' of the bar to the +`trailing edge'. For example, if one bar chart is created with +\begin{ex} + \cs{barchart}\oarg{1,1,-.4}\marg{h}\marg{$\ldots$} +\end{ex} +and another with +\begin{ex} + \cs{barchart}\oarg{1,1,.4}\marg{h}\marg{$\ldots$} +\end{ex} +both having the same number of bars, then the first will have its first +bar from $y = 1$ to $y = 1 -.4 = .6$, while the second will have its +first bar on top of that one, from $1$ to $1 + .4$. Similarly the next +bars will be above and below $y=2$, etc. This makes it easy to draw bars +next to one another for comparison. + +\begin{cd}\pagelabel{chartbar} +\cs{chartbar}\marg{\meta{num}}\\ +\cs{graphbar}\marg{\meta{num}}\\ +\cs{histobar}\marg{\meta{num}}\\ +\cs{ganttbar}\marg{\meta{num}}% +\index{chartbar@\cs{chartbar}}% +\index{graphbar@\cs{graphbar}}% +\index{histobar@\cs{histobar}}% +\index{ganttbar@\cs{ganttbar}}% +\end{cd} + +The figure macro \cs{chartbar} (synonyms \cs{graphbar}, \cs{ganttbar}, +and \cs{histobar}) takes a number from $1$ to the number of elements in +the list of data of the most recent \cs{barchart} command and produces +the corresponding rectangular path computed by that command. This +behaves just like any other figure macro, and the prefix macros from +section~\ref{rendering} may be used to give adjacent bars contrasting +colors, fills, etc. + + +\begin{cd}\pagelabel{piechart} +\cs{piechart}\oarg{\meta{dir}\meta{angle}}\marg{\meta{$c$},\meta{$r$}}% + \marg{\meta{list}}\\ +\cs{mfppiechart}\dots +\index{piechart@\cs{piechart}}% +\end{cd} + +The macro \cs{piechart} also does not draw anything, but computes the +\cs{piewedge} regions described below. The first part of the optional +parameter, \meta{dir}, is a single letter to indicate a direction: +`\texttt{c}' for \emph{clockwise} or `\texttt{a}' for \emph{anticlockwise}. +The \meta{angle} is the angle in degrees of the starting edge of the +first wedge. The defaults correspond to \oarg{c90}, which means the +first wedge starts at 12~o'clock and proceeds clockwise. + +The first required argument contains the center \meta{$c$} and radius +\meta{$r$} of the chart. The second required argument is the list of +data: positive numbers separated by commas. + +Since this command never actually draws anything, only defining the +wedges, it makes sense to heave it available outside the drawing +environment. Starting with version 0.9 of \mfp{} that is the case, but +the command name is \cs{mfppiechart} (to avoid a name clash with some +other package's \cs{piechart} command). The command to draw wedges +(\cs{piewedge}, see below) is still required to be inside an \env{mfpic} +environment. + +\begin{cd}\pagelabel{piewedge} +\cs{piewedge}\oarg{\meta{spec}\meta{trans}}\marg{\meta{num}}% +\index{piewedge@\cs{piewedge}}% +\end{cd} + +This figure macro takes a number from $1$ to the number of elements in +the list of data of the most recent \cs{piechart} command and produces +the corresponding wedge-shaped path computed by that command. By +default, the path is positioned as computed by that \cs{piechart} +command, but The optional argument to \cs{piewedge} can override this. +The parameter \meta{spec} is a single letter, which can be \texttt{x}, +\texttt{s} or \texttt{m}. The \texttt{x} stands for \emph{exploded} and +it means the wedge is moved directly out from the center of the pie a +distance \meta{trans}. \meta{trans} should then be a pure number and is +interpreted as a distance in graph units. The \texttt{s} stands for +\emph{shifted} and in this case \meta{trans} should be a pair of the +form \texttt{(\meta{dx},\meta{dy})} indicating the wedge should be +shifted \meta{dx} horizontally and \meta{dy} vertically (in graph +units). The \texttt{m} stands for \emph{move to}, and \meta{trans} is +then the absolute coordinates \texttt{(\meta{x},\meta{y})} in the graph +where the point of the wedge should be placed. + + +\section{Colors in \mfp{}.}\label{colors} + +\subsection{\CMP{} color functions}\label{mpcolors} + +Because of changes to color handling with \MP{} 1.000, we will have to +give two descriptions of some operations. For brevity, we will refer to +\MP{} versions before the addition of the \kw{cmykcolor} data type as +`early' \MP{} and the versions afterward as `recent' \MP{}. Early \MP{} +actually ended with version 0.642. When development resumed, beta test +versions began with 0.900. Any version 0.900 or later qualifies as +`recent'. + +In early \MP{}, the only \kw{color} data type is a triple of numbers +like \mfc{(1,.5,.5)}, with the components between 0 and 1, representing +red, green and blue levels, respectively. White is given by +\mfc{(1,1,1)} and black by \mfc{(0,0,0)}. Recent \MP{} has the +\kw{color} data type (refered to as either \kw{color} or \kw{rgbcolor}) +as well as the \kw{cmykcolor} type. A \kw{cmykcolor} is a quadruple of +numbers like \mfc{(1,.2,0,.3)}, with components between 0 and 1 +representing levels of cyan, magenta, yellow and black. White is +represented by \mfc{(0,0,0,0)}. While black can be obtained in several +ways,\mfc{(0,0,0,1)} is the simplest. + +\CMP{} also has \kw{color} variables (and \kw{cmykcolor} variables) and +several have been predefined. The colors \mfc{red}, \mfc{green}, +\mfc{blue}, \mfc{white} and \mfc{black} are built in to \MP{} and are of +type \kw{rgbcolor}. Colors \gbc{cyan}, \gbc{magenta} and \gbc{yellow} +are defined by \mfp{}'s \MP{} support macros to be \kw{cmykcolor}. In +addition, \mfp{} defines \gbc{cmykblack}, \gbc{cmykwhite}, +\gbc{rgbblack}, \gbc{rgbwhite}, \gbc{grayscaleblack} and +\gbc{grayscalewhite}. These give black and white in the indicated data +type (grayscale being a numeric: $0$ for black, $1$ for white). + +All the names in the \LaTeX{} \prog{color} package's \file{dvipsnam.def} +have also been predefined by \mfp{} as color variable names. Since \MP{} +allows color expressions, colors may be added (as long as they are the +same type) and multiplied by numerics. Multiplication by a number +between $0$ and $1$ darkens a \kw{rgbcolor}, but lightens a +\kw{cmykcolor}. + +Moreover, several \MP{} color functions have been defined in +\file{grafbase.mp}. These have the same names as the color models. +Strictly speaking, it is never necessary to use these in recent \MP{}. +However, since \MF{} and early \MP{} don't have a data type consisting +of quadruples, and \MF{} doesn't have one for triples, these functions +allow the same \mfp{} code to be used for all three figure processors. +These functions are defined to convert to a usable data type, (which may +be ignored in \MF{}). + +\begin{cd} +\mfc{cmyk($c$,$m$,$y$,$k$)}% +\index{cmyk@\mfc{cmyk($c$,$m$,$y$,$k$)}} +\end{cd} + +In early \MP{}, this converts a cmyk color specification to \MP{}'s +native rgb. For example, the command \mfc{cmyk(1,0,0,0)} yields +\mfc{(0,1,1)}, which is the rgb equivalent of cyan. In recent \MP{} this +produces the \kw{cmykcolor} with the given components. That is, +\gbc{cmyk(1,0,0,0)} simply produces $(1,0,0,0)$, the cmyk coding for +cyan. + +\begin{cd} +\mfc{gray($g$)}% +\index{gray@\mfc{gray($g$)}} +\end{cd} + +In early \MP{}, this converts a numeric $g$ (designating a level of +gray) to the corresponding multiple of white: \mfc{($g$,$g$,$g$)}. In +recent \MP{}, commands to draw paths or pictures in a particular color +will accept a \kw{numeric} parameter instead of \kw{color} or +\kw{cmykcolor}, so in recent \MP{} this command simply returns the given +numeric $g$. + +\begin{cd} +\mfc{named(\meta{name})}, +\mfc{rgb($r$,$g$,$b$)}% +\index{named@\mfc{named(\meta{name})}}% +\index{rgb@\mfc{rgb($r$,$g$,$b$)}} +\end{cd} + +These are essentially no-ops. However; \mfc{rgb()} will truncate the +arguments to the 0--1 range, and set an unknown argument to 0. An +unknown \meta{name} is converted to \mfc{black} (in the appropriate +color model if \meta{name} is an unknown color variable, otherwise rgb +black). + +\begin{cd} +\mfc{RGB($R$,$G$,$B$)}% +\index{RGB@\mfc{RGB($R$,$G$,$B$)}} +\end{cd} + +Converts an RGB color specification to rgb. It divides each component by +255, and performs the same truncations as \gbc{rgb()}. The RGB model +consists of a triple of numbers between 0 and 255. Originally, the model +required they be integers. However, since they are converted to +fractions anyway, it doesn't matter in this command. + +\medskip +As an example of the use of these functions, in early \MP{} one could +conceivable write: +% +\begin{verbatim} +\draw[0.5*RGB(255,0,0)+0.5*cmyk(1,0,0,0)]\circle{(0,0),1} +\end{verbatim} +% +to have a circle drawn in a color halfway between red and cyan (which +turns out to be the same as \gbc{gray(0.5)}). In recent \MP{}, however, +this would be an error, as one cannot add two different data types +(\kw{rgbcolor} and \kw{cmykcolor}). So \mfp{} supplies conversion functions. + +\begin{cd} +\mfc{makecmyk \meta{clr}}\\ +\mfc{makergb \meta{clr}}\\ +\mfc{makegray \meta{clr}}% +\index{makecmyk@\mfc{makecmyk}}% +\index{makergb@\mfc{makergb}}% +\index{makegray@\mfc{makegray}} +\end{cd} + +In recent \MP{}, the \meta{clr} can be a known color name, a constant +of type \kw{numeric}, \kw{rgbcolor}, or \kw{cmykcolor}, or the result of +a color function. Then \mfc{makecmyk} returns the \kw{cmykcolor} +equivalent, and \mfc{makergb} returns the \kw{rgbcolor} equivalent (a +\kw{numeric} \meta{clr} is interpreted as a grayscale color). Unknown +colors produce a black in the appropriate model. Then one can use +% +\begin{verbatim} +\draw{.5*RGB(255,0,0) + .5*makergb cmyk(1,0,0,0)}\circle{(0,0),1} +\end{verbatim} +% +And if one didn't know that \mfc{RGB} returned an \kw{rgbcolor}, one +could also write \verb$makergb RGB(255,0,0)$ to be sure to get an +\kw{rgbcolor}. + +The first two commands are never necessary in early \MP{}, but they are +still defined: they simply return the given color if it is a known +argument of type \kw{color}, or apply the function \gbc{gray()} is it is +\kw{numeric}, and return black for an unknown name. + +The last one \gbc{makegray} converts any color to a numeric, and then +returns either that number (recent \MP) or that multiple of \mfc{white} +(early \MP). In \MF{}, all three pass the (presumably numeric) argument +\meta{clr} unchanged. + +All three functions return some kind of black if \meta{clr} is not some +kind of color, or has an unknown value. + + +\subsection{Establishing \mfp{} default colors}\label{defaultcolors} + +\begin{cd}\pagelabel{drawcolor} +\cs{drawcolor}\oarg{\meta{model}}\marg{\meta{colorspec}}\\ +\cs{fillcolor}\oarg{\meta{model}}\marg{\meta{colorspec}}\\ +\cs{hatchcolor}\oarg{\meta{model}}\marg{\meta{colorspec}}\\ +\cs{pointcolor}\oarg{\meta{model}}\marg{\meta{colorspec}}\\ +\cs{headcolor}\oarg{\meta{model}}\marg{\meta{colorspec}}\\ +\cs{tlabelcolor}\oarg{\meta{model}}\marg{\meta{colorspec}}\\ +\cs{backgroundcolor}\oarg{\meta{model}}\marg{\meta{colorspec}}% +\index{drawcolor@\cs{drawcolor}}% +\index{fillcolor@\cs{fillcolor}}% +\index{hatchcolor@\cs{hatchcolor}}% +\index{pointcolor@\cs{pointcolor}}% +\index{headcolor@\cs{headcolor}}% +\index{tlabelcolor@\cs{tlabelcolor}}% +\index{backgroundcolor@\cs{backgroundcolor}}% +\end{cd} + +These macros set the default color for various drawing elements. Any +curve (with one exception, those drawn by \cs{plotdata}), whether solid, +dashed, dotted, or plotted in symbols, will be in the color set by +\cs{drawcolor}. Set the color used by \cs{gfill} with \cs{fillcolor}. +For all the hatching commands use \cs{hatchcolor}. For the \cs{point}, +\cs{plotsymbol} and \cs{gridpoints} commands use \cs{pointcolor}, and +for arrowheads, \cs{headcolor}. One can set the color used by +\cs{gclear} with \cs{backgroundcolor} (the same color will also be used +in the interior of unfilled points that are drawn with \cs{point}) and, +when \opt{mplabels} is in effect, the color of labels can be set with +\cs{tlabelcolor}. + +The optional \meta{model} may be one of \texttt{rgb}, \texttt{RGB}, +\texttt{cmyk}, \texttt{gray}, and \texttt{named}. The \meta{colorspec} +depends on the model, as outlined below. Each of these commands sets a +corresponding \MP{} color variable with the same name (except +\cs{backgroundcolor} sets the color named \mfc{background}). Thus, after +\texttt{drawcolor} has been set, one can issue the command +\cs{fillcolor}\marg{drawcolor} to fill with the same color. + +As previously discussed, all these colors are initially set to +\mfc{black} except \mfc{background} is set to \mfc{white}. + +If the optional \meta{model} argument is omitted, the color +specification may be any expression recognized as a color by \MP{}. It +is highly recommended (for portability) that one use either a predefined +name or one of the color functions of the previous section. + +When the optional \meta{model} is specified in the color setting +commands, it determines the format of the color specification as in +figure~\ref{fig:colorspecs}. + +\begin{figure}[hbt] +\halign{\quad\texttt{#}\hfil\quad&#\hfil\cr +\omit\quad{\slshape Model:}\hfil& {\slshape Specification:}\cr +rgb & Three numbers in the range 0 to 1 separated by commas.\cr +RGB & Three numbers in the range 0 to 255 separated by commas.\cr +cmyk & Four numbers in the range 0 to 1 separated by commas.\cr +gray & One number in the range 0 to 1, with 0 indicating + black, 1 white.\cr +named & A \MP{} color variable name either predefined by + \mfp{} or by the user.\cr} +\caption{Color specifications} +\label{fig:colorspecs} +\end{figure} + +\pagebreak[3] +\Mfp{} translates the command: +\begin{verbatim} +\fillcolor[cmyk]{1,.3,0,.2} +\end{verbatim} +into the equivalent of: +\begin{verbatim} +\fillcolor{cmyk(1,.3,0,.2)}. +\end{verbatim} +Note that when the optional model is specified, the color specification +must \emph{not} be enclosed in parentheses. Note also that each model +name is the name of a color function described in the previous +subsection. That is how the models are implemented internally. One sees +from this that the optional argument is never necessary. It's there only +to make the \LaTeX{} user comfortable. + + +\subsection{Defining a color name}\label{colorname} + +\begin{cd}\pagelabel{mfpdefinecolor} +\cs{mfpdefinecolor}\marg{\meta{name}}\marg{\meta{model}}\marg{\meta{colorspec}}% +\index{mfpdefinecolor@\cs{mfpdefinecolor}} +\end{cd} + +This defines a color variable \meta{name} for later use, either in the +commands \cs{drawcolor}, etc., or in the optional parameters to +\cs{draw}, etc. The name can be used alone or in the \texttt{named} model. +The mandatory \meta{model} and \meta{colorspec} are as above. + +\medskip +A final caution, the colors of an \mfp{} figure are stored in the +\file{.mp} output file, and are not related to colors used or defined by +the \LaTeX{} \prog{color} package. In particular a color defined only by +\LaTeX{}'s \cs{definecolor} command will remain unknown to \mfp{}. +Conversely, \LaTeX{} commands will not recognize any color defined only +by \cs{mfpdefinecolor}. + + +\subsection{\CMF{} colors}\label{MFcolor} + +\CMF{} was never meant to understand colors, but it certainly can be +taught the difference between black and white and, to a limited extent, +various grays. Starting with version 0.7, \mfp{} will not generate +an error when a color-changing command is used under the \opt{metafont} +option. Instead, when possible, the variables that represent colors in +\MP{} will be converted to a numeric value between 0 and 1 in \MF{}. When +possible (for example, when a region is filled) the numeric will be +interpreted as a gray level and shading (see subsection~\ref{filling}) +will be used to approximate the gray. In other cases (drawing or dashing +of curves, placing of points or symbols, filling with a pattern of hatch +lines) the number will be interpreted as black or white: a value less +than 1 will cause the figure to be rendered in black, while a value +equal to 1 (white) will cause pixels corresponding to the figure to be +erased. + +This depends on adhering to certain restrictions. \CMF{}'s syntax +does not recognize a triple of numbers as any sort of data structure, +but it does allow \emph{commands} to have any number of parameters in +parentheses. So colors must be specified using the color commands such +as \gbc{rgb(1,1,0)} or color names such as \gbc{yellow}, and never as a +bare triple. Also, as currently written, the color names defined in +\file{dvipsnam.mp} are not defined in \MF{}. With these provisions the +same \mfp{} code can often produce either gray scale \MF{} pictures or +\MP{} color pictures depending only on the \opt{metapost} option. + +The commands \cs{shade} and \cs{gfill}\oarg{gray(.75)} (see +subsection~\ref{filling} for their meaning) will produce a similar shade +of gray, but there is a difference. The first simply adds small dots on +top of whatever is already drawn. The second, however, tries to simulate +the \MP{} effect, which is to cover up whatever is previously drawn. +Therefore, it first erases all affected pixels before adding the dots to +simulate gray. In particular, \cs{gfill}\oarg{white} should have the +same effect as \cs{gclear}. + + +\section{Modifying the figures.}\label{modifier} + +Some \mfp{} macros operate by \emph{modifying} a figure macro: if you +want to turn an open arc into a closed figure by adding a straight line, +you can write: \cs{lclosed}\cs{arc}\marg{(0,0),(1,0),45}. These are +always prefixed to some figure drawing command, and apply only to the +next following figure macro provided that only other prefix commands +intervene. This is a rather long section, but even more modification +prefixes are documented in subsection~\ref{transformation}. + +The combination of a modifying macro, followed by a figure macro, can +usually be thought of as a new figure macro, to which further prefixes +might be prepended. + +More precisely: all prefix macros have an \emph{input} path, an +\emph{output} path, and a \emph{side effect}. The input is the path that +is output by the \emph{following} prefix or figure macro. The output is +either the same as the input or a modification of it. The side effect +might be a drawing or filling of the path or the addition of an +arrowhead. + +We list here a classifications of prefix and figure macros that is +useful for understanding the \mfp{} system. + +\begin{description} + +\item[Figure macros.] These\index{figure macro} take no input path; they + must come last in a sequence. They output the path they were + designed to produce. Examples are \cs{circle}, \cs{rect} and + \cs{polygon}. If they have no prefixes, or are preceded only by + appending macros (see next), they invoke a default rendering of the + path (usually a drawing as a solid stroke) as the side effect. + +\item[Apending macros] These\index{prefix macro} pass their input + unchanged as their output. Their side effect is the appending of + some object such as an arrow head or tail. Currently only the + various prefix macros whose names begin with \texttt{arrow} are + appending macros (see subsection~\ref{arrows}). But \cs{reverse}, + which technically modifies a path and has no side effect, is coded + as an appending macro so that it will work correctly with arrows. + Think of it as `appending' a new direction. + +\item[Rendering macros] These\index{prefix macro} pass their + input unchanged as their output. They have the side effect of adding + or subtracting ink from a picture in the shape of the input path. + Examples are \cs{draw}, \cs{dotted}, \cs{gfill} and \cs{gclip}. + +\item[Modifying macros] These\index{prefix macro} output the result of + applying their intended modification to the input path. Examples are + macros that close the path if it was open, macros that apply a + transformation such as a rotation, and macros that return only a + part of a path. If they have no prefixes, or are preceded only by + appending macros (see above), they also invoke a default rendering + of the output path (usually a drawing as a solid stroke of the + modified path) as the side effect. + +\end{description} + +\subsection{Closure of paths}\label{closure} + +It should be pointed out that the closure macros will leave already +closed paths unchanged, so it is always safe to add one when uncertain. +Moreover, if the path is not closed but the endpoints are identical, +\cs{lclosed} and \cs{bclosed} will close it without adding any path segment. + + +\begin{cd}\pagelabel{lclosed} +\cs{lclosed}$\ldots$\\ +\cs{bclosed}\oarg{\meta{tens}}$\ldots$\\ +\cs{sclosed}\oarg{\meta{tens}}$\ldots$% +\index{lclosed@\cs{lclosed}} +\index{bclosed@\cs{bclosed}}% +\index{sclosed@\cs{sclosed}} +\end{cd} + +These modifying macros all turn an open path into a closed one. If the +path is already closed, they do nothing. + +\cs{lclosed} makes an open path into a closed path by adding a line +segment between the endpoints of the path. In the special case where +the path ends exactly where it begins, all \cs{lclosed} does is change +the type of the path from open to closed. + +The \cs{bclosed} macro is similar to \cs{lclosed}, except that it closes +an open path smoothly by drawing a B\'ezier curve. A B\'ezier is \MF{}'s +natural way of connecting points into a curve, and \cs{bclosed} is the +simplest and most efficient closure next to \cs{lclosed}. Moreover it +usually gives a reasonably aesthetic result. Sometimes, however, one +might wish a tighter connection. If that is the case, use the optional +argument with a value of the tension \meta{tens} greater than $1$, the +default. The command \cs{settension} (see subsection~\ref{curves}) can +be used to change the default. + +\cs{sclosed} closes the curve by mimicking the definition of the +\cs{curve} command. That command tries to force the curve to pass +through the $n$th point in a direction parallel to the line from point +$(n-1)$ to point $(n+1)$. In order to close a curve in this way, the +direction at the two endpoints often has to be changed, and this changes +the shape of the first and last segments of the curve. Use \cs{bclosed} +if you don't wish this to happen. However, \cs{sclosed}\cs{curve} +produces a result almost identical to \cs{cyclic} given the same points +and tension values. The optional tension argument is as in the +\cs{bclosed} command. + +There are two other closure commands but, because they are associated +with particular types of paths (splines), we delay their discussion +until those are discussed (subsection~\ref{splines}). + +\begin{cd}\pagelabel{makesector} +\cs{makesector}\cs{arc}[\meta{fmt}]\marg{\meta{spec}}% +\index{makesector@\cs{makesector}} +\end{cd} + +The modifying macro \cs{makesector} can be applied to any path, but its +name makes sense (and its action is predictable) only if that path is an +arc. It appends line segments from the center of the arc's circle to the +ends of the arc, producing a closed path. It is useful if one doesn't +know where the center of the arc is (a required parameter of +\cs{sector}). It works by selecting the first point, a middle point, and +the last point of the following path, then calculates the center of the +circle through those three points. + + +\subsection{Reversal, connection and other path modifications}% +\label{reversal} + +\begin{cd}\pagelabel{reverse} +\cs{reverse}$\ldots$% +\index{reverse@\cs{reverse}} +\end{cd} + +This modifies the following path by reversing its sense. This will +affect the direction of arrows: bi-directional arrows can be coded with +\cs{arrow}\cs{reverse}\cs{arrow}$\ldots$, where the leftmost \cs{arrow} +prefix applies to the \emph{reversed} path. The order of endpoints for +the following \env{connect} environment will also be affected. + + +\begin{cd}\pagelabel{connect} +\cs{connect} $\ldots$ \cs{endconnect}% +\index{connect@\cs{connect}}% +\index{endconnect@\cs{endconnect}} +\end{cd} + +The macro \cs{connect} produces a connected path by joining all the +paths following it up to the matching \cs{endconnect} command. Line +segments are added from the end of one path to the start of the next. +The whole group acts as one figure macro, permitting any prefix macros +to come before. + +In \LaTeX{}, instead of this pair of macros, an environment named +\env{connect} may be used. For example +\begin{verbatim} +\lclosed +\begin{connect} + \curve{(2,1),(1,2),(0,1)} + \polyline{(0,0),(2,0)} +\end{connect} +\end{verbatim} +produces a closed figure consisting of one smooth curve and three line +segments: the segment produced by \cs{polyline}, the segment added by +the \env{connect} environment, and the segment added by \cs{lclosed}. + + +\begin{cd}\pagelabel{partpath} +\cs{partpath}\marg{\meta{frac1},\meta{frac2}}\dots\\ +\cs{subpath}\marg{\meta{num1},\meta{num2}}\dots\\ +\cs{trimpath}\marg{\meta{dim$_1$},\meta{dim$_2$}}\dots\\ +\cs{trimpath}\marg{\meta{dim}}\dots% +\index{partpath@\cs{partpath}}% +\index{subpath@\cs{subpath}}% +\index{trimpath@\cs{trimpath}}% +\end{cd} + +These macros modify the following path by producing only a part of it. In +\cs{partpath} the parameters \meta{frac1} and \meta{frac2} should be +numbers between 0 and 1. The path produced travels the same course as +the path that follows, but starts at the point that is the fraction +\meta{frac1} of the original length along it, and ends at the point +\meta{frac2} of its original length. If \meta{frac1} is greater than +\meta{frac2}, the sense of the path is reversed. In \cs{subpath}, the +two numbers should be between 0 and the number of B\'ezier segments in +the path. This is mainly for experienced \MF{}ers and provides an \mfp{} +interface to \MF{}'s `\mfc{subpath}' operation. + +The \cs{trimpath} macro takes two dimensions separated by commas and +trims those lengths off the initial and terminal ends of the following path. +Alternatively, it takes one dimension and and trims that length off of +both ends. If any of \meta{dim$_1$}, \meta{dim$_2$} or \meta{dim} is +missing, it is taken to be \dim{0pt}. This works by finding the points of +intersection between the path and circles around the endpoints with the given +dimensions as radii. If the path is shorter than either dimension, it +will not intersect either circle and nothing will be trimmed. Similar +problems can occur, at one end or the other, if the path is shorter than +the sum of the dimensions. + +\begin{cd}\pagelabel{parallelpath} +\cs{parallelpath}{\meta{dist}}$\ldots$ +\index{parallelpath@\cs{parallelpath}} +\end{cd} + +This modifying macro takes the following path and returns a path that +follows beside it, keeping a fixed distance \meta{dist} to the left. If +\meta{dist} is negative, it keeps to the right. Left or right is from +the point of view of a traveller following the given path from start to +finish. The distance is a pure number in \emph{graph} coordinates. Note: +this should be compared to the first optional argument of +\cs{doubledraw} (see subsection~\ref{drawing}), which requires an +absolute dimension like \dim{2pt}, even though it is implemented using +the internal code of \cs{parallelpath}. + +The calculation of the parallel path is approximate and rather +inefficient. It is likely to produce inexplicable small loops where it +tries to follow the inside of tight turns (radius less than +\meta{dist}). Actual corners, (which might be thought of as turns of +radius $0$) are usually detected and dealt with in a reasonable manner. +However, if the path is made up of segments of length \meta{dist} or +less, this is unlikely to work correctly at all. + +\begin{cd}\pagelabel{arccomplement} +\cs{arccomplement}\dots% +\index{arccomplement@\cs{arccomplement}} +\end{cd} + +This macro, to work properly, must be followed by an arc of a circle. It +produces the complementary arc. That is, it produces the circular arc, +which would, if appended to the following arc, complete the circle. The +complementary arc will have the same direction, clockwise or +anticlockwise, as the original. The arc that follows doesn't have to be +produced by \cs{arc}, as in the following example: +\begin{ex} +\cs{draw}\oarg{blue}\cs{arccomplement}\\ +\ \cs{draw}\oarg{red}\cs{partpath}\marg{0,.333}\\ +\ \cs{circle}\marg{(0,0),1} +\end{ex} +This will draw 1/3 of the circle in red and the rest in blue. + +\CMF{} cannot check if a path is really a circular arc. The \MF{} code, +like that of \cs{makesector} (see subsection~\ref{closure}), selects +three key points on the arc, then it produces the rest of the circle +much the same way as the internal code of \cs{arc}\oarg{t} (the three +point option for \cs{arc}). Thus, it will produce \emph{some} arc from +the end of any following path to its beginning (or a straight line if +the three chosen points happen to lie in a straight line). However, the +result needn't bear any significant relation to the original path. + + +\subsection{Arrows}\label{arrows} + +\begin{cd}\pagelabel{arrow} +\cs{arrow}\oarg{l\meta{headlen}}\oarg{r\meta{rotate}}% + \oarg{b\meta{backset}}\oarg{c\meta{color}}$\ldots$\\ +\cs{arrow*}\oarg{l\meta{headlen}}\oarg{r\meta{rotate}}% + \oarg{b\meta{backset}}\oarg{c\meta{color}}$\ldots$% +\index{arrow@\cs{arrow}} +\end{cd} + +This macro adds an arrowhead at the endpoint of the open path (or at the +last key point of the closed path) that follows. The optional parameter +\meta{headlen} determines the length of the arrowhead. The default is +the value of the \TeX{} dimension \cs{headlen}, initially \dim{3pt}. The +optional parameter \meta{rotate} allows the arrowhead to be rotated +anticlockwise around its point an angle of \meta{rotate} degrees. The +default is 0. The optional parameter \meta{backset} allows the arrowhead +to be `set back' from its original point, thus allowing (for example) +double arrowheads. This parameter is in the form of a \TeX{} +dimension---its default value is \dim{0pt}. If an arrowhead is both +rotated and set back, it is set back in the direction after the +rotation. The optional \meta{color} defaults to \gbc{headcolor}, +initially black. The optional parameters may appear in any order, the +indicated key character determining the meaning of a parameter. The key +letter \texttt{l} for `length' can be replaced by \texttt{s} for `size'. + +There is also a star-form: If \cs{arrow} is called as \cs{arrow*}, then +any part of the tip of the following curve that lies outside the +arrowhead shape is clipped off. Imagine a rectangle with one side +connecting the ends of the barbs and the opposite side passing through +the tip. Everything in that rectangle outside the arrowhead is erased, +so be careful using this (also see comments about \MP{}'s method of +`erasing' in the description of \cs{gclear} in +\cs{}subsection~\ref{filling}). One use of this is adding an arrowhead +to a figure rendered with \cs{doubledraw} (see the next section) or with +a rather large pen diameter (see section~\ref{parameters}). + +For the star-form to work, the head has to be added after the path is +drawn. What this means in practice is that the \cs{arrow*} command must +come before any drawing command in the list of prefixes. This is because +prefix macros add their elements to the result of everything that +follows. If you \cs{store} a curve in a path variable (see +subsection~\ref{transformation}), and draw the path and the arrowhead in +separate commands, then the arrow command must come \emph{after} the +drawing command. + +\begin{cd}\pagelabel{arrowhead} +\cs{arrowhead}\marg{\meta{symbol}}\oarg{l\meta{length}}\oarg{r\meta{rotate}}% + \oarg{b\meta{backset}}\oarg{c\meta{color}}$\ldots$\\ +\cs{arrowmid}\marg{\meta{symbol}}\oarg{l\meta{length}}\oarg{r\meta{rotate}}% + \oarg{f\meta{fraction}}\oarg{c\meta{color}}$\ldots$\\ +\cs{arrowtail}\marg{\meta{symbol}}\oarg{l\meta{length}}\oarg{r\meta{rotate}}% + \oarg{f\meta{forward}}\oarg{c\meta{color}}$\ldots$% +\index{arrowhead@\cs{arrowhead}}% +\index{arrowmid@\cs{arrowmid}}% +\index{arrowtail@\cs{arrowtail}} +\end{cd} + +These macros add some sort of symbol at different locations along a +path. The first adds an arrowhead, but the head can be any appropriately +designed symbol. It has been arranged that any of the symbols usable in +\cs{plotsymbol} (see subsection~\ref{points}) can be used: you can have +\gbc{Diamond}- or \gbc{Asterisk}-tipped arrows. The special symbol +\gbc{Arrowhead} produces the same shape as the head in the \cs{arrow} +command. In total eight special \meta{symbols} have been made available, +intended for use with \cs{arrowhead}, \cs{arrowmid} and \cs{arrowtail}. +Here is a list and description of all these symbols. +\begin{description} + \item[\gbc{Arrowhead}] The\index{Arrowhead@\gbc{Arrowhead}} shape that + would be drawn at the end of a path by \cs{arrow}. + \item[\gbc{Leftharpoon}] The\index{Leftharpoon@\gbc{Leftharpoon}} left + half of \gbc{Arrowhead}. + \item[\gbc{Rightharpoon}] The\index{Rightharpoon@\gbc{Rightharpoon}} + right half of \gbc{Arrowhead}. + \item[\gbc{Crossbar}] A\index{Crossbar@\gbc{Crossbar}} short + line crossing the path perpendicularly unless rotated. + \item[\gbc{Leftbar}] Essentially\index{Leftbar@\gbc{Leftbar}} the left + half of \gbc{Crossbar}. + \item[\gbc{Rightbar}] The\index{Rightbar@\gbc{Rightbar}} right half. + \item[\gbc{Lefthook}] An\index{Lefthook@\gbc{Lefthook}} open + semicircle with its open face in the direction of the path, added to + the left side of the path. + \item[\gbc{Righthook}] Like\index{Righthook@\gbc{Righthook}} + \gbc{Lefthook} but on the right side. +\end{description} +Here `left' and `right' are from the point of view of an observer facing +in the direction of the path. + +If the symbol is a closed path (see subsection~\ref{closure} for the +difference between a closed path and one that merely looks closed), the +head will be filled, otherwise its outline will be drawn. Thus +\cs{arrowhead}\marg{Diamond} draws an outline, and +\cs{arrowhead}\marg{SolidDiamond} draws a filled shape because +\gbc{Diamond} has been left open, while \gbc{SolidDiamond} has been +defined to be closed. + +It is possible, to get an outline drawn with the inside erased: just +place the solid version with color \mfc{background} (usually the same as +\mfc{white}) and then the outline version. This can produce a pleasing +result. But recall that the prefix macro nearest the figure macro is +executed first. For example: +% +\begin{verbatim} +\arrowmid{Circle}\arrowmid{SolidCircle}[cwhite]\polyline{(0,0),(1,1)} +\end{verbatim} + +The symbol is always rotated so that it points in the direction of the +path (for this purpose, all symbols are initially assumed to point +straight upward) before the \oarg{r\meta{rotate}} parameter is applied. + +There is a star-form \cs{arrowhead*} that behaves like \cs{arrow*} (when +possible). The optional arguments are exactly as in \cs{arrow}, with the +same defaults for all of them. + +The second command, \cs{arrowmid}, places the symbol somewhere between +the start and the end of the path. In this case the optional parameter +\oarg{f\meta{fraction}} gives the location of the symbol as a fraction +of the length of the path. The default is \oarg{f0.5}, which places it +approximately in the middle. The other optional arguments have the same +meaning as for \cs{arrowhead}. As with \cs{arrowhead}, the symbol is +rotated to `point' in the direction of the path before the +\oarg{r\meta{rotate}} is applied. + +The third command \cs{arrowtail} places the symbol at the start of the +path. Otherwise it behaves as the other two commands, except the option +\oarg{f\meta{forward}} is an amount to shift the symbol forward from +that first point. + +One might be tempted to use \cs{arrowmid} with the \meta{fraction} equal +to $1$ or $0$ to get arrowheads or tails. This will work sometimes. +However, some shapes have a `tip', that is, a particular point +designated as the tip of the arrowhead. The \cs{arrowhead} and +\cs{arrowtail} commands pay attention to this, while \cs{arrowmid} does +not. Also, \cs{arrowmid} has no star-form. + +You can design your own \meta{symbol} for these commands: use \cs{store} +to store a path in a path variable (see +subsection~\ref{transformation}). These commands assume that the length +is $1$, that the symbol `points' up and that the `tip' (the `pointy +end') is at $(0,0)$ (unless the pair variable \meta{symbol}\gbc{.tip} is +defined, in which case that is taken to be the tip). So draw your symbol +pointing up with its tip at $(0,0)$ and its length equal to $1$ (graph +unit). For example the following produces a solid head with a common +shape: +\begin{verbatim} +\store{myAH}\polygon{(-.5,-1)(0,0),(0.5,-1),(0,-.7)} +\arrowhead{myAH}\arc{(-10,0),(10,0),90} +\end{verbatim} +If you replace the \cs{polygon} above with \cs{polyline}: +\begin{verbatim} +\store{myAH}\polyline{(-.5,-1)(0,0),(0.5,-1),(0,-.7),(-.5,-1)} +\end{verbatim} +the path will not be closed and so the arrowhead will not be filled in. + +To make the star-form work with such self-defined symbols, one must also +define a closed path \gbc{myAH.clear} that gives the region to be +erased. In the above example: +\begin{verbatim} +\store{myAH.clear}\polygon{(-.5,-1),(-.5,0),(.5,0),(.5,-1),(0,-.7)} +\end{verbatim} + + +\section{Rendering figures.}\label{rendering} + +When \mfp{} is loaded, the initial way in which figures are drawn is +with a solid outline. That is, \cs{polyline}\marg{(1,0),(1,1),(0,0)} will +draw two solid lines connecting the points. It is possible to establish +a different default (see \cs{setrender} in subsection~\ref{default}), +however that default is used only when no explicit rendering prefix is +present. That is, when the macros in this section are used, any +previously established default is overridden. + +\begin{cd}\pagelabel{norender} +\cs{norender}$\ldots$% +\index{norender@\cs{norender}}% +\end{cd} + +This causes the following path not to be rendered at all. This can be +used to override \mfp{}'s automatic rendering rules. See +section~\ref{transformation}, page~\pageref{norenderexample} for an +example where one might need to do this. + +\subsection{Drawing}\label{drawing} + +\begin{cd}\pagelabel{draw} +\cs{draw}\oarg{\meta{color}}$\ldots$% +\index{draw@\cs{draw}} +\end{cd} + +Draws the subsequent path using a solid outline. For an example: to both +draw a curve and hatch its interior, \cs{draw}\cs{hatch} must be used. +The default for \meta{color} is \gbc{drawcolor}. + +To save repetition, the color used for the following commands is also +\gbc{drawcolor}: \cs{dashed}, \cs{dotted}, \cs{doubledraw}, \cs{plot}, +\cs{plotnodes}, and \cs{gendashed}, + +\begin{cd}\pagelabel{doubledraw} +\cs{doubledraw}\oarg{\meta{sep}}\oarg{\meta{color}}$\ldots$ +\index{doubledraw@\cs{doubledraw}} +\end{cd} + +This rendering macro draws the path with a double line. The default +separation (distance between centers of the two penstrokes) is twice the +pen diameter. This normally leaves one line thickness of white space +between. You can change this with the \oarg{\meta{sep}} argument. In +order to make the space between the lines transparent, this command is +implemented by calculating two curves that parallel the given curve and +drawing those. For technical reasons, that calculation is rather lengthy +so this is somewhat inefficient and users of slow machines might want to +avoid it. See also comments at \cs{parallelpath} in +subsection~\ref{reversal}. + +\begin{cd}\pagelabel{dashed} +\cs{dashed}\oarg{\meta{length},\meta{space}}$\ldots$% +\index{dashed@\cs{dashed}} +\end{cd} + +This rendering macro draws dashed segments along the path specified. +The default length of the dashes is the value of the \TeX{} dimension +\cs{dashlen}, initially \dim{4pt}. The default space between the dashes +is the value of the \TeX{} dimension \cs{dashspace}, initially +\dim{4pt}. The dashes and the spaces between may be increased or +decreased by as much as $1/n$ of their value, where $n$ is the number of +spaces appearing in the curve, in order to have the proper dashes at the +ends. The dashes at the ends are half of \cs{dashlen} long. + +\begin{cd}\pagelabel{dotted} +\cs{dotted}\oarg{\meta{size},\meta{space}}$\ldots$% +\index{dotted@\cs{dotted}} +\end{cd} + +This rendering macro draws dots along the specified path. The default +size of the dots is the value of the \TeX{} dimension \cs{dotsize}, +initially \dim{0.5pt}. The default space between the dots is the value +of the \TeX{} dimension \cs{dotspace}, initially \dim{3pt}. The size of +the spaces may be adjusted as in \cs{dashed}. + +\begin{cd}\pagelabel{plot} +\cs{plot}\oarg{\meta{size},\meta{space}}\marg{\meta{symbol}}$\ldots$% +\index{plot@\cs{plot}} +\end{cd} + +Similar to \cs{dotted}, this rendering macro draws copies of +\meta{symbol} along the path. Possible symbols are those listed under +\cs{plotsymbol} in subsection~\ref{points}. The default \meta{size} is +\cs{pointsize} (initially \dim{2pt}) and the default \meta{space} is +\cs{symbolspace} (initially \dim{5pt}). + +\begin{cd}\pagelabel{plotnodes} +\cs{plotnodes}\oarg{\meta{size}}\marg{\meta{symbol}}$\ldots$% +\index{plotnodes@\cs{plotnodes}} +\end{cd} + +This rendering macro places a symbol at each \emph{node} of the path +that follows. Possible symbols are those listed under \cs{plotsymbol} in +subsection~\ref{points}. A node is one of the points through which \MF{} +draws its curve. If one of the macros \cs{polyline}\marg{$\ldots$} or +\cs{curve}\marg{$\ldots$} follows, each of the points listed is a node. +In the \cs{datafile} command (subsection~\ref{external}), each of the +data points in the file is a node. In the function macros +(subsection~\ref{plotting}) the points corresponding to \meta{min}, +\meta{max} and each step in between are nodes. The optional \meta{size} +defaults to \cs{pointsize}. If the command \cs{clearsymbols} has been +issued then the interiors of the open symbols are erased. The effect of +something like the following is rather nice: +\begin{verbatim} +\clearsymbols +\plotnodes{Circle}\draw\polyline{...} +\end{verbatim} +This will first draw the polyline with solid lines, and then the points +listed will be plotted as open circles with the portion of the lines +inside the circles erased. One sees a series of open circles connected +one to the next by line segments + + +\begin{cd}\pagelabel{dashpattern} +\cs{dashpattern}\marg{\meta{name}}% + \marg{\meta{len1},\meta{len2},$\ldots$,\meta{len2k}}% +\index{dashpattern@\cs{dashpattern}} +\end{cd} + +For more general dash patterns than \cs{dashed} and \cs{dotted} provide, +\mfp{} offers a generalized dashing command. Before using it, one must +first establish a named dashing pattern with the above command. The +\meta{name} can be any sequence of letters and underscores. Try to make +it distinctive to avoid undoing some internal variable. \meta{len1} +through \meta{len2k} are an even number of lengths. The odd ones +determine the lengths of dashes, the even ones the lengths of spaces. A +dash of length \texttt{0pt} means a dot. An alternating dot-dash pattern +can be specified with +\begin{verbatim} +\dashpattern{dotdash}{0pt,4pt,3pt,4pt} +\end{verbatim} +\emph{Note}: Since pens have some thickness, dashes look a little +longer, and spaces a little shorter, than the numbers suggest. If one +wants dashes and spaces with the same length, one needs to take the size +desired and increase the spaces by the thickness of the drawing pen +(normally) \dim{0.5pt}) and decrease the dashes by the same amount.% + \footnote{Experienced \MP{} users could also set the \mfc{linecap} + variable to \mfc{butt}.} + +If \cs{dashpattern} is used with an odd number of entries, a space of +length \dim{0pt} is appended. This makes the last dash in one copy of +the pattern abut the first dash in the next copy. + +\begin{cd}\pagelabel{gendashed} +\cs{gendashed}\marg{\meta{name}}$\ldots$% +\index{gendashed@\cs{gendashed}} +\end{cd} + +Once a dashing pattern name has been defined, it can be used in this +figure macro to draw the curve that follows it. Using a name not +previously defined will cause the curve to be drawn with a solid line, +and generate a \MF{} warning, but \TeX{} will not complain. If all the +dimensions in a dash pattern are 0, \cs{gendashed} responds by drawing a +solid curve. The same is true if the pattern has only one entry. + +\begin{cd}\pagelabel{zigzag} +\cs{zigzag}\marg{\meta{start},\meta{end},\meta{wl},\meta{amp}}\dots\\ +\cs{sinewave}\oarg{\meta{tens}}% + \marg{\meta{start},\meta{end},\meta{wl},\meta{amp}}\dots% +\index{zigzag@\cs{zigzag}}% +\index{sinewave@\cs{sinewave}} +\end{cd} + +These figure macros both draw a solid line that crosses from one +side of the path to the other. The \cs{zigzag} makes a jagged result +while the \cs{sinewave} makes a smooth one. The optional argument of +\cs{sinewave} is a `tension' and controls how smooth the result is. The +default tension is $1$. Higher values make a less smooth path, and +values of 10 or so produce a result almost indistinguishable from +\cs{zigzag}. Tension is required to be greater than $3/4$. + +The mandatory arguments consists of four dimensions separated by a comma. +The rendering produced by these macros actually follow the path a little +way at the start and end of the path. This is controlled by the +dimensions \meta{start} and \meta{end}. + +The third dimension, \meta{wl}, is the distance from one `peak' to the +next (the `wavelength'). The second, \meta{amp}, is the maximum distance +to either side of the true path (the `amplitude'). Reasonable values of +\meta{wl} and \meta{amp} are \dim{8pt} and \dim{2pt}, respectively. +These proportions (4 to 1) causes the zigzag and the sinewave to cross +the path at an angle of about 45 degrees, a rather pleasant result. +Those sizes are close to optimal: too much smaller and the rendering +just looks like a fuzzy line, too much larger, and bends in the path +will distort the zigzagging. + +The zigzags zig to the left first if \meta{amp} is positive, to the +right if it is negative. For closed curves, the beginning and end are +constructed to meet smoothly. It is always arranged that there are an +equal number of left zigs and right zags, so the \meta{wl} is only +approximate. + + +\begin{cd}\pagelabel{corkscrew} +\cs{corkscrew}\oarg{\meta{tens}}% + \marg{\meta{start},\meta{end},\meta{wl},\meta{amp}}\dots\\% +\cs{coil}\oarg{\meta{tens}}% + \marg{\meta{start},\meta{end},\meta{wl},\meta{amp}}\dots% +\index{corkscrew@\cs{corkscrew}}% +\index{coil@\cs{coil}} +\end{cd} + +This rendering macro draws a coil or corkscrew that coils around a +given path, something like this: \includegraphics{coil.mps} (the red +dots show the actual path). The \meta{tens} is a tension option that +controls how `loopy' the result will be (the higher the number the more +jagged). The mandatory argument contains four explicit dimensions. The +first two, \meta{start} and \meta{end} are as in \cs{zigzag}. The +\meta{wl} is the distance from one loop to the next, and \meta{amp} is +the distance from the true path to the tops (or bottoms) of the +loops. If \meta{amp} is positive, the tip of the loop is to the left +of the path, if negative it is to the right. The example at the start of +this paragraph was drawn using the following code: +\begin{verbatim} +\mfpic{0}{33}{0}{6.4} +\dotsize=1pt +\drawcolor{red} + \dotted\polyline{(0,3.2),(33,3.2)} +\drawcolor{black} + \coil[1.5]{3pt,3pt,4.8pt,3.2pt}\polyline{(0,3.2),(33,3.2)} +\endmfpic +\end{verbatim} + + +\subsection{Shading, filling, erasing, clipping, hatching}\label{filling} + +For the purposes of this section, a distinction must be made in the +figure macros between `open' and `closed' paths. A path that merely +returns to its starting point is \emph{not} automatically closed; such a +path might be open and may need to be explicitly closed, for example by +\cs{lclosed}. The (already) closed paths are those that have +`\texttt{closed}' or `\texttt{cyclic}' in their name plus: +\begin{display} + \cs{belowfcn}, \cs{border}, \cs{btwnfcn}, \cs{btwnplrfcn}, + \cs{chartbar} (and its aliases),\\ + \cs{circle}, \cs{ellipse}, \cs{levelcurve}, \cs{makesector}, + \cs{piewedge}, \cs{plrregion},\\ + \cs{polygon}, \cs{pshcircle}. \cs{rect}, \cs{regpolygon}, + \cs{sector}, \cs{tlabelcircle},\\ + \cs{tlabelellipse}, \cs{tlabeloval}, and \cs{tlabelrect}. +\end{display} + +The macros of this section can all be used to fill (or unfill) the +interior of closed paths, even if the paths cross themselves. Filling an +open curve is technically an error, but the \MF{} code responds by +drawing the path and not doing any filling. Note that these macros +override the default rendering, so if you want some sort of fill pattern +\emph{and} an outline drawn, you need an explicit prefix for both. + +\begin{cd}\pagelabel{gfill} +\cs{gfill}\oarg{\meta{color}}$\ldots$% +\index{gfill@\cs{gfill}} +\end{cd} + +This rendering macro fills in the subsequent closed path. Under \MP{} it +fills with \meta{color}, which defaults to +\index{fillcolor@\gbc{fillcolor}}\gbc{fillcolor}. Under \MF{} it +approximates the color with a shade of gray, clears the interior, and +then fills with a pattern of black and white pixels simulating gray. + +\begin{cd}\pagelabel{gclear} +\cs{gclear}$\ldots$% +\index{gclear@\cs{gclear}} +\end{cd} + +This rendering macro erases everything \emph{inside} the subsequent +closed path (except text labels under some circumstances, see +section~\ref{mplabels} and \ref{overlaylabels}). Under \MP{} it actually +fills with the predefined color named \mfc{background}. Since +\mfc{background} is normally \mfc{white}, and so are most actual +backgrounds, this is usually indistinguishable from clearing. However, +if an \env{mfpic} environment utilzes \emph{background text} (see +subsection~\ref{text}), part of the background text may appear to be +`erased'. Unfortunately, there is little that can be done about this. + +\begin{cd}\pagelabel{gclip} +\cs{gclip}$\ldots$% +\index{gclip@\cs{gclip}} +\end{cd} + +This rendering macro erases everything \emph{outside} the subsequent +closed path from the picture (except text labels under some +circumstances, see section~\ref{mplabels} and \ref{overlaylabels}). Note +that this is a true erasing, even in \MP{}. + +\begin{cd}\pagelabel{shade} +\cs{shade}\oarg{\meta{shadesp}}$\ldots$% +\index{shade@\cs{shade}} +\end{cd} + +This rendering macro shades the interior of the subsequent closed path +with dots. The diameter of the dots is the \MF{} variable \mfc{shadewd}, +set by the macro \cs{shadewd}\marg{\meta{size}}. Normally this is +\dim{0.5bp}. The optional argument specifies the spacing between (the +centers of) the dots, which defaults to the \TeX{} dimension +\cs{shadespace}, initially \dim{1pt}. If \cs{shadespace} is less than +\mfc{shadewd}, the closed path is filled with black, as if with +\cs{gfill}. Under \MP{} this macro actually fills the path's interior +with a shade of gray. The shade to use is computed based on +\cs{shadespace} and \mfc{shadewd}. The default values of these +parameters correspond to a gray level of about 78\% of white.% + \footnote{If \cs{shadewd} is $w$ and \cs{shadespace} is $s$, then + the level of gray is $1 - (.88w/s)^2$, where $0$ denotes black and + $1$ white.} % +The \MF{} version attempts to optimize the dots to the pixel grid +corresponding to the printers resolution (to avoid generating dither +lines). Because this involves rounding, it will happen that values of +\cs{shadespace} that are relatively close and at the same time close to +\mfc{shadewd} produce exactly the same shade. Most of the time, however, +values of \cs{shadespace} that differ by at least 20\% will produce +different patterns. The actual behavior for particular values of the +parameters and particular printer resolutions cannot be predicted, and +we even make no guarantee it will not change from one version of \mfp{} +to another. + +\begin{cd}\pagelabel{polkadot} +\cs{polkadot}\oarg{\meta{space}}$\ldots$% +\index{polkadot@\cs{polkadot}} +\end{cd} + +This rendering macro fills the interior of a closed path with large +dots. This is almost what \cs{shade} does, but there are several +differences. \cs{shade} is intended solely to simulate a gray fill in +\MF{} where the only color is black. So it is optimized for small dots +aligned to the pixel grid (in \MF{}). In \MP{} \cs{shade} only fills with +gray and is intended merely for compatibility. The macro \cs{polkadot} +is intended for large dots in any color, and so it optimizes spacing (a +nice hexagonal array) and makes no attempt to align at the pixel level. +The \meta{space} defaults to the \TeX{} dimension \cs{polkadotspace}, +initially \dim{10pt}. The diameter of the dots is the value of the \MF{} +variable \mfc{polkadotwd}, which can be set with +\cs{polkadotwd}\marg{\meta{size}}, and is initially \dim{5bp}. The dots +are colored with \index{fillcolor@\gbc{fillcolor}}\gbc{fillcolor}. In +\MF{}, nonblack values of \gbc{fillcolor} will produce shaded dots. + +\begin{cd}\pagelabel{thatch} +\cs{thatch}\oarg{\meta{hatchsp},\meta{angle}}\oarg{\meta{color}}$\ldots$% +\index{thatch@\cs{thatch}} +\end{cd} + +This rendering macro fills a closed path with equally spaced parallel +lines at the specified angle. The thickness of the lines is set by the +macro \cs{hatchwd}. In the optional argument, \meta{hatchsp} specifies +the space between lines, which defaults to the \TeX{} dimension +\cs{hatchspace}, initially \dim{3pt}. The \meta{angle} defaults to 0. +The \meta{color} defaults to \gbc{hatchcolor}. If \cs{hatchspace} is +less than the line thickness, the closed path is filled with +\meta{color}, as if with \cs{gfill}. If the first optional argument +appears, both parts must be present, separated by a comma. For the color +argument to be present, the other optional argument must also be +present. However, if one wishes only to override the default color one +can use an empty first optional argument (completely empty, no spaces or +comma). + +\begin{cd}\pagelabel{hatch} +\cs{lhatch}\oarg{\meta{hatchsp}}\oarg{\meta{color}}$\ldots$\\ +\cs{rhatch}\oarg{\meta{hatchsp}}\oarg{\meta{color}}$\ldots$\\ +\cs{hatch}\oarg{\meta{hatchsp}}\oarg{\meta{color}}$\ldots$\\ +\cs{xhatch}\oarg{\meta{hatchsp}}\oarg{\meta{color}}$\ldots$% +\index{lhatch@\cs{lhatch}}% +\index{rhatch@\cs{rhatch}}% +\index{hatch@\cs{hatch}}% +\index{xhatch@\cs{xhatch}}% +\end{cd} + +These rendering macros are just \cs{thatch} with predefined values of +the angle. \cs{lhatch} fills the region with left slanted lines (from +upper left to lower right). It is exactly the same as +\begin{display} +\cs{thatch}\oarg{\meta{hatchsp},-45}\oarg{\meta{color}}$\ldots$ +\end{display} + +\cs{rhatch} draws right slanted lines (lower left to upper right). It is +exactly the same as +\begin{display} +\cs{thatch}\oarg{\meta{hatchsp},45}\oarg{\meta{color}}$\ldots$ +\end{display} + +\cs{hatch} (\cs{xhatch} is a synonym) draws lines in a cross-hatched +pattern. It is exactly the same as \cs{rhatch} followed by \cs{lhatch} +using the same \meta{hatchsp} and \meta{color}. + +Hatching should normally be used very sparingly, or never if +alternatives are available (color, shading). However, hatching or +polkadotting on top of another filling macro is almost the only way to +fill in two regions that \emph{automatically} shows the overlap area. +Hatching is at least less garish than polkadots. + + +\subsection{Changing the default rendering}\label{default} + +\emph{Rendering} is the process of converting a geometric description +into a drawing. In \MF{}, this means producing a bitmap (\MF{} stores +these in \mfc{picture} variables), either by stroking (drawing) a path +using a particular pen), or by filling a closed path. In \MP{} it means +producing a \PS{} description of penstrokes and fills (with possible +clipping). + +\begin{cd}\pagelabel{setrender} +\cs{setrender}\marg{\meta{\TeX{} commands}}% +\index{setrender@\cs{setrender}} +\end{cd} + +Initially, \mfp{} uses the \cs{draw} command (stroking) as the default +operation when a figure is to be rendered. However, this can be changed +to any combination of \mfp{} rendering commands or indeed any \TeX{} +commands, by using the \cs{setrender} command. This redefinition is +local inside an \env{mfpic} environment, so it can be enclosed in braces +to restrict its range. Outside an \env{mfpic} environment it is a global +redefinition. + +For example, after \cs{setrender}\marg{\cs{dashed}\cs{shade}} the +command \cs{circle}\marg{(0,0),1} produces a shaded circle with a dashed +outline. Any explicit rendering prefix overrides this default. + +\subsection{Examples}\label{examples} + +It may be instructive, for the purpose of understanding the syntax of +\emph{shape-modifier and rendering prefixes}, to consider two examples: +\begin{ex} + \cs{draw}\cs{gfill}\oarg{red}\cs{lclosed}\cs{polyline}\marg{$\ldots$} +\end{ex} +which fills inside a polygon and draws its outline; and +\begin{ex} + \cs{gfill}[red]\cs{lclosed}\cs{draw}\cs{polyline}\marg{$\ldots$} +\end{ex} +which draws all of the outline \emph{except} the line segment supplied +by \cs{lclosed}, then fills the interior. Thus, in the first case the +path is first defined (by \cs{polyline}), then closed, then the resulting closed +path is filled, and finally drawn. In the second case the order is: +defined, drawn, closed, filled. In particular, what is drawn in the +second case is the path not yet closed. It should also be pointed out +that in the last case, the fill is placed last and will cover half +the thickness of the previously drawn outline. + + +\section{Functions and Plotting.}\label{functions} + +In the following macros, expressions like $f(\mathtt{x})$ or $g(\mathtt{t})$ +stand for any legal \MF{} expression, in which the only unknown +variables are those indicated (\texttt{x} in the first case, and \texttt{t} in +the second). + +\subsection{Defining functions}\label{defining} + +\begin{cd}\pagelabel{fdef} +\cs{fdef}\marg{\meta{fcn}}\marg{\meta{param1},\meta{param2},$\ldots$}% + \marg{\meta{mf-expr}}% +\index{fdef@\cs{fdef}} +\end{cd} + +Defines a \MF{} function \meta{fcn} of the parameters \meta{param1}, +\meta{param2}, $\ldots$, by the \MF{} expression \meta{mf-expr} in which +the only free parameters are those named. The return type of the +function is the same as the type of the expression. What is allowed for +the function name \meta{fcn} is more restrictive than \MF{}'s rule for +variable names. Roughly speaking, it should consist of letters and +underscore characters only. (In particular, for those that know what +this means, the name should have no suffixes.) Try to make the name +distinctive to avoid redefining internal \MF{} commands. + +The expression \meta{mf-expr} is passed directly into the corresponding +\MF{} macro and interpreted there, so \MF{}'s rules for algebraic +expressions apply. If \cs{fdef} occurs inside an \env{mfpic} +environment, it is local to that environment, otherwise it is available +to all subsequent \env{mfpic} environments. + +As an example, after \cs{fdef}\marg{myfcn}\marg{s,t}\marg{s*t-t}, any +place below where a \MF{} expression is required, you can use +\mfc{myfcn(2,3)} to mean \mfc{2*3-3} and \mfc{myfcn(x,x)} to mean +\mfc{x*x-x}. + +Operations available include \mfc{+}, \mfc{-}, \mfc{*}, \mfc{/}, and +\mfc{**} (\mfc{x**y}$=x^y$), with `\mfc{(}' and `\mfc{)}' for grouping. +Functions already available include the standard \MF{} functions +\mfc{round}, \mfc{floor}, \mfc{ceiling}, \mfc{abs}, \mfc{sqrt}, +\mfc{sind}, \mfc{cosd}, \mfc{mlog}, and \mfc{mexp}. Note that in \MF{} +the operations \mfc{*} and \mfc{**} have the same level of precedence, +so \mfc{x*y**z} means $(xy)^z$. Use parentheses liberally! + +(\textit{Notes:} The \MF{} trigonometric functions \mfc{sind} and +\mfc{cosd} take arguments in degrees; \mfc{mlog(x)}$=256\ln x$, and +\mfc{mexp} is its inverse.) You can also define the function \meta{fcn} +by cases, using the \MF{} conditional expression +\begin{ex} + \mfc{if~\meta{boolean}:~\meta{expr}~elseif + \meta{boolean}:~$\ldots$~else:~\meta{expr}~fi}. +\end{ex} +Relations available for the \meta{boolean} part of the expression +include \mfc{=}, \mfc{<}, \mfc{>}, \mfc{<=}, \mfc{<>} and \mfc{>=}. + +Complicated functions can be defined by a compound expression, which is +a series of \MF{} statements, followed by an expression, all enclosed +between \mfc{begingroup} and \mfc{endgroup}. The \cs{fdef} command +automatically supplies these grouping commands around the definition so +if the entire \meta{mf-expr} is one such compound expression the user +need not type them. \CMF{} functions can call \MF{} functions, even +recursively. + +Many common functions have been predefined in \file{grafbase}, which is +a package of \MF{} macros that implement \prog{mfpic}'s drawing. These +include the rest of the trig functions \mfc{tand}, \mfc{cotd}, \mfc{secd}, +\mfc{cscd}, which take angles in degrees, plus variants \mfc{sin}, +\mfc{cos}, \mfc{tan}, \mfc{cot}, \mfc{sec}, and \mfc{csc}, which take +angles in radians. Some inverse trig functions are also available, the +following produce angles in degrees: \mfc{asin}, \mfc{acos}, and +\mfc{atan}, and the following in radians: \mfc{invsin}, \mfc{invcos}, +\mfc{invtan}. The exponential and hyperbolic functions: \mfc{exp}, +\mfc{sinh}, \mfc{cosh}, \mfc{tanh}, \mfc{coth}, \mfc{sech}, and +\mfc{csch}; and some of their inverses: \mfc{ln} (or \mfc{log}), +\mfc{asinh}, \mfc{acosh}, and \mfc{atanh} are also defined. + +There are also two conversion functions: \gbc{radians(t)} produces the +number of radians in \mfc{t} degrees and \gbc{degrees(t)} produces the +number of degrees in \mfc{t} radians. In these expressions the special +variable \gbc{pi} produces $\pi$, accurate to roughly 5 decimals. +(\CMF{} and \MP{} provide accuracy only to $\pm2^{-17} = \pm +.76\times10^{-5}$.) + +The integer functions \gbc{gcd(m,n)} and \gbc{lcm(m,n)} produce the +greatest common divisor and least common multiple of two integers +\gbc{m} and \gbc{n}. + + +\subsection{Plotting functions}\label{plotting} + +The plotting macros take two or more arguments. They have an optional +first argument, \meta{spec}, which determines whether a function is +drawn smooth (as a \MF{} B\'ezier curve), or polygonal (as line +segments)---if \meta{spec} is \texttt{p}, the function will be +polygonal. Otherwise the \meta{spec} should be \texttt{s}, followed by +an optional positive number no smaller than 0.75. In this case the +function will be smooth with a tension equal to the number. See the +\cs{curve} command (subsection~\ref{curves}) for an explanation of +tension. The default \meta{spec} depends on the purpose of the macro. + +One compulsory argument contains three values \meta{min}, \meta{max} and +\meta{step} separated by commas. The independent variable of a function +starts at the value \meta{min} and steps by \meta{step} until reaching +\meta{max}. If \meta{max}${}-{}$\meta{min} is not a whole number of +steps, then round$((\meta{max}-\meta{min})/\meta{step})$ equal steps are +used. One may have to experiment with the size of \meta{step}, since +\MF{} merely connects the points corresponding to these steps with what +\emph{it} considers to be a smooth curve. Smaller \meta{step} gives +better accuracy, but too small may cause the curve to exceed \MF{}'s +capacity or slow down its processing. Increasing the tension may help +keep the curve in line, but at the expense of reduced smoothness. + +There are one or more subsequent arguments, each of which is a \MF{} +function or expression as described above. All the macros are figure +macros, defining a path to which prefixes may be applied. + +\begin{cd}\pagelabel{function} +\cs{function}\oarg{\meta{spec}}\marg{\meta{$x_{\mathrm{min}}$},% + \meta{$x_{\mathrm{max}}$},\meta{$\Delta x$}}% + \marg{$f(\mathtt{x})$}% +\index{function@\cs{function}} +\end{cd} + +This figure macro produces the graph of $y = f(x)$, where $f$ is a \MF{} numeric +function or expression of one numeric argument, which must be denoted by +a literal \texttt{x}. The default \meta{spec} is \texttt{s}. For example +\begin{verbatim} +\function{0,pi,pi/10}{sin x} +\end{verbatim} +draws the graph of $\sin x$ between 0 and $\pi$. + +\begin{cd}\pagelabel{parafcn} +\cs{parafcn}\oarg{\meta{spec}}\marg{\meta{$t_{\mathrm{min}}$},% + \meta{$t_{\mathrm{max}}$},\meta{$\Delta t$}}% + \marg{($x(\mathtt{t}), y(\mathtt{t})$)}\\ +\cs{parafcn}\oarg{\meta{spec}}\marg{\meta{$t_{\mathrm{min}}$},% + \meta{$t_{\mathrm{max}}$},\meta{$\Delta t$}}% + \marg{\meta{pair-fcn}}% +\index{parafcn@\cs{parafcn}} +\end{cd} + +This figure macro produces the parametric path determined by the last +argument. This can be a pair of expressions $x(\mathtt{t})$ and +$y(\mathtt{t})$ enclosed in parentheses and separated by a comma, with +the literal variable \texttt{t}. Alternatively, the last argument can be +a \MF{} function or expression in \texttt{t} that returns a pair.% + \footnote{There are very few of these. \CMF{} provides \mfc{dir t}, + which is essentially \mfc{(cosd t, sind t)}. \Mfp{} adds \gbc{cis t} + which is \gbc{(cos t, sin t)}.} +The default \meta{spec} is \texttt{s}. For example +\begin{verbatim} +\parafcn{0,1,.1}{(2t, t+t*t)} +\end{verbatim} +plots a smooth parabola from $(0,0)$ to $(2,2)$. + +\begin{cd}\pagelabel{plrfcn} +\cs{plrfcn}\oarg{\meta{spec}}\marg{\meta{$\theta_{\mathrm{min}}$},% + \meta{$\theta_{\mathrm{max}}$},\meta{$\Delta\theta$}}% + \marg{$f(\mathtt{t})$}% +\index{plrfcn@\cs{plrfcn}} +\end{cd} + +This figure macro produces the graph of the polar coordinate equation +$r=f(\theta)$, where $f$ is a \MF{} numeric function or expression of +one numeric argument, and $\theta$ varies from +\meta{$\theta_{\mathrm{min}}$} to \meta{$\theta_{\mathrm{max}}$} in +steps of \meta{$\Delta\theta$}. Each $\theta$ value is interpreted as an +angle measured in \emph{degrees}. In the expression $f(\mathtt{t})$, the +unknown \texttt{t} stands for $\theta$. The default \meta{spec} is +\texttt{s}. For example +\begin{verbatim} +\plrfcn{0,90,5}{sind (2t)} +\end{verbatim} +draws one loop of a 4-petal rosette. Note that this function demands the +variable \mfc{t} be in degrees. The range and step size must be in +degrees and the function must operate on the numeric variable \gbc{t} in +degrees. If one needs to measure angles in radians, use the conversion +functions \gbc{degrees()} and \gbc{radians()}, as follows: +\begin{verbatim} +\plrfcn{0,degrees(pi/2),degrees(pi/36)}{sin (radians(2t))} +\end{verbatim} + + +\begin{cd}\pagelabel{btwnfcn} +\cs{btwnfcn}\oarg{\meta{spec}}\marg{\meta{$x_{\mathrm{min}}$},% + \meta{$x_{\mathrm{max}}$},\meta{$\Delta x$}}% + \marg{$f(\mathtt{x})$}\marg{$g(\mathtt{x})$}\\ +\cs{btwnplrfcn}\oarg{\meta{spec}}\marg{\meta{$\theta_{\mathrm{min}}$},% + \meta{$\theta_{\mathrm{max}}$},\meta{$\Delta \theta$}}% + \marg{$f(\mathtt{t})$}\marg{$g(\mathtt{t})$}% +\index{btwnfcn@\cs{btwnfcn}}% +\index{btwnplrfcn@\cs{btwnplrfcn}} +\end{cd} + +These are figure macros. The first one produces a closed path +surrounding the region between the graphs of the two functions. The +second one does the same for two polar functions. That is (in both +cases), the path follows the first function (in order or increasing $x$ +or $\theta$), thence along the straight line to the \emph{end} of the +second one, thence backwards along the second function (decreasing $x$ +or $\theta$) and finally along the straight line to the start. The last +two mandatory arguments, the functions, are specified exactly as in +\cs{function} and \cs{plrfcn}, being numeric functions of one numeric +argument \texttt{x} or \texttt{t}. Unlike the previous function macros, +the default \meta{spec} is \texttt{p}---these macros are intended to be +used for shading between drawn functions, a task for which smoothness is +usually unnecessary. For example, the first line below +\begin{verbatim} +\shade\btwnfcn{0,1,.1}{0}{x - x**2} +\btwnplrfcn[s]{-30,30,5}{1}{2*cosd 2t} +\end{verbatim} +shades the area between the $x$-axis and the given parabola. The second +draws the boundary of the region between the circle $r = 1$ and one loop +of the rosette $r = 2\cos 2\theta$. + +Note: the effect of \cs{btwnfcn} could also be accomplished with +\begin{ex} + \cs{lclosed}\cs{connect}\\ + \cs{function}\marg{\meta{$x_{\mathrm{min}}$},% + \meta{$x_{\mathrm{max}}$},\meta{$\Delta x$}}\marg{$f(\mathtt{x})$}\\ + \cs{reverse}\cs{function}\marg{\meta{$x_{\mathrm{min}}$},% + \meta{$x_{\mathrm{max}}$},\meta{$\Delta x$}}\marg{$g(\mathtt{x})$}\\ + \cs{endconnect} +\end{ex} +\cs{lclosed} was described in subsection~\ref{closure} and the +\cs{connect}\dots\cs{endconnect} pair was described in +subsection~\ref{reversal}. + +\begin{cd}\pagelabel{belowfcn} +\cs{belowfcn}\oarg{\meta{spec}}% + \marg{\meta{$x_{\mathrm{min}}$},\meta{$x_{\mathrm{max}}$},% + \meta{$\Delta x$}}\marg{$f(\mathtt{x})$}\\ +\cs{plrregion}\oarg{\meta{spec}}% + \marg{\meta{$\theta_{\mathrm{min}}$},\meta{$\theta_{\mathrm{max}}$},% + \meta{$\Delta\theta$}}\marg{$f(\mathtt{t})$}% +\index{belowfcn@\cs{belowfcn}}% +\index{plrregion@\cs{plrregion}} +\end{cd} + +These figure macros produce identical results to \cs{btwnfcn} and +\cs{btwnplrfcn} when the first function is just $0$. They are, however, +much more efficient. The first of these, \cs{belowfcn}, produces the +path surrounding the region bounded by the $x$-axis, the graph of +$y=f(x)$ and the two vertical lines $x=x_{\mathrm{min}}$ and $x = +x_{\mathrm{max}}$. (The region is not actually \emph{below} $y = f(x)$ +unless $f(x) \ge 0$ throughout the interval.) The second produces the +path surrounding the region bounded by the polar function $r = +f(\theta)$ and the two rays $\theta=\theta_{\mathrm{min}}$ and +$\theta=\theta_{\mathrm{max}}$. + +The arguments of these command are the same as the nonclosed versions, +\cs{function} and \cs{plrfcn}, except the default for the optional +agument is \texttt{[p]}. Again, this is because it is mainly for +shading. However, drawing the boundary is often needed: +\begin{verbatim} +\shade\plrregion{0,90,5}{sind (2t)} +\plrregion[s]{0,90,5}{sind (2t)} +\end{verbatim} +shades one loop of the 4-petal rosette, and then draws it. + +\begin{cd}\pagelabel{levelcurve} +\cs{levelcurve}\oarg{\meta{spec}}\marg{\meta{seed},\meta{step}} + \marg{\meta{inequality}}% +\index{levelcurve@\cs{levelcurve}} +\end{cd} + +This figure macro produces a level curve of some function $F(x,y)$. +There are three requirements on the parameters for this to work +correctly. First, in order to obtain the curve satisfying $F(x,y) = C$, +the \marg{\meta{inequality}} must be either \verb${F(x,y) > C}$ or +\verb${F(x,y) < C}$.% + \footnote{A non-strict inequality such as \mfc{>=} can be + used, but the result will not be significantly different.} +Second, the level curve must surround the point given by the \meta{seed} +paramter, and third, the inequality must be true at this seed point. + +The command works by searching rightward from \meta{seed} until it +encounters the first point on the level curve. It then tries to find a +nearby point on the level curve and joins it to the first one, and +continues similarly until it finds it has returned near the starting +point. The meaning of ``nearby point on the level curve'' is the +intersection of the level curve with a circle of radius \meta{step} +centered at the previously found point. If the region defined by the +inequality extends beyond the bounds of the picture (as set by the +\cs{mfpic} command), the region is truncated and the resulting curve +will follow along the picture's border. + +Since the algorithm only approximates the level set, a tolerance (how +close the points are to actually being \emph{on} the level curve) is +chosen which gives two decimal places more accuracy than \meta{step}. +The value of \meta{step} is interpreted in \emph{graph} units and +so should be a pure number. The \oarg{\meta{spec}} is either \oarg{p}, +in which case the calculated points are joined with straight lines, or +\oarg{s\meta{tension}} as in \cs{function}. The default is +\oarg{s}: a smooth curve with the current default tension. + +In general, choosing a \meta{step} that corresponds to a few millimeters +works reasonably well. For example, if the graph unit is 1cm (for +example, \cs{mfpicunit=1cm} and no scaling is used), then +\meta{step}${}= 0.5$ might be a reasonable first choice. If the level +set is reasonably smooth and \oarg{s} is used, then the result will +match the actual curve to within .005cm, which is approximately .14pt, +which is less than half the thickness of the standard pen used to draw +it. + +Be warned that there is a limit: there should not be more than 2000 +steps in the completed curve. In a figure which is 10-by-10 graph units, +a level curve without too much oscillation would probably be less than +80 units in length and a step size of .04 would probably produce under +2000 steps. This should be accurate enough for most purposes. If you +\emph{really} need more, the value of the \MF{} variable +\verb$max_points$ must be changed. This can be done with +\cs{setmfvariable} (see section~\ref{variables}). + +As a special case, if \meta{step} is 0, the maximum of width and height +of the figure (as given by the arguments to the \env{mfpic} environment) +is divided by 100. For example, in a 5-by-10 graph, giving a step size +of $0$ will actually select \meta{step}${}= 10/100 = 0.1$. + +The algorithm used will produce incorrect results if there are two +points on the curve closer that \meta{step} in straight-line distance, +but much further apart when measured along the curve. + +The algorithm used will produce incorrect results if two points of the +curve that are distant (as measured along the curve) are closer than +\meta{step} in straight-line distance. + +\subsection{Plotting external data files}\label{external} + +\begin{cd}\pagelabel{datafile} +\cs{datafile}\oarg{\meta{spec}}\marg{\meta{file}}\\ +\cs{smoothdata}\oarg{\meta{tension}}\\ +\cs{unsmoothdata}% +\index{datafile@\cs{datafile}}% +\index{smoothdata@\cs{smoothdata}}% +\index{unsmoothdata@\cs{unsmoothdata}} +\end{cd} + +The figure macro \cs{datafile} produces a curve connecting the points +listed in the file \meta{file}. (The context makes it clear whether this +meaning of \cs{datafile} or that of subsection~\ref{list} is meant.) The +\meta{spec} may be \texttt{p} to produce a polygonal path, or \texttt{s} +followed by a tension value (as in \cs{curve}) to produce a smooth path. +If no \meta{spec} is given, the default is initially \texttt{p}, but +\cs{smoothdata} may be used to change this. Thus, after the command +\cs{smoothdata}\oarg{\meta{tension}} the default \oarg{\meta{spec}} is +changed to \oarg{s\meta{tension}}. If the tension parameter is not +supplied it defaults to \mfc{1.0} (or the value set by the +\cs{settension} command if one has been used). + +The command \cs{unsmoothdata} restores the default \oarg{\meta{spec}} to +\oarg{p}. + +By default, each non-blank line in the file is assumed to contain at +least two numbers, separated by whitespace (blanks or tabs). The first +two numbers on each line are assumed to represent the $x$- and +$y$-coordinates of a point. Initial blank lines in the file are ignored, +as are comments. The comment character in the data file is assumed to be +\texttt{\%}, but it can be reset using \cs{mfpdatacomment} (below). Any +blank line other than at the start of the file causes the curve to +terminate. The \cs{datafile} command may be preceded by any of the +prefix commands, so that, for example, a closed curve could be formed +with \cs{lclosed}\cs{datafile}\marg{data.dat}. + +The \index{datafile@\cs{datafile}}\cs{datafile} command has another use, +independent of the above description. We saw in subsection~\ref{list} +that any \mfp{} command (other than one that prints text labels) that +takes as its last argument a list of points (or numerical values) +separated by commas, can have that list replaced with a reference to an +external data file. For example, if a file \file{ptlist.dat} contains +two or more numerical values per line separated by whitespace, then one +can draw a dot at each of the points corresponding to the first pair of +numbers on each line with the following. +\begin{verbatim} +\point\datafile{ptlist.dat} +\end{verbatim} +In fact there is no essential difference between `\cs{datafile}\oarg{p}' +and `\cs{polyline}\cs{datafile}', and no difference between +`\cs{datafile}\oarg{s}' and `\cs{curve}\cs{datafile}'. +Here is the full list (omitting aliases) of \mfp{} macros that allow +this usage of \cs{datafile}\index{datafile@\cs{datafile}}: + +\begin{itemize} +\raggedright +\item Numeric data: + \cs{barchart}, \cs{dashpattern}, \cs{numericarray}, + \cs{piechart}, and all the axis marks commands. +\item Point or vector data: + \cs{cbeziers}, \cs{closedcbeziers}, \cs{closedcomputedspline}, + \cs{closedcspline}, \cs{closedmfbezier}, \cs{closedqbeziers}, + \cs{closedqspline}, \cs{computedspline}, \cs{convexcurve}, + \cs{convexcyclic}, \cs{cspline}, \cs{curve}, \cs{cyclic}, + \cs{fcncurve}, \cs{fcnspline}, \cs{mfbezier}, + \cs{periodicfcnspline}, \cs{plotsymbol}, \cs{point}, \cs{polygon}, + \cs{polyline}, \cs{putmfpimage}, \cs{qbeziers}, \cs{qspline}, + \cs{turtle}, and \cs{pairarray}. +\end{itemize} +In addition \cs{setarray} and \cs{globalsetarray} (with the numeric or +pair data type) allow this usage. + +\begin{cd}\pagelabel{mfpdatacomment} +\cs{mfpdatacomment}\cs{}\meta{char}% +\index{mfpdatacomment@\cs{mfpdatacomment}} +\end{cd} + +Changes \meta{char} to a comment character and changes the usual \TeX{} +comment character \texttt{\%} to an ordinary character \emph{while reading a +datafile for drawing}. + +\begin{cd}\pagelabel{using} +\cs{using}\marg{\meta{in-pattern}}\marg{\meta{out-pattern}}% +\index{using@\cs{using}} +\end{cd} + +Used to change the assumptions about the format of the data file. For +example, if there are four numbers on each line separated by commas, to +plot the third against the second (in that order) you can say +\cs{using}\marg{\#1,\#2,\#3,\#4}\marg{(\#3,\#2)}. This means the +following: Everything on a line up to the first comma is assigned to +parameter \texttt{\#1}, everything from there up to the second comma is +assigned to parameter \texttt{\#2}, etc. Everything from the third comma +to the end of line is assigned to \texttt{\#4}. When the line is +processed by \TeX{} a \MF{} pair is produced representing a point on the +curve. \CMF{} pair expressions can be used in the output portion of +\cs{using}. For example \cs{using}\marg{\#1,\#2,\#3}\marg{(\#2,\#1)/10} +or even \cs{using}\marg{\#1 \#2 \#3}\marg{polar(\#1,\#2)} if the data +are polar coordinates. The default assumptions of the \cs{datafile} +command (numbers separated by spaces, with the first two determining the +$(x,y)$ pair) corresponds to the following setting. +\begin{verbatim} +\using{#1 #2 #3}{(#1,#2)} +\end{verbatim} +The \cs{using} command cannot normally be used in the replacement text +of another command. Or rather, it can be so used, but then each +\texttt{\#} has to be doubled. If a \cs{using} declaration occurs in an +\env{mfpic} environment it is local to that environment. Otherwise it +affects all subsequent ones. + +\begin{cd}\pagelabel{sequence} +\cs{sequence}% +\index{sequence@\cs{sequence}} +\end{cd} + +As a special case, you can plot any number against its sequence +position, with something like +\cs{using}\marg{\#1 \#2}\marg{(\cs{sequence},\#1)}. Here, the macro +\cs{sequence} will take on the values \texttt{1}, \texttt{2}, etc. as +lines are read from the file. + +\begin{cd}\pagelabel{usingpairdefault} +\cs{usingpairdefault}\\ +\cs{usingnumericdefault}% +\index{usingpairdefault@\cs{usingpairdefault}}% +\index{usingnumericdefault@\cs{usingnumericdefault}} +\end{cd} + +The command \cs{usingpairdefault} restores the above described default +for pair data. The command \cs{usingnumericdefault} is the equivalent of +\cs{using}\marg{\#1 \#2}\marg{\#1}, a useful default for numeric data. + +Note that the default value of \cs{using} appears to reference three +arguments. If there are only two numbers on a line separated by +whitespace, this will still work because of \TeX{}'s argument matching +rules. \TeX{}'s file reading mechanism normally converts the EOL to a +space, but there are exceptions so \mfp{} internally adds a space at +the end of each line read in to be on the safe side. Then the default +definition of \cs{using} reads everything up to the first space as +\texttt{\#1} (whitespace is normally compressed to a single space by +\TeX{}'s reading mechanism), then everything to the second space (the one +added at the end of the line, perhaps) is \texttt{\#2}, then everything +to the EOL is \texttt{\#3}. This might assign an empty argument to +\texttt{\#3}, but it is discarded anyway. + +If the numerical data contain percentages with explicit \texttt{\%} signs, +then choose another comment character with \cs{mfpdatacomment}. This +will change \texttt{\%} to an ordinary character \emph{in the data file}. +However, in your \cs{using} command it would still be read as a comment. +The following allows one to overcome this. + +\begin{cd}\pagelabel{makepercentother} +\cs{makepercentother}\\ +\cs{makepercentcomment}% +\index{makepercentother@\cs{makepercentother}}% +\index{makepercentcomment@\cs{makepercentcomment}} +\end{cd} + +Here is an example or their use: +\begin{verbatim} +\makepercentother +\using{#1% #2 #3}{(#1/100,#2)} +\makepercentcomment +\end{verbatim} + +Here is an analysis of the meaning of this example: everything in a +line, up to the first percent followed by a space is assigned to +parameter \texttt{\#1}, everything from there to the next space is +assigned to \texttt{\#2} and the rest of the line (which may be empty) +is \texttt{\#3}. On the output side in the above example, the percentage +is divided by 100 to convert it to a fraction, and plotted against the +second parameter. Note: normal comments should not be used between +\cs{makepercentother} and \cs{makepercentcomment}, for obvious reasons. +Moreover, the above construction will fail inside the argument of +another command. + +\begin{cd}\pagelabel{plotdata} +\cs{plotdata}\oarg{\meta{spec}}\marg{\meta{file}}% +\index{plotdata@\cs{plotdata}} +\end{cd} + +This plots several curves from a single file. The \meta{spec} and the +command \cs{smoothdata} have the same effect on each curve as in the +\cs{datafile} command. The data for each curve is a succession of +nonblank lines separated from the data for the next curve by a single +blank line. A \emph{pair} of successive blank lines is treated as the +end of the data. No prefix macros are permitted in front of +\cs{plotdata}. + +Each successive curve in the data file is drawn differently. By default, +the first is drawn as a solid line the next dashed, the third dotted, +etc., through a total of six different line types. A \cs{gendashed} +command is used with predefined dash patterns named \mfc{dashtype0} +through \mfc{dashtype5}. This behavior can be changed with: + +\begin{cd}\pagelabel{coloredlines} +\cs{coloredlines}\\ +\cs{pointedlines}\\ +\cs{datapointsonly}\\ +\cs{dashedlines}% +\index{coloredlines@\cs{coloredlines}}% +\index{pointedlines@\cs{pointedlines}}% +\index{datapointsonly@\cs{datapointsonly}}% +\index{dashedlines@\cs{dashedlines}} +\end{cd} + +The command \cs{coloredlines} causes \cs{plotdata} to use the rendering +command \cs{draw} with a color option that cycles through eight +different colors starting with black (hey! black is a color too). The +command \cs{pointedlines} causes \cs{plotdata} to use the rendering +command \cs{plot}, cycling through nine symbols. The command +\cs{datapointsonly} causes \cs{plotdata} to use the rendering command +\cs{plotnodes}, cycling through the same nine symbols. The data points +become the nodes of the paths created and so only the data points are +plotted. The command \cs{dashedlines} restores the default. See +appendix~\ref{styles} for the details on the actual dash patterns, +colors and symbols used. + +The command \cs{coloredlines} will produce a warning under the +\opt{metafont} option and substitute \cs{dashedlines}. Under the +\opt{metapost} option, this is the sole exception to the general rule +that all curves are drawn in \gbc{drawcolor} by default: the +\cs{plotdata} command after \cs{coloredlines} has been issued. + +If, for some reason, you do not like the default starting line style +(say you want to start with a color other than black), you can use one +of the following commands. + +\begin{cd}\pagelabel{mfplinetype} +\cs{mfplinetype}\marg{\meta{num}}, or\\ +\cs{mfplinestyle}\marg{\meta{num}}% +\index{mfplinetype@\cs{mfplinetype}}% +\index{mfplinestyle@\cs{mfplinestyle}} +\end{cd} + +Here \meta{num} is a non-negative number, less than the number of +different drawing types available. The four previous commands reset the +number to 0, so if you use one of them, issue \cs{mfplinetype} +\emph{after} it. The different line styles are numbered starting from +$0$. If two or more \cs{plotdata} commands are used in the same +\env{mfpic} environment, the numbering in each continues where the one +before left off (unless you issue one of the commands above in between). +\cs{mfplinestyle} means the same as \cs{mfplinetype}, and is included +for compatibility. See appendix~\ref{styles} to find out what dash pattern, +color or symbol corresponds to each number by default. The commands +below can be used to change the default dashes, colors, or symbols. + +\begin{cd}\pagelabel{reconfigureplot} +\cs{reconfigureplot}\marg{dashes}\marg{\meta{pat$_1$},\dots,\meta{pat$_n$}}\\ +\cs{reconfigureplot}\marg{colors}\marg{\meta{clr$_1$},\dots,\meta{clr$_n$}}\\ +\cs{reconfigureplot}\marg{symbols}\marg{\meta{symb$_1$},\dots,\meta{symb$_n$}}% +\index{reconfigureplot@\cs{reconfigureplot}} +\end{cd} + +The first argument of \cs{reconfigureplot} is the rendering method to be +changed: \texttt{dashes}, \texttt{colors}, or \texttt{symbols}. The +second argument is a list of dash patterns, colors, or symbols. The dash +patterns should be names of patterns defined through the use of +\cs{dashpattern}. The colors can be any color names already known to +\MP{}, or defined through \cs{mfpdefinecolor}. The symbols can be any of +those listed with the \cs{plotsymbol} command (see +subsection~\ref{points}), or any known \MF{} path variable. The colors +can also be \MP{} color constants or expressions, and the symbols can be +expressions of type path. In recent \MP{} these `colors' can be +\kw{numeric} (selecting gray), \kw{rgbcolor} or \kw{cmykcolor}. Within a +\env{mfpic} environment, the changes made are local to that environment. +Outside, they affect all subsequent environments. + +Using \cs{reconfigureplot}\marg{colors} under the \opt{metafont} option +will have no effect, but may produce an error from \MF{} unless the +colors used conform to the guidelines in subsection~\ref{MFcolor}. +This also holds for \cs{defaultplot}\marg{colors} (below). + +\begin{cd}\pagelabel{defaultplot} +\cs{defaultplot}\marg{dashes}\\ +\cs{defaultplot}\marg{colors}\\ +\cs{defaultplot}\marg{symbols} +\index{defaultplot@\cs{defaultplot}} +\end{cd} + +The command \cs{defaultplot} restores the built-in defaults for the +indicated method of rendering in \cs{plotdata}. + +The commands \cs{using}, \cs{mfpdatacomment} and \cs{sequence} have the +same meaning here (for \cs{plotdata}) as they do for \cs{datafile} +(above). The sequence numbering for \cs{sequence} starts over with each +new curve. + +\section{Labels and Captions.}\label{labels} + +\subsection{Setting text}\label{text} + +If option \opt{metafont} is in effect macros \cs{tlabel}, \cs{tlabels}, +\cs{axislabels} and \cs{tcaption} do not affect the \MF{} file +(\file{\meta{file}.mf}) at all, but are added to the picture by \TeX{}. If +\opt{metapost} is in effect but \opt{mplabels} is not, they do not +affect the \MP{} file. In these cases, if these macros are the only +changes or additions to your document, there is no need to repeat the +processing with \MF{} or \MP{} nor the reprocessing with \TeX{} in order +to complete your \TeX{} document. + +\begin{cd}\pagelabel{tlabel} +\cs{tlabel}\oarg{\meta{just}}\parg{\meta{x},\meta{y}}\marg{\meta{labeltext}}\\ +\cs{tlabel}\oarg{\meta{just}}\marg{\meta{pair-list}}\marg{\meta{label text}}\\ +\cs{tlabels}\marg{\meta{params$_1$} \meta{params$_2$} $\ldots$}% +\index{tlabel@\cs{tlabel}}% +\index{tlabels@\cs{tlabels}} +\end{cd} + +These place \TeX{} text or math on the graph. The special form +\cs{tlabels} (note the plural) essentially just applies \cs{tlabel} to +each set of parameters listed in its argument. That is, each +\meta{params$_k$} is a valid set of parameters for a \cs{tlabel} +command. These can be separated by spaces, newlines, or nothing at all. +They should \emph{not} be separated by blank lines. + +The last required parameter is ordinary \TeX{} text. The pair +\parg{\meta{x},\meta{y}} gives the coordinates of a point in the graph +where the text will be placed. It may optionally be enclosed in braces, +\verb${$ and \verb$}$. If braces are used, any number of coordinate +pairs may be listed, separated by commas. This is what is meant by +\meta{pair-list} in the above syntax. If \opt{mplabels} is in effect, +the \meta{pair-list} can be any list of expressions recognized as a pair +by \MP{}. + +The optional parameter \oarg{\meta{just}} specifies the +\emph{justification}, the relative placement of the label with respect +to the point with coordinates \parg{\meta{x},\meta{y}}. It is a +two-character sequence in which the first character is one of \texttt{t} +(top), \texttt{c} (center), \texttt{b} (bottom), or \texttt{B} +(Baseline), to specify vertical placement, and the second character is +one of \texttt{l} (left), \texttt{c} (center), or \texttt{r} (right), to +specify horizontal placement. These letters specify what part of the +\emph{text} is to be placed at the given point, so \texttt{r} puts the +right end of the text there---which means the text will be left of the +point. The default justification is \oarg{Bl}: the left end of the +baseline of the text is placed at the coordinates. + +When \opt{mplabels} is in effect, the two characters may optionally be +followed by a number, specifying an angle in degrees to rotate the text +about the point \parg{\meta{x},\meta{y}}. If the angle is supplied +without \opt{mplabels} it is ignored after a warning. If the angle is +absent, there is no rotation. Note that the rotation takes place after +the placement and uses the given point as the center of rotation. For +example, \oarg{cr} will place the text left of the point, while +\oarg{cr180} will rotate it around to the right side of the point (and +upsidedown, of course). + +There should be no spaces before, between, or after the first two +characters. However the number, if present, is only required to be a +valid \MP{} numerical expression containing no bracket characters; as +such, it may contain some spaces (e.g., around operations as in +\texttt{45 + 30}). + +A multiline \cs{tlabel} may be specified by explicit line breaks, which +are indicated by the \bbsl{} command or the \cs{cr} command. This is a +very rudimentary feature. By default it left justifies the lines and +causes \cs{tlabel} to redefine \bbsl. One can center a line by putting +\cs{hfil} as the first thing in the line, and right justify by putting +\cs{hfill} there (these are \TeX{} primitives). Redefining \bbsl{} can +interfere with \LaTeX{}'s definition. For better control in \LaTeX{} use +\cs{shortstack} inside the label (or a \env{tabular} environment or some +other environment which always initializes \bbsl{} with its own +definition). + +If the label goes beyond the bounds of the graph in any direction, the +space reserved for the graph is expanded to make room for it. (Note: +this behavior is very much different from that of the \LaTeX{} +\env{picture} environment.) + +If the \opt{mplabels} option is in effect, \cs{tlabel} will write a +\mfc{btex $\ldots$ etex} group to the output file, allowing \MP{} to +arrange for typesetting the label. Normally, the label becomes part of +the picture, rather than being laid on top of it, and can be covered up +by any filling macros that follow, or clipped off by \cs{gclip}. +However, under the \opt{overlaylabels} option (or after the command +\cs{overlaylabels}), labels are saved and added to the picture at the +very end. This may prevent some special effects, but it makes the +behavior of labels much more consistent through all the 12 permissable +settings of the options \opt{metapost}, \opt{mplabels}, \opt{clip}, and +\opt{truebbox}. + +There is another command, \cs{startbacktext}, which also save the labels +and adds them later, but \emph{under} the rest of the picture as +background text. Thus, they will not be clipped, but may be covered up. +Since erasing regions with \cs{gclear} actually covers up those regions +with white, labels saved as background text may appear to have portions +erased. + +\begin{cd}\pagelabel{everytlabel} +\cs{everytlabel}\marg{\meta{\TeX{}-code}}% +\index{everytlabel@\cs{everytlabel}} +\end{cd} + +One problem with multiline \cs{tlabel}s is that each line of their +contents constitutes a separate group. This makes it difficult to change +the \cs{baselineskip} (for example) inside a label. The command +\cs{everytlabel} saves it's contents in a token register and the code is +issued in each \cs{tlabel}, as the last thing before the actual line(s) +of text. Any switch you want to apply to every line can be supplied. For +example +\begin{verbatim} +\everytlabel{\bf\baselineskip 10pt} +\end{verbatim} +will make every line of every \cs{tlabel}'s text come out bold with 10 +point baselines. The effect of \cs{everytlabel} is local to the +\env{mfpic} environment, if it is issued inside one. Note that each line +of a tlabel is wrapped in a box, but the commands of \cs{everytlabel} +are outside all of them, so no actual text should be produced by the +contents of \cs{everytlabel}. + +Using \cs{tlabel} without an optional argument is equivalent to +specifying \oarg{Bl}. Use the following command to change this +behavior. + +\begin{cd}\pagelabel{tlabeljustify} +\cs{tlabeljustify}\marg{\meta{just}}% +\index{tlabeljustify@\cs{tlabeljustify}} +\end{cd} + +After this command the placement of all subsequent labels without +optional argument will be as specified in this command. For example, +\cs{tlabeljustify}\marg{cr45} would cause all subsequent \cs{tlabel} +commands lacking an optional argument to be placed as if the argument +\oarg{cr45} were used in each. If \opt{mplabels} is not in effect at the +time of this command, the rotation part will be saved in case that +option is turned on later, but a warning message will be issued. If +\opt{mplabels} is not turned on later, that rotation will be ignored by +\cs{tlabel}. + +\begin{cd}\pagelabel{tlabeloffset} +\cs{tlabeloffset}\marg{\meta{hlen}}\marg{\meta{vlen}}\\ +\cs{tlpointsep}\marg{\meta{len}}\\ +\cs{tlpathsep}\marg{\meta{len}}\\ +\cs{tlabelsep}\marg{\meta{len}}% +\index{tlabeloffset@\cs{tlabeloffset}}% +\index{tlabelsep@\cs{tlabelsep}}% +\index{tlpathsep@\cs{tlpathsep}}% +\index{tlpointsep@\cs{tlpointsep}} +\end{cd} + +The first command causes all subsequent \cs{tlabel} commands to shift +the label right by \meta{hlen} and up by \meta{vlen} (negative lengths +cause it to be shifted left and down, respectively). + +The \cs{tlpointsep} command causes labels to be shifted by the given +amount in a direction that depends on the optional positioning +parameter. For example, if the first letter is \texttt{t} the label is +shifted down by the amount \meta{len} and if the second letter is +\texttt{l} it is also shifted right. In all cases it is shifted +\emph{away} from the point of placement (unless the dimension is +negative). If \texttt{c} or \texttt{B} is the first parameter, no +vertical shift takes place, and if \texttt{c} is the second, there is no +horizontal shift. This is intended to be used in cases where something +has been drawn at that particular point, in order to separate the text +from the drawing. + +Prior to version 0.8, this separation also defined the separation +between the label and those curves designed to frame the label +such as \cs{tlabelrect} (subsection~\ref{surrounding}). Now the two +separations are independent and \cs{tlpathsep} is used to set the +separation between the label and such paths. + +For backward compatability, the command \cs{tlabelsep} is still +available and sets both separations to the same value. + +\begin{cd}\pagelabel{axislabels} +\cs{axislabels}\marg{\meta{axis}}\oarg{\meta{just}}% + \marg{\marg{\meta{text$_1$}}\meta{$n_1$},% + \marg{\meta{text$_2$}}\meta{$n_2$},$\ldots$}% +\index{axislabels@\cs{axislabels}} +\end{cd} + +This command places the given \TeX{} text (\meta{text$_k$}) at the given +positions (\meta{$n_k$}) on the given axis, \meta{axis}, which must be a +single letter and one of \texttt{l}, \texttt{b}, \texttt{r}, \texttt{t}, +\texttt{x}, or \texttt{y}. The text is placed as in \cs{tlabels} +(including the taking into account of \cs{tlpointsep} and +\cs{tlableoffset}), except that the default justification depends on the +axis (the settings of \cs{tlabeljustify} are ignored). In the case of +the border axes, the default is to place the label outside the axis and +centered. So, for example, for the bottom axis it is \oarg{tc}. The +defaults for the $x$- and $y$-axis are below and left, respectively. The +optional \meta{just} can be used to change this. For example, to place +the labels \emph{inside} the left border axis, use \oarg{cl}. If +\opt{mplabels} is in effect, rotations can be included in the +justification parameter. For example, to place the text strings +`first', `second' and `third' just below the positions 1, 2 and 3 +on the $x$-axis, rotated so they read upwards at a 90 degree angle, one +can use \cs{axislabels}\marg{x}\oarg{cr90}\marg{\marg{first}1, +\marg{second}2, \marg{third}3}. + +\begin{cd}\pagelabel{plottext} +\cs{plottext}\oarg{\meta{just}}\marg{\meta{text}}\marg{($x_0$,$y_0$), + ($x_1$,$y_1$), $\ldots$}% +\index{plottext@\cs{plottext}} +\end{cd} + +Similar in effect to \cs{point} and \cs{plotsymbol} (but without +requiring \MF{}), \cs{plottext} places a copy of \meta{text} at each of +the listed points. Since version 0.9, when \cs{tlabel} was enhanced to +allow lists of points, it is implemented by an equivalent \cs{tlabel} +command and is only kept for backward compatibility. It differs from +\cs{tlabel} when the optional argument is absent: the default +justification is \oarg{cc} regardless of the setting of +\cs{tlabeljustify}. + +\begin{cd}\pagelabel{mfpverbtex} +\cs{mfpverbtex}\marg{\meta{\TeX{}-cmds}}% +\index{mfpverbtex@\cs{mfpverbtex}} +\end{cd} + +This writes a \mfc{verbatimtex} block to the \file{.mp} file. It makes +sense only if the \opt{mplabels} option is used and so only for \MP{}. +The \meta{\TeX{}-cmds} in the argument are written to the \file{.mp} +file, preceded by the \MP{} command \mfc{verbatimtex} and followed by +\mfc{etex}. Line breaks within the \meta{\TeX{}-cmd} are preserved. The +\cs{mfpverbtex} command must come before any \cs{tlabel} that is to be +affected by it. Any settings common to all \env{mfpic} environments +should be in a \cs{mfpverbtex} command preceding all such environments. + +It may be issued at any point after \mfp{} is loaded, and any number of +times. If it is issued after \cs{opengraphsfile}, its contents are +immediately written to the \file{.mp} file. If it is issued before +\cs{opengraphsfile}, its contents are saved and written when the file is +opened (successive uses being cummulative). In this case its contents +will precede the boilerplate \TeX{} code that \mfp{} writes. If you wish +to redefine some of that code, you need to use \cs{mfpverbtex} after +\cs{opengraphsfile}. + +Because of the way \MP{} handles \mfc{verbatimtex} material, the effects +cannot be constrained by any grouping unless one places \TeX{} grouping +commands within \meta{\TeX{}-cmds}. However, \mfp{} itself places +grouping commands into the output file at the beginning and end of each +picture, so definitions written by a \cs{mfpverbtex} are local to any +picture in which it occurs. Prior to version 0.8, \mfp{} did not write +comments that occured within the \meta{\TeX{}-cmds}. Now they will be +preserved, and can be used to place the `\verb$%&latex$' line that some +\TeX{} distributions permit as a signal that latex should be run to +produce the labels. + +This command attempts a near-verbatim writing of the \meta{\TeX{}-cmds} +and, as with all verbatim-like commands, it should not be used in the +argument of another command. + +\begin{cd}\pagelabel{backtext} +\cs{startbacktext} \dots \cs{stopbacktext}% +\index{startbacktext@\cs{startbacktext}}% +\index{stopbacktext@\cs{stopbacktext}} +\end{cd} + +When \TeX{} adds labels (\cs{nomplabels}) they have to be positioned +either on top of a complete figure, or placed under a complete figure. +The most reasonable choice (and happily the easiest to implement) is to +put them on top. When \MP{} is placing labels (option \opt{mplabel}) the +same can be forced with the option \opt{overlaylabels}, but otherwise +they are placed as they occur, with later drawing commands perhaps +putting their results on top of the labels or clipping parts of them off. + +Sometimes it is useful to place some label as a background (not on top), +and yet not have it clipped by later commands. The effect of the command +\cs{startbacktext} is that \cs{tlabel} commands are saved in a special +place until the command \cs{stopbacktext}. Then, at \cs{endmfpic} the +rest of the figure is simply place on top of them. Since labels in \MP{} +files can only consist of characters from some font, if one wants to +include a graphic in the background (for example, via +\cs{includegraphics}), one needs to switch off \opt{mplabels}: +\begin{verbatim} +\nomplabels +\startbacktext + \tlabel[cc](0,0){\includegraphics{mygraph}} +\stopbacktext +\usemplabels +\end{verbatim} +As with other labels, it is permitted to switch \opt{mplabels} off and +on while creating background text. If there are both kinds of labels +within the background text area the ones handled by \TeX{} will be +further back than the ones handled by \MP{}. Within a given type, +earlier ones are further back than later ones. + +\Mfp{} normally uses a naming scheme like \cs{cmd} \dots \cs{endcmd} and +tries to arrange that \env{cmd} can be used as an environment. As +currently written, the extra grouping added by \cs{begin}\marg{cmd} and +\cs{end}\marg{cmd} would break the code that implements background text, +so we have named these in a different way to avoid suggesting this +possiblity. There should be at most one of these pairs in any +\env{mfpic} environment. It can occur anywhere in the environment, but +the two commands must not be inside any grouping. + +Under the \opt{metapost} option, the \cs{gclear} command doesn't really +clear a space, but rather paints the space over with white. Any +background text will not be visible through such `holes'. This is a +limitation of \MP{}. + +\begin{cd}\pagelabel{tcaption} +\cs{tcaption}\oarg{\meta{maxwd},\meta{linewd}}\marg{\meta{caption text}}% +\index{tcaption@\cs{tcaption}} +\end{cd} + +Places a \TeX{} caption at the bottom of the graph. (Not to be confused +with \LaTeX{}'s similar \cs{caption} command.) The macro will +automatically break lines which are too much wider than the graph---if +the \cs{tcaption} line exceeds \meta{maxwd} times the width of the +graph, then lines will be broken to form lines at most \meta{linewd} +times the width of the graph. The default settings for \meta{maxwd} and +\meta{linewd} are 1.2 and 1.0, respectively. \cs{tcaption} may typeset +its argument twice (as might \LaTeX{}'s \cs{caption}), the first time as +a single line to test its width, then again if that was too wide. +Therefore, the user is advised \emph{not} to include any global +assignments in the caption text. + +If the \cs{tcaption} and graph have different widths, the two are +centered relative to each other. If the \cs{tcaption} takes multiple +lines, then the default is to set lines both left- and right-justified +(except for the last line) with no indentation on the first line. If the +option \opt{raggedcaptions} is in effect, the lines are only +left-justified and ragged on the right. Finally, if the option +\opt{centeredcaptions} is in effect, each line of the caption will be +centered (under \opt{raggedcaptions} they will be ragged on both sides). + +In a \cs{tcaption}, explicit line breaks may be specified by using the +\bbsl{} command. The separation between the bottom of the picture and +the caption can be changed by increasing or decreasing the skip +\cs{mfpiccaptionskip}\index{mfpiccaptionskip@\cs{mfpiccaptionskip}} +(a `rubber' length in Lamport's terminology). + +Many \mfp{} users find the \cs{tcaption} command too limiting (one +cannot, for example, place the caption to the side of the figure). It is +common to use some other method (such as \LaTeX{}'s \cs{caption} command +in a \env{figure} environment). The dimensions \cs{mfpicheight} and +\cs{mfpicwidth} (see section~\ref{parameters}) might be a convenience +for plain \TeX{} users who want to roll their own caption macros. + + +\subsection{Curves surrounding text}\label{surrounding} + +\begin{cd}\pagelabel{tlabelrect} +\cs{tlabelrect}\oarg{\meta{rad}}\oarg{\meta{just}}% + \meta{pair}\marg{\meta{text}}\\ +\cs{tlabelrect*...}% +\index{tlabelrect@\cs{tlabelrect}} +\end{cd} + +This figure macro and the following two methods of surounding a bit of +text with a curve share some common characteristics which will be +described here. The commands all take an optional argument that can +modify the shape of the curve. After that come arguments exactly as for +the \cs{tlabel} command except that only a single point is permitted, +not a list. (So \meta{pair} is either of the form +\parg{\meta{x},\meta{y}} or the same enclosed in braces, or for +\opt{mplabels} a pair expression in braces.) After processing the +surrounding curve, a \cs{tlabel} is applied to those arguments unless a +\texttt{*} is present. In order for the second optional argument (the +optional justification argument for the \cs{tlabel} command) to be +recognized as the second, the first optional argument must also be +present. An empty first optional argument is permitted, causing the +default value to be used. The default for the justification argument is +\texttt{cc}, for compatibility with past \mfp{} versions, in which these +commands all centered the figure around the point and no justification +parameter existed. This default can be changed with the +\cs{tlpathjustify} command below. + +The plain rectangle version produces a frame separated from the text on +all sides by the amount defined with \cs{tlpathsep}. All other versions +produce the smallest described curve that contains this rectangle. + +These commands may be preceded by prefix macros (see the sections +\ref{modifier}~and \ref{rendering}, above). They all have a +`star-form' which produces the curve but omits placing the text. +All have the effect of rendering the path \emph{before} placing any +text. For example, \cs{gclear}\cs{tlabelrect}\dots\ will clear the +rectangle and then place the following text in the cleared space. + +The optional argument of \cs{tlabelrect}, \meta{rad}, is a dimension, +defaulting to \dim{0pt}, that produces rounded corners made from +quarter-circles of the given radius. If the corners are rounded, the +sides are expanded slightly so the resulting shape still encompasses the +rectangle mentioned above. There is one special case for the optional +argument \meta{rad}: if the keyword `\texttt{roundends}' is used instead +of a dimension, the radius will be chosen to make the nearest quarter +circles just meet, so the narrow side of the rectangle is a half circle. + +\begin{cd}\pagelabel{tlabeloval} +\cs{tlabeloval}\oarg{\meta{mult}}\oarg{\meta{just}}% + \meta{pair}\marg{\meta{text}}\\ +\cs{tlabeloval*...}% +\index{tlabeloval@\cs{tlabeloval}} +\end{cd} + +This figure macro is similar to \cs{tlabelrect}, except it produces an +ellipse. The ellipse is calculated to have the same ratio of width to +height as the rectangle mentioned above. The optional \meta{mult} is a +multiplier that increases or decreases this ratio. Values of \meta{mult} +larger than 1 increase the width and decrease the height. + +\begin{cd}\pagelabel{tlabelellipse} +\cs{tlabelellipse}\oarg{\meta{ratio}}\oarg{\meta{just}}% + \meta{pair}\marg{\meta{text}}\\ +\cs{tlabelellipse*...}\\ +\cs{tlabelcircle}\oarg{\meta{just}}\meta{pair}\marg{\meta{text}}\\ +\cs{tlabelcircle*...}% +\index{tlabelellipse@\cs{tlabelellipse}}% +\index{tlabelcircle@\cs{tlabelcircle}} +\end{cd} + +This figure macro produces the smallest ellipse centered at the point +that encompasses the rectangle defined above, and that has a ratio of +width to height equal to \meta{ratio}, then places the text. The default +ratio is $1$, which produces a circle. We also provide the command +\cs{tlabelcircle}, which takes only the \oarg{\meta{just}} optional +argument. Internally, it just processes any \texttt{*} and calls +\cs{tlabelellipse} with parameter 1. + +In the above \cs{tlabel...} curves, the optional parameter should be +positive. If it is zero, all the curves silently revert to +\cs{tlabelrect}. If it is negative, it is silently accepted. In the case +of \cs{tlabelrect} this causes the quarter-circles at the corners to be +indented rather than convex. In the other cases, there is no visible +effect, but in all cases the sense of the curve is reversed. + +\begin{cd}\pagelabel{tlpathjustify} +\cs{tlpathjustify}\marg{\meta{just}}% +\index{tlpathjustify@\cs{tlpathjustify}} +\end{cd} + +This can be used to change the default justification for \cs{tlabelrect} +and friends. The \meta{just} parameter is exactly as in +\cs{tlabeljustify} in subsection~\ref{text}. + + +\section{Saving and Reusing an \mfp{} Picture.}\label{saving} + +These commands have been changed from versions prior to 0.3.14 in order +to behave more like the \LaTeX{}'s \cs{savebox}, and also to allow the +reuse of an allocated box. Past files that use \cs{savepic} will have to +be edited to add \cs{newsavepic} commands that allocate the \TeX{} +boxes. + +\begin{cd}\pagelabel{newsavepic} +\cs{newsavepic}\marg{\meta{picname}}\\ +\cs{savepic}\marg{\meta{picname}}\\ +\cs{usepic}\marg{\meta{picname}}% +\index{newsavepic@\cs{newsavepic}}% +\index{savepic@\cs{savepic}}% +\index{usepic@\cs{usepic}} +\end{cd} + +\cs{newsavepic} allocates a box (like \LaTeX{}'s \cs{newsavebox}) in which +to save a picture. As in \cs{newsavebox}, \meta{picname} is a control +sequence. Example: \cs{newsavepic}\marg{\cs{foo}}. In a \LaTeX{} +document, \cs{newsavepic} is actually defined to be \cs{newsavebox}. + +\cs{savepic} saves the \emph{next} \cs{mfpic} picture in the named box, +which should have been previously allocated with \cs{newsavepic}. (This +command should not be used \emph{inside} an \env{mfpic} environment.) +The next picture will not be placed, but saved in the box for later use. +This is primarily intended as a convenience. One \emph{could} use +\begin{ex} + \cs{savebox}\marg{\meta{picname}}\marg{\meta{entire + \env{mfpic} environment}}, +\end{ex} +but \cs{savepic} avoids having to place the \env{mfpic} environment in +braces, and avoids one extra level of \TeX{} grouping. It also avoids +reading the entire \env{mfpic} environment as a parameter, which would +nullify \mfp{}'s efforts to preserve line breaks in parameters +written to the \MF{} output file. If you repeat \cs{savepic} with the +same \meta{picname}, the old contents are replaced with the next +picture. + +\cs{usepic} copies the picture that had been saved in the named box. +This may be repeated as often as liked to create multiple copies of one +picture. The \cs{usepic} command is essentially a clone of the \LaTeX{} +\cs{usebox} command. Since the contents of the saved picture are only +defined during the \TeX{} run, \cs{usebox} cannot be used in the +\TeX-commands argument of the \cs{tlabel} command while \opt{mplabels} +is in effect. + + +\section{Picture Frames.}\label{frames} + +When \TeX{} is run but before \MF{} or \MP{} has been run on the output +file, \mfp{} detects that the \file{.tfm} file is missing or that +the first \MP{} figure file \file{\meta{file}.1} is missing. In these +cases, the \env{mfpic} environment draws only a rectangular frame with +dimensions equal to the nominal size of the picture, containing the +figure number (and any text placed by \cs{tlabel} and its relatives +without \opt{mplabels} in effect). The command(s) used internally to do +this are made available to the user. + +\begin{cd}\pagelabel{mfpframe} +\cs{mfpframe}\oarg{\meta{fsep}}% + \meta{ material-to-be-framed }% +\cs{endmfpframe}\\ +\cs{mfpframed}\oarg{\meta{fsep}}\marg{\meta{material-to-be-framed}}% +\index{mfpframed@\cs{mfpframed}}% +\index{endmfpframe@\cs{endmfpframe}}% +\index{mfpframe@\cs{mfpframe}} +\end{cd} + +These commands surround their contents with a rectangular frame +consisting of lines with thickness \cs{mfpframethickness} separated from +the contents by the \meta{fsep} if specified, otherwise by the value of +the dimension \cs{mfpframesep}. The default value of the \TeX{} +dimensions \cs{mfpframesep} and \cs{mfpframethickness} are \dim{2pt} and +\dim{0.4pt}, respectively. The \cs{mfpframe} $\ldots$ \cs{endmfpframe} +version is preferred around \env{mfpic} environments or verbatim +material since it avoids reading the enclosed material before +appropriate \cs{catcode} changes go into effect. In \LaTeX{}, one can +also use environment syntax: \cs{begin}\marg{mfpframe} $\ldots$ +\cs{end}\marg{mfpframe}. + +An alternative way to frame \env{mfpic} pictures is to save them with +\cs{savepic} (see previous section) and issue a corresponding +\cs{usepic} command inside any framing environment or command of the user's +choice or devising. + + +\section{Affine Transforms.}\label{transforms} + +Coordinate transformations that keep parallel lines in parallel are +called \emph{affine transforms}. These include translation, rotation, +reflection, scaling and skewing (slanting). For the \MF{} coordinate +system only---that is, for paths, but not for \cs{tlabel}'s (let alone +\cs{tcaption}'s)---\mfp{} provides the ability to apply \MF{} +affine transforms. + + +\subsection{Transforming the \MF{} coordinate system}\label{affine} + +\begin{cd}\pagelabel{coords} +\cs{coords} \dots \cs{endcoords}% +\index{coords@\cs{coords}}% +\index{endcoords@\cs{endcoords}} +\end{cd} + +All affine transforms are restricted to the innermost enclosing +\cs{coords}$\ldots$\cs{endcoords} pair. If there is \emph{no} such +enclosure, then the transforms will apply to the rest of the \env{mfpic} +environment. In \LaTeX{}, one can use the environment named +\env{coords}. + +\medskip +\noindent Transforms provided by \mfp{}: + +\nobreak +\begin{cd}\pagelabel{applyT}% +\begin{tabular}[b]{@{}ll@{}} + \cs{rotate}\marg{\meta{$\theta$}}% + \index{rotate@\cs{rotate}}% + & Rotate around origin by \meta{$\theta$} degrees.\\ + \cs{rotatearound}\marg{\meta{$p$}}\marg{\meta{$\theta$}}% + \index{rotatearound@\cs{rotatearound}}% + & Rotate around point \meta{$p$} by \meta{$\theta$} degrees.\\ + \cs{turn}\oarg{\meta{p}}\marg{\meta{$\theta$}}% + \index{turn@\cs{turn}}% + & Rotate around point \meta{p} (origin is default) by + \meta{$\theta$}.\\ + \cs{reflectabout}\marg{\meta{$p_1$}}\marg{\meta{$p_1$}}% + \index{reflectabout@\cs{reflectabout}}% + & Reflect in the line through points \meta{$p_1$} and \meta{$p_2$}.\\ + \cs{mirror}\marg{\meta{$p_1$}}\marg{\meta{$p_2$}}% + \index{mirror@\cs{mirror}}% + & Same as \cs{reflectabout}.\\ + \cs{shift}\marg{\meta{v}}% + \index{shift@\cs{shift}}% + & Shift origin by the vector \meta{v}.\\ + \cs{scale}\marg{\meta{s}}% + \index{scale@\cs{scale}}% + & Scale uniformly by a factor of \meta{s}.\\ + \cs{xscale}\marg{\meta{s}}% + \index{xscale@\cs{xscale}}% + & Scale only the $x$ coordinates by a factor of \meta{s}.\\ + \cs{yscale}\marg{\meta{s}}% + \index{yscale@\cs{yscale}}% + & Scale only the $y$ coordinates by a factor of \meta{s}.\\ + \cs{zscale}\marg{\meta{pair}}% + \index{zscale@\cs{zscale}}% + & Scale by the magnitude of vector \meta{v}, and rotate by its + angle.\\ + \cs{xslant}\marg{\meta{s}}% + \index{xslant@\cs{xslant}}% + & Skew in $x$ direction by the multiple \meta{s} of $y$.\\ + \cs{yslant}\marg{\meta{s}}% + \index{yslant@\cs{yslant}}% + & Skew in $y$ direction by the multiple \meta{s} of $x$.\\ + \cs{zslant}\marg{\meta{pair}}% + \index{zslant@\cs{zslant}}% + & See \mfc{zslanted} in \file{grafbase.dtx}.\\ + \cs{boost}\marg{\meta{$\chi$}}% + \index{boost@\cs{boost}}% + & Special relativity boost by $\chi$, see \mfc{boost} in + \file{grafbase.dtx}.\\ + \cs{xyswap}% + \index{xyswap@\cs{xyswap}}% + & Exchange the values of $x$ and $y$.\\ + \cs{applyT}\marg{\meta{transformer}}% + \index{applyT@\cs{applyT}}% + & Apply the \meta{transformer}. +\end{tabular} +\end{cd} + +\cs{applyT} is for \MF{} hackers. Any code is permitted that satisfies +\MF{}'s syntax for a \meta{transformer} (see D.~E.~Knuth, ``The +\MF{}book'', page~73), although no effort is made to correctly write +\TeX{} special characters nor to preserve linebreaks in the code. + +When any of these commands is issued, the effect is to transform all +subsequent figures (within the enclosing \env{coords} or \env{mfpic} +environment). In particular, attention may need to be paid to whether +these transformations move (part of) the figure outside the space +allotted by the \cs{mfpic} command parameters. + +A not-so-obvious point is that if several of these transformations are +applied in succession, then the most recent is applied first, so that +figures are transformed as if the transformations were applied in the +reverse order of their occurrence. This is similar to the application of +prefix macros (as well as application of transformations in mathematics: +$S T z$ usually means to apply $S$ to the result of $T z$). + +Finally, some of these may not produce what the unwary user might expect +if the \env{mfpic} environment was started with unequal scaling. For +example, in such a case a rotated rectangle will not have right angles +unless the rotation is by a multiple of 90 degrees. The reason for this: +the scaling given by the \cs{mfpic} command is applied last and +slanted lines subjected to unequal horizontal and verical scaling will +change have their angles changed. + + +\subsection{Transforming paths}\label{transformation} + +In the previous section we discussed transformations of the \MF{} +coordinate system. Those macros affect the \emph{drawing} of paths and +other figures, but do not change the actual paths. We will explain the +distinction after introducing two macros for storing and reusing +figures. + +\begin{cd}\pagelabel{store} +\cs{store}\marg{\meta{path variable}}\marg{\meta{path}}\\ +\cs{store}\marg{\meta{path variable}}\meta{path}% +\index{store@\cs{store}} +\end{cd} + +This stores the following \meta{path} in the specified \MF{} \meta{path +variable}. Any valid \MF{} symbolic token will do, in particular, any +sequence of letters and underscores. You should be careful to make the +name distinctive to avoid overwriting the definition of some internal +variable. The stored path may later be used as a figure macro +using \cs{mfobj} (below). The \meta{path} may be any of the figure +macros (such as \cs{curve}\marg{(0,0),(1,0),(1,1)}) or the result of +modifying it. For example: +\begin{verbatim} +\store{pth}\lclosed\reverse\curve{(0,0),(1,0),(1,1)} +\end{verbatim} + +In fact, \cs{store} is a prefix macro that does nothing to the following +curve except store it. It acts as a rendering macro with a null +rendering, so the curve is not made visible unless other rendering +macros appear before or after it. It allows the following path to be an +argument, that is, enclosed in braces. This is solely to support files +written for past \mfp{} versions in which \cs{store} was \emph{not} +defined as a prefix macro. + +One use of \cs{store} is to create a shorthand for a path that is +otherwise long and tedious to type. Another is to create `symbols' or +`arrowheads' for use in \cs{plotsymbol}, \cs{arrowhead} and related +commands. + +\begin{cd}\pagelabel{mfobj} +\cs{mfobj}\marg{\meta{path expression}}\\ +\cs{mpobj}\marg{\meta{path expression}}% +\index{mfobj@\cs{mfobj}}% +\index{mpobj@\cs{mpobj}} +\end{cd} + +This figure macro produces the path represented by \meta{path +expression}, which is either a path variable in which a path was +previously stored, or a valid \MF{} expression combining such variables +and constant paths. This allows the use of path variables or +expressions as figure macros, permitting all prefix operations, etc.. +Here are some examples of the use of \cs{store} and \cs{mfobj}. + +\nobreak +\begin{verbatim} +\store{my_f}{\cyclic{...}} % Store a closed curve. +\dotted\mfobj{my_f} % Now draw it dotted, +\hatch\mfobj{my_f} % and hatch its interior +% Create two symbols +% one outline: +\store{MyTriang}{\polyline{(-.5,-.5),(.5,-.5),(0,.5),(-.5,-.5)} +% one solid: +\store{MySolidTriang}{\polygon{(-.5,-.5),(.5,-.5),(0,.5)} +% Use them as symbols: +\plotsymbols{MyTriang}{(0,0),(2,2)} +\arrowmid{MySolidTriang}\polyline{(1,1),(0,2)} +\end{verbatim} + +\emph{Note}: If a stored path has the same starting point as ending +point, but is \emph{not} closed then it will behave like \texttt{Circle} +(for example) when used in \cs{plotsymbol}: only its outline is drawn, +and its interior is erased when \opt{clearsymbols} is in effect. If a +closed path is stored, it behaves like \texttt{SolidCircle}: it is not +drawn, but rather filled. If a path is stored that satisfies neither, it +behaves like \texttt{Asterisk}, being simply drawn in all circumstances. + +The two forms \cs{mfobj} and \cs{mpobj} are absolutely equivalent; they +differ only in spelling. + +It should be noted that every \mfp{} figure is implicitly stored in the +object \gbc{curpath}. So you can use \cs{mfobj}\marg{curpath} and get +the path defined by the most recently completed figure macro (possibly +modified by prefixes). + +Getting back to coordinate transforms, if one changes the coordinate +system and then stores and draws a curve, say by +\begin{verbatim} +\coords + \rotate{45 deg} + \store{xx}{\rect{(0,0),(1,1)}} + \dashed\mfobj{xx} +\endcoords +\end{verbatim} +one will get a transformed picture, but the object \cs{mfobj}\marg{xx} +will contain the simple, unrotated rectangular path and drawing it later +(outside the \env{coords} environment) will prove that. This is because +the \texttt{coords} environment works at the drawing level, not at the +definition level. + +In oversimplified terms, \cs{dashed} invokes the transformation, but not +\cs{store}. More precisely, the rendering macros have the side effect of +adding ink to the page (or subtracting it). To know where to place this +ink, a calculation is performed that translates graph coordinates to +actual positions. The above transforms work by modify the parameters +used in that calculation. On the other hand, \cs{store} merely stores +the output of the immediately following prefix or figure macro. See the +beginning of section~\ref{modifier} for a discussion of input, output +and side effects of \mfp{} prefix and figure macros. + +The following transformation prefixes provide a means of actually +creating and storing a transformed path. In the terms just discussed, +their input is a path, their output is the transformed path, and they +have no side effects. + +\begin{cd}\pagelabel{shiftpath} +\cs{rotatepath}\marg{\meta{$p$},\meta{$\theta$}}$\ldots$\\ +\cs{shiftpath}\marg{\meta{v}}$\ldots$\\ +\cs{scalepath}\marg{\meta{$p$},\meta{s}}$\ldots$\\ +\cs{xscalepath}\marg{\meta{x},\meta{s}}$\ldots$\\ +\cs{yscalepath}\marg{\meta{y},\meta{s}}$\ldots$\\ +\cs{slantpath}\marg{\meta{y},\meta{s}}$\ldots$\\ +\cs{xslantpath}\marg{\meta{y},\meta{s}}$\ldots$\\ +\cs{yslantpath}\marg{\meta{x},\meta{s}}$\ldots$\\ +\cs{reflectpath}\marg{\meta{$p_1$},\meta{$p_2$}}$\ldots$\\ +\cs{xyswappath}$\ldots$\\ +\cs{transformpath}\marg{\meta{transformer}}$\ldots$% +\index{rotatepath@\cs{rotatepath}}% +\index{shiftpath@\cs{shiftpath}}% +\index{scalepath@\cs{scalepath}}% +\index{xscalepath@\cs{xscalepath}}% +\index{yscalepath@\cs{yscalepath}}% +\index{slantpath@\cs{slantpath}}% +\index{xslantpath@\cs{xslantpath}}% +\index{yslantpath@\cs{yslantpath}}% +\index{reflectpath@\cs{reflectpath}}% +\index{xyswappath@\cs{xyswappath}}% +\index{transformpath@\cs{transformpath}} +\end{cd} + +These are modifying macros that all return the result of applying an +affine transformation to the following path. They differ in the +transformation applied and the data needed in the mandatory argument. I +have found them extremely useful, and better than \env{coords} +environments when I need to draw a figure, together with several +slightly different versions of it. If \cs{store} is used just before one +of these prefixes, it stores the transformed path rather than the +original. + +\cs{rotatepath} rotates the following path by \meta{$\theta$} degrees +about point \meta{$p$}. + +\cs{shiftpath} shifts the following path by the vector \meta{v}. + +\cs{scalepath} scales (magnifies or shrinks) the following path by the +factor \meta{s}, in such a way that the point \meta{$p$} is kept fixed. +That is +\begin{verbatim} +\scalepath{(0,0),2}\rect{(0,0),(1,1)} +\end{verbatim} +is essentially the same as \cs{rect}\marg{(0,0),(2,2)}, while +\begin{verbatim} +\scalepath{(1,1),2}\rect{(0,0),(1,1)} +\end{verbatim} +is the same as \cs{rect}\marg{(-1,-1),(1,1)}. In both cases the +rectangle is doubled in size. In the first case the lower left corner +stays the same, while in the second case the the upper right corner +stays the same. + +\cs{xscalepath} is similar to \cs{scalepath}, but only the $x$-direction +is scaled, and all points with first coordinate equal to \meta{x} remain +fixed. \cs{yscalepath} is similar, except the $y$-direction is affected. + +\cs{slantpath} applies a slant transformation to the following path, +keeping points with second coordinate equal to \meta{y} fixed. That is, +a point $p$ on the path is moved right by an amount proportional to the +height of $p$ above the line $y={}$\meta{y}, with $s$ being the +proportionality factor. Points below that line move left. Vertical lines +in the path will acquire a slope of $1/s$, while horizontal lines stay +horizontal. + +\cs{xslantpath} is an alias for \cs{slantpath} + +\cs{yslantpath} is similar to \cs{xslantpath}, but exchanges the roles +of $x$ and $y$ coordinates. + +\cs{reflectpath} returns the mirror image of the following path, where +the line determined by the points \meta{$p_1$} and \meta{$p_2$} is the +mirror. + +\cs{xyswappath} returns the path with the roles of $x$ and $y$ +exchanged. This is similar in some respects to +\cs{reflectpath}\marg{(0,0),(1,1)}, and produces the same result if the +$x$ and $y$ scales of the picture are the same. However, +\cs{reflectpath} compensates for such different scales (so the path +shape remains the same), while \cs{xyswappath} does not. However, after +a swap, verticals become horizontal and horizontals become vertical. +(It is impossible, when the scales are different, for an affine transform +to both preserve shape and exchange horizontal and vertical lines.) + +This compensation for different scales is also done for \cs{rotatepath}, +so the resulting path always has the same shape after the rotation as +before. None of the other path transformation prefixes compensate for +different scales, and none of the coordinate system transformations of +the previous subsection do it. + +For \MF{} or \MP{} power users, \cs{transformpath} can take any +`transformer' and transform the following path with it. Here, a +\emph{transformer} is the same as in the previous section. Examples are +\mfc{scaled}, \mfc{shifted(1,1)}, and \mfc{rotatedabout(0,1)}. Note that +using this last transformer with \cs{transformpath} is almost like +\cs{rotatepath}\marg{(0,1)}, but it does not compensate for different +scales. + +All these prefixes change only the path that follows, not any rendering +of it that follows. For example: +\begin{verbatim} +\gfill\rotatepath{(0,0),90}\dashed\rect{(0,0),(1,1)} +\end{verbatim} +will not produce a rotated dashed rectangle. Rather the original +rectangle will be dashed, and the rotated rectangle will be filled. + +One complication is the handling of the default rendering. One expects +\verb$\rect{(0,0),(1,1)}$ to draw a rectangle, and +\verb$\rotatepath{(0,0),45}\rect{(0,0),(1,1)}$ to draw a rotated +rectangle (but not the original). That is, a transformation + figure is +treated as if it were a single figure. But what would one expect in the +following? +\begin{verbatim} +\rotatepath{(0,0),45}\dashed\rect{(0,0),(1,1)} +\end{verbatim} +What one will get is the original dashed and the rotated one with the +default rendering (typically drawn with solid lines). That is, these +prefixes cannot see the renderings that occur later in the sequence. +They add the default rendering as if those didn't exist. If something +other than this is desired, one can either rearrange the prefixes or add +a \phantomsection\label{norenderexample}\cs{norender} in appropriate +places. For example, to add a shifted arrowhead without drawing the +shifted path: +\begin{verbatim} +\arrow\norender\shiftpath{(0,1)}\arrow\draw\lines{(0,0),(8,8)} +\end{verbatim} + +\section{Parameters.}\label{parameters} + +There are many parameters in \mfp{} which the user can modify to +obtain different effects, such as different arrowhead size or shape. +Most of these parameters have been described already in the context of +macros they modify, but they are all described together here. + +Many of the parameters are stored by \TeX{} as dimensions, and so are +available even if there is no \MF{} file open; changes to them are not +subject to the usual \TeX{} rules of scope however: they are local +only to \env{mfpic} environments if set inside one, otherwise +they are global. This is for consistency: other parameters are stored by +\MF{} (so the macros to change them will have no effect unless a \MF{} +file is open) and the changes are subject to \MF{}'s rules of scope---to +the \mfp{} user, this means that changes inside the \cs{mfpic} $\ldots$ +\cs{endmfpic} environment are local to that environment, but other +\TeX{} groupings have no effect on scope. Some commands (notably those +that set the axismargins and \cs{tlabel} parameters) change both \TeX{} +parameters and \MF{} parameters, and it is important to keep them +consistent. + +There are a few parameters that do obey \TeX{} grouping, but only inside +\env{mfpic} environments. These are noted where the parameter is +described. + +All parameters are initialized when \prog{mfpic} is loaded. We give the +initial value or state in each of these descriptions. + +\begin{cd}\pagelabel{mfpicunit} +\cs{mfpicunit}% +\index{mfpicunit@\cs{mfpicunit}} +\end{cd} + +This dimension stores the basic unit length for \mfp{} pictures. The $x$ +and $y$ scales in the \cs{mfpic} macro are multiples of this unit. The +initial value is \dim{1pt}. It is global outside an \env{mfpic} +environment. Changes made to it inside an \env{mfpic} environment have +no effect and are lost at the end of the environment. + +\begin{cd}\pagelabel{pointsize} +\cs{pointsize}% +\index{pointsize@\cs{pointsize}} +\end{cd} + +This dimension stores the diameter of the circle drawn by the +\cs{point} macro and the diameter of the symbols drawn by \cs{plot}, +\cs{plotsymbol} and \cs{plotnodes}. The initial value is \dim{2pt}. + +\begin{cd}\pagelabel{pointfilltrue} +\cs{pointfilltrue}, \cs{pointfillfalse}% +\index{pointfilltrue@\cs{pointfilltrue}}% +\index{pointfillfalse@\cs{pointfillfalse}} +\end{cd} + +This \TeX{} boolean switch determines whether the circle drawn by +\cs{point} will be filled or open (outline drawn, inside erased). +The initial state is \texttt{true}: filled. This value is local to any \TeX{} +group inside an \env{mfpic} environment. Outside such it is global. + +\begin{cd}\pagelabel{drawpen} +\cs{pen}\marg{\meta{size}}\\ +\cs{drawpen}\marg{\meta{size}}\\ +\cs{penwd}\marg{\meta{size}}% +\index{pen@\cs{pen}}% +\index{drawpen@\cs{drawpen}}% +\index{penwd@\cs{penwd}} +\end{cd} + +These commands establishes the width of the normal drawing pen (that is, +the thickness of lines, whether solid or dashed). The initial value is +\dim{0.5bp}. This width is stored by \MF{}. This has no effect on the +size of dots for \cs{dotted}, \cs{shade}, \cs{grid}, etc. It also has no +effect on the lines drawn for hatching. There exist three aliases for +this command, the first two to maintain backward compatibility, the last +one for consistency with other dimension changing commands. Publishers +generally recommended authors to use at least a width of one-half point +for drawings submitted for publication. + +\begin{cd}\pagelabel{shadewd} +\cs{shadewd}\marg{\meta{diam}}% +\index{shadewd@\cs{shadewd}} +\end{cd} + +This command sets the diameter of the dots used in the shading macro. +The drawing and hatching pens are unaffected by this. The initial value +is \dim{0.5bp}, and the value is stored by \MF{}. + +\begin{cd}\pagelabel{hatchwd} +\cs{hatchwd}\marg{\meta{size}}% +\index{hatchwd@\cs{hatchwd}} +\end{cd} + +This sets the line thickness used in the hatching macros. The drawing +pen and shading dots are unaffected by this. The initial value is +\dim{0.5bp}, and the value is stored by \MF{}. + +\begin{cd}\pagelabel{polkadotwd} +\cs{polkadotwd}\marg{\meta{diam}}% +\index{polkadotwd@\cs{polkadotwd}} +\end{cd} + +This sets the diameter of the dots used in the \cs{polkadot} macro. The +initial value is \dim{5bp}, and the value is stored by \MF{}. + +\begin{cd}\pagelabel{headlen} +\cs{headlen}% +\index{headlen@\cs{headlen}} +\end{cd} + +This dimension stores the length of the arrowhead drawn by the +\cs{arrow} macro. The initial value is \dim{3pt}. + +\begin{cd}\pagelabel{axisheadlen} +\cs{axisheadlen}% +\index{axisheadlen@\cs{axisheadlen}} +\end{cd} + +This dimension stores the length of the arrowhead drawn by the +\cs{axes}, \cs{xaxis} and \cs{yaxis} macros, and by the macros \cs{axis} +and \cs{doaxes} when applied to the parameters \texttt{x} and +\texttt{y}. The initial value is \dim{5pt}. + +\begin{cd}\pagelabel{sideheadlen} +\cs{sideheadlen}% +\index{sideheadlen@\cs{sideheadlen}} +\end{cd} + +This dimension stores the length of the arrowhead drawn by the \cs{axis} +and \cs{doaxes} macros when applied to \texttt{l}, \texttt{b}, +\texttt{r} or \texttt{t}. The initial value is \dim{0pt} (that is, the +default is not to put arrowheads on border axes). + +\begin{cd}\pagelabel{headshape} +\cs{headshape}\marg{\meta{ratio}}\marg{\meta{tension}}\marg{\meta{filled}}% +\index{headshape@\cs{headshape}} +\end{cd} + +This establishes the shape of the \gbc{Arrowhead} drawn by the +\cs{arrow...} and \cs{axes} macros. It also establishes the shape of +\gbc{Leftharpoon} and \gbc{Rightharpoon}. The value of \meta{ratio} is +the ratio of the width of the arrowhead to its length; \meta{tension} is +the tension of the B\'ezier curves; and \meta{filled} is a \MF{} boolean +value indicating whether the arrowheads are to be filled (if \mfc{true}) +or open. The initial values are $1$, $1$, and \mfc{false}, respectively. +Setting \meta{tension} to the literal keyword `\mfc{infinity}' will make +the sides of the arrowheads straight lines. The harpoon heads are +arranged to be exactly half of the full arrowhead. The \meta{ratio}, +\meta{tension} and \meta{filled} values are stored by \MF{}. + +After \cs{headshape} is used, the symbols \gbc{Arrowhead}, +\gbc{Leftharpoon}, and \gbc{Rightharpoon} take on the new shape if used +in one of the \cs{plot...} commands. + +\begin{cd}\pagelabel{dashlen} +\cs{dashlen}, \cs{dashspace}% +\index{dashlen@\cs{dashlen}} +\end{cd} + +These dimensions store, respectively, the length of dashes and the +length of spaces between dashes, for lines drawn by the \cs{dashed} +macro. The \cs{dashed} macro may adjust the dashes and the spaces +between by as much as $1/n$ of their value, where $n$ is the number of +spaces appearing in the curve, in order not to have partial dashes at +the ends. The initial values are both \dim{4pt}. The dashes will +actually be longer (and the spaces shorter) by the thickness of the pen +used when they are drawn. + +\begin{cd}\pagelabel{dashlineset} +\cs{dashlineset}, \cs{dotlineset}% +\index{dashlineset@\cs{dashlineset}}% +\index{dotlineset@\cs{dotlineset}} +\end{cd} + +These macros provide shorthands for certain settings of the \cs{dashlen} +and \cs{dashspace} dimensions. The macro \cs{dashlineset} sets both +values to \dim{4pt}, while \cs{dotlineset} sets \cs{dashlen} to +\dim{1pt} and \cs{dashspace} to \dim{2pt}. They are kept mainly for +backward compatibility. + +\begin{cd}\pagelabel{hashlen} +\cs{hashlen}% +\index{hashlen@\cs{hashlen}} +\end{cd} + +This dimension stores the length of the axis hash marks drawn by the +\cs{xmarks} and \cs{ymarks} macros. The initial value is \dim{4pt}. + +\begin{cd}\pagelabel{shadespace} +\cs{shadespace}% +\index{shadespace@\cs{shadespace}} +\end{cd} + +This dimension establishes the spacing between dots drawn by the +\cs{shade} macro. The initial value is \dim{1pt}. + +\begin{cd}\pagelabel{darkershade} +\cs{darkershade}, \cs{lightershade}% +\index{darkershade@\cs{darkershade}}% +\index{lightershade@\cs{lightershade}} +\end{cd} + +These macros both multiply the \cs{shadespace} dimension by constant +factors, $5/6=.833333$ and $6/5=1.2$ respectively, to provide convenient +standard settings for several levels of shading. Under \MF{} it is +possible that using one of these macros can have no visible effect. See +the discussion of the \cs{shade} macro in subsection~\ref{filling}. + +\begin{cd}\pagelabel{polkadotspace} +\cs{polkadotspace}% +\index{polkadotspace@\cs{polkadotspace}} +\end{cd} + +This dimension establishes the spacing between the centers of the dots +used for the macro \cs{polkadot}. The initial value is \dim{10pt}. + +\begin{cd}\pagelabel{dotsize} +\cs{dotsize}, \cs{dotspace}% +\index{dotsize@\cs{dotsize}}\index{dotspace@\cs{dotspace}}% +\end{cd} + +These \TeX{} dimensions establishes the size and spacing between the +centers of the dots used in the \cs{dotted} macro. The initial values +are \dim{0.5pt} and \dim{3pt}. + +\begin{cd}\pagelabel{griddotsize} +\cs{griddotsize}% +\index{griddotsize@\cs{griddotsize}}% +\end{cd} + +This dimension is used as the default for the sizes of dots in the +\cs{grid} and \cs{plrgridpoints} commands. The initial value is +\dim{0.5pt} + +\begin{cd}\pagelabel{symbolspace} +\cs{symbolspace}% +\index{symbolspace@\cs{symbolspace}} +\end{cd} + +Similar to \cs{dotspace}, this \TeX{} dimension establishes the space +between the centers of symbols placed by the macro +\cs{plot}\marg{\meta{symbol}}$\ldots\,$. Its initial value is \dim{5pt}. + +\begin{cd}\pagelabel{hatchspace} +\cs{hatchspace}% +\index{hatchspace@\cs{hatchspace}} +\end{cd} + +This dimension establishes the spacing between lines drawn by the +\cs{hatch} macro. The initial value is \dim{3pt}. + +\begin{cd} +\cs{tlpointsep}\marg{\meta{separation}}\\ +\cs{tlpathsep}\marg{\meta{separation}}\\ +\cs{tlabelsep}\marg{\meta{separation}}% +\index{tlpointsep@\cs{tlpointsep}}% +\index{tlpathsep@\cs{tlpathsep}}% +\index{tlabelsep@\cs{tlabelsep}} +\end{cd} + +The first macro establishes the separation between a label and its +nominal position. It affects text written with any of the commands +\cs{tlabel}, \cs{tlabels}, \cs{axislabels} or \cs{plottext}. The second +sets the separation between the text and the curve defined by the +commands \cs{tlabelrect}, \cs{tlabeloval} or \cs{tlabelellipse}. The +third sets both of these separations to the same value. It is for +backward compatibility: in the past there was only one dimension used +for both purposes. The initial value of each is \dim{0pt}. The values +are stored by both \TeX{} and \MF{}. + +\begin{cd} +\cs{tlabeloffset}\marg{\meta{hlen}}\marg{\meta{vlen}}% +\index{tlabeloffset@\cs{tlabeloffset}} +\end{cd} + +This macro establishes a uniform offset that applies to all labels. It +affects text written with any of the commands \cs{tlabel}, \cs{tlabels}, +\cs{axislabels} or \cs{plottext}. The initial state is to have both +horizontal and vertical offsets of \dim{0pt}. The values are stored by +both \TeX{} and \MF{}. + +\begin{cd}\pagelabel{mfpdataperline} +\cs{mfpdataperline}% +\index{mfpdataperline@\cs{mfpdataperline}} +\end{cd} + +When \mfp{} is reading from data files and writing to the output file, +this macro stores the maximum number of data points that will be written +on a single line in the output file. Its initial definition is +\cs{def}\cs{mfpdataperline}\marg{5}. Any such definition (or +redefinition) obeys \emph{all} \TeX{} groupings. + +\begin{cd}\pagelabel{mfpicheight} +\cs{mfpicheight}, \cs{mfpicwidth}% +\index{mfpicheight@\cs{mfpicheight}}% +\index{mfpicwidth@\cs{mfpicwidth}} +\end{cd} + +These dimensions store the height and width of the figure created by the +most recently completed \env{mfpic} environment. This might perhaps be +of interest to hackers or to aid in precise positioning of the graphics. +They are meant to be read-only: the \cs{endmfpic} command globally sets +them equal to the height and width of the picture, but \mfp{} does not +otherwise make any use of them. As they are not to be changed, grouping +is irrelevent, but when \mfp{} sets them, it does so globally. These are +set even if the picture is saved with \cs{savepic}. If they are needed +for the corresponding \cs{usepic}, and that occurs after another +\env{mfpic} environment, they should be copied to other length commands +right after the \env{mfpic} environment that set them. + +\begin{cd}\pagelabel{mfpiccaptionskip} +\cs{mfpiccaptionskip}% +\index{mfpiccaptionskip@\cs{mfpiccaptionskip}} +\end{cd} + +This skip register (`rubber length' in \LaTeX) stores the space between +a picture and the caption produced with \cs{tcaption}. It is local to +all \TeX{} groups. If changed inside an \env{mfpic} environment it will +affect only the \cs{tcaption} command in that picture. It's initial +setting is \cs{medskipamount}, producing the same space as a +\cs{medskip}. + + +\section{For Advanced Users.}\label{advanced} + +\subsection{Splines}\label{splines} + +\begin{cd}\pagelabel{qspline} +\cs{qspline}\marg{\meta{list}}\\ +\cs{closedqspline}\marg{\meta{list}}\\ +\cs{cspline}\marg{\meta{list}}\\ +\cs{closedcspline}\marg{\meta{list}}% +\index{qspline@\cs{qspline}}% +\index{closedqspline@\cs{closedqspline}}% +\index{cspline@\cs{cspline}}% +\index{closedcspline@\cs{closedcspline}}% +\end{cd} + +These figure macros use alternative ways of defining curves. In each case, +\meta{list} is a comma separated list of ordered pairs. These represent +not the points the curve passes through, but the \emph{control points}. +The first two produce quadratic B-splines and the last two produce cubic +B-splines. If you don't know what B-splines are, or don't know what +control points are, it is recommended you not use these commands. + +For \cs{qspline}, the curve will pass through the midpoints of the line +segments joining the points in the list, tangent to that line segment. + +For the \cs{cspline}, the list also defines line segments. Divide these +into equal thirds at two points on each segment. Connect these +\emph{division points only} to obtain line segments. Each \emph{odd +numbered} segment is the middle third of one of the original line +segments. The \cs{cspline} curve passes through the midpoint of each +\emph{even numbered} line segment, tangent to it. + +\begin{cd}\pagelabel{computedspline} +\cs{computedspline}\marg{\meta{list}}\\ +\cs{closedcomputedspline}\marg{\meta{list}}% +\index{computedspline@\cs{computedspline}}% +\index{closedcomputedspline@\cs{closedcomputedspline}}% +\end{cd} + +These figure macros both produce cubic splines. For these you \emph{do} +provide the list of points the curves are to pass through. They become +the nodes, and then the control points are computed from them. The nodes +do not uniquely determine the control points so extra equations are +required. For the first version, the extra equations give the path zero +curvature at the endpoints (a \emph{relaxed} spline). For the closed +version, the extra equations are those that close the curve smoothly. +The portions of the spline that connect one node to the next are +parametrized cubic B/'eziers, they are computed so that the first and +second derivatives (with respect to the parameter) of adjacent curves +match at the common node. + +\begin{cd}\pagelabel{fcnspline} +\cs{fcnspline}\marg{\meta{list}}\\ +\cs{periodicfcnspline}\marg{\meta{list}}% +\index{fcnspline@\cs{fcnspline}}% +\index{periodicfcnspline@\cs{periodicfcnspline}}% +\end{cd} + +These figure macros use cubic spline equations (as in +\cs{computedspline} above) to produce a smooth graph of a function based +on a list of points with increasing $x$-values. See \cs{fcncurve} in +section~\ref{curves} for another way to do this. As in the computed +splines, above, the spline equations at the nodes do not provide +sufficient information to compute all control points. In the basic +version, \cs{fcnspline}, extra equations produce a graph with zero +curvature at the endpoints (a relaxed spline), while the periodic +version uses equations that make the first and second derivatives at the +last point match those at the first point. + +\begin{cd}\pagelabel{cbclosed} +\cs{cbclosed}$\ldots$\\ +\cs{qbclosed}$\ldots$% +\index{cbclosed@\cs{cbclosed}}% +\index{qbclosed@\cs{qbclosed}} +\end{cd} + +These are modifying macros that close the following path. The first +closes with a cubic B-spline, the second with a quadratic B-spline. They +will close any given curve, but the command \cs{cbclosed} is meant to +close a cubic B-spline (see above). That is, \cs{cbclosed}\cs{cspline} +should produce the same result as \cs{closedcspline} with the same +argument. The corresponding statements are true of \cs{qbclosed}: it is +meant to close a quadratic B-spline and \cs{qbclosed}\cs{qspline} should +produce the same result as \cs{closedqspline} with the same argument. + +\subsection{B\'eziers} + +The power user, having noticed that \cs{curve} and \cs{cyclic} insert +some direction modifiers into the path created, may have decided that +there is no \mfp{} command to create a simple \MF{} default style path, +for example \mfc{(1,1)..(0,1)..(0,0)..cycle}. If so, he or she has forgotten +about \cs{mfobj}: the command +\begin{verbatim} +\mfobj{(1,1)..(0,1)..(0,0)..cycle} +\end{verbatim} +will produce, in the \file{.mf} file, exactly this path, but surround it +with the \TeX{} wrapping needed to make \mfp{}'s prefix macro system work. +However, the syntax of more complicated paths can be extremely lengthy, +so we offer this interface: + +\begin{cd}\pagelabel{mfbezier} + \cs{mfbezier}\oarg{\meta{tens}}\marg{\meta{list}}\\ + \cs{closedmfbezier}\oarg{\meta{tens}}\marg{\meta{list}}% +\index{mfbezier@\cs{mfbezier}}% +\index{closedmfbezier@\cs{closedmfbezier}} +\end{cd} + +These figure macros uses the \MF{} path join operator `\mfc{..tension +\meta{tens}..}' to connect the points in the list. If the tension option +\oarg{\meta{tens}} is omitted, the value set by \cs{settension} +(initially 1) is used. One can get a cyclic path by prepending +\cs{bclosed} (with matching tension option), but it will not produce the +same result as \cs{closedmfbezier}. These are cubic B\'ezier's (but you +know that if you are a power user). Quadratic B\'eziers (as in +\LaTeX{}'s picture environment) can be obtained with the following: + +\begin{cd}\pagelabel{qbeziers} + \cs{qbeziers}\marg{\meta{list}}\\ + \cs{closedqbeziers}\marg{\meta{list}}% +\index{qbeziers@\cs{qbeziers}}% +\index{closedqbeziers@\cs{closedqbeziers}} +\end{cd} + +These figure macros produce \emph{quadratic} B\'ezier curves, the +equivalent of a sequence of \LaTeX{} \cs{qbezier} commands. Note the +plural forms, to distinguish the first from the \LaTeX{} command, and to +indicate that they can draw a \emph{series} of quadratic B\'eziers. + +In the \meta{list}, the first, third, fifth, etc., are the points to +connect, while the second, fourth, etc., are the control points. The +open version requires an ending point, and so needs an odd number of +points in the list. The closed version assumes the first point is the +ending, and so requires an even number in the list. If the number of +ponts is wrong, no error is produced: the last point is simply repeated +to get the required number. + +The curve will not automatically be smooth; that depends on the choice +of the control points. + +\begin{cd}\pagelabel{cbeziers} + \cs{cbeziers}\marg{\meta{list}}\\ + \cs{closedcbeziers}\marg{\meta{list}}% +\index{cbeziers@\cs{cbeziers}}% +\index{closedcbeziers@\cs{closedcbeziers}} +\end{cd} + +These figure macros produce a series of \emph{cubic} B\'ezier curves. In +the \meta{list}, the first, fourth, seventh, etc., are the points to +connect, while the second and third, fifth and sixth, etc., are pairs of +control points. The closed version uses the starting point as the ending +point, and so needs a number of points divisible by $3$ ($n=3k$). The +open version requires an explicitly given ending node (so $n=3k+1$). +If the number of ponts is wrong, no error is produced: the last point +or last two points are simply repeated to get the required number. + +The curves will not automatically be smooth; that depends on the choice +of the control points. Cubic B\'eziers are how curves are represented in +PostScript files, and how a number of vector drawing programs represent +curves. + +\subsection{Raw \MF{} code}\label{mfcode} + +\begin{cd}\pagelabel{mfsrc} +\cs{mfsrc}\marg{\meta{metafont code}}\\ +\cs{mfcmd}\marg{\meta{metafont code}}\\ +\cs{mflist}\marg{\meta{metafont code}}% +\index{mfsrc@\cs{mfsrc}}% +\index{mfcmd@\cs{mfcmd}}% +\index{mflist@\cs{mflist}}% +\end{cd} + +These all write the \meta{metafont code} directly to the \MF{} file, +using a \TeX{} \cs{write} command. Line breaks within \meta{metafont +code} are preserved.% + \footnote{Under most circumstances, but not if the command (plus its + argument) is part of the argument of another macro.} % +Almost all the \mfp{} drawing macros invoke one of these. Because of the +way \TeX{} reads and processes macro arguments, not all drawing macros +preserve line breaks (nor do they all need to). However, the ones that +operate on long lists of pair or numeric data (for example, \cs{point}, +\cs{curve}, etc.), do preserve line breaks in that data. The difference +in these is minor: \cs{mfsrc} writes its argument without change, +\cs{mfcmd} appends a semicolon (`\mfc{;}') to the code, while +\cs{mflist} surrounds its argument with parentheses and then appends a +semicolon. + +Using these can have some rather bizarre consequences, though, so it is +not recommended to the unwary. It is, however, currently the only way to +make use of \MF{}'s equation solving ability. Here's an oversimplified +example: +\begin{verbatim} +\mfpic[20]{-0.5}{1.5}{0}{1.5} +\mfsrc{z1=(0,0); + z2-z3=(1,2); + z2+2z3=(1,-1);} % z2=(1,1), z3=(0,-1) +\arc[t]{z1,z2,z3} +\endmfpic +\end{verbatim} + +Check out the sample \file{forfun.tex} for a more extensive example. It +should produce the word `\textsf{mfpic}' in blue, outlined in green in a +box with yellow background. + +\subsection{Creating \MF{} variables}\label{variables} + +\begin{cd}\pagelabel{setmfvariable} +\cs{setmfvariable}\marg{\meta{type}}\marg{\meta{name}}\marg{\meta{value}}\\ +\cs{setmpvariable}\marg{\meta{type}}\marg{\meta{name}}\marg{\meta{value}}\\ +\cs{globalsetmfvariable}\marg{\meta{type}}\marg{\meta{name}}\marg{\meta{value}}\\ +\cs{globalsetmpvariable}\marg{\meta{type}}\marg{\meta{name}}\marg{\meta{value}}\\ +\cs{setmfnumeric}\marg{\meta{name}}\marg{\meta{value}}\\ +\cs{setmfpair} \marg{\meta{name}}\marg{\meta{value}}\\ +\cs{setmfboolean}\marg{\meta{name}}\marg{\meta{value}}\\ +\cs{setmfcolor} \marg{\meta{name}}\marg{\meta{value}}% +\index{setmfvariable@\cs{setmfvariable}}% +\index{setmpvariable@\cs{setmpvariable}}% +\index{globalsetmfvariable@\cs{globalsetmfvariable}}% +\index{globalsetmpvariable@\cs{globalsetmpvariable}}% +\index{setmfnumeric@\cs{setmfnumeric}}% +\index{setmfpair@\cs{setmfpair}}% +\index{setmfboolean@\cs{setmfboolean}}% +\index{setmfcolor@\cs{setmfcolor}}% +\end{cd} + +These formerly internal \mfp{} macros can be use to define symbolic +names for any \MF{} or \MP{} variable type. The last four are +abbreviations for the first used with an appropriate value for +\meta{type}. For example, +\cs{setmfvariable}\marg{pair}\marg{X}\marg{(2,0)} can be abbreviated +\cs{setmfpair}\marg{X}\marg{(2,0)}. Note that these overwrite any +variable with the specified \meta{name}. For certain internal names, +\MF{} will issue an error, but usually the variable is silently +redefined. + +The commands \cs{setmpvariable} and \cs{globalsetmpvariable} (note the +\texttt{mp} instead of \texttt{mf}) are just alternative spellings . You +can use either spelling with either the \opt{metafont} or \opt{metapost} +option. + +The \meta{value} must be a constant of the appropriate type or a \MF{} +expression returning the appropriate type. It can also be (or include) +other variables previously defined. The \cs{setmfcolor} command has been +enhanced so that in recent \MP{} the \meta{value} can be any of the +three types of colors \MP{} allows: \kw{numeric} (for grayscale color), +\kw{rgbcolor} or \kw{cmykcolor}. The data type of \meta{value} will be +examined, and the variable \meta{name} will be declared to be a variable +of the appropriate type. The same is true of +\cs{setmfvariable}\marg{color}. + +As an example of their use, since dimensions are numeric data types in +\MF{}, the command +\begin{verbatim} +\setmfnumeric{my_spc}{5pt} +\setmfnumeric{my_dia}{.8pt} +\end{verbatim} +would set the \MF{} variables \verb$my_spc$ and \verb$my_dia$ to the +values \texttt{5pt} and \texttt{.8pt}, respectively. After that, these +variables can be used in any \emph{drawing} command where a dimension is +required: +\begin{verbatim} +\plot[my_dia,my_spc]{Triangle}\rect{(0,0),(1,1)} +\end{verbatim} +will plot the rectangle with small triangles of diameter \dim{.8pt}, +spaced \dim{5pt} apart. + +The knowledgeable user may realize that \mfc{path} and \gbc{picture} are +\MF{} data types, and may want use them in \cs{setmfvariable}. It is +also true that at some level, \mfp{} figure macros produce a path and +\cs{mfpimage} produces a picture. However, \mfp{} commands cannot be +used in the value portion of \cs{setmfvariable}. The \TeX{} code that +most \mfp{} commands produce would be meaningless to \MF{}. You can +store the path produced by figure macros with \cs{store}, and store +pictures in variables with \cs{mfpimage} or even \cs{tile}. + +With the obvious exception of the \cs{globalsetmfvariable} command, these +commands define the variable locally. That is, the variable will revert +to any previous definition (or become undefined) at the end of the +\env{mfpic} environment it is defined in. It is in fact local to any +\MF{} group. In \mfp{}, only \cs{connect} {\dots} \cs{endconnect}, +\cs{mfpimage} {\dots} \cs{endmfpimage}, and \cs{mfpic} {\dots} +\cs{endmfpic} create \MF{} groups in the graph file. + +A warning about variable names. \CMF{} and \MP{} allow multi-part +variable names like `\mfc{arrowhead length}' or `\mfc{X.r}' The part +after the first space or `.' is called a \mfc{suffix}. In \MF{}, +variable settings are global unless explicitly made local. The code of +the \cs{set...} commands does make the variable setting local. However, +\MF{} syntax forbids this localization when a variable name has a +suffix. Moreover, if you localize a variable, \MF{} will localize all +variables with that name plus any suffix. Even more, localizing a +variable renders all variables with the same name plus suffix locally +undefined. The command \cs{globalsetmfvariable} simply omits the +localization part, so suffixes are permitted, but it cannot `globalize' +something that has previously been localized within the same group. + +For example, suppose you use the example code in subsection~\ref{arrows} +and define a custom arrowhead path \gbc{myAH} and the corresponding +clearing path \gbc{myAH.clear}. Suppose now you try to make this head +the default for the \cs{arrow} command by doing the following. +\begin{verbatim} +\setmfvariable{path}{Arrowhead}{myAH} +\end{verbatim} +Then this assignments is local and makes \gbc{Arrowhead.clear} undefined +(locally). You cannot use \cs{setmfvariable} to define +\gbc{Arrowhead.clear}; that will produce an error from \MF{}. You need +to do +\begin{verbatim} +\setmfvariable{path}{Arrowhead}{myAH} +\globalsetmfvariable{path}{Arrowhead.clear}{myAH.clear} +\end{verbatim} +and \emph{both} assignments will be local. To make both assignments +global, use the global version in both. + + +\begin{cd}\pagelabel{patharr} +\cs{patharr}\marg{\meta{name}}$\ldots$\cs{endpatharr}% +\index{patharr@\cs{patharr}}% +\index{endpatharr@\cs{endpatharr}} +\end{cd} + +This pair of macros, acting as an environment, accumulate all enclosing +paths, in order, into a path array named \meta{name}. A path array is a +collection of paths with a common base name indexed by integers from 1 +to the number of paths. Any path in the array can be accessed by means +of \cs{mfobj}. For example, after +\begin{verbatim} +\patharr{pa} + \rect{(0,0),(1,1)} \circle{(.5,.5), .5} +\endpatharr +\end{verbatim} +then \cs{mfobj}\marg{pa[1]} refers to the rectangle and +\cs{mfobj}\marg{pa[2]} refers to the circle. In case explicit numbers +are used, \MF{} allows \gbc{pa1} as an abbreviation for \gbc{pa[1]}. +However, if a numeric variable or some expression is used (e.g., +\gbc{pa[n+1]}) the square brackets are required. + +This command can only be used in an \env{mfpic} environment. For this +reason, the definitions it makes are global. + +\emph{Note}: In \LaTeX{}, this pair of macros can be used in the form of a +\LaTeX{}-style environment called \env{patharr}---as in +\cs{begin}\marg{patharr}$\ldots$\cs{end}\marg{patharr}. + +\begin{cd}\pagelabel{setarray} +\cs{setarray}\marg{\meta{type}}\marg{\meta{var}}\marg{\meta{list}}\\ +\cs{globalsetarray}\marg{\meta{type}}\marg{\meta{var}}\marg{\meta{list}}\\ +\cs{pairarray}\marg{\meta{var}}\marg{\meta{list-of-points}}\\ +\cs{numericarray}\marg{\meta{var}}\marg{\meta{list-of-numbers}}\\ +\cs{colorarray}\marg{\meta{var}}\marg{\meta{list-of-colors}}\\ +\cs{rgbcolorarray}\marg{\meta{var}}\marg{\meta{list-of-rgbcolors}}\\ +\cs{cmykcolorarray}\marg{\meta{var}}\marg{\meta{list-of-cmykcolors}}% +\index{setarray@\cs{setarray}}% +\index{globalsetarray@\cs{globalsetarray}}% +\index{pairarray@\cs{pairarray}}% +\index{numericarray@\cs{numericarray}}% +\index{colorarray@\cs{colorarray}}% +\index{rgbcolorarray@\cs{rgbcolorarray}}% +\index{cmykcolorarray@\cs{cmykcolorarray}} +\end{cd} + +These enable the simultaneous definition of variables. +For example, after +\begin{verbatim} +\pairarray{X}{(0,1),(1,1),(0,0),(1,0)} +\end{verbatim} +the variables \mfc{X1}, \mfc{X2}, \mfc{X3}, and \mfc{X4} are equal to +the given points in that order. And then +\begin{verbatim} +\polyline{X1,X2,X3,X4} +\end{verbatim} +will draw the lines connecting these four points. The index may +optionally be put in square brackets and may be separated from the name +by any number of spaces. That is, \verb$\polyline{X[1],X[2]}$ +and \verb$\polyline{X 1,X 2}$ are the same as \verb$\polyline{X1,X2}$ +to \MF{}. If a numeric \emph{expression} is used instead of an explicit +number, square brackets \emph{must} surround it: \gbc{X[1+1]}, +\gbc{X[2]}, \gbc{X2} and \gbc{X 2} are all the same. For all these array +commands, the variable \gbc{X} by itself (not followed by any digit or +brackets) becomes a numeric variable equal to the number of elements in +the array. Except for \cs{globalsetarray}, the arrays are defined +locally if these commands occur in an \env{mfpic} environment, global +otherwise. + +Array variables may be used only where the values are processed only by +\MF{} or \MP{}, they are unknown to \TeX{}. In particular, they cannot be +used in commands that position text unless \opt{mplabels} is in effect. +Variables may be used in the \meta{list} parameters of commands, +but they must have been previously defined or otherwise known to \MF{}. + +Since arrays must all be variables of the same type, one cannot mix rgb +and cmyk colors. The \verb$\colorarray$ command requires rgb colors (for +compatibility with early \MP{}). + +Several commands in \mfp{} define arrays of objects that can be used in +other commands. The main ones are \cs{regpolygon}, \cs{piechart} and +\cs{barchart}. These arrays are always global (either because their +use is restricted to an \env{mfpic} environment or for backward +compatibility with the time when they were so restricted). + +Using \cs{regpolygon}{\meta{num}}\marg{X}\marg{...}\marg{...} causes a +pair array named \gbc{X} to be defined having \meta{num} elements (and +the additional pair \gbc{X0} for the center). This is in addition to +creating the actual figure. The variable \gbc{X} alone becomes a numeric +equated to \meta{num}. + +Using \cs{piechart} (or \cs{mfppiechart}) causes the following arrays to +become defined (or redefined): +\begin{itemize} + \item \gbc{piewedge}, a path array describing the wedges of the chart. + To access \gbc{piewedge[1]}, for example, one could use + \cs{mfobj}\marg{piewedge[1]}. This is almost exactly the + same as the \mfp{} command \cs{piewdge}\marg{1} without + optional arguments. + \item \gbc{pieangle}, a numeric array, gives the starting angles of + the wedges. + \item \gbc{piedirection}, a pair array, gives the unit vectors + pointing from the center of the piechart through middles of the + wedges. For example, if \cs{pieangle1} is 0 and \gbc{pieangle2} + is 90 degrees, then \gbc{piedirection1} is $(\cos 45,\sin 45)$, + the unit vector whose angle is $45$ degrees. +\end{itemize} + +Using \cs{barchart} (or \cs{mfpbarchart} or any of its aliases) causes +the following arrays to become defined (or redefined). The exact meaning +depends on whether bars are horizontal or vertical. The following +describes horizontal bars; exchange the roles of $x$ and $y$ if they are +vertical (also change `right' to `top', etc.): +\begin{itemize} + \item \gbc{barstart}, a numeric array, gives the position on the + $y$-axis of the leading edge of the bars. + \item \gbc{barbegin}, numeric, gives the $x$-coordinate of the + leftmost end of the bars. + \item \gbc{barend}, numeric, gives the $x$-coordinate of the rightmost + end of the bars. + \item \gbc{chartbar}, a path array, gives the actual bars. For + example, \gbc{chartbar2} is the rectangle with opposite corners + \gbc{(barbegin2,barstart2)} and \gbc{(barend2,barstart2+barwd)}, + where the numeric variable \gbc{barwd} is the thickness of the + bar (which is a height for horizontal bars). + \item \gbc{barlength}, the same as \gbc{barend}. This is for backward + compatibility; the name was chosen at a time when all the bars + had one side on an axis. +\end{itemize} + +\subsection{Miscelaneous pair expressions}\label{pairexpressions} + +A useful \MF{} operator that produces points is the intermediation +operator, whose syntax is +\begin{cd} +\texttt{(\meta{num})[\meta{$p_1$},\meta{$p_2$}]} +\end{cd} +That is, a number or numeric expression in parentheses followed by +literal brackets (this is \emph{not} an optional argument) containing two points +or pair expressions separated by a comma. It returns an intermediate point on +the line through \meta{$p_1$} and \meta{$p_2$}. The formula for the +returned value is $p_1 + \mbox{\meta{num}}(p_2 - p_1)$. The midpoint is +obtained with $\mbox{\meta{num}} = .5$. If the \meta{num} is a pure +number, the parentheses can be omitted, but they are required if it is +any other numeric expression. Values of \meta{num} larger than 1 or +less than zero produce points on the line that lie outside the segment +from $p_1$ to $p_2$. This operator can also be applied to numbers or (in +\MP{}) to colors (of the same type). So that \mfc{(2/3)[3,6] = 5} and +\mfc{.7[green,blue] = (0,.3,.7)}. See section~\ref{colors} for a +description of colors in \MP{} and \MF{}. + +\begin{cd} + \gbc{pathpoint(\meta{frac},\meta{name})} +\end{cd} +This is another useful \MF{} command. It requires a number, \meta{frac}, +and the \emph{name} of a previously defined \MF{} path variable. +(Defined, for example, using \cs{store}; see +subsection~\ref{transformation}). It returns the point on the path that +is approximately that fraction of the path's length from the start of +the path. For example to draw a line from $(0,0)$ to the midpoint of an +arc, do the following: +\begin{verbatim} +\store{myarc}\draw\arc{(1,0),(0,2),90} +\polyline{(0,0), pathpoint(.5,myarc)} +\end{verbatim} +\CMF{} has no general command for calculating the lengths of paths; +\CMP{} does, but it is quite slow. Thus neither program has an efficient +method for finding the described point, so \mfp{} uses \MF\slash\MP{} macros +that are faster, but less accurate than they could be. Still, the +results should (except in pathological cases) be accurate to within a +couple of percent of the length of the path. If they are not, adjust the +value of the fraction. These remarks about accuracy also hold for any +other command (such as \cs{partpath} in subsection~\ref{reversal}) that +take the fraction of a path length as a parameter. + +The \gbc{pathpoint} command is not a basic \MF{} command, but is defined +by the \prog{grafbase} macros that accompany \mfp{}. + +\MF{} pairs can conveniently be viewed as complex numbers. So +\file{grafbase} also contains some functions useful in complex analysis +(my research field). In what follows \gbc{a}, \gbc{z} and \gbc{w} denote +pair variables or constants, and each function interprets them as +complex numbers. Also \gbc{t} denotes an angle in radians. There are +both numeric and pair valued functions, the type of each is noted after +the description: + +\noindent +\begin{tabular}{@{}ll} +\gbc{Arg z} & The principle argument of $z$ in radians (numeric).\\ +\gbc{Log z} & The principle logarithm of $z$ (pair).\\ +\gbc{cis t} & $(\cos t, \sin t)$, same as \gbc{dir degrees(t)} (pair).\\ +\gbc{zexp w} & The complex exponential, $e^w$ (pair).\\ +\gbc{sgn z} & The signum, $\sgn (0,0) = (0,0)$ otherwise $\sgn z = z/|z|$ (pair).\\ +\gbc{conj z} & The complex conjugate, $\bar z$ (pair).\\ +\gbc{Moebius(a) z} & The M\"obius transformation $(z+a)/(1+\bar{a}z)$ (pair)\\ +\gbc{pshdist(z,w)} & The pseudohyperbolic distance between $z$ and + $w$: $|z-w| / |1-\bar{w}z|$ (numeric). +\end{tabular} + + +\subsection{Manipulating \MF{} picture variables} + +\begin{cd}\pagelabel{tile} +\cs{tile}\marg{\meta{tilename},\meta{unit},\meta{wd},\meta{ht},\meta{clip}}\\ + \ \meta{\mfp{} drawing commands}\\ +\cs{endtile}% +\index{tile@\cs{tile}}% +\index{endtile@\cs{endtile}} +\end{cd} + +In this environment, all drawing commands contribute to a \emph{tile}. A +\emph{tile} is a rectangular picture which may be used to fill the +interior of closed paths. Actually, a tile is a composite object. After +\cs{tile}\marg{Nick, ... } $\ldots$ \cs{endtile} a picture variable +\gbc{Nick.pic} is created as well as numeric variable \gbc{Nick.wd} and +\gbc{Nick.ht}. These are needed by the \cs{tess} command, below. + +The units of drawing are given by \meta{unit}, which should be an +explicit dimension (like \dim{1pt} or \dim{.2in}). The tile's horizontal +dimensions are $0$ to $\meta{wd}\cdot\meta{unit}$ and its vertical +dimensions $0$ to $\meta{ht}\cdot\meta{unit}$, so \meta{wd} and +\meta{ht} should be pure numbers. If \meta{clip} is \mfc{true} then the +drawing is clipped to be within the tile's boundary. + +By using this macro, you can design your own fill patterns (to use them, +see the \cs{tess} macro below), but see the warning about memory use by +the \cs{tess} command. The \meta{tilename} is globally defined by this +command. + +\begin{cd}\pagelabel{tess} +\cs{tess}\marg{\meta{tilename}}$\ldots$% +\index{tess@\cs{tess}} +\end{cd} + +This rendering macro tiles the interior of a closed path with a +tessellation comprised of copies of the \emph{tile} specified by +\meta{tilename}. The tile must have been previously created by +\cs{tile}\marg{\meta{tilename}, ... }. Tiling an open curve is +technically an error, but the \MF{} code responds by drawing the path +and not doing any tiling. The \MF{} code places shifted copies of the +tile picture in a rectangular grid sufficient to cover the region, then +clips it to the closed path before drawing it. + +Tiling large regions with complicated tiles can exceed the capacity of +some versions of \MP{}. There is less of a problem with \MF{}. This is not +because \MF{} has greater capacity, but because of the natural +difference between bitmaps and vector graphics. + +In \MP{}, the tiles are copied with whatever color they are given when +they are defined. They can be multicolored. + +Before version 0.8, \cs{tile} was the only way to create a picture +variable, and the only way to draw this picture was with the \cs{tess} +command. Now we have the following command to place multiple copies of +a picture: + +\begin{cd}\pagelabel{putmfpimage} + \cs{putmfpimage}\marg{\meta{name}}{\meta{list}}% +\index{putmfpimage@\cs{putmfpimage}} +\end{cd} + +This take the name of a picture variable and copies the picture at each +location in the \meta{list}, which should be a comma-separated list of +coordinate pairs in graph coordinates. The picture is copied so that its +\emph{reference point} is placed at each of the locations. The reference +point of a picture created with \cs{tile} is its lower left corner. + +\begin{cd}\pagelabel{mfpimage} + \cs{mfpimage}\oarg{\meta{refpt}}\marg{\meta{picname}}\\ + \ \meta{\mfp{} drawing commands}\\ + \cs{endmfpimage}% +\index{mfpimage@\cs{mfpimage}}% +\index{endmfpimage@\cs{endmfpimage}} +\end{cd} + +This is another way to create a picture variable. The drawing commands +within the \env{mfpimage} environment contribute not to the current +\mfp{} picture, but rather to the picture variable named in \meta{picname}. +Otherwise, they operate exactly as they would outside this environment, +using the same coordinate system and the same default values of all +parameters, etc. (unlike the \env{tile} environment, which defines its +own coordinate system). The picture is created with its reference point +at the point \meta{refpt} given in the optional argument. The default is +\texttt{(0,0)}. For example: +\begin{verbatim} +\mfpimage[(1,1)]{Jan} + \fill\rect{(0,0),(1,1)} + \fill\rect{(1,1),(2,2)} + \rect{(0,0),(2,2)} +\endmfpimage +\end{verbatim} +produces a simple 2-by-2 chessboard with its reference point at the +center point $(1,1)$. One can then write something like +\begin{verbatim} +\putmfpimage{Jan}{(1,1),(3,1),(1,3),(3,3)} +\end{verbatim} +to get a 4-by-4 chessboard: the picture \mfc{Jan} copied with its +center at each of the listed points. + +The behavior of \cs{tlabel} in an \env{mfpimage} environment depends on +the setting. If \opt{mplabels} is turned off, then labels are added by +\TeX{} and are \emph{not} included as part of the named \MF{} or \MP{} +picture variable. They are placed on the current picture as if the +\env{mfpimage} environment were not there at all. If \opt{mplabels} is +turned on and \opt{overlaylabels} is also turned on, or if the +\env{mfpimage} environment is between \cs{startbacktext} and +\cs{stopbacktext}, then the labels will be saved and placed when the +\env{mfpic} environment ends and \emph{not} added to the named picture +variable. Thus, to include text labels in the named picture variable, +you must have \opt{mplabels} on, \opt{overlaylabels} off, and +\env{mfpimage} outside any \cs{startbacktext}\slash\cs{stopbacktext}. + +The picture created by \cs{mfpimage} is locally defined. That is, it +becomes undefined at the end of the current \env{mfpic} environment. If +one needs it to be global, one can use \cs{globalsetmfvariable} (see +subsection~\ref{variables}) to copy it to another variable. For example. +the command +\begin{verbatim} + \globalsetmfvariable{picture}{Dan}{Jan} +\end{verbatim} +would make \gbc{Dan} globally defined to be equal to the current value +of the picture \gbc{Jan}. Note that picture variables can consume a lot +of \MF{}'s memory. Copying one variable to another doubles the amount of +memory, at least until the end of the \env{mfpic} environment. + +You can use \cs{putmfpimage} inside a \env{mfpimage} environment, +provided the picture being placed has been previously defined. Nesting a +\env{mfpimage} inside another has not been tested at all and so is not +recommended. But if it works, the inner image would be local to the +environment created by the outer one, and so would be of limited use. +One can use the \LaTeX{} environment construct \cs{begin}\marg{mfpimage} +$\ldots$ \cs{end}\marg{mfpimage} in a LaTeX document instead of +\cs{mfpimage} $\ldots$ \cs{endmfpimage}. + +\subsection{\CMF{} loops}\label{loops} + +All the \mfp{} loop commands create a loop (in the \MF{} language) in +the output file. The \MF{} commands in that loop are executed repeatedly +by \MF{} or \MP{}. From the point of view of \TeX{}, however each +command occurs only once. Starting with version 0.9, these loops can be +created inside or outside the \env{mfpic} drawing environment. If +outside, they must not contain any drawing commands, but can contain +commands that set variables, perform computations, etc. + +\begin{cd}\pagelabel{mfpfor} +\cs{mfpfor}\marg{\meta{for-loop header}}\\ + \ \meta{\mfp{} commands}\\ +\cs{endmfpfor}% +\index{mfpfor@\cs{mfpfor}}% +\index{endmfpfor@\cs{endmfpfor}} +\end{cd} + +This creates a for-loop in the \MF{} output file. The \cs{mfpfor} writes +the start of the loop and \cs{endmfpfor} writes the end. Any code +written in the output file between them is executed repeatedly by +\MF{}, according to the information in \meta{for-loop header}. There are +two types of headers possible, illustrated by the following examples. +\begin{verbatim} +\mfpfor{center = (0,0), (1,0), (0,1)} + \gfill\circle{center,1} +\endmfpfor +\end{verbatim} +This example will fill three circles of radius 1 with centers at the +three given points. This type of header has the format +\begin{display} + \mfc{\meta{variable} = \meta{list}} +\end{display} +where \meta{variable} should be a simple variable name and \meta{list} +is a comma separated list of items of the appropriate data type. In the +above, \gbc{center} is equated to pairs, but in the following +\begin{verbatim} +\mfpfor{radius = 1,3,4} + \dotted\circle{(0,0),radius} +\endmfpfor +\end{verbatim} +\gbc{radius} gets numeric data. + +The other type of header uses a stepped variable: +\begin{verbatim} +\mfpfor{level = 3 step 2 until 9} + \circle{(0,0),sqrt(level)} +\endmfpfor +\end{verbatim} +This will cause the \MF{} variable \gbc{level} to step through the +values 3, 5, 7 and 9 and the circles with radius $\sqrt{3}$, $\sqrt{5}$, +etc. will be drawn. This type of header has the format +\begin{display} + \mfc{\meta{variable} = \meta{start} step \meta{delta} until \meta{stop}} +\end{display} +where \meta{variable} is as before, while \meta{start}, \meta{delta} and +\meta{stop} are numeric values. If \meta{delta} is positive the loop is +skipped entirely if \meta{stop} is less than \meta{start}. Otherwise the +loop is executed successively with the variable equal to \meta{start}, +then $\meta{start} + \meta{delta}$ then $\meta{start} + 2\meta{delta}$, +etc., as long as the variable is not greater than \meta{stop}. The +behavior is similar if \meta{delta} is negative, except the loop is +repeated only as long as the variable is not less than \meta{stop}. If +\meta{delta} is \mfc{0}, then the \MF{} run will generate an error. + +Note that the index variable (\gbc{center} and \gbc{radius} in the above +two examples) is a temporary \MF{} variable. If \opt{mplabels} is turned +on, this variable will work as expected in the \emph{location} parameter +of a \cs{tlabel} command, but if it is used in the \emph{label} part, it +will be interpreted as \TeX{} code and printed as is. The index variable +reverts to its previous state outside the loop. That is, if it existed +before the loop, it regains its previous value after the loop, and if it +was undefined before the loop, it is again undefined after. + +The single word ``\mfc{upto}'' can be used as an abbreviation for +``\mfc{step 1 until}'' and ``\mfc{downto}'' for ``\mfc{step -1 until}'' +in for-loop headers. Spaces are not significant in for-loop headers, +except to distinguish the keywords (e.g. \mfc{step}) from variable names +that might be use (e.g., for \meta{start}). + +\begin{cd}\pagelabel{mfpwhile} + \cs{mfpwhile}\marg{\meta{condition}}\\ + \ \meta{\mfp{} commands}\\ + \cs{endmfpwhile}% +\index{mfpwhile@\cs{mfpwhile}}% +\index{endmfpwhile@\cs{endmfpwhile}} +\end{cd} + +The \meta{condition} should be an expression that can be either true or +false about a \MF{} variable that changes at some time during the loop +body. The loop body is executed (by \MF) as long as the condition is +true. Example: +\begin{verbatim} +\setmfvariable{numeric}{R}{20} +\mfpwhile{R > 1} + \rect{(0,0), (R,3R)} + \mfcmd{R:=R/2} +\endmfpwhile +\end{verbatim} +There are no \mfp{} command to \emph{systematically} change a variable, +so in this example we have resorted to directly writing a \MF{} assignment +command via \cs{mfcmd} (see subsection~\ref{mfcode} above) that reduces +\mfc{R} by half. The loop will be executed with \mfc{R} having the +successive values $20$, $10$, $5$, $2.5$, and $1.25$. The resulting +picture could have been achieved with \cs{mfpfor} using this list of +values. + +\begin{cd}\pagelabel{mfploop} +\cs{mfploop}\\ + \ \meta{\mfp{} commands}\\ +\cs{mfpuntil}\marg{\meta{condition}}\\ + \ \meta{\mfp{} commands}\\ +\cs{endmfploop}% +\index{mfploop@\cs{mfploop}}% +\index{mfpuntil@\cs{mfpuntil}}% +\index{endmfploop@\cs{endmfploop}}% +\end{cd} + +The body of this loop will be repeated until the \meta{condition} +becomes true. The condition should be some expression that can be either +true or false about a variable that changes during the loop execution. +It should eventually become true. If an \env{mfploop} environment does +not contain an \cs{mfpuntil} command, then the \cs{endmfploop} command +will generate a warning message. If the warning is ignored, and the user +has not otherwise arranged for loop termination,% + \footnote{Perhaps by means of \cs{mfsrc} commands. It is because of + this possibility that only a warning is produced and not an error.} +the \file{.mf} file will contain an infinite loop. The \cs{mfpuntil} +command will break the loop at whatever point it occurs. Example: +\begin{verbatim} +\setmfvariable{numeric}{R}{20} +\mfploop + \mfcmd{R:=R/2} + \mfpuntil{R <= 1} + \rect{(0,0), (R,3R)} +\endmfploop +\end{verbatim} +This will draw rectangles with $R$ equal to $10$, $5$, $2.5$, and +$1.25$. On the next execution of the loop the condition \mfc{R<=1} is +true, and the break occurs before the next rectangle is drawn. Note that +any \cs{mfpwhile} could be encoded with \cs{mfploop}. In fact, the code +written to the output file by +\begin{display} +\cs{mfpwhile}\marg{\meta{condition}} +\end{display} +is identical to that written by +\begin{display} +\cs{mfploop}\cs{mfpuntil}\marg{not \meta{condition}} +\end{display} + +The command \cs{mfpuntil} can also be used in \env{mfpfor} and +\env{mfpwhile} environments to break the loop prematurely when the given +condition becomes true. + +All three of these loop structures bracket the inner code in a \TeX{} +group. In a \LaTeX{} document, the usual \cs{begin}\slash\cs{end} style can +be used. For example, +\begin{verbatim} +\begin{mfpfor}{radius = 1,3,4} + \circle{(0,0),radius} +\end{mfpfor} +\end{verbatim} + +Just to be clear: in all the examples, what is written to the figure +file is a \emph{single} circle or rectangle drawing command, bracketed +by code that causes \MF{} to execute it several times with different +values for the variable. From \TeX{}'s point of view, there is only one +drawing command command. + +\subsection{Miscellaneous}\label{misc} + +\begin{cd}\pagelabel{mfmode} +\cs{mfmode}\marg{\meta{mode-name}}\\ +\cs{mfresolution}\marg{\meta{DPI}}% +\end{cd} + +When working with \MF{}, the code in \file{grafbase.mf} needs to know +the resolution at which to make the font with all the figures. If the +wrong resolution is assumed, the figure may end up appearing wrongly +scaled or have other problems (especially with shading). If your DVI +viewing/printing program and the file \file{modes.mf} are correctly +configured, nothing may need to be done. If not, as a last resort, you +can set the \MF{} mode or the \MF{} resolution in your \file{.tex} file +with these commands. If you don't know what that means, ask a guru, but +then you probably shouldn't be using \MF{} at all. + +\begin{cd}\pagelabel{noship} +\cs{noship}\\% +\cs{stopshipping}\\% +\cs{resumeshipping}% +\index{noship@\cs{noship}}% +\index{stopshipping@\cs{stopshipping}}% +\index{resumeshipping@\cs{resumeshipping}} +\end{cd} + +\cs{stopshipping} turns off character shipping (by \MF{} to the TFM and +GF files, or by \MP{} to appropriate \EPS{} output file) until +\cs{resumeshipping} occurs. If you want just one character not shipped, +just use \cs{noship} inside that \env{mfpic} environment. This is useful +if all one wishes to do in the current \env{mfpic} environment is to +make tiles (see above) or define picture variables with \cs{mfpimage} or +path arrays with \cs{patharr}. While \cs{mfpimage} defines the picture +locally, one can globally copy it to another variable with +\cs{globalsetmfvariable} (see subsection~\ref{variables}). + +\begin{cd}\pagelabel{assignmfvalue} +\cs{assignmfvalue}\marg{\meta{\TeX{}-macro}}\marg{\meta{MF-expr}}\\ +\cs{assignmpvalue}\marg{\meta{\TeX{}-macro}}\marg{\meta{MF-expr}}\\ +\cs{globalassignmfvalue}\marg{\meta{\TeX{}-macro}}\marg{\meta{MF-expr}}\\ +\cs{globalassignmpvalue}\marg{\meta{\TeX{}-macro}}\marg{\meta{MF-expr}}% +\index{assignmfvalue@\cs{assignmfvalue}}% +\index{assignmpvalue@\cs{assignmpvalue}}% +\index{globalassignmfvalue@\cs{globalassignmfvalue}}% +\index{globalassignmpvalue@\cs{globalassignmpvalue}}% +\end{cd} + +The commands \cs{assignmpvalue} and \cs{globalassignmpvalue} are just +alternative spellings. You can use either spelling with either the +\opt{metafont} or \opt{metapost} option. + +These commands causes the \meta{MF-expr} to be written to the output +file for \MF{} to evaluate. The resulting value is then written to the +\file{.log} file of that \MF{} run. On the next \TeX{} run, if +\opt{mfpreadlog} (see section~\ref{readlog}) is in effect, the macro +\meta{\TeX{}-macro} will be defined to produce the resulting value. For +example: +\begin{verbatim} +\setmfnumeric{s}{2} +\assignmfvalue{\val}{exp s} +\tlabel(1,2){$e^s = \val$} +\end{verbatim} +After \MF{} is run and then \TeX{} run a second time, \cs{val} will +acquire the definition `7.38905', the value of \gbc{exp s} when +\gbc{s=2} (i.e., $e^2$, correct to at least the fourth decimal place). +If \opt{mplabels} is in effect, the correct label is written to the +figure file only during this second run, and a second \MP{} run will be +required. In many cases (when using \pdfTeX{}, for example, or when the +label changes the figure dimensions), a third \TeX{} run will be +required to make the figure correct when it is included in the document. + +Before \MF{} is run to evaluate the expression, the macro produces +`???'. Thus, it cannot be used in places where a number is needed (as in +the position arguments of a \cs{tlabel} command). Note also that if a +command defined by \cs{assignmfvalue} is used in a tlabel with +\opt{mplabels} in effect, then \opt{mplabels} must be in effect during +the \cs{assignmfvalue} command as well. + +The `\texttt{global}' version makes the definition of the +\meta{\TeX{}-macro} global, surviving the current group. In particular, +it can be used in other pictures. The plain versions create commands +that are only locally defined. Past versions of this manual stated that +you can say +\begin{display} + \cs{global}\cs{assignmfvalue} +\end{display} +to define the macro globally. This turns out not to be true in all +cases. If a global definition is needed, use the global versions above. + +Because of the asynchronous nature of the definition process, using +\cs{assignmfvalue} with the same macro name more than once in the same +\env{mfpic} environment will not work. The macro acquires its definition +upon reading the logfile during the execution of \cs{opengraphsfile}, +and it will end up with the last definition encountered. (The same is +true for uses outside \env{mfpic} environments: the macro acquires the +last such definition.) Moreover, the definition is associated to a +picture by number. Which means that reordering the environments or +changing the numbering by any means will require the \TeX{}-\MF{}-\TeX{} +sequence (or more) to be repeated. + +If the \meta{\TeX{}-macro} is already defined, no warning will be issued +and the command will be redefined, so be careful in the name chosen. +If \opt{mplabels} is turned off when \cs{assignmfvalue} is used, but +turned on before the \meta{\TeX{}-macro} is used in a \cs{tlabel} +command, the macro definition will not be written to the \file{.mp} +file, and either an error message, or incorrect label will result +when \MP{} tries to make the tlabel. + +The concept and much of the code for \cs{assignmfvalue} came from Werner +Lemberg. However, I have rewritten it substantially to conform to \mfp{} +conventions and so any errors are my responsibility. + +\begin{cd}\pagelabel{cutoffafter} +\cs{cutoffafter}\marg{\meta{obj}}\dots\\ +\cs{cutoffbefore}\marg{\meta{obj}}\dots\\ +\index{cutoffafter@\cs{cutoffafter}}% +\index{cutoffbefore@\cs{cutoffbefore}}% +\end{cd} + +These prefix macros modify the following path by cutting part of it off. +They take an `object' (a variable in which a path was +previously stored using \cs{store}) and uses it to trim off one end of the +following path. \cs{cutoffbefore} cuts off the part of the path +\emph{before} its first intersection with the object, while +\cs{cutoffafter} cuts off the part \emph{after} the last intersection. +If the path does not intersect the object, nothing is cut off. If the +object and the path intersect in more than one point, as little as +possible (usually% + \footnote{\MF{}'s methods for finding the `first' point of + intersection do not always find the actual first one.}) % +is cut off. This is reliable only when there is only one point of +intersection. + +These macros can be used to create a curve that starts or ends +right at another figure without having to know the point where the two +curves intersect. + +\begin{cd}\pagelabel{random} +\cs{randomlines}\marg{\meta{maxshift}}\dots\\ +\cs{randomizepath}\marg{\meta{maxshift}, \meta{weirdness}}\dots +\index{randomizepath@\cs{randomizepath}}% +\index{randomlines@\cs{randomlines}} +\end{cd} + +These modify the following path by applying random shifts to the nodes +of a path. The first one, \cs{randomlines} then simply connects those +new points by straight lines, while the second one also applies +randomization to the control vectors. The \meta{maxshift} argument is +either a positive number (in graph units) that limits the distance a +node can be moved, or it is an ordered pair of positive numbers, in +which case the first limits the horizontal distance and the second +limits the vertical. If \meta{maxshift} is larger than the distance +between nodes, cusps or loops are likely in the result. + +For \cs{randomizepath} the \meta{weirdness} parameter controls how the +control vectors are modified. Roughly speaking the control vectors are +randomly rotated up to $30\langle\mathit{weirdness}\rangle$ degrees and +randomly scaled up or down by a factor of +$2^{\langle\mathit{weirdness}\rangle}$. (A `control vector' is a vector +pointing from a node to one of its control points.) However, this is +done in a way that preserves smoothness at each node where the path is +smooth. Values of \meta{weirdness} greater than 1 are probably too +weird. + +\begin{cd}\pagelabel{brownianmotion} +\cs{brownianmotion}\marg{\meta{start},\meta{num},\meta{scale}}% +\index{brownianmotion@\cs{brownianmotion}} +\end{cd} + +This figure macro uses another kind of randomness. The path starts at +the point \meta{start}, then proceeds in a straight line in a random +direction a random distance. The random process used is a normaldeviate +in each coordinate, scaled by \meta{scale}. This is repeated \meta{num} +times. Thus, \meta{start} is a coordinate pair in graph coordinates, +\meta{num} is a positive whole number and \meta{scale} is a positive +real number. In rare cases, the random distance can be quite large, but +on average it will be about $0.56\times{}$\meta{scale}. The size +(bounding box) of the resultant path can also be, in rare cases, +quite large, but it is usually on the order of $\sqrt{\meta{num}}$ times +\meta{scale}. + +The path produced is technically not Brownian motion, but rather a +`random walk'. However, for small \meta{scale} and large \meta{num} it +approximates Brownian motion. + +\begin{cd}\pagelabel{mftitle} +\cs{mftitle}\marg{\meta{title}}% +\index{mftitle@\cs{mftitle}} +\end{cd} + +Write the string \meta{title} to the \MF{} file, and use it as a \MF{} +message. (See \textit{The \MF{}book}, chapter 22, page 187, for two uses of +this.) + +\begin{cd}\pagelabel{tmtitle} +\cs{tmtitle}\marg{\meta{title}}% +\index{tmtitle@\cs{tmtitle}} +\end{cd} + +Write the text \meta{title} to the \TeX{} document, and to the log file, +and use it implicitly in \cs{mftitle}. This macro forms a local group +around its argument. + +\medskip + +Since \TeX{} is limited to 256 dimension registers, and since dimensions +are so important to typesetting and drawing, it is common to use up all +256 when drawing packages are loaded. Therefore \mfp{} uses font +dimensions to store dimension values. The following is the command that +handles the allocation of these dimensions. + +\begin{cd}\pagelabel{newfdim} +\cs{newfdim}\marg{\meta{fdim}}% +\index{newfdim@\cs{newfdim}} +\end{cd} + +This create a new global font dimension named \meta{fdim}, which is a +\TeX{} control sequence (with backslash). It can be used almost like +an ordinary \TeX{} dimension. One exception is that the \TeX{} commands +\cs{advance}, \cs{multiply} and \cs{divide} cannot be applied directly +to font dimensions (nor \LaTeX{}'s \cs{addtolength}); however, the font +dimension can be copied to a temporary \TeX{} dimension register, which +can then be manipulated and copied back (using \cs{setlength} in \LaTeX{}, +if desired). Another exception is that all changes to a font dimension +are global in scope. Also beware that \cs{newfdim} uses font dimensions +from a single font, the \file{dummy} font, which most \TeX{} systems +ought to have. (You'll know if yours doesn't, because \mfp{} will fail +upon loading!) Also, implementations of \TeX{} differ in the number of +font dimensions allowed per font. \Mfp{} currently uses font dimensions +23 through 52, which should be OK. + +Almost all of \mfp{}'s basic dimension parameters are font dimensions. +We arrange for them to be local to \env{mfpic} environments by saving +their values at the start and restoring them at the end. + +\begin{cd}\pagelabel{setmfpicgraphic} +\cs{setmfpicgraphic}\marg{\meta{filename}}% +\index{setmfpicgraphic@\cs{setmfpicgraphic}} +\end{cd} + +This is the command that is invoked to place the graphic created. See +appendix~\ref{graphics} for a discussion of its use and its default +definition. It is a user-level macro so that it can be redefined in +unusual cases. It operates on the output of the following macro: + +\begin{cd}\pagelabel{setfilename} +\cs{setfilename}\marg{\meta{file}}\marg{\meta{num}}% +\index{setfilename@\cs{setfilename}} +\end{cd} + +\Mfp's figure inclusion code ultimately executes +\cs{setmfpicgraphic} on the result of applying \cs{setfilename} to two +arguments: the file name specified in the \cs{opengraphsfile} command +and the number of the current picture. Normally \cs{setfilename} just +puts them together with the `\texttt{.}' separator (because that is +usually the way \MP{} names its output), but this can be redefined if +the \MP{} output undergoes further processing or conversion to another +format in which the name is changed. Any redefinition of +\cs{setfilename} must come before \cs{opengraphsfile} because that +command tests for the existence of the first figure. After any +redefinition, \cs{setfilename} must be a macro with two arguments that +creates the actual filename from the above two parts. It should also be +completely expandable. See the appendices, subsection~\ref{graphics} for +further dicussion. + +\begin{cd}\pagelabel{setfilenametemplate} +\cs{setfilenametemplate}\marg{\meta{template}}% +\index{setfilenametemplate@\cs{setfilenametemplate}} +\end{cd} + +With the \opt{metapost} option, when you write +\cs{opengraphsfile{figs}}, a file \file{figs.mp} is created. By default, +running \MP{} on it results in files named \file{figs.1}, \file{figs.2}, +etc. Recent \MP{} allows the output filenames to be modified. As of +\mfp{} version \mfpversion, you can do this to some extent from your +\file{.tex} file. One needs to define a template that tells \MP{} how to +construct the output file name from the `jobname' and the figure number. +This is done with the above command. In \meta{template} you can put any +plain characters, plus the two special tokens: \verb$\_$ and \verb$\#$. +Each figure's filename is constructed by replacing these tokens with the +\MP{} jobname and the figure number, respectively. For example, with the +jobname \file{figs}, +\begin{verbatim} +\setfilenametemplate{my\_-\#.mps} +\end{verbatim} +will cause the figure files to have names \file{myfigs-1.mps}, +\file{myfigs-2.mps}, etc., instead of the defaults. \Mfp{} adjusts the +definition of \cs{setfilename} accordingly, so that the correct +filenames are used. + +Do not use this command unless you know your version of \MP{} is recent +enough to have this capability. Under the \opt{metafont} option, this +command is simply ignored, but \mfp{} has no way of checking the \MP{} +version on its own. + + +\begin{cd}\pagelabel{preparemfpicgraphic} +\cs{preparemfpicgraphic}\marg{\meta{filename}}% +\index{preparemfpicgraphic@\cs{preparemfpicgraphic}} +\end{cd} + +This command is automatically invoked before \cs{setmfpicgraphic} to +make any preparations needed. The default definition is to do nothing +except when the \prog{graphics} package is used. That package provides +no clean way to determine the bounding box of the graphic after it is +included. Since \mfp{} needs this information, this command redefines an +internal command of the \prog{graphics} package to make the data +available. If \cs{setmfpicgraphic} is redefined then this may also have +to be redefined. + +\begin{cd}\pagelabel{getmfpicoffset} +\cs{getmfpicoffset}\marg{\meta{filename}}% +\index{getmfpicoffset@\cs{getmfpicoffset}} +\end{cd} + +This command is automatically invoked after \cs{setmfpicgraphic} to +store the offset of the lower left corner of the figure in the macros +\cs{mfpicllx} and \cs{mfpiclly}. If \cs{setmfpicgraphic} is redefined +then this may also have to be redefined. + +\begin{cd}\pagelabel{ifmfpmpost} +\cs{ifmfpmpost}% +\index{ifmfpmpost@\cs{ifmfpmpost}} +\end{cd} + +Users wishing to write code that adjusts its behavior to the graph file +processor can use this to test which option is in effect. The macro +\cs{usemetapost} sets it true and \cs{usemetafont} sets it false. There +are no commands \cs{mfpmposttrue} nor \cs{mfpmpostfalse}, since the user +should not be changing the setting once it is set: a great deal of +\mfp{} internal code depends on them, and on keeping them consistent +with the \cs{opengraphsfile} commands reading of these booleans. + +\begin{cd}\pagelabel{mfpicversion} +\cs{mfpicversion}% +\index{mfpicversion@\cs{mfpicversion}} +\end{cd} + +This expands to the current \mfp{} version multiplied by 100. At this +writing, it produces `\texttt{100}' because the version is 1.0. It can +be used to test the version: +\begin{verbatim} +\ifx\mfpicversion\undefined \def\mfpicversion{0}\fi +\ifnum\mfpicversion>70 ... \else ... \fi +\end{verbatim} +\cs{mfpicversion} was added in version 0.7. + + +Most of \mfp{}'s commands have arguments with parts delimited by commas +and parentheses. In most cases this is no problem because they are +written unchanged to the \file{.mf} and there they are parsed just fine. +Some commands' arguments, however, have to be parsed by both \TeX{} and +\MF{}. Examples are \cs{tlabel} (sometimes, under \opt{mplabels}), and +\cs{pointdef}. One might be tempted to use \MP{} expressions there and +that works fine as long as they do not contain commas or parentheses. In +such cases, they can sometimes be enclosed in braces to prevent \TeX{} +seeing these elements as delimiters, but sometimes these braces might +get written to the \file{.mf} (or \file{.mp}) output and cause a \MF{} +(\MP{}) error. In such cases the following work-around might be possible: +\begin{verbatim} +\def\identity#1{#1} +\pointdef{A}(\identity{angle (1,2)},3) +\rect{(0,0),\A} +\end{verbatim} + +The braces prevent \TeX{}'s argument parsing from seeing the first comma +as a delimiter, but upon writing to the \file{.mf}, the \cs{identity} +commands are expanded and only the contents appear in the output. (\TeX{} +parses the argument to assign meanings to \cs{Ax} and \cs{Ay}.) + +If the \prog{babel} package is loaded with certain options, the comma +may become a special character. In that case, one may need to deactivate +babel shorthands before some \mfp{} code. One might use \cs{everymfpic} +to do this in every \env{mfpic} environment. In some cases, one may need +to reactivate babel shorthands insided \cs{tlabel}, and one might use +\cs{everytlabel} for this purpose. See your \prog{babel} documentation +for the commands to do these things. + +\clearpage + +\def\sectionmark#1{\markright {\thesection\quad#1}}% +\def\subsectionmark#1{} +\def\subsubsectionmark#1{} +\thispagestyle{plain} +\chapter{Appendices}\label{appendices} + +\section{Acknowledgements.}\label{acknowledgements} + +Tom would like to thank all of the people at Dartmouth as well as out in +the network world for testing \mfp{} and sending him back +comments. He would particularly like to thank: + +Geoffrey Tobin +for his many suggestions, especially about cleaning up the \MF{} code, +enforcing dimensions, fixing the dotted line computations, and speeding +up the shading routines (through this process, Geoffrey and Tom managed +to teach each other many of the subtleties of \MF{}), and for keeping +track of \mfp{} for nearly a year while Tom finished his thesis; + +Bryan Green +for his many suggestions, some of which (including his rewriting the +\cs{tcaption} macro) ultimately led to the current version's ability to +put graphs in-line or side-by-side; and + +Uwe Bonnes and +Jarom\'\i r Kuben, +who worked out rewrites of \mfp{} during Tom's working hiatus and who +each contributed several valuable ideas. + +Some credit also belongs to +Anthony Stark, +whose work on a FIG to \MF{} converter has had a serious impact on the +development of many of \mfp{}'s capabilities. + +Finally, Tom would like to thank +Alan Vlach, +the other \TeX{}nician at Berry College, for helping him decide on the +format of many of the macros, and for helping with testing. + +\medskip +Dan Luecking would like to echo Tom's thanks to all of the above, +especially Geoffrey Tobin and Jarom\'\i r Kuben. And to add the names +Taco Hoekwater, for comments, advice and suggestions, Werner Lemberg, +for the \cs{assignmfvalue} command, and Zaimi Sami~Alex for suggestions. + +But mostly, he'd like to thank Tom Leathrum for starting it all. + +\section{Changes History.}\label{changes} + +See the file \file{changes.txt} for a somewhat sporadic history of +changes to \mfp{}. See the file \file{README} for changes added since +the previous version, and for any known problems. + +%\clearpage +\section{Summary of Options.}\label{summary} + +Unless otherwise stated, any of the command forms will be local to the +current \env{mfpic} environment if used inside. Otherwise it will affect +all later environments. + +\medskip +% \shortstack doesn't allow [t] aligment: +\def\stack#1{{\tabular[t]{@{}l@{}}#1\endtabular}} + +% Use halign so it will break over 2 pages +{\openup\jot +\halign to \textwidth + {#\hfil\quad\tabskip0ptplus 1fil& + #\hfil\quad& + \vtop{\parindent0pt\rightskip0pt plus 1fil\relax + \hsize.5\hsize\normalbaselines + \strut#\strut}\tabskip0pt \cr +\textsc{Option}:& \textsc{Command form(s)}:& \textsc{Restrictions}:\cr +\noalign{\smallskip\hrule\smallskip} +\opt{metapost}& + \cs{usemetapost}& + Command must come before \cs{opengraphsfile}. + Incompatible with \opt{metafont} option.\cr +\opt{metafont}& + \cs{usemetafont}& + The default. Command must come before + \cs{opengraphsfile}. Incompatible with \opt{metapost} + option. \cr +\opt{mplabels}& + \stack{\cs{usemplabels},\\ \cs{nomplabels}}& + Requires \opt{metapost}. If command is used inside an + \env{mfpic} environment, it should come before + \cs{tlabel} commands to be affected. \cr +\opt{overlaylabels}& + \stack{\cs{overlaylabels},\\ \cs{nooverlaylabels}}& + Has no effect without \opt{metapost}. \cr +\opt{truebbox}& + \stack{\cs{usetruebbox},\\ \cs{notruebbox}}& + Has no effect without \opt{metapost}. \cr +\opt{clip}& + \stack{\cs{clipmfpic},\\ \cs{noclipmfpic}}& + No restrictions. \cr +\opt{clearsymbols}& + \stack{\cs{clearsymbols},\\ \cs{noclearsymbols}}& + No restrictions. \cr +\stack{\opt{centeredcaptions}\\ \opt{raggedcaptions}}& + \stack{\cs{usecenteredcaptions},\\ \cs{nocenteredcaptions}\\ + \cs{useraggedcaptions},\\ \cs{noraggedcaptions}}& + If command is used inside an \env{mfpic} environment, it + should come before the \cs{tcaption} command.\cr +\opt{debug}& + \stack{\cs{mfpicdebugtrue},\\\cs{mfpicdebugfalse}}& + To turn on debugging while \file{mfpic.tex} is loading, + issue \cs{def}\cs{mfpicdebug}\marg{true}.\cr +\stack{\opt{draft}\\ \opt{final}\\ \opt{nowrite}}& + \stack{\cs{mfpicdraft}\\ \cs{mfpicfinal}\\ \cs{mfpicnowrite}}& + Should not be used together. Command forms should come + before \cs{opengraphsfile} \cr +\opt{mfpreadlog}& + \cs{mfpreadlog}& + Needed for \cs{assignmfvalue}. Must occur before + \cs{opengraphsfile}. \cr +}} + +%\clearpage +\section{Plotting Styles for \cs{plotdata}.}\label{styles} + +When \cs{plotdata} passes from one curve to the next, it increments a +counter and uses that counter to select a dash pattern, color, or +symbol. It uses predefined dash \mfc{dashtype0} through \mfc{dashtype5}, +or predefined colors \mfc{colortype0} through \mfc{colortype7}, or +predefined symbols \mfc{pointtype0} through \mfc{pointtype8}. Here +follows a description of each of these variables. These variables must +not be used in the second argument of \cs{reconfigureplot}, whose +purpose is to redefine these variables. + +\medskip +Under \cs{dashedlines}, we have the following dash patterns: + +\medskip +\begin{tabular}{@{}lll} +\textsc{Name}&\textsc{Pattern}&\textsc{Meaning}\cr +\hline +\vbox to 10pt{}% +\mfc{dashtype0}& \dim{0bp} & solid line \\ +\mfc{dashtype1}& \dim{3bp,4bp} & dashes \\ +\mfc{dashtype2}& \dim{0bp,4bp} & dots \\ +\mfc{dashtype3}& \dim{0bp,4bp,3bp,4bp} & dot-dash \\ +\mfc{dashtype4}& \dim{0bp,4bp,3bp,4bp,0bp,4bp}& dot-dash-dot \\ +\mfc{dashtype5}& \dim{0bp,4bp,3bp,4bp,3bp,4bp}& dot-dash-dash +\end{tabular} + +\medskip +Under \cs{coloredlines}, we have the following colors. Except for +\mfc{black} and \mfc{red}, each color is altered as indicated. This is +an attempt to make the colors more equal in visibility against a white +background. (The success of this attempt varies greatly with the output +or display device.) Four of the eight colors use the cmyk model +when the \MP{} version is at least $1.000$. + +\medskip +\begin{tabular}{@{}llll} +\textsc{Name}&\textsc{Color}&\textsc{(r,g,b)}&\textsc{(c,m,y,k)}\\ +\hline +\vbox to 10pt{}% +\mfc{colortype0}& black & $( 0, 0, 0)$&(0,0,0,1)\\ +\mfc{colortype1}& red & $( 1, 0, 0)$&\\ +\mfc{colortype2}& blue & $( .2, .2, 1)$&\\ +\mfc{colortype3}& orange & $(.66,.34, 0)$&\\ +\mfc{colortype4}& green & $( 0, .8, 0)$&\\ +\mfc{colortype5}& magenta& $(.85, 0,.85)$&(0,.85,0,.15)\\ +\mfc{colortype6}& cyan & $( 0,.85,.85)$&(.85,0,0,.15)\\ +\mfc{colortype7}& yellow & $(.85,.85, 0)$&(0,0,.85,.15)\\ +\end{tabular} + +\medskip + +Under \cs{pointedlines} and \cs{datapointsonly}, the following symbols +are used. Internally each is referred to by the numeric name, but they +are identical to the more descriptive name. Syntactically, all are \MF{} +path variables. (The order changed between versions 0.6 and 0.7.) + +\medskip +\begin{tabular}{@{}ll} +\textsc{Name}&\textsc{Description}\\ +\hline +\vbox to 10pt{}% +\mfc{pointtype0}& \mfc{Circle} \\ +\mfc{pointtype1}& \mfc{Cross} \\ +\mfc{pointtype2}& \mfc{SolidDiamond} \\ +\mfc{pointtype3}& \mfc{Square} \\ +\mfc{pointtype4}& \mfc{Plus} \\ +\mfc{pointtype5}& \mfc{Triangle} \\ +\mfc{pointtype6}& \mfc{SolidCircle} \\ +\mfc{pointtype7}& \mfc{Star} \\ +\mfc{pointtype8}& \mfc{SolidTriangle} +\end{tabular} + +\section{Special Considerations When Using \CMF{}.}\label{mfconsiderations} + +The most important restriction in \MF{} is on the size of a picture. +Coordinates in \MF{} ultimately refer to pixel units in the font that is +output. These are required to be less than 4096, so an absolute limit on +the size of a picture is whatever length a row of 4095 pixels is. In +fonts prepared for a LaserJet4 (600 DPI), this means 6.825 inches +(17.3355cm). For a 1200 DPI pronter, the limit is 3.4125 inches. + +A similar limit holds for numbers input, and the values of variables: +\MF{} will return an error for \mfc{sin 4096}. Intermediate values can +be greater (\mfc{sin (2*2048)} will cause no error), but final, stored +results are subject to the limit. An \mfp{} example that generated an +error recently was: +\begin{verbatim} +\mfpicunit 1mm +\mfpic[10]{-3}{7}{-3.5}{5} + \function{-4.5,4,.1}{x*x} +\endmfpic +\end{verbatim} +The problem was the value of $4.5*4.5 = 20.25$: after multiplying by the +\cs{mfpic} scaling factor, the \cs{mfpicunit} in inches, and the DPI +value, this produces $20.25\times10\times0.03937\times600 > 4783$ pixel +units. The error did not occur at the point of creating the font, but +merely at the point of storing the path in an internal variable for +manipulation and drawing. Thus, the fact that this particular picture +was clipped to a much smaller size for printing did not help. + +In \MP{}, the limit on numeric values is only 8 times as high: $32768$. +However, that is independent of printer resolution and is interpreted as +\PS{} points (\TeX{}'s `big points'). At $72$ points to the inch, this +allows figures to be about 12.64 yards (11.56$\,$m). + + +\section{Special Considerations When Using \CMP{}.}\label{mpconsiderations} + +\subsection{Required support} + +To use \mfp{} with \MP{}, the following support is needed (besides a +working \MP{} installation): + +\medskip\noindent +\begin{tabular}{@{}lp{4.2in}} +plain \TeX{} &The file \file{epsf.tex} or \file{epsf.sty}\\ +\LaTeX{}209 &(No longer supported, but plain \TeX{} methods + might work)\\ +\LaTeX{} &The package \prog{graphics} or \prog{graphicx}\\ +\pdfLaTeX{} &The package \prog{graphics} or + \prog{graphicx} with option \opt{pdftex}\\ +plain \pdfTeX{} &The files \file{supp-pdf.mkii} or \file{supp-pdf.tex} + and (possibly) \file{supp-mis.tex}\\ +In all cases &\raggedright The files \file{grafbase.mp} and + \file{dvipsnam.mp} plus, of course, + \file{mfpic.tex} (and \file{mfpic.sty} for + \LaTeX{}) +\end{tabular} + +\medskip +The files \file{grafbase.mp} and \file{dvipsnam.mp} should be in a +directory searched by \MP{}. The remaining files should be in directories +searched by the appropriate \TeX{} variant. If \MP{} cannot find the +file \file{grafbase.mp}, then by default it will try to input +\file{grafbase.mf}, which is generally futile (or fatal). + +In case \pdfLaTeX{} is used, the \prog{graphics} package is given the +\opt{pdftex} option. This option requires the file \file{pdftex.def} +which currently inputs one of the \file{supp-pdf} files. Early versions +of \file{supp-pdf.tex} will input \file{supp-mis.tex}. These three files +should be supplied with most \TeX{} installations.% + \footnote{At this writing, these files, plus a few others, + can found at \file{CTAN/macros/pdftex/graphics/}.} % +Older versions had some bugs in connection with the \prog{babel} +package. One workaround was to load the \prog{graphics} package and +\mfp{} before \prog{babel}. + +If the user loads one of the above required files or packages before the +\mfp{} macros are loaded then \mfp{} will not reload them. \Mfp{} will +load whichever one it decides is required. In the \LaTeXe{} case, \mfp{} +will load the \prog{graphics} package. If the user wishes +\prog{graphicx}, then that package must be loaded before \mfp{}. + +\subsection{\CMP{} is not \MF{}} + +\PS{} is not a pixel oriented language and so neither is \MP{}. The model +for drawing objects is completely different between \MF{} and \MP{}, and +so one cannot always expect the same results. \CMP{} support in +\mfp{} was carefully written so that files successfully printed +with \mfp{} using \MF{} would be just as successfully printed +using \MP{}. Nevertheless, it frequently chokes on files that make use of +the \cs{mfsrc} command for writing code directly to the \file{.mf} file. +While \file{grafbase.mp} is closely based on \file{grafbase.mf}, some of +the code had to be completely rewritten. + +Pictures in \MP{} are stored as (possibly nested) sequences of objects, +where objects are things like points, paths, contours, sub-pictures, +etc. In \MF{}, pictures are stored as a grid of pixels. Pictures that are +relatively simple in one program might be very complex in the other and +even exceed memory allocated for their storage. Two examples are the +\cs{polkadot} and \cs{hatch} commands. When the polkadot space and size +are both too small, a \cs{polkadot}-ed region has been known to exceed +\MP{} capacity, while being well within \MF{} capacity. In \MP{} the +memory consumed by \cs{hatch} goes up in direct proportion to the linear +dimensions of the figure being hatched, while in \MF{} it goes up in +proportion to the area (except in horizontal hatching), and then the +reverse can happen, with \MF{}'s capacity exeeded far sooner that \MP{}'s. + +In \MP{} it is important to note that each +prefix modifies the result of the entire following sequence. In essence +prefixes can be viewed as being applied in the opposite order to their +occurrence. Example: +\begin{verbatim} +\dashed\gfill\rect{(0,0),(1,1)} +\end{verbatim} +This adds the dashed outline to the filled rectangle. That is, first the +rectangle is defined, then it is filled, then the outline is drawn in +dashed lines. This makes a difference when colors other than black are +used. Drawing is done with the center of the virtual pen stroked down +the middle of the boundary, so half of its width falls inside the +rectangle. On the other hand, filling is done right up to the boundary. +In this example, the dashed lines are drawn on top of part of the fill. +In the reverse order, the fill would cover part of the dashed outline. + +\subsection{Graphic inclusion}\label{graphics} + +It may be impossible to completely cater to all possible methods of +graphic inclusions with automatic tests. The macro that is invoked +to include the \PS{} graphic is \cs{setmfpicgraphic} and the user +may (carefully!) redefine this to suit special circumstances. Actually, +\mfp{} runs the following sequence: + +\begin{ex} + \cs{preparemfpicgraphic}\marg{\meta{filename}}\\ + \cs{setmfpicgraphic}\marg{\meta{filename}}\\ + \cs{getmfpicoffset}\marg{\meta{filename}}% +\index{preparemfpicgraphic@\cs{preparemfpicgraphic}}% +\index{setmfpicgraphic@\cs{setmfpicgraphic}}% +\index{getmfpicoffset@\cs{getmfpicoffset}} +\end{ex} + +The following are the default definitions for \cs{setmfpicgraphic}: + +\medskip\noindent +\begin{tabular}{@{}ll} +plain \TeX{}& + \cs{def}\cs{setmfpicgraphic}\texttt{\#1}\marg{\cs{epsfbox}% + \marg{\#1}}\\ +\LaTeX{}209& (No longer supported, but likely the plain \TeX{} +definition will be selected.)\\ +\LaTeX{}& + \cs{def}\cs{setmfpicgraphic}\texttt{\#1}\marg{\cs{includegraphics}% + \marg{\#1}}\\ +\pdfLaTeX{}& + \cs{def}\cs{setmfpicgraphic}\texttt{\#1}\marg{\cs{includegraphics}% + \marg{\#1}}\\ +\pdfTeX{}& + \cs{def}\cs{setmfpicgraphic}\texttt{\#1}\marg{\cs{convertMPtoPDF}% + \marg{\#1}\marg{1}\marg{1}} +\end{tabular} + +\medskip +Moreover, since \MP{} by default writes files with numeric extensions, +we add code to each figure, so that these graphics are correctly +recognized as \EPS{} or \prog{MPS}. For example, to the figure with +extension \file{.1}, we add the equivalent of one of the following +\begin{itemize} +\item[] \cs{DeclareGraphicsRule}\marg{.1}\marg{eps}\marg{.1}\marg{} in \LaTeXe{}. +\item[] \cs{DeclareGraphicsRule}\marg{.1}\marg{mps}\marg{.1}\marg{} in +\pdfLaTeX{}. +\end{itemize} + +After running the command \cs{setmfpicgraphic}, \mfp{} runs +\cs{getmfpicoffset} to store the lower left corner of the bounding box +of the figure in two macros \cs{mfpicllx} and \cs{mfpiclly}. All the +above versions of \cs{setmfpicgraphic} (except \cs{includegraphics}) +make this information available; the definition of \cs{getmfpicoffset} +merely copies it into these two macros. What \mfp{} does in the +case of \cs{includegraphics} is to modify (locally) the definition of an +internal command of the \prog{graphics} package so that it copies the +information to those macros, and then \cs{getmfpicoffset} does nothing. +This internal modification is accomplished by the macro +\cs{preparemfpicgraphic}. Changes to \cs{setmfpicgraphic} might require +changing either or both of \cs{preparemfpicgraphic} and +\cs{getmfpicoffset}. All three of these commands are fed the graphic's +file name as the only argument, although only \cs{setmfpicgraphic} +currently does anything with it. + +One possible reason for wanting to redefine \cs{setmfpicgraphic} might +be to rescale all pictures. This is \emph{definitely not} a good idea. A +good deal of \mfp{}'s figure placemant code assumes that the size of the +figure is consistent with the coordinate system set up by the \cs{mfpic} +command. With \opt{mplabels} plus \opt{truebbox} it might work, but +(i)~it has \emph{not} been considered in writing the \mfp{} code, +(ii)~it will then scale all the text as well as the figure, and (iii)~it +will scale all line thickness, which should normally be a design choice +independent of the size of a picture. To rescale all pictures, one need +only change \cs{mfpicunit} and rerun \TeX{} and \MP{}. + +A better reason might be to allow the conversion of your \MP{} figures +to some other format. Then redefining \cs{setmfpicgraphic} +could enable including the appropriate file in the appropriate format. + +The filename argument mentioned above is actually the result obtained by +running the macro \cs{setfilename}\index{setfilename@\cs{setfilename}}. +The command \cs{setfilename} gets two arguments: the name of the \MP{} +output file (set in the \cs{opengraphsfile} command) without extension, +and the number of the picture. The default definition of +\cs{setfilename} merely inserts a dot between the two arguments. That is +\cs{setfilename}\marg{fig}\marg{1} produces \file{fig.1}. You can +redefine this behavior also. Any changes to \cs{setfilename} must come +after the \mfp{} macros are input and before the +\cs{opengraphsfile} command. Any changes to \cs{setmfpicgraphic} must +come after the \mfp{} macros are input and before any \cs{mfpic} +commands, but it is best to place it before the \cs{opengraphsfile} +command. + +As \mfp{} is currently written, \cs{setfilename} must be +\emph{completely expandable}, which means it should contain no +definitions, no assignments such as \cs{setcounter}, and no +calculations.% + \footnote{But appropriate use of \cs{numexpr} (in \eTeX) for + calculations is probably OK.} +To test whether a proposed definition is completely +expandable, put +\begin{verbatim} +\message{***\setfilename{file}{1}***} +\end{verbatim} +after the definition in a \file{.tex} file and view the result on the +terminal or in the \file{.log} file. You should see only your expected +filename between the asterisks. + + +\section{\prog{Mfpic} and the Rest of the World.} + +\subsection{The literature} + +This author has personal knowledge of only one mathematical article +which definitely uses \mfp{} to create diagrams, and that is this +author's joint paper with J.~Duncan and C.~M.~McGregor: \textit{On the +value of pi for norms in $\mathbf{R}^2$} in the College Mathematics +Journal, vol.~35, pages 84--92. Oddly enough, it was McGregor and not me +who chose to use \mfp{} for the illustrations. + +There are at least two major publications where \mfp{} has garnered more +than a cursory mention. The most up-to-date is a section in \textit{The +\LaTeX{} Graphics Companion} by Michel Goossens, Sebastian Rahtz and +Frank Mittelbach. It describes a version prior to the introduction of +\MP{} support, but it correctly describes a subset of its current +commands and abilities. \textit{The \LaTeX{} Companion} (Second Edition) +mentions \mfp{}, but only in its annotation of the bibliography entry +for \textit{\TeX{} Unbound} (see below). + +The other is \textit{\TeX{} Unbound} by Alan Hoenig, which contains a +chapter on \mfp{}. Unfortunately, it describes a version that was +replaced in 1996 with version 0.2.10.9. The following summarizes the +differences between the description% + \footnote{While I'm at it: \textit{\TeX{} Unbound} occasionally + refers to \mfp{} using a logo-like formatting in which the `MF' is + in a special font and the `I' is lowered. This `logo' may suggest + a relationship between \mfp{} and \PiCTeX{}. There is no such + relationship, and there is no official logo-like designation for + \mfp{}.} % +found in Chapter 15 and \mfp{} versions 0.2.10.9 through the +current one: + +\cs{wedge} is now renamed \cs{sector} to avoid conflict with the \TeX{} +command of the same name. The syntax is slightly different from that +given for \cs{wedge}: +\begin{ex} + \cs{sector}\marg{(\meta{x},\meta{y}), \meta{radius}, \meta{angle1}, + \meta{angle2}} +\end{ex} + +The macro \cs{plr}\marg{(\meta{$r_0$},\meta{$\theta_0$}),% +(\meta{$r_1$},\meta{$\theta_1$}),$\ldots$} is used to convert polar +coordinate pairs to rectangular coordinates, so the commands +\cs{plrcurve}, \cs{plrcyclic}, \cs{plrlines} and \cs{plrpoint} were +dropped from \mfp{}. Now use +\begin{ex} + \cs{curve}\marg{\cs{plr}\marg{(\meta{$r_0$},\meta{$\theta_0$}),% + (\meta{$r_1$},\meta{$\theta_1$}),$\ldots$}} +\end{ex} +instead of +\begin{ex} + \cs{plrcurve}\marg{(\meta{$r_0$},\meta{$\theta_0$}),% + (\meta{$r_1$},\meta{$\theta_1$}),$\ldots$} +\end{ex} +and similarly for \cs{plrcyclic}, \cs{plrlines} and \cs{plrpoint}. + +\cs{fill} is now renamed \cs{gfill} to avoid conflict with the \LaTeX{} +command of the same name. + +\cs{rotate}, which rotates a following figure about a point, is now +renamed \cs{rotatepath} to avoid confusion with a similar name for a +transformation (see below). + +\cs{white} is now renamed \cs{gclear} because \cs{white} is too likely +to be chosen for, or confused with, a color command. + +\smallskip +The following affine transform commands were changed from a third person +indicative form (which could be confused with a plural noun) to an +imperative form: + +\begin{ex} +\begin{tabular}{@{}ll} + Old name: & New name:\\ + \cs{boosts} & \cs{boost}\\ + \cs{reflectsabout} & \cs{reflectabout}\\ + \cs{rotatesaround} & \cs{rotatearound}\\ + \cs{rotates} & \cs{rotate}\\ + \cs{scales} & \cs{scale}\\ + \cs{shifts} & \cs{shift}\\ + \cs{xscales} & \cs{xscale}\\ + \cs{xslants} & \cs{xslant}\\ + \cs{xyswaps} & \cs{xyswap}\\ + \cs{yscales} & \cs{yscale}\\ + \cs{yslants} & \cs{yslant}\\ + \cs{zscales} & \cs{zscale}\\ + \cs{zslants} & \cs{zslant} +\end{tabular} +\end{ex} + +\cs{caption} and \cs{label} are now renamed \cs{tcaption} and +\cs{tlabel} to avoid conflict with the \LaTeX{} commands. + +\cs{mfcmd} was renamed \cs{mfsrc} for clarity, and (in version 0.7) a +new \cs{mfcmd} was defined, which is pretty much the same except it appends +a semicolon to its argument. + +\smallskip +There is a misprint: \cs{axisheadlin} should be \cs{axisheadlen}. + +Finally, in the \LaTeX{} template on page 496: recent \mfp{} may be +loaded with \cs{usepackage}. + +\subsection{Other programs} + +There exists a program, \prog{fig2mfpic} that produces \mfp{} code as +output. The code produced (as of this writing) is somewhat old and +mostly incompatible with the description in this manual. Fortunately, it +is accompanied by the appropriate versions of files \file{mfpic.tex} and +\file{grafbase.mf}. Unfortunately, the names conflict with the current +filenames and so they should only be used in circumstances where no +substitution will occur, say in a local directory with the other sources +for the document being produced. Moreover, the documentation in this +manual may not apply to the code produced. However the information in +\textit{\TeX{} Unbound} may apply. + +There exist a package, \prog{circuit\_macros}, that can produce a +variety of output formats, one of which is \mfp{} code. One writes a +file (don't ask me what it consists of) and apparently processes it with +\prog{m4} and then \prog{dpic} to produce the output. The \mfp{} code +produced appears to be compatible with the current \mfp{}. + +\renewcommand\mfpindexheading{% + \section{Index of commands, options and parameters.}} +\let\oldcs\cs +\renewcommand{\cs}[1]{\leavevmode\mytt{\llap{\char`\\}#1}} + +\InputIfFileExists{mfpic-doc.ind}{}{\mfpindexheading} + +\let\cs\oldcs + +\columnseprule 0pt +\columnsep 35pt +\twocolumn[\section{List of commands by type.}] +\parindent0pt +\parskip0pt plus .3pt\relax +\makeatletter +\renewcommand\@idxitem{\par\hangindent 10\p@} +\let\item\@idxitem +\makeatother + +\subsection{Figure macros} + + \item \cs{arc}, \pageref{arc} + \item \cs{axis}, \pageref{axis} + \item \cs{axisline}, \pageref{axisline} + \item \cs{belowfcn}, \pageref{belowfcn} + \item \cs{border}, \pageref{axisline} + \item \cs{brownianmotion}, \pageref{brownianmotion} + \item \cs{btwnfcn}, \pageref{btwnfcn} + \item \cs{btwnplrfcn}, \pageref{btwnfcn} + \item \cs{cbeziers}, \cs{closedcbeziers}, \pageref{cbeziers} + \item \cs{chartbar}, \pageref{chartbar} + \item \cs{circle}, \pageref{circle} + \item \cs{computedspline},\\ + \cs{closedcomputedspline}, \pageref{computedspline} + \item \cs{convexcurve}, \cs{closedconvexcurve}, \pageref{convexcurve} + \item \cs{convexcyclic}, \pageref{convexcurve} + \item \cs{cspline}, \cs{closedcspline}, \pageref{qspline} + \item \cs{curve}, \cs{closedcurve}, \pageref{curve} + \item \cs{cyclic}, \pageref{curve} + \item \cs{datafile}, \pageref{datafile} + \item \cs{ellipse}, \pageref{ellipse} + \item \cs{fcncurve}, \pageref{fcncurve} + \item \cs{fcnspline}, \pageref{fcnspline} + \item \cs{function}, \pageref{function} + \item \cs{ganttbar}, \pageref{chartbar} + \item \cs{graphbar}, \pageref{chartbar} + \item \cs{histobar}, \pageref{chartbar} + \item \cs{levelcurve}, \pageref{levelcurve} + \item \cs{lines}, \pageref{polyline} + \item \cs{mfbezier}, \cs{closedmfbezier}, \pageref{mfbezier} + \item \cs{mfobj}, \cs{mpobj}, \pageref{mfobj} + \item \cs{parafcn}, \pageref{parafcn} + \item \cs{periodicfcnspline}, \pageref{fcnspline} + \item \cs{piewedge}, \pageref{piewedge} + \item \cs{plrfcn}, \pageref{plrfcn} + \item \cs{plrregion}, \pageref{belowfcn} + \item \cs{polygon}, \pageref{polygon} + \item \cs{polyline}, \pageref{polyline} + \item \cs{pshcircle}, \pageref{pshcircle} + \item \cs{qbeziers}, \cs{closedqbeziers}, \pageref{qbeziers} + \item \cs{qspline}, \cs{closedqspline}, \pageref{qspline} + \item \cs{rect}, \pageref{rect} + \item \cs{regpolygon}, \pageref{regpolygon} + \item \cs{sector}, \pageref{sector} + \item \cs{tlabelcircle}, \pageref{tlabelellipse} + \item \cs{tlabelellipse}, \pageref{tlabelellipse} + \item \cs{tlabeloval}, \pageref{tlabeloval} + \item \cs{tlabelrect}, \pageref{tlabelrect} + \item \cs{turtle}, \pageref{turtle} + +\subsection{Macros that render} + + \item \cs{corkscrew}, \pageref{corkscrew} + \item \cs{dashed}, \pageref{dashed} + \item \cs{dotted}, \pageref{dotted} + \item \cs{doubledraw}, \pageref{doubledraw} + \item \cs{draw}, \pageref{draw} + \item \cs{gclear}, \pageref{gclear} + \item \cs{gclip}, \pageref{gclip} + \item \cs{gendashed}, \pageref{gendashed} + \item \cs{gfill}, \pageref{gfill} + \item \cs{hatch}, \pageref{hatch} + \item \cs{lhatch}, \pageref{hatch} + \item \cs{plot}, \pageref{plot} + \item \cs{plotdata}, \pageref{plotdata} + \item \cs{plotnodes}, \pageref{plotnodes} + \item \cs{polkadot}, \pageref{polkadot} + \item \cs{rhatch}, \pageref{hatch} + \item \cs{sinewave}, \pageref{zigzag} + \item \cs{shade}, \pageref{shade} + \item \cs{tess}, \pageref{tess} + \item \cs{thatch}, \pageref{thatch} + \item \cs{xhatch}, \pageref{hatch} + \item \cs{zigzag}, \pageref{zigzag} + +\subsection{Macros that append (arrows)} + + \item \cs{arrow}, \pageref{arrow} + \item \cs{arrowhead}, \pageref{arrowhead} + \item \cs{arrowmid}, \pageref{arrowhead} + \item \cs{arrowtail}, \pageref{arrowhead} + +\subsection{Macros that modify} + + \item \cs{bclosed}, \pageref{lclosed} + \item \cs{cbclosed}, \pageref{cbclosed} + \item \cs{connect}, \cs{endconnect}, \pageref{connect} + \item \cs{cutoffafter}, \pageref{cutoffafter} + \item \cs{cutoffbefore}, \pageref{cutoffafter} + \item \cs{lclosed}, \pageref{lclosed} + \item \cs{makesector}, \pageref{makesector} + \item \cs{parallelpath}, \pageref{parallelpath} + \item \cs{partpath}, \pageref{partpath} + \item \cs{qbclosed}, \pageref{cbclosed} + \item \cs{randomizepath}, \pageref{random} + \item \cs{randomlines}, \pageref{random} + \item \cs{reflectpath}, \pageref{shiftpath} + \item \cs{reverse}, \pageref{reverse} + \item \cs{rotatepath}, \pageref{shiftpath} + \item \cs{scalepath}, \pageref{shiftpath} + \item \cs{sclosed}, \pageref{lclosed} + \item \cs{shiftpath}, \pageref{shiftpath} + \item \cs{slantpath}, \pageref{shiftpath} + \item \cs{subpath}, \pageref{partpath} + \item \cs{transformpath}, \pageref{shiftpath} + \item \cs{trimpath}, \pageref{partpath} + \item \cs{xscalepath}, \pageref{shiftpath} + \item \cs{xslantpath}, \pageref{shiftpath} + \item \cs{xyswappath}, \pageref{shiftpath} + \item \cs{yscalepath}, \pageref{shiftpath} + \item \cs{yslantpath}, \pageref{shiftpath} + +\subsection{Lengths} + + \item \cs{axisheadlen}, \pageref{axisheadlen} + \item \cs{dashlen}, \pageref{dashlen} + \item \cs{dotsize}, \pageref{dotsize} + \item \cs{dotspace}, \pageref{dotsize} + \item \cs{griddotsize}, \pageref{griddotsize} + \item \cs{hashlen}, \pageref{hashlen} + \item \cs{hatchspace}, \pageref{hatchspace} + \item \cs{headlen}, \pageref{headlen} + \item \cs{mfpiccaptionskip}, \pageref{mfpiccaptionskip} + \item \cs{mfpicheight}, \pageref{mfpicheight} + \item \cs{mfpicunit}, \pageref{mfpicunit} + \item \cs{mfpicwidth}, \pageref{mfpicheight} + \item \cs{pointsize}, \pageref{pointsize} + \item \cs{polkadotspace}, \pageref{polkadotspace} + \item \cs{shadespace}, \pageref{shadespace} + \item \cs{sideheadlen}, \pageref{sideheadlen} + \item \cs{symbolspace}, \pageref{symbolspace} + +\subsection{Coordinate transformation} + + \item \cs{applyT}, \pageref{applyT} + \item \cs{boost}, \pageref{applyT} + \item \cs{coords}, \cs{endcoords}, \pageref{coords} + \item \cs{mirror}, \pageref{applyT} + \item \cs{reflectabout}, \pageref{applyT} + \item \cs{rotate}, \pageref{applyT} + \item \cs{rotatearound}, \pageref{applyT} + \item \cs{scale}, \pageref{applyT} + \item \cs{shift}, \pageref{applyT} + \item \cs{turn}, \pageref{applyT} + \item \cs{xscale}, \pageref{applyT} + \item \cs{xslant}, \pageref{applyT} + \item \cs{xyswap}, \pageref{applyT} + \item \cs{yscale}, \pageref{applyT} + \item \cs{yslant}, \pageref{applyT} + \item \cs{zscale}, \pageref{applyT} + \item \cs{zslant}, \pageref{applyT} + +\subsection{Symbols, axes, grids, marks} + + \item \cs{axes}, \pageref{axes} + \item \cs{axis}, \pageref{axis} + \item \cs{axismarks}, \pageref{axismarks} + \item \cs{bmarks}, \pageref{axismarks} + \item \cs{doaxes}, \pageref{axis} + \item \cs{grid}, \pageref{grid} + \item \cs{gridarcs}, \pageref{plrgrid} + \item \cs{gridlines}, \pageref{grid} + \item \cs{gridpoints}, \pageref{grid} + \item \cs{gridrays}, \pageref{plrgrid} + \item \cs{hgridlines}, \pageref{grid} + \item \cs{lattice}, \pageref{grid} + \item \cs{lmarks}, \pageref{axismarks} + \item \cs{plotsymbol}, \pageref{plotsymbol} + \item \cs{plrgridpoints}, \pageref{plrgrid} + \item \cs{plrgrid}, \pageref{plrgrid} + \item \cs{plrpatch}, \pageref{plrgrid} + \item \cs{plrvectorfield}, \pageref{vectorfield} + \item \cs{point}, \pageref{point} + \item \cs{putmfpimage}, \pageref{putmfpimage} + \item \cs{rmarks}, \pageref{axismarks} + \item \cs{tmarks}, \pageref{axismarks} + \item \cs{vectorfield}, \pageref{vectorfield} + \item \cs{vgridlines}, \pageref{grid} + \item \cs{xaxis}, \pageref{axes} + \item \cs{xmarks}, \pageref{axismarks} + \item \cs{yaxis}, \pageref{axes} + \item \cs{ymarks}, \pageref{axismarks} + +\subsection{Symbol names} + + \item \gbc{Arrowhead}, \pageref{arrowhead} + \item \gbc{Asterisk}, \pageref{plotsymbol} + \item \gbc{Circle}, \pageref{plotsymbol} + \item \gbc{Crossbar}, \pageref{arrowhead} + \item \gbc{Cross}, \pageref{plotsymbol} + \item \gbc{Diamond}, \pageref{plotsymbol} + \item \gbc{Leftbar}, \pageref{arrowhead} + \item \gbc{Leftharpoon}, \pageref{arrowhead} + \item \gbc{Lefthook}, \pageref{arrowhead} + \item \gbc{Plus}, \pageref{plotsymbol} + \item \gbc{Rightbar}, \pageref{arrowhead} + \item \gbc{Rightharpoon}, \pageref{arrowhead} + \item \gbc{Righthook}, \pageref{arrowhead} + \item \gbc{SolidCircle}, \pageref{plotsymbol} + \item \gbc{SolidDiamond}, \pageref{plotsymbol} + \item \gbc{SolidSquare}, \pageref{plotsymbol} + \item \gbc{SolidStar}, \pageref{plotsymbol} + \item \gbc{SolidTriangle}, \pageref{plotsymbol} + \item \gbc{Square}, \pageref{plotsymbol} + \item \gbc{Star}, \pageref{plotsymbol} + \item \gbc{Triangle}, \pageref{plotsymbol} + +\subsection{Setting options} + + \item \cs{clearsymbols}, \pageref{clearsymbols} + \item \cs{clipmfpic}, \pageref{clip} + \item \cs{mfpicdebugfalse}, \pageref{debug} + \item \cs{mfpicdebugtrue}, \pageref{debug} + \item \cs{mfpicdraft}, \pageref{draft} + \item \cs{mfpicfinal}, \pageref{draft} + \item \cs{mfpicnowrite}, \pageref{draft} + \item \cs{mfpreadlog}, \pageref{readlog} + \item \cs{nocenteredcaptions}, \pageref{centeredcaptions} + \item \cs{noclearsymbols}, \pageref{clearsymbols} + \item \cs{noclipmfpic}, \pageref{clip} + \item \cs{nomplabels}, \pageref{mplabels} + \item \cs{nooverlaylabels}, \pageref{overlaylabels} + \item \cs{noraggedcaptions}, \pageref{raggedcaptions} + \item \cs{notruebbox}, \pageref{truebbox} + \item \cs{overlaylabels}, \pageref{overlaylabels} + \item \cs{usecenteredcaptions}, \pageref{centeredcaptions} + \item \cs{usemetafont}, \pageref{metapost} + \item \cs{usemetapost}, \pageref{metapost} + \item \cs{usemplabels}, \pageref{mplabels} + \item \cs{useraggedcaptions}, \pageref{raggedcaptions} + \item \cs{usetruebbox}, \pageref{truebbox} + +\subsection{Setting values} + + \item \cs{axismargin}, \pageref{axismargin} + \item \cs{darkershade}, \pageref{darkershade} + \item \cs{dashlineset}, \pageref{dashlineset} + \item \cs{dashpattern}, \pageref{dashpattern} + \item \cs{dotlineset}, \pageref{dashlineset} + \item \cs{drawpen}, \pageref{drawpen} + \item \cs{globalsetmfvariable}, \pageref{setmfvariable} + \item \cs{hatchwd}, \pageref{hatchwd} + \item \cs{headshape}, \pageref{headshape} + \item \cs{lightershade}, \pageref{darkershade} + \item \cs{mfpicnumber}, \pageref{mfpicnumber} + \item \cs{mfplinestyle}, \pageref{mfplinetype} + \item \cs{mfplinetype}, \pageref{mfplinetype} + \item \cs{pen}, \pageref{drawpen} + \item \cs{penwd}, \pageref{drawpen} + \item \cs{polkadotwd}, \pageref{polkadotwd} + \item \cs{setallaxismargins}, \pageref{axismargin} + \item \cs{setallbordermarks}, \pageref{setaxismarks} + \item \cs{setaxismargins}, \pageref{axismargin} + \item \cs{setaxismarks}, \pageref{setaxismarks} + \item \cs{setbordermarks}, \pageref{setaxismarks} + \item \cs{setmfboolean}, \pageref{setmfvariable} + \item \cs{setmfcolor}, \pageref{setmfvariable} + \item \cs{setmfnumeric}, \pageref{setmfvariable} + \item \cs{setmfpair}, \pageref{setmfvariable} + \item \cs{setmfvariable}, \pageref{setmfvariable} + \item \cs{settension}, \pageref{settension} + \item \cs{setxmarks}, \pageref{setaxismarks} + \item \cs{setymarks}, \pageref{setaxismarks} + \item \cs{shadewd}, \pageref{shadewd} + +\subsection{Changing colors} + + \item \cs{backgroundcolor}, \pageref{drawcolor} + \item \cs{drawcolor}, \pageref{drawcolor} + \item \cs{fillcolor}, \pageref{drawcolor} + \item \cs{hatchcolor}, \pageref{drawcolor} + \item \cs{headcolor}, \pageref{drawcolor} + \item \cs{mfpdefinecolor}, \pageref{mfpdefinecolor} + \item \cs{pointcolor}, \pageref{drawcolor} + \item \cs{tlabelcolor}, \pageref{drawcolor} + +\subsection{Defining arrays} + + \item \cs{barchart}, \pageref{barchart} + \item \cs{bargraph}, \pageref{barchart} + \item \cs{colorarray}, \pageref{setarray} + \item \cs{gantt}, \pageref{barchart} + \item \cs{globalsetarray}, \pageref{setarray} + \item \cs{histogram}, \pageref{barchart} + \item \cs{mfpbarchart}, \pageref{barchart} + \item \cs{mfpbargraph}, \pageref{barchart} + \item \cs{mfpgantt}, \pageref{barchart} + \item \cs{mfphistogram}, \pageref{barchart} + \item \cs{mfppiechart}, \pageref{piechart} + \item \cs{numericarray}, \pageref{setarray} + \item \cs{pairarray}, \pageref{setarray} + \item \cs{patharr}, \cs{endpatharr}, \pageref{patharr} + \item \cs{piechart}, \pageref{piechart} + \item \cs{setarray}, \pageref{setarray} + +\subsection{Changing behavior} + + \item \cs{coloredlines}, \pageref{coloredlines} + \item \cs{dashedlines}, \pageref{coloredlines} + \item \cs{datapointsonly}, \pageref{coloredlines} + \item \cs{defaultplot}, \pageref{defaultplot} + \item \cs{everytlabel}, \pageref{everytlabel} + \item \cs{everymfpic}, \cs{everyendmfpic}, \pageref{everymfpic} + \item \cs{makepercentcomment}, \pageref{makepercentother} + \item \cs{makepercentother}, \pageref{makepercentother} + \item \cs{mfpdatacomment}, \pageref{mfpdatacomment} + \item \cs{mfpdataperline}, \pageref{mfpdataperline} + \item \cs{mfpverbtex}, \pageref{mfpverbtex} + \item \cs{noship}, \pageref{noship} + \item \cs{pointedlines}, \pageref{coloredlines} + \item \cs{pointfillfalse}, \cs{pointfilltrue}, \pageref{pointfilltrue} + \item \cs{reconfigureplot}, \pageref{reconfigureplot} + \item \cs{resumeshipping}, \pageref{noship} + \item \cs{setrender}, \pageref{setrender} + \item \cs{smoothdata}, \pageref{datafile} + \item \cs{stopshipping}, \pageref{noship} + \item \cs{tlabeljustify}, \pageref{tlabeljustify} + \item \cs{tlabeloffset}, \pageref{tlabeloffset} + \item \cs{tlabelsep}, \pageref{tlabeloffset} + \item \cs{tlpathjustify}, \pageref{tlpathjustify} + \item \cs{tlpathsep}, \pageref{tlabeloffset} + \item \cs{tlpointsep}, \pageref{tlabeloffset} + \item \cs{unsmoothdata}, \pageref{datafile} + \item \cs{using}, \pageref{using} + \item \cs{usingnumericdefault}, \pageref{usingpairdefault} + \item \cs{usingpairdefault}, \pageref{usingpairdefault} + +\subsection{Files and environments} + + \item \cs{closegraphsfile}, \pageref{opengraphsfile} + \item \cs{mfpframe}, \cs{endmfpframe}, \pageref{mfpframe} + \item \cs{mfpic}, \cs{endmfpic}, \pageref{mfpic} + \item \cs{opengraphsfile}, \pageref{opengraphsfile} + \item \cs{setfilename}, \pageref{setfilename} + \item \cs{setfilenametemplate}, \pageref{setfilenametemplate} + +\subsection{Text} + + \item \cs{axislabels}, \pageref{axislabels} + \item \cs{plottext}, \pageref{plottext} + \item \cs{startbacktext}, \pageref{backtext} + \item \cs{stopbacktext}, \pageref{backtext} + \item \cs{tcaption}, \pageref{tcaption} + \item \cs{tlabel}, \pageref{tlabel} + \item \cs{tlabels}, \pageref{tlabel} + +\subsection{Misc} + + \item \cs{assignmfvalue}, \cs{assignmpvalue}, \pageref{assignmfvalue} + \item \cs{fdef}, \pageref{fdef} + \item \cs{getmfpicoffset}, \pageref{getmfpicoffset} + \item \cs{globalassignmfvalue},\\ + \cs{globalassignmpvalue}, \pageref{assignmfvalue} + \item \cs{ifmfpmpost}, \pageref{ifmfpmpost} + \item \cs{mfcmd}, \pageref{mfsrc} + \item \cs{mflist}, \pageref{mfsrc} + \item \cs{mfmode}, \pageref{mfmode} + \item \cs{mfpfor}, \cs{endmfpfor}, \pageref{mfpfor} + \item \cs{mfpframed}, \pageref{mfpframe} + \item \cs{mfpicversion}, \pageref{mfpicversion} + \item \cs{mfpimage}, \cs{endmfpimage}, \pageref{mfpimage} + \item \cs{mfploop}, \cs{endmfploop}, \pageref{mfploop} + \item \cs{mfpuntil}, \pageref{mfploop} + \item \cs{mfpwhile}, \cs{endmfpwhile}, \pageref{mfpwhile} + \item \cs{mfresolution}, \pageref{mfmode} + \item \cs{mfsrc}, \pageref{mfsrc} + \item \cs{mftitle}, \pageref{mftitle} + \item \cs{newfdim}, \pageref{newfdim} + \item \cs{newsavepic}, \pageref{newsavepic} + \item \cs{plr}, \pageref{plr} + \item \cs{pointdef}, \pageref{pointdef} + \item \cs{preparemfpicgraphic}, \pageref{preparemfpicgraphic} + \item \cs{savepic}, \pageref{newsavepic} + \item \cs{sequence}, \pageref{sequence} + \item \cs{setmfpicgraphic}, \pageref{setmfpicgraphic} + \item \cs{store}, \pageref{store} + \item \cs{tile}, \cs{endtile}, \pageref{tile} + \item \cs{tmtitle}, \pageref{tmtitle} + \item \cs{usepic}, \pageref{newsavepic} + + +\end{document} + |