diff options
Diffstat (limited to 'Master/texmf-dist/doc/generic/mfpic/mfpic-doc.tex')
| -rw-r--r-- | Master/texmf-dist/doc/generic/mfpic/mfpic-doc.tex | 497 |
1 files changed, 292 insertions, 205 deletions
diff --git a/Master/texmf-dist/doc/generic/mfpic/mfpic-doc.tex b/Master/texmf-dist/doc/generic/mfpic/mfpic-doc.tex index c818579dfd1..f4aeb3a2ff4 100644 --- a/Master/texmf-dist/doc/generic/mfpic/mfpic-doc.tex +++ b/Master/texmf-dist/doc/generic/mfpic/mfpic-doc.tex @@ -1,13 +1,16 @@ -%%% File: mfpic-doc.tex -%%% A part of mfpic 1.05 2010/06/10 -%%% +% File: mfpic-doc.tex +% A part of mfpic 1.06 2011/03/08 +% % Documentation of mfpic macros \documentclass[letterpaper]{article} -% Fonts: TimesRoman, CM Sans serif, and LuxiMono for TeX commands. +% Fonts: +% Body text: TimesRoman, +% Titles: CM Sans serif, +% Typewriter: LuxiMono. \usepackage[T1]{fontenc} \usepackage{mathptmx} -\usepackage[scaled=.85]{luximono} +\usepackage[scaled]{luximono} \renewcommand\sfdefault{cmss} \newcommand\sgn{\mathop{\mathrm{sgn}}\nolimits} % Fake chapters (really sections): @@ -29,7 +32,7 @@ \stepcounter{secnumdepth} \title{\Mfp{}: Pictures in \TeX{}\\ with Metafont and -MetaPost\thanks{Copyright 2002--2010, Daniel H. Luecking}} +MetaPost\thanks{Copyright 2002--2011, Daniel H. Luecking}} \author{% Daniel H. Luecking% @@ -39,7 +42,7 @@ Daniel H. Luecking% \and Thomas E. Leathrum \and Geoffrey Tobin} -\date{\mfpdate} +\date{\mfpfiledate} \begin{document} @@ -118,22 +121,19 @@ Acknowledgements. \section{What?}\label{manifest} See the \file{README} file for a list of files in the distribution and a -brief explanation of each. Only four are actually needed for full access -to \mfp{}'s capabilities: \file{mfpic.dtx}, \file{mfpic.ins}, -\file{grafbase.dtx} and \file{mfppatch.tex}. Running \LaTeX{} on +brief explanation of each. Only three are actually needed for full access +to \mfp{}'s capabilities: \file{mfpic.dtx}, \file{mfpic.ins} and +\file{grafbase.dtx}. Running \LaTeX{} on \file{mfpic.ins} creates the only required files: \begin{display} - \file{mfpic.tex} and \file{mfpic.sty}, the latter required only for - \LaTeX{}.\\ - \file{grafbase.mf}, required only if \MF{} will be processing - figures.\\ - \file{grafbase.mp} and \file{dvipsnam.mp}, needed only if \MP{} will - be the processor.\\ - \file{mfppatch.tex} is used to distribute simple bug fixes. It does - nothing after a major update, but if it is not installed and a - previous one is, a warning will be issued. + \file{mfpic.tex} and \file{mfpic.sty}, the latter required only for + \LaTeX{}.\\ + \file{grafbase.mf}, required only if \MF{} will be processing + figures.\\ + \file{grafbase.mp} and \file{dvipsnam.mp}, needed only if \MP{} will + be the processor. \end{display} -The README file also gives some guidence on the proper location for the +The file \file{install.txt} gives some guidance on the proper location for the installation of these files. \section{How?}\label{process} @@ -154,7 +154,7 @@ no file \file{pics.1}, but \TeX{} will continue processing the file anyway. When \TeX{} is finished, you will now have a file called \file{pics.mp}. This is the \MP{} file containing the descriptions of the pictures for \file{pictures.tex}. You need to run \MP{} on -\file{pics.mp} (Read your \MF{} manual to see how to do +\file{pics.mp} (Read your \MP{} manual to see how to do this.% \footnote{The document \textit{Some experiences on running Metafont and MetaPost}, by Peter Wilson, can be useful for beginners. Fetch @@ -165,14 +165,18 @@ Typically, you just type \begin{verbatim} mpost pics.mp \end{verbatim} -(or possibly ``\verb$mp pics.mp$'', but try ``\verb$mpost$'' first). -This produces files \file{pics.1}, \file{pics.2}, etc., the number of -files depending on the version of \file{pictures.tex}. You then -reprocess \file{pictures.tex} with \TeX{} to produce a DVI file. This -file can then be processed with \prog{dvips} (for example) to produce -\PS{} output which can be printed or viewed. One can also process the -DVI with \prog{dvipdfm(x)} to produce a PDF file. +This usually produces files named% + \footnote{Recent \MP{} allows one to change the default names of the + output files. Current \mfp{} provides an interface to that + capability: see \cs{setfilenametemplate} on page + \pageref{setfilenametemplate}.} +\file{pics.1}, \file{pics.2}, etc., the number of files depending on the +version of \file{pictures.tex}. You then reprocess \file{pictures.tex} +with \TeX{} to produce a DVI file. This file can then be processed with +\prog{dvips} (for example) to produce \PS{} output which can be printed +or viewed. One can also process the DVI with \prog{dvipdfm(x)} to +produce a PDF file. If \pdfTeX{} is used instead of \TeX{} on the second run, you should be able to view the resulting PDF file immediately, without any further @@ -315,16 +319,11 @@ options are processed. You can create such a file containing an have as default. Actual options to \cs{usepackage} will override these defaults, of course. And so will any of the commands below. -If a file named \file{mfpic.usr} can be found, it will be input at the +Finally, if a file named \file{mfpic.usr} can be found, it will be input at the end of the loading of \mfp{}. The user can create such a file containing any of the commands of this section that he would like to have as -default. +default, plus any other \TeX{} code. -Finally, if the file \file{mfppatch.tex} can be found, it will be input -slightly before the end of loading \mfp{}. It is part of the \mfp{} -distribution, and will be used to implement minor corrections when bugs -are found. The user should \emph{not} modify this file unless -he really knows what he is doing. \section{\opt{metapost}, \opt{metafont}, \cs{usemetapost}, \cs{usemetafont}.}% \label{metapost}\index{metapost@\opt{metapost}}\index{usemetapost@\cs{usemetapost}}% @@ -414,8 +413,8 @@ subsequent figures, inside a figure they affect all subsequent text in that figure. The commands and option are ignored under the metafont option. -\section{\opt{truebbox}, \cs{usetruebbox}, -\cs{notruebbox}.}\label{truebbox} +\section{\opt{truebbox}, \cs{usetruebbox}, \cs{notruebbox}.}% +\label{truebbox}% \index{truebbox@\opt{truebbox}}% \index{usetruebbox@\cs{usetruebbox}}% \index{notruebbox@\cs{notruebbox}} @@ -442,17 +441,18 @@ bounding box. Thus, anything running outside those bounds is lost. \index{clipmfpic@\cs{clipmfpic}}% \index{noclipmfpic@\cs{noclipmfpic}} -Causes all parts of the figure outside the rectangle specified by the -\cs{mfpic} command to be removed. The commands can come anywhere. If -issued inside an \env{mfpic} environment they affect the current figure -only. Otherwise all subsequent figures are affected. Note: this is a -rather rudimentary option. It has an often unexpected interaction with -truebbox. When both are in effect, \MP{} will produce a bounding box -that is the intersection of two rectangles: the true one \emph{without -clipping}, and the clipping rectangle (i.e., the one specified in the -\cs{mfpic} command). It is possible for the actual figure to be much -smaller than this bounding box (even empty!). This is a property of the -\MP{} \gbc{clip} command and we know of no way to avoid it. +The \opt{clip} option causes all parts of the figure outside the +rectangle specified by the \cs{mfpic} command to be removed. The +commands can come anywhere. If issued inside an \env{mfpic} environment +they affect the current figure only. Otherwise all subsequent figures +are affected. Note: this is a rather rudimentary option. It has an often +unexpected interaction with truebbox. When both are in effect, \MP{} +will produce a bounding box that is the intersection of two rectangles: +the true one \emph{without clipping}, and the clipping rectangle (i.e., +the one specified in the \cs{mfpic} command). It is possible for the +actual figure to be much smaller than this bounding box (even empty!). +This is a property of the \MP{} \gbc{clip} command and we know of no way +to avoid it. \section{\opt{centeredcaptions}, \cs{usecenteredcaptions}, @@ -461,9 +461,9 @@ smaller than this bounding box (even empty!). This is a property of the \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.% +The \opt{centeredcaptions} option 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} @@ -480,11 +480,12 @@ be used in the argument of a \cs{tcaption} command. \index{useraggedcaptions@\cs{useraggedcaptions}}% \index{noraggedcaptions@\cs{noraggedcaptions}} -Causes multiline captions created by \cs{tcaption} to have all lines -raggedright. If \opt{centeredcaptions} is on, both sides will be ragged. -The command \cs{noraggedcaptions} restores the default: all lines except -the last justified. The last is either centered or flush left according -to whether \opt{centeredcaptions} is on or off. +The \opt{raggedcaptions} option causes multiline captions created by +\cs{tcaption} to have raggedright lines. If \opt{centeredcaptions} +is on, both sides will be ragged. The command \cs{noraggedcaptions} +restores the default: all lines except the last justified. The last is +either centered or flush left according to whether +\opt{centeredcaptions} is on or off. The commands can be issued anywhere. If inside an \env{mfpic} environment they should come before the \cs{tcaption} command and affect @@ -497,12 +498,13 @@ be used in the argument of a \cs{tcaption} command. \index{mfpicdebugtrue@\cs{mfpicdebugtrue}}% \index{mfpicdebugfalse@\cs{mfpicdebugfalse}} -Causes \mfp{} to write a rather large amount of information to the -\file{.log} file and sometimes to the terminal. Debug information -generated by \file{mfpic.tex} \emph{while loading} is probably of -interest only to developers, but can be turned on by giving a definition -to the command \cs{mfpicdebug} prior to loading. Any definition will -work because \prog{mfpic} only checks whether it is defined. +The \opt{debug} option causes \mfp{} to write a rather large amount of +information to the \file{.log} file and sometimes to the terminal. Debug +information generated by \file{mfpic.tex} \emph{while loading} is +probably of interest only to developers, but can be turned on by giving +a definition to the command \cs{mfpicdebug} prior to loading. Any +definition will work because \prog{mfpic} only checks whether it is +defined. \section{\opt{clearsymbols}, \cs{clearsymbols}, \cs{noclearsymbols}.} \index{clearsymbols@\opt{clearsymbols}}% @@ -573,11 +575,11 @@ can be used. From version 0.8, there exists a scheme to allow \MF{} or \MP{} to pass information back to the \file{.tex} file. This is done by writing code to the figure file requesting \MF{} to place that information in the -\file{.log} file it produces. This option instructs \mfp{} to -read through that log file line-by-line looking for such information. -Since such log files can be potentially quite lengthy, this is made an -option. If the command form \cs{mfpreadlog} is used, it must come before -the \cs{opengraphsfile} command, since that is when the file will be +\file{.log} file it produces. This option instructs \mfp{} to read +through that log file line-by-line looking for such information. Since +such log files can be potentially quite lengthy, this is made an option. +If the command form \cs{mfpreadlog} is used, it must come before the +\cs{opengraphsfile} command, since that is when the file will be examined. At the present time, the only \mfp{} facility that requires this two-way communication is \cs{assignmfvalue} (see subsection~\ref{misc}). If this is used, the filename given to @@ -607,13 +609,12 @@ document that fact, please let me know. The following are special: \begin{display} -\cs{usemetapost}\index{usemetapost@\cs{usemetapost}}, -\cs{usemetafont}\index{usemetafont@\cs{usemetafont}}, -\cs{mfpicdraft}\index{mfpicdraft@\cs{mfpicdraft}}, -\cs{mfpicfinal}\index{mfpicfinal@\cs{mfpicfinal}}, -\cs{mfpicnowrite}\index{mfpicnowrite@\cs{mfpicnowrite}},\\ -and -\cs{mfpreadlog}\index{mfpreadlog@\cs{mfpreadlog}}. + \cs{usemetapost}\index{usemetapost@\cs{usemetapost}}, + \cs{usemetafont}\index{usemetafont@\cs{usemetafont}}, + \cs{mfpicdraft}\index{mfpicdraft@\cs{mfpicdraft}}, + \cs{mfpicfinal}\index{mfpicfinal@\cs{mfpicfinal}}, + \cs{mfpicnowrite}\index{mfpicnowrite@\cs{mfpicnowrite}},\\ + and \cs{mfpreadlog}\index{mfpreadlog@\cs{mfpreadlog}}. \end{display} \noindent Their effects are always global, partly because they should occur prior to the initialization command \cs{opengraphsfile} (described @@ -722,7 +723,7 @@ name without actually drawing it. However, because of their complexity, objects of type \kw{picture} require somewhat more care than paths or other data types. Do not expect to use stored pictures in the same way as stored paths. In fact, one should use \kw{picture} variables only in -those command that are explicitely designed for them. In \mfp{} to date +those command that are explicitly designed for them. In \mfp{} to date these are only \cs{tile...}\cs{endtile} and \cs{mfpimage} to store pictures, and \cs{putmfpimage} to draw copies of one. There is also \cs{tess}, but it is used only to fill a region with copies of a picture @@ -800,13 +801,13 @@ file and open another, and even to change between \opt{metapost} and maintainer and it might be fixed in some later version. There may be limitations on what can be used as a filename. As of \mfp{} -version \mfpversion, we have tried to permit \cs{jobname} as part of +version 1.00, we have tried to permit \cs{jobname} as part of \meta{file}. Thus we permit \TeX{} macros, but they should expand to non-special characters. Permitting macros makes it essentially impossible for the filename to contain the backslash and brace characters. Also spaces are problematic. However other special \TeX{} characters (for example: tilde, underscore and percent) can be used, -though that is really not recommended. +though that is not recommended. \begin{cd}\pagelabel{mfpic} \cs{mfpic}\oarg{\meta{xfactor}}\oarg{\meta{yfactor}}% @@ -1016,19 +1017,19 @@ Draws small symbols centered at the points \meta{$p_0$}, \meta{$p_1$}, and so on. The symbols must be given by name, and the available symbols are: \begin{display} -\gbc{Asterisk}\index{Asterisk@\gbc{Asterisk}}, -\gbc{Circle}\index{Circle@\gbc{Circle}}, -\gbc{Diamond}\index{Diamond@\gbc{Diamond}}, -\gbc{Square}\index{Square@\gbc{Square}}, -\gbc{Triangle}\index{Triangle@\gbc{Triangle}}, -\gbc{Star}\index{Star@\gbc{Star}}, -\gbc{SolidCircle}\index{SolidCircle@\gbc{SolidCircle}},\\ -\gbc{SolidDiamond}\index{SolidDiamond@\gbc{SolidDiamond}}, -\gbc{SolidSquare}\index{SolidSquare@\gbc{SolidSquare}}, -\gbc{SolidTriangle}\index{SolidTriangle@\gbc{SolidTriangle}}, -\gbc{SolidStar}\index{SolidStar@\gbc{SolidStar}}, -\gbc{Cross}\index{Cross@\gbc{Cross}} and -\gbc{Plus}\index{Plus@\gbc{Plus}}. + \gbc{Asterisk}\index{Asterisk@\gbc{Asterisk}}, + \gbc{Circle}\index{Circle@\gbc{Circle}}, + \gbc{Diamond}\index{Diamond@\gbc{Diamond}}, + \gbc{Square}\index{Square@\gbc{Square}}, + \gbc{Triangle}\index{Triangle@\gbc{Triangle}}, + \gbc{Star}\index{Star@\gbc{Star}}, + \gbc{SolidCircle}\index{SolidCircle@\gbc{SolidCircle}},\\ + \gbc{SolidDiamond}\index{SolidDiamond@\gbc{SolidDiamond}}, + \gbc{SolidSquare}\index{SolidSquare@\gbc{SolidSquare}}, + \gbc{SolidTriangle}\index{SolidTriangle@\gbc{SolidTriangle}}, + \gbc{SolidStar}\index{SolidStar@\gbc{SolidStar}}, + \gbc{Cross}\index{Cross@\gbc{Cross}} and + \gbc{Plus}\index{Plus@\gbc{Plus}}. \end{display} The names should be self-explanatory, the `\gbc{Solid}' ones are filled in, the others are outlines. Under \opt{metapost}, symbols are drawn in @@ -1043,24 +1044,23 @@ symbols. The command \cs{symbol} was already taken (standard \LaTeX{}). While one would rarely want to use them for this purpose, the following symbols are also available: \begin{display} -\gbc{Arrowhead}\index{Arrowhead@\gbc{Arrowhead}}, -\gbc{Crossbar}\index{Crossbar@\gbc{Crossbar}}, -\gbc{Leftbar}\index{Leftbar@\gbc{Leftbar}}, -\gbc{Rightbar}\index{Rightbar@\gbc{Rightbar}}, -\gbc{Lefthook}\index{Lefthook@\gbc{Lefthook}}, -\gbc{Righthook}\index{Righthook@\gbc{Righthook}}, -\gbc{Leftharpoon}\index{Leftharpoon@\gbc{Leftharpoon}},\\ -\gbc{Rightharpoon}\index{Rightharpoon@\gbc{Rightharpoon}}. + \gbc{Arrowhead}\index{Arrowhead@\gbc{Arrowhead}}, + \gbc{Crossbar}\index{Crossbar@\gbc{Crossbar}}, + \gbc{Leftbar}\index{Leftbar@\gbc{Leftbar}}, + \gbc{Rightbar}\index{Rightbar@\gbc{Rightbar}}, + \gbc{Lefthook}\index{Lefthook@\gbc{Lefthook}}, + \gbc{Righthook}\index{Righthook@\gbc{Righthook}}, + \gbc{Leftharpoon}\index{Leftharpoon@\gbc{Leftharpoon}},\\ + \gbc{Rightharpoon}\index{Rightharpoon@\gbc{Rightharpoon}}. \end{display} These are mainly intended for making arrows. See subsection~\ref{arrows} for a further description. -The difference between \cs{pointfillfalse}\cs{point}$\ldots$ and -\cs{plotsymbol}\marg{Circle}$\ldots$ is that the inside of the circle -will not be erased in the second version, so whatever else has already -been drawn in that area will remain visible. This is the default (for -backward compatibility), but that can be changed with the commands -below. +The difference between \cs{pointfillfalse}\cs{point} and +\cs{plotsymbol}\marg{Circle} is that the inside of the circle will not +be erased in the second version, so whatever else has already been drawn +in that area will remain visible. This is the default (for backward +compatibility), but that can be changed with the commands below. \begin{cd}\pagelabel{clearsymbols} \cs{clearsymbols}\\ @@ -1258,7 +1258,7 @@ be affected. These are figure macros that draw the line or lines that an \cs{axis} command would draw. An \cs{axis} command is almost the equivalent of \begin{display} -\cs{arrow}\oarg{l\meta{hlen}}\cs{axisline}\marg{\meta{one-axis}}. + \cs{arrow}\oarg{l\meta{hlen}}\cs{axisline}\marg{\meta{one-axis}}. \end{display} The \cs{axisline} command is provided as a figure macro for maximum flexibility. For example, one can use the star-form of the \cs{arrow} @@ -1400,15 +1400,14 @@ value. The last two commands are abbreviations for \cs{setaxismarks}\marg{x}\marg{\meta{pos}} and \cs{setaxismarks}\marg{y}\marg{\meta{pos}}, respectively. -Not all combinations make sense (for example, -\cs{setaxismarks}\marg{r}\marg{ontop}). In these cases, no error message -is produced: \gbc{ontop} and \gbc{onleft} give the same results, as do -\gbc{onbottom} and \gbc{onright}. The parameters \gbc{inside} and -\gbc{outside} make no sense for the $x$- and $y$-axes, but if they are -used then \gbc{inside} means \gbc{ontop} for the $x$-axis and -\gbc{onright} for the $y$-axis. These words are actually \MF{} numeric -variables and the variables \gbc{ontop} and \gbc{onleft}, for example, -have the same value. +Not all combinations make sense (for example, \texttt{ontop} for the +right side axis). In these cases, no error message is produced: +\gbc{ontop} and \gbc{onleft} give the same results, as do \gbc{onbottom} +and \gbc{onright}. The parameters \gbc{inside} and \gbc{outside} make no +sense for the $x$- and $y$-axes, but if they are used then \gbc{inside} +means \gbc{ontop} for the $x$-axis and \gbc{onright} for the $y$-axis. +These words are actually \MF{} numeric variables and the variables +\gbc{ontop} and \gbc{onleft}, for example, have the same value. \begin{cd}\pagelabel{grid} \cs{grid}\oarg{\meta{size}}\marg{\meta{xsep},\meta{ysep}}\\ @@ -2047,10 +2046,10 @@ several have been predefined. The colors \mfc{red}, \mfc{green}, \mfc{blue}, \mfc{white} and \mfc{black} are built in to \MP{} and are of type \kw{rgbcolor}. Colors \gbc{cyan}, \gbc{magenta} and \gbc{yellow} are defined by \mfp{}'s \MP{} support macros to be \kw{cmykcolor}. In -addition, \mfp{} defines \gbc{cmykblack}, \gbc{cmykwhite}, -\gbc{rgbblack}, \gbc{rgbwhite}, \gbc{grayscaleblack} and -\gbc{grayscalewhite}. These give black and white in the indicated data -type (grayscale being a numeric: $0$ for black, $1$ for white). +addition, \mfp{} defines \gbc{grayscaleblack}, \gbc{grayscalewhite}, +\gbc{cmykblack}, \gbc{cmykwhite}, \gbc{rgbblack} and \gbc{rgbwhite}. +These give black and white in the indicated data type (grayscale being a +numeric: $0$ for black, $1$ for white). All the names in the \LaTeX{} \prog{color} package's \file{dvipsnam.def} have also been predefined by \mfp{} as color variable names. Since \MP{} @@ -2149,7 +2148,7 @@ colors produce a black in the appropriate model. Then one can use \draw{.5*RGB(255,0,0) + .5*makergb cmyk(1,0,0,0)}\circle{(0,0),1} \end{verbatim} % -If one didn't know that \mfc{RGB} returned an \kw{rgbcolor}, one +If one has forgotton whether \mfc{RGB} returns an \kw{rgbcolor}, one could write \verb$makergb RGB(255,0,0)$ to be sure to get an \kw{rgbcolor}. @@ -2191,11 +2190,12 @@ curve (with one exception, those drawn by \cs{plotdata}), whether solid, dashed, dotted, or plotted in symbols, will be in the color set by \cs{drawcolor}. Set the color used by \cs{gfill} with \cs{fillcolor}. For all the hatching commands use \cs{hatchcolor}. For the \cs{point}, -\cs{plotsymbol} and \cs{gridpoints} commands use \cs{pointcolor}, and -for arrowheads, \cs{headcolor}. One can set the color used by -\cs{gclear} with \cs{backgroundcolor} (the same color will also be used -in the interior of unfilled points that are drawn with \cs{point}) and, -when \opt{mplabels} is in effect, the color of labels can be set with +and \cs{plotsymbol} commands, as well as \cs{gridpoints} and +\cs{plrgridpoints}, use \cs{pointcolor}, and for arrowheads, +\cs{headcolor}. One can set the color used by \cs{gclear} with +\cs{backgroundcolor} (the same color will also be used in the interior +of unfilled points that are drawn with \cs{point}) and, when +\opt{mplabels} is in effect, the color of labels can be set with \cs{tlabelcolor}. The optional \meta{model} may be one of \texttt{rgb}, \texttt{RGB}, @@ -2311,11 +2311,14 @@ same effect as \cs{gclear}. Some \mfp{} macros operate by \emph{modifying} a figure macro: if you want to turn an open arc into a closed figure by adding a straight line, -you can write: \cs{lclosed}\cs{arc}\marg{(0,0),(1,0),45}. These are -always prefixed to some figure drawing command, and apply only to the -next following figure macro provided that only other prefix commands -intervene. This is a rather long section, but even more modification -prefixes are documented in subsection~\ref{transformation}. +you can write: +\begin{ex} + \cs{lclosed}\cs{arc}\marg{(0,0),(1,0),45}. +\end{ex} +These are always prefixed to some figure drawing command, and apply only +to the next following figure macro provided that only other prefix +commands intervene. This is a rather long section, but even more +modification prefixes are documented in subsection~\ref{transformation}. The combination of a modifying macro, followed by a figure macro, can usually be thought of as a new figure macro, to which further prefixes @@ -2538,7 +2541,7 @@ complementary arc will have the same direction, clockwise or anticlockwise, as the original. The arc that follows doesn't have to be produced by \cs{arc}, as in the following example: \begin{ex} -\cs{draw}\oarg{blue}\cs{arccomplement}\\ + \cs{draw}\oarg{blue}\cs{arccomplement}\\ \ \cs{draw}\oarg{red}\cs{partpath}\marg{0,.333}\\ \ \cs{circle}\marg{(0,0),1} \end{ex} @@ -2748,8 +2751,9 @@ draw a curve and hatch its interior, \cs{draw}\cs{hatch} must be used. The default for \meta{color} is \gbc{drawcolor}. To save repetition, the color used for the following commands is also -\gbc{drawcolor}: \cs{dashed}, \cs{dotted}, \cs{doubledraw}, \cs{plot}, -\cs{plotnodes}, and \cs{gendashed}, +\gbc{drawcolor}:\\ +\cs{dashed}, \cs{dotted}, \cs{doubledraw}, \cs{plot}, \cs{plotnodes}, +and \cs{gendashed}, \begin{cd}\pagelabel{doubledraw} \cs{doubledraw}\oarg{\meta{sep}}\oarg{\meta{color}}$\ldots$ @@ -3012,8 +3016,8 @@ with dots. The diameter of the dots is the \MF{} variable \mfc{shadewd}, set by the macro \cs{shadewd}\marg{\meta{size}}. Normally this is \dim{0.5bp}. The optional argument specifies the spacing between (the centers of) the dots, which defaults to the \TeX{} dimension -\cs{shadespace}, initially \dim{1pt}. If \cs{shadespace} is less than -\mfc{shadewd}, the closed path is filled with black, as if with +\cs{shadespace}, initially \dim{1pt}. If \mfc{shadewd} is larger than +\cs{shadespace}, 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 @@ -3086,13 +3090,13 @@ These rendering macros are just \cs{thatch} with predefined values of the angle. \cs{lhatch} fills the region with left slanted lines (from upper left to lower right). It is exactly the same as \begin{display} -\cs{thatch}\oarg{\meta{hatchsp},-45}\oarg{\meta{color}}$\ldots$ + \cs{thatch}\oarg{\meta{hatchsp},-45}\oarg{\meta{color}}$\ldots$ \end{display} \cs{rhatch} draws right slanted lines (lower left to upper right). It is exactly the same as \begin{display} -\cs{thatch}\oarg{\meta{hatchsp},45}\oarg{\meta{color}}$\ldots$ + \cs{thatch}\oarg{\meta{hatchsp},45}\oarg{\meta{color}}$\ldots$ \end{display} \cs{hatch} (\cs{xhatch} is a synonym) draws lines in a cross-hatched @@ -3128,20 +3132,23 @@ 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. +For example, suppose one uses \cs{setrender}\marg{\cs{dashed}\cs{shade}} +in a \env{mfpic} environment. If the command \cs{circle}\marg{(0,0),1} +occurs later, it will produce a shaded circle with a dashed outline. If +an explicit rendering prefix is given in a drawing command, it will +override this default. + \subsection{Examples}\label{examples} It may be instructive, for the purpose of understanding the syntax of \emph{shape-modifier and rendering prefixes}, to consider two examples: \begin{ex} - \cs{draw}\cs{gfill}\oarg{red}\cs{lclosed}\cs{polyline}\marg{$\ldots$} + \cs{draw}\cs{gfill}\oarg{red}\cs{lclosed}\cs{polyline}\marg{$\ldots$} \end{ex} which fills inside a polygon and draws its outline; and \begin{ex} - \cs{gfill}[red]\cs{lclosed}\cs{draw}\cs{polyline}\marg{$\ldots$} + \cs{gfill}[red]\cs{lclosed}\cs{draw}\cs{polyline}\marg{$\ldots$} \end{ex} which draws all of the outline \emph{except} the line segment supplied by \cs{lclosed}, then fills the interior. Thus, in the first case the @@ -3254,16 +3261,16 @@ function will be smooth with a tension equal to the number. See the 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 +\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. +\meta{max}. If (\meta{max}${}-{}$\meta{min})/\meta{step} is not a whole +number, the nearest whole number of equal steps are used. One may have +to experiment with the size of \meta{step}, since \MF{} merely connects +the points corresponding to these steps with what \emph{it} considers to +be a smooth curve. Smaller \meta{step} gives better accuracy, but too +small may cause the curve to exceed \MF{}'s capacity or slow down its +processing. Increasing the tension may help keep the curve in line, but +at the expense of reduced smoothness. There are one or more subsequent arguments, each of which is a \MF{} function or expression as described above. All the macros are figure @@ -3413,6 +3420,12 @@ shading. However, drawing the boundary is often needed: \end{verbatim} shades one loop of the 4-petal rosette, and then draws it. +The next sets of macros are similar to the previous function plotting +macros, but don't fit the \meta{max}, \meta{min} \meta{step} model for +the first argument. For the first (\cs{levelcurve}) this is a limitation +of the task being performed. For the others (\cs{DEgraph}, +\cs{DEtrajectory}) it is a design choice. + \begin{cd}\pagelabel{levelcurve} \cs{levelcurve}\oarg{\meta{spec}}\marg{\meta{seed},\meta{step}} \marg{\meta{inequality}}% @@ -3476,6 +3489,72 @@ The algorithm used will produce imprecise results if there are two points on the curve closer than \meta{step} in straight-line distance, but much further apart when measured along the curve. +\begin{cd}\pagelabel{DEgraph} +\cs{DEgraph}\oarg{\meta{spec}}% + \marg{\meta{$x_0$},\meta{$y_0$},\meta{$\Delta s$},\meta{$N$}}% + \marg{$f(\mathtt{x},\mathtt{y})$}\\ +\cs{DEtrajectory}\oarg{\meta{spec}}% + \marg{\meta{$p_0$},\meta{$\Delta s$},\meta{$N$}}% + \marg{$\mathbf{F}(\mathtt{x},\mathtt{y},\mathtt{t})$}% +\index{DEgraph@\cs{DEgraph}}% +\index{DEtrajectory@\cs{DEtrajectory}}% +\end{cd} + +The first of these plots the graph of the solution of the differential +equation +$$ + \frac{dy}{dx} = f(x,y)\,,\quad y(x_0) = y_0\,. +$$ +The \meta{$\Delta s$} parameter is a step size and the \meta{$N$} +parameter is the number of steps. The step size is \emph{not} an +increment in the $x$ variable. Rather is is (roughly) the distance from +one point to the next along the graph as \MF{} computes them. That is, +\MF{} computes using a variable $x$-step $\Delta x$, chosen so that +$\sqrt{\Delta x^2 + \Delta y^2}$ is approximately \meta{$\Delta s$}. The +algorithm used is a modified 4-step Ringe-Kutta method. + +The second macro, \cs{DEtrajectory} draws the path traced by the +solution $(x(t),y(t))$ of +$$ + \left( \frac{dx}{dt},\frac{dy}{dt} \right) = \mathbf{F}(x,y,t)\,, + \quad (x(0),y(0)) = p_0\,. +$$ +This is not a \emph{graph}, since the dependence on $t$ cannot be shown +in two dimensions (a third dimension would be needed). The parameter +\meta{$p_0$} should be an ordered pair of numbers, the \meta{$\Delta s$} and +\meta{$N$} are as for \cs{DEgraph}. The function $\mathbf{F}(x,y,t)$ +should be either a pair-valued expression or an ordered pair of numeric +expressions. The variables must be literally \texttt{x}, \texttt{y} and +\texttt{t}. The expressions do not have to explicitly depend on these +variables. In fact, the \cs{DEgraph} macro is implemented using the same +internal macro as \cs{DEtrajectory} with $\mathbf{F}(x,y,t) = (1, +f(x,y))$ and $p_0 = (x_0,y_0)$. + +Notice that the trajectory starts at $t=0$. If you need some other +starting value $t=a$, then replace $t$ in the formula for +$\mathbf{F}(x,y,t)$ with $(t+a)$. + +It is possible to use a negative value of $\Delta s$ in both these +macros. For \cs{DEgraph} this produces the graph to the left of $x=x_0$, +and for \cs{DEtrajectory} it produces the trajectory with time running +backward. For the latter, it is also equivalent to replacing +$\mathbf{F}(x,y,t)$ by its negative. + +The purpose of making \meta{$\Delta s$} a distance rather than an +$x$-increment or a $t$-increment (as the Runge-Kutta method is taught in +the usual numerical analysis course) is stability: even very simple +differential equations can have graphs the tend to $\infty$ in finite +time. These macros, however, never travel more than a distance $N\Delta +s$ from the starting point. + +If you want to use \mfp{} to illustrate the results of the standard +Runge-Kutta method or other methods, you can use the \prog{mfpic4ode} +package. That package also includes the Euler method and the two-step +Runge-Kutta method. It loads \mfp{} if it has not already been loaded. +Like \mfp{}, it works in plain \TeX{} (with \verb$\input mfpic4ode$) or +\LaTeX{} (with \verb$\usepackage{mfpic4ode}$). + + \subsection{Plotting external data files}\label{external} \begin{cd}\pagelabel{datafile} @@ -3734,16 +3813,16 @@ below can be used to change the default dashes, colors, or symbols. The first argument of \cs{reconfigureplot} is the rendering method to be changed: \texttt{dashes}, \texttt{colors} or \texttt{symbols}. The second argument is a list of dash patterns, colors, or symbols. The dash -patterns should be names previously defined through the use of -\cs{dashpattern}. The colors can be any names already known to \MP{}, or -defined through \cs{mfpdefinecolor}. The symbols can be any of those -listed with the \cs{plotsymbol} command (subsection~\ref{points}), -or any known \MF{} path variable. The colors can also be \MP{} color -constants or expressions, and the symbols can be expressions of type -path. In recent \MP{} these `colors' can be \kw{numeric} (selecting -gray), \kw{rgbcolor} or \kw{cmykcolor}. Within a \env{mfpic} -environment, the changes made are local to that environment. Outside, -they affect all subsequent environments. +patterns should be names of patterns defined through the use of +\cs{dashpattern}. The colors can be any color names already known to +\MP{}, or defined through \cs{mfpdefinecolor}. The symbols can be any of +those listed with the \cs{plotsymbol} command (see +subsection~\ref{points}), or any known \MF{} path variable. The colors +can also be \MP{} color constants or expressions, and the symbols can be +expressions of type path. In recent \MP{} these `colors' can be +\kw{numeric} (selecting gray), \kw{rgbcolor} or \kw{cmykcolor}. Within a +\env{mfpic} environment, the changes made are local to that environment. +Outside, they affect all subsequent environments. Using \cs{reconfigureplot}\marg{colors} under the \opt{metafont} option will have no effect, but may produce an error from \MF{} unless the @@ -4236,8 +4315,8 @@ 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}}, + \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 @@ -4468,7 +4547,7 @@ Here are some examples of the use of \cs{store} and \cs{mfobj}. % one outline: \store{MyTriang}{\polyline{(-.5,-.5),(.5,-.5),(0,.5),(-.5,-.5)} % one solid: -\store{MySolidTriang}{\polygon{(-.5,-.5),(.5,-.5),(0,.5)} +\store{MySolidTriang}\polygon{(-.5,-.5),(.5,-.5),(0,.5)} % Use them as symbols: \plotsymbols{MyTriang}{(0,0),(2,2)} \arrowmid{MySolidTriang}\polyline{(1,1),(0,2)} @@ -5721,7 +5800,7 @@ true. Example: \mfcmd{R:=R/2} \endmfpwhile \end{verbatim} -There are no \mfp{} command to \emph{systematically} change a variable, +There are no \mfp{} commands to \emph{systematically} change a variable, so in this example we have resorted to directly writing a \MF{} assignment command via \cs{mfcmd} (see subsection~\ref{mfcode} above) that reduces \mfc{R} by half. The loop will be executed with \mfc{R} having the @@ -5748,7 +5827,10 @@ not contain an \cs{mfpuntil} command, then the \cs{endmfploop} command will generate a warning message. If the warning is ignored, and the user has not otherwise arranged for loop termination,% \footnote{Perhaps by means of \cs{mfsrc} commands. It is because of - this possibility that only a warning is produced and not an error.} + this possibility that only a warning is produced and not an error. + If the warning becomes annoying, adding \cs{mfpuntil\marg{false}} to + the loop will silence it. This command will never break the loop + because the condition \mfc{false} (of course) never becomes true.} the \file{.mf} file will contain an infinite loop. The \cs{mfpuntil} command will break the loop at whatever point it occurs. Example: \begin{verbatim} @@ -5765,11 +5847,11 @@ true, and the break occurs before the next rectangle is drawn. Note that any \cs{mfpwhile} could be encoded with \cs{mfploop}. In fact, the code written to the output file by \begin{display} -\cs{mfpwhile}\marg{\meta{condition}} + \cs{mfpwhile}\marg{\meta{condition}} \end{display} is identical to that written by \begin{display} -\cs{mfploop}\cs{mfpuntil}\marg{not \meta{condition}} + \cs{mfploop}\cs{mfpuntil}\marg{not \meta{condition}} \end{display} The command \cs{mfpuntil} can also be used in \env{mfpfor} and @@ -5879,9 +5961,9 @@ The `\texttt{global}' version makes the definition of the it can be used in other pictures. The plain versions create commands that are only locally defined. Past versions of this manual stated that you can say -\begin{display} - \cs{global}\cs{assignmfvalue} -\end{display} +\begin{ex} + \cs{global}\cs{assignmfvalue} +\end{ex} to define the macro globally. This turns out not to be true in all cases. If a global definition is needed, use the global versions above. @@ -6067,16 +6149,16 @@ further dicussion. \end{cd} With the \opt{metapost} option, when you write -\cs{opengraphsfile}\marg{figs}, a file \file{figs.mp} is created. By -default, running \MP{} on it results in files named \file{figs.1}, -\file{figs.2}, etc. Recent \MP{} allows the output filenames to be -modified. As of \mfp{} version 1.00, you can do this to some extent from -your \file{.tex} file. One needs to define a template that tells \MP{} -how to construct the output file name from the `jobname' and the figure -number. This is done with the above command. In \meta{template} you can -put any plain characters, plus the two special tokens: \verb$\_$ and -\verb$\#$. Each figure's filename is constructed by replacing these -tokens with the \MP{} jobname and the figure number, respectively. For +\cs{opengraphsfile}\marg{figs}, a file \file{figs.mp} is created. By +default, running \MP{} on it results in files named \file{figs.1}, +\file{figs.2}, etc. Recent \MP{} allows the output filenames to be +modified. As of \mfp{} version 1.00, you can do this to some extent from +your \file{.tex} file. One needs to define a template that tells \MP{} +how to construct the output file name from the `jobname' and the figure +number. This is done with the above command. In \meta{template} you can +put any plain characters, plus the two special tokens: \verb$\_$ and +\verb$\#$. Each figure's filename is constructed by replacing these +tokens with the \MP{} jobname and the figure number, respectively. For example, with the jobname \file{figs}, \begin{verbatim} \setfilenametemplate{my\_-\#.mps} @@ -6135,8 +6217,8 @@ with the \cs{opengraphsfile} commands reading of these booleans. \end{cd} This expands to the current \mfp{} version multiplied by 100. At this -writing, it produces `\texttt{105}' because the version is 1.05. It can -be used to test the version: +writing, it produces `\texttt{\mfpicversion}' because the version is +\mfpversion. It can be used to test the version: \begin{verbatim} \ifx\mfpicversion\undefined \def\mfpicversion{0}\fi \ifnum\mfpicversion<70 ... \else ... \fi @@ -6300,11 +6382,11 @@ all later environments. 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 patterns named \mfc{dashtype0} through -\mfc{dashtype5}, or predefined colors named \mfc{colortype0} through -\mfc{colortype7}, or predefined symbols named \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 +symbol. It uses predefined dash patterns named \mfc{dashtype0} through +\mfc{dashtype5}, or predefined colors named \mfc{colortype0} through +\mfc{colortype7}, or predefined symbols named \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 @@ -6379,9 +6461,9 @@ fonts prepared for a LaserJet4 (600 DPI), this means 6.825 inches (17.3355cm). For a 1200 DPI pronter, the limit is 3.4125 inches. A similar limit holds for numbers input, and the values of variables: -\MF{} will return an error for ``\mfc{sin 4096}''. Intermediate values -can be greater (\mfc{sin (2*2048)} will cause no error), but final, -stored results are subject to the limit. An \mfp{} example that +\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 @@ -6486,8 +6568,8 @@ occurrence. Example: 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 +used. Drawing is done with the center of the virtual pen stroked along +the boundary curve(s), so half of its width falls inside the rectangle. On the other hand, filling is done right up to the boundary. In this example, the dashed lines are drawn on top of part of the fill. In the reverse order, the fill would cover part of the dashed outline. @@ -6576,10 +6658,12 @@ 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{setfilename} merely inserts a dot between the two arguments.% + \footnote{Unless modified by \cs{setfilenametemplate}, of course. + See subsection~\ref{misc}.} +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} @@ -6609,7 +6693,7 @@ This author has personal knowledge of only one mathematical article which definitely uses \mfp{} to create diagrams, and that is this author's joint paper with J.~Duncan and C.~M.~McGregor: \textit{On the value of pi for norms in $\mathbf{R}^2$} in the College Mathematics -Journal, vol.~35, pages 84--92. Oddly enough, it was McGregor and not me +Journal, vol.~35, pages 84--92. Oddly enough, it was McGregor and not I who chose to use \mfp{} for the illustrations. There are at least two major publications where \mfp{} has garnered more @@ -6644,7 +6728,7 @@ given for \cs{wedge}: 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 commands +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} @@ -6713,23 +6797,24 @@ 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. +substitution will occur, say in a local directory together 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{}. +\prog{m4} and then (perhaps) \prog{dpic} to produce the output. The +\mfp{} code produced appears to be compatible with the current \mfp{}. \renewcommand\mfpindexheading{% \section{Index of commands, options and parameters.}} \let\oldcs\cs \renewcommand{\cs}[1]{\leavevmode\mytt{\llap{\char`\\}#1}} -\InputIfFileExists{mfpic-doc.ind}{}{\mfpindexheading} +\renewcommand\headingprefix[1]{\textbf{\large #1}} +\InputIfFileExists{\jobname.ind}{}{\mfpindexheading} \let\cs\oldcs @@ -6764,6 +6849,8 @@ produced appears to be compatible with the current \mfp{}. \item \cs{curve}, \cs{closedcurve}, \pageref{curve} \item \cs{cyclic}, \pageref{curve} \item \cs{datafile}, \pageref{datafile} + \item \cs{DEgraph}, \pageref{DEgraph} + \item \cs{DEtrajectory}, \pageref{DEgraph} \item \cs{ellipse}, \pageref{ellipse} \item \cs{fcncurve}, \pageref{fcncurve} \item \cs{fcnspline}, \pageref{fcnspline} |