diff options
Diffstat (limited to 'Master/texmf-dist/doc/generic/mfpic/mfpman.tex')
-rw-r--r-- | Master/texmf-dist/doc/generic/mfpic/mfpman.tex | 4991 |
1 files changed, 4991 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/generic/mfpic/mfpman.tex b/Master/texmf-dist/doc/generic/mfpic/mfpman.tex new file mode 100644 index 00000000000..7f93ed20e27 --- /dev/null +++ b/Master/texmf-dist/doc/generic/mfpic/mfpman.tex @@ -0,0 +1,4991 @@ +%%% File: mfpman.tex +%%% A part of mfpic 0.7a beta 2004/04/16 +%%% +% Documentation of mfpic macros +\documentclass[letterpaper]{article} + +\usepackage{pslatex} + +\usepackage{mfpdoc} +\pagestyle{mfpdoc} +\usepackage{verbatim} +\usepackage{makeidx} +\makeindex + +\ifpdf +\usepackage[pdftex,colorlinks,pdfpagemode=none,pdfstartview=FitH,% +plainpages=false,hypertexnames=true]{hyperref} +\pdfstringdefDisableCommands{\def\cs#1{\otherbackslash#1}% + \def\opt#1{#1}\def\prog#1{#1}} +\fi + +\title{\Mfp: Pictures in \TeX\\ with Metafont and MetaPost} +\author{Dr Thomas E. Leathrum +\and Geoffrey Tobin\thanks{\email{G.Tobin@latrobe.edu.au}} +\and Daniel H. Luecking\thanks{\email {luecking@uark.edu}}} +\date{\mfpdate} + +\begin{document} + +\pagenumbering{roman} +\maketitle +\tableofcontents + +\clearpage +\pagenumbering{arabic} + +\section{Introduction}\label{introduction} + +\subsection{Why?}\label{why} + +Tom got the idea for \mfp% + \footnote{If you're wondering how to pronounce `\mfp': I always say + `em-eff-\textbf{pick}', speaking the first two letters. ---DHL.} % +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 is wonderfully flexible and general, +but its most obvious feature was its speed---or rather lack of it. +Processing a single picture in \PiCTeX{} 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 is \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 does +not get along well with PK fonts, but is quite happy with \MP{} +pictures. Unfortunately \file{grafbase.mf}, which contained the \MF{} +macros responsible for processing \mfp's output, was far too +pixel-oriented for \MP. A new file, \file{grafbase.mp} was created, +based very heavily on \file{grafbase.mf} but compatible with \MP. Now +when an \mfp{} output file says \mfc{input grafbase}, either \MF{} or +\MP{} may be run on it, and each program will select its own macros, and +produce (nearly) the same picture. This gets us away from device +independence, but many users were not so much concerned with that as +with having a convenient way to have text and pictures described in the +same document. + +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. + +\subsection{Who?}\label{author} + +\Mfp{} 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. + +\subsection{What?}\label{manifest} + +See \file{README.txt} for a list and a brief explanation of each of +the files. Only five are actually needed for full access to +\mfp's capabilities: \file{mfpic.tex}, \file{mfpic.sty} (the +latter needed only for \LaTeX's \cs{usepackage}), \file{grafbase.mf} +(needed only if \MF{} will be processing the figures), +\file{grafbase.mp} and \file{dvipsnam.mp} (needed only if \MP{} will be +the processor). + +The readme file that accompanies \mfp{} gives some guidence on the +proper location for the installation of these files. + +\subsection{How?}\label{process} + +Setting up \TeX{} and \MF{} to process these files will, to an extent, +depend on your local installation. The biggest problem you are likely to +have, regardless of your installation, will be convincing \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 driver/viewer looks +in the current directory for \file{.pk} files. If you process your +pictures with \MP{} there is nothing to do in this regard. + +Here is an example of the process: for the sample file +\file{pictures.tex}% + \footnote{Read \file{mfpguide.pdf} for examples of minimal \mfp{} + input files.}, % +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.tfm}, but +\TeX{} will continue processing the file anyway. 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 +\cs{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 \hbox{Geoffrey Tobin}, is a good + start. Fetch \file{CTAN/info/metafont-for-beginners.tex}. + `\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} + 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 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}). You can delete \file{pics.600gf} and +\file{pics.log}. + +If you use \mfp{} with the \opt{metapost} option (this would require you +to edit \file{pictures.tex} or \file{lapictures.tex}. See +chapter~\ref{options} for how to do this), then \file{pics.mp} is +produced, and you need to replace the \MF/\prog{gftopk} steps with the +single step of running \MP. (Read your \MP{} documentation on 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}.}) % +Typically just +\begin{verbatim} + mpost pics.mp +\end{verbatim} +or possibly \ \verb$mp pics.mp$ . + +After reprocessing \file{pictures.tex} with \TeX{} you should then be +able to run dvips on the resulting DVI file and print or view its \PS{} +output. It \pdfTeX{} is used instead of \TeX{} on the second run, you +should be able to view the resulting PDF file with the pictures +included. + +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}, +as \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 +unpredictable places) before you can see any later changes. It might +be wise to write a shell script (batch file) that (1)~runs \MF, (2)~runs +\prog{gftopk} if step~1 returns no error, (3)~deletes the \file{.tfm} if +the \file{.pk} file does not exist. 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/\prog{gftopk}, 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 file that has gone through the above +process. Listing the exact cirumstances is rather involved, so it is +recommended that you always repeat the \TeX{} step if changes have been +made. + +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 \MF{} file, that \mfp{} drawing macros translate almost +directly into similar \MF/\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 \MP{} places the labels). + + +\clearpage +\section{Options.}\label{options} + +There are now several options to the \mfp{} package. These can be listed +in the standard \LaTeX{} \cs{usepackage} optional argument, or can be +turned on with certain provided commands (the only possibility for plain +\TeX). 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 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 the file \file{mfpic.usr} exists, 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. + +\subsection{\opt{metapost}, \cs{usemetapost}}\label{metapost} +\index{metapost@\opt{metapost}}\index{usemetapost@\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. 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. + + +\subsection{\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 has no effect on the \cs{tcaption} command. 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). It may also produce an +error either from \TeX{} or \MF. Otherwise the commands can come +anywhere and affect subsequent \cs{tlabel} commands. 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, by setting the environmental variable +\texttt{TEX} to \texttt{latex} in the command shell of your operating +system.). + + +\subsection{\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 this version 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}. + + +\subsection{\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. + + +\subsection{\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 box specified in the \cs{mfpic} command. It is +possible that the actual figure will be much smaller (even empty!). This +is a property of the \MP{} \gbc{clip} command and we know of no way to +avoid it. + + +\subsection{\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. + +\subsection{\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. + +\subsection{\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 until now was always simply to 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. + + +\subsection{\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 should come \emph{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. + + +\subsection{Option 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. However, as of this writing I don't +claim to have caught every one. + +The following are special: +\cs{usemetapost}\index{usemetapost@\cs{usemetapost}}, +\cs{usemetafont}\index{usemetafont@\cs{usemetafont}}, +\cs{mfpicdraft}\index{mfpicdraft@\cs{mfpicdraft}}, +\cs{mfpicfinal}\index{mfpicfinal@\cs{mfpicfinal}}, +and +\cs{mfpicnowrite}\index{mfpicnowrite@\cs{mfpicnowrite}}. +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 +\section{The Macros.}\label{macros} + +In these descriptions 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 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: \LaTeX, \pdfTeX, \pdfLaTeX, etc. + +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{ex} + \cs{circle}\marg{(0,0),1} +\end{ex} +having only the mandatory argument, or +\begin{ex} + \cs{circle}\oarg{p}\marg{(0,0),1} +\end{ex} +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 that \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 request 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}}. + +Optional arguments for \mfp{} commands may consist of empty brackets +(completely empty, no spaces) and the default will be used. This is +useful only for commands that have two optional arguments and one only +wants to change from the defaults in the second one. 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 many cases (perhaps most) this will cause no harm, but it +would be better to avoid doing it altogether. + + +\subsection{Files and Environments.}\label{files} + +\begin{cd} +\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 will 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. + +\begin{cd} +\cs{mfpic}\oarg{\meta{xscale}}\oarg{\meta{yscale}}% + \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 in which most of +the rest of the macros make sense. The \cs{mfpic} macro also sets up the +local coordinate system for the picture. The \meta{xscale} and +\meta{yscale} 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 (i.e., each coordinate system unit +is 1 \cs{mfpicunit}). If only one is specified, then they are assumed to +be equal. 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{xscale}$ times +\cs{mfpicunit}, its height $(\meta{ymax}-\meta{ymin})\cdot\meta{yscale}$ +times \cs{mfpicunit}, and its depth zero. One can scale all pictures +uniformly by changing \cs{mfpicunit}, and scale an individual picture by +changing \meta{xscale} and \meta{yscale}. 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 certain parameters +that are defined in absolute units. Examples of these are the default +width of the drawing pen, the default lengths of arrowheads, the default +sizes of dashes and dots, etc. If you wish, you can set these to +multiples of \cs{mfpicunit}, but it is difficult (and probably unwise) +to get them 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. + +\begin{cd} +\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} +\cs{begin}\marg{mfpic}\texttt{...}\cs{end}\marg{mfpic}% +\index{begin@\cs{begin}\marg{mfpic}} +\end{cd} + +In \LaTeX, instead of \cs{mfpic} and \cs{endmfpic}, you may prefer to +use \cs{begin}\marg{mfpic} and \cs{end}\marg{mfpic}. This is by no means +required: in \LaTeX{} \cs{begin}\marg{command} invokes \cs{command}, and +\cs{end}\marg{command} invokes \cs{endcommand}, for any environment +\env{command}. + +The sample file \file{lapictures.tex} provided with \mfp{} +illustrates this use of an \env{mfpic} environment in \LaTeX. + +\medskip +The rest of the \mfp{} macros do not affect the font metric file +(\file{\meta{file}.tfm}), and so if these commands are changed or added +in your document, you will not have to repeat the third step of +processing (reprocessing with \TeX) to complete your \TeX{} document. +The same is true when option \opt{metapost} is selected without the +\opt{truebbox} option, except under \pdfTeX{} or \pdfLaTeX. Those \TeX{} +programs will embed the figures right in the \file{.pdf} output. For +normal \LaTeX{} + \prog{dvips}, the figures are embedded by +\prog{dvips}, which must always be repeated. + +\medskip +For the remainder of the macros, the numerical parameters are expressed +in the units of the local coordinate system specified by \cs{mfpic}, +unless otherwise indicated. + + +\subsection{Figures.}\label{figures} + +\subsubsection{\CMF{} Pairs.}\label{pairs} + +Since many of the arguments of the \mfp{} drawing commands are +sent to \MF{} to be interpreted, it's useful to know something about +\MF{} concepts. + +In particular, \MF{} has \mfc{pair} objects, which may be constants or +variables. Pair constants have the form \mfc{($x$,$y$)}. Pairs are +two-dimensional rectangular (cartesian) quantities, and are clearly +useful for representing both points and vectors on the plane. + +Moreover, we herein often represent each pair by a brief name, such as +$p$, $v$ or $c$, the meanings of which are usually obvious in the +context of the macro. The succinctness of this notation also helps us to +think geometrically rather than only of coordinates. + +\CMP{} has these same concepts, but also has color objects, which may +also be constants or variables. Color constants 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 (rgb model). A color variable is a name, like \mfc{magenta} or +\mfc{RoyalBlue} (predefined). There are also color functions like +\mfc{cmyk($x$,$y$,$z$,$w$)} which is defined to convert cmyk values into +\MP's native rgb model. + +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. +When \MP{} output is selected, figures can be drawn in any color. +Several of the above mentioned parameters are colors. \Mfp{} provides +commands to change any of these parameters. + + +\subsubsection{Points, Lines, and Rectangles.}\label{points} + +\begin{cd} +\cs{pointdef}\marg{\meta{name}}\texttt{($x$,$y$)}% +\index{pointdef@\cs{pointdef}} +\end{cd} + +Defines a symbolic name for points and their coordinates. \meta{name} is +any legal \TeX{} command name \emph{without} the backslash; $x$ and $y$ +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. Because +of the way \cs{tlabel} is defined (see section~\ref{labels} below), one +cannot use \cs{A} to specify where to place a label (unless +\opt{mplabels} is in effect), but must use \texttt{ (\cs{Ax},\cs{Ay})}. In +most other commands, one can use \cs{A} where a pair or point is +required. + +\begin{cd} +\cs{point}\oarg{\meta{ptsize}}\marg{\meta{$p_0$},\meta{$p_1$},$\ldots$}% +\index{point@\cs{point}} +\end{cd} + +Draws small disks centered at the points \meta{$p_0$}, \meta{$p_1$}, and +so on. If the optional argument \meta{ptsize} is present, it determines +the diameter of the disks, which otherwise equals the \TeX{} dimension +\cs{pointsize}, initially \dim{2pt}. The disks have a filled interior if +the command \cs{pointfilltrue} has been issued (the initial value), +\cs{pointfillfalse} causes the interior to be erased and an outline +drawn. The color of the circles is the value of the predefined variable +\gbc{pointcolor}, and the inside of the open circles is the value of +\mfc{background}. + +\begin{cd} +\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 +\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}}. +The names should be self-explanatory. 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 closed, ten-sided +polygon. The name `\cs{plotsymbol}' comes from the fact that the \cs{plot} +command, which was written first, utilizes these same symbols. The command +\cs{symbol} was already taken (standard \LaTeX). + +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 (i.e., 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} +\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. + +\begin{cd} +\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} + +Draws the line segment with endpoints at \meta{$p_0$} and \meta{$p_1$}, +then the line segment with endpoints at \meta{$p_1$} and \meta{$p_2$}, +etc. The result is an open polygonal path through the specified points, +in the specified order. \cs{polyline} and \cs{lines} mean the same +thing. + +\begin{cd} +\cs{polygon}\marg{\meta{$p_0$},\meta{$p_1$},$\ldots$}% +\index{polygon@\cs{polygon}} +\end{cd} + +Draws a closed polygon with vertices at the specified points in the +specified order. + +\begin{cd} +\cs{rect}\marg{\meta{$p_0$},\meta{$p_1$}}% +\index{rect@\cs{rect}} +\end{cd} + +Draws the rectangle specified by the points \meta{$p_0$} and +\meta{$p_1$}, these being either pair of opposite corners of the +rectangle in any order. + +It is occasionally helpful to know that connected paths like those +produced by \cs{polyline} or \cs{rect} have a \emph{sense} (a +direction). The sense of \cs{polyline} is 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 begins at the first of +the two points and goes horizontally from there. + +\begin{cd} +\cs{regpolygon}\marg{\meta{num}}\marg{\meta{name}}% +\marg{\meta{eqn$_1$}}\marg{\meta{eqn$_2$}}% +\index{regpolygon@\cs{regpolygon}} +\end{cd} + +This produces a 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 refered +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) will be a \MF{} variable assigned +the value of \meta{num}. For example, +\begin{ex} +\cs{regpolygon}\marg{5}\marg{Meg}\marg{Meg0=(0,1)}\marg{Meg1=(2,0)} +\end{ex} +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{ex} +\cs{polygon}\marg{Meg1,Meg3,Meg5,Meg2,Meg4} +\end{ex} +Moreover, \gbc{Meg} 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. + +\subsubsection{A Word on List Arguments}\label{list} + +We have seen already four \mfp{} macros that take a mandatory argument +consisting of a list of coordinate pairs. There are many more, and some +that take a comma-separated lists of other types of items. 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{lines}\marg{\meta{list}}, one can write\index{datafile@\cs{datafile}} +\begin{ex} +\cs{lines}\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 as its last argument, +\emph{with the exception of those commands that adds text to the +picture}. Examples of the latter are \cs{plottext} and \cs{axislabels} +(subsection~\ref{text}). + +\subsubsection{Axes, Axis Marks, and Grids.}\label{axes} + +\begin{cd} +\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 the prefix macros of sections \ref{modifier}~and \ref{rendering}. +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} +\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 changes made by +\cs{setrender} (see subsection~\ref{default}). Moreover, prefix macros +may be applied to \cs{axis} without error (see sections +\ref{modifier}~and \ref{rendering}): \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. + +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{doaxis}, 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} +\cs{axismargin}\marg{\meta{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 \meta{axis} is one of the letters \texttt{l}, \texttt{b}, \texttt{r}, or \texttt{ +t}. \cs{axismargin} causes the given axis to be shifted \emph{inward} by +the \meta{num} specified (in \emph{graph} coordinates). 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 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. + +\begin{cd} +\cs{xmarks}\oarg{\meta{len}}\marg{\meta{numberlist}}\\ +\cs{tmarks}\oarg{\meta{len}}\marg{\meta{numberlist}}\\ +\cs{bmarks}\oarg{\meta{len}}\marg{\meta{numberlist}}\\ +\cs{ymarks}\oarg{\meta{len}}\marg{\meta{numberlist}}\\ +\cs{lmarks}\oarg{\meta{len}}\marg{\meta{numberlist}}\\ +\cs{rmarks}\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 \cs{marks}, but e\kern-.16em\TeX{} makes that a primitive.) + +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{ex} + \cs{xmarks}\marg{-2 step 1 until 2} +\end{ex} +is the equivalent of +\begin{ex} + \cs{xmarks}\marg{-2,-1,0,1,2} +\end{ex} + +One must use exactly the words \mfc{step} and \mfc{until}. There must be +spaces between, but 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}} % +Users should be aware that if any of the numbers are non-integral then +due to natural round-off effects, the last value might be overshot and a +mark not printed there. + +\begin{cd} +\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} are considered to be +equivalent, as are \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 defined in the file \file{grafbase.mf}, and the +variables \gbc{ontop} and \gbc{onleft}, for example, are given the same +value. + +\begin{cd} +\cs{grid}\oarg{\meta{ptsize}}\marg{\meta{xsep},\meta{ysep}}\\ +\cs{gridpoints}\oarg{\meta{ptsize}}\marg{\meta{xsep},\meta{ysep}}\\ +\cs{lattice}\oarg{\meta{ptsize}}\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{ptsize}. The default is \dim{.5bp} and is hard coded in the +\MF{} macros that ultimately do the drawing. 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 grids. Or omit them entirely: well-designed graphs +usually don't need them and almost never should both horizontals and +verticals be used. + +\begin{cd} +\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}\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 at all the places the rays and arcs +would intersect. + +The arcs are centered at $(0,0)$ and the lines emanate from $(0,0)$ +(even if $(0,0)$ is not in the graph space). The corresponding \MF{} +commands actually draw enough to cover the graph area and then clip them +to the graph boundaries. If you don't want them clipped, use +\cs{plrpatch}. + +\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 \cs{gridlines} holds for \cs{plrgrid} +as well. + + +\subsubsection{Circles and Ellipses.}\label{circles} + +\begin{cd} +\cs{circle}\oarg{\meta{format}}\marg{\meta{specification}}% +\index{circle@\cs{circle}}% +\end{cd} + +Draws a circle. Starting with \mfp{} version 0.7, there are 4 +different ways to specify a circle, so \cs{circle} can be given an +optional argument that determines what data is 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$}}% +\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 $c$ and radius $r$ of the +circle. + +\item[\oarg{c}] The \textit{Center-point form}. In this case the data +should be the center and one point on the circumference. + +\item[\oarg{t}] The \textit{Three-point form}. The data are three points +that do not lie in a straight line. + +\item[\oarg{s}] The \textit{point-sweep}. The data are two points on the +circle, followed by the angle of arc between them. +\end{description} +These optional arguments are also used in the \cs{arc} command (see +subsection~\ref{arcs}). The \cs{circle} command draws the whole circle +which the equivalent \cs{arc} command draws only part of. The sense of +the circle produced is anticlockwise except in the case \texttt{[t]}, +where it is the direction determined by the order of the three points, +and the case \texttt{[s]}, where it is determined by \meta{$\theta$}: +clockwise if negative, anticlockwise if positive. + + +\begin{cd} +\cs{ellipse}\oarg{\meta{$\theta$}}\marg{\meta{$c$},\meta{$r_x$},\meta{$r_y$}}% +\index{ellipse@\cs{ellipse}}% +\end{cd} + +Draws 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. + + +\subsubsection{Curves.}\label{curves} + +\begin{cd} +\cs{curve}\oarg{\meta{tension}}\marg{\meta{$p_0$},\meta{$p_1$},$\ldots$}% +\index{curve@\cs{curve}}% +\end{cd} + +Draws 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 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} +\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. + +\begin{cd} +\cs{cyclic}\oarg{\meta{tension}}\marg{\meta{$p_0$},\meta{$p_1$},$\ldots$}% +\index{cyclic@\cs{cyclic}}% +\end{cd} + +Draws a cyclic (i.e., closed) \MF{} B\'ezier curve through the specified +points, in the specified order. It uses the same procedure as +\cs{curve}, but treats the first listed point as having the last as its +predecessor and the last point has the first as its successor. The +\meta{tension} is as in the \cs{curve} command. + +\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} +\cs{fcncurve}\oarg{\meta{tension}}\marg{($x_0$,$y_0$),($x_1$,$y_1$),$\ldots$}% +\index{fcncurve@\cs{fcncurve}}% +\end{cd} + +Draws 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 equal to or greater than $1.0$ 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 typically $1.2$ +(actually $1.2$ times the value set with \cs{settension}). 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 be any positive +number, but only values greater than or equal to $1$ guarantee the +property of never doubling back. + + +\subsubsection{Circular Arcs.}\label{arcs} + +\begin{cd} +\cs{arc}\oarg{\meta{format}}\marg{\meta{specification}}% +\index{arc@\cs{arc}}% +\end{cd} + +Draws a circular arc specified as determined by the \meta{format} +optional parameter. This macro and \cs{circle} are unusual in that 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. + +\begin{cd} +\cs{arc}\oarg{s}\marg{\meta{$p_0$},\meta{$p_1$},\meta{sweep}}\\ +\cs{arc}\oarg{t}\marg{\meta{$p_0$},\meta{$p_1$},\meta{$p_2$}}\\ +\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$}}% +\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{sweep} +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{sweep} +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{sweep} gives a clockwise arc from \meta{$p_0$} +to \meta{$p_1$}. + +\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{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. + +\item[\oarg{a}] The \textit{Alternate polar form} draws the arc of a +circle with center \meta{$c$} and radius \meta{$r$}, starting at the +angle \meta{$\theta_1$} and ending at the angle \meta{$\theta_2$}. Both +angles are measured anticlockwise from the positive $x$ axis. This is +provided because it seems a more reasonable order of arguments, and +matches the order \cs{sector} requires (see subsection~\ref{other} +below). The \texttt{p} option is retained for backward compatibility. + +\item[\oarg{c}] The \textit{Center-point 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 and +the point sweep form are the basic methods of handling arcs---the +previous three formats are translated to one of these two before drawing.) +\end{description} + + +\subsubsection{Other Figures.}\label{other} + +\begin{cd} +\cs{turtle}\marg{\meta{$p_0$},\meta{$v_1$},\meta{$v_2$},$\ldots$}% +\index{turtle@\cs{turtle}}% +\end{cd} + +Draws a line segment, starting from the point \meta{$p_0$}, and +extending along the (2-dimen\-sional vector) displacement \meta{$v_1$}. +It then draws a line segment from the previous segment's endpoint, along +displacement \meta{$v_2$}. This continues for all listed displacements, +a process similar to `turtle graphics'. + +\begin{cd} +\cs{sector}\marg{\meta{$c$},\meta{$r$},\meta{$\theta_1$},\meta{$\theta_2$}}% +\index{sector@\cs{sector}}% +\end{cd} + +Draws the sector, from the angle \meta{$\theta_1$} to the angle +\meta{$\theta_2$} inside the circle with center at the point \meta{$c$} +and radius \meta{$r$}, where 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} +\cs{makesector} +\index{makesector@\cs{makesector}} +\end{cd} +The \cs{sector} command requires the center of the arc as one of its +arguments. But if one doesn't know that center (say one only knows three +points the arc connects) then even though the arc can be drawn, +\cs{sector} cannot. The \cs{makesector} command, when followed by any +\cs{arc} command, will find the center and connect it to the two ends of +the arc. It will actually attempt to do the same with any path that +follows, but the `center' it finds (if it finds one) will usually be +meaningless. + + +\subsubsection{Bar Charts and Pie Charts.}\label{charts} + +\begin{cd} +\cs{barchart}\oarg{\meta{start},\meta{sep},\meta{r}}\marg{\meta{h-or-v}}\marg{\meta{list}}\\ +\cs{bargraph}$\ldots$\\ +\cs{gantt}$\ldots$\\ +\cs{histogram}$\ldots$\\ +\cs{chartbar}\marg{\meta{num}}\\ +\cs{graphbar}\marg{\meta{num}}\\ +\cs{histobar}\marg{\meta{num}}% +\index{barchart@\cs{barchart}}% +\index{bargraph@\cs{bargraph}}% +\index{histogram@\cs{histogram}}% +\index{chartbar@\cs{chartbar}}% +\index{graphbar@\cs{graphbar}}% +\index{histobar@\cs{histobar}}% +\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. + +\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/or pairs giving the coordinates of +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{..} +\end{ex} +and another with +\begin{ex} + \cs{barchart}\oarg{1,1,.4}\marg{h}\marg{..} +\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 adjacent to 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. + +The macro \cs{chartbar} (synonyms \cs{graphbar}, \cs{ganttbar}, and +\cs{histobar}) takes a number from $1$ to the number of elements in the +\meta{list} and draws the rectangular path. 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} +\cs{piechart}\oarg{\meta{dir}\meta{angle}}\marg{\meta{$c$},\meta{$r$}}% + \marg{\meta{list}}\\ +\cs{piewedge}\oarg{\meta{spec}\meta{trans}}\marg{\meta{num}}% +\index{piechart@\cs{piechart}}% +\index{piewedge@\cs{piewedge}}% +\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 which may be either \texttt{c} or +\texttt{a} which stand for \emph{clockwise} or \emph{anticlockwise}, +respectively. It is common to draw piecharts with the largest wedge +starting at 12 o'clock (angle 90 degrees) and successive wedges +clockwise from there. This is the default. You can change the starting +angle from 90 with the \meta{angle} parameter, and the change the +direction to counter-clockwise by specifying \texttt{a} for \meta{dir}. It +is also traditional to arrange the wedges from largest to smallest, +except there is often a miscellaneous category which is usually last and +may be larger than some others. Therefore \cs{piechart} makes no attempt +to sort the data. The data is entered as a comma separated \meta{list} +of positive numbers in the second required parameter. These are only +used to determine the relative sizes of the wedges and are not printed +anywhere. The first required parameter should contain a pair \meta{c} +for the center and a positive number \meta{r} for the radius, separated +by a comma. + +After a \cs{piechart} command has been issued, the individual wedges may +be drawn, filled, etc., using \cs{piewedge}\marg{1}, +\cs{piewedge}\marg{2}, etc. Without the optional argument, the wedges +are located according to the arguments of the last \cs{piechart} +command. 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. + +\subsubsection{Polar Coordinates to Rectangular.}\label{polar} + +\begin{cd} +\cs{plr}\marg{(\meta{$r_0$},\meta{$\theta_0$}), +(\meta{$r_1$},\meta{$\theta_1$}), $\ldots$}% +\index{plr@\cs{plr}}% +\end{cd} + +Replaces 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---and to data containing both +rectangular and polar coordinate pairs. + + +\subsection{Colors}\label{colors} + +\subsubsection{Setting the Default Colors.}\label{defaultcolors} + +\begin{cd} +\cs{drawcolor}\oarg{\meta{model}}\marg{\meta{colorspec}}\\ +\cs{fillcolor}$\ldots$\\ +\cs{hatchcolor}$\ldots$\\ +\cs{pointcolor}$\ldots$\\ +\cs{headcolor}$\ldots$\\ +\cs{tlabelcolor}$\ldots$\\ +\cs{backgroundcolor}$\ldots$% +\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{grid} commands use +\cs{pointcolor}, and for arrowheads, \cs{headcolor}. When \opt{mplabels} +is in effect, the color of labels can be set with \cs{tlabelcolor}, and +one can set the color used by \cs{gclear} with \cs{backgroundcolor} (the +same color is used in the interior of unfilled points drawn with +\cs{point}). The optional \meta{model} may be one of \opt{rgb}, +\opt{RGB}, \opt{cmyk}, \opt{gray}, and \opt{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 \mfc{background}). Thus one can set +the filling color to the drawing color with +\cs{fillcolor}\marg{drawcolor}. + +\subsubsection{\CMP{} Colors.}\label{mpcolors} + +If the optional \meta{model} specification is omitted, the color +specification may be any expression recognized as a color by \MP. In +\MP, a color is a triple of numbers like \mfc{(1,.5,.5)}, with the +coordinates 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)}. \CMP{} also has color variables and several have been +predefined: \mfc{red}, \mfc{green}, \mfc{blue}, \mfc{yellow}, +\mfc{cyan}, \mfc{magenta}, \mfc{white}, and \mfc{black}. All the names +in the \LaTeX{} \prog{color} package's \file{dvipsnam.def} are +predefined color variable names. Since \MP{} allows color expressions, +colors may be added and multiplied by numerics. Moreover, several \MP{} +color functions have been defined in \file{grafbase.mp}: + +\begin{cd} +\mfc{cmyk($c$,$m$,$y$,$k$)}% +\index{cmyk@\mfc{cmyk($c$,$m$,$y$,$k$)}} +\end{cd} + +Converts a \opt{cmyk} color specification to \MP's native \opt{rgb}. For +example, the command \mfc{cmyk(1,0,0,0)} yields \mfc{(0,1,1)}, which is +the definition of \mfc{cyan}. + +\begin{cd} +\mfc{RGB($R$,$G$,$B$)}% +\index{RGB@\mfc{RGB($R$,$G$,$B$)}} +\end{cd} + +Converts an \opt{RGB} color specification to \opt{rgb}. It essentially +just divides each component by 255. + +\begin{cd} +\mfc{gray($g$)}% +\index{gray@\mfc{gray($g$)}} +\end{cd} + +Converts a numeric $g$ (a gray level) to the corresponding multiple of +\mfc{(1,1,1)}. + +\begin{cd} +\mfc{named(\meta{name})}, +\mfc{rgb($r$,$g$,$b$)}% +\index{named@\mfc{named(\meta{name})}}% +\index{rgb@rgb($r$,$g$,$b$)} +\end{cd} + +These are essentially no-ops. However; \mfc{rgb} will truncate the +arguments to the 0--1 range, an unknown \meta{name} is converted to +\mfc{black}, and an unknown numeric argument is set to 0. + +\medskip +As an example of the use of these functions, one could conceivable +write: +\begin{ex} + \cs{drawcolor}\marg{0.5*RGB(255,0,0)+0.5*cmyk(1,0,0,0)} +\end{ex} +to have all curves drawn in a color halfway between red and cyan (which +turns out to be the same as \gbc{gray(0.5)}). + +\subsubsection{Color Models.}\label{colormodels} + +When the optional \meta{model} is specified in the color setting +commands, it determines the format of the color specification: + +\medskip +\halign{\quad#\hfil\quad&#\hfil\cr +{\sl Model:}& {\sl Specification:}\cr +\opt{rgb}& Three numbers in the range 0 to 1 separated by commas.\cr +\opt{RGB}& Three numbers in the range 0 to 255 separated by commas.\cr +\opt{cmyk}& Four numbers in the range 0 to 1 separated by commas.\cr +\opt{gray}& One number in the range 0 to 1, with 1 indicating + white, 0 black.\cr +\opt{named}& A \MP{} color variable name either predefined by + \mfp{} or by the user.\cr} + +\medskip +\Mfp{} translates +\begin{ex} + \cs{fillcolor}\oarg{cmyk}\marg{1,.3,0,.2} +\end{ex} +into the equivalent of +\begin{ex} + \cs{fillcolor}\marg{cmyk(1,.3,0,.2)}. +\end{ex} +Note that when the optional model is specified, the color +specification must 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. + + +\subsubsection{Defining a Color Name.}\label{colorname} + +\begin{cd} +\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 \opt{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}. + +\subsubsection{Color in \MF} + +\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 no longer 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 is still somewhat experimental and 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 zeros all affected pixels before adding the dots to +simulate gray. In particular, \cs{gfill}\oarg{white} should have the +same effect as \cs{gclear}. + + +\subsection{Shape-Modifier Macros.}\label{modifier} + +Some \mfp{} macros operate as \emph{shape-modifier} macros---for +example, if you want to put an arrowhead on a line segment, you could +write: \cs{arrow}\cs{lines}\marg{(0,0),(1,0)}. These are always prefixed +to some figure drawing command, and apply only to the next following +figure macro (which can be rather far removed) provided that only other +prefix commands intervene. This is a rather long section, but even more +modification prefixes are documented in subsection~\ref{transformation}. + +For the purposes of these macros, 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 is open, and must be explicitly closed, for example by \cs{lclosed} +(see below). The (already) closed paths are those that have +`\texttt{closed}' in their name plus: \cs{rect}, \cs{circle}, +\cs{ellipse}, \cs{sector}, \cs{cyclic}, \cs{polygon}, \cs{plrregion}, +\cs{chartbar}, \cs{piewedge}, \cs{tlabelrect}, \cs{tlabeloval}, +\cs{tlabelellipse}, \cs{tlabelcircle} and \cs{btwnfcn} (below). + +\subsubsection{Closure of Paths.}\label{closure} + +\begin{cd} +\cs{lclosed}$\ldots$% +\index{lclosed@\cs{lclosed}} +\end{cd} + +Makes each open path into a closed path by adding a line segment between +the endpoints of the path. + +\begin{cd} +\cs{bclosed}\oarg{\meta{tens}}$\ldots$ +\index{bclosed@\cs{bclosed}}% +\end{cd} + +This 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. + +\begin{cd} +\cs{sclosed}\oarg{\meta{tens}}$\ldots$% +\index{sclosed@\cs{sclosed}} +\end{cd} + +This 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 the same result +as \cs{cyclic} given the same points and tension valuse. The optional +tension argument is as in the \cs{bclosed} command. + + +\subsubsection{Reversal, Connection and Subpaths.}\label{reversal} + +\begin{cd} +\cs{reverse}$\ldots$% +\index{reverse@\cs{reverse}} +\end{cd} + +Turns a path around, reversing its sense. This will affect both +the direction of arrows (e.g. bi-directional arrows can be coded with +\cs{arrow}\cs{reverse}\cs{arrow}$\ldots$, where the first \cs{arrow} +modifier applies to the \emph{reversed} path), and the order of +endpoints for a \cs{connect}$\ldots$\cs{endconnect} environment (below). + + +\begin{cd} +\cs{connect} $\ldots$ +\cs{endconnect}% +\index{connect@\cs{connect}} +\index{endconnect@\cs{endconnect}} +\end{cd} + +This pair of macros, acting as an environment, adds line segments from +the trailing endpoint of one path to the leading endpoint of the +next path, in the given order. The result is a connected, \emph{open} +path. + +\emph{Note}: In \LaTeX, this pair of macros can be used in the form of a +\LaTeX-style environment called \env{connect} ---as in +\cs{begin}\marg{connect}$\ldots$\cs{end}\marg{connect}. + +\begin{cd} +\cs{partpath}\marg{\meta{frac1},\meta{frac2}}\dots\\ +\cs{subpath}\marg{\meta{num1},\meta{num2}}\dots% +\index{partpath@\cs{partpath}}% +\index{subpath@\cs{subpath}} +\end{cd} + +Both produce a part of the following path. 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 \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. + +As an example of \cs{partpath}, one can put an arrowhead (see next +subsection) in the middle of a path with something like the following. + +\begin{ex} +\cs{arrow}\cs{partpath}\marg{0,.5}\cs{draw}\dots +\end{ex} + + +\subsubsection{Arrows.}\label{arrows} + +\begin{cd} +\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} + +Draws 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 e.g. 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, the rotation affects the direction in which the arrowhead is set +back. The optional \meta{color} defaults to \gbc{headcolor}. The +optional parameters may appear in any order, but the indicated key +character for each parameter must always appear. + + +\subsection{Rendering macros}\label{rendering} + +\subsubsection{Drawing.}\label{drawing} + +When \mfp{} is loaded, the initial way in which figures are drawn +is with a solid outline. That is, \cs{lines}\marg{(1,0),(1,1),(0,0)} +will draw two solid lines connecting the points. When the macros in this +section are used, any previously established default (see +subsection~\ref{default} below) is overridden. + +\begin{cd} +\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{plot}, \cs{plotnodes}, +and \cs{gendashed}, + +\begin{cd} +\cs{dashed}\oarg{\meta{length},\meta{space}}$\ldots$% +\index{dashed@\cs{dashed}} +\end{cd} + +Draws dashed segments along the path specified in the next command. 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\over 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} +\cs{dotted}\oarg{\meta{size},\meta{space}}$\ldots$% +\index{dotted@\cs{dotted}} +\end{cd} + +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} +\cs{plot}\oarg{\meta{size},\meta{space}}\marg{\meta{symbol}}$\ldots$% +\index{plot@\cs{plot}} +\end{cd} + +Similar to \cs{dotted} except copies of \meta{symbol} are drawn along +the path. Possible symbols are those listed under \cs{plotsymbol} in +subsection~\ref{points}. The default \meta{size} is \cs{pointsize} and +the default \meta{space} is \cs{symbolspace}, initially \dim{5pt}. + +\begin{cd} +\cs{plotnodes}\oarg{\meta{size}}\marg{\meta{symbol}}$\ldots$% +\index{plotnodes@\cs{plotnodes}} +\end{cd} + +This places a symbol (same possibilities as in \cs{plotsymbol}, see +subsection~\ref{points}) at each node of the path that follows. 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 (below), each of the data points in the file is. In the function +macros (below) 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} +\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, +there is a generalized dashing command. One must first establish a named +dashing pattern with this command. \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{ex} + \cs{dashpattern}\marg{dotdash}\marg{0pt,4pt,3pt,4pt}. +\end{ex} +\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 space 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. + +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} +\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 +command 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. + + +\subsubsection{Shading, Filling, Erasing, Clipping, +Hatching.}\label{filling} + +These macros 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. These macros replace the default rendering: +when they are used the outline will not be drawn unless an explicit +prefix to do so is present. + +\begin{cd} +\cs{gfill}\oarg{\meta{color}}$\ldots$% +\index{gfill@\cs{gfill}} +\end{cd} + +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} +\cs{gclear}$\ldots$% +\index{gclear@\cs{gclear}} +\end{cd} + +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 +white, and so are most actual backgrounds, this is usually +indistinguishable from clearing. + +\begin{cd} +\cs{gclip}$\ldots$% +\index{gclip@\cs{gclip}} +\end{cd} + +Erases everything \emph{outside} the subsequent closed path from the +picture (except text labels under some circumstances, see +section~\ref{mplabels} and \ref{overlaylabels}). + +\begin{cd} +\cs{shade}\oarg{\meta{shadesp}}$\ldots$% +\index{shade@\cs{shade}} +\end{cd} + +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.5pt}. 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 75\% of white.% + \footnote{If \cs{shadewd} is $w$ and \cs{shadespace} is $s$, then + the level of gray is $1 - (w/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} +\cs{polkadot}\oarg{\meta{space}}$\ldots$% +\index{polkadot@\cs{polkadot}} +\end{cd} + +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{} all it does is fill 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{5pt}. The dots are colored with +\index{fillcolor@\gbc{fillcolor}}\gbc{fillcolor}. In \MF, nonblack +values of \gbc{fillcolor} will produce shaded dots. + +\begin{cd} +\cs{thatch}\oarg{\meta{hatchsp},\meta{angle}}\oarg{\meta{color}}$\ldots$% +\index{thatch@\cs{thatch}} +\end{cd} + +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). + +\begin{cd} +\cs{lhatch}\oarg{\meta{hatchsp}}\oarg{\meta{color}}$\ldots$% +\index{lhatch@\cs{lhatch}} +\end{cd} + +Draws lines shading in the subsequent closed path in a left-oblique +hatched (upper left to lower right) pattern. It is exactly the same as +\cs{thatch}\oarg{\meta{hatchsp},-45}\oarg{\meta{color}}$\ldots$ + +\begin{cd} +\cs{rhatch}\oarg{\meta{hatchsp}}\oarg{\meta{color}}$\ldots$% +\index{rhatch@\cs{rhatch}} +\end{cd} + +Draws lines shading in the subsequent closed path in a right-oblique +hatched (lower left to upper right) pattern. It is exactly the same as +\cs{thatch}\oarg{\meta{hatchsp},45}\oarg{\meta{color}}$\ldots$ + +\begin{cd} +\cs{hatch}\oarg{\meta{hatchsp}}\oarg{\meta{color}}$\ldots$\\ +\cs{xhatch}\oarg{\meta{hatchsp}}\oarg{\meta{color}}$\ldots$% +\index{hatch@\cs{hatch}}% +\index{xhatch@\cs{xhatch}} +\end{cd} + +Draws lines shading in the subsequent closed path 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). Hatching at two different +angles is, however, almost the only way to fill in two regions that +\emph{automatically} shows the overlapping region. + + +\subsubsection{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 strokes with pens, and fills + +\begin{cd} +\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 and/or other \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. + +\subsubsection{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{shade}\cs{lclosed}\cs{lines}\marg{...} +\end{ex} +which shades inside a polygon and draws its outline; and +\begin{ex} + \cs{shade}\cs{lclosed}\cs{draw}\cs{lines}\marg{...} +\end{ex} +which draws all of the outline \emph{except} the line segment supplied +by \cs{lclosed}, then shades the interior. Thus, in the first case the +path is defined (by \cs{lines}) then closed, then the resulting closed +path is shaded, then drawn; while in the second case the order is: +defined, drawn, closed, shaded. In particular, what is drawn is the path +not yet closed. + + +\subsection{Functions and Plotting.}\label{functions} + +In the following macros, expressions like $f(\mathtt{x})$, $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). + +\subsubsection{Defining Functions}\label{defining} + +\begin{cd} +\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 names +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 in +the commands \mfc{begingroup} and \mfc{endgroup}. The \cs{fdef} +command automatically supplies the grouping around the definition so +the user need not type them if the entire \meta{mf-expr} is one such +compound expression. \CMF{} functions can call \MF{} functions, +even recursively. + +Many common functions have been predefined in \file{grafbase}. These +include all the usual 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}, and their inverses \mfc{ln} (or +\mfc{log}), \mfc{asinh}, \mfc{acosh}, and \mfc{atanh} are also defined. + +\subsubsection{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. + +\begin{cd} +\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} + +Plots $f(\mathtt{x})$, 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{ex} +\cs{function}\marg{0,pi,pi/10}\marg{sin x} +\end{ex} +draws the graph of $\sin x$ between 0 and $\pi$. + +\begin{cd} +\cs{parafcn}\oarg{\meta{spec}}\marg{\meta{$t_{\mathrm{min}}$},% + \meta{$t_{\mathrm{max}}$},\meta{$\Delta t$}}% + \marg{\meta{pfcn}}% +\index{parafcn@\cs{parafcn}} +\end{cd} + +Plots the parametric path determined by \meta{pfcn}, where \meta{pfcn} +is a \MF{} function or expression of one numeric argument \texttt{t}, +returning a \MF{} \emph{pair}. Or a pair of numeric expressions +$(x(\mathtt{t}),y(\mathtt{t}))$ enclosed in parentheses and separated by +a comma. The default \meta{spec} is \texttt{s}. For example +\begin{ex} +\cs{parafcn}\marg{0,1,.1}\marg{(2t, t + t*t)} +\end{ex} +plots a smooth parabola from $(0,0)$ to $(2,2)$. + +\begin{cd} +\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} + +Plots the polar function determined by $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{ex} +\cs{plrfcn}\marg{0,90,5}\marg{sind (2t)} +\end{ex} +draws one loop of a 4-petal rosette. If one needs radian measures, use +something like the following. +\begin{ex} +\cs{plrfcn}\marg{0,pi*radian,pi*radian/18}\marg{sin (2t/radian)} +\end{ex} + + +\begin{cd} +\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})$}% +\index{btwnfcn@\cs{btwnfcn}} +\end{cd} + +Draws the region between the two functions $f(x)$ and $g(x)$, these +being numeric functions of one numeric argument \texttt{x}. The region is +bounded also by the vertical lines at \meta{$x_{\mathrm{min}}$} and \meta{$x_{\mathrm{max}}$}. +Unlike the previous function macros, the default \meta{spec} is +\texttt{p}---this macro is intended to be used for shading between drawn +functions, a task for which smoothness is usually unnecessary. +For example +\begin{ex} +\cs{shade}\cs{btwnfcn}\marg{0,180,5}\marg{0}\marg{sind x} +\end{ex} +shades the area between first crest of a sine wave and the x-axis. + +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} + +\begin{cd} +\cs{plrregion}\oarg{\meta{spec}}% + \marg{\meta{$\theta_{\mathrm{min}}$},\meta{$\theta_{\mathrm{max}}$},% + \meta{$\Delta\theta$}}\marg{$f(\mathtt{t})$}% +\index{plrregion@\cs{plrregion}} +\end{cd} + +Plots the polar region determined by $r=f(\theta)$, where $f$ is a \MF{} +numeric function of one numeric argument \texttt{t}. The $\theta$ +values are angles (measured in \emph{degrees}), varying from +\meta{$\theta_{\mathrm{min}}$} to \meta{$\theta_{\mathrm{max}}$} in +steps of \meta{$\Delta\theta$}. In the expression $f(\mathtt{t})$, the +\texttt{t} stands for $\theta$. The region is also bounded by the angles +\meta{$\theta_{\mathrm{min}}$} and \meta{$\theta_{\mathrm{max}}$}, i.e. +by the line segments joining the origin to the endpoints of the +function. The default \meta{spec} is \texttt{p} ---this macro is +intended to be used for shading a region with the boundary drawn, a task +for which smoothness is usually unnecessary. For example +\begin{ex} +\cs{shade}\cs{plrregion}\marg{0,90,5}\marg{sind (2t)} +\end{ex} +shades one loop of the 4-petal rosette. + + +\subsubsection{Plotting external data files}\label{external} + +\begin{cd} +\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} + +\cs{datafile} defines 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 \meta{spec} is changed +to \texttt{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 \meta{spec} to +\texttt{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{ex} + \cs{point}\cs{datafile}\marg{ptlist.dat} +\end{ex} +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 of \mfp{} macros that allow this usage of +\cs{datafile}\index{datafile@\cs{datafile}}: + + \begin{raggedright} +\begin{itemize} +\item Numeric data: \cs{piechart}, \cs{barchart}, \cs{numericarray}, and + all the axis marks commands. +\item Point or vector data: \cs{point}, \cs{plotsymbol}, \cs{polyline}, + \cs{polygon}, \cs{fcncurve}, \cs{curve}, \cs{cyclic}, \cs{turtle}, + \cs{qspline}, \cs{closedqspline}, \cs{cspline}, \cs{closedcspline}, + \cs{mfbezier}, \cs{closedmfbezier}, \cs{qbeziers}, + \cs{closedqbeziers}, and \cs{pairarray}. +\end{itemize} + + \end{raggedright} + +\begin{cd} +\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} +\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 (i.e., space separated numbers, the first two determining each +point) correspond to the setting +\begin{ex} +\cs{using}\marg{\#1 \#2 \#3}\marg{(\#1,\#2)} +\end{ex} +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} +\cs{sequence}\index{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} +\cs{usingpairdefault}\\ +\cs{usingnumericdefault}% +\index{usingpairdefault@\cs{usingpairdefault}}% +\index{usingnumericdefault@\cs{usingnumericdefault}} +\end{cd} + +The command \cs{usingpairdefault} restores the above default for pair +data. The command \cs{usingnumericdefault} is the equivalent of +\cs{using}\marg{\#1 \#2}\marg{\#1}. + +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 example shows how to overcome this: +\begin{verbatim} + \makepercentother + \using{#1% #2 #3}{(#1/100,#2)} + \makepercentcomment +\end{verbatim} + + +Here\index{makepercentother@\cs{makepercentother}}% +\index{makepercentcomment@\cs{makepercentcomment}} +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. + +\begin{cd} + \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} +\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} changes to cycling through eight different +colors starting with black (hey, black is a color too). This has an +effect only for \MP. The sole exception to the general rule that all +curves are drawn in \gbc{drawcolor} is the \cs{plotdata} command after +\cs{coloredlines} has been issued. The command \cs{pointedlines} causes +\cs{plotdata} to use \cs{plot} commands, cycling through nine symbols. +The command \cs{datapointsonly} causes \cs{plotdata} to use +\cs{plotnodes}\marg{\meta{symbol}} commands to plot the data points +only. (See the Appendix for more details.) The command \cs{dashedlines} +restores the default. 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} +\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 the Appendix 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 dashess, colors, or symbols. + +\begin{cd} +\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 +change: \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{} expressions of type color, and the symbols can be +expressions of type path. Within a \env{mfpic} environment, the changes +made are local to that environment. Outside, they affect all subsequent +environments. + +\begin{cd} +\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. + +\subsection{Labels and Captions.}\label{labels} + +\subsubsection{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} +\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} + +Places \TeX{} labels on the graph. (Not to be confused with \LaTeX's +\cs{label} command.) 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. +In fact, the second syntax may be used if \opt{mplabels} is in effect, +where \meta{pair-list} is any expression recognized as a pair by \MP, or +a comma-separated list of such pairs. + +The optional parameter \oarg{\meta{just}} specifies the +\emph{justification}, the relative placement of the label with respect +to the point \parg{\meta{x},\meta{y}}. It is a two-character sequence +where 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}. + +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{gclear} or +\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}. + +\begin{cd} +\cs{everytlabel}\marg{\meta{\TeX-code}}% +\index{everytlabel@\cs{everytlabel}} +\end{cd} + +One problem with multi-line \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{ex} + \cs{everytlabel}\marg{\cs{bf}\cs{baselineskip} 10pt} +\end{ex} +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 the lines +of a tlabel are wrapped in a box, but the commands of \cs{everytlabel} +are outside all of them, so no actual text should be produced by these +commands. + +Using \cs{tlabel} without an optional argument is equivalent to +specifying \oarg{Bl}. Use the following command to change this +behavior. + +\begin{cd} +\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. Without +\opt{mplabels}, the rotation is ignored by \cs{tlabel} . + +\begin{cd} +\cs{tlabeloffset}\marg{\meta{hlen}}\marg{\meta{vlen}}\\ +\cs{tlabelsep}\marg{\meta{len}}% +\index{tlabeloffset@\cs{tlabeloffset}}% +\index{tlabelsep@\cs{tlabelsep}} +\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{tlabelsep} 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, but the value is +also written to the output file for use by \cs{tlabelrect} +(subsection~\ref{surrounding}) and related +commands. + +\begin{cd} +\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{tlabelsep} 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} +\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. It simply issues multiple \cs{tlabel} commands with +the same text and optional parameter, but at the different points +listed. This is intended to plot a set of points with a single letter or +font symbol (instead of a \MF{} generated shape). Like \cs{axislabels}, +this does not respond to the setting of \cs{tlabeljustify}. It has a +default setting of \oarg{cc} if the optional argument is omitted. The +points may be MetaPost pair expressions under \opt{mplabels}, but they +must \emph{not} be individually enclosed in braces. (This requirement is +new with version 0.7; prior to that pairs in braces didn't work reliably +anyway.) This command is actually unnecessary under \opt{mplabels} as +the plain \cs{tlabel} command can then be given a list of points. The +\cs{tlabel} command is more efficient, and \cs{plottext} is converted to +it internally. + +\begin{cd} +\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 issued before \cs{opengraphsfile}, its contents are saved +and written by that command. 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}. + +\begin{cd} +\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} typesets its +argument twice (as does \LaTeX's \cs{caption}), the first time to test +its width, the second time for real. 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 lines are both left- and right-justified (except for the +last line), but the first line is not indented. If the option +\opt{centeredcaptions} is in effect, each line of the caption will be +centered. + +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. + +\subsubsection{Curves surrounding text}\label{surrounding} + + +\begin{cd} +\cs{tlabelrect}\oarg{\meta{rad}}\oarg{\meta{just}}% + \meta{pair}\marg{\meta{text}}\\ +\cs{tlabelrect*...}% +\index{tlabelrect@\cs{tlabelrect}} +\end{cd} + +This 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 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 parameter 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{tlabelsep}. 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 +`\texttt{*}-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} +\cs{tlabeloval}\oarg{\meta{mult}}\oarg{\meta{just}}% + \meta{pair}\marg{\meta{text}}\\ +\cs{tlabeloval*...}% +\index{tlabeloval@\cs{tlabeloval}} +\end{cd} + +This is similar to \cs{tlabelrect}, except it draws 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} +\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} + +Draws 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 +take 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} +\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}. + + +\subsection{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} +\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}}. + +\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. + + +\subsection{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 name and number (and any \TeX{} labels). The command(s) used +internally to do this are made available to the user. + +\begin{cd} +\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 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 the \cs{begin}\marg{mfpframe} $\ldots$ \cs{end}\marg{mfpframe} +syntax. + +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/command of the user's +choice or devising. + + +\subsection{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. + + +\subsubsection{Affine Transforms of the \MF{} Coordinate +System.}\label{affine} + +\begin{cd} +\cs{coords} $\ldots$ +\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 + +\emph{Note}: In \LaTeX, a \env{coords} environment may be used. + +\medskip +Transforms provided by \mfp. + +\medskip +\halign +{#\hfil&\quad#\hfil\cr + \cs{rotate}\marg{\meta{$\theta$}}% + \index{rotate@\cs{rotate}}% + & Rotates around origin by \meta{$\theta$} degrees \cr + \cs{rotatearound}\marg{\meta{point}}\marg{\meta{$\theta$}}% + \index{rotatearound@\cs{rotatearound}}% + & Rotates around point \meta{point} by \meta{$\theta$} degrees \cr + \cs{turn}\oarg{\meta{point}}\marg{\meta{$\theta$}}% + \index{turn@\cs{turn}}% + & Rotates around point \meta{point} (origin is default) by + \meta{$\theta$} \cr + \cs{mirror}\marg{\meta{$p_1$}}\marg{\meta{$p_2$}}% + \index{mirror@\cs{mirror}}% + & Same as \cs{reflectabout}\cr + \cs{reflectabout}\marg{\meta{$p_1$}}\marg{\meta{$p_1$}}% + \index{reflectabout@\cs{reflectabout}}% + & Reflect about the line \meta{$p_1$}\texttt{--}\meta{$p_2$} \cr + \cs{shift}\marg{\meta{pair}}% + \index{shift@\cs{shift}}% + & Shifts origin by the vector \meta{pair} \cr + \cs{scale}\marg{\meta{s}}% + \index{scale@\cs{scale}}% + & Scales uniformly by a factor of \meta{s} \cr + \cs{xscale}\marg{\meta{s}}% + \index{xscale@\cs{xscale}}% + & Scales only the X coordinates by a factor of \meta{s} \cr + \cs{yscale}\marg{\meta{s}}% + \index{yscale@\cs{yscale}}% + & Scales only the Y coordinates by a factor of \meta{s} \cr + \cs{zscale}\marg{\meta{pair}}% + \index{zscale@\cs{zscale}}% + & Scales uniformly by magnitude of \meta{pair}, and rotates by angle + of \meta{pair} \cr + \cs{xslant}\marg{\meta{s}}% + \index{xslant@\cs{xslant}}% + & Skew in $X$ direction by the multiple \meta{s} of $Y$ \cr + \cs{yslant}\marg{\meta{s}}% + \index{yslant@\cs{yslant}}% + & Skew in $Y$ direction by the multiple \meta{s} of $X$ \cr + \cs{zslant}\marg{\meta{pair}}% + \index{zslant@\cs{zslant}}% + & See \mfc{zslanted} in \file{grafdoc.tex} \cr + \cs{boost}\marg{\meta{$\chi$}}% + \index{boost@\cs{boost}}% + & Special relativity boost by $\chi$, see \mfc{boost} in + \file{grafdoc.tex} \cr + \cs{xyswap}% + \index{xyswap@\cs{xyswap}}% + & Exchanges the values of $x$ and $y$. \cr}% + +An arbitrary \MF{} transformation can be implemented with + +\begin{cd} +\cs{applyT}\marg{\meta{transformer}}% +\index{applyT@\cs{applyT}} +\end{cd} + +This is mainly for \MF{} hackers. This applies the \MF{} +\meta{transformer} to the current coordinate system. For example, the +\mfp{} \TeX{} macro \cs{zslant\#1} is implemented as +\cs{applyT}\marg{zslanted \#1} where the argument \mfc{\#1} is a \MF{} +pair, such as $(x,y)$. Any code that satisfies \MF's syntax for a +\meta{transformer} (see D.~E.~Knuth, ``The \MF book'') is permitted, +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: +$T_1 T_2 z$ usually means to apply $T_1$ to the result of $T_2 z$). + + +\subsubsection{Transformation of 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} +\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 or 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{ex} +\cs{store}\marg{pth}\cs{lclosed}\cs{reverse}% + \cs{curve}\marg{(0,0),(1,0),(1,1)}) +\end{ex} + +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 is special in that it is the only +prefix macro that allows the following path to be an argument, that is, +enclosed in braces. This is solely to support past \mfp{} versions in +which \cs{store} was \emph{not} defined as a prefix macro. + +\begin{cd} +\cs{mfobj}\marg{\meta{path expression}}\\ +\cs{mpobj}\marg{\meta{path expression}}% +\index{mfobj@\cs{mfobj}}\index{mpobj@\cs{mpobj}} +\end{cd} + +The \meta{path expression} is a previously stored path variable, or a +valid \MF{} (or \MP) expression combining such variables and/or constant +paths. This allows the use of path variables or expressions as figure +macros, permitting all prefix operations, etc.. Here's some +oversimplified uses of \cs{store} and \cs{mfobj}: + +\nobreak +\begin{verbatim} +\store{my_f}{\circle{...}} % Store a circle. +\dotted\mfobj{my_f} % Now draw it dotted, +\hatch\mfobj{my_f} % and hatch its interior +% Store two curves: +\store{my_f}{\curve{...}} +\store{my_g}{\curve{...}} +% Store two combinations of them: +\store{my_h}{\mfobj{my_f--my_g--cycle}} % a MF path expression +\store{my_k}{% + \lclosed\connect % a combination path created from + \mfobj{my_f}\mfobj{my_g} % mfpic commands. + \endconnect} +\dotted\mfobj{my_f} % Draw the first dotted, +\dotted\mfobj{my_g} % then the second. +\shade\mfobj{my_h} % Now shade one combination. +\hatch\mfobj{my_k} % and hatch the other +\end{verbatim} +The two forms \cs{mfobj} and \cs{mpobj} are absolutely equivalent. + +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 recent sequence of prefix macros and +figure. + +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, \mfp{} prefix macros +have an input and an output and a side effect. The input is the output +of whatever follows it, the output can be the same as the input (the +case for rendering prefixes) or modified version of that (the closure +prefixes). The side effect is the drawing (dashing, filling) of the path, +appending of an arrowhead, etc.. These side effects have to know where +to place their marks, so a computation is invoked that converts the +user's graph coordinates into \MF's drawing coordinates. The previous +transformation macros work by modifying the parameters used in this +computation. + +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 (other than invoking the default rendering if no +rendering prefix was previously provided). + +\begin{cd} +\cs{rotatepath}\marg{(\meta{x},\meta{y}),\meta{$\theta$}}$\ldots$\\ +\cs{shiftpath}\marg{(\meta{dx},\meta{dy})}$\ldots$\\ +\cs{scalepath}\marg{(\meta{x},\meta{y}),\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} + +\cs{rotatepath} rotates the following path by \meta{$\theta$} degrees +about point \mfc{(\meta{x},\meta{y})}. After the commands: +\begin{ex} + \cs{store}\marg{xx}\marg{\cs{rotatepath}\marg{(0,0), 45}% + \cs{rect}\marg{(0,0),(1,1)}} +\end{ex} +the object \cs{mfobj}\marg{xx} contains an actual rotated rectangle, as +drawing it will prove. The above macro, and the five that follow are +extremely useful (and better than \env{coords} environments) if one +needs to draw a figure, together with many slightly different versions +of it. + +\cs{shiftpath} shifts the following path by the horizontal amount +\meta{dx} and the vertical amount \meta{dy}. + +\cs{scalepath} scales (magnifies or shrinks) the following path by the +factor \meta{s}, in such a way that the point \parg{\meta{x},\meta{y}} +is kept fixed. That is +\begin{ex} + \cs{scalepath}\marg{(0,0),2}\cs{rect}\marg{(0,0),(1,1)} +\end{ex} +is essentially the same as \cs{rect}\marg{(0,0),(2,2)}, while +\begin{ex} + \cs{scalepath}\marg{(1,1),2}\cs{rect}\marg{(0,0),(1,1)} +\end{ex} +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. 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 (so that after a +swap, verticals become horizontal and horizontals become vertical). One +cannot have both when the scales are different. + +For \MF{} or \MP{} power users, \cs{transformpath} can take any +`transformer' and transform the following path with it. Here, a +\emph{transformer} is anything that can follow a path and create a new +path. Examples are \mfc{scaled}, \mfc{shifted (1,1)}, and \mfc{rotatedabout +(0,1)}. + +All these prefixes change only the path that follows, not any rendering +of it that follows. For example: +\begin{ex} + \cs{gfill}\cs{rotatepath}\marg{(0,0),90}\cs{dashed}% + \cs{rect}\marg{(0,0),(1,1)} +\end{ex} +will not produce a rotated dashed rectangle. Rather the original +rectangle will be dashed, and the rotated rectangle will be filled. + + +\subsection{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 to +\TeX{} groups only if set inside an \env{mfpic} environment 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 then +consistent. + +\begin{cd} +\cs{mfpicunit}% +\index{mfpicunit@\cs{mfpicunit}} +\end{cd} + +This \TeX{} 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 default value is \dim{1pt}. + +\begin{cd} +\cs{pointsize}% +\index{pointsize@\cs{pointsize}} +\end{cd} + +This \TeX{} dimension stores the diameter of the circle drawn by the +\cs{point} macro and the diameter of the symbols drawn by +\cs{plotsymbol} and by \cs{plot}. The default value is \dim{2pt}. + +\begin{cd} +\cs{pointfilltrue} and \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 default is \texttt{true}: filled. This value is local to any \TeX{} +group inside an \env{mfpic} environment. Outside such it is global. + +\begin{cd} +\cs{pen}\marg{\meta{drawpensize}}\\ +\cs{drawpen}\marg{\meta{drawpensize}}\\ +\cs{penwd}\marg{\meta{drawpensize}}% +\index{pen@\cs{pen}}% +\index{drawpen@\cs{drawpen}}% +\index{penwd@\cs{penwd}} +\end{cd} + +Establishes the width of the normal drawing pen. The default is +\dim{0.5pt}. This width is stored by \MF. The shading dots and hatching +pen are unaffected by this. 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} +\cs{shadewd}\marg{\meta{dotdiam}}% +\index{shadewd@\cs{shadewd}} +\end{cd} + +Sets the diameter of the dots used in the shading macro. The drawing and +hatching pens are unaffected by this. The default is \dim{0.5pt}, and +the value is stored by \MF. + +\begin{cd} +\cs{hatchwd}\marg{\meta{hatchpensize}}% +\index{hatchwd@\cs{hatchwd}} +\end{cd} + +Sets the line thickness used in the hatching macros. The drawing pen and +shading dots are unaffected by this. The default is \dim{0.5pt}, and the +value is stored by \MF. + +\begin{cd} +\cs{polkadotwd}\marg{\meta{polkadotdiam}}% +\index{polkadotwd@\cs{polkadotwd}} +\end{cd} + +Sets the diameter of the dots used in the \cs{polkadot} macro. The +default is \dim{5pt}, and the value is stored by \MF. + +\begin{cd} +\cs{headlen}% +\index{headlen@\cs{headlen}} +\end{cd} + +This \TeX{} dimension stores the length of the arrowhead drawn by +the \cs{arrow} macro. The default value is \dim{3pt}. + +\begin{cd} +\cs{axisheadlen}% +\index{axisheadlen@\cs{axisheadlen}} +\end{cd} + +This \TeX{} 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}. + +\begin{cd} +\cs{sideheadlen}% +\index{sideheadlen@\cs{sideheadlen}} +\end{cd} + +This \TeX{} 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 default value is \dim{0pt}. + +\begin{cd} +\cs{headshape}\marg{\meta{hdwdr}}\marg{\meta{hdten}}\marg{\meta{hfilled}}% +\index{headshape@\cs{headshape}} +\end{cd} + +Establishes the shape of the arrowhead drawn by the \cs{arrow} and +\cs{axes} macros. The value of \meta{hdwdr} is the ratio of the width of +the arrowhead to its length; \meta{hdten} is the tension of the B\'ezier +curves; and \meta{hfilled} is a \MF{} boolean value indicating whether +the arrowheads are to be filled (if \mfc{true}) or open. The default +values are $1$, $1$, \mfc{false}, respectively. The \meta{hdwdr}, +\meta{hdten} and \meta{hfilled} values are stored by \MF. Setting +\meta{hdten} to `\mfc{infinity}' will make the sides of the arrowheads +straight lines. These values are all stored by \MF. + +\begin{cd} +\cs{dashlen}, \cs{dashspace}% +\index{dashlen@\cs{dashlen}} +\end{cd} + +These \TeX{} 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\over{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 default 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} +\cs{dashlineset}, +\cs{dotlineset}% +\index{dashlineset@\cs{dashlineset}}% +\index{dotlineset@\cs{dotlineset}} +\end{cd} + +These macros provide convenient standard settings for the \cs{dashlen} +and \cs{dashspace} dimensions. The macro \cs{dashlineset} sets both +values to \dim{4pt}; the macro \cs{dotlineset} sets \cs{dashlen} to +\dim{1pt} and \cs{dashspace} to \dim{2pt}. + +\begin{cd} +\cs{hashlen}% +\index{hashlen@\cs{hashlen}} +\end{cd} + +This \TeX{} dimension stores the length of the axis hash marks drawn by +the \cs{xmarks} and \cs{ymarks} macros. The default value is \dim{4pt}. + +\begin{cd} +\cs{shadespace}% +\index{shadespace@\cs{shadespace}} +\end{cd} + +This \TeX{} dimension establishes the spacing between dots drawn by the +\cs{shade} macro. The default value is \dim{1pt}. + +\begin{cd} +\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. + +\begin{cd} +\cs{polkadotspace}% +\index{polkadotspace@\cs{polkadotspace}} +\end{cd} + +This \TeX{} dimension establishes the spacing between the centers of the +dots used in the macro \cs{polkadot}. The default is \dim{10pt}. + +\begin{cd} +\cs{dotsize}, \index{dotspace@\cs{dotspace}}\cs{dotspace}% +\index{dotsize@\cs{dotsize}} +\end{cd} + +These \TeX{} dimensions establishes the size and spacing between the +centers of the dots used in the \cs{dotted} macro. The defaults are +\dim{0.5pt} and \dim{3pt}. + +\begin{cd} +\cs{symbolspace}% +\index{symbolspace@\cs{symbolspace}} +\end{cd} + +Similar to \cs{dotspace}, this \TeX{} dimension establishes the space +between symbols placed by the macro +\cs{plot}\marg{\meta{symbol}}$\ldots\,$. Its default is \dim{5pt}. + +\begin{cd} +\cs{hatchspace}% +\index{hatchspace@\cs{hatchspace}} +\end{cd} + +This \TeX{} dimension establishes the spacing between lines drawn by the +\cs{hatch} macro. The default value is \dim{3pt}. + +\begin{cd} +\cs{tlabelsep}\marg{\meta{separation}}% +\index{tlabelsep@\cs{tlabelsep}} +\end{cd} + +This 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}. It also sets the +separation between the text and the curve defined by the commands +\cs{tlabelrect}, \cs{tlabeloval} or \cs{tlabelellipse}. The default is +\dim{0pt}. The value is 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 default is to have both horizontal +and vertical offsets of \dim{0pt}. The values are stored by both \TeX{} +and \MF. + +\begin{cd} +\cs{mfpdataperline}% +\index{mfpdataperline@\cs{mfpdataperline}} +\end{cd} + +When \mfp{} is reading data from files and writing it to the +output file, this macro stores the maximum number of points that will be +written on a single line in the output file. Its default is defined by +\cs{def}\cs{mfpdataperline}\marg{5}. + +\begin{cd} +\cs{mfpicheight}, +\cs{mfpicwidth}% +\index{mfpicheight@\cs{mfpicheight}}% +\index{mfpicwidth@\cs{mfpicwidth}} +\end{cd} + +These \TeX{} 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. + + +\subsection{For Advanced Users.}\label{advanced} + +\subsubsection{Power Users.}\label{power} + + +\begin{cd} +\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 are alternate ways of defining curves. In each case, \meta{list} +is a comma separated list of points. 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. + +\begin{cd} +\cs{cbclosed}$\ldots$\\ +\cs{qbclosed}$\ldots$% +\index{cbclosed@\cs{cbclosed}}% +\index{qbclosed@\cs{qbclosed}} +\end{cd} + +These are prefix macros for closing curves. 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. + +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} + \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} + +This connects the points in the list with the path join operator +\mfc{..tension \meta{tens}..}. 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} + \cs{qbeziers}\oarg{\meta{tens}}\marg{\meta{list}}\\ + \cs{closedqbeziers}\oarg{\meta{tens}}\marg{\meta{list}}% +\index{qbeziers@\cs{qbeziers}} +\index{closedqbeziers@\cs{closedqbeziers}} +\end{cd} + +Note the plural, to indicate that they will draw a 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. The curve +will not automatically be smooth. That depends on the choice of the +control points. + + +\begin{cd} +\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 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 realistic example. + +\begin{cd} +\cs{setmfvariable}\marg{\meta{type}}\marg{\meta{name}}\marg{\meta{value}}\\ +\cs{setmpvariable}\marg{\meta{type}}\marg{\meta{name}}\marg{\meta{value}}% +\index{setmfvariable@\cs{setmfvariable}} +\index{setmpvariable@\cs{setmpvariable}} +\end{cd} + +These formerly internal \mfp{} macros can be use to define symbolic +names for any \MF{} or \MP{} variable type. They are interchangeable; +you can use either one with or without the \opt{metapost} option. +As an example of their use, since dimensions are numeric data types in +\MF, the command +\begin{ex} + \cs{setmfvariable}\marg{numeric}\verb${my_dim}$\marg{7pt} +\end{ex} +would set the \MF{} variable \verb$my_dim$ to the value \texttt{7pt}. +After that, \verb$my_dim$ can be used in any \emph{drawing} command +where a dimension is required: +\begin{ex} + \cs{plotsymbol}\verb$[my_dim]$\marg{Triangle}\cs{rect}\marg{(0,0),(1,1)} +\end{ex} +will plot the rectangle with small triangles spaced \dim{7pt} apart. + +You can define paths this way +(\cs{setmfvariable}\marg{path}\marg{X}\marg{(0,0)..(1,1)..(0,1)}), but +the \meta{value} has to be valid \MF{} path construction syntax, +\emph{not} something like \cs{rect}\marg{$\ldots$}. You need \cs{store} +if you want to set a variable to an \mfp{} path. However, defined either +way, they can be used in \cs{mfobj}. + +A variable defined this way is local to the \env{mfpic} environment it +is contained in. It is in fact local to any \MF{} group. In \mfp, only +\cs{connect} {\dots} \cs{endconnect} and \cs{mfpic} {\dots} +\cs{endmfpic} create \MF{} groups in the graph file. + +\begin{cd} +\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 the mfpic environment. This is useful if all +one wishes to do in the current \env{mfpic} environment is to make +\emph{tiles} (see below). + +\begin{cd} +\cs{patharr}\marg{\meta{pv}}$\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{pv}. 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. The +definitions it makes are, however, 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} +\cs{pairarray}\marg{\meta{var}}{\meta{list-of-points}}\\ +\cs{numericarray}\marg{\meta{var}}{\meta{list-of-numbers}}% +\index{pairarray@\cs{pairarray}}% +\index{numericarray@\cs{numericarray}} +\end{cd} + +These enable the simultaneous definition of pair and numeric 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. If a numeric 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. The arrays are +defined locally if these commands occur in an \env{mfpic} environment, +global otherwise. In all arrays, the variable \gbc{X} itself (not +followed by any digit or brackets) is a number equal to the number of +elements in the array. + +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. + +Several commands in \mfp{} define arrays of objects that can be used in +other commands. The main ones are \cs{piechart} and \cs{barchart}. These +arrays are always global. Using \cs{piechart} causes the following +arrays to become defined: +\begin{itemize} + \item \gbc{piewedge}, a path array describing the wedges of the chart. + The command \cs{piewdge}\marg{\meta{num}} (without optional + argument) is almost exactly the same as + \cs{mfobj}\marg{piewedge[\meta{num}]}. + \item \gbc{pieangle}, a numeric array, the starting angle of each wedge. + \item \gbc{piedirection}, a pair array, the unit vectors pointing in + the directions of the centers of the wedges. If \cs{pieangle1} + is 0 and \gbc{pieangle2} is 90 degrees, then \gbc{piedirection1} + is $(\cos 45,\sin 45)$. +\end{itemize} + +Using \cs{barchart} causes the following arrays to become defined. The +exact meaning depends on whether bars are horizontal or vertical. The +following describes horizontal bars; interchange the roles of $x$ and +$y$ if they are vertical: +\begin{itemize} + \item \gbc{barstart}, the position on the $y$-axis of the leading edge + of the bars. + \item \gbc{barbegin}, the $x$-coordinate of the leftmost end of the + bars. + \item \gbc{barend}, the $x$-coordinate of the rightmost end of the + bars. + \item \gbc{chartbar}, the rectangular path of the bar; \gbc{chartbar1} + is the rectangle with corners at \gbc{(barbegin1,barstart1)} and + \gbc{(barend1,barstart+barwd)}, where \gbc{barwd} is the + width (thickness) of the bar. + \item \gbc{barlength}, the same as \gbc{barend}. This is for backward + compatibility; the was name chosen at a time when all the bars + had one side on an axis (i.e., \gbc{barbegin[n] = 0}). +\end{itemize} + +\begin{cd} +\cs{tile}\marg{\meta{tilename},\meta{unit},\meta{wd},\meta{ht},\meta{clip}}\\ + \ $\ldots$\\ +\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. The units of drawing are given by +\meta{unit}, which should be a 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 all 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 please take some care with the +\ae sthetics! The \meta{tilename} is globally defined by this command. + +\begin{cd} +\cs{tess}\marg{\meta{tilename}}$\ldots$% +\index{tess@\cs{tess}} +\end{cd} + +Tile the interior of a closed path with a tessellation comprised of +copies of the \emph{tile} specified by \meta{tilename}. There is no +default \meta{tilename}; you must make all your own tiles. Tiling an +open curve is technically an error, but the \MF{} code responds by +drawing the path and not doing any tiling. + +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. + +\begin{cd} +\cs{cutoffafter}\marg{\meta{obj}}\dots\\ +\cs{cutoffbefore}\marg{\meta{obj}}\dots\\ +\cs{trimpath}\marg{\meta{dim$_1$},\meta{dim$_2$}}\dots\\ +\cs{trimpath}\marg{\meta{dim$_1$}}\dots\\ +\index{cutoffafter@\cs{cutoffafter}}% +\index{cutoffbefore@\cs{cutoffbefore}}% +\index{trimpath@\cs{trimpath}}% +\end{cd} + +These are prefix macros. The first two take an `object' (a variable in +which a path was previously stored using \cs{store}) and uses it to trim +one end off the following path. \cs{cutoffbefore} cuts off the part of +the path before its first intersection with the object, while +\cs{cutoffafter} cuts off the part 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 completely reliably only when there is only one +point of intersection. + +The \cs{trimpath} macro takes two dimensions separated by commas and +trims those lengths off the initial and terminal ends of the path. If +only one dimension is given, that is used at both ends. This macro is +essentially equivalent to applying \cs{cutoffafter} and then +\cs{cutoffbefore} where the objects are circles which have radii equal +to the given dimensions and which are centered at the endpoints of the +path. Consequently, if the path is shorter than either dimension, it +will not intersect either circle and nothing will be trimmed. Similarly, +if the result of \cs{cutoffafter} is shorter than the first dimension, +then \cs{cutoffbefore} will not trim any more off. The first two macros +can be used to create a curve that starts or ends right at another +figure without having to find the point where the two curves intersect. +The third one can be used on the result to produce a curve that stops +just short of the point of intersection. + +\begin{cd} +\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} +\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} +\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. Hopefully, \mfp{} won't exceed your +local \TeX's limit. + +All of \mfp's basic dimension parameters are font dimensions. We have +lied slightly when we called them `\TeX{} 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} +\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} +\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} +\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 graphics package to make the data +available. If \cs{setmfpicgraphic} is redefined then this may also have +to be redefined. + +\begin{cd} +\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} +\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} +\cs{mfpicversion} +\index{mfpicversion@\cs{mfpicversion}} +\end{cd} + +This expands to the current \mfp{} version multiplied by 100. At this +writing, it produces `\texttt{70}' because the version is 0.7. It +can be used to test for the current 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. + +\subsubsection{Hackers.}\label{hackers} + +\Mfp{} employs a modified version of \LaTeX's \cs{@ifnextchar} +that not only skips over spaces when seeking the next character, but +also skips over \cs{relax} or tokens that have been \cs{let} equal to +it. This is because, in contexts where we try to preserve lines, we make +the end-of-line character active and set it equal to \cs{relax}. Since +it is hard to predict in what context a macro will be used, this gives +code like +\begin{ex} + \cs{function}\\ + \oarg{s1.2}\marg{0,2,.1}\marg{ x**2 } +\end{ex} +the same behavior in both.% + \footnote{Actually, because of a bug in previous versions, this was + not true, but it is now. I hope.} +One consequence is that putting \cs{relax} to stop a command from seeing +a `\texttt{[}' as the start of an optional argument will not work for +\mfp{} commands. The same holds for the `\texttt{*}' in those few +commands that have a star-form, and also for other commands that look +ahead (\cs{tlabel} looks for a `\texttt{(}' starting off the location, +and macros that operate on lists of data look ahead for +`\cs{datafile}'). This is not a serious problem, because there is only +one command (\cs{smoothdata}) that takes an optional arguments but +doesn't have mandatory arguments after that. If a `\cs{relax}' appeared +after any other \mfp{} command, it would be taken as an argument and an +error would result. In any case, \cs{empty} will stop the looking ahead +if it should ever be necessary. + +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}.) + + +\clearpage + +\def\sectionmark#1{\markright {\thesection\quad#1}}% +\def\subsectionmark#1{} +\def\subsubsectionmark#1{} +\thispagestyle{plain} +\section{Appendices}\label{appendices} + +\subsection{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: + +\medskip +Geoffrey Tobin %(G.Tobin@latrobe.edu.au) +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; + +\medskip +Bryan Green %(bgreen@sanjuan.uvic.ca) +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 + +\medskip +Uwe Bonnes %(bon@lte.e-technik.uni-erlangen.de) +and Jarom\'\i r Kuben, % (vabo@muni.cz) +who worked out rewrites of \mfp{} during Tom's +working hiatus and who each contributed several valuable ideas. + +\medskip +Some credit also belongs to Anthony Stark, % (ajs@merck.com) +whose work on a FIG to \MF{} converter has had a serious impact on the +development of many of \mfp's capabilities. + +\medskip +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, and Zaimi +Sami~Alex for suggestions. + +But mostly, he'd like to thank Tom Leathrum for starting it all. + +\subsection{Changes History.}\label{changes} + +See the file \file{changes.txt} for a somewhat sporadic and rambling +history of changes to \mfp. See the file \file{readme.txt} for a +list of any known problems. + +%\clearpage +\subsection{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 +\def\stack#1{\everycr{}\def\\{\cr}\halign{\strut##\hfil\cr#1\crcr}} +{\everycr{\noalign{\medskip}} +\halign to \hsize{\opt{#}\hfil\quad\tabskip0pt plus 1fil& + \vtop{\stack{#}}\hfil\quad& + \vtop{\parindent0pt \hsize.45\hsize \rightskip0pt plus1fil\relax + \strut\ignorespaces#\strut}\tabskip0pt\cr +{\rmfamily\scshape Option}:& \textsc{Command form(s)}:& \omit\textsc{Restrictions}: \hfil\cr +\noalign{\smallskip\hrule\smallskip} +metapost&\cs{usemetapost}& Command must come before + \cs{opengraphsfile}. Incompatible with \opt{metafont} option. \cr +metafont&\cs{usemetafont}& The default. Command must come before + \cs{opengraphsfile}. Incompatible with \opt{metapost} option. \cr +mplabels&\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 +overlaylabels&\cs{overlaylabels},\\ \cs{nooverlaylabels}& Has no effect + without \opt{metapost}. \cr +truebbox& \cs{usetruebbox},\\ \cs{notruebbox}& Has no effect + without \opt{metapost}. \cr +clip& \cs{clipmfpic},\\ \cs{noclipmfpic}& No restrictions. \cr +clearsymbols& \cs{clearsymbols},\\ \cs{noclearsymbols}& No restrictions. \cr +centeredcaptions& \cs{usecenteredcaptions},\\ \cs{nocenteredcaptions}& + No restrictions. \cr +debug&\cs{mfpicdebugtrue},\\\cs{mfpicdebugfalse}& To turn on + debugging while \file{mfpic.tex} is loading, issue + \cs{def}\cs{mfpicdebug}\marg{true}. \cr +\vtop{\hbox{draft\strut} + \hbox{final\strut} + \hbox{nowrite\strut}}&\cs{mfpicdraft}\\ + \cs{mfpicfinal}\\ + \cs{mfpicnowrite}& Should not be used + together. Command forms should come before + \cs{opengraphsfile}\cr +}} + +%\clearpage +\subsection{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 pattern names \mfc{dashtype0} through +\mfc{dashtype5}, or predefined color names \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 +\indent\vbox{% +\halign{#\hfil\qquad&#\hfil\quad&#\hfil\strut\cr +\textsc{Name}&\textsc{Pattern}&\textsc{Meaning}\cr +\noalign{\smallskip\hrule\smallskip} +\mfc{dashtype0}& \dim{0bp} & solid line \cr +\mfc{dashtype1}& \dim{3bp,4bp} & dashes \cr +\mfc{dashtype2}& \dim{0bp,4bp} & dots \cr +\mfc{dashtype3}& \dim{0bp,4bp,3bp,4bp} & dot-dash \cr +\mfc{dashtype4}& \dim{0bp,4bp,3bp,4bp,0bp,4bp} & dot-dash-dot \cr +\mfc{dashtype5}& \dim{0bp,4bp,3bp,4bp,3bp,4bp} & dot-dash-dash\cr +}} + +\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.) + +\medskip +\indent\vbox{% +\halign{#\hfil\qquad&#\hfil\quad&#\hfil\strut\cr +\textsc{Name}&\textsc{Color}&\textsc{(r,g,b)}\cr +\noalign{\smallskip\hrule\smallskip} +\mfc{colortype0}& black & $( 0, 0, 0)$\cr +\mfc{colortype1}& red & $( 1, 0, 0)$\cr +\mfc{colortype2}& blue & $( .2, .2, 1)$\cr +\mfc{colortype3}& orange & $(.66,.34, 0)$\cr +\mfc{colortype4}& green & $( 0, .8, 0)$\cr +\mfc{colortype5}& magenta& $(.85, 0,.85)$\cr +\mfc{colortype6}& cyan & $( 0,.85,.85)$\cr +\mfc{colortype7}& yellow & $(.85,.85, 0)$\cr +}} + +\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 +\indent\vbox{% +\halign{#\hfil\qquad&#\hfil\strut\cr +\textsc{Name}&\textsc{Description}\cr +\noalign{\smallskip\hrule\smallskip} +\mfc{pointtype0}& \mfc{Circle} \cr +\mfc{pointtype1}& \mfc{Cross} \cr +\mfc{pointtype2}& \mfc{SolidDiamond} \cr +\mfc{pointtype3}& \mfc{Square} \cr +\mfc{pointtype4}& \mfc{Plus} \cr +\mfc{pointtype5}& \mfc{Triangle} \cr +\mfc{pointtype6}& \mfc{SolidCircle} \cr +\mfc{pointtype7}& \mfc{Star} \cr +\mfc{pointtype8}& \mfc{SolidTriangle}\cr +}} + +\subsection{Special considerations when using \MF}\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 4096 pixels is. In +fonts prepared for a LaserJet4 (600 DPI), this means about 6.8 inches. +For a 1200 DPI pronter, the limit is about 3.4 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)^2=20.25$ in pixel units (after +multiplying by the \cs{mfpic} scaling factor the \cs{mfpicunit} in +inches and the DPI value): $20.25\times10\times0.03937\times600 > 4783$. +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. + + +\subsection{Special considerations when using \MP}\label{mpconsiderations} + +\subsubsection{Required support} + +To use \mfp{} with \MP, the following support is needed (besides a +working \MP{} installation): + +\medskip +\halign{#\hfil\quad&\vtop{\hsize 4.4 truein \raggedright \noindent + \strut#\strut}\hfil\cr +Under plain\TeX &The file \file{epsf.tex}\cr +Under \LaTeX209 &The file \file{epsf.tex} or \file{epsf.sty}\cr +Under \LaTeXe &The package \prog{graphics} or \prog{graphicx}\cr +Under \pdfLaTeX{} &The package \prog{graphics} or + \prog{graphicx} with option \opt{pdftex}\cr +Under plain \pdfTeX{} &The files \file{supp-pdf.tex} and + \file{supp-mis.tex}\cr +In all cases &The files \file{grafbase.mp} and + \file{dvipsnam.mp} plus, of course, + \file{mfpic.tex} (and \file{mfpic.sty} for + \LaTeX)\cr +} + +\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 graphics package is given the +\opt{pdftex} option. This option requires the file \file{pdftex.def} +which currently inputs the files \file{supp-pdf.tex} and +\file{supp-mis.tex}. The file \file{pdftex.def} is supplied with the +\prog{graphics} package. The other two are usually supplied with a +\pdfTeX{} distribution, and are definitely part of the \ConTeXt{} +distribution. 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. +If they have not been input, \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. + +\subsubsection{\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 choke 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}, much 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, other 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, 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{ex} + \cs{dashed}\cs{gfill}\cs{rect}\marg{(0,0),(1,1)} +\end{ex} +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 outline. + +\subsubsection{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{cd} +\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{cd} + +The following are the default definitions for \cs{setmfpicgraphic}: + +\medskip +\halign{#:\hfil&\quad#\hfil\cr +In plain \TeX& +\cs{def}\cs{setmfpicgraphic}\texttt{\#1}\marg{\cs{epsfbox}\marg{\#1}}\cr +In \LaTeX209& +\cs{def}\cs{setmfpicgraphic}\texttt{\#1}\marg{\cs{epsfbox}\marg{\#1}}\cr +In \LaTeXe& +\cs{def}\cs{setmfpicgraphic}\texttt{\#1}\marg{\cs{includegraphics}\marg{\#1}}\cr +In \pdfLaTeX& +\cs{def}\cs{setmfpicgraphic}\texttt{\#1}\marg{\cs{includegraphics}\marg{\#1}}\cr +In \pdfTeX& +\cs{def}\cs{setmfpicgraphic}\texttt{\#1}\marg{\cs{convertMPtoPDF}\marg{\#1}% + \marg{1}\marg{1}}\cr +} +\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 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 +without the option \opt{mplabels} since the \mfp{} code for +placing labels and captions and reserving space for the picture relies +on the picture having the dimensions given by the arguments to the +\cs{mfpic} command. With \opt{mplabels} plus \opt{truebbox} it will +probably 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. To test whether a proposed definition is completely +expandable, put +\begin{ex} +\cs{message}\marg{\texttt{***}% +\cs{setfilename}\marg{file}\marg{1}\texttt{***}} +\end{ex} +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. + + +\subsection{\prog{Mfpic} and the rest of the world} + +\subsubsection{The literature} + +There are at least two places 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. + +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{cyclic}, \cs{lines} and \cs{point} with respect to +\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: + +\medskip +\moveright\parindent +\vbox{% + \halign{#\qquad\hfil&#\hfil\cr + Old name: & New name:\cr + \cs{boosts} & \cs{boost}\cr + \cs{reflectsabout} & \cs{reflectabout}\cr + \cs{rotatesaround} & \cs{rotatearound}\cr + \cs{rotates} & \cs{rotate}\cr + \cs{scales} & \cs{scale}\cr + \cs{shifts} & \cs{shift}\cr + \cs{xscales} & \cs{xscale}\cr + \cs{xslants} & \cs{xslant}\cr + \cs{xyswaps} & \cs{xyswap}\cr + \cs{yscales} & \cs{yscale}\cr + \cs{yslants} & \cs{yslant}\cr + \cs{zscales} & \cs{zscale}\cr + \cs{zslants} & \cs{zslant}\cr + }% +} + +\medskip +\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: \mfp{} now supports +the \cs{usepackage} method of loading. + +\subsubsection{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{% + \subsection{Index of commands, options and parameters by page}} +\let\oldcs\cs +\renewcommand{\cs}[1]{\leavevmode\mytt{\llap{\char`\\}#1}} + +\InputIfFileExists{mfpman.ind}{}{\mfpindexheading} + +\let\cs\oldcs + +\columnseprule 0pt +\columnsep 35pt +\twocolumn[\subsection{List of commands by type}] +\parindent0pt +\parskip0pt plus .3pt\relax +\makeatletter +\let\item\@idxitem +\makeatother + +\subsubsection{Figures} + + \item \cs{arc} + \item \cs{axis} + \item \cs{btwnfcn} + \item \cs{chartbar} + \item \cs{circle} + \item \cs{closedcspline} + \item \cs{closedmfbezier} + \item \cs{closedqbeziers} + \item \cs{closedqspline} + \item \cs{cspline} + \item \cs{curve} + \item \cs{cyclic} + \item \cs{datafile} + \item \cs{ellipse} + \item \cs{fcncurve} + \item \cs{function} + \item \cs{graphbar} + \item \cs{histobar} + \item \cs{lines} + \item \cs{mfbezier} + \item \cs{mfobj} + \item \cs{parafcn} + \item \cs{piewedge} + \item \cs{plrfcn} + \item \cs{plrregion} + \item \cs{polygon} + \item \cs{polyline} + \item \cs{qbeziers} + \item \cs{qspline} + \item \cs{rect} + \item \cs{regpolygon} + \item \cs{sector} + \item \cs{tlabelcircle} + \item \cs{tlabelellipse} + \item \cs{tlabeloval} + \item \cs{tlabelrect} + \item \cs{turtle} + + +\subsubsection{Figure modifiers} + + \item \cs{arrow} + \item \cs{bclosed} + \item \cs{cbclosed} + \item \cs{connect}, \cs{endconnect} + \item \cs{cutoffafter} + \item \cs{cutoffbefore} + \item \cs{lclosed} + \item \cs{makesector} + \item \cs{partpath} + \item \cs{qbclosed} + \item \cs{reflectpath} + \item \cs{reverse} + \item \cs{rotatepath} + \item \cs{scalepath} + \item \cs{sclosed} + \item \cs{shiftpath} + \item \cs{slantpath} + \item \cs{subpath} + \item \cs{transformpath} + \item \cs{trimpath} + \item \cs{xscalepath} + \item \cs{xslantpath} + \item \cs{xyswappath} + \item \cs{yscalepath} + \item \cs{yslantpath} + + +\subsubsection{Figure renderers} + + \item \cs{dashed} + \item \cs{dotted} + \item \cs{draw} + \item \cs{gclear} + \item \cs{gclip} + \item \cs{gendashed} + \item \cs{gfill} + \item \cs{hatch} + \item \cs{lhatch} + \item \cs{plot} + \item \cs{plotdata} (sort of) + \item \cs{plotnodes} + \item \cs{polkadot} + \item \cs{rhatch} + \item \cs{shade} + \item \cs{tess} + \item \cs{thatch} + \item \cs{xhatch} + +\subsubsection{Lengths} + + + \item \cs{axisheadlen} + \item \cs{dashlen} + \item \cs{dotsize} + \item \cs{dotspace} + \item \cs{hashlen} + \item \cs{hatchspace} + \item \cs{headlen} + \item \cs{mfpiccaptionskip} + \item \cs{mfpicheight} + \item \cs{mfpicunit} + \item \cs{mfpicwidth} + \item \cs{pointsize} + \item \cs{polkadotspace} + \item \cs{shadespace} + \item \cs{sideheadlen} + \item \cs{symbolspace} + +\subsubsection{Coordinate transformation} + + \item \cs{applyT} + \item \cs{boost} + \item \cs{coords}, \cs{endcoords} + \item \cs{mirror} + \item \cs{reflectabout} + \item \cs{rotate} + \item \cs{rotatearound} + \item \cs{scale} + \item \cs{shift} + \item \cs{turn} + \item \cs{xscale} + \item \cs{xslant} + \item \cs{xyswap} + \item \cs{yscale} + \item \cs{yslant} + \item \cs{zscale} + \item \cs{zslant} + +\subsubsection{Axes, grids, and marks} + + \item \cs{axes} + \item \cs{axis} + \item \cs{axismarks} + \item \cs{bmarks} + \item \cs{doaxes} + \item \cs{grid} + \item \cs{gridarcs} + \item \cs{gridlines} + \item \cs{gridpoints} + \item \cs{gridrays} + \item \cs{hgridlines} + \item \cs{lattice} + \item \cs{lmarks} + \item \cs{plotsymbol} + \item \cs{plrgrid} + \item \cs{plrgridpoints} + \item \cs{plrpatch} + \item \cs{point} + \item \cs{rmarks} + \item \cs{tmarks} + \item \cs{vgridlines} + \item \cs{xaxis} + \item \cs{xmarks} + \item \cs{yaxis} + \item \cs{ymarks} + +\subsubsection{Setting options} + + \item \cs{clearsymbols} + \item \cs{clipmfpic} + \item \cs{mfpicdebugfalse} + \item \cs{mfpicdebugtrue} + \item \cs{mfpicdraft} + \item \cs{mfpicfinal} + \item \cs{mfpicnowrite} + \item \cs{nocenteredcaptions} + \item \cs{noclearsymbols} + \item \cs{noclipmfpic} + \item \cs{nomplabels} + \item \cs{nooverlaylabels} + \item \cs{noship} + \item \cs{notruebbox} + \item \cs{overlaylabels} + \item \cs{resumeshipping} + \item \cs{stopshipping} + \item \cs{usecenteredcaptions} + \item \cs{usemetafont} + \item \cs{usemetapost} + \item \cs{usemplabels} + \item \cs{usetruebbox} + +\subsubsection{Changing values} + + \item \cs{axismargin} + \item \cs{darkershade} + \item \cs{dashlineset} + \item \cs{dashpattern} + \item \cs{dotlineset} + \item \cs{drawpen} + \item \cs{hatchwd} + \item \cs{headshape} + \item \cs{lightershade} + \item \cs{mfpicnumber} + \item \cs{mfplinestyle} + \item \cs{mfplinetype} + \item \cs{pen} + \item \cs{penwd} + \item \cs{polkadotwd} + \item \cs{setallaxismargins} + \item \cs{setallbordermarks} + \item \cs{setaxismargins} + \item \cs{setaxismarks} + \item \cs{setbordermarks} + \item \cs{setmfvariable} + \item \cs{setmpvariable} + \item \cs{settension} + \item \cs{setxmarks} + \item \cs{setymarks} + \item \cs{shadewd} + +\subsubsection{Changing colors} + + \item \cs{backgroundcolor} + \item \cs{drawcolor} + \item \cs{fillcolor} + \item \cs{hatchcolor} + \item \cs{headcolor} + \item \cs{mfpdefinecolor} + \item \cs{pointcolor} + \item \cs{tlabelcolor} + +\subsubsection{Defining arrays} + + \item \cs{barchart} + \item \cs{bargraph} + \item \cs{histogram} + \item \cs{numericarray} + \item \cs{pairarray} + \item \cs{patharr}, \cs{endpatharr} + \item \cs{piechart} + +\subsubsection{Changing behavior} + + \item \cs{clearsymbols} + \item \cs{coloredlines} + \item \cs{dashedlines} + \item \cs{datapointsonly} + \item \cs{defaultplot} + \item \cs{everytlabel} + \item \cs{makepercentcomment} + \item \cs{makepercentother} + \item \cs{mfpdatacomment} + \item \cs{mfpdataperline} + \item \cs{mfpverbtex} + \item \cs{noclearsymbols} + \item \cs{pointedlines} + \item \cs{pointfillfalse} + \item \cs{pointfilltrue} + \item \cs{reconfigureplot} + \item \cs{setrender} + \item \cs{smoothdata} + \item \cs{tlabeljustify} + \item \cs{tlabeloffset} + \item \cs{tlabelsep} + \item \cs{tlpathjustify} + \item \cs{unsmoothdata} + \item \cs{using} + \item \cs{usingnumericdefault} + \item \cs{usingpairdefault} + +\subsubsection{Files and environments} + + \item \cs{closegraphsfile} + \item \cs{mfpframe}, \cs{endmfpframe} + \item \cs{mfpic}, \cs{endmfpic} + \item \cs{opengraphsfile} + +\subsubsection{Text} + + \item \cs{axislabels} + \item \cs{plottext} + \item \cs{tcaption} + \item \cs{tlabels} + \item \cs{tlabel} + +\subsubsection{Misc} \widowpenalty10000 + + \item \cs{fdef} + \item \cs{getmfpicoffset} + \item \cs{ifmfpmpost} + \item \cs{mfcmd} + \item \cs{mflist} + \item \cs{mfpframed} + \item \cs{mfpicversion} + \item \cs{mfpverbtex} + \item \cs{mfsrc} + \item \cs{mftitle} + \item \cs{newfdim} + \item \cs{newsavepic} + \item \cs{plr} + \item \cs{pointdef} + \item \cs{preparemfpicgraphic} + \item \cs{savepic} + \item \cs{setmfpicgraphic} + \item \cs{setfilename} + \item \cs{sequence} + \item \cs{store} + \item \cs{tile}, \cs{endtile} + \item \cs{tmtitle} + \item \cs{usepic} + + +\end{document} + |