diff options
Diffstat (limited to 'Master/texmf-dist/doc/metapost/base/source/mpman.tex')
-rw-r--r-- | Master/texmf-dist/doc/metapost/base/source/mpman.tex | 4221 |
1 files changed, 2449 insertions, 1772 deletions
diff --git a/Master/texmf-dist/doc/metapost/base/source/mpman.tex b/Master/texmf-dist/doc/metapost/base/source/mpman.tex index 4c75733f3ba..ed965965baf 100644 --- a/Master/texmf-dist/doc/metapost/base/source/mpman.tex +++ b/Master/texmf-dist/doc/metapost/base/source/mpman.tex @@ -1,13 +1,17 @@ +% $Id: mpman.tex,v 1.26 2005/04/13 12:57:28 karl Exp $ +% MetaPost manual, by John Hobby. License at end. \documentclass{article} % article is NOT the original style +% \usepackage{makeidx} \usepackage{fancyvrb} \usepackage{ctabbing} \RecustomVerbatimEnvironment {verbatim}{BVerbatim}{baseline=c} -\usepackage{epsf} -\usepackage[textwidth=6in,textheight=8.75in]{geometry} +\usepackage{graphicx} +\usepackage[textwidth=6in,textheight=8.65in]{geometry} \usepackage{tocloft} -\setlength\cftbeforesecskip{1.5ex plus 0.2ex minus 0.1ex} + \setlength\cftbeforesecskip{1.3ex plus 0.3ex minus 0.3ex} +\usepackage{url} \makeatletter \def\logo{\global\font\logo=logo10 at1\@ptsize\p@ \logo} @@ -16,10 +20,14 @@ {\logo META}\-{\logo FONT}}} \makeatother +\def\ttindex#1{{\tt #1}\index{#1?\texttt{#1}}} +\def\ttt{\texttt} % I get tired of typing this out + +\def\ConTeXt{Con\TeX t} % \def\MF{{META\-FONT}} % Replacement for the above when using times.sty -\newfont\psyvii{rpsyr at 7pt} +\newfont\psyvii{psyr at 7pt} \newcommand\reg{$^{\hbox{\psyvii\char'322}}$} % Registered trademark \newcommand\descr[1]{{\langle\hbox{#1}\rangle}} @@ -27,7 +35,7 @@ \newcommand\tdescr[1]{$\langle$\invisgap#1\invisgap$\rangle$} \newcommand\pl{\dag} -\newcommand\bx{\ddag} +\newcommand\bx{$*$} \newcommand\mathcenter[1]{\vcenter{\hbox{#1}}} @@ -35,7 +43,7 @@ \renewcommand{\topfraction}{.85} \renewcommand{\bottomfraction}{.7} \renewcommand{\textfraction}{.15} -\renewcommand{\floatpagefraction}{.66} +\renewcommand{\floatpagefraction}{.5} \renewcommand{\dbltopfraction}{.66} \renewcommand{\dblfloatpagefraction}{.66} \setcounter{topnumber}{9} @@ -49,20 +57,21 @@ \VerbatimFootnotes \author{John D. Hobby} \title{A User's Manual for MetaPost} -\date{} +\date{documented version: 0.99} \maketitle \begin{abstract} -The MetaPost system implements a picture-drawing language very much like Knuth's -\MF\ except that it outputs PostScript commands instead of run-length-encoded -bitmaps. MetaPost is a powerful language for producing figures for documents -to be printed on PostScript printers. It provides easy access to all the -features of PostScript and it includes facilities for integrating text and -graphics. +The MetaPost system implements a picture-drawing language very much like +Knuth's \MF\ except that it outputs PostScript commands instead of +run-length-encoded bitmaps. MetaPost is a powerful language for +producing figures for documents to be printed on PostScript printers. +It provides easy access to all the features of PostScript and it +includes facilities for integrating text and graphics. This document serves as an introductory user's manual. It does not require -knowledge of \MF\ or access to {\it The \MF book}, but both are beneficial. +knowledge of \MF\ or access to {\sl The \MF book}, but both are beneficial. An appendix explains the differences between MetaPost and \MF. + \end{abstract} \thispagestyle{empty} \newpage @@ -74,40 +83,41 @@ An appendix explains the differences between MetaPost and \MF. \setcounter{page}{1} \pagestyle{headings} \pagenumbering{arabic} -\setlength{\parskip}{1ex plus 0.5ex minus 0.2ex} +\setlength{\parskip}{.75ex plus 0.5ex minus 0.2ex} \section{Introduction} \label{intro} -MetaPost is a programming language much like Knuth's \MF\footnote{\MF\ is a -trademark of Addison Wesley Publishing company.}\index{metafont?\MF}~\cite{kn:c} -except that it outputs PostScript programs instead of bitmaps. Borrowed from \MF\ -are the basic tools for creating and manipulating pictures. These include numbers, -coordinate pairs, cubic splines, affine transformations, text strings, and boolean -quantities. Additional features facilitate integrating text and graphics and -accessing special features of PostScript\footnote{PostScript is a -trademark of Adobe Systems Inc.}\index{PostScript} such as clipping, shading, and -dashed lines. -Another feature borrowed from \MF\ is the ability to solve linear equations -that are given implicitly, thus allowing many programs to be written in a -largely declarative style. By building complex operations +MetaPost is a programming language much like Knuth's \MF\footnote{\MF\ +is a trademark of Addison Wesley Publishing +company.}\index{metafont?\MF}~\cite{kn:c} except that it outputs +PostScript programs instead of bitmaps. Borrowed from \MF\ are the +basic tools for creating and manipulating pictures. These include +numbers, coordinate pairs, cubic splines, affine transformations, text +strings, and boolean quantities. Additional features facilitate +integrating text and graphics and accessing special features of +PostScript\footnote{PostScript is a trademark of Adobe Systems +Inc.}\index{PostScript} such as clipping, shading, and dashed lines. +Another feature borrowed from \MF\ is the ability to solve linear +equations that are given implicitly, thus allowing many programs to be +written in a largely declarative style. By building complex operations from simpler ones, MetaPost achieves both power and flexibility. -MetaPost is particularly -well-suited to generating figures for technical documents where some aspects of a -picture may be controlled by mathematical or geometrical constraints that are -best expressed symbolically. In other words, MetaPost is not meant to take the -place of a freehand drawing tool or even an interactive graphics editor. -It is really a programming language for generating graphics, especially figures -for \TeX\footnote{\TeX\ is a trademark of the American Mathematical -Society.}\index{TeX?\TeX} and troff\index{troff} documents. -The figures can be integrated into a \TeX\ document via a freely available -program called {\tt dvips}\index{dvips} as shown in -Figure~\ref{fig0}.\footnote{The C -source for {\tt dvips} comes with the web2c \TeX\ distribution. Similar programs -are available from other sources.} A similar procedure works with troff: the -{\tt dpost} output processor includes PostScript figures when they are -requested via troff's {\tt \char`\\X} command. +MetaPost is particularly well-suited to generating figures for technical +documents where some aspects of a picture may be controlled by +mathematical or geometrical constraints that are best expressed +symbolically. In other words, MetaPost is not meant to take the place +of a freehand drawing tool or even an interactive graphics editor. It +is really a programming language for generating graphics, especially +figures for \TeX\footnote{\TeX\ is a trademark of the American +Mathematical Society.}\index{TeX?\TeX} and troff\index{troff} documents. +The figures can be integrated into a \TeX\ document via a freely +available program called {\tt dvips}\index{dvips} as shown in +Figure~\ref{fig0}.\footnote{The C source for {\tt dvips} comes with the +web2c \TeX\ distribution. Similar programs are available from other +sources.} A similar procedure works with troff: the {\tt dpost} output +processor includes PostScript figures when they are requested via +troff's {\tt \char`\\X} command. \begin{figure}[htp] $$ \def\fbox#1{\hbox{\vrule @@ -148,36 +158,70 @@ $$ \label{fig0} \end{figure} -To use MetaPost, you prepare an input file containing MetaPost code and then -invoke MetaPost, usually by giving a command of the form\index{mp?\texttt{mp}} -$$ {\tt mp}\, \descr{file name} $$ -(This syntax could be system dependent). -MetaPost input files\index{files!input} normally have names ending ``{\tt .mp}'' -but this part of the name can be omitted when invoking MetaPost. For an input -file {\tt foo.mp} -$$ \hbox{\tt mp foo} $$ -invokes MetaPost and produces output files with names like {\tt foo.1} and -{\tt foo.2}. Any terminal I/O is summarized in a -transcript\index{files!transcript}\index{transcript file} -file called {\tt foo.log}. This includes -error messages and any MetaPost commands entered interactively.% -\footnote{A {\tt *}\index{*?\texttt{*}} prompt is used for interactive input and a -{\tt **}\index{**?\texttt{**}} prompt -indicates that an input file name is expected. This can be avoided by invoking -MetaPost on a file that ends with an {\tt end}\index{end?\texttt{end}} command.} -The transcript file starts with a banner line that tells what version of MetaPost -you are using. - -This document introduces the MetaPost language, beginning with the features that -are easiest to use and most important for simple applications. The first few -sections describe the language as it appears to the novice user with key parameters -at their default values. Some features described in these sections are part of a -predefined macro package called Plain. Later sections summarize the -complete language and distinguish between primitives and preloaded macros -from the Plain macro package\index{Plain macros}. -Since much of the language is identical to Knuth's \MF, the appendix gives a -detailed comparison so that advanced users can learn more about MetaPost by -reading {\sl The \MF book\/}.~\cite{kn:c} +To use MetaPost, you prepare an input file containing MetaPost code and +then invoke MetaPost, usually by giving a command of the +form\index{mpost?\texttt{mpost}} +$$ {\tt mpost}\, \descr{filename} $$ +The syntax and program name itself are system-dependent; sometimes it is +named \texttt{mp}. MetaPost input +files\index{files!input} normally have names ending ``{\tt .mp}'' but +this part of the name can be omitted when invoking MetaPost. For an +input file {\tt foo.mp} +$$ \hbox{\tt mpost foo} $$ +invokes MetaPost and produces output files with names like {\tt foo.1} +and {\tt foo.2}. Any terminal I/O is summarized in a +transcript\index{files!transcript}\index{transcript file} file called +{\tt foo.log}. This includes error messages and any MetaPost commands +entered interactively.\footnote{A {\tt *}\index{*?\texttt{*}} prompt is +used for interactive input and a {\tt **}\index{**?\texttt{**}} prompt +indicates that an input file name is expected. This can be avoided by +invoking MetaPost on a file that ends with an {\tt +end}\index{end?\texttt{end}} command.} + +\label{Dmpversion}The transcript file starts with a banner line that +identifies the version of MetaPost you are using. You can also determine +the current version from within a MetaPost program via the +\texttt{mpversion} predefined constant string (this was introduced in +version 0.9). For instance: +$$\begin{verbatim} +if known mpversion: + message "mp = " \& mpversion; + if mpversion > "1.0": message "time has flown by" fi +fi; +\end{verbatim} +$$ +prints `{\tt mp = 0.9}'. (Incidentally, \texttt{>} does a simple ASCII +comparison of strings; that works here, because of our particular +version numbering---until and unless MetaPost reaches version 10!) +\index{Creator comment in PostScript output} +The version number is also included in the \texttt{Creator} comment in +the PostScript output. + +This document introduces the MetaPost language, beginning with the +features that are easiest to use and most important for simple +applications. The first few sections describe the language as it +appears to the novice user with key parameters at their default values. +Some features described in these sections are part of a predefined macro +package called Plain. Later sections summarize the complete language +and distinguish between primitives and preloaded macros from the Plain +macro package\index{Plain macros}. Since much of the language is +identical to Knuth's \MF, the appendix gives a detailed comparison so +that advanced users can learn more about MetaPost by reading {\sl The +\MF book\/} \cite{kn:c}. + +The MetaPost home page is \url{http://tug.org/metapost}. It has links +to much additional information, including many articles that have been +written about MetaPost. For general help, try the +\url{metapost@tug.org} mailing list; you can subscribe to this list at +\url{http://tug.org/mailman/listinfo/metapost}. + +The development is currently hosted at Sarovar; visit +\url{http://www.sarovar.org/projects/metapost} for the current +development team members, sources, and much else. + +Please report bugs and request enhancements either on the +\url{metapost@tug.org} list, or through Sarovar. (Please do not send +reports directly to Dr.\ Hobby any more.) \section{Basic Drawing Statements} @@ -189,41 +233,46 @@ $$ \hbox{\verb|draw (20,20)--(0,0)|} $$ draws\index{draw?\texttt{draw}} a diagonal line and $$ \hbox{\verb|draw (20,20)--(0,0)--(0,30)--(30,0)--(0,0)|} $$ draws a polygonal line like this: -$$ \epsfbox{manfig.0} $$ +$$ \includegraphics{manfig-0} $$ -What is meant by coordinates like \verb|(30,0)|? MetaPost uses the same default -coordinate system that PostScript\index{PostScript} does. This means that -\verb|(30,0)| is 30 units -to the right of the origin, where a unit is $1\over72$ of an inch. We shall refer -to this default unit as a +\label{Ddrawdot}MetaPost also has a \ttt{drawdot} command to print a +single point, as in \ttt{drawdot(30,0)}. + +What is meant by coordinates like \verb|(30,0)|? MetaPost uses the same +default coordinate system that PostScript\index{PostScript!coordinate +system} does. This +means that \verb|(30,0)| is 30 units to the right of the origin, where a +unit is $1\over72$ of an inch. We shall refer to this default unit as a {\sl PostScript point\/}\index{PostScript!point}\index{point!PostScript} -to distinguish it from the standard printer's point\index{point!printer's} -which is $1\over72.27$ inches. - -MetaPost uses the same names for units of measure that \TeX\ and \MF\ do. Thus -\verb|bp|\index{bp?\texttt{bp}}\label{Dbp} refers to PostScript points (``big points'') -and \verb|pt|\index{pt?\texttt{pt}}\label{Dpt} refers to printer's points. -Other units of measure -include \verb|in|\index{in?\texttt{in}}\label{Din} for inches, -\verb|cm|\index{cm?\texttt{cm}}\label{Dcm} for centimeters, -and \verb|mm|\index{mm?\texttt{mm}}\label{Dmm} for -millimeters. For example, +to distinguish it from the standard printer's +point\index{point!printer's} which is $1\over72.27$ inches. + +MetaPost uses the same names for units of measure that \TeX\ and \MF\ +do. Thus \verb|bp|\index{bp?\texttt{bp}}\label{Dbp} refers to +PostScript points (``big points'') and +\verb|pt|\index{pt?\texttt{pt}}\label{Dpt} refers to printer's points. +Other units of measure include +\verb|in|\index{in?\texttt{in}}\label{Din} for inches, +\verb|cm|\index{cm?\texttt{cm}}\label{Dcm} for centimeters, and +\verb|mm|\index{mm?\texttt{mm}}\label{Dmm} for millimeters. For +example, $$ \hbox{\verb|(2cm,2cm)--(0,0)--(0,3cm)--(3cm,0)--(0,0)|} $$ -generates a larger version of the above diagram. It is OK to say \verb|0| instead -\verb|0cm| because {\tt cm} is really just a conversion factor and {\tt 0cm} just -multiplies the conversion factor by zero. (MetaPost understands constructions -like {\tt 2cm}\index{multiplication!implicit} as shorthand for \verb|2*cm|). - -It is often convenient to introduce your own scale factor, say $u$. -Then you can define coordinates in terms of $u$ and decide later whether you want -to begin with \verb|u=1cm| or \verb|u=0.5cm|. This gives you control over what -gets scaled and what does not so that changing $u$ will not affect features such -as line widths. - -There are many ways to affect the appearance of a line besides just changing its -width, so the width-control mechanisms allow a lot of generality that we do not need -yet. -This leads to the strange looking statement\index{pickup?\texttt{pickup}}\index{pencircle?\texttt{pencircle}}% +generates a larger version of the above diagram. It is OK to say +\verb|0| instead \verb|0cm| because {\tt cm} is really just a conversion +factor and {\tt 0cm} just multiplies the conversion factor by zero. +(MetaPost understands constructions like {\tt +2cm}\index{multiplication!implicit} as shorthand for \verb|2*cm|). + +It is convenient to introduce your own scale factor, say $u$. Then you +can define coordinates in terms of $u$ and decide later whether you want +to begin with \verb|u=1cm| or \verb|u=0.5cm|. This gives you control +over what gets scaled and what does not so that changing $u$ will not +affect features such as line widths. + +There are many ways to affect the appearance of a line besides just +changing its width, so the width-control mechanisms allow a lot of +generality that we do not need yet. This leads to the strange looking +statement\index{pickup?\texttt{pickup}}\index{pencircle?\texttt{pencircle}}% \index{scaled?\texttt{scaled}} $$ \hbox{\verb|pickup pencircle scaled 4pt|} $$ for setting the line width for subsequent \verb|draw| statements to 4 points. @@ -257,32 +306,32 @@ for i=0 upto 2: endfor endfig; \end{verbatim} -\quad \mathcenter{\epsfbox{manfig.2}} +\quad \mathcenter{\includegraphics{manfig-2}} $$ \caption{MetaPost commands and the resulting output} \label{fig1} \end{figure} Note that the program in Figure~\ref{fig1} starts with -\verb|beginfig(2)|\index{beginfig?\texttt{beginfig}} and -ends with \verb|endfig|\index{endfig?\texttt{endfig}}. -These are macros that perform various administrative -functions and ensure that the results of all the \verb|draw| statements get -packaged up and translated into PostScript. A MetaPost input file normally -contains a sequence of \verb|beginfig|, \verb|endfig| pairs with an -{\tt end}\index{end?\texttt{end}} -statement after the last one. If this file is named {\tt fig.mp}, the output -from \verb|draw| statements between \verb|beginfig(1)| and the next \verb|endfig| -is written in a file {\tt fig.1}\index{files!output}. -In other words, the numeric argument to the \verb|beginfig| macro determines the -name of the corresponding output file. - -What does one do with all the PostScript files? They can be included as figures -in a \TeX\index{TeX?\TeX} or troff\index{troff} document if you have an -output driver that can handle -encapsulated PostScript figures. If your standard \TeX\ macro directory contains -a file {\tt epsf.tex}\index{epsf.tex?\texttt{epsf.tex}}, you can probably include {\tt fig.1} -in a \TeX\ document as follows: +\verb|beginfig(2)|\index{beginfig?\texttt{beginfig}} and ends with +\verb|endfig|\index{endfig?\texttt{endfig}}. These are macros that +perform various administrative functions and ensure that the results of +all the \verb|draw| statements get packaged up and translated into +PostScript. A MetaPost input file normally contains a sequence of +\verb|beginfig|, \verb|endfig| pairs with an {\tt +end}\index{end?\texttt{end}} statement after the last one. If this file +is named {\tt fig.mp}, the output from \verb|draw| statements between +\verb|beginfig(1)| and the next \verb|endfig| is written in a file {\tt +fig.1}\index{files!output}. In other words, the numeric argument to the +\verb|beginfig| macro determines the name of the corresponding output +file. + +What does one do with all the PostScript files? They can be included as +figures in a \TeX\index{TeX?\TeX} or troff\index{troff} document if you +have an output driver that can handle encapsulated PostScript figures. +If your standard \TeX\ macro directory contains a file {\tt +epsf.tex}\index{epsf.tex?\texttt{epsf.tex}}, you can probably include +{\tt fig.1} in a \TeX\ document as follows: $$ \begin{array}{c} \hbox{\verb|\input epsf |}\\ \vdots\\ @@ -299,6 +348,47 @@ $$ \hbox{\verb|.BP fig.1 3c 3c|} $$ includes {\tt fig.1} and specifies that its height and width are both three centimeters. +\subsection{Filename templates} + +Metapost has support for output file-name templates. These templates +use \ttt{printf}-style escape sequences and are re-evaluated before +each figure is written to disk. + +The command to use is \ttt{filenametemplate}, and it accepts a string +as argument. The syntax is as simple as: + +\begin{center}\begin{tabular}{l} +\verb|filenametemplate "%j-%3c.mps";|\\ +\verb|beginfig(1);|\\ +\verb| draw p;|\\ +\verb|endfig;| +\end{tabular}\end{center} + +If the file is saved as \ttt{fig.mp}, then this will create the output +file \ttt{fig-001.mps} instead of \ttt{fig.1}. A small set of escape +sequences are possible, see table~\ref{tab:fntmpl} for details. + +\def\d{$\langle$0-9$\rangle$} + +\begin{table} +\begin{center}\begin{tabular}{ll} +\%\% & A percent sign \\ +\%\,j & The current jobname\\ +\%\d c & The charcode value\\ +\%\d y & The current year\\ +\%\d m & The numeric month\\ +\%\d d & The day of the month\\ +\%\d H & The hour\\ +\%\d M & The minute\\ +\end{tabular}\end{center} +\caption{Allowed escape sequences for \ttt{filenametemplate}} +\label{tab:fntmpl} +\end{table} + +To ensure compatibility with older files, the default value of +\ttt{filenametemplate} is \verb|%j.%c|. +If you assign an empty string, it will revert to that default. + \section{Curves} \label{curves} @@ -318,20 +408,20 @@ Figure~\ref{fig2} shows the curve with points \verb|z0| through \verb|z4| labeled. \begin{figure}[htp] -$$ \epsfbox{manfig.3} +$$ \includegraphics{manfig-3} $$ \caption[A curve through points 0, 1, 2, 3, and 4] {The result of {\tt draw z0..z1..z2..z3..z4}} \label{fig2} \end{figure} -There are many other ways to draw a curved path through the same five points. -To make a smooth closed curve, connect \verb|z4| back to the beginning by -appending \verb|..cycle|\index{cycle?\texttt{cycle}} to the \verb|draw| statement as shown -in Figure~\ref{fig3}a. It is also possible in a single \verb|draw| statement -to mix curves and straight lines as shown in Figure~\ref{fig3}b. Just use -\verb|--| where you want straight lines and \verb|..| where you want curves. -Thus +There are many other ways to draw a curved path through the same five +points. To make a smooth closed curve, connect \verb|z4| back to the +beginning by appending \verb|..cycle|\index{cycle?\texttt{cycle}} to the +\verb|draw| statement as shown in Figure~\ref{fig3}a. It is also +possible in a single \verb|draw| statement to mix curves and straight +lines as shown in Figure~\ref{fig3}b. Just use \verb|--| where you want +straight lines and \verb|..| where you want curves. Thus $$ \hbox{\verb|draw z0..z1..z2..z3--z4--cycle|} $$ produces a curve through points 0,~1, 2, and~3, then a polygonal line from point~3 to point~4 and back to point~0. The result is essentially the same @@ -343,8 +433,8 @@ as having two draw statements \end{eqnarray*} \begin{figure}[htp] -$$ {\epsfbox{manfig.104} \atop (a)} - \qquad {\epsfbox{manfig.204} \atop (b)} +$$ {\includegraphics{manfig-104} \atop (a)} + \qquad {\includegraphics{manfig-204} \atop (b)} $$ \caption[Closed curves through five points] {(a)~The result of {\tt draw z0..\linebreak[0]z1..\linebreak[0]% @@ -356,10 +446,10 @@ $$ \subsection{B\'ezier Cubic Curves} -When MetaPost is asked to draw a smooth curve through a sequence of points, -it constructs a piecewise cubic curve with continuous slope and approximately -continuous curvature\index{curvature}. This means that a path specification such -as +When MetaPost is asked to draw a smooth curve through a sequence of +points, it constructs a piecewise cubic curve with continuous slope and +approximately continuous curvature\index{curvature}. This means that a +path specification such as $$ \hbox{\verb|z0..z1..z2..z3..z4..z5|} $$ results in a curve that can be defined parametrically\index{parameterization} as $(X(t),Y(t))$ for @@ -397,7 +487,7 @@ draw (0,0)..controls (26.8,-1.8) and (51.4,14.6) $$ \begin{figure}[htp] -$$ \epsfbox{manfig.5} +$$ \includegraphics{manfig-5} $$ \caption[A curve and the control polygon] {The result of {\tt draw z0..z1..z2..z3..z4} with the @@ -409,22 +499,23 @@ $$ \subsection{Specifying Direction, Tension, and Curl} \label{tenscurl} -MetaPost provides many ways of controlling the behavior of a curved path without -actually specifying the control points. For instance, some points on the path -may be selected as vertical or horizontal extrema. If \verb|z1| is to be a -horizontal extreme and \verb|z2| is to be a vertical extreme, you can specify -that $(X(t),Y(t))$ should go upward at \verb|z1| and to the left at \verb|z2|: +MetaPost provides many ways of controlling the behavior of a curved path +without actually specifying the control points. For instance, some +points on the path may be selected as vertical or horizontal extrema. +If \verb|z1| is to be a horizontal extreme and \verb|z2| is to be a +vertical extreme, you can specify that $(X(t),Y(t))$ should go upward at +\verb|z1| and to the left at \verb|z2|: $$ \hbox{\verb|draw z0..z1{up}..z2{left}..z3..z4;|} $$ -The resulting shown in Figure~\ref{fig5} has the desired vertical and horizontal -directions at \verb|z1| and \verb|z2|, but it does not look as smooth as the -curve in Figure~\ref{fig2}. The reason is the large discontinuity in -curvature\index{curvature} -at \verb|z1|. If it were not for the specified direction at \verb|z1|, the -MetaPost interpreter would have chosen a direction designed to make the curvature -above \verb|z1| almost the same as the curvature below that point. +The resulting shown in Figure~\ref{fig5} has the desired vertical and +horizontal directions at \verb|z1| and \verb|z2|, but it does not look +as smooth as the curve in Figure~\ref{fig2}. The reason is the large +discontinuity in curvature\index{curvature} at \verb|z1|. If it were +not for the specified direction at \verb|z1|, the MetaPost interpreter +would have chosen a direction designed to make the curvature above +\verb|z1| almost the same as the curvature below that point. \begin{figure}[htp] -$$ \epsfbox{manfig.6} +$$ \includegraphics{manfig-6} $$ \caption[A curve and the control polygon] {The result of {\tt draw z0..z1\char`\{up\char`\}..z2\char`\{left\char`\}% @@ -439,7 +530,7 @@ directions there. Figures \ref{fig6} and~\ref{fig7} give a good idea of what this family of curves is like. \begin{figure}[htp] -$$ \mathcenter{\epsfbox{manfig.7}} \quad +$$ \mathcenter{\includegraphics{manfig-7}} \quad \begin{verbatim} beginfig(7) for a=0 upto 9: @@ -453,7 +544,7 @@ $$ \end{figure} \begin{figure}[htp] -$$ \mathcenter{\epsfbox{manfig.8}} \quad +$$ \mathcenter{\includegraphics{manfig-8}} \quad \begin{verbatim} beginfig(8) for a=0 upto 7: @@ -466,15 +557,17 @@ $$ \label{fig7} \end{figure} -Figures \ref{fig6} and~\ref{fig7} illustrate a few new MetaPost features. -The first is the {\tt dir}\index{dir?\texttt{dir}}\label{Ddirop} operator that takes an -angle in degrees -and generates a unit vector in that direction. Thus \verb|dir 0| is equivalent -to {\tt right}\index{right?\texttt{right}}\label{Dright} and \verb|dir 90| is equivalent to -{\tt up}\index{up?\texttt{up}}\label{Dup}. There are also predefined direction vectors -{\tt left}\index{left?\texttt{left}}\label{Dleft} -and {\tt down}\index{down?\texttt{down}}\label{Ddown} for {\tt dir 180} -and {\tt dir 270}. +Figures \ref{fig6} and~\ref{fig7} illustrate a few new MetaPost +features. The first is the {\tt +dir}\index{dir?\texttt{dir}}\label{Ddirop} operator that takes an angle +in degrees and generates a unit vector in that direction. Thus +\verb|dir 0| is equivalent to {\tt +right}\index{right?\texttt{right}}\label{Dright} and \verb|dir 90| is +equivalent to {\tt up}\index{up?\texttt{up}}\label{Dup}. There are also +predefined direction vectors {\tt +left}\index{left?\texttt{left}}\label{Dleft} and {\tt +down}\index{down?\texttt{down}}\label{Ddown} for {\tt dir 180} and {\tt +dir 270}. The direction vectors given in \verb|{}| can be of any length, and they can come before a @@ -485,22 +578,22 @@ $$ \hbox{\verb|..{dir 60}(10,0){up}..|} $$ produces a curve with a corner at $(10,0)$. Note that some of the curves in Figure~\ref{fig6} have points of -inflection\index{inflections}. -This is necessary in order to produce smooth curves in situations like -Figure~\ref{fig3}a, but it is probably not desirable when dealing with vertical -and horizontal extreme points as in Figure~\ref{fig8}a. If \verb|z1| is supposed -to be the topmost point on the curve, this can be achieved by using -\verb|...|\index{...?\texttt{...}} -instead of \verb|..| in the path specification as shown in Figure~\ref{fig8}b. -The meaning of \verb|...| is ``choose an inflection-free path between these -points unless the endpoint directions make this impossible.'' (It would be -possible to avoid inflections in Figure~\ref{fig6}, but not in Figure~\ref{fig7}). +inflection\index{inflections}. This is necessary in order to produce +smooth curves in situations like Figure~\ref{fig3}a, but it is probably +not desirable when dealing with vertical and horizontal extreme points +as in Figure~\ref{fig8}a. If \verb|z1| is supposed to be the topmost +point on the curve, this can be achieved by using +\verb|...|\index{...?\texttt{...}} instead of \verb|..| in the path +specification as shown in Figure~\ref{fig8}b. The meaning of \verb|...| +is ``choose an inflection-free path between these points unless the +endpoint directions make this impossible.'' (It would be possible to +avoid inflections in Figure~\ref{fig6}, but not in Figure~\ref{fig7}). \begin{figure}[htp] -$$ {\mathcenter{\epsfbox{manfig.109}} \atop +$$ {\mathcenter{\includegraphics{manfig-109}} \atop \hbox{\verb|draw z0{up}..z1{right}..z2{down}|}} \quad - {\mathcenter{\epsfbox{manfig.209}} \atop + {\mathcenter{\includegraphics{manfig-209}} \atop \hbox{\verb|draw z0{up}...z1{right}...z2{down}|}} $$ \caption{Two {\tt draw} statements and the resulting curves.} @@ -508,12 +601,12 @@ $$ \end{figure} Another way to control a misbehaving path is to increase the -``tension''\index{tension} parameter. -Using \verb|..| in a path specification sets the tension parameter to the default -value~1. If this makes some part of a path a little too wild, we can selectively -increase the tension. If Figure~\ref{fig9}a is considered ``too wild,'' a -{\tt draw} statement of the following form increases the tension between -{\tt z1} and {\tt z2}: +``tension''\index{tension} parameter. Using \verb|..| in a path +specification sets the tension parameter to the default value~1. If +this makes some part of a path a little too wild, we can selectively +increase the tension. If Figure~\ref{fig9}a is considered ``too wild,'' +a {\tt draw} statement of the following form increases the tension +between {\tt z1} and {\tt z2}: $$ \hbox{\verb|draw z0..z1..tension 1.3..z2..z3|} $$ This produces Figure~\ref{fig9}b. For an asymmetrical effect like Figure~\ref{fig9}c, the \verb|draw| statement becomes @@ -521,11 +614,11 @@ $$ \hbox{\verb|draw z0..z1..tension 1.6 and 1..z2..z3|} $$ The tension parameter can be less than one, but it must be at least $3\over4$. \begin{figure}[htp] -$$ {\mathcenter{\epsfbox{manfig.110}} \atop (a)} +$$ {\mathcenter{\includegraphics{manfig-110}} \atop (a)} \quad - {\mathcenter{\epsfbox{manfig.210}} \atop (b)} + {\mathcenter{\includegraphics{manfig-210}} \atop (b)} \quad - {\mathcenter{\epsfbox{manfig.310}} \atop (c)} + {\mathcenter{\includegraphics{manfig-310}} \atop (c)} $$ \caption[Effects of changing the tension parameter] {Results of {\tt draw z0..z1..tension} $\alpha$ {\tt and} $\beta$ @@ -535,27 +628,27 @@ $$ \label{fig9} \end{figure} -MetaPost paths also have a parameter called ``curl''\index{curl?\texttt{curl}} that affects -the ends of a -path. In the absence of any direction specifications, the first and last segments -of a non-cyclic path are approximately circular arcs as in the $c=1$ case of -Figure~\ref{fig10}. To use a different value for the curl parameter, specify -\verb|{curl c}| for some other value of $c$. Thus +MetaPost paths also have a parameter called +``curl''\index{curl?\texttt{curl}} that affects the ends of a path. In +the absence of any direction specifications, the first and last segments +of a non-cyclic path are approximately circular arcs as in the $c=1$ +case of Figure~\ref{fig10}. To use a different value for the curl +parameter, specify \verb|{curl c}| for some other value of $c$. Thus $$ \hbox{\verb|draw z0{curl c}..z1..{curl c}z2|} $$ -sets the curl parameter for \verb|z0| and \verb|z2|. Small values of the curl -parameter reduce the curvature\index{curvature} at the indicated path endpoints, -while large values -increase the curvature as shown in Figure~\ref{fig10}. In particular, a curl value -of zero makes the curvature approach zero. +sets the curl parameter for \verb|z0| and \verb|z2|. Small values of +the curl parameter reduce the curvature\index{curvature} at the +indicated path endpoints, while large values increase the curvature as +shown in Figure~\ref{fig10}. In particular, a curl value of zero makes +the curvature approach zero. \begin{figure}[htp] -$$ {\mathcenter{\epsfbox{manfig.111}} \atop c=0} +$$ {\mathcenter{\includegraphics{manfig-111}} \atop c=0} \qquad - {\mathcenter{\epsfbox{manfig.211}} \atop c=1} + {\mathcenter{\includegraphics{manfig-211}} \atop c=1} \qquad - {\mathcenter{\epsfbox{manfig.311}} \atop c=2} + {\mathcenter{\includegraphics{manfig-311}} \atop c=2} \qquad - {\mathcenter{\epsfbox{manfig.411}} \atop c=\infty} + {\mathcenter{\includegraphics{manfig-411}} \atop c=\infty} $$ \caption[Effects of changing the curl parameter] {Results of {\tt draw z0\char`\{curl c\char`\}..z1..% @@ -566,17 +659,18 @@ $$ \subsection{Summary of Path Syntax} -There are a few other features of MetaPost path syntax, but they are relatively -unimportant. Since \MF\ uses the same path syntax, interested readers can refer -to \cite[chapter 14]{kn:c}. The summary of path syntax in Figure~\ref{sypath} -includes everything discussed so far including the \verb|--| and \verb|...| -constructions which \cite{kn:c} shows to be macros rather than primitives. -A few comments on the semantics are in order here: If there is a non-empty -$\descr{direction specifier}$ before a $\descr{path knot}$ but not after it, -or vice versa, the specified direction (or curl amount) applies to both the -incoming and outgoing path segments. A similar arrangement applies when a -$\descr{controls}$ specification gives only one $\descr{pair primary}$. -Thus +There are a few other features of MetaPost path syntax, but they are +relatively unimportant. Since \MF\ uses the same path syntax, +interested readers can refer to \cite[chapter 14]{kn:c}. The summary of +path syntax in Figure~\ref{sypath} includes everything discussed so far +including the \verb|--| and \verb|...| constructions which \cite{kn:c} +shows to be macros rather than primitives. A few comments on the +semantics are in order here: If there is a non-empty $\descr{direction +specifier}$ before a $\descr{path knot}$ but not after it, or vice +versa, the specified direction (or curl amount) applies to both the +incoming and outgoing path segments. A similar arrangement applies when +a $\descr{controls}$ specification gives only one $\descr{pair +primary}$. Thus $$ \hbox{\verb|..controls (30,20)..|} $$ is equivalent to $$ \hbox{\verb|...controls (30,20) and (30,20)..|} $$ @@ -618,11 +712,12 @@ $\descr{controls} \rightarrow \label{sypath} \end{figure} -A pair of coordinates like \verb|(30,20)| or a \verb|z| variable that represents a -coordinate pair is what Figure~\ref{sypath} calls a $\descr{pair primary}$. -A $\descr{path knot}$ is similar except that it can take on other forms such as -a path expression in parentheses. Primaries and expressions of various types will -be discussed in full generality in Section~\ref{exprs}. +A pair of coordinates like \verb|(30,20)| or a \verb|z| variable that +represents a coordinate pair is what Figure~\ref{sypath} calls a +$\descr{pair primary}$. A $\descr{path knot}$ is similar except that it +can take on other forms such as a path expression in parentheses. +Primaries and expressions of various types will be discussed in full +generality in Section~\ref{exprs}. \section{Linear Equations} @@ -631,11 +726,13 @@ be discussed in full generality in Section~\ref{exprs}. An important feature taken from \MF\ is the ability to solve linear equations so that programs can be written in a partially declarative fashion. For example, the MetaPost interpreter can read -$$ \hbox{\verb|a+b=3; 2*a=b+3;|} $$ -and deduce that $a=2$ and $b=1$. The same equations can be written slightly more -compactly by stringing them together with multiple equal signs: -$$ \hbox{\verb|a+b = 2*a-b = 3;|} $$ -Whichever way you give the equations, you can then give the command\index{show?\texttt{show}} +$$ \hbox{\verb|a+b=3; 2a=b+3;|} $$ +and deduce that $a=2$ and $b=1$. The same equations can be written +slightly more compactly by stringing them together with multiple equal +signs: +$$ \hbox{\verb|a+b = 2a-b = 3;|} $$ +Whichever way you give the equations, you can then give the +command\index{show?\texttt{show}} $$ \hbox{\tt show a,b;} $$ to see the values of {\tt a} and {\tt b}. MetaPost responds by typing $$\begin{verbatim} @@ -644,40 +741,42 @@ $$\begin{verbatim} \end{verbatim} $$ -Note that {\tt =}\index{=?\texttt{=}} is not an assignment operator; it simply declares -that the left-hand side equals the right-hand side. Thus {\tt a=a+1} produces an -error message complaining about an -``inconsistent equation\index{Inconsistent equation?\texttt{Inconsistent equation}}.'' The way to increase -the value of {\tt a} is to use the assignment\index{assignment} operator -{\tt :=}\index{:=?\texttt{:=}} as follows: +Note that {\tt =}\index{=?\texttt{=}} is not an assignment operator; it +simply declares that the left-hand side equals the right-hand side. +Thus {\tt a=a+1} produces an error message complaining about an +``inconsistent equation\index{Inconsistent equation?\texttt{Inconsistent +equation}}.'' The way to increase the value of {\tt a} is to use the +assignment\index{assignment} operator {\tt :=}\index{:=?\texttt{:=}} as +follows: $$ \hbox{\tt a:=a+1;} $$ In other words, {\tt :=} is for changing existing values while {\tt =} is for giving linear equations to solve. -There is no restriction against mixing equations and assignment operations as in -the following example: +There is no restriction against mixing equations and assignment +operations as in the following example: $$ \hbox{\tt a = 2; b = a; a := 3; c = a;} $$ -After the first two equations set {\tt a} and~{\tt b} equal to 2, the assignment -operation changes {\tt a} to~3 without affecting {\tt b}. The final value of -{\tt c} is 3 since it is equated to the new value of {\tt a}. In general, an -assignment operation is interpreted by first computing the new value, then -eliminating the old value from all existing equations before actually assigning -the new value. +After the first two equations set {\tt a} and~{\tt b} equal to 2, the +assignment operation changes {\tt a} to~3 without affecting {\tt b}. +The final value of {\tt c} is 3 since it is equated to the new value of +{\tt a}. In general, an assignment operation is interpreted by first +computing the new value, then eliminating the old value from all +existing equations before actually assigning the new value. \subsection{Equations and Coordinate Pairs} MetaPost can also solve linear equations involving coordinate pairs. We have already seen many trivial examples of this in the form of equations like $$ \hbox{\verb|z1=(0,.2in)|} $$ -Each side of the equation must be formed by adding or subtracting coordinate pairs -and multiplying or dividing them by known numeric quantities. Other ways of -naming pair-valued variables will be discussed later, but the -${\tt z}\descr{number}$\index{z convention?{\tt z} convention} is convenient because it is -an abbreviation for +Each side of the equation must be formed by adding or subtracting +coordinate pairs and multiplying or dividing them by known numeric +quantities. Other ways of naming pair-valued variables will be +discussed later, but the ${\tt z}\descr{number}$\index{z convention?{\tt +z} convention} is convenient because it is an abbreviation for $$ \hbox{\tt (x}\descr{number} \hbox{\tt, y}\descr{number}\hbox{\tt)} $$ -This makes it possible to give values to \verb|z| variables by giving equations -involving their coordinates. For instance, points {\tt z1}, {\tt z2}, {\tt z3}, -and~{\tt z6} in Figure~\ref{fig12} were initialized via the following equations: +This makes it possible to give values to \verb|z| variables by giving +equations involving their coordinates. For instance, points {\tt z1}, +{\tt z2}, {\tt z3}, and~{\tt z6} in Figure~\ref{fig12} were initialized +via the following equations: \begin{eqnarray*} &&\hbox{\verb|z1=-z2=(.2in,0);|} \\ &&\hbox{\verb|x3=-x6=.3in;|} \\ @@ -690,12 +789,12 @@ z3=(.3in,.6in); z6=(-.3in,1.2in); \end{verbatim} $$ -After reading the equations, the MetaPost interpreter knows the values of -{\tt z1}, {\tt z2}, -{\tt z3}, and~{\tt z6}. The next step in the construction of Figure~\ref{fig12} -is to define points {\tt z4} and {\tt z5} equally spaced along the line from -{\tt z3} to {\tt z6}. Since this operation comes up often, MetaPost has a special -syntax for it. This mediation construction\index{mediation} +After reading the equations, the MetaPost interpreter knows the values +of {\tt z1}, {\tt z2}, {\tt z3}, and~{\tt z6}. The next step in the +construction of Figure~\ref{fig12} is to define points {\tt z4} and {\tt +z5} equally spaced along the line from {\tt z3} to {\tt z6}. Since this +operation comes up often, MetaPost has a special syntax for it. This +mediation construction\index{mediation} $$ \hbox{\verb|z4=1/3[z3,z6]|} $$ means that {\tt z4} is $1\over3$ of the way from $z3$ to $z6$; i.e., $$ {\tt z4}={\tt z3}+{1\over3}({\tt z6}-{\tt z3}). $$ @@ -720,7 +819,7 @@ draw z1--z2; draw z3--z6; endfig; \end{verbatim} -\quad \mathcenter{\epsfbox{manfig.13}} +\quad \mathcenter{\includegraphics{manfig-13}} $$ \caption[MetaPost code and figure using linear equations] {MetaPost commands and the resulting figure. Point labels have been @@ -728,23 +827,24 @@ $$ \label{fig12} \end{figure} -Mediation can also be used to say that some point is at an unknown position along -the line between two known points. For instance, we could a introduce new -variable {\tt aa} and write something like +Mediation can also be used to say that some point is at an unknown +position along the line between two known points. For instance, we +could a introduce new variable {\tt aa} and write something like $$ \hbox{\verb|z20=aa[z1,z3];|} $$ -This says that {\tt z20} is some unknown fraction {\tt aa} of the way along the -line between {\tt z1} and {\tt z3}. Another such equation involving a different -line is sufficient to fix the value of {\tt z20}. To say that {\tt z20} is at -the intersection of the {\tt z1}-{\tt z3} line and the {\tt z2}-{\tt z4} line, -introduce another variable {\tt ab} and set +This says that {\tt z20} is some unknown fraction {\tt aa} of the way +along the line between {\tt z1} and {\tt z3}. Another such equation +involving a different line is sufficient to fix the value of {\tt z20}. +To say that {\tt z20} is at the intersection of the {\tt z1}-{\tt z3} +line and the {\tt z2}-{\tt z4} line, introduce another variable {\tt ab} +and set $$ \hbox{\verb|z20=ab[z2,z4];|} $$ This allows MetaPost to solve for {\tt x20}, {\tt y20}, {\tt aa}, and {\tt ab}. -It is a little painful to keep -thinking up new names like {\tt aa} and {\tt ab}. This can be avoided by using -a special feature called {\tt whatever}\index{whatever?\texttt{whatever}}\label{Dwhatev}. -This macro generates a new anonymous -variable each time it appears. Thus the statement +It is a little painful to keep thinking up new names like {\tt aa} and +{\tt ab}. This can be avoided by using a special feature called {\tt +whatever}\index{whatever?\texttt{whatever}}\label{Dwhatev}. This macro +generates a new anonymous variable each time it appears. Thus the +statement $$ \hbox{\verb|z20=whatever[z1,z3]=whatever[z2,z4]|} $$ sets {\tt z20} as before, except it uses {\tt whatever} to generate two {\em different\/} anonymous variables instead of {\tt aa} and {\tt ab}. @@ -763,19 +863,20 @@ be determined before they are needed. This means that the equations && \hbox{\verb|z4=1/3[z3,z6];|}\\ && \hbox{\verb|z5=2/3[z3,z6];|} \end{eqnarray*} -suffice to determine {\tt z1} through {\tt z6}, no matter what order the equations -are given in. On the other hand +suffice to determine {\tt z1} through {\tt z6}, no matter what order the +equations are given in. On the other hand $$ \hbox{\verb|z20=whatever[z1,z3]|} $$ is legal only when a known value has previously been specified for the difference ${\tt z3}-{\tt z1}$, because the equation is equivalent to\index{mediation} $$ \hbox{\verb|z20 = z1 + whatever*(z3-z1)|} $$ -and the linearity requirement disallows multiplying unknown components of -${\tt z3}-{\tt z1}$ by the anonymous unknown result of {\tt whatever}. The general -rule is that you cannot multiply two unknown quantities or divide by an unknown -quantity, nor can an unknown quantity be used in a {\tt draw} statement. -Since only linear equations are allowed, the MetaPost interpreter can easily solve -the equations and keep track of what values are known. +and the linearity requirement disallows multiplying unknown components +of ${\tt z3}-{\tt z1}$ by the anonymous unknown result of {\tt +whatever}. The general rule is that you cannot multiply two unknown +quantities or divide by an unknown quantity, nor can an unknown quantity +be used in a {\tt draw} statement. Since only linear equations are +allowed, the MetaPost interpreter can easily solve the equations and +keep track of what values are known. The most natural way to ensure that MetaPost can handle an expression like $$ \hbox{\verb|whatever[z1,z3]|} $$ @@ -784,18 +885,20 @@ actually required since MetaPost may be able to deduce a known value for ${\tt z3}-{\tt z1}$ before either of {\tt z1} and {\tt z3} are known. For instance, MetaPost will accept the equations $$ \hbox{\verb|z3=z1+(.1in,.6in); z20=whatever[z1,z3];|} $$ -but it will not be able to determine any of the components of {\tt z1}, {\tt z3}, -or {\tt z20}. +but it will not be able to determine any of the components of {\tt z1}, +{\tt z3}, or {\tt z20}. These equations do give partial information about {\tt z1}, {\tt z3}, and {\tt z20}. A good way to see this is to give another equation such as $$ \hbox{\verb|x20-x1=(y20-y1)/6;|} $$ -This produces the error message -``{\tt ! Redundant equation}\index{Redundant equation?\texttt{Redundant equation}}.'' -MetaPost assumes that you are trying to tell it something new, so it will usually -warn you when you give a redundant equation. If the new equation had been +This produces the error message ``{\tt ! Redundant +equation}\index{Redundant equation?\texttt{Redundant equation}}.'' +MetaPost assumes that you are trying to tell it something new, so it +will usually warn you when you give a redundant equation. If the new +equation had been $$ \hbox{\verb|(x20-x1)-(y20-y1)/6=1in;|} $$ -the error message would have been\index{Inconsistent equation?\texttt{Inconsistent equation}} +the error message would have been\index{Inconsistent +equation?\texttt{Inconsistent equation}} $$ \hbox{\verb|! Inconsistent equation (off by 71.99979).|} $$ This error message illustrates roundoff\index{roundoff error} error in MetaPost's linear equation solving @@ -808,32 +911,34 @@ parallel. \section{Expressions} \label{exprs} -It is now time for a more systematic view of the MetaPost language. We have seen -that there are numeric quantities and coordinate pairs, and that these can be -combined to specify paths for {\tt draw} statements. -We have also seen how variables can be used in linear equations, but we have not -discussed all the operations and data types that can be used in equations. +It is now time for a more systematic view of the MetaPost language. We +have seen that there are numeric quantities and coordinate pairs, and +that these can be combined to specify paths for {\tt draw} statements. +We have also seen how variables can be used in linear equations, but we +have not discussed all the operations and data types that can be used in +equations. It is possible to experiment with expressions involving any of the data types mentioned below by using the statement\index{show?\texttt{show}}\label{Dshow} $$ {\tt show}\, \descr{expression} $$ -to ask MetaPost to print a symbolic representation of the value of each expression. -For known numeric values, each is printed on a new line preceded by ``{\tt >>} ''. -Other types of results are printed similarly, except that complicated values are -sometimes not printed on standard output. This produces a reference to the -transcript file\index{files!transcript} that looks like this: +to ask MetaPost to print a symbolic representation of the value of each +expression. For known numeric values, each is printed on a new line +preceded by ``{\tt >>} ''. Other types of result are printed similarly, +except that complicated values are sometimes not printed on standard +output. This produces a reference to the transcript +file\index{files!transcript} that looks like this: $$ \hbox{\tt >> picture (see the transcript file)} $$ -If you want to the full results of {\tt show} statements to be printed on your -terminal, assign a positive value to the -internal\index{internal variables} variable\index{variables!internal} -{\tt tracingonline}\index{tracingonline?\texttt{tracingonline}}\label{Dtonline}. +If you want to the full results of {\tt show} statements to be printed +on your terminal, assign a positive value to the internal\index{internal +variables} variable\index{variables!internal} {\tt +tracingonline}\index{tracingonline?\texttt{tracingonline}}\label{Dtonline}. \subsection{Data Types} -MetaPost actually has nine basic data types\index{types}: numeric, -pair, path, transform, -color, string, boolean, picture, and pen. Let us consider these one at a time -beginning with the numeric type. +MetaPost actually has ten basic data types\index{types}: numeric, +pair, path, transform, (rgb)color, cmykcolor, string, boolean, picture, and +pen. Let us consider these one at a time beginning with the numeric +type. Numeric\index{numeric type} quantities in MetaPost are represented in fixed point arithmetic\index{arithmetic} as @@ -845,10 +950,10 @@ of magnitude 4096 or more, setting the internal variable {\tt warningcheck}\index{warningcheck}\label{Dwarncheck} to zero suppresses the warning messages about large numeric quantities. -The pair\index{pair type} type is represented as a pair of numeric quantities. -We have seen that pairs -are used to give coordinates in {\tt draw} statements. Pairs can be added, -subtracted, used in mediation expressions, or multiplied or divided by numerics. +The pair\index{pair type} type is represented as a pair of numeric +quantities. We have seen that pairs are used to give coordinates in +{\tt draw} statements. Pairs can be added, subtracted, used in +mediation expressions, or multiplied or divided by numerics. Paths\index{path type} have already been discussed in the context of {\tt draw} statements, but @@ -857,9 +962,9 @@ stored and manipulated. A path represents a straight or curved line that is defined parametrically. Another data type represents an arbitrary affine -transformation\index{transform type}. A {\em transform\/} can be any combination -of rotating, scaling, slanting, -and shifting. If ${\tt p}=(p_x,p_y)$ is a pair and {\tt T} is a +transformation\index{transform type}. A {\em transform\/} can be any +combination of rotating, scaling, slanting, and shifting. If ${\tt +p}=(p_x,p_y)$ is a pair and {\tt T} is a transform,\index{transformed?\texttt{transformed}} $$ \hbox{\tt p transformed T} $$ is a pair of the form @@ -868,21 +973,28 @@ where the six numeric quantities $(t_x,t_y,t_{xx},t_{xy},t_{yx},t_{yy})$ determine {\tt T}. Transforms can also be applied to paths, pictures, pens, and transforms. -The color\index{color type} type is a lot like the pair type, except that it -has three components -instead of two. Like pairs, colors can be added, subtracted, used in mediation -expressions, or multiplied or divided by numerics. Colors can be specified -in terms of the predefined constants {\tt black}\index{black?\texttt{black}}\label{Dblack}, -{\tt white}\index{white?\texttt{white}}\label{Dwhite}, {\tt red}\index{red?\texttt{red}}\label{Dred}, +The color\index{color type} type is like the pair type, except +that it has three components instead of two and each component is normally between 0 and 1. Like pairs, colors can be added, subtracted, used in mediation expressions, or multiplied or divided by numerics. Colors can be specified in terms of the predefined constants {\tt black}\index{black?\texttt{black}}\label{Dblack}, {\tt +white}\index{white?\texttt{white}}\label{Dwhite}, +{\tt red}\index{red?\texttt{red}}\label{Dred}, {\tt green}\index{green?\texttt{green}}\label{Dgreen}, -{\tt blue}\index{blue?\texttt{blue}}\label{Dblue}, or the red, green, -and blue components can be given explicitly. Black is {\tt (0,0,0)} and white -is {\tt (1,1,1)}. A level of gray such as {\tt (.4,.4,.4)} can be specified -as {\tt 0.4white}. There is no restriction against colors ``blacker -than black'' or ``whiter than white'' except all components are snapped -back to the $[0,1]$ range when a color is given in a PostScript\index{PostScript} -output file. MetaPost solves linear equations involving colors the same way it -does for pairs. +{\tt blue}\index{blue?\texttt{blue}}\label{Dblue}, or the red, green, and +blue components can be given explicitly. Black is {\tt (0,0,0)} and +white is {\tt (1,1,1)}. A level of gray such as {\tt (.4,.4,.4)} can also be +specified as {\tt 0.4white}. Although color typed variables may be +any ordered triplet, when adding an object to a picture, MetaPost will +convert its color by clipping each component between 0 and 1. For +example, MetaPost will output the color (1,2,3) as (1,1,1). +MetaPost solves linear equations involving +colors the same way it does for pairs. The type `rgbcolor' is an alias of +type `color'. + +The cmykcolor\index{cmykcolor type} type is similar to the color +type except that it has four components instead of three. This type is used to +specify colors by their cyan, magenta, yellow, and black components explicitly. +Because cmykcolors deal with pigments instead of light rays, the color +black would be expressed as {\tt (1,1,1,1)} and white as {\tt (0,0,0,0)}. + A string\index{string type} represents a sequence of characters. String constants\index{string constants} are given @@ -890,31 +1002,39 @@ in double quotes \hbox{\verb|"like this"|}. String constants cannot contain double quotes or newlines, but there is a way to construct a string containing any sequence of eight-bit characters. -The boolean\index{boolean type} type has the constants -{\tt true}\index{true?\texttt{true}}\label{Dtrue} and -{\tt false}\index{false}\label{Dfalse} and the -operators {\tt and}\index{and?\texttt{and}}\label{Dand}, {\tt or}\index{or?\texttt{or}}\label{Dor}, -{\tt not}\index{not?\texttt{not}}\label{Dnot}. The relations \verb|=| and -\verb|<>|\index{<>?\texttt{<>}}\label{Dcmpar} -test objects of any type for equality and inequality\index{inequality}. +\label{Dscantokens} +Conversion from strings to other types, notably numeric, can be accomplished by +the \ttindex{scantokens} primitive: +\begin{center}\texttt{n := scantokens(}\textit{str}\texttt{);}\end{center} +More generally, \texttt{scantokens} parses a string into a token +sequence, as if MetaPost had read it as input. + +The boolean\index{boolean type} type has the constants {\tt +true}\index{true?\texttt{true}}\label{Dtrue} and {\tt +false}\index{false}\label{Dfalse} and the operators {\tt +and}\index{and?\texttt{and}}\label{Dand}, {\tt +or}\index{or?\texttt{or}}\label{Dor}, {\tt +not}\index{not?\texttt{not}}\label{Dnot}. The relations \verb|=| and +\verb|<>|\index{<>?\texttt{<>}}\label{Dcmpar} test objects of any type +for equality and inequality\index{inequality}. Comparison\index{comparison} relations \verb|<|\index{<?\texttt{<}}, -\verb|<=|\index{<=?\texttt{<=}}, \verb|>|\index{>?\texttt{>}}, and \verb|>=|\index{>=?\texttt{>=}} -are defined lexicographically for -strings and in the obvious way for numerics. Ordering relations are also -defined for booleans, pairs, colors, and transforms, but the comparison rules -are not worth discussing here. +\verb|<=|\index{<=?\texttt{<=}}, \verb|>|\index{>?\texttt{>}}, and +\verb|>=|\index{>=?\texttt{>=}} are defined lexicographically for +strings and in the obvious way for numerics. Ordering relations are +also defined for booleans, pairs, colors, and transforms, but the +comparison rules are not worth discussing here. The picture\index{picture type} data type is just what the name implies. -Anything that can be drawn in MetaPost can be stored in a picture variable. -In fact, the {\tt draw}\index{draw?\texttt{draw}} -statement actually stores its results in a special picture variable called -{\tt currentpicture}\index{currentpicture?\texttt{currentpicture}}. Pictures can be added to other -pictures and operated on by transforms. - -Finally, there is a data type called a pen\index{pen type}. The main function -of pens in -MetaPost is to determine line thickness, but they can also be used to achieve -calligraphic effects. The statement\index{pickup?\texttt{pickup}}\label{Dpickup} +Anything that can be drawn in MetaPost can be stored in a picture +variable. In fact, the {\tt draw}\index{draw?\texttt{draw}} statement +actually stores its results in a special picture variable called {\tt +currentpicture}\index{currentpicture?\texttt{currentpicture}}. Pictures +can be added to other pictures and operated on by transforms. + +Finally, there is a data type called a pen\index{pen type}. The main +function of pens in MetaPost is to determine line thickness, but they +can also be used to achieve calligraphic effects. The +statement\index{pickup?\texttt{pickup}}\label{Dpickup} $$ {\tt pickup\ }\descr{pen expression} $$ causes the given pen to be used in subsequent {\tt draw} statements. Normally, the pen expression is of the form @@ -925,20 +1045,22 @@ an elliptical pen or a polygonal pen. \subsection{Operators} -There are many different ways to make expressions of the nine basic types, but -most of the operations fit into a fairly simple syntax with four levels of -precedence as shown in Figure~\ref{syexpr}. There are -primaries\index{primary?\tdescr{primary}}, secondaries\index{secondary?\tdescr{secondary}}, -tertiaries\index{tertiary?\tdescr{tertiary}}, and expressions\index{expression?\tdescr{expression}} -of each of the basic types, so the syntax rules could -be specialized to deal with items such as \tdescr{numeric primary}, -\tdescr{boolean tertiary}, etc. This allows the result type for an operation -to depend on the choice of operator and the types of its operands. For example, -the {\tt <} relation is a \tdescr{tertiary binary} that can be applied -to a \tdescr{numeric expression} and a \tdescr{numeric tertiary} to give a -\tdescr{boolean expression}. The same operator can accept other operand types -such as \tdescr{string expression} and \tdescr{string tertiary}, but an error -message results if the operand types do not match. +There are many different ways to make expressions of the nine basic +types, but most of the operations fit into a fairly simple syntax with +four levels of precedence as shown in Figure~\ref{syexpr}. There are +primaries\index{primary?\tdescr{primary}}, +secondaries\index{secondary?\tdescr{secondary}}, +tertiaries\index{tertiary?\tdescr{tertiary}}, and +expressions\index{expression?\tdescr{expression}} of each of the basic +types, so the syntax rules could be specialized to deal with items such +as \tdescr{numeric primary}, \tdescr{boolean tertiary}, etc. This +allows the result type for an operation to depend on the choice of +operator and the types of its operands. For example, the {\tt <} +relation is a \tdescr{tertiary binary} that can be applied to a +\tdescr{numeric expression} and a \tdescr{numeric tertiary} to give a +\tdescr{boolean expression}. The same operator can accept other operand +types such as \tdescr{string expression} and \tdescr{string tertiary}, +but an error message results if the operand types do not match. \begin{figure}[htp] \begin{ctabbing} @@ -959,72 +1081,74 @@ $\tt \qquad \;|\; \descr{expression} \descr{tertiary binop} \end{ctabbing} \caption{The overall syntax rules for expressions} \index{unary op?\tdescr{unary op}} \index{nullary op?\tdescr{nullary op}} -\index{primary binop?\tdescr{primary binop}} \index{secondary binop?\tdescr{secondary binop}} +\index{primary binop?\tdescr{primary binop}} +\index{secondary binop?\tdescr{secondary binop}} \index{tertiary binop?\tdescr{tertiary binop}} \label{syexpr} \end{figure} -The multiplication and division operators {\tt *}\label{Dmldiv} -and~{\tt /} are examples of what -Figure~\ref{syexpr} calls a \tdescr{primary binop}. Each can accept two numeric -operands or one numeric operand and one operand of type pair or color. -The exponentiation operator \verb|**|\index{**?\texttt{**}}\index{exponentiation}\label{Dpow} -is a \tdescr{primary binop} that requires two numeric operands. -Placing this at the -same level of precedence as multiplication -and division has the unfortunate consequence that \verb|3*a**2| means $(3a)^2$, -not $3(a^2)$\index{parsing irregularities}. Since unary negation\label{Dneg} -applies at the primary level, it also turns -out that \verb|-a**2| means $(-a)^2$. Fortunately, subtraction has lower -precedence so that \verb|a-b**2| does mean $a-(b^2)$ instead of $(a-b)^2$. - -Another \tdescr{primary binop} is the -{\tt dotprod}\index{dotprod?\texttt{dotprod}}\label{Ddprod} operator that computes the -vector dot product of two pairs. For example, {\tt z1 dotprod z2} is equivalent -to {\tt x1*y1 + x2*y2}. +The multiplication and division operators {\tt *}\label{Dmldiv} and~{\tt +/} are examples of what Figure~\ref{syexpr} calls a \tdescr{primary +binop}. Each can accept two numeric operands or one numeric operand and +one operand of type pair or color. The exponentiation operator +\verb|**|\index{**?\texttt{**}}\index{exponentiation}\label{Dpow} is a +\tdescr{primary binop} that requires two numeric operands. Placing this +at the same level of precedence as multiplication and division has the +unfortunate consequence that \verb|3*a**2| means $(3a)^2$, not +$3(a^2)$\index{parsing irregularities}. Since unary +negation\label{Dneg} applies at the primary level, it also turns out +that \verb|-a**2| means $(-a)^2$. Fortunately, subtraction has lower +precedence so that \verb|a-b**2| does mean $a-(b^2)$ instead of +$(a-b)^2$. + +Another \tdescr{primary binop} is the {\tt +dotprod}\index{dotprod?\texttt{dotprod}}\label{Ddprod} operator that +computes the vector dot product of two pairs. For example, {\tt z1 +dotprod z2} is equivalent to {\tt x1*y1 + x2*y2}. The additive operators {\tt +} and {\tt -}\label{Dadd} are -\tdescr{secondary binops} that -operate on numerics, pairs, or colors and produce results of the same type. -Other operators that fall in this category are ``Pythagorean addition'' -\verb|++|\index{++?\texttt{++}}\label{Dpyadd} and -``Pythagorean subtraction'' \verb|+-+|\index{+-+?\texttt{+-+}}\label{Dpysub}: -\verb|a++b| means $\sqrt{a^2+b^2}$ and \verb|a+-+b| means $\sqrt{a^2-b^2}$. -There are too many other operators to list here, but some of the most important -are the boolean operators {\tt and}\index{and?\texttt{and}} and {\tt or}\index{or?\texttt{or}}. -The {\tt and} operator is a -\tdescr{primary binop} and the {\tt or} operator is a \tdescr{secondary binop}. +\tdescr{secondary binops} that operate on numerics, pairs, or colors and +produce results of the same type. Other operators that fall in this +category are ``Pythagorean addition'' +\verb|++|\index{++?\texttt{++}}\label{Dpyadd} and ``Pythagorean +subtraction'' \verb|+-+|\index{+-+?\texttt{+-+}}\label{Dpysub}: +\verb|a++b| means $\sqrt{a^2+b^2}$ and \verb|a+-+b| means +$\sqrt{a^2-b^2}$. There are too many other operators to list here, but +some of the most important are the boolean operators {\tt +and}\index{and?\texttt{and}} and {\tt or}\index{or?\texttt{or}}. The +{\tt and} operator is a \tdescr{primary binop} and the {\tt or} operator +is a \tdescr{secondary binop}. The basic operations on strings are concatenation\index{concatenation} and substring construction. The \tdescr{tertiary binop} \verb|&|\index{&?\texttt{\&}}\label{Damp} implements concatenation; e.g., $$ \hbox{\verb|"abc" & "de"|} $$ -produces the string \verb|"abcde"|. -For substring construction, the -\tdescr{of operator} {\tt substring}\index{substring of?\texttt{substring of}}\label{Dsubstr} -is used like this: +produces the string \verb|"abcde"|. For substring construction, the +\tdescr{of operator} {\tt substring}\index{substring +of?\texttt{substring of}}\label{Dsubstr} is used like this: $$ {\tt substring}\, \descr{pair expression} \,{\tt of}\, \descr{string primary} $$ -The \tdescr{pair expression} determines what part of the string to select. For -this purpose, the string is indexed\index{indexing} so that integer positions -fall {\em between\/} characters. Pretend the string is written on a piece of -graph paper -so that the first character occupies $x$~coordinates between zero and one and the -next character covers the range $1\le x\le2$, etc. Thus the string \verb|"abcde"| +The \tdescr{pair expression} determines what part of the string to +select. For this purpose, the string is indexed\index{indexing} so that +integer positions fall {\em between\/} characters. Pretend the string +is written on a piece of graph paper so that the first character +occupies $x$~coordinates between zero and one and the next character +covers the range $1\le x\le2$, etc. Thus the string \verb|"abcde"| should be thought of like this -$$ \epsfbox{manfig.14} $$ -and {\tt substring (2,4) of "abcde"} is {\tt "cd"}. This takes a little getting -used to but it tends to avoid annoying ``off by one'' errors. +$$ \includegraphics{manfig-14} $$ +and {\tt substring (2,4) of "abcde"} is {\tt "cd"}. This takes a little +getting used to but it tends to avoid annoying ``off by one'' errors. -Some operators take no arguments at all. An example of what Figure~\ref{syexpr} -calls a \tdescr{nullary op} is -{\tt nullpicture}\index{nullpicture?\texttt{nullpicture}}\label{Dnlpic} which +Some operators take no arguments at all. An example of what +Figure~\ref{syexpr} calls a \tdescr{nullary op} is {\tt +nullpicture}\index{nullpicture?\texttt{nullpicture}}\label{Dnlpic} which returns a completely blank picture. -The basic syntax in Figure~\ref{syexpr} only covers aspects of the expression -syntax that are relatively type-independent. For instance, the complicated path -syntax given in Figure~\ref{sypath} gives alternative rules for constructing a -\tdescr{path expression}. An additional rule\index{path knot?\tdescr{path knot}} +The basic syntax in Figure~\ref{syexpr} only covers aspects of the +expression syntax that are relatively type-independent. For instance, +the complicated path syntax given in Figure~\ref{sypath} gives +alternative rules for constructing a \tdescr{path expression}. An +additional rule\index{path knot?\tdescr{path knot}} $$ \descr{path knot} \rightarrow \descr{pair tertiary} \;|\; \descr{path tertiary} $$ explains the meaning of \tdescr{path knot} in Figure~\ref{sypath}. This means @@ -1042,12 +1166,12 @@ $$ \descr{primary} \rightarrow \hbox{\tt ,} \descr{expression} \hbox{\tt ]} $$ where each \tdescr{expression} can be of type numeric, pair, or color. -The \tdescr{numeric atom}\index{numeric atom?\tdescr{numeric atom}} in a mediation -expression is an extra simple type of \tdescr{numeric primary} as -shown in Figure~\ref{synprim}. The meaning of all this is that the initial -parameter in a mediation expression needs to be parenthesized when it is not -just a variable, a positive number, or a positive fraction. -For example,\index{parsing irregularities} +The \tdescr{numeric atom}\index{numeric atom?\tdescr{numeric atom}} in a +mediation expression is an extra simple type of \tdescr{numeric primary} +as shown in Figure~\ref{synprim}. The meaning of all this is that the +initial parameter in a mediation expression needs to be parenthesized +when it is not just a variable, a positive number, or a positive +fraction. For example,\index{parsing irregularities} $$ \hbox{\tt -1[a,b]} \quad {\rm and}\quad \hbox{\tt (-1)[a,b]} $$ are very different: the former is $-b$ since it is equivalent to {\tt -(1[a,b])}; the latter is $a-(b-a)$ or $2a-b$. @@ -1066,88 +1190,99 @@ $\tt \qquad \;|\; \descr{numeric nullary op}$\\ $\tt \descr{number or fraction} \rightarrow \descr{number} \hbox{\tt /}\descr{number}$\\ $\tt \qquad \;|\; \descr{number not followed by - `$\hbox{\tt /}\descr{number}$'}$\\ + `$\hbox{\tt /}\descr{number}$'}$ \end{ctabbing} \caption{Syntax rules for numeric primaries} \label{synprim} \end{figure} -A noteworthy feature of the syntax rules in Figure~\ref{synprim} is that the -{\tt /}\index{fractions} operator binds most tightly when its operands are -numbers. Thus {\tt 2/3} is a -\tdescr{numeric atom}\index{numeric atom?\tdescr{numeric atom}}\index{parsing irregularities} -while {\tt (1+1)/3} is only a \tdescr{numeric secondary}. Applying a -\tdescr{primary binop} such as {\tt sqrt}\index{sqrt?\texttt{sqrt}}\label{Dsqrt} -makes the difference clear: +A noteworthy feature of the syntax rules in Figure~\ref{synprim} is that +the {\tt /}\index{fractions} operator binds most tightly when its +operands are numbers. Thus {\tt 2/3} is a \tdescr{numeric +atom}\index{numeric atom?\tdescr{numeric atom}}\index{parsing +irregularities} while {\tt (1+1)/3} is only a \tdescr{numeric +secondary}. Applying a \tdescr{primary binop} such as {\tt +sqrt}\index{sqrt?\texttt{sqrt}}\label{Dsqrt} makes the difference clear: $$ \hbox{\tt sqrt 2/3} $$ means $\sqrt{2\over3}$ while $$ \hbox{\tt sqrt(1+1)/3} $$ -means $\sqrt 2/3$. -Operators such as {\tt sqrt} can be written in standard functional notation, -but it is often unnecessary to parenthesize the argument. This applies to any -function that is parsed as a \tdescr{primary binop}. For instance -{\tt abs(x)}\index{abs?\texttt{abs}}\label{Dabs} and {\tt abs x} both compute the -absolute value of {\tt x}. The same holds for the -{\tt round}\index{round?\texttt{round}}\label{Dround}, -{\tt floor}\index{floor?\texttt{floor}}\label{Dfloor}, -{\tt ceiling}\index{ceiling?\texttt{ceiling}}\label{Dceil}, -{\tt sind}\index{sind?\texttt{sind}}\label{Dsind}, -and {\tt cosd}\index{cosd?\texttt{cosd}}\label{Dcosd} -functions. The last two of these compute trigonometric functions of angles in -degrees. - -Not all unary operators take numeric arguments and return numeric results. -For instance, the {\tt abs}\index{abs?\texttt{abs}} operator can be applied to a pair -to compute the Euclidean length of a vector. Applying the -{\tt unitvector}\index{unitvector?\texttt{unitvector}}\label{Duvec} operator to a pair produces -the same pair rescaled so that its Euclidean length is~1. -The {\tt decimal}\index{decimal?\texttt{decimal}}\label{Ddecop} -operator takes a number and returns the string representation. -The {\tt angle}\index{angle?\texttt{angle}}\label{Dangle} -operator takes a pair and computes the two-argument arctangent; i.e., {\tt angle} -is the inverse of the {\tt dir} operator that was discussed in -Section~\ref{tenscurl}. There is also an operator -{\tt cycle}\index{cycle?\texttt{cycle}}\label{Dcycop} -that takes a \tdescr{path primary} and returns a boolean result indicating whether +means $\sqrt 2/3$. Operators such as {\tt sqrt} can be written in +standard functional notation, but it is often unnecessary to +parenthesize the argument. This applies to any function that is parsed +as a \tdescr{primary binop}. For instance {\tt +abs(x)}\index{abs?\texttt{abs}}\label{Dabs} and {\tt abs x} both compute +the absolute value of {\tt x}. The same holds for the {\tt +round}\index{round?\texttt{round}}\label{Dround}, {\tt +floor}\index{floor?\texttt{floor}}\label{Dfloor}, {\tt +ceiling}\index{ceiling?\texttt{ceiling}}\label{Dceil}, {\tt +sind}\index{sind?\texttt{sind}}\label{Dsind}, and {\tt +cosd}\index{cosd?\texttt{cosd}}\label{Dcosd} functions. The last two of +these compute trigonometric functions of angles in degrees. + +Not all unary operators take numeric arguments and return numeric +results. For instance, the {\tt abs}\index{abs?\texttt{abs}} operator +can be applied to a pair to compute the Euclidean length of a vector. +Applying the {\tt +unitvector}\index{unitvector?\texttt{unitvector}}\label{Duvec} operator +to a pair produces the same pair rescaled so that its Euclidean length +is~1. The {\tt decimal}\index{decimal?\texttt{decimal}}\label{Ddecop} +operator takes a number and returns the string representation. The {\tt +angle}\index{angle?\texttt{angle}}\label{Dangle} operator takes a pair +and computes the two-argument arctangent; i.e., {\tt angle} is the +inverse of the {\tt dir} operator that was discussed in +Section~\ref{tenscurl}. There is also an operator {\tt +cycle}\index{cycle?\texttt{cycle}}\label{Dcycop} that takes a +\tdescr{path primary} and returns a boolean result indicating whether the path is a closed curve. -There is a whole class of other operators that classify expressions and return -boolean results. A type name such as {\tt pair}\index{pair?\texttt{pair}} can operate on -any type of \tdescr{primary} and return a boolean result indicating whether the -argument is a {\tt pair}\label{Dpairop}. Similarly, each of the following can -be used as a unary operator: -{\tt numeric}\index{numeric?\texttt{numeric}}\label{Dnumop}, -{\tt boolean}\index{boolean?\texttt{boolean}}\label{Dboolop}, -{\tt color}\index{color?\texttt{color}}\label{Dcolrop}, -{\tt string}\index{string?\texttt{string}}\label{Dstrgop}, -{\tt transform}\index{transform?\texttt{transform}}\label{Dtrnfop}, -{\tt path}\index{path?\texttt{path}}\label{Dpathop}, -{\tt pen}\index{pen?\texttt{pen}}\label{Dpenop}, -and {\tt picture}\index{picture?\texttt{picture}}\label{Dpictop}. -Besides just testing the type of a \tdescr{primary}, you can use the -{\tt known}\index{known?\texttt{known}}\label{Dknown} and -{\tt unknown}\index{unknown?\texttt{unknown}}\label{Dunknwn} operators to +There is a whole class of other operators that classify expressions and +return boolean results. A type name such as {\tt +pair}\index{pair?\texttt{pair}} can operate on any type of +\tdescr{primary} and return a boolean result indicating whether the +argument is a {\tt pair}\label{Dpairop}. Similarly, each of the +following can be used as a unary operator: +{\tt numeric}\index{numeric?\texttt{numeric}}\label{Dnumop}, +{\tt boolean}\index{boolean?\texttt{boolean}}\label{Dboolop}, +{\tt cmykcolor}\index{cmykcolor?\texttt{cmykcolor}}\label{Dccolrop}, +{\tt color}\index{color?\texttt{color}}\label{Dcolrop}, +{\tt string}\index{string?\texttt{string}}\label{Dstrgop}, +{\tt transform}\index{transform?\texttt{transform}}\label{Dtrnfop}, +{\tt path}\index{path?\texttt{path}}\label{Dpathop}, +{\tt pen}\index{pen?\texttt{pen}}\label{Dpenop}, +{\tt picture}\index{picture?\texttt{picture}}\label{Dpictop}, and +{\tt rgbcolor}\index{rgbcolor?\texttt{rgbcolor}}\label{Drcolrop}. +Besides just +testing the type of a \tdescr{primary}, you can use the {\tt +known}\index{known?\texttt{known}}\label{Dknown} and {\tt +unknown}\index{unknown?\texttt{unknown}}\label{Dunknwn} operators to test if it has a completely known value. -Even a number can behave like an operator in some contexts. -This refers to the trick that allows {\tt 3x}\index{multiplication, implicit} and -{\tt 3cm} as alternatives to {\tt 3*x} and {\tt 3*cm}. The rule is that a -\tdescr{number or fraction} that is not followed by {\tt +}, {\tt -}, or another -\tdescr{number or fraction} can serve as a \tdescr{primary binop}. -Thus {\tt 2/3x}\index{parsing irregularities} -is two thirds of {\tt x} but {\tt (2)/3x} is $2\over3x$ and {\tt 3 3} is illegal. - -There are also operators for extracting numeric subfields from pairs, colors, -and even transforms. If {\tt p} is a \tdescr{pair primary}, -{\tt xpart p}\index{xpart?\texttt{xpart}}\label{Dxprt} and -{\tt ypart p}\index{ypart}\label{Dyprt} extract its -components so that -$$ \hbox{\tt (xpart p, ypart p)} $$ -is equivalent to~{\tt p} even if {\tt p} is an unknown pair that is being used -in a linear equation. Similarly, a color {\tt c} is equivalent -to\index{redpart?\texttt{redpart}}\index{greenpart?\texttt{greenpart}}\index{bluepart?\texttt{bluepart}}\label{Drgbprt} -$$ \hbox{\tt (redpart c, greenpart c, bluepart c)} $$ -The part specifiers for transforms will be discussed later. +Even a number can behave like an operator in some contexts. This refers +to the trick that allows {\tt 3x}\index{multiplication, implicit} and +{\tt 3cm} as alternatives to {\tt 3*x} and {\tt 3*cm}. The rule is that +a \tdescr{number or fraction} that is not followed by {\tt +}, {\tt -}, +or another \tdescr{number or fraction} can serve as a \tdescr{primary +binop}. Thus {\tt 2/3x}\index{parsing irregularities} is two thirds of +{\tt x} but {\tt (2)/3x} is $2\over3x$ and {\tt 3 3} is illegal. + +There are also operators for extracting numeric subfields from pairs, +colors, cmykcolors, and even transforms. If {\tt p} is a \tdescr{pair +primary}, {\tt xpart p}\index{xpart?\texttt{xpart}}\label{Dxprt} and +{\tt ypart p}\index{ypart}\label{Dyprt} extract its components so that +$$ \hbox{\tt (xpart p, ypart p)} $$ is equivalent to~{\tt p} even if +{\tt p} is an unknown pair that is being used in a linear equation. +Similarly, a color {\tt c} is equivalent +to\index{redpart?\texttt{redpart}}% +\index{greenpart?\texttt{greenpart}}% +\index{bluepart?\texttt{bluepart}}\label{Drgbprt} +$$ \hbox{\tt (redpart c, greenpart c, bluepart c)} $$. +For a cmykcolor {\tt c}, the parts are:\index{cyanpart?\texttt{cyanpart}}% +\index{magentapart?\texttt{magentapart}}% +\index{yellowpart?\texttt{yellowpart}}% +\index{blackpart?\texttt{blackpart}}\label{Dcmykprt} +$$ \hbox{\tt (cyanpart c, magentapart c, yellowpart c, blackpart c)} $$ +The part +specifiers for transforms will be discussed later. \section{Variables} @@ -1163,14 +1298,15 @@ comments about tokens. \subsection{Tokens} -A MetaPost input file is treated as a sequence of numbers, string constants, and -symbolic tokens\index{tokens}\index{tokens!symbolic}. A number consists of a -sequence of digits possibly containing -a decimal point. Technically, the minus sign in front of a negative number is -a separate token. Since MetaPost uses fixed point arithmetic\index{arithmetic}, -it does not understand exponential notation such as {\tt 6.02E23}. MetaPost -would interpret this as the number 6.02, followed by the symbolic token {\tt E}, -followed by the number~23. +A MetaPost input file is treated as a sequence of numbers, string +constants, and symbolic tokens\index{tokens}\index{tokens!symbolic}. A +number consists of a sequence of digits possibly containing a decimal +point. Technically, the minus sign in front of a negative number is a +separate token. Since MetaPost uses fixed point +arithmetic\index{arithmetic}, it does not understand exponential +notation such as {\tt 6.02E23}. MetaPost would interpret this as the +number 6.02, followed by the symbolic token {\tt E}, followed by the +number~23. Anything between a pair of double quotes {\tt "} is a string constant\index{string constants}. It is @@ -1202,18 +1338,19 @@ $$ \label{classes} \end{table} -Thus \verb|A_alpha| and {\tt +-+} are symbolic tokens but {\tt !=} is interpreted -as two tokens and {\tt x34} is a symbolic token followed by a number. Since the -brackets {\tt [} and {\tt ]} are listed on lines by themselves, the only symbolic -tokens involving them are {\tt [}, {\tt [[}, {\tt [[[}, etc.\ and -{\tt ]}, {\tt ]]}, etc. +Thus \verb|A_alpha| and {\tt +-+} are symbolic tokens but {\tt !=} is +interpreted as two tokens and {\tt x34} is a symbolic token followed by +a number. Since the brackets {\tt [} and {\tt ]} are listed on lines by +themselves, the only symbolic tokens involving them are {\tt [}, {\tt +[[}, {\tt [[[}, etc.\ and {\tt ]}, {\tt ]]}, etc. -Some characters are not listed in Table~\ref{classes} because they need special -treatment. The four characters {\tt ,;()} are ``loners'': each comma, semicolon, -or parenthesis is a separate token even when they occur consecutively. Thus -{\tt (())} is four tokens, not one or two. The percent sign is very special -because it introduces comments\index{comments}. The percent sign and everything -after it up to the end of the line are ignored. +Some characters are not listed in Table~\ref{classes} because they need +special treatment. The four characters {\tt ,;()} are ``loners'': each +comma, semicolon, or parenthesis is a separate token +even when they occur consecutively. Thus {\tt (())} is four tokens, not +one or two. The percent sign is very special because it introduces +comments\index{comments}. The percent sign and everything after it up +to the end of the line are ignored. Another special character is the period. Two or more periods together form a symbolic token, but a single period is ignored, and a period @@ -1226,23 +1363,24 @@ when naming a variable that is more than one token long. \label{vardecl} A variable name is a symbolic token or a sequence of symbolic tokens. -Most symbolic -tokens are legitimate variable names, but anything with a predefined meaning like -{\tt draw}, {\tt +}, or {\tt ..} is disallowed; i.e., variable names cannot be -macros or MetaPost primitives. This minor restriction allows an amazingly broad -class of variable names: {\tt alpha}, \verb|==>|, \verb|@&#$&|, and \verb|~~| are -all legitimate variable names. Such symbolic tokens without special meanings -are called {\em tags}\index{tags}. - -A variable name can be a sequence of tags like {\tt f.bot} or {\tt f.top}. -The idea is to provide some of the functionality of Pascal records or C structures. -It is also possible to simulate arrays by using variable names that contain -numbers as well as symbolic tokens. For example, the variable name {\tt x2r} -consists of the tag {\tt x}, the number 2, and the tag~{\tt r}. There can also -be variables named {\tt x3r} and even {\tt x3.14r}. These variables can be -treated as an array\index{arrays} via constructions like {\tt x[i]r}, -where {\tt i} has an appropriate numeric value. The overall syntax for -variable names is shown in Figure~\ref{syvar}. +Most symbolic tokens are legitimate variable names, but anything with a +predefined meaning like {\tt draw}, {\tt +}, or {\tt ..} is disallowed; +i.e., variable names cannot be macros or MetaPost primitives. This +minor restriction allows an amazingly broad class of variable names: +{\tt alpha}, \verb|==>|, \verb|@&#$&|, and \verb|~~| are all legitimate +variable names. Such symbolic tokens without special meanings are +called {\em tags}\index{tags}. + +A variable name can be a sequence of tags like {\tt f.bot} or {\tt +f.top}. The idea is to provide some of the functionality of Pascal +records or C structures. It is also possible to simulate arrays by +using variable names that contain numbers as well as symbolic tokens. +For example, the variable name {\tt x2r} consists of the tag {\tt x}, +the number 2, and the tag~{\tt r}. There can also be variables named +{\tt x3r} and even {\tt x3.14r}. These variables can be treated as an +array\index{arrays} via constructions like {\tt x[i]r}, where {\tt i} +has an appropriate numeric value. The overall syntax for variable names +is shown in Figure~\ref{syvar}. \begin{figure}[htp] \begin{ctabbing} @@ -1261,29 +1399,30 @@ Variables like {\tt x2} and {\tt y2} take on numeric values by default, so we can use the fact that {\tt z}\tdescr{suffix} is an abbreviation for\index{z convention?{\tt z} convention}\label{Dzconv} $$ (x\descr{suffix},\, y\descr{suffix}) $$ to generate pair-valued variables when needed. It turns out that the -{\tt beginfig}\index{beginfig?\texttt{beginfig}} macro wipes out pre-existing values variables -that begin with the tags {\tt x} or {\tt y} so that -{\tt beginfig} \ldots\ {\tt endfig} -blocks do not interfere with each other when this naming scheme is used. -In other words, variables that start with {\tt x}, {\tt y}, {\tt z} are -local\index{variables!local}\index{locality} -to the figure they are used in. General mechanisms for making variables local -will be discussed in Section~\ref{grsec}. +{\tt beginfig}\index{beginfig?\texttt{beginfig}} macro wipes out +pre-existing values variables that begin with the tags {\tt x} or {\tt +y} so that {\tt beginfig} \ldots\ {\tt endfig} blocks do not interfere +with each other when this naming scheme is used. In other words, +variables that start with {\tt x}, {\tt y}, {\tt z} are +local\index{variables!local}\index{locality} to the figure they are used +in. General mechanisms for making variables local will be discussed in +Section~\ref{grsec}. Type declarations\index{declarations}\index{type declarations} make it possible to use almost any naming scheme while still wiping out any previous value that might cause interference. For example, the declaration $$ \hbox{\tt pair pp, a.b;} $$ -makes {\tt pp} and {\tt a.b} unknown pairs. Such a declaration is not strictly -local since {\tt pp} and {\tt a.b} are not automatically restored to their -previous values at the end of the current figure. Of course, they are restored -to unknown pairs if the declaration is repeated. - -Declarations work the same way for any of -the other eight types: numeric, path, transform, color, string, boolean, picture, -and pen. The only restriction is that you cannot give explicit numeric subscripts -in a variable declaration. Do not give the illegal declaration +makes {\tt pp} and {\tt a.b} unknown pairs. Such a declaration is not +strictly local since {\tt pp} and {\tt a.b} are not automatically +restored to their previous values at the end of the current figure. Of +course, they are restored to unknown pairs if the declaration is +repeated. + +Declarations work the same way for any of the other eight types: +numeric, path, transform, color, string, boolean, picture, and pen. The +only restriction is that you cannot give explicit numeric subscripts in +a variable declaration. Do not give the illegal declaration $$ \hbox{\tt numeric q1, q2, q3;} $$ use the generic subscript\index{subscript!generic} symbol {\tt []}\index{[]?\texttt{[]}} instead, to declare the whole array: @@ -1293,56 +1432,60 @@ After the declaration $$ \hbox{\tt path p[]q[], pq[][];} $$ {\tt p2q3} and {\tt pq1.4 5} are both paths. -Internal\index{internal variables}\index{variables!internal} -variables like {\tt tracingonline} cannot be declared in -the normal fashion. All the internal variables discussed in this manual are -predefined and do not have to be declared at all, but there is a way to declare -that a variable should behave like a newly-created internal variable. -The declaration is {\tt newinternal}\index{newinternal?\texttt{newinternal}}\label{Dnewint} +Internal\index{internal variables}\index{variables!internal} variables +like {\tt tracingonline} cannot be declared in the normal fashion. All +the internal variables discussed in this manual are predefined and do +not have to be declared at all, but there is a way to declare that a +variable should behave like a newly-created internal variable. The +declaration is {\tt +newinternal}\index{newinternal?\texttt{newinternal}}\label{Dnewint} followed by a list of symbolic tokens. For example, $$ \hbox{\tt newinternal a, b, c;} $$ -causes {\tt a}, {\tt b}, and {\tt c} to behave like internal variables. Such -variables always have known numeric values, and these values can only be changed -by using the assignment\index{assignment} operator {\tt:=}\index{:=?\texttt{:=}}. -Internal variables are initially zero -except that the Plain\index{Plain macros} macro package gives some of them nonzero -initial values. (The Plain macros are normally preloaded automatically as -explained in Section~\ref{intro}.) +causes {\tt a}, {\tt b}, and {\tt c} to behave like internal variables. +Such variables always have known numeric values, and these values can +only be changed by using the assignment\index{assignment} operator +{\tt:=}\index{:=?\texttt{:=}}. Internal variables are initially zero +except that the Plain\index{Plain macros} macro package gives some of +them nonzero initial values. (The Plain macros are normally preloaded +automatically as explained in Section~\ref{intro}.) \section{Integrating Text and Graphics} \label{text} MetaPost has a number of features for including labels and other -text\index{text and graphics} -in the figures it generates. The simplest way to do this is to use the -{\tt label}\index{label?\texttt{label}}\label{Dlabel} statement\index{label suffix?\tdescr{label suffix}} +text\index{text and graphics} in the figures it generates. The simplest +way to do this is to use the {\tt +label}\index{label?\texttt{label}}\label{Dlabel} statement\index{label +suffix?\tdescr{label suffix}} $$ {\tt label}\descr{label suffix} \hbox{\tt (} \descr{string or picture expression} \hbox{\tt,}\, \descr{pair expression} \hbox{\tt );} $$ The \tdescr{string or picture expression} gives the label and the -\tdescr{pair expression} says where to put it. The \tdescr{label suffix} can be -\tdescr{empty} in which case the label is just centered on the given coordinates. -If you are labeling some feature of a diagram you probably want to offset the -label slightly to avoid overlapping. This is illustrated in Figure~\ref{fig16} -where the {\tt "a"} label is placed above the midpoint of the line it refers to -and the {\tt "b"} label is to the left of the midpoint of its line. This is -achieved by using {\tt label.top}\index{top?\texttt{top}} for the {\tt "a"} label and -{\tt label.lft}\index{lft?\texttt{lft}} -for the {\tt "b"} label as shown in the figure. The \tdescr{label suffix} -specifies the position of the label relative to the specified coordinates. -The complete set of possibilities is\index{rt?\texttt{rt}}\index{bot?\texttt{bot}}% +\tdescr{pair expression} says where to put it. The \tdescr{label +suffix} can be \tdescr{empty} in which case the label is just centered +on the given coordinates. If you are labeling some feature of a diagram +you probably want to offset the label slightly to avoid overlapping. +This is illustrated in Figure~\ref{fig16} where the {\tt "a"} label is +placed above the midpoint of the line it refers to and the {\tt "b"} +label is to the left of the midpoint of its line. This is achieved by +using {\tt label.top}\index{top?\texttt{top}} for the {\tt "a"} label +and {\tt label.lft}\index{lft?\texttt{lft}} for the {\tt "b"} label as +shown in the figure. The \tdescr{label suffix} specifies the position +of the label relative to the specified coordinates. The complete set of +possibilities is\index{rt?\texttt{rt}}\index{bot?\texttt{bot}}% \index{ulft?\texttt{ulft}}\index{urt?\texttt{urt}}\index{llft?\texttt{llft}}\index{lrt?\texttt{lrt}} $$ \tt \descr{label suffix} \rightarrow \descr{empty} \;|\; lft \;|\; rt \;|\; top \;|\; bot \;|\; ulft \;|\;urt \;|\; llft \;|\; lrt $$ -where {\tt lft} and {\tt rt} mean left and right and {\tt llft}, {\tt ulft}, etc.\ -mean lower left, upper left, etc. The actual amount by which the label is offset -in whatever direction is determined by the +where {\tt lft} and {\tt rt} mean left and right and {\tt llft}, {\tt +ulft}, etc.\ mean lower left, upper left, etc. The actual amount by +which the label is offset in whatever direction is determined by the internal variable\index{internal variables}\index{variables!internal} -{\tt labeloffset}\index{labeloffset?\texttt{labeloffset}}\label{Dlaboff}. +{\tt +labeloffset}\index{labeloffset?\texttt{labeloffset}}\label{Dlaboff}. \begin{figure}[htp] $$ @@ -1359,7 +1502,7 @@ label.lft("b", .5[z0,z2]); dotlabel.bot("(0,0)", z0); endfig; \end{verbatim} -\qquad \mathcenter{\epsfbox{manfig.17}} +\qquad \mathcenter{\includegraphics{manfig-17}} $$ \caption{MetaPost code and the resulting output} \label{fig16} @@ -1367,11 +1510,12 @@ $$ Figure~\ref{fig16} also illustrates the {\tt dotlabel}\index{dotlabel?\texttt{dotlabel}}\label{Ddotlab} -statement. This is exactly -like the {\tt label} statement except that it adds a dot at the indicated -coordinates. For example +statement. This is effectively +like a {\tt label} statement followed by a statement drawing a dot at +the indicated coordinates. For example $$ \hbox{\tt dotlabel.bot("(0,0)", z0)} $$ places a dot at {\tt z0} and then puts the label ``(0,0)'' just below the dot. + Another alternative is the macro {\tt thelabel}\index{thelabel?\texttt{thelabel}}\label{Dthelab}. This has the same syntax as the {\tt label} and {\tt dotlabel} statements except that it @@ -1381,12 +1525,12 @@ $$ \hbox{\tt label.bot("(0,0)", z0)} $$ is equivalent to $$ \hbox{\tt draw thelabel.bot("(0,0)", z0)} $$ -For simple applications of labeled figures, you can normally get by with just -{\tt label} and {\tt dotlabel}. In fact, you may be able to use a short form of -the {\tt dotlabel} statement that saves a lot of typing -when you have many points {\tt z0}, {\tt z1}, {\tt z.a}, {\tt z.b}, etc.\ -and you want to use the {\tt z} suffixes as labels. -The statement\index{dotlabels?\texttt{dotlabels}}\label{Ddotlbs} +For simple applications of labeled figures, you can normally get by with +just {\tt label} and {\tt dotlabel}. In fact, you may be able to use a +short form of the {\tt dotlabel} statement that saves a lot of typing +when you have many points {\tt z0}, {\tt z1}, {\tt z.a}, {\tt z.b}, +etc.\ and you want to use the {\tt z} suffixes as labels. The +statement\index{dotlabels?\texttt{dotlabels}}\label{Ddotlbs} $$ \hbox{\tt dotlabels.rt(0, 1, a);} $$ is equivalent to $$ \hbox{\tt dotlabel.rt("0",z0); dotlabel.rt("1",z1); dotlabel.rt("a",z.a);} $$ @@ -1394,48 +1538,61 @@ Thus the argument to {\tt dotlabels} is a list of suffixes for which {\tt z} variables are known, and the \tdescr{label suffix} given with {\tt dotlabels} is used to position all the labels. -There is also a {\tt labels}\index{labels?\texttt{labels}}\label{Dlabels} statement that is -analogous to -{\tt dotlabels} but its use is discouraged because it presents compatibility -problems with \MF\index{metafont?\MF}. Some versions of the preloaded -Plain\index{Plain macros} macro package define {\tt labels} to be synonymous -with {\tt dotlabels}. - -For labeling statements such as {\tt label} and {\tt dotlabel} that use a -string expression for the label text, -the string gets typeset in a default font as determined by -the string variable {\tt defaultfont}\index{defaultfont?\texttt{defaultfont}}\label{Ddffont}. -The initial value of {\tt defaultfont} -is likely to be {\tt "cmr10"}, but it can be changed to a different font name -by giving an assignment such as -$$ \hbox{\tt defaultfont:="Times-Roman"} $$ +There is also a {\tt +labels}\index{labels?\texttt{labels}}\label{Dlabels} statement that is +analogous to {\tt dotlabels} but its use is discouraged because it +presents compatibility problems with \MF\index{metafont?\MF}. Some +versions of the preloaded Plain\index{Plain macros} macro package define +{\tt labels} to be synonymous with {\tt dotlabels}. + +For labeling statements such as {\tt label} and {\tt dotlabel} that use +a string expression for the label text, the string gets typeset in a +default font as determined by the string variable {\tt +defaultfont}\index{defaultfont?\texttt{defaultfont}}\label{Ddffont}. +The initial value of {\tt defaultfont} is likely to be {\tt "cmr10"}, +but it can be changed to a different font name by giving an assignment +such as +$$ \hbox{\tt defaultfont:="ptmr8r"} $$ +\ttt{ptmr8r} is a typical way to refer to the Times-Roman font in \TeX. +The discussion of font names on p.\ \pageref{fontname} explains further. + There is also a numeric quantity called {\tt defaultscale}\index{defaultscale?\texttt{defaultscale}}\label{Ddfscale} that determines the type size. When {\tt default\-scale} is 1, you get the ``normal size'' which is usually 10 point, but this can also be changed. For instance $$ \hbox{\tt defaultscale := 1.2} $$ -makes labels come out twenty percent larger. If you do not know the normal size -and you want to be sure the text comes out at some specific size, say 12 points, -you can use the {\tt fontsize}\index{fontsize?\texttt{fontsize}}\label{Dfntsiz} -operator to determine the normal size: e.g., +makes labels come out twenty percent larger. If you do not know the +normal size and you want to be sure the text comes out at some specific +size, say 12 points, you can use the {\tt +fontsize}\index{fontsize?\texttt{fontsize}}\label{Dfntsiz} operator to +determine the normal size: e.g., $$ \hbox{\tt defaultscale := 12pt/fontsize defaultfont;} $$ -When you change {\tt defaultfont}, the new font name should be something that -\TeX\ would understand since MetaPost gets height and width information by reading -the {\tt tfm}\index{tfm file?{\tt tfm} file}\index{files!tfm?{\tt tfm}} file. -(This is explained in {\it The \TeX book\/}.~\cite{kn:a}) -It should be possible to use built-in PostScript fonts, but the names for them -are system-dependent. Some systems may use {\tt rptmr} or {\tt ps-times-roman} -instead of {\tt Times-Roman}. -A \TeX\index{TeX?\TeX} font such as {\tt cmr10} is a little dangerous because it does -not have a space character or certain ASCII symbols. In addition, MetaPost does -not use the ligatures\index{ligatures} and kerning\index{kerning} information -that comes with a \TeX\ font. +\label{fontname} +When you change {\tt defaultfont}, the new font name should be something +that \TeX\ would understand since MetaPost gets height and width +information by reading a {\tt tfm}\index{tfm file?{\tt tfm} +file}\index{files!tfm?{\tt tfm}} file. (This is explained in {\sl The +\TeX book\/} \cite{kn:a}.) It should be possible to use built-in +PostScript fonts, but the names for them are system-dependent. Some +typical ones are {\tt ptmr8r} for Times-Roman, \ttt{pplr8r} for +Palatino, and \ttt{phvr} for Helvetica. The Fontname document, +available at \url{http://tug.org/fontname}, has much more information +about font names and TeX. A \TeX\index{TeX fonts?\TeX\ fonts} font such +as {\tt cmr10} is a little dangerous because it does not have a space +character or certain ASCII symbols. + +MetaPost does not use the ligatures\index{ligatures} and +kerning\index{kerning} information that comes with a \TeX\ font. +Further, MetaPost does not interpret virtual fonts. \subsection{Typesetting Your Labels} +\label{Dbtex} +\index{labels, typesetting} + \TeX\index{TeX?\TeX} may be used to format complex labels. If you say\index{btex?\texttt{btex}}\index{etex?\texttt{etex}} $$ {\tt btex}\, \descr{typesetting commands}\, {\tt etex} $$ @@ -1463,9 +1620,9 @@ label.bot(btex $x$ etex, (2u,0)); label.lft(btex $y$ etex, (0,u)); endfig; \end{verbatim} -\qquad \mathcenter{\epsfbox{manfig.18}} +\qquad \mathcenter{\includegraphics{manfig-18}} $$ -\caption{MetaPost code and the resulting output} +\caption{Arbitrary \TeX\ as labels} \label{fig17} \end{figure} @@ -1499,9 +1656,9 @@ label.lft( (120ux, 4uy)); endfig; \end{verbatim} -\qquad \mathcenter{\epsfbox{manfig.19}} +\qquad \mathcenter{\includegraphics{manfig-19}} $$ -\caption{MetaPost code and the resulting output} +\caption{\TeX\ labels with display math, and rotated by MetaPost} \label{fig18} \end{figure} @@ -1512,72 +1669,176 @@ $$ \hbox{\verb|$$y={2\over 1+\cos x}$$|} $$ but this would not work because \TeX\ typesets the labels in ``horizontal mode.'' -Here is how \TeX\ material gets translated into a form MetaPost understands: -The MetaPost processor skips over -{\tt btex}\index{btex?\texttt{btex}} \ldots\ {\tt etex}\index{etex?\texttt{etex}} blocks -and depends on a preprocessor to translate them into low level MetaPost -commands. If the main file is {\tt fig.mp}, the translated \TeX\ -material is placed in a file named {\tt fig.mpx}\index{files!mpx?{\tt mpx}}. -This is normally -done silently without any user intervention but it could fail if one of -the {\tt btex} $\ldots$ {\tt etex} blocks contains an erroneous -\TeX\index{TeX?\TeX!errors} command. Then the erroneous \TeX\ input -is saved in the file {\tt mpxerr.tex}\index{mpxerr.tex?\texttt{mpxerr.tex}} and the error -messages appear in {\tt mpxerr.log}\index{mpxerr.log?\texttt{mpxerr.log}}. - -\TeX\ macro definitions or any other auxiliary -\TeX\ commands can be enclosed in a -{\tt verbatimtex}\index{verbatimtex?\texttt{verbatimtex}} \ldots\ {\tt etex}\index{etex?\texttt{etex}} block. -The difference between -{\tt btex} and {\tt verbatimtex} is that the former generates a picture -expression while the latter only adds material for \TeX\ to process. -For instance, if you want \TeX\ to typeset labels using macros defined in -{\tt mymac.tex}, your MetaPost input file would look something like this: +For a way to typeset \emph{variable} text as labels, see the +\texttt{TEX} utility routine described on p.\ \pageref{dTEX}. + +Here is how \TeX\ material gets translated into a form MetaPost +understands: The MetaPost processor skips over {\tt +btex}\index{btex?\texttt{btex}} \ldots\ {\tt +etex}\index{etex?\texttt{etex}} blocks and depends on a preprocessor to +translate them into low level MetaPost commands. If the main file is +{\tt fig.mp}, the translated \TeX\ material is placed in a file named +{\tt fig.mpx}\index{files!mpx?{\tt mpx}}. This is normally done +silently without any user intervention but it could fail if one of the +{\tt btex} $\ldots$ {\tt etex} blocks contains an erroneous +\TeX\index{TeX?\TeX!errors} command. Then the erroneous \TeX\ input is +saved in the file {\tt mpxerr.tex}\index{mpxerr.tex?\texttt{mpxerr.tex}} +and the error messages appear in {\tt +mpxerr.log}\index{mpxerr.log?\texttt{mpxerr.log}}. + +The preprocessor for \TeX\ labels {\it does\/} understand virtual +fonts, so you can use your normal \TeX\ font switching commands inside +the label. + +\label{Dverbatimtex} +\TeX\ macro definitions or any other auxiliary \TeX\ commands can be +enclosed in a {\tt verbatimtex}\index{verbatimtex?\texttt{verbatimtex}} +\ldots\ {\tt etex}\index{etex?\texttt{etex}} block. The difference +between {\tt btex} and {\tt verbatimtex} is that the former generates a +picture expression while the latter only adds material for \TeX\ to +process. For instance, if you want \TeX\ to typeset labels using macros +defined in {\tt mymac.tex}, your MetaPost input file would look +something like this: \begin{eqnarray*} && \verb|verbatimtex \input mymac etex|\\ && \verb|beginfig(1);|\\ -&& \qquad \vdots\\ +&& \qquad \dots\\ && \verb|label(btex|\, \descr{\TeX\ material using \hbox{\tt mymac.tex}}\, \verb|etex, | \descr{some coordinates} \hbox{\tt );}\\ -&& \qquad \vdots +&& \qquad \dots \end{eqnarray*} On Unix\footnote{Unix is a registered trademark of Unix Systems -Laboratories.}\index{Unix\reg} -systems, an environment variable can be used to specify that -{\tt btex} $\ldots$ {\tt etex} and {\tt verbatimtex} $\ldots$ {\tt etex} -blocks are in troff\index{troff} instead of \TeX. When using this option, -it is a good idea to start your MetaPost input file with the assignment -{\tt prologues:=1}\index{prologues?\texttt{prologues}}\label{Dprologs}. Giving this -internal variable\index{internal variables}\index{variables!internal} -a positive value causes causes output to be formatted as -``structured PostScript''\index{PostScript!structured} generated on the -assumption that text comes from built-in PostScript fonts. This makes MetaPost -output much more portable, but it has an important drawback: It generally -does not work when you use \TeX\ fonts, since programs that translate \TeX\ -output into PostScript\index{PostScript} need to make special provisions for -\TeX\index{TeX?\TeX!fonts} fonts in -included figures and the standard PostScript structuring rules do not allow -for this. The details on how to include PostScript figures in a paper done -in \TeX\ or troff are system-dependent. They can generally be found in -manual pages and other on-line documentation. A file called {\tt dvips.tex} -is distributed electronically along with the dvips\index{dvips} \TeX\ output -processor. +Laboratories.}\index{Unix\reg} and other Web2C-based systems, the +option {\tt -troff} to MetaPost tells the preprocessor that {\tt btex} +$\ldots$ {\tt etex} and {\tt verbatimtex} $\ldots$ {\tt etex} blocks +are in troff\index{troff} instead of \TeX. When using this option, +MetaPost sets the internal variable +\ttindex{troffmode} to~1\index{prologues?\texttt{prologues}}. + +\label{Dprologues} +Setting \ttt{prologues} can be useful with \TeX, too, not just troff. +Here is some explanation: + +\begin{itemize} +\item When \ttt{prologues} is 0, which is the default, the MetaPost +output files do not have embedded fonts. Fonts in the resulting +output will probably render as Courier\index{Courier} or Times-Roman\index{Times-Roman}. + +\item When \ttt{prologues} is 1, the MetaPost output claims to be +``structured PostScript''\index{PostScript!structured} (EPSF\index{EPSF}), +but it is not completely conformant. This variant is kept for backward +compatibility with old (troff) documents, but its use is deprecated. +For historical reasons, MetaPost sets \ttt{prologues} to~1 when the {\tt +-troff} option is given on the command line. + +\item When \ttt{prologues} is 2, the MetaPost output is EPSF and assumes +that the text comes from PostScript fonts +provided by the ``environment'', such as the document viewer or +embedded application using the output. MetaPost will attempt to +set up the font encodings correctly, based on \ttt{fontmapfile} and +\ttt{fontmapline} commands. + +\item When \ttt{prologues} is 3, the MetaPost output will be EPSF but +will contain the PostScript font(s) (or a subset) used based on the +\ttt{fontmapfile} and \ttt{fontmapline} commands. This value is useful +for generating stand-alone PostScript graphics. +\end{itemize} + +It is worth noting that the default value \ttt{prologues:=0} is sufficient +for graphics included in \TeX-based documents. Also, the \ttt{prologues} variable is irrelevant +when processing MetaPost files through the \ttindex{mptopdf} utility +(part of the \ConTeXt\ distribution), because PDF files are, by nature, +stand-alone. The details on how to include PostScript figures in a paper +done in \TeX\ or troff are system-dependent. They can generally be found +in manual pages and other on-line documentation. The manual for the +widely-used Dvips processor is in a file \ttt{dvips.texi}, included in +most distributions, and is available online at +\url{http://tug.org/texinfohtml/dvips.html}, among many other places and +formats. + +\label{Dmakempx} +On Web2C-based systems, the preprocessor is named \ttindex{makempx}, +which calls another utility \ttindex{mpto}; the Web2C documentation +describes them in more detail. We'll mention one feature here, though: +if the environment variable \ttindex{MPTEXPRE} is set to the name of an +existing file, {\tt makempx} will prepend it to the output. You can use +this to include \LaTeX\ preambles, for instance. The \ttt{TEX} +macro described on p.\ \pageref{dTEX} provides another way to handle this. + + +\subsection{Font map files} +\label{Sfontmapfile}\label{Sfontmapline} + +If \ttt{prologues} is set to~2, any used fonts in the output file are +automatically re-encoded, and the encoding vector file specified in +the fontmap entry will be embedded in the output file. If +\ttt{prologues} is set to~3, MetaPost will also attempt to include +(a subset of) the used PostScript fonts. For this to work, it needs to +acquire font map information. + +The code is based on the font library used by pdf\TeX. Following in +the footsteps of pdf\TeX, there are two new associated primitives: +\ttindex{fontmapfile} and \ttindex{fontmapline}. Here is a simple +example, specifying the map file for Latin Modern fonts in \LaTeX\ +(T1) encoding: +\begin{center}\begin{tabular}{l} +\verb|prologues:=2;|\\ +\verb|fontmapfile "ec-public-lm.map";|\\ +\verb|beginfig(1);|\\ +\verb| draw "Helló, világ" infont "ec-lmr10";|\\ +\verb|endfig;| +\end{tabular}\end{center} + +Using \ttt{fontmapline}, you can specify font mapping information +inside the figure: +\begin{center}\begin{tabular}{l} +\verb|prologues:=2;|\\ +\verb|fontmapline "pplbo8r URWPalladioL-Bold "&ditto&|\\ +\verb| ".167 SlantFont"&ditto&" <8r.enc <uplb8a.pfb";|\\ +\verb|beginfig(1);|\\ +\verb| draw "Hello, world" infont "pplbo8r";|\\ +\verb|endfig;| +\end{tabular}\end{center} +This will attempt to reencode the PostScript font URWPalladioL-Bold +whose tfm file is pplbo8r.tfm. The encoding is found in the file +8r.enc, and will be included into the output file. + +If the same example was run with \ttt{prologues:=3}, MetaPost would +include a subset of the font that resides in uplb8a.pfb into the +output. In this case, the subset of the font is reorganized so that it +has the correct encoding internally, 8r.enc will not be embedded also. + +The argument to both commands has an optional flag character at the very +beginning. This optional flag has the same meaning as in pdf\TeX: +$$\begin{tabular}{|c|l|} \hline +\multicolumn1{|c|}{option}& \multicolumn1{c|}{meaning}\\ \hline + + & extend the font list, but ignore duplicates \\ + = & extend the font list, replacing duplicates \\ + $-$ & remove all matching fonts from the font list \\ +\hline +\end{tabular} +$$ +Without any option, the current list will be completely replaced. If there are no \ttt{fontmapfile} statements, MetaPost will attempt +to locate a default map file with a preference to read {\tt +mpost.map} and then {\tt pdftex.map}. If \ttt{prologues} is set to~1, +MetaPost attempts to read a file called {\tt psfonts.map}, regardless of any +{\tt fontmapfile} statement. Again, this is for backward compatibility only. \subsection{The {\tt infont} operator} \label{Sinfont} -Regardless of whether you use \TeX\ or troff, all the real work of adding -text to pictures is done by a MetaPost primitive operator called -{\tt infont}\index{infont?\texttt{infont}}. It is a -\tdescr{primary binop}\index{primary binop?\tdescr{primary binop}} that takes a -\tdescr{string secondary} as its -left argument and a \tdescr{string primary} as its right argument. The left -argument is text, and the right argument is a font name. -The result of the operation is a \tdescr{picture secondary} that can then be -transformed in various ways. One possibility is enlargement by a given factor -via the syntax\index{scaled?\texttt{scaled}} +Regardless of whether you use \TeX\ or troff, all the real work of +adding text to pictures is done by a MetaPost primitive operator called +{\tt infont}\index{infont?\texttt{infont}}. It is a \tdescr{primary +binop}\index{primary binop?\tdescr{primary binop}} that takes a +\tdescr{string secondary} as its left argument and a \tdescr{string +primary} as its right argument. The left argument is text, and the +right argument is a font name. The result of the operation is a +\tdescr{picture secondary} that can then be transformed in various ways. +One possibility is enlargement by a given factor via the +syntax\index{scaled?\texttt{scaled}} $$ \descr{picture secondary}\, \hbox{\tt scaled}\, \descr{numeric primary} $$ Thus {\tt label("text",z0)} is equivalent to $$ \hbox{\tt label("text" infont defaultfont scaled defaultscale, z0)} $$ @@ -1587,61 +1848,69 @@ If it is not convenient to use a string constant for the left argument of $$ {\tt char}\, \descr{numeric primary} $$ to select a character based on its numeric position in the font. Thus -$$ \hbox{\tt char(n+64) infont "Times-Roman"} $$ -is a picture containing character {\tt n+64} of the Times-Roman font. +$$ \hbox{\tt char(n+64) infont "ptmr8r"} $$ +is a picture containing character {\tt n+64} of the font \ttt{ptmr8r}, +which is a typical \TeX\ way to refer to Times-Roman. See p.\ +\pageref{fontname} for further discussion. \subsection{Measuring Text} \label{meas} -MetaPost makes readily available the physical dimensions\index{size} -of pictures generated by the {\tt infont} operator. There are -unary operators {\tt llcorner}\index{llcorner?\texttt{llcorner}}\label{Dcornop}, -{\tt lrcorner}\index{lrcorner?\texttt{lrcorner}}, {\tt urcorner}\index{urcorner?\texttt{urcorner}}, -{\tt ulcorner}\index{ulcorner?\texttt{ulcorner}}, and {\tt center}\index{center}\label{Dcenter} -that take a \tdescr{picture primary} and return the corners of its ``bounding -box'' as illustrated in Figure~\ref{bbox}. The {\tt center} operator also -accepts \tdescr{path primary} and \tdescr{pen primary} operands. -In MetaPost Version 0.30 and higher, {\tt llcorner}, {\tt lrcorner}, etc. -accept all three argument types as well. - -The argument type restrictions on the corner operators are not very important -because their main purpose is to allow {\tt label} and {\tt dotlabel} statements -to center their text properly. -The predefined macro\index{bbox?\texttt{bbox}}\label{Dbbox} +MetaPost makes readily available the physical dimensions\index{size} of +pictures generated by the {\tt infont} operator. There are unary +operators {\tt +llcorner}\index{llcorner?\texttt{llcorner}}\label{Dcornop}, {\tt +lrcorner}\index{lrcorner?\texttt{lrcorner}}, {\tt +urcorner}\index{urcorner?\texttt{urcorner}}, {\tt +ulcorner}\index{ulcorner?\texttt{ulcorner}}, and {\tt +center}\index{center}\label{Dcenter} that take a \tdescr{picture +primary} and return the corners of its ``bounding box'' as illustrated +in Figure~\ref{bbox}. The {\tt center} operator also accepts +\tdescr{path primary} and \tdescr{pen primary} operands. In MetaPost +Version 0.30 and higher, {\tt llcorner}, {\tt lrcorner}, etc. accept +all three argument types as well. + +The argument type restrictions on the corner operators are not very +important because their main purpose is to allow {\tt label} and {\tt +dotlabel} statements to center their text properly. The predefined +macro\index{bbox?\texttt{bbox}}\label{Dbbox} $$ {\tt bbox}\, \descr{picture primary} $$ finds a rectangular path that represents the bounding box of a given picture. If {\tt p} is a picture, {\tt bbox p} equivalent to $$ \hbox{\tt (llcorner p--lrcorner p--urcorner p--ulcorner p--cycle)} $$ -except that it allows for a small amount of extra space around {\tt p} as specified -by the internal variable\index{internal variables}\index{variables!internal} -{\tt bboxmargin}\index{bboxmargin?\texttt{bboxmargin}}\label{Dbbmargin}. +except that it allows for a small amount of extra space around {\tt p} +as specified by the internal variable\index{internal +variables}\index{variables!internal} {\tt +bboxmargin}\index{bboxmargin?\texttt{bboxmargin}}\label{Dbbmargin}. \begin{figure}[htp] -$$ \epsfbox{manfig.20} $$ +$$ \includegraphics{manfig-20} $$ \caption{A bounding box and its corner points.} \label{bbox} \end{figure} -Note that MetaPost computes the bounding box of a {\tt btex}\index{btex?\texttt{btex}} -\ldots\ {\tt etex}\index{etex?\texttt{etex}} picture just the way \TeX\index{TeX?\TeX} does. -This is quite natural, but it has certain implications in view of the fact that -\TeX\ has features like {\tt\string\strut}\index{strut?{\tt\string\strut}} and -{\tt\string\rlap}\index{rlap?{\tt\string\rlap}} that allow \TeX\ users to lie about the -dimensions of a box. - -When \TeX\ commands that lie about the dimensions of a box are translated in to -low-level MetaPost code, a {\tt setbounds}\index{setbounds?\texttt{setbounds}}\label{Dsetbnd} -statement does the lying:\index{picture variable?\tdescr{picture variable}} +Note that MetaPost computes the bounding box of a {\tt +btex}\index{btex?\texttt{btex}} \ldots\ {\tt +etex}\index{etex?\texttt{etex}} picture just the way +\TeX\index{TeX?\TeX} does. This is quite natural, but it has certain +implications in view of the fact that \TeX\ has features like +{\tt\string\strut}\index{strut?{\tt\string\strut}} and +{\tt\string\rlap}\index{rlap?{\tt\string\rlap}} that allow \TeX\ users +to lie about the dimensions of a box. + +When \TeX\ commands that lie about the dimensions of a box are +translated in to low-level MetaPost code, a {\tt +setbounds}\index{setbounds?\texttt{setbounds}}\label{Dsetbnd} statement +does the lying:\index{picture variable?\tdescr{picture variable}} $$ {\tt setbounds}\, \descr{picture variable}\, {\tt to}\, \descr{path expression} $$ -makes the \tdescr{picture variable} behave as if its bounding box were the same -as the given path. To get the true bounding box of such a picture, assign a -positive value to the -internal variable\index{internal variables}\index{variables!internal} -{\tt truecorners}\index{truecorners?\texttt{truecorners}}\label{Dtruecorn}:\footnote{The -{\tt setbounds} and -{\tt truecorners} features are only found in MetaPost version 0.30 and higher.} -i.e., +makes the \tdescr{picture variable} behave as if its bounding box were +the same as the given path. To get the true bounding box of such a +picture, assign a positive value to the internal variable\index{internal +variables}\index{variables!internal} {\tt +truecorners}\index{truecorners?\texttt{truecorners}}\label{Dtruecorn}:\footnote{The +{\tt setbounds} and {\tt truecorners} features are only found in +MetaPost version 0.30 and higher.} i.e., $$ \hbox{\verb|show urcorner btex $\bullet$\rlap{ A} etex|} $$ produces ``\verb|>> (4.9813,6.8078)|'' while $$ \hbox{\verb|truecorners:=1; show urcorner btex $\bullet$\rlap{ A} etex|} $$ @@ -1651,20 +1920,19 @@ produces ``\verb|>> (15.7742,6.8078)|.'' \section{Advanced Graphics} \label{adv.gr} -All the examples in the previous sections have been simple line drawings with -labels added. This section describes shading and tools for generating -not-so-simple line drawings. -Shading is done with the {\tt fill}\index{fill?\texttt{fill}}\label{Dfill} statement. -In its simplest -form, the {\tt fill} statement requires a \tdescr{path expression} that gives -the boundary of the region to be filled. In the syntax +All the examples in the previous sections have been simple line drawings +with labels added. This section describes shading and tools for +generating not-so-simple line drawings. Shading is done with the {\tt +fill}\index{fill?\texttt{fill}}\label{Dfill} statement. In its simplest +form, the {\tt fill} statement requires a \tdescr{path expression} that +gives the boundary of the region to be filled. In the syntax $$ {\tt fill}\, \descr{path expression} $$ -the argument should be a cyclic path, i.e., a path that describes a closed curve -via the {\tt ..cycle} or {\tt --cycle} notation. For example, the {\tt fill} -statement in Figure~\ref{fig20} builds a closed path by extending the roughly -semicircular path~{\tt p}. -This path has a counter-clockwise orientation, but that does not matter because -the {\tt fill} statement uses PostScript's\index{PostScript} non-zero +the argument should be a cyclic path, i.e., a path that describes a +closed curve via the {\tt ..cycle} or {\tt --cycle} notation. For +example, the {\tt fill} statement in Figure~\ref{fig20} builds a closed +path by extending the roughly semicircular path~{\tt p}. This path has +a counter-clockwise orientation, but that does not matter because the +{\tt fill} statement uses PostScript's\index{PostScript} non-zero winding\index{winding number} number rule~\cite{ad:red}. \begin{figure}[htp] @@ -1676,7 +1944,7 @@ fill p{up}..(0,0){-1,-2}..{up}cycle; draw p..(0,1cm)..cycle; endfig; \end{verbatim} -\qquad \mathcenter{\epsfbox{manfig.21}} +\qquad \mathcenter{\includegraphics{manfig-21}} $$ \caption{MetaPost code and the corresponding output.} \label{fig20} @@ -1687,18 +1955,67 @@ $$ {\tt fill}\, \descr{path expression}\, {\tt withcolor}\, \descr{color expression} $$ specifies a shade of gray or (if you have a color printer) some -rainbow color. - -Figure~\ref{fig21} illustrates several applications of the fill command to fill -areas with shades of gray. The paths involved are intersecting circles {\tt a} -and {\tt b} and a path {\tt ab} that bounds the region inside both circles. -Circles {\tt a} and {\tt b} are derived from a predefined path -{\tt fullcircle}\index{fullcircle?\texttt{fullcircle}}\label{Dfcirc} -that approximates a circle of unit diameter centered on the origin. There is -also a predefined path {\tt halfcircle}\index{halfcircle?\texttt{halfcircle}}\label{Dhcirc} -that is the part -of {\tt fullcircle} above the $x$ axis. Path~{\tt ab} is the initialized -using a predefined macro {\tt buildcycle} that will be discussed shortly. +rainbow color. The $\descr{color expression}$ can have five possible +values, mapping to four possible color models: + +$$ +\begin{tabular}{|l|l|} +Actual input & Remapped meaning\\ +{\tt withcolor} $\descr{rgbcolor} c$ & withrgbcolor $c$\\ +{\tt withcolor} $\descr{cmykcolor} c$ & withcmykcolor $c$\\ +{\tt withcolor} $\descr{numeric} c$ & withgreyscale $c$\\ +{\tt withcolor} $\descr{false}$ & withoutcolor \\ +{\tt withcolor} $\descr{true}$ & $\descr{current default color model}$\\ +\end{tabular} +$$ + +For the specific color models, there are also: +$$ {\tt fill}\, \descr{path expression}\, + {\tt withrgbcolor}\, \descr{rgbcolor expression} +$$ +$$ {\tt fill}\, \descr{path expression}\, + {\tt withcmykcolor}\, \descr{cmykcolor expression} +$$ +$$ {\tt fill}\, \descr{path expression}\, + {\tt withgreyscale}\, \descr{numeric} +$$ +$$ {\tt fill}\, \descr{path expression}\, + {\tt withoutcolor} +$$ + +An image object cannot have more then one color model, the last +\ttt{withcolor}, \ttt{withrgbcolor}, \ttt{withcmykcolor}, +\ttt{withgreyscale} or \ttt{withoutcolor} specification sets the color +model for any particular object. + +The model \ttt{withoutcolor} needs a bit more explanation: selecting +this model means that MetaPost will not write a color selection +statement to the PostScript output file for this object. + +The `current default' color model can be set up using the internal +parameter \ttindex{defaultcolormodel}. Valid values are: +$$ +\begin{tabular}{|l|l|} +1 & no model\\ +3 & greyscale\\ +5 & rgb (default)\\ +7 & cmyk\\ +\end{tabular} +$$ + + +Figure~\ref{fig21} illustrates several applications of the fill command +to fill areas with shades of gray. The paths involved are intersecting +circles {\tt a} and {\tt b} and a path {\tt ab} that bounds the region +inside both circles. Circles {\tt a} and {\tt b} are derived from a +predefined path {\tt +fullcircle}\index{fullcircle?\texttt{fullcircle}}\label{Dfcirc} that +approximates a circle of unit diameter centered on the origin. There is +also a predefined path {\tt +halfcircle}\index{halfcircle?\texttt{halfcircle}}\label{Dhcirc} that is +the part of {\tt fullcircle} above the $x$ axis. Path~{\tt ab} is then +initialized using a predefined macro {\tt buildcycle} that will be +discussed shortly. \begin{figure}[htp] $$ \begin{verbatim} @@ -1722,38 +2039,40 @@ label.lft(btex $U$ etex, (-1cm,.5cm)); draw bbox currentpicture; endfig; \end{verbatim} -\qquad \mathcenter{\epsfbox{manfig.22}} +\qquad \mathcenter{\includegraphics{manfig-22}} $$ \caption{MetaPost code and the corresponding output.} \index{fullcircle?\texttt{fullcircle}}\index{halfcircle?\texttt{halfcircle}}\index{buildcycle?\texttt{buildcycle}} \label{fig21} \end{figure} -Filling circle {\tt a} with the light gray color {\tt .7white} and then doing the -same with circle {\tt b} doubly fills the region where the disks overlap. The -rule is that each {\tt fill} statement assigns the given color to all points in -the region covered, wiping out whatever was there previously including lines and -text as well as filled regions. Thus it is important to give {\tt fill} commands -in the right order. -In the above example, the overlap region gets the same color twice, -leaving it light gray after the first two {\tt fill} statements. The third fill +Filling circle {\tt a} with the light gray color {\tt .7white} and then +doing the same with circle {\tt b} doubly fills the region where the +disks overlap. The rule is that each {\tt fill} statement assigns the +given color to all points in the region covered, wiping out whatever was +there previously including lines and text as well as filled regions. +Thus it is important to give {\tt fill} commands in the right order. In +the above example, the overlap region gets the same color twice, leaving +it light gray after the first two {\tt fill} statements. The third fill statement assigns the darker color {\tt .4white} to the overlap region. -At this point the circles and the overlap region have their final colors but -there are no cutouts for the labels. The cutouts are achieved by the -{\tt unfill}\index{unfill?\texttt{unfill}}\label{Dunfill} -statements that effectively erase\index{erasing} -the regions bounded by {\tt bbox pa}\index{bbox?\texttt{bbox}} and -{\tt bbox pb}. More precisely, {\tt unfill} is shorthand for filling -{\tt withcolor background}, where {\tt background} is normally equal to {\tt white} -as is appropriate for printing on white paper. If necessary, you can assign a new -color value to {\tt background}\index{background?\texttt{background}}\label{Dbground}. +At this point the circles and the overlap region have their final colors +but there are no cutouts for the labels. The cutouts are achieved by +the {\tt unfill}\index{unfill?\texttt{unfill}}\label{Dunfill} statements +that effectively erase\index{erasing} the regions bounded by {\tt bbox +pa}\index{bbox?\texttt{bbox}} and {\tt bbox pb}. More precisely, {\tt +unfill} is shorthand for filling {\tt withcolor background}, where {\tt +background} is normally equal to {\tt white} as is appropriate for +printing on white paper. If necessary, you can assign a new color value +to {\tt +background}\index{background?\texttt{background}}\label{Dbground}. The labels need to be stored in pictures {\tt pa} and {\tt pb} to allow -for measuring their bounding box before actually drawing them. The macro -{\tt thelabel}\index{thelabel?\texttt{thelabel}} creates such -pictures and shifts them into position so that they are ready to draw. Using the -resulting pictures in {\tt draw} statements of the form\index{draw?\texttt{draw}} +for measuring their bounding box before actually drawing them. The +macro {\tt thelabel}\index{thelabel?\texttt{thelabel}} creates such +pictures and shifts them into position so that they are ready to draw. +Using the resulting pictures in {\tt draw} statements of the +form\index{draw?\texttt{draw}} $$ {\tt draw}\, \descr{picture expression} $$ adds them to {\tt currentpicture}\index{currentpicture?\texttt{currentpicture}} so that they overwrite a portion of what has @@ -1763,28 +2082,29 @@ already been drawn. In Figure~\ref{fig21} just the white rectangles produced by \subsection{Building Cycles} \label{buildcy} -The {\tt buildcycle}\index{buildcycle?\texttt{buildcycle}} command constructs paths for use with -the {\tt fill} or {\tt unfill} macros. When given two or more paths such as -{\tt aa} and {\tt b}, -the {\tt buildcycle} macro tries to piece them together so as to form a cyclic -path. In this case path {\tt aa} is a semicircle that starts just to the right -of the intersection with path {\tt b}, then passes through {\tt b} and ends just -outside the circle on the left as shown in Figure~\ref{fig22}a. - -Figure~\ref{fig22}b shows how {\tt buildcycle} forms a closed -cycle from pieces of paths {\tt aa} and {\tt b}. -The {\tt buildcycle} macro detects the two intersections\index{intersections} -labeled 1 and 2 in -Figure~\ref{fig22}b. Then it constructs the cyclic path shown in bold in the -figure by going forward along path {\tt aa} from intersection~1 to -intersection~2 and then forward around the counter-clockwise path {\tt b} back to -intersection~1. It turns out that {\tt buildcycle(a,b)} would have produced the -same result, but the reasoning behind this is a little confusing. +The {\tt buildcycle}\index{buildcycle?\texttt{buildcycle}} command +constructs paths for use with the {\tt fill} or {\tt unfill} macros. +When given two or more paths such as {\tt aa} and {\tt b}, the {\tt +buildcycle} macro tries to piece them together so as to form a cyclic +path. In this case path {\tt aa} is a semicircle that starts just to +the right of the intersection with path {\tt b}, then passes through +{\tt b} and ends just outside the circle on the left as shown in +Figure~\ref{fig22}a. + +Figure~\ref{fig22}b shows how {\tt buildcycle} forms a closed cycle from +the pieces of paths {\tt aa} and {\tt b}. The {\tt buildcycle} macro +detects the two intersections\index{intersections} labeled 1 and 2 in +Figure~\ref{fig22}b. Then it constructs the cyclic path shown in bold +in the figure by going forward along path {\tt aa} from intersection~1 +to intersection~2 and then forward around the counter-clockwise path +{\tt b} back to intersection~1. It turns out that {\tt buildcycle(a,b)} +would have produced the same result, but the reasoning behind this is a +little confusing. \begin{figure}[htp] -$$ {\epsfbox{manfig.123} \atop (a)} - \qquad {\epsfbox{manfig.223} \atop (b)} +$$ {\includegraphics{manfig-123} \atop (a)} + \qquad {\includegraphics{manfig-223} \atop (b)} $$ \caption[A demonstration of cycle building] {(a)~The semicircular path~{\tt aa} @@ -1794,18 +2114,20 @@ $$ \end{figure} It is a easier to use the {\tt buildcycle} macro in situations like -Figure~\ref{fig23} where there are more than two path arguments and each pair -of consecutive paths has a unique intersection. For instance, the line~{\tt q0.5} -and the curve~{\tt p2} intersect only at point~$P$; and the curve {\tt p2} and the -line~{\tt q1.5} intersect only at point~$Q$. In fact, each of the points $P$, -$Q$, $R$, $S$ is a unique intersection, and the result of\index{buildcycle?\texttt{buildcycle}} +Figure~\ref{fig23} where there are more than two path arguments and each +pair of consecutive paths has a unique intersection. For instance, the +line~{\tt q0.5} and the curve~{\tt p2} intersect only at point~$P$; and +the curve {\tt p2} and the line~{\tt q1.5} intersect only at point~$Q$. +In fact, each of the points $P$, $Q$, $R$, $S$ is a unique intersection, +and the result of\index{buildcycle?\texttt{buildcycle}} $$ \hbox{\tt buildcycle(q0.5, p2, q1.5, p4)} $$ -takes {\tt q0.5} from $S$ to~$P$, then {\tt p2} from $P$ to~$Q$, then {\tt q1.5} -from $Q$ to~$R$, and finally {\tt p4} from $R$ back to~$S$. An examination of the -MetaPost code for Figure~\ref{fig23} reveals that you have to go backwards along -{\tt p2} in order to get from $P$ to~$Q$. This works perfectly well as long as -the intersection\index{intersection} points are uniquely defined but it can cause -unexpected results when pairs of paths intersect more than once. +takes {\tt q0.5} from $S$ to~$P$, then {\tt p2} from $P$ to~$Q$, then +{\tt q1.5} from $Q$ to~$R$, and finally {\tt p4} from $R$ back to~$S$. +An examination of the MetaPost code for Figure~\ref{fig23} reveals that +you have to go backwards along {\tt p2} in order to get from $P$ to~$Q$. +This works perfectly well as long as the +intersection\index{intersection} points are uniquely defined but it can +cause unexpected results when pairs of paths intersect more than once. \begin{figure}[htp] $$ \begin{verbatim} @@ -1829,7 +2151,7 @@ dotlabel.lft(btex $R$ etex, p4 intersectionpoint q1.5); dotlabel.bot(btex $S$ etex, p4 intersectionpoint q0.5); endfig; \end{verbatim} -\atop \mathcenter{\epsfbox{manfig.24}} +\atop \mathcenter{\includegraphics{manfig-24}} $$ \caption{MetaPost code and the corresponding output.} \label{fig23} @@ -1839,132 +2161,143 @@ The general rule for the {\tt buildcycle} macro is that $$ \hbox{\tt buildcycle(}p_1\hbox{\tt,}\, p_2\hbox{\tt,}\, p_3\hbox{\tt,}\, \ldots \hbox{\tt,} p_k \hbox{\tt )} $$ -chooses the intersection between each $p_i$ and $p_{i+1}$ to be as late as possible -on $p_i$ and as early as possible on $p_{i+1}$. There is no -simple rule for resolving conflicts between these two goals, so you should avoid -cases where one intersection point occurs later on $p_i$ and another -intersection\index{intersection} point occurs earlier on $p_{i+1}$. - -The preference for intersections as late as possible -on $p_i$ and as early as possible on $p_{i+1}$ leads to ambiguity resolution in -favor of forward-going subpaths. For cyclic paths such as path~{\tt b} in -Figure~\ref{fig22} ``early'' and ``late'' are relative to a start/finish point -which is where you get back to when you say ``{\tt ..cycle}''. -For the path~{\tt b}, this turns out to be the rightmost point on the circle. +chooses the intersection between each $p_i$ and $p_{i+1}$ to be as late +as possible on $p_i$ and as early as possible on $p_{i+1}$. There is no +simple rule for resolving conflicts between these two goals, so you +should avoid cases where one intersection point occurs later on $p_i$ +and another intersection\index{intersection} point occurs earlier on +$p_{i+1}$. + +The preference for intersections as late as possible on $p_i$ and as +early as possible on $p_{i+1}$ leads to ambiguity resolution in favor of +forward-going subpaths. For cyclic paths such as path~{\tt b} in +Figure~\ref{fig22} ``early'' and ``late'' are relative to a start/finish +point which is where you get back to when you say ``{\tt ..cycle}''. +For the path~{\tt b}, this turns out to be the rightmost point on the +circle. A more direct way to deal with path intersections is via the \tdescr{secondary binop}\index{secondary binop?\tdescr{secondary binop}} -{\tt intersection\-point}\index{intersectionpoint?\texttt{intersectionpoint}}\label{Disecpt} +{\tt +intersection\-point}\index{intersectionpoint?\texttt{intersectionpoint}}\label{Disecpt} that finds the points $P$, $Q$, $R$, and~$S$ in Figure~\ref{fig23}. -This macro finds a point where two given -paths intersect. If there is more than one intersection point, it just chooses -one; if there is no intersection, the macro generates an error message. +This macro finds a point where two given paths intersect. If there is +more than one intersection point, it just chooses one; if there is no +intersection, the macro generates an error message. \subsection{Dealing with Paths Parametrically} -The {\tt intersectionpoint}\index{intersectionpoint?\texttt{intersectionpoint}} macro is based on a -primitive operation called -{\tt intersectiontimes}\index{intersectiontimes?\texttt{intersectiontimes}}\label{Disectt}. -This \tdescr{secondary binop} is one of several -operations that deal with paths parametrically. It locates an intersection -between two paths by giving the ``time'' parameter on each path. This refers to -the parameterization scheme from Section~\ref{curves} that described paths as -piecewise cubic curves $\bigl(X(t),Y(t)\bigr)$ where $t$ ranges from zero to the -number of curve segments. In other words, when a path is specified as passing -through a sequence of points, where $t=0$ at the first point, -then $t=1$ at the next, and $t=2$ at the next, etc. The result of +The {\tt +intersectionpoint}\index{intersectionpoint?\texttt{intersectionpoint}} +macro is based on a primitive operation called {\tt +intersectiontimes}\index{intersectiontimes?\texttt{intersectiontimes}}\label{Disectt}. +This \tdescr{secondary binop} is one of several operations that deal +with paths parametrically. It locates an intersection between two paths +by giving the ``time'' parameter on each path. This refers to the +parameterization scheme from Section~\ref{curves} that described paths +as piecewise cubic curves $\bigl(X(t),Y(t)\bigr)$ where $t$ ranges from +zero to the number of curve segments. In other words, when a path is +specified as passing through a sequence of points, where $t=0$ at the +first point, then $t=1$ at the next, and $t=2$ at the next, etc. The +result of $$ \hbox{\tt a intersectiontimes b} $$ is $(-1,-1)$ if there is no intersection; otherwise you get a pair $(t_a,t_b)$, where $t_a$ is a time on path {\tt a} when it intersects path~{\tt b}, and $t_b$ is the corresponding time on path~{\tt b}. -For example, suppose path~{\tt a} is denoted by the thin line in Figure~\ref{fig24} -and path~{\tt b} is denoted by the thicker line. If the labels indicate time -values on the paths, the pair of time values computed by +For example, suppose path~{\tt a} is denoted by the thin line in +Figure~\ref{fig24} and path~{\tt b} is denoted by the thicker line. If +the labels indicate time values on the paths, the pair of time values +computed by $$ \hbox{\tt a intersectiontimes b} $$ must be one of $$ (0.25,1.77),\ (0.75,1.40), {\rm or}\ (2.58,0.24), $$ -depending on which of the three intersection points is chosen by the MetaPost -interpreter. The exact rules for choosing among multiple intersection points -are a little complicated, but it turns out that you get the time values -$(0.25,1.77)$ in this example. Smaller time values are preferred over larger -ones so that $(t_a,t_b)$ is preferred to $(t'_a,t'_b)$ whenever $t'_a<t_a$ and -$t_b<t'_b$. When no single alternative minimizes both the $t_a$ and $t_b$ -components the $t_a$ component tends to get priority, but the rules get more -complicated when there are no integers between $t_a$ -and $t'_a$\index{intersection}. -(For more details, see {\it The \MF book}.\cite[Chapter 14]{kn:c}) +depending on which of the three intersection points is chosen by the +MetaPost interpreter. The exact rules for choosing among multiple +intersection points are a little complicated, but it turns out that you +get the time values $(0.25,1.77)$ in this example. Smaller time values +are preferred over larger ones so that $(t_a,t_b)$ is preferred to +$(t'_a,t'_b)$ whenever $t_a<t'_a$ and $t_b<t'_b$. When no single +alternative minimizes both the $t_a$ and $t_b$ components the $t_a$ +component tends to get priority, but the rules get more complicated when +there are no integers between $t_a$ and $t'_a$\index{intersection}. +(For more details, see {\sl The \MF book} \cite[Chapter 14]{kn:c}). \begin{figure}[htp] -$$ \epsfbox{manfig.25} $$ +$$ \includegraphics{manfig-25} $$ \caption{Two intersecting paths with time values marked on each path.} \label{fig24} \end{figure} -The {\tt intersectiontimes} operator is more flexible than {\tt intersectionpoint} -because there are a number of things that can be done with time values on a path. -One of the most important is just to ask ``where is path {\tt p} at -time {\tt t}?'' The construction\index{point of?\texttt{point of}}\label{Dpntof} +The {\tt intersectiontimes} operator is more flexible than {\tt +intersectionpoint} because there are a number of things that can be done +with time values on a path. One of the most important is just to ask +``where is path {\tt p} at time {\tt t}?'' The construction\index{point +of?\texttt{point of}}\label{Dpntof} $$ {\tt point}\, \descr{numeric expression}\, {\tt of}\, \descr{path primary} $$ -answers this question. If the \tdescr{numeric expression} is less than zero or -greater than the time value assigned to the last point on the path, the -{\tt point of} construction normally yields an endpoint of the path. Hence, it -is common to use the predefined constant -{\tt infinity}\index{infinity?\texttt{infinity}}\label{Dinf} -(equal to 4095.99998) as the -\tdescr{numeric expression} in a {\tt point of} construction when dealing with -the end of a path. - -Such ``infinite'' time values do not work for a cyclic path, since -time values outside of the normal range can be handled by modular arithmetic in -that case; i.e., a cyclic path~{\tt p} through points $z_0$, $z_1$, $z_2$, -\ldots, $z_{n-1}$ has the normal parameter range $0\le t<n$, but +answers this question. If the \tdescr{numeric expression} is less than +zero or greater than the time value assigned to the last point on the +path, the {\tt point of} construction normally yields an endpoint of the +path. Hence, it is common to use the predefined constant {\tt +infinity}\index{infinity?\texttt{infinity}}\label{Dinf} (equal to +4095.99998) as the \tdescr{numeric expression} in a {\tt point of} +construction when dealing with the end of a path. + +Such ``infinite'' time values do not work for a cyclic path, since time +values outside of the normal range can be handled by modular arithmetic +in that case; i.e., a cyclic path~{\tt p} through points $z_0$, $z_1$, +$z_2$, \ldots, $z_{n-1}$ has the normal parameter range $0\le t<n$, but $$ \hbox{\tt point t of p} $$ -can be computed for any~$t$ by first reducing $t$ modulo~$n$. If the modulus~$n$ -is not readily available,\index{length?\texttt{length}}\label{Dlength} +can be computed for any~$t$ by first reducing $t$ modulo~$n$. If the +modulus~$n$ is not readily +available,\index{length?\texttt{length}}\label{Dlength} $$ {\tt length}\, \descr{path primary} $$ -gives the integer value of the upper limit of the normal time parameter range -for the specified path. +gives the integer value of the upper limit of the normal time parameter +range for the specified path. -MetaPost uses the same correspondence between time values and points on a path to -evaluate the {\tt subpath}\index{subpath?\texttt{subpath}}\label{Dsubpth} operator. -The syntax for this operator is +MetaPost uses the same correspondence between time values and points on +a path to evaluate the {\tt +subpath}\index{subpath?\texttt{subpath}}\label{Dsubpth} operator. The +syntax for this operator is $$ {\tt subpath}\, \descr{pair expression}\, {\tt of}\, \descr{path primary} $$ If the value of the \tdescr{pair expression} is $(t_1,t_2)$ and the \tdescr{path primary} is $p$, the result is a path that follows $p$ from -{\tt point $t_1$ of $p$} to {\tt point $t_2$ of $p$}. If $t_2<t_1$, the subpath -runs backwards along~$p$. +{\tt point $t_1$ of $p$} to {\tt point $t_2$ of $p$}. If $t_2<t_1$, the +subpath runs backwards along~$p$. An important operation based on the {\tt subpath} operator is the \tdescr{tertiary binop}\index{tertiary binop?\tdescr{tertiary binop}} -{\tt cutbefore}\index{cutbefore?\texttt{cutbefore}}\label{Dcutb}. For intersecting -paths $p_1$ and $p_2$, +{\tt cutbefore}\index{cutbefore?\texttt{cutbefore}}\label{Dcutb}. For +intersecting paths $p_1$ and $p_2$, $$ p_1\ {\tt cutbefore}\ p_2 $$ is equivalent to $$ \hbox{\tt subpath (xpart($p_1$ intersectiontimes $p_2$), length $p_1$) of $p_1$} $$ -except that it also sets the path variable -{\tt cuttings}\index{cuttings?\texttt{cuttings}}\label{Dcuttings} to -the portion of $p_1$ that gets cut off. In other words, {\tt cutbefore} returns -its first argument with the part before the intersection cut off. With multiple -intersections, it tries to cut off as little as possible. If the paths do not -intersect, {\tt cutbefore} returns its first argument. - -There is also an analogous \tdescr{tertiary binop}\index{tertiary binop?\tdescr{tertiary binop}} -called {\tt cutafter}\index{cutafter?\texttt{cutafter}}\label{Dcuta} that works by applying -{\tt cutbefore} with -time reversed along its first argument. Thus +except that it also sets the path variable {\tt +cuttings}\index{cuttings?\texttt{cuttings}}\label{Dcuttings} to the +portion of $p_1$ that gets cut off. In other words, {\tt cutbefore} +returns its first argument with the part before the intersection cut +off. With multiple intersections, it tries to cut off as little as +possible. If the paths do not intersect, {\tt cutbefore} returns its +first argument. + +There is also an analogous \tdescr{tertiary binop}\index{tertiary +binop?\tdescr{tertiary binop}} called {\tt +cutafter}\index{cutafter?\texttt{cutafter}}\label{Dcuta} that works by +applying {\tt cutbefore} with time reversed along its first argument. +Thus $$ p_1\ {\tt cutafter}\ p_2 $$ tries to cut off the part of $p_1$ after its last intersection with $p_2$. Another operator\index{direction of?\texttt{direction of}}\label{Ddirof} $$ {\tt direction}\, \descr{numeric expression}\, {\tt of}\, \descr{path primary} $$ -finds a vector in the direction of the \tdescr{path primary}. This is defined -for any time value analogously to the {\tt point of} construction. The resulting -direction vector has the correct orientation and a somewhat arbitrary magnitude. -Combining {\tt point of} and {\tt direction of} constructions yields the equation -for a tangent line as illustrated in Figure~\ref{fig25}. +finds a vector in the direction of the \tdescr{path primary}. This is +defined for any time value analogously to the {\tt point of} +construction. The resulting direction vector has the correct +orientation and a somewhat arbitrary magnitude. Combining {\tt point +of} and {\tt direction of} constructions yields the equation for a +tangent line as illustrated in Figure~\ref{fig25}. \begin{figure}[htp] $$ \begin{verbatim} @@ -1992,26 +2325,26 @@ pickup pencircle scaled 1pt; draw fun; endfig; \end{verbatim} -\atop \epsfbox{manfig.26} +\atop \includegraphics{manfig-26} $$ \caption{MetaPost code and the resulting figure} \label{fig25} \end{figure} -If you know a slope and you want to find a point on a curve where the tangent -line has that slope, -the {\tt directiontime}\index{directiontime of?\texttt{directiontime of}}\label{Ddtimof} -operator inverts the {\tt direction -of} operation. Given a direction vector and a path, +If you know a slope and you want to find a point on a curve where the +tangent line has that slope, the {\tt directiontime}\index{directiontime +of?\texttt{directiontime of}}\label{Ddtimof} operator inverts the {\tt +direction of} operation. Given a direction vector and a path, $$ {\tt directiontime}\, \descr{pair expression}\, {\tt of}\, \descr{path primary} $$ -returns a numeric value that gives the first time~$t$ when the path has the -indicated direction. (If there is no such time, the result is $-1$). -For example, if {\tt a} is the path drawn as a thin curve in Figure~\ref{fig24}, -{\tt directiontime (1,1) of a} returns 0.2084. +returns a numeric value that gives the first time~$t$ when the path has +the indicated direction. (If there is no such time, the result is +$-1$). For example, if {\tt a} is the path drawn as a thin curve in +Figure~\ref{fig24}, {\tt directiontime (1,1) of a} returns 0.2084. -There is also an predefined macro \index{directionpoint of?\texttt{directionpoint of}}\label{Ddpntof} +There is also an predefined macro \index{directionpoint +of?\texttt{directionpoint of}}\label{Ddpntof} $$ {\tt directionpoint}\, \descr{pair expression}\, {\tt of}\, \descr{path primary} $$ @@ -2019,13 +2352,13 @@ that finds the first point on a path where a given direction is achieved. The {\tt directionpoint} macro produces an error message if the direction does not occur on the path. -Operators {\tt arclength}\index{arclength?\texttt{arclength}}\label{Darclng} and -{\tt arctime of}\index{arctime of?\texttt{arctime of}}\label{Darctim} relate the ``time'' -on a path is related to the more familiar concept of -arc length.\index{arc length}\footnote{The -{\tt arclength} and {\tt arctime} operators are only found in MetaPost -version 0.50 and higher.} -The expression +Operators {\tt +arclength}\index{arclength?\texttt{arclength}}\label{Darclng} and {\tt +arctime of}\index{arctime of?\texttt{arctime of}}\label{Darctim} relate +the ``time'' on a path to the more familiar concept of arc +length.\index{arc length}\footnote{The {\tt arclength} and {\tt arctime} +operators are only found in MetaPost version 0.50 and higher.} The +expression $$ \hbox{{\tt arclength} \tdescr{path primary}} $$ gives the arc length of a path. If {\tt p} is a path and {\tt a} is a number between 0 and {\tt arclength p}, @@ -2039,14 +2372,16 @@ $$ \hbox{\tt arclength subpath (0,t) of p} = {\tt a}. $$ Note how path {\tt fun} in Figure~\ref{fig25} is first constructed as $$ \hbox{\verb|(0,-.1)..(1,.05){right}..(1.9,.02){right}..{curl .1}(3.2,.2)|} $$ -and then the {\tt yscaled}\index{yscaled?\texttt{yscaled}} and {\tt scaled}\index{scaled?\texttt{scaled}} -operators are used to adjust the -shape and size of the path. As the name suggests, an expression involving -``{\tt yscaled 10}'' multiplies $y$ coordinates by ten so that every point $(x,y)$ -on the original path corresponds to a point $(x,10y)$ on the transformed path. +and then the {\tt yscaled}\index{yscaled?\texttt{yscaled}} and {\tt +scaled}\index{scaled?\texttt{scaled}} operators are used to adjust the +shape and size of the path. As the name suggests, an expression +involving ``{\tt yscaled 10}'' multiplies $y$ coordinates by ten so that +every point $(x,y)$ on the original path corresponds to a point +$(x,10y)$ on the transformed path. Including {\tt scaled} and {\tt yscaled}, there are seven transformation -operators that take a numeric or pair argument:\index{shifted?\texttt{shifted}}% +operators that take a numeric or pair +argument:\index{shifted?\texttt{shifted}}% \index{rotated?\texttt{rotated}}\index{slanted?\texttt{slanted}}\index{scaled?\texttt{scaled}}\index{xscaled?\texttt{xscaled}}% \index{yscaled?\texttt{yscaled}}\index{zscaled?\texttt{zscaled}}\label{Dtranop} \begin{eqnarray*} @@ -2059,17 +2394,20 @@ operators that take a numeric or pair argument:\index{shifted?\texttt{shifted}}% (x,y){\tt\ yscaled\ }a &=& (x,\, ay); \\ (x,y){\tt\ zscaled\ }(a,b) &=& (ax-by,\, bx+ay). \end{eqnarray*} -Most of these operations are self-explanatory except for {\tt zscaled} which can -be thought of as multiplication of complex numbers. The effect of {\tt zscaled} -$(a,b)$ is to rotate and scale so as to map $(1,0)$ into $(a,b)$. The effect of -{\tt rotated}~$\theta$ is rotate $\theta$ degrees counter-clockwise. - -Any combination of shifting, rotating, slanting, etc.\ is an affine transformation, -the net effect of which is to transform any pair $(x,y)$ into +Most of these operations are self-explanatory except for {\tt zscaled} +which can be thought of as multiplication of complex numbers. The +effect of {\tt zscaled} $(a,b)$ is to rotate and scale so as to map +$(1,0)$ into $(a,b)$. The effect of {\tt rotated}~$\theta$ is rotate +$\theta$ degrees counter-clockwise. + +Any combination of shifting, rotating, slanting, etc.\ is an affine +transformation, the net effect of which is to transform any pair $(x,y)$ +into $$ (t_x+t_{xx}x+t_{xy}y,\, t_y+t_{yx}x+t_{yy}y), $$ -for some sextuple $(t_x,t_y,t_{xx},t_{xy},t_{yx},t_{yy})$. This information can -be stored in a variable of type transform so that -{\tt transformed T}\index{transformed?\texttt{transformed}}\label{Dtrfrmd} might be equivalent to +for some sextuple $(t_x,t_y,t_{xx},t_{xy},t_{yx},t_{yy})$. This +information can be stored in a variable of type transform so that {\tt +transformed T}\index{transformed?\texttt{transformed}}\label{Dtrfrmd} +might be equivalent to $$ \hbox{\tt xscaled -1 rotated 90 shifted (1,1)} $$ if {\tt T} is an appropriate transform variable. The transform~{\tt T} could then be initialized with an @@ -2079,21 +2417,24 @@ transform T; T = identity xscaled -1 rotated 90 shifted (1,1); \end{verbatim} $$ -As this example indicates, transform expressions can be built up by applying -transformation operators to other transforms. The predefined transformation -{\tt identity}\index{identity?\texttt{identity}}\label{Dident} is a useful starting point -for this process. -This can be illustrated by paraphrasing the above equation for {\tt T} into -English: ``{\tt T} should be the transform obtained by doing whatever -{\tt identity} does, then scaling $x$~coordinates by $-1$, rotating $45^\circ$, -and shifting by $(1,1)$.'' This works because {\tt identity} is the identity -transformation which does nothing; i.e., {\tt transformed identity} is a no-op. +As this example indicates, transform expressions can be built up by +applying transformation operators to other transforms. The predefined +transformation {\tt +identity}\index{identity?\texttt{identity}}\label{Dident} is a useful +starting point for this process. This can be illustrated by +paraphrasing the above equation for {\tt T} into English: ``{\tt T} +should be the transform obtained by doing whatever {\tt identity} +does. Then scaling $x$~coordinates by $-1$, rotating $45^\circ$, and +shifting by $(1,1)$.'' This works because {\tt identity} is the +identity transformaion which does nothing; i.e., {\tt transformed +identity} is a no-op. The syntax for transform expressions and transformation operators is given in Figure~\ref{sytrans}. It includes two more options for \tdescr{transformer}:\index{reflectedabout?\texttt{reflectedabout}} $$ \hbox{\tt reflectededabout(}p, q\hbox{\tt )} $$ -reflects about the line defined by points $p$ and $q$; and\index{rotatedaround?\texttt{rotatedaround}} +reflects about the line defined by points $p$ and $q$; +and\index{rotatedaround?\texttt{rotatedaround}} $$ \hbox{\tt rotatedaround(}p,\theta\hbox{\tt )} $$ rotates $\theta$ degrees counter-clockwise around point $p$. For example, the equation for initializing transform~{\tt T} could have been @@ -2122,16 +2463,16 @@ $\tt \qquad \;|\; zscaled \descr{pair primary}$\\ $\tt \qquad \;|\; reflectedabout\hbox{\tt (}\descr{pair expression} \hbox{\tt ,}\descr{pair expression}\hbox{\tt )}$\\ $\tt \qquad \;|\; rotatedaround\hbox{\tt (}\descr{pair expression} - \hbox{\tt ,}\descr{numeric expression}\hbox{\tt )}$\\ + \hbox{\tt ,}\descr{numeric expression}\hbox{\tt )}$ \end{ctabbing} \caption{The syntax for transforms and related operators} \label{sytrans} \end{figure} -There is also a unary operator {\tt inverse}\index{inverse?\texttt{inverse}}\label{Dinv} -that takes a -transform and finds another transform that undoes the effect of the first -transform. Thus if +There is also a unary operator {\tt +inverse}\index{inverse?\texttt{inverse}}\label{Dinv} that takes a +transform and finds another transform that undoes the effect of the +first transform. Thus if $$ p = q{\tt\ transformed\ }T $$ then $$ q = p{\tt\ transformed\ inverse\ }T. $$ @@ -2140,10 +2481,10 @@ It is not legal to take the {\tt inverse} of an unknown transform\index{transformation!unknown} but we have already seen that you can say $$ \hbox{\tt T = } \descr{transform expression} $$ -when {\tt T} has not been given a value yet. It is also possible to apply -an unknown transform to a known pair or transform and use the result in a linear -equation. Three such equations are sufficient to determine a transform. Thus -the equations +when {\tt T} has not been given a value yet. It is also possible to +apply an unknown transform to a known pair or transform and use the +result in a linear equation. Three such equations are sufficient to +determine a transform. Thus the equations $$ \begin{verbatim} (0,1) transformed T' = (3,4); (1,1) transformed T' = (7,1); @@ -2164,9 +2505,10 @@ $$\openup\jot t_x&=0,& t_y&=0.\cr} $$ -Equations involving an unknown transform are treated as linear equations in the -six parameters that define the transform. These six parameters can also be -referred to directly as\index{xpart?\texttt{xpart}}\index{ypart?\texttt{ypart}}\index{xxpart?\texttt{xxpart}}% +Equations involving an unknown transform are treated as linear equations +in the six parameters that define the transform. These six parameters +can also be referred to directly +as\index{xpart?\texttt{xpart}}\index{ypart?\texttt{ypart}}\index{xxpart?\texttt{xxpart}}% \index{xypart?\texttt{xypart}}\index{yxpart?\texttt{yxpart}}\index{yypart?\texttt{yypart}}\label{Dtrprt} $$ {\tt xpart\ T},\ {\tt ypart\ T},\ {\tt xxpart\ T},\ {\tt xypart\ T},\ {\tt yxpart\ T},\ {\tt yypart\ T}, @@ -2201,7 +2543,7 @@ endfor dotlabels.top(1,2,3); dotlabels.bot(4); endfig; \end{verbatim} -\quad \mathcenter{\epsfbox{manfig.28}} +\quad \mathcenter{\includegraphics{manfig-28}} $$ \caption{MetaPost code and the resulting ``fractal'' figure} \label{fig27} @@ -2210,50 +2552,56 @@ $$ \subsection{Dashed Lines} -The MetaPost language provides many ways of changing the appearance of a line -besides just changing its width. One way is to use dashed lines as was done in -Figures \ref{fig4} and~\ref{fig22}. The syntax for this is\index{dashed?\texttt{dashed}} +The MetaPost language provides many ways of changing the appearance of a +line besides just changing its width. One way is to use dashed lines as +was done in Figures \ref{fig4} and~\ref{fig22}. The syntax for this +is\index{dashed?\texttt{dashed}} $$ {\tt draw}\, \descr{path expression}\, {\tt dashed}\, \descr{dash pattern} $$ -where a \tdescr{dash pattern}\index{dash pattern?\tdescr{dash pattern}} is really a special -type of \tdescr{picture expression}. There is a predefined \tdescr{dash pattern} -called {\tt evenly}\index{evenly?\texttt{evenly}}\label{Devenly} that makes dashes 3 PostScript -points long separated by gaps of the same size. -Another predefined dash pattern {\tt withdots}\index{withdots?\texttt{withdots}}\label{Dwdots} -produces dotted lines with dots 5 PostScript points apart.\footnote{{\tt withdots} -is only found in MetaPost version 0.50 and higher.} -For dots further apart or longer dashes further apart, the -\tdescr{dash pattern} can be -scaled\index{scaled?\texttt{scaled}} as shown in Figure~\ref{fig28} +where a \tdescr{dash pattern}\index{dash pattern?\tdescr{dash pattern}} +is really a special type of \tdescr{picture expression}. There is a +predefined \tdescr{dash pattern} called {\tt +evenly}\index{evenly?\texttt{evenly}}\label{Devenly} that makes dashes 3 +PostScript points long separated by gaps of the same size. Another +predefined dash pattern {\tt +withdots}\index{withdots?\texttt{withdots}}\label{Dwdots} produces +dotted lines with dots 5 PostScript points apart.\footnote{{\tt +withdots} is only found in MetaPost version 0.50 and higher.} For dots +further apart or longer dashes further apart, the \tdescr{dash pattern} +can be scaled\index{scaled?\texttt{scaled}} as shown in +Figure~\ref{fig28}. \begin{figure}[htp] -$$ \epsfbox{manfig.29} $$ +$$ \includegraphics{manfig-29} $$ \caption[Dashed lines and the corresponding dash patters] {Dashed lines each labeled with the \tdescr{dash pattern} used to create it.} \label{fig28} \end{figure} -Another way to change a dash pattern is to alter its phase by shifting it -horizontally. Shifting to the right makes the dashes move forward along the -path and shifting to the left moves them backward. Figure~\ref{fig29} illustrates -this effect. The dash pattern can be thought of as an infinitely repeating pattern -strung out along a horizontal line where the portion of the line to the right of -the $y$~axis is laid out along the path to be dashed\index{dash pattern?\tdescr{dash pattern}}. +Another way to change a dash pattern is to alter its phase by shifting +it horizontally. Shifting to the right makes the dashes move forward +along the path and shifting to the left moves them backward. +Figure~\ref{fig29} illustrates this effect. The dash pattern can be +thought of as an infinitely repeating pattern strung out along a +horizontal line where the portion of the line to the right of the +$y$~axis is laid out along the path to be dashed\index{dash +pattern?\tdescr{dash pattern}}. \begin{figure}[htp] -$$ \epsfbox{manfig.30} $$ +$$ \includegraphics{manfig-30} $$ \caption[Dashed lines and the corresponding dash patters] {Dashed lines and the MetaPost statements for drawing them where {\tt e4} refers to the dash pattern {\tt evenly scaled 4}.} \label{fig29} \end{figure} -When you shift a dash pattern so that the $y$~axis crosses the middle of a dash, -the first dash gets truncated. Thus the line with dash pattern {\tt e4} starts -with a dash of length 12bp followed by a 12bp gap and another 12bp dash, etc., -while {\tt e4 shifted (-6bp,0)} produces a 6bp dash, a 12 bp gap, then a -12bp dash, etc. This dash pattern could be specified more directly via the -{\tt dashpattern}\index{dash pattern?\texttt{dash pattern}}\label{Ddshpat} function: +When you shift a dash pattern so that the $y$~axis crosses the middle of +a dash, the first dash gets truncated. Thus the line with dash pattern +{\tt e4} starts with a dash of length 12bp followed by a 12bp gap and +another 12bp dash, etc., while {\tt e4 shifted (-6bp,0)} produces a 6bp +dash, a 12 bp gap, then a 12bp dash, etc. This dash pattern could be +specified more directly via the {\tt dashpattern}\index{dash +pattern?\texttt{dash pattern}}\label{Ddshpat} function: $$ \hbox{\tt dashpattern(on 6bp off 12bp on 6bp)} $$ This means ``draw the first 6bp of the line, then skip the next 12bp, then draw another 6bp and repeat.'' If the line to be dashed is more than 30bp long, the @@ -2274,24 +2622,26 @@ $\tt \descr{on/off clause} \rightarrow on \descr{numeric tertiary} \label{sydash} \end{figure} -Since a dash pattern is really just a special kind of picture, the -{\tt dashpattern} function returns a picture. It is not really necessary to know -the structure of such a picture, so the casual reader will probably want to skip -on to Section~\ref{oopt}. For those who want to know, a little experimentation -shows that if {\tt d} is +Since a dash pattern is really just a special kind of picture, the {\tt +dashpattern} function returns a picture. It is not really necessary to +know the structure of such a picture, so the casual reader will probably +want to skip on to Section~\ref{oopt}. For those who want to know, a +little experimentation shows that if {\tt d} is $$ \hbox{\tt dashpattern(on 6bp off 12bp on 6bp)}, $$ -then {\tt llcorner d} is $(0,24)$ and {\tt urcorner d} is $(24,24)$. Drawing -{\tt d} directly without using it as a dash pattern produces two thin horizontal -line segments like this: -$$ \epsfbox{manfig.31} $$ -The lines in this example are specified as having width zero, but this does not -matter because the line width is ignored when a picture is used as a dash pattern. - -The general rule for interpreting a picture {\tt d} as a dash pattern is that -the line segments in {\tt d} are projected onto the $x$-axis and the resulting -pattern is replicated to infinity in both directions by placing copies of the -pattern end-to-end. The actual dash lengths are obtained by starting at $x=0$ -and scanning in the positive $x$ direction. +then {\tt llcorner d} is $(0,24)$ and {\tt urcorner d} is $(24,24)$. +Drawing {\tt d} directly without using it as a dash pattern produces two +thin horizontal line segments like this: +$$ \includegraphics{manfig-31} $$ +The lines in this example are specified as having width zero, but this +does not matter because the line width is ignored when a picture is used +as a dash pattern. + +The general rule for interpreting a picture {\tt d} as a dash pattern is +that the line segments in {\tt d} are projected onto the $x$-axis and +the resulting pattern is replicated to infinity in both directions by +placing copies of the pattern end-to-end. The actual dash lengths are +obtained by starting at $x=0$ and scanning in the positive $x$ +direction. To make the idea of ``replicating to infinity'' more precise, let $P({\tt d})$ be the projection of {\tt d} onto the $x$~axis, and let @@ -2304,14 +2654,14 @@ where $[d_{\rm min},d_{\rm max}]$ is the range of $x$~coordinates in $P(d)$. In fact, MetaPost uses $$ \max(\left|y_0({\tt d})\right|,\, d_{\rm max}-d_{\rm min}), $$ where $y_0({\tt d})$ is the $y$ coordinate of the contents of {\tt d}. -The contents of {\tt d} should lie on a horizontal line, but if they do not, -the MetaPost interpreter just picks -a $y$~coordinate that occurs in {\tt d}\index{dash pattern?\tdescr{dash pattern}}. +The contents of {\tt d} should lie on a horizontal line, but if they do +not, the MetaPost interpreter just picks a $y$~coordinate that occurs in +{\tt d}\index{dash pattern?\tdescr{dash pattern}}. -A picture used as a dashed pattern must contain no text or filled regions, -but it can contain lines that are themselves dashed. This can give small dashes -inside of larger dashes as shown in -Figure~\ref{fig32}\index{dash pattern?\tdescr{dash pattern}!recursive} +A picture used as a dashed pattern must contain no text or filled +regions, but it can contain lines that are themselves dashed. This can +give small dashes inside of larger dashes as shown in +Figure~\ref{fig32}.\index{dash pattern?\tdescr{dash pattern}!recursive} \begin{figure}[htp] $$\begin{verbatim} @@ -2323,37 +2673,61 @@ currentpicture:=nullpicture; draw fullcircle scaled 1cm xscaled 3 dashed p; endfig; \end{verbatim} -\quad \mathcenter{\epsfbox{manfig.32}} +\quad \mathcenter{\includegraphics{manfig-32}} $$ -\caption{MetaPost code and the corresponding output} +\caption{MetaPost code for dashed patterns and the corresponding output} \label{fig32} \end{figure} +\label{dashed-pens} +Also, dashed patterns are intended to be used either with {\tt +pencircle} or no pen at all; {\tt pensquare} and other complex pens +should be avoided. This is because the output uses the PostScript +primitive {\tt setdash}, which does not interact well with the filled +paths created by polygonal pens. See Section~\ref{sec.pens}, p.\ +\pageref{sec.pens}. + +%\newpage + +\subsection{Local specials} + +If you want to attach a special bit of PostScript code, you can use +$$ +{\tt withprescript} \descr{string expression} +$$ +and +$$ +{\tt withpostcript} \descr{string expression} +$$ +the strings will be written to the output file before and after the +current object, each beginning on their own line. You can specify +multiple {\tt withprescript} or {\tt withpostscript} options if you +like. \subsection{Other Options} \label{oopt} -You might have noticed that the dashed lines produced by -{\tt dashed evenly}\index{evenly?\texttt{evenly}} appear -to have more black than white. This is an effect of the -{\tt linecap}\index{linecap?\texttt{linecap}}\label{Dlinecap} parameter -that controls the appearance of the ends of lines as well as the ends of dashes. -There are also a number of other ways to affect the appearance of things drawn -with MetaPost. - -The {\tt linecap} parameter has three different settings just as in PostScript. -Plain MetaPost gives this -internal variable\index{internal variables}\index{variables!internal} the -default value {\tt rounded}\index{rounded?\texttt{rounded}} -which causes line segments to be drawn with rounded ends like the segment from -{\tt z0} to {\tt z3} in Figure~\ref{fig33}. Setting -${\tt linecap}\mathrel{\hbox{\tt:=}}{\tt butt}$\index{butt?\texttt{butt}}\label{Dbutt} -cuts the ends off -flush so that dashes produced by {\tt dashed evenly}\index{evenly?\texttt{evenly}} have -length 3bp, not 3bp plus the line width. You can also get squared-off ends -that extend past the specified endpoints by setting -${\tt linecap}\mathrel{\hbox{\tt:=}}{\tt squared}$\index{squared?\texttt{squared}}\label{Dsqred} -as was done in the line from {\tt z2} to {\tt z5} in Figure~\ref{fig33}. +You might have noticed that the dashed lines produced by {\tt dashed +evenly}\index{evenly?\texttt{evenly}} appear to have more black than +white. This is an effect of the {\tt +linecap}\index{linecap?\texttt{linecap}}\label{Dlinecap} parameter that +controls the appearance of the ends of lines as well as the ends of +dashes. There are also a number of other ways to affect the appearance +of things drawn with MetaPost. + +The {\tt linecap} parameter has three different settings just as in +PostScript. Plain MetaPost gives this internal variable\index{internal +variables}\index{variables!internal} the default value {\tt +rounded}\index{rounded?\texttt{rounded}} which causes line segments to +be drawn with rounded ends like the segment from {\tt z0} to {\tt z3} in +Figure~\ref{fig33}. Setting ${\tt linecap}\mathrel{\hbox{\tt:=}}{\tt +butt}$\index{butt?\texttt{butt}}\label{Dbutt} cuts the ends off flush so +that dashes produced by {\tt dashed +evenly}\index{evenly?\texttt{evenly}} have length 3bp, not 3bp plus the +line width. You can also get squared-off ends that extend past the +specified endpoints by setting ${\tt linecap}\mathrel{\hbox{\tt:=}}{\tt +squared}$\index{squared?\texttt{squared}}\label{Dsqred} as was done in +the line from {\tt z2} to {\tt z5} in Figure~\ref{fig33}. \begin{figure}[htp] $$\begin{verbatim} @@ -2371,20 +2745,21 @@ dotlabels.top(0,1,2,3,4,5); endfig; linecap:=rounded; \end{verbatim} \qquad -\mathcenter{\epsfbox{manfig.33}} +\mathcenter{\includegraphics{manfig-33}} $$ \caption{MetaPost code and the corresponding output} \label{fig33} \end{figure} -Another parameter borrowed from PostScript affects the way a {\tt draw} statement -treats sharp corners\index{corners} in the path to be drawn. -The {\tt linejoin}\index{linejoin?\texttt{linejoin}}\label{Dlinejoin} parameter can -be {\tt rounded}\index{rounded?\texttt{rounded}}\label{Drnded}, -{\tt beveled}\index{beveled?\texttt{beveled}}\label{Dbvled}, -or {\tt mitered}\index{mitered?\texttt{mitered}}\label{Dmitred} as shown in Figure~\ref{fig34}. -The default value for plain MetaPost is {\tt rounded} which gives the effect of -drawing with a circular brush. +Another parameter borrowed from PostScript affects the way a {\tt draw} +statement treats sharp corners\index{corners} in the path to be drawn. +The {\tt linejoin}\index{linejoin?\texttt{linejoin}}\label{Dlinejoin} +parameter can be {\tt +rounded}\index{rounded?\texttt{rounded}}\label{Drnded}, {\tt +beveled}\index{beveled?\texttt{beveled}}\label{Dbvled}, or {\tt +mitered}\index{mitered?\texttt{mitered}}\label{Dmitred} as shown in +Figure~\ref{fig34}. The default value for plain MetaPost is {\tt +rounded} which gives the effect of drawing with a circular brush. \begin{figure}[htp] $$\begin{verbatim} @@ -2403,37 +2778,39 @@ dotlabels.bot(0,1,2,3,4,5,6,7,8); endfig; linejoin:=rounded; \end{verbatim} \qquad -\mathcenter{\epsfbox{manfig.34}} +\mathcenter{\includegraphics{manfig-34}} $$ \caption{MetaPost code and the corresponding output} \label{fig34} \end{figure} -When {\tt linejoin} is {\tt mitered}, sharp corners generate long pointed features -as shown in Figure~\ref{fig35}. Since this might be undesirable, there is an -internal variable\index{internal variables}\index{variables!internal} -called {\tt miterlimit}\index{miterlimit?\texttt{miterlimit}}\label{Dmiterlim} that controls how -extreme the situation can get before the mitered join is replaced by a beveled -join. For Plain MetaPost, {\tt miterlimit} has a default value of 10.0 and line -joins revert to beveled when the ratio of miter length to line width -reaches this value. +When {\tt linejoin} is {\tt mitered}, sharp corners generate long +pointed features as shown in Figure~\ref{fig35}. Since this might be +undesirable, there is an internal variable\index{internal +variables}\index{variables!internal} called {\tt +miterlimit}\index{miterlimit?\texttt{miterlimit}}\label{Dmiterlim} that +controls how extreme the situation can get before the mitered join is +replaced by a beveled join. For Plain MetaPost, {\tt miterlimit} has a +default value of 10.0 and line joins revert to beveled when the ratio of +miter length to line width reaches this value. \begin{figure}[htp] -$$ \epsfbox{manfig.35} $$ +$$ \includegraphics{manfig-35} $$ \caption{The miter length and line width whose ratio is limited by {\tt miterlimit}.} \label{fig35} \end{figure} -The {\tt linecap}, {\tt linejoin}, and {\tt miterlimit} parameters are especially -important because they also affect things that get drawn behind the scenes. -For instance, Plain MetaPost has statements for drawing -arrows\index{arrows}, and the arrowheads are slightly rounded when {\tt linejoin} -is {\tt rounded}. The effect depends on the line width and is quite subtle at the -default line width of 0.5bp as shown in Figure~\ref{fig36}. +The {\tt linecap}, {\tt linejoin}, and {\tt miterlimit} parameters are +especially important because they also affect things that get drawn +behind the scenes. For instance, Plain MetaPost has statements for +drawing arrows\index{arrows}, and the arrowheads are slightly rounded +when {\tt linejoin} is {\tt rounded}. The effect depends on the line +width and is quite subtle at the default line width of 0.5bp as shown in +Figure~\ref{fig36}. \begin{figure}[htp] -$$\epsfbox{manfig.36}$$ +$$\includegraphics{manfig-36}$$ \caption{Three ways of drawing arrows.} \label{fig36} \end{figure} @@ -2441,87 +2818,91 @@ $$\epsfbox{manfig.36}$$ Drawing arrows like the ones in Figure~\ref{fig36} is simply a matter of saying\index{drawarrow?\texttt{drawarrow}}\label{Ddrwarr} $$ {\tt drawarrow}\, \descr{path expression} $$ -instead of {\tt draw} \tdescr{path expression}. This draws the given path with -an arrowhead at the last point on the path. If you want the arrowhead at the -beginning of the path, just use the unary operator -{\tt reverse}\index{reverse?\texttt{reverse}}\label{Drevrse} to take the -original path and make a new one with its time sense reversed; i.e., for a -path~{\tt p} with {\tt length p}${}=n$, +instead of {\tt draw} \tdescr{path expression}. This draws the given +path with an arrowhead at the last point on the path. If you want the +arrowhead at the beginning of the path, just use the unary operator {\tt +reverse}\index{reverse?\texttt{reverse}}\label{Drevrse} to take the +original path and make a new one with its time sense reversed; i.e., for +a path~{\tt p} with {\tt length p}${}=n$, $$ {\tt point\ } t {\tt\ of\ reverse\ p} \quad {\rm and} \quad {\tt point\ } n-t {\tt\ of\ p} $$ are synonymous. -As shown in Figure~\ref{fig36}, a statement beginning\index{drawdblarrow?\texttt{drawdblarrow}}% +As shown in Figure~\ref{fig36}, a statement +beginning\index{drawdblarrow?\texttt{drawdblarrow}}% \index{arrows!double-headed}\label{Ddrwdar} $$ {\tt drawdblarrow}\, \descr{path expression} $$ -draws a double-headed arrow. The size of the arrowhead is guaranteed to be -larger than the line width, but it might need adjusting if the line width is -very great. This is done by assigning a new value to the +draws a double-headed arrow. The size of the arrowhead is guaranteed to +be larger than the line width, but it might need adjusting if the line +width is very great. This is done by assigning a new value to the internal variable\index{internal variables}\index{variables!internal} -{\tt ahlength}\index{ahlength?\texttt{ahlength}}\label{Dahlength} -that determines arrowhead length as shown in Figure~\ref{fig37}. -Increasing {\tt ahlength} from the default value of 4 PostScript points to -1.5 centimeters produces the large arrowhead in Figure~\ref{fig37}. There +{\tt ahlength}\index{ahlength?\texttt{ahlength}}\label{Dahlength} that +determines arrowhead length as shown in Figure~\ref{fig37}. Increasing +{\tt ahlength} from the default value of 4 PostScript points to 1.5 +centimeters produces the large arrowhead in Figure~\ref{fig37}. There is also an {\tt ahangle}\index{ahangle?\texttt{ahangle}}\label{Dahangle} -parameter that controls the angle -at the tip of the arrowhead. The default value of this angle is 45 degrees -as shown in the figure. +parameter that controls the angle at the tip of the arrowhead. The +default value of this angle is 45 degrees as shown in the figure. \begin{figure}[htp] -$$ \epsfbox{manfig.37} $$ +$$ \includegraphics{manfig-37} $$ \caption[A large arrowhead with key parameters labeled.] {A large arrowhead with key parameters labeled and paths used to draw it marked with white lines.} \label{fig37} \end{figure} -The arrowhead is created by filling the triangular region that is outlined -in white in Figure~\ref{fig37} and then drawing around it with the currently -picked up pen. This combination of filling and drawing can be combined into -a single {\tt filldraw} statement\index{filldraw?\texttt{filldraw}}\label{Dfildrw}: +The arrowhead is created by filling the triangular region that is +outlined in white in Figure~\ref{fig37} and then drawing around it with +the currently picked up pen. This combination of filling and drawing +can be combined into a single {\tt filldraw} +statement\index{filldraw?\texttt{filldraw}}\label{Dfildrw}: $$ {\tt filldraw}\, \descr{path expression}\, \descr{optional {\tt dashed} and {\tt withcolor} and {\tt withpen} clauses}; $$ -The \tdescr{path expression} should be a closed cycle like the triangular path -in Figure~\ref{fig37}. This path should not be confused with the path argument -to {\tt drawarrow} which is indicated by a white line in the figure. - -White lines like the ones in the figure can be created by an -{\tt undraw}\index{undraw?\texttt{undraw}}\label{Dundraw} statement. -This is an erasing\index{erasing} -version of {\tt draw} that draws {\tt withcolor background}\index{background?\texttt{background}} -just as the {\tt unfill} statement does. There is also an -{\tt unfilldraw}\index{unfilldraw?\texttt{unfilldraw}}\label{Dunfdrw} -statement just in case someone finds a -use for it. - -The {\tt filldraw}, {\tt undraw} and {\tt unfilldraw} statements and all the -arrow drawing statements are like the {\tt fill} and {\tt draw} statements in that -they take {\tt dashed}\index{dashed?\texttt{dashed}}, {\tt withpen}\index{withpen?\texttt{withpen}}, -and {\tt withcolor}\index{withcolor?\texttt{withcolor}} options. -When you have a lot of drawing statements it is -nice to be able to apply an option such as {\tt withcolor 0.8white} to all of -them without having to type this repeatedly as was done in Figures \ref{fig33} -and~\ref{fig34}. The statement for this purpose is\index{drawoptions?\texttt{drawoptions}}\label{Ddropts} +The \tdescr{path expression} should be a closed cycle like the +triangular path in Figure~\ref{fig37}. This path should not be confused +with the path argument to {\tt drawarrow} which is indicated by a white +line in the figure. + +White lines like the ones in the figure can be created by an {\tt +undraw}\index{undraw?\texttt{undraw}}\label{Dundraw} statement. This is +an erasing\index{erasing} version of {\tt draw} that draws {\tt +withcolor background}\index{background?\texttt{background}} just as the +{\tt unfill} statement does. There is also an {\tt +unfilldraw}\index{unfilldraw?\texttt{unfilldraw}}\label{Dunfdrw} +statement just in case someone finds a use for it. + +The {\tt filldraw}, {\tt undraw} and {\tt unfilldraw} statements and all +the arrow drawing statements are like the {\tt fill} and {\tt draw} +statements in that they take {\tt dashed}\index{dashed?\texttt{dashed}}, +{\tt withpen}\index{withpen?\texttt{withpen}}, and {\tt +withcolor}\index{withcolor?\texttt{withcolor}} options. When you have a +lot of drawing statements it is nice to be able to apply an option such +as {\tt withcolor 0.8white} to all of them without having to type this +repeatedly as was done in Figures \ref{fig33} and~\ref{fig34}. The +statement for this purpose +is\index{drawoptions?\texttt{drawoptions}}\label{Ddropts} $$ \hbox{\tt drawoptions(} \descr{text} \hbox{\tt )} $$ -where the \tdescr{text} argument gives a sequence of {\tt dashed}, {\tt withcolor}, -and {\tt withpen} options to be applied automatically to all drawing statements. -If you specify +where the \tdescr{text} argument gives a sequence of {\tt dashed}, {\tt +withcolor}, and {\tt withpen} options to be applied automatically to all +drawing statements. If you specify $$ \hbox{\tt drawoptions(withcolor .5[black,white])} $$ and then want to draw a black line, you can override the {\tt drawoptions} by specifying $$ {\tt draw}\, \descr{path expression}\, {\tt withcolor\ black} $$ To turn off {\tt drawoptions} all together, just give an empty list: $$ \hbox{\tt drawoptions()} $$ -(This is done automatically by the {\tt beginfig}\index{beginfig?\texttt{beginfig}} macro). +(This is done automatically by the {\tt +beginfig}\index{beginfig?\texttt{beginfig}} macro). Since irrelevant options are ignored, there is no harm in giving a statement like $$ \hbox{\tt drawoptions(dashed evenly)} $$ -followed by a sequence of {\tt draw} and {\tt fill} commands. It does not make -sense to use a dash pattern when filling so the {\tt dashed evenly} gets ignored -for {\tt fill} statements. It turns out that +followed by a sequence of {\tt draw} and {\tt fill} commands. It does +not make sense to use a dash pattern when filling so the {\tt dashed +evenly} gets ignored for {\tt fill} statements. It turns out that $$ \hbox{\tt drawoptions(withpen } \descr{pen expression} \hbox{\tt )} $$ does affect {\tt fill} statements as well as {\tt draw} statements. In fact there is a special pen variable called @@ -2529,33 +2910,37 @@ In fact there is a special pen variable called {\tt fill} \ldots\ {\tt withpen currentpen} is equivalent to a {\tt filldraw} statement. -Precisely what does it mean to say that drawing options affect those statements -where they make sense? The {\tt dashed} \tdescr{dash pattern} option only affects +Precisely what does it mean to say that drawing options affect those +statements where they make sense? The {\tt dashed} \tdescr{dash +pattern} option only affects $$ {\tt draw}\, \descr{path expression} $$ statements, and text appearing in the \tdescr{picture expression} argument to $$ {\tt draw}\, \descr{picture expression} $$ -statement is only affected by the {\tt withcolor} \tdescr{color expression} option. -For all other combinations of drawing statements and options, there is some effect. -An option applied to a {\tt draw} \tdescr{picture expression} statement will in -general affect some parts of the picture but not others. For instance, -a {\tt dashed} or {\tt withpen} option will affect all the lines in the picture -but none of the labels. +statement is only affected by the {\tt withcolor} \tdescr{color +expression} option. For all other combinations of drawing statements +and options, there is some effect. An option applied to a {\tt draw} +\tdescr{picture expression} statement will in general affect some parts +of the picture but not others. For instance, a {\tt dashed} or {\tt +withpen} option will affect all the lines in the picture but none of the +labels. \subsection{Pens} +\label{sec.pens} Previous sections have given numerous examples of {\tt pickup} -\tdescr{pen expression} and {\tt withpen} \tdescr{pen expression}, but there have -not been any examples of pen expressions other than +\tdescr{pen expression} and {\tt withpen} \tdescr{pen expression}, but +there have not been any examples of pen expressions other than $$ {\tt pencircle\ scaled}\, \descr{numeric primary} $$ -which produces lines of a specified width. For calligraphic effects such in -Figure~\ref{fig38}, you can apply any of the transformation operators discussed -in Section~\ref{transsec}. The starting point for such transformations is -{\tt pencircle}\index{pencircle?\texttt{pencircle}}\label{Dpncirc}, -a circle one PostScript point in diameter. Thus affine -transformations produce a circular or elliptical\index{pens!elliptical} pen shape. -The width of lines drawn with the pen depends on how nearly perpendicular the line -is to the long axis of the ellipse. +which produces lines of a specified width. For calligraphic effects +such in Figure~\ref{fig38}, you can apply any of the transformation +operators discussed in Section~\ref{transsec}. The starting point for +such transformations is {\tt +pencircle}\index{pencircle?\texttt{pencircle}}\label{Dpncirc}, a circle +one PostScript point in diameter. Thus affine transformations produce a +circular or elliptical\index{pens!elliptical} pen shape. The width of +lines drawn with the pen depends on how nearly perpendicular the line is +to the long axis of the ellipse. \begin{figure}[htp] $$\begin{verbatim} @@ -2575,68 +2960,76 @@ draw z0--z1--z2--z3--z4--z5--z6 withcolor .7white; dotlabels.top(0,1,2,3,4,5,6); endfig; \end{verbatim} -\quad \mathcenter{\epsfbox{manfig.38}} +\quad \mathcenter{\includegraphics{manfig-38}} $$ \caption{MetaPost code and the resulting ``calligraphic'' figure.} \label{fig38}\index{lft?\texttt{lft}}\index{bot?\texttt{bot}}\index{top?\texttt{top}} \end{figure} -Figure~\ref{fig38} demonstrates operators {\tt lft}\index{lft?\texttt{lft}}\label{Dlft}, -{\tt rt}\index{rt?\texttt{rt}}\label{Drt}, {\tt top}\index{top?\texttt{top}}\label{Dtop}, -and {\tt bot}\index{bot?\texttt{bot}}\label{Dbot} -that answer the question, ``If the current pen is placed at the position -given by the argument, where will its left, right, top, or bottom edge be?'' -In this case the current pen is the ellipse given in the {\tt pickup} statement -and its bounding box is 0.1734 inches wide and 0.1010 inches high, so -{\tt rt x3} is ${\tt x3}+{\tt 0.0867in}$ and {\tt bot y5} is -${\tt y5}-{\tt 0.0505in}$. -The {\tt lft}, {\tt rt}, {\tt top}, and {\tt bot} operators also accept arguments -of type pair in which case they compute the $x$ and~$y$ coordinates of the -leftmost, rightmost, topmost, or bottommost point on the pen shape. For example, +Figure~\ref{fig38} demonstrates operators {\tt +lft}\index{lft?\texttt{lft}}\label{Dlft}, {\tt +rt}\index{rt?\texttt{rt}}\label{Drt}, {\tt +top}\index{top?\texttt{top}}\label{Dtop}, and {\tt +bot}\index{bot?\texttt{bot}}\label{Dbot} that answer the question, ``If +the current pen is placed at the position given by the argument, where +will its left, right, top, or bottom edge be?'' In this case the +current pen is the ellipse given in the {\tt pickup} statement and its +bounding box is 0.1734 inches wide and 0.1010 inches high, so {\tt rt +x3} is ${\tt x3}+{\tt 0.0867in}$ and {\tt bot y5} is ${\tt y5}-{\tt +0.0505in}$. The {\tt lft}, {\tt rt}, {\tt top}, and {\tt bot} operators +also accept arguments of type pair in which case they compute the $x$ +and~$y$ coordinates of the leftmost, rightmost, topmost, or bottommost +point on the pen shape. For example, $$ {\tt rt}(x,y) = (x,y)+({\tt 0.0867in}, {\tt 0.0496in}) $$ -for the pen in Figure~\ref{fig38}. Note that {\tt beginfig}\index{beginfig?\texttt{beginfig}} -resets the current pen to a default value of +for the pen in Figure~\ref{fig38}. Note that {\tt +beginfig}\index{beginfig?\texttt{beginfig}} resets the current pen to a +default value of $$ \hbox{\tt pencircle scaled 0.5bp} $$ -at the beginning of each figure. This value can be reselected at any time -by giving the command -{\tt pickup defaultpen}\index{defaultpen?\texttt{defaultpen}}\label{Ddefaultpen}. - -This would be the end of the story on pens, except that -for compatibility with \MF\index{metafont?\MF}, MetaPost also allows pen shapes to be -polygonal\index{pens!polygonal}. -There is a predefined pen called -{\tt pensquare}\index{pensquare?\texttt{pensquare}}\label{Dpnsqr} that -can be transformed to yield pens shaped like parallelograms. In fact, there is -even an operator called {\tt makepen}\index{makepen?\texttt{makepen}}\label{Dmkpen} that takes -a convex-polygon-shaped path and makes a pen that shape and size. If the path is -not exactly convex or polygonal, the {\tt makepen} operator will straighten the -edges and/or drop some of the vertices. -In particular, {\tt pensquare} is equivalent to +at the beginning of each figure. This value can be reselected at any +time by giving the command {\tt pickup +defaultpen}\index{defaultpen?\texttt{defaultpen}}\label{Ddefaultpen}. + +This would be the end of the story on pens, except that for +compatibility with \MF\index{metafont?\MF}, MetaPost also allows pen +shapes to be polygonal\index{pens!polygonal}. There is a predefined pen +called {\tt pensquare}\index{pensquare?\texttt{pensquare}}\label{Dpnsqr} +that can be transformed to yield pens shaped like parallelograms. + +In fact, there is even an operator called {\tt +makepen}\index{makepen?\texttt{makepen}}\label{Dmkpen} that takes a +convex-polygon-shaped path and makes a pen that shape and size. If the +path is not exactly convex or polygonal, the {\tt makepen} operator will +straighten the edges and/or drop some of the vertices. In particular, +{\tt pensquare} is equivalent to $$ \hbox{\tt makepen((-.5,-.5)--(.5,-.5)--(.5,.5)--(-.5,.5)--cycle)} $$ -The inverse of {\tt makepen} is the -{\tt makepath}\index{makepath?\texttt{makepath}}\label{Dmkpath} operator -that takes a \tdescr{pen primary} and returns the corresponding path. Thus -{\tt makepath pencircle} produces a circular path identical to -{\tt fullcircle}\index{fullcircle?\texttt{fullcircle}}. This also works for a polygonal pen -so that +{\tt pensquare} and {\tt makepen} should not be used with dash +patterns. See the end of Section~\ref{sec.pens}, p.\ +\pageref{dashed-pens}. + +The inverse of {\tt makepen} is the {\tt +makepath}\index{makepath?\texttt{makepath}}\label{Dmkpath} operator that +takes a \tdescr{pen primary} and returns the corresponding path. Thus +{\tt makepath pencircle} produces a circular path identical to {\tt +fullcircle}\index{fullcircle?\texttt{fullcircle}}. This also works for +a polygonal pen so that $$ {\tt makepath\ makepen}\, \descr{path expression} $$ will take any cyclic path and turn it into a convex polygon\index{convex polygons}. \subsection{Clipping and Low-Level Drawing Commands} -Drawing statements such as {\tt draw}, {\tt fill}, {\tt filldraw}, and {\tt unfill} -are part of the Plain macro\index{Plain macros} package and are defined in terms -of more primitive statements. The main difference between the drawing -statements discussed in previous sections and the more primitive versions is that -the primitive drawing statements all require you to specify a picture variable to -hold the results. For {\tt fill}, {\tt draw}, and related statements, the results -always go to a picture variable called -{\tt currentpicture}\index{currentpicture?\texttt{currentpicture}}\label{Dcurpic}. -The syntax for the primitive -drawing statements that allow you to specify a picture variable is shown in -Figure~\ref{sydraw}. +Drawing statements such as {\tt draw}, {\tt fill}, {\tt filldraw}, and +{\tt unfill} are part of the Plain macro\index{Plain macros} package and +are defined in terms of more primitive statements. The main difference +between the drawing statements discussed in previous sections and the +more primitive versions is that the primitive drawing statements all +require you to specify a picture variable to hold the results. For {\tt +fill}, {\tt draw}, and related statements, the results always go to a +picture variable called {\tt +currentpicture}\index{currentpicture?\texttt{currentpicture}}\label{Dcurpic}. +The syntax for the primitive drawing statements that allow you to +specify a picture variable is shown in Figure~\ref{sydraw}. \begin{figure}[htp] \begin{ctabbing} @@ -2650,6 +3043,12 @@ $\tt \qquad \;|\; addto \descr{picture variable} $\tt \descr{option list} \rightarrow \descr{empty} \;|\; \descr{drawing option} \descr{option list}$\\ $\tt \descr{drawing option} \rightarrow withcolor \descr{color expression}$\\ +$\tt \qquad \;|\; withrgbcolor \descr{rgbcolor expression} \;|\; + withcmykcolor \descr{cmykcolor expression}$\\ +$\tt \qquad \;|\; withgreyscale \descr{numeric expression} \;|\; + withoutcolor$\\ +$\tt \qquad \;|\; withprescript \descr{string expression} \;|\; + withpostscript \descr{string expression}$\\ $\tt \qquad \;|\; withpen \descr{pen expression} \;|\; dashed \descr{picture expression}$ \end{ctabbing} @@ -2661,21 +3060,22 @@ $\tt \qquad \;|\; withpen \descr{pen expression} \;|\; \end{figure} The syntax for primitive drawing commands is compatible with -\MF\index{metafont?\MF}. Table~\ref{draweqv} shows how the primitive drawing statements -relate to the familiar {\tt draw} and {\tt fill} statements. Each of the -statements in the first column of the table could be ended with an -\tdescr{option list} of its own, which is equivalent to appending the -\tdescr{option list} to the corresponding entry in the second column of the table. -For example, +\MF\index{metafont?\MF}. Table~\ref{draweqv} shows how the primitive +drawing statements relate to the familiar {\tt draw} and {\tt fill} +statements. Each of the statements in the first column of the table +could be ended with an \tdescr{option list} of its own, which is +equivalent to appending the \tdescr{option list} to the corresponding +entry in the second column of the table. For example, $$ {\tt draw}\ p\ {\tt withpen\ pencircle} $$ is equivalent to $$ {\tt addto\ currentpicture\ doublepath}\ p\ {\tt withpen\ currentpen\ withpen\ pencircle} $$ -where {\tt currentpen}\index{currentpen?\texttt{currentpen}}\label{Dcurpen} is a special -pen variable that always holds the last pen picked up. -The second {\tt withpen} option silently overrides the {\tt withpen currentpen} -from the expansion of {\tt draw}. +where {\tt +currentpen}\index{currentpen?\texttt{currentpen}}\label{Dcurpen} is a +special pen variable that always holds the last pen picked up. The +second {\tt withpen} option silently overrides the {\tt withpen +currentpen} from the expansion of {\tt draw}. \begin{table}[htp] $$\begin{tabular}{|l|l|} \hline @@ -2696,26 +3096,34 @@ $$\begin{tabular}{|l|l|} \hline {\tt withcolor} $b$\\ \hline \end{tabular} $$ -\caption[Drawing statements and equivalent primitive commands] - {Common drawing statements and equivalent primitive versions, where - $q$ stands for {\tt currentpen}, $b$ stands for {\tt background}, - $p$ stands for any path, $c$ stands for a cyclic path, and {\it pic} stands - for a \tdescr{picture expression}. Note that nonempty {\tt drawoptions} - would complicate the entries in the second column.} +\caption[Drawing statements and equivalent primitive commands] {Common + drawing statements and equivalent primitive versions, where $q$ + stands for {\tt currentpen}, $b$ stands for {\tt background}, + $p$ stands for any path, $c$ stands for a cyclic path, and {\it + pic} stands for a \tdescr{picture expression}. Note that + nonempty {\tt drawoptions} would complicate the entries in the + second column.} \label{draweqv} \index{drawoptions?\texttt{drawoptions}} \end{table} -There are two more primitive drawing commands that do not accept any drawing -options. One is the {\tt setbounds} command that was discussed in -Section~\ref{meas}; the other is the -{\tt clip} command\index{clip?\texttt{clip}}\label{Dclip}: + +The {\tt image}\index{image?\texttt{image}}\label{Dimage} macro from +Plain MetaPost takes any text as its argument, executes it, and returns +the resulting picture. The value of {\tt currentpicture} is not +affected. + +There are two more primitive drawing commands that do not accept any +drawing options. One is the {\tt setbounds} command that was discussed +in Section~\ref{meas}; the other is the {\tt clip} +command\index{clip?\texttt{clip}}\label{Dclip}: $$ {\tt clip}\, \descr{picture variable}\, {\tt to}\, \descr{path expression} $$ Given a cyclic path, this statement trims the contents of the \tdescr{picture variable} to eliminate everything outside of the cyclic path. There is no ``high level'' version of this statement, so you have to use $$ {\tt clip\ currentpicture\ to}\, \descr{path expression} $$ -if you want to clip {\tt currentpicture}\index{currentpicture?\texttt{currentpicture}}. +if you want to clip {\tt +currentpicture}\index{currentpicture?\texttt{currentpicture}}. Figure~\ref{fig40} illustrates clipping. \begin{figure}[htp] @@ -2735,30 +3143,34 @@ draw p3; endfig; \end{verbatim} \qquad -\mathcenter{\epsfbox{manfig.40}} +\mathcenter{\includegraphics{manfig-40}} $$ \caption{MetaPost code and the resulting ``clipped'' figure.} \label{fig40} \end{figure} -All the primitive drawing operations would be useless without one last operation -called {\tt shipout}. The statement\index{shipout?\texttt{shipout}}\label{Dship} +All the primitive drawing operations would be useless without one last +operation called {\tt shipout}. The +statement\index{shipout?\texttt{shipout}}\label{Dship} $$ {\tt shipout}\, \descr{picture expression} $$ -This writes out a picture as a PostScript\index{PostScript} file whose name ends -{\tt.}{\it nnn}, where {\tt nnn} is the decimal representation of the value of -the internal variable\index{internal variables}\index{variables!internal} -{\tt charcode}\index{charcode?\texttt{charcode}}\label{Dcharcode}. -(The name ``{\tt charcode}'' is for compatibility with \MF\index{metafont?\MF}.) -Normally, {\tt beginfig}\index{beginfig?\texttt{beginfig}} sets {\tt charcode}, and -{\tt endfig}\index{endfig?\texttt{endfig}} invokes {\tt shipout}. +This writes out a picture as a PostScript\index{PostScript} file whose +name ends {\tt.}{\it nnn}, where {\tt nnn} is the decimal representation +of the value of the internal variable\index{internal +variables}\index{variables!internal} {\tt +charcode}\index{charcode?\texttt{charcode}}\label{Dcharcode}. (The name +``{\tt charcode}'' is for compatibility with \MF\index{metafont?\MF}.) +Normally, {\tt beginfig}\index{beginfig?\texttt{beginfig}} sets {\tt +charcode}, and {\tt endfig}\index{endfig?\texttt{endfig}} invokes {\tt +shipout}. \section{Macros} \label{macros} -As alluded to earlier, MetaPost has a set of automatically included macros called -the Plain macro package\index{Plain macros}, and some of the commands discussed in -previous sections are defined as macros instead of being built into MetaPost. -The purpose of this section is to explain how to write such macros. +As alluded to earlier, MetaPost has a set of automatically included +macros called the Plain macro package\index{Plain macros}, and some of +the commands discussed in previous sections are defined as macros +instead of being built into MetaPost. The purpose of this section is to +explain how to write such macros. Macros with no arguments are very simple. A macro definition\index{replacement text?\tdescr{replacement text}}% @@ -2766,59 +3178,67 @@ A macro definition\index{replacement text?\tdescr{replacement text}}% $$ {\tt def}\, \descr{symbolic token}\, \hbox{\tt =}\, \descr{replacement text}\, {\tt enddef} $$ -makes the \tdescr{symbolic token} an abbreviation for the \tdescr{replacement text}, -where the \tdescr{replacement text} can be virtually any sequence of tokens. For -example, the Plain macro package could almost define the {\tt fill} statement like +makes the \tdescr{symbolic token} an abbreviation for the +\tdescr{replacement text}, where the \tdescr{replacement text} can be +virtually any sequence of tokens. For example, the Plain macro package +could almost define the {\tt fill} statement like this\index{fill?\texttt{fill}}: $$ \hbox{\tt def fill = addto currentpicture contour enddef} $$ -Macros with arguments are similar, except they have formal parameters that tell -how to use the arguments in the \tdescr{replacement text}. For example, the -{\tt rotatedaround}\index{rotatedaround?\texttt{rotatedaround}} macro is defined like this: +Macros with arguments are similar, except they have formal parameters +that tell how to use the arguments in the \tdescr{replacement text}. +For example, the {\tt +rotatedaround}\index{rotatedaround?\texttt{rotatedaround}} macro is +defined like this: $$\begin{verbatim} def rotatedaround(expr z, d) = shifted -z rotated d shifted z enddef; \end{verbatim} $$ -The {\tt expr}\index{expr?\texttt{expr}} in this definition means that formal parameters -{\tt z} and {\tt d} can be arbitrary expressions. (They should be pair expressions -but the MetaPost interpreter does not immediately check for that.) +The {\tt expr}\index{expr?\texttt{expr}} in this definition means that +formal parameters {\tt z} and {\tt d} can be arbitrary expressions. +(They should be pair expressions but the MetaPost interpreter does not +immediately check for that.) -Since MetaPost is an interpreted language, macros with arguments are a lot like -subroutines\index{subroutines}. MetaPost macros are often used like subroutines, -so the language includes programming concepts to support this. -These concepts include local variables, loops, and conditional statements. +Since MetaPost is an interpreted language, macros with arguments are a +lot like subroutines\index{subroutines}. MetaPost macros are often used +like subroutines, so the language includes programming concepts to +support this. These concepts include local variables, loops, and +conditional statements. \subsection{Grouping} \label{grsec} Grouping in MetaPost is essential for functions\index{functions} and -local\index{variables!local}\index{locality} variables. -The basic idea is that a group is -a sequence of statements possibly followed by an expression with the provision -that certain symbolic tokens\index{tokens!symbolic} can have their old meanings -restored at the end of the group. If the group ends with an expression, the -group behaves like a function call that returns that expression. Otherwise, -the group is just a compound statement\index{compound statement}. -The syntax for a group is\index{begingroup?\texttt{begingroup}}\index{endgroup?\texttt{endgroup}} +local\index{variables!local}\index{locality} variables. The basic idea +is that a group is a sequence of statements possibly followed by an +expression with the provision that certain symbolic +tokens\index{tokens!symbolic} can have their old meanings restored at +the end of the group. If the group ends with an expression, the group +behaves like a function call that returns that expression. Otherwise, +the group is just a compound statement\index{compound statement}. The +syntax for a group +is\index{begingroup?\texttt{begingroup}}\index{endgroup?\texttt{endgroup}} $$ {\tt begingroup}\, \descr{statement list}\, {\tt endgroup} $$ or $$ {\tt begingroup}\, \descr{statement list}\, \descr{expression}\, {\tt endgroup} $$ -where a \tdescr{statement list} is a sequence of statements each followed by a -semicolon. A group with an \tdescr{expression} after the \tdescr{statement list} -behaves like a \tdescr{primary} in Figure~\ref{syexpr} or like a -\tdescr{numeric atom} in Figure~\ref{synprim}. - -Since the \tdescr{replacement text} for the {\tt beginfig}\index{beginfig?\texttt{beginfig}} -macro starts with {\tt begingroup} and the \tdescr{replacement text} for -{\tt endfig}\index{endfig?\texttt{endfig}} ends with {\tt endgroup}, -each figure in a MetaPost input file behaves like a -group. This is what allows figures can have local variables. -We have already seen in Section~\ref{vardecl} that -variable names beginning with {\tt x} or {\tt y} are local in the sense that they -have unknown values at the beginning of each figure and these values are forgotten -at the end of each figure. The following example illustrates how locality works: +where a \tdescr{statement list} is a sequence of statements each +followed by a semicolon. A group with an \tdescr{expression} after the +\tdescr{statement list} behaves like a \tdescr{primary} in +Figure~\ref{syexpr} or like a \tdescr{numeric atom} in +Figure~\ref{synprim}. + +Since the \tdescr{replacement text} for the {\tt +beginfig}\index{beginfig?\texttt{beginfig}} macro starts with {\tt +begingroup} and the \tdescr{replacement text} for {\tt +endfig}\index{endfig?\texttt{endfig}} ends with {\tt endgroup}, each +figure in a MetaPost input file behaves like a group. This is what +allows figures can have local variables. We have already seen in +Section~\ref{vardecl} that variable names beginning with {\tt x} or {\tt +y} are local in the sense that they have unknown values at the beginning +of each figure and these values are forgotten at the end of each figure. +The following example illustrates how locality works: \begin{eqnarray*} && \hbox{\tt x23 = 3.1;}\\ && \hbox{\tt beginfig(17);}\\ @@ -2840,8 +3260,9 @@ indicating that {\tt x23} has returned to its former value of {\tt 3.1} and The locality of {\tt x} and {\tt y} variables is achieved by the statement\index{save?\texttt{save}}\label{Dsave} $$ \hbox{\tt save x,y} $$ -in the \tdescr{replacement text} for {\tt beginfig}\index{beginfig?\texttt{beginfig}}. -In general, variables are made local by the statement +in the \tdescr{replacement text} for {\tt +beginfig}\index{beginfig?\texttt{beginfig}}. In general, variables are +made local by the statement $$ {\tt save}\, \descr{symbolic token list} $$ where \tdescr{symbolic token list} is a comma-separated list of tokens:\index{tokens!symbolic} @@ -2850,32 +3271,36 @@ $\tt \descr{symbolic token list} \rightarrow \descr{symbolic token}$\\ $\tt \qquad \;|\; \descr{symbolic token}\hbox{\tt ,} \descr{symbolic token list}$ \end{ctabbing} -All variables whose names begin with one of the specified symbolic tokens become -unknown numerics and their present values are saved for restoration at the end -of the current group. If the {\tt save} statement is used outside of a group, the -original values are simply discarded. - -The main purpose of the {\tt save} statement is to allow macros to use variables -without interfering with existing variables or variables in other calls to the -same macro. For example, the predefined macro {\tt whatever}\index{whatever} -has the \tdescr{replacement text} +All variables whose names begin with one of the specified symbolic +tokens become unknown numerics and their present values are saved for +restoration at the end of the current group. If the {\tt save} +statement is used outside of a group, the original values are simply +discarded. + +The main purpose of the {\tt save} statement is to allow macros to use +variables without interfering with existing variables or variables in +other calls to the same macro. For example, the predefined macro {\tt +whatever}\index{whatever} has the \tdescr{replacement text} $$ \hbox{\tt begingroup save ?; ? endgroup} $$ -This returns an unknown numeric quantity, but it is no longer called question -mark since that name was local to the group. Asking the name via -{\tt show\index{show?\texttt{show}} whatever} yields\index{CAPSULE?\texttt{CAPSULE}} +This returns an unknown numeric quantity, but it is no longer called +question mark since that name was local to the group. Asking the name +via {\tt show\index{show?\texttt{show}} whatever} +yields\index{CAPSULE?\texttt{CAPSULE}} $$ \hbox{\tt >> \%CAPSULE}{\it nnnn} $$ where {\it nnnn} is an identification number that is chosen when {\tt save} makes the name question mark disappear. -In spite of the versatility of {\tt save}, it cannot be used to make local changes -to any of MetaPost's -internal variables\index{internal variables}\index{variables!internal}. -A statement such as\index{linecap?\texttt{linecap}} +In spite of the versatility of {\tt save}, it cannot be used to make +local changes to any of MetaPost's internal variables\index{internal +variables}\index{variables!internal}. A statement such +as\index{linecap?\texttt{linecap}} $$ \hbox{\tt save linecap} $$ -would cause MetaPost to temporarily forget the special meaning of this variable -and just make it an unknown numeric. If you want to draw one dashed line with -{\tt linecap:=butt} and then go back to the previous value, you can use the -{\tt interim}\index{interim?\texttt{interim}}\label{Dinterm} statement as follows: +would cause MetaPost to temporarily forget the special meaning of this +variable and just make it an unknown numeric. If you want to draw one +dashed line with {\tt linecap:=butt} and then go back to the previous +value, you can use the {\tt +interim}\index{interim?\texttt{interim}}\label{Dinterm} statement as +follows: \begin{eqnarray*} && \hbox{\tt begingroup interim linecap:=butt;}\\ && {\tt draw}\, \descr{path expression}\, \hbox{\tt dashed evenly; endgroup} @@ -2904,36 +3329,39 @@ $$\tt rotatedaround\hbox{\tt (} \descr{expression}\hbox{\tt ,} \descr{expression}\hbox{\tt )} $$ -The keyword {\tt expr}\index{expr?\texttt{expr}}\index{parameter!expr} in the macro -definition means that the -parameters can be expressions of any type. When the definition specifies -{\tt (expr z, d)}, the formal parameters {\tt z} and {\tt d} behave like -variables of the appropriate -types. Within the \tdescr{replacement text}, they can be used in expressions -just like variables, but they cannot be redeclared or assigned to. There is no -restriction against unknown or partially known arguments. Thus the -definition\index{midpoint?\texttt{midpoint}} +The keyword {\tt expr}\index{expr?\texttt{expr}}\index{parameter!expr} +in the macro definition means that the parameters can be expressions of +any type. When the definition specifies {\tt (expr z, d)}, the formal +parameters {\tt z} and {\tt d} behave like variables of the appropriate +types. Within the \tdescr{replacement text}, they can be used in +expressions just like variables, but they cannot be redeclared or +assigned to. There is no restriction against unknown or partially known +arguments. Thus the definition\index{midpoint?\texttt{midpoint}} $$ \hbox{\tt def midpoint(expr a, b) = (.5[a,b]) enddef} $$ works perfectly well when {\tt a} and {\tt b} are unknown. An equation such as $$ \hbox{\tt midpoint(z1,z2) = (1,1)} $$ could be used to help determine {\tt z1} and {\tt z2}. -Notice that the above definition for {\tt midpoint} works for numerics, pairs, -or colors as long as both parameters have the same type. If for some reason we -want a {\tt middlepoint}\index{middlepoint?\texttt{middlepoint}} macro that works for -a single path or picture, it would be -necessary to do an {\tt if}\index{if?\texttt{if}} test on the argument type. This uses -the fact there is a unary operator\index{path?\texttt{path}} +Notice that the above definition for {\tt midpoint} works for numerics, +pairs, or colors as long as both parameters have the same type. If for +some reason we want a {\tt +middlepoint}\index{middlepoint?\texttt{middlepoint}} macro that works +for a single path or picture, it would be necessary to do an {\tt +if}\index{if?\texttt{if}} test on the argument type. This uses the fact +there is a unary operator\index{path?\texttt{path}} $$ {\tt path}\, \descr{primary} $$ -that returns a boolean result indicating whether its argument is a path. Since -the basic {\tt if} test has the syntax\index{else?\texttt{else}}\index{fi?\texttt{fi}} +that returns a boolean result indicating whether its argument is a path. +Since the basic {\tt if} test has the +syntax\index{else?\texttt{else}}\index{fi?\texttt{fi}} $$ {\tt if}\, \descr{boolean expression}\hbox{\tt:}\, \descr{balanced tokens}\, \hbox{\tt else:}\, \descr{balanced tokens}\, {\tt fi} $$ -where the \tdescr{balanced tokens}\index{balanced tokens?\tdescr{balanced tokens}} can be anything -that is balanced with respect to {\tt if} and {\tt fi}, the complete -{\tt middlepoint}\index{midpoint?\texttt{midpoint}} macro with type test looks like this: +where the \tdescr{balanced tokens}\index{balanced +tokens?\tdescr{balanced tokens}} can be anything that is balanced with +respect to {\tt if} and {\tt fi}, the complete {\tt +middlepoint}\index{midpoint?\texttt{midpoint}} macro with type test +looks like this: $$\begin{verbatim} def middlepoint(expr a) = if path a: (point .5*length a of a) else: .5(llcorner a + urcorner a) fi enddef; @@ -2946,10 +3374,11 @@ to be shortened to\index{elseif?\texttt{elseif}} $$ \hbox{\tt if $e_1$: \ldots\ elseif $e_2$: \ldots\ else: \ldots\ fi} $$ where $e_1$ and $e_2$ represent boolean expressions. -Note that {\tt if} tests are not statements and the \tdescr{balanced tokens} in -the syntax rules can be any sequence of balanced tokens even if they do not form -a complete expression or statement. Thus we could have saved two tokens at the -expense of clarity by defining {\tt midpoint} like this: +Note that {\tt if} tests are not statements and the \tdescr{balanced +tokens} in the syntax rules can be any sequence of balanced tokens even +if they do not form a complete expression or statement. Thus we could +have saved two tokens at the expense of clarity by defining {\tt +midpoint} like this: $$\begin{verbatim} def midpoint(expr a) = if path a: (point .5*length a of else: .5(llcorner a + urcorner fi a) enddef; @@ -2969,10 +3398,11 @@ $\tt \qquad \;|\; elseif \descr{boolean expression} \hbox{\tt :} \label{syif} \end{figure} -The real purpose of macros and {\tt if} tests is to automate repetitive tasks and -allow important subtasks to be solved separately. For example, Figure~\ref{fig42} -uses macros \verb|draw_marked|, \verb|mark_angle|, and \verb|mark_rt_angle| to -mark lines and angles that appear in the figure. +The real purpose of macros and {\tt if} tests is to automate repetitive +tasks and allow important subtasks to be solved separately. For +example, Figure~\ref{fig42} uses macros \verb|draw_marked|, +\verb|mark_angle|, and \verb|mark_rt_angle| to mark lines and angles +that appear in the figure. \begin{figure}[htp] $$\begin{verbatim} @@ -3005,27 +3435,30 @@ mark_rt_angle(z.p, z0, a); mark_rt_angle(z.p, z1, b); endfig; \end{verbatim} -\quad \mathcenter{\epsfbox{manfig.42}} +\quad \mathcenter{\includegraphics{manfig-42}} $$ \caption{MetaPost code and the corresponding figure} \label{fig42} \end{figure} -The task of the \verb|draw_marked|\index{draw_marked?\texttt{draw\_marked}} macro is to draw a path -with a given number of cross marks near its midpoint. A convenient starting place -is the subproblem of drawing a single cross mark perpendicular to a path {\tt p} -at some time {\tt t}. The \verb|draw_mark|\index{draw_mark?\texttt{draw\_mark}} macro in -Figure~\ref{drawmarked} does this by first finding a vector {\tt dm} perpendicular -to~{\tt p} at~{\tt t}. To simplify positioning the cross mark, -the \verb|draw_marked| macro is defined to take an arc length\index{arc length} -{\tt a} along {\tt p} and use the {\tt arctime}\index{arctime} operator to -compute~{\tt t} - -With the subproblem of drawing a single mark out of the way, the \verb|draw_marked| -macro only needs to draw the path and call \verb|draw_mark| with the appropriate -arc length values. The \verb|draw_marked| macro in Figure~\ref{drawmarked} -uses {\tt n} equally-spaced {\tt a} values centered on -{\tt .5*arclength~p}\index{arclength?\texttt{arclength}}. +The task of the +\verb|draw_marked|\index{draw_marked?\texttt{draw\_marked}} macro is to +draw a path with a given number of cross marks near its midpoint. A +convenient starting place is the subproblem of drawing a single cross +mark perpendicular to a path {\tt p} at some time {\tt t}. The +\verb|draw_mark|\index{draw_mark?\texttt{draw\_mark}} macro in +Figure~\ref{drawmarked} does this by first finding a vector {\tt dm} +perpendicular to~{\tt p} at~{\tt t}. To simplify positioning the cross +mark, the \verb|draw_marked| macro is defined to take an arc +length\index{arc length} {\tt a} along {\tt p} and use the {\tt +arctime}\index{arctime} operator to compute~{\tt t} + +With the subproblem of drawing a single mark out of the way, the +\verb|draw_marked| macro only needs to draw the path and call +\verb|draw_mark| with the appropriate arc length values. The +\verb|draw_marked| macro in Figure~\ref{drawmarked} uses {\tt n} +equally-spaced {\tt a} values centered on {\tt +.5*arclength~p}\index{arclength?\texttt{arclength}}. \begin{figure}[htp] $$\begin{verbatim} @@ -3057,17 +3490,20 @@ $$ \label{drawmarked} \end{figure} -Since \verb|draw_marked| works for curved lines, it can be used to draw the arcs -that the \verb|mark_angle|\index{mark_angle?\texttt{mark\_angle}} macro generates. Given points -{\tt a}, {\tt b}, and {\tt c} that define a counter-clockwise angle at {\tt b}, -the \verb|mark_angle| needs to generate a small arc from segment {\tt ba} to -segment {\tt bc}. The macro definition in Figure~\ref{markangle} does this by -creating an arc {\tt p} of radius one and then computing a scale factor {\tt s} -that makes it big enough to see clearly. - -The \verb|mark_rt_angle|\index{mark_rt_angle?\texttt{mark\_rt\_angle}} macro is much simpler. -It takes a generic right-angle corner and uses the {\tt zscaled}\index{zscaled?\texttt{zscaled}} -operator to rotate it and scale it as necessary. +Since \verb|draw_marked| works for curved lines, it can be used to draw +the arcs that the +\verb|mark_angle|\index{mark_angle?\texttt{mark\_angle}} macro +generates. Given points {\tt a}, {\tt b}, and {\tt c} that define a +counter-clockwise angle at {\tt b}, the \verb|mark_angle| needs to +generate a small arc from segment {\tt ba} to segment {\tt bc}. The +macro definition in Figure~\ref{markangle} does this by creating an arc +{\tt p} of radius one and then computing a scale factor {\tt s} that +makes it big enough to see clearly. + +The \verb|mark_rt_angle|\index{mark_rt_angle?\texttt{mark\_rt\_angle}} +macro is much simpler. It takes a generic right-angle corner and uses +the {\tt zscaled}\index{zscaled?\texttt{zscaled}} operator to rotate it +and scale it as necessary. \begin{figure}[htp] $$\begin{verbatim} @@ -3096,15 +3532,17 @@ $$ \subsection{Suffix and Text Parameters} -Macro parameters need not always be expressions as in the previous examples. -Replacing the keyword {\tt expr} with {\tt suffix}\index{suffix?\texttt{suffix}} or -{\tt text}\index{text?\texttt{text}} in a macro definition declares the parameters to be -variable names or arbitrary sequences of tokens. For example, there is a -predefined macro called {\tt hide}\index{hide?\texttt{hide}} that takes a -text parameter\index{parameter!text} and -interprets it as a sequence of statements while ultimately producing an empty -\tdescr{replacement text}. In other words, {\tt hide} executes its argument and -then gets the next token as if nothing happened. Thus +Macro parameters need not always be expressions as in the previous +examples. Replacing the keyword {\tt expr} with {\tt +suffix}\index{suffix?\texttt{suffix}} or {\tt +text}\index{text?\texttt{text}} in a macro definition declares the +parameters to be variable names or arbitrary sequences of tokens. For +example, there is a predefined macro called {\tt +hide}\index{hide?\texttt{hide}} that takes a text +parameter\index{parameter!text} and interprets it as a sequence of +statements while ultimately producing an empty \tdescr{replacement +text}. In other words, {\tt hide} executes its argument and then gets +the next token as if nothing happened. Thus $$ \hbox{\tt show hide(numeric a,b; a+b=3; a-b=1) a;} $$ prints ``\verb|>> 2|.'' @@ -3114,14 +3552,14 @@ def ignore(expr a) = enddef; def hide(text t) = ignore(begingroup t; 0 endgroup) enddef; \end{verbatim} $$ -The statements represented by the text parameter {\tt t} would be evaluated as part -of the group that forms the argument to {\tt ignore}. Since {\tt ignore} has an -empty \tdescr{replacement text}, expansion of the {\tt hide} macro ultimately -produces nothing. - -Another example of a predefined macro with a text parameter is -{\tt dashpattern}\index{dashpattern?\texttt{dashpattern}}. The definition of {\tt dashpattern} -starts +The statements represented by the text parameter {\tt t} would be +evaluated as part of the group that forms the argument to {\tt ignore}. +Since {\tt ignore} has an empty \tdescr{replacement text}, expansion of +the {\tt hide} macro ultimately produces nothing. + +Another example of a predefined macro with a text parameter is {\tt +dashpattern}\index{dashpattern?\texttt{dashpattern}}. The definition of +{\tt dashpattern} starts $$\begin{verbatim} def dashpattern(text t) = begingroup save on, off; @@ -3130,24 +3568,27 @@ $$ then it defines {\tt on} and {\tt off} to be macros that create the desired picture when the text parameter~{\tt t} appears in the replacement text. -Text parameters are very general, but their generality sometimes gets in the way. -If you just want to pass a variable name to a macro, it is better to declare it -as a suffix parameter\index{parameter!suffix}. For example,\index{incr?\texttt{incr}} +Text parameters are very general, but their generality sometimes gets in +the way. If you just want to pass a variable name to a macro, it is +better to declare it as a suffix parameter\index{parameter!suffix}. For +example,\index{incr?\texttt{incr}} $$ \hbox{\verb|def incr(suffix $) = begingroup $:=$+1; $ endgroup enddef;|} $$ defines a macro that will take any numeric variable, add one to it, and return the new value. Since variable names can be more than one token long, $$ \hbox{\tt incr(a3b)} $$ -is perfectly acceptable if {\tt a3b} is a numeric variable. -Suffix parameters are slightly more general than variable names because the -definition in Figure~\ref{syvar} allows a \tdescr{suffix}\index{suffix?\tdescr{suffix}} -to start with a \tdescr{subscript}\index{subscript?\tdescr{subscript}}. - -Figure~\ref{fig45} shows how suffix and expr parameters can be used together. -The {\tt getmid}\index{getmid?\texttt{getmid}} macro takes a path variable and creates arrays -of points and directions whose names are obtained by appending {\tt mid}, -{\tt off}, and {\tt dir} to the path variable. The {\tt joinup}\index{joinup?\texttt{joinup}} -macro takes arrays of points and directions and creates a path of length {\tt n} -that passes through each {\tt pt[i]} with direction {\tt d[i]} or +is perfectly acceptable if {\tt a3b} is a numeric variable. Suffix +parameters are slightly more general than variable names because the +definition in Figure~\ref{syvar} allows a +\tdescr{suffix}\index{suffix?\tdescr{suffix}} to start with a +\tdescr{subscript}\index{subscript?\tdescr{subscript}}. + +Figure~\ref{fig45} shows how suffix and expr parameters can be used +together. The {\tt getmid}\index{getmid?\texttt{getmid}} macro takes a +path variable and creates arrays of points and directions whose names +are obtained by appending {\tt mid}, {\tt off}, and {\tt dir} to the +path variable. The {\tt joinup}\index{joinup?\texttt{joinup}} macro +takes arrays of points and directions and creates a path of length {\tt +n} that passes through each {\tt pt[i]} with direction {\tt d[i]} or $-\hbox{\tt d[i]}$. \begin{figure}[htp] @@ -3189,7 +3630,7 @@ for i=0 upto 3: endfor endfig; \end{verbatim} -\quad \mathcenter{\epsfbox{manfig.45}} +\quad \mathcenter{\includegraphics{manfig-45}} $$ \caption{MetaPost code and the corresponding figure} \label{fig45} @@ -3202,11 +3643,11 @@ parentheses as in $$ \hbox{\tt joinup(p.mid, p.dir)(36)} $$ instead of $$ \hbox{\tt joinup(p.mid, p.dir, 36)} $$ -In fact, both forms are acceptable. Parameters in a macro call can be separated -by commas or by {\tt )(} pairs. The only restriction is that a -text parameter\index{parameter!text} -must be followed by a right parenthesis. For instance, a macro {\tt foo} with one -text parameter and one expr parameter can be called +In fact, both forms are acceptable. Parameters in a macro call can be +separated by commas or by {\tt )(} pairs. The only restriction is that +a text parameter\index{parameter!text} must be followed by a right +parenthesis. For instance, a macro {\tt foo} with one text parameter +and one expr parameter can be called $$ \hbox{\tt foo(a,b)(c)} $$ in which case the text parameter is ``{\tt a,b}'' and the expr parameter is {\tt c}, but @@ -3217,79 +3658,86 @@ still looking for the expr parameter. \subsection{Vardef Macros} -A macro definition can begin with {\tt vardef}\index{vardef?\texttt{vardef}} instead of -{\tt def}. Macros defined in this way are called vardef macros. They are -particularly well-suited to applications where macros are being used like functions -or subroutines. The main idea is that a vardef macro is like a variable of type -``macro.'' +A macro definition can begin with {\tt +vardef}\index{vardef?\texttt{vardef}} instead of {\tt def}. Macros +defined in this way are called vardef macros. They are particularly +well-suited to applications where macros are being used like functions +or subroutines. The main idea is that a vardef macro is like a variable +of type ``macro.'' Instead of {\tt def} \tdescr{symbolic token}, a vardef macro begins $$ {\tt vardef}\, \descr{generic variable} $$ -where a \tdescr{generic variable}\index{generic variable?\tdescr{generic variable}} is a variable -name with numeric subscripts replaced by the -generic subscript\index{subscript!generic} symbol {\tt []}\index{[]?\texttt{[]}}. -In other words, the name following {\tt vardef} obeys exactly the same syntax as -the name given in a variable declaration. It is a sequence of tags and generic -subscript symbols starting with a tag, where a tag\index{tags} is a symbolic token -that is not a macro or a primitive operator as explained in Section~\ref{vardecl}. - -The simplest case is when the name of a vardef macro consists of a single tag. -Under such circumstances, {\tt def} and {\tt vardef} provide roughly the same -functionality. The most obvious difference is that -{\tt begingroup}\index{begingroup?\texttt{begingroup}} and {\tt endgroup}\index{endgroup?\texttt{endgroup}} -are automatically inserted at the beginning and end of the -\tdescr{replacement text} of every vardef macro. This makes the -\tdescr{replacement text} a group so that a vardef -macro behaves like a subroutine or a function call. +where a \tdescr{generic variable}\index{generic variable?\tdescr{generic +variable}} is a variable name with numeric subscripts replaced by the +generic subscript\index{subscript!generic} symbol {\tt +[]}\index{[]?\texttt{[]}}. In other words, the name following {\tt +vardef} obeys exactly the same syntax as the name given in a variable +declaration. It is a sequence of tags and generic subscript symbols +starting with a tag, where a tag\index{tags} is a symbolic token that is +not a macro or a primitive operator as explained in +Section~\ref{vardecl}. + +The simplest case is when the name of a vardef macro consists of a +single tag. Under such circumstances, {\tt def} and {\tt vardef} +provide roughly the same functionality. The most obvious difference is +that {\tt begingroup}\index{begingroup?\texttt{begingroup}} and {\tt +endgroup}\index{endgroup?\texttt{endgroup}} are automatically inserted +at the beginning and end of the \tdescr{replacement text} of every +vardef macro. This makes the \tdescr{replacement text} a group so that +a vardef macro behaves like a subroutine or a function call. Another property of vardef macros is that they allow multi-token macro -names and macro names involving generic subscripts. -When a vardef macro name has generic subscripts, numeric values have to be given -when the macro is called. After a macro definition +names and macro names involving generic subscripts. When a vardef macro +name has generic subscripts, numeric values have to be given when the +macro is called. After a macro definition $$ \hbox{\tt vardef a[]b(expr p) =}\, \descr{replacement text}\, \hbox{\tt enddef;} $$ -{\tt a2b((1,2))} and {\tt a3b((1,2)..(3,4))} are macro calls. But how can the -\tdescr{replacement text} tell the difference between {\tt a2b} and {\tt a3b}? -Two implicit suffix parameters\index{parameter!suffix} are automatically -provided for this purpose. -Every vardef macro has suffix parameters \verb|#@|\index{#@?\texttt{\#@}} -and \verb|@|\index{@?\texttt{@}}, where \verb|@| is the last token in the name from the -macro call and \verb|#@| is everything preceding the last token. Thus \verb|#@| -is {\tt a2} when the name is given as {\tt a2b} and {\tt a3} when the name is -given as {\tt a3b}. - -Suppose, for example, that the {\tt a[]b} macro is to take its argument and -shift it by an amount that depends on the macro name. The macro could be defined -like this: +{\tt a2b((1,2))} and {\tt a3b((1,2)..(3,4))} are macro calls. But how +can the \tdescr{replacement text} tell the difference between {\tt a2b} +and {\tt a3b}? Two implicit suffix parameters\index{parameter!suffix} +are automatically provided for this purpose. Every vardef macro has +suffix parameters \verb|#@|\index{#@?\texttt{\#@}} and +\verb|@|\index{@?\texttt{@}}, where \verb|@| is the last token in the +name from the macro call and \verb|#@| is everything preceding the last +token. Thus \verb|#@| is {\tt a2} when the name is given as {\tt a2b} +and {\tt a3} when the name is given as {\tt a3b}. + +Suppose, for example, that the {\tt a[]b} macro is to take its argument +and shift it by an amount that depends on the macro name. The macro +could be defined like this: $$ \hbox{\verb|vardef a[]b(expr p) = p shifted (#@,b) enddef;|} $$ Then {\tt a2b((1,2))} means {\tt (1,2) shifted (a2,b)} and {\tt a3b((1,2)..(3,4))} means $$ \hbox{\tt ((1,2)..(3,4)) shifted (a3,b)}. $$ -If the macro had been {\tt a.b[]}, \verb|#@| would always be {\tt a.b} and the -\verb|@| parameter would give the numeric subscript. Then {\tt a@} would refer to -an element of the array {\tt a[]}. Note that \verb|@| is a suffix parameter, not -an expr parameter, so an expression like {\tt @+1} would be illegal. The only way -to get at the numeric values of subscripts in a -suffix parameter\index{parameter!suffix} is by extracting -them from the string returned by the {\tt str}\index{str?\texttt{str}}\label{Dstr} -operator. This operator takes a suffix and returns a string -representation of a suffix. Thus {\tt str @} would be \verb|"3"| in {\tt a.b3} -and \verb|"3.14"| in {\tt a.b3.14} or {\tt a.b[3.14]}. Since the syntax for a -\tdescr{suffix}\index{suffix?\tdescr{suffix}} in Figure~\ref{syvar} requires negative -subscripts to be in brackets, {\tt str @} returns {\tt "[-3]"} in {\tt a.b[-3]}. - -The {\tt str} operator is generally for emergency use only. It is better to -use suffix parameters only as variable names or suffixes. The best example of a -vardef macro involving suffixes is the {\tt z} macro that defines the -{\tt z} convention\index{z convention?{\tt z} convention}. The definition involves a special -token \verb|@#|\index{@#?\texttt{@\#}} that refers to the suffix following the macro name: +If the macro had been {\tt a.b[]}, \verb|#@| would always be {\tt a.b} +and the \verb|@| parameter would give the numeric subscript. Then {\tt +a@} would refer to an element of the array {\tt a[]}. Note that +\verb|@| is a suffix parameter, not an expr parameter, so an expression +like {\tt @+1} would be illegal. The only way to get at the numeric +values of subscripts in a suffix parameter\index{parameter!suffix} is by +extracting them from the string returned by the {\tt +str}\index{str?\texttt{str}}\label{Dstr} operator. This operator takes +a suffix and returns a string representation of a suffix. Thus {\tt str +@} would be \verb|"3"| in {\tt a.b3} and \verb|"3.14"| in {\tt a.b3.14} +or {\tt a.b[3.14]}. Since the syntax for a +\tdescr{suffix}\index{suffix?\tdescr{suffix}} in Figure~\ref{syvar} +requires negative subscripts to be in brackets, {\tt str @} returns {\tt +"[-3]"} in {\tt a.b[-3]}. + +The {\tt str} operator is generally for emergency use only. It is +better to use suffix parameters only as variable names or suffixes. The +best example of a vardef macro involving suffixes is the {\tt z} macro +that defines the {\tt z} convention\index{z convention?{\tt z} +convention}. The definition involves a special token +\verb|@#|\index{@#?\texttt{@\#}} that refers to the suffix following the +macro name: $$ \hbox{\verb|vardef z@#=(x@#,y@#) enddef;|} $$ -This means that any variable name whose first token is {\tt z} is equivalent to -a pair of variables whose names are obtained by replacing {\tt z} with {\tt x} -and~{\tt y}. For instance, {\tt z.a1} calls the {\tt z} macro with the suffix -parameter \verb|@#| set to {\tt a1}. +This means that any variable name whose first token is {\tt z} is +equivalent to a pair of variables whose names are obtained by replacing +{\tt z} with {\tt x} and~{\tt y}. For instance, {\tt z.a1} calls the +{\tt z} macro with the suffix parameter \verb|@#| set to {\tt a1}. In general, $$ {\tt vardef}\, \descr{generic variable} \hbox{\verb|@#|} $$ @@ -3298,19 +3746,21 @@ MetaPost interpreter to look for a suffix following the name given in the macro call and makes this available as the \verb|@#| suffix parameter. -To summarize the special features of vardef macros, they allow a broad class of -macro names as well as macro names followed by a special suffix parameter. -Furthermore, {\tt begingroup} and {\tt endgroup} are automatically added to the -\tdescr{replacement text} of a vardef macro. Thus using {\tt vardef} -instead of {\tt def} to define the {\tt joinup}\index{joinup?\texttt{joinup}} macro in -Figure~\ref{fig45} would have avoided the need to include {\tt begingroup} and -{\tt endgroup} explicitly in the macro definition. - -In fact, most of the macro definitions given in previous examples could equally -well use {\tt vardef} instead of {\tt def}. It usually does not matter very much -which you use, but a good general rule is to use {\tt vardef} if you intend the -macro to be used like a function or a subroutine. The following comparison -should help in deciding when to use {\tt vardef}. +To summarize the special features of vardef macros, they allow a broad +class of macro names as well as macro names followed by a special suffix +parameter. Furthermore, {\tt begingroup} and {\tt endgroup} are +automatically added to the \tdescr{replacement text} of a vardef macro. +Thus using {\tt vardef} instead of {\tt def} to define the {\tt +joinup}\index{joinup?\texttt{joinup}} macro in Figure~\ref{fig45} would +have avoided the need to include {\tt begingroup} and {\tt endgroup} +explicitly in the macro definition. + +In fact, most of the macro definitions given in previous examples could +equally well use {\tt vardef} instead of {\tt def}. It usually does not +matter very much which you use, but a good general rule is to use {\tt +vardef} if you intend the macro to be used like a function or a +subroutine. The following comparison should help in deciding when to +use {\tt vardef}. \begin{itemize} \item Vardef macros are automatically surrounded by {\tt begingroup} @@ -3320,29 +3770,32 @@ contain subscripts. \item A vardef macro can have access to the suffix that follows the macro name when the macro is called. \item When a symbolic token is used in the name of a vardef macro it remains -a tag\index{tags} and can still be used in other variable names. Thus {\tt p5dir} -is a legal variable name even though {\tt dir} is a vardef macro, but an ordinary -macro such as {\tt ...}\index{...?\texttt{...}} cannot be used in a variable name. -(This is fortunate since {\tt z5...z6} is supposed to be a path expression, not -an elaborate variable name). +a tag\index{tags} and can still be used in other variable names. Thus +{\tt p5dir} is a legal variable name even though {\tt dir} is a vardef +macro, but an ordinary macro such as {\tt ...}\index{...?\texttt{...}} +cannot be used in a variable name. (This is fortunate since {\tt +z5...z6} is supposed to be a path expression, not an elaborate variable +name). \end{itemize} \subsection{Defining Unary and Binary Macros} -It has been mentioned several times that some of the operators and commands -discussed so far are actually predefined macros. These include unary operators -such as {\tt round}\index{round?\texttt{round}} and {\tt unitvector}\index{unitvector?\texttt{unitvector}}, -statements such as {\tt fill}\index{fill?\texttt{fill}} and {\tt draw}\index{draw?\texttt{draw}}, -and binary operators such as {\tt dotprod}\index{dotprod?\texttt{dotprod}} and -{\tt intersectionpoint}\index{intersectionpoint?\texttt{intersectionpoint}}. The main difference -between these macros and the ones we already know how to define is their argument -syntax. +It has been mentioned several times that some of the operators and +commands discussed so far are actually predefined macros. These include +unary operators such as {\tt round}\index{round?\texttt{round}} and {\tt +unitvector}\index{unitvector?\texttt{unitvector}}, statements such as +{\tt fill}\index{fill?\texttt{fill}} and {\tt +draw}\index{draw?\texttt{draw}}, and binary operators such as {\tt +dotprod}\index{dotprod?\texttt{dotprod}} and {\tt +intersectionpoint}\index{intersectionpoint?\texttt{intersectionpoint}}. +The main difference between these macros and the ones we already know +how to define is their argument syntax. The {\tt round} and {\tt unitvector} macros are examples of what -Figure~\ref{syexpr} calls \tdescr{unary op}. That is, they are followed by a -primary expression. To specify a macro argument of this type, the macro definition -should look like this: +Figure~\ref{syexpr} calls \tdescr{unary op}. That is, they are followed +by a primary expression. To specify a macro argument of this type, the +macro definition should look like this: $$ \hbox{\tt vardef round primary u =}\, \descr{replacement text}\, \hbox{\tt enddef;} $$ @@ -3354,14 +3807,16 @@ syntax. As the {\tt round} example suggests, a macro can be defined to take a \tdescr{secondary}\index{secondary?\tdescr{secondary}}, \tdescr{tertiary}\index{tertiary?\tdescr{tertiary}}, or an -\tdescr{expression}\index{expression?\tdescr{expression}} parameter. For example, the -predefined definition of the {\tt fill} macro is roughly\index{fill?\texttt{fill}} +\tdescr{expression}\index{expression?\tdescr{expression}} parameter. +For example, the predefined definition of the {\tt fill} macro is +roughly\index{fill?\texttt{fill}} $$ \hbox{\tt def fill expr c = addto currentpicture contour c enddef;} $$ -It is even possible to define a macro to play the role of -\tdescr{of operator}\index{of operator?\tdescr{of operator}} in Figure~\ref{syexpr}. -For example, the {\tt direction of}\index{direction of?\texttt{direction of}} macro has a definition -of this form: +It is even possible to define a macro to play the role of \tdescr{of +operator}\index{of operator?\tdescr{of operator}} in +Figure~\ref{syexpr}. For example, the {\tt direction +of}\index{direction of?\texttt{direction of}} macro has a definition of +this form: $$ \hbox{\tt vardef direction expr t of p =}\, \descr{replacement text}\, \hbox{\tt enddef;} $$ @@ -3372,25 +3827,28 @@ form\index{dotprod?\texttt{dotprod}}\index{primarydef?\texttt{primarydef}} $$ \hbox{\tt primarydef w dotprod z =}\, \descr{replacement text}\, \hbox{\tt enddef;} $$ -This makes {\tt dotprod} a \tdescr{primary binop}\index{primary binop?\tdescr{primary binop}}. -Similarly, {\tt secondarydef}\index{secondarydef?\texttt{secondarydef}} and -{\tt tertiarydef}\index{tertiarydef?\texttt{tertiarydef}} introduce -\tdescr{secondary binop}\index{secondary binop?\tdescr{secondary binop}} and -\tdescr{tertiary binop}\index{tertiary binop?\tdescr{tertiary binop}} definitions. These all -define ordinary macros, not vardef macros; e.g., there is -no ``{\tt primaryvardef}.'' +This makes {\tt dotprod} a \tdescr{primary binop}\index{primary +binop?\tdescr{primary binop}}. Similarly, {\tt +secondarydef}\index{secondarydef?\texttt{secondarydef}} and {\tt +tertiarydef}\index{tertiarydef?\texttt{tertiarydef}} introduce +\tdescr{secondary binop}\index{secondary binop?\tdescr{secondary binop}} +and \tdescr{tertiary binop}\index{tertiary binop?\tdescr{tertiary +binop}} definitions. These all define ordinary macros, not vardef +macros; e.g., there is no ``{\tt primaryvardef}.'' Thus macro definitions can be introduced by {\tt def}, {\tt vardef}, -{\tt primarydef}, {\tt secondarydef}, or {\tt tertiarydef}. -A \tdescr{replacement text}\index{replacement text?\tdescr{replacement text}} is any list of tokens -that is balanced with respect to {\tt def}-{\tt enddef} pairs where all five macro -definition tokens are treated like {\tt def} for the purpose of -{\tt def}-{\tt enddef} matching. - -The rest of the syntax for macro definitions is summarized in Figure~\ref{symacro}. -The syntax contains a few surprises. The macro parameters can have a -\tdescr{delimited part} and an \tdescr{undelimited part}. Normally, one of -these is \tdescr{empty}, but it is possible to have both parts nonempty: +{\tt primarydef}, {\tt secondarydef}, or {\tt tertiarydef}. A +\tdescr{replacement text}\index{replacement text?\tdescr{replacement +text}} is any list of tokens that is balanced with respect to {\tt +def}-{\tt enddef} pairs where all five macro definition tokens are +treated like {\tt def} for the purpose of {\tt def}-{\tt enddef} +matching. + +The rest of the syntax for macro definitions is summarized in +Figure~\ref{symacro}. The syntax contains a few surprises. The macro +parameters can have a \tdescr{delimited part} and an \tdescr{undelimited +part}. Normally, one of these is \tdescr{empty}, but it is possible to +have both parts nonempty: $$ \hbox{\tt def foo(text a) expr b =}\, \descr{replacement text}\, \hbox{\tt enddef;} $$ @@ -3429,34 +3887,38 @@ $\tt \descr{binary def} \rightarrow primarydef \;|\; secondarydef \;|\; \label{symacro} \end{figure} -The syntax also allows the \tdescr{undelimited part} to specify an argument type -of {\tt suffix}\index{suffix?\texttt{suffix}} or {\tt text}\index{text?\texttt{text}}. An example of -a macro with an undelimited suffix parameter\index{parameter!suffix} -is the predefined macro {\tt incr}\index{incr?\texttt{incr}}\label{Dincr} that is actually +The syntax also allows the \tdescr{undelimited part} to specify an +argument type of {\tt suffix}\index{suffix?\texttt{suffix}} or {\tt +text}\index{text?\texttt{text}}. An example of a macro with an +undelimited suffix parameter\index{parameter!suffix} is the predefined +macro {\tt incr}\index{incr?\texttt{incr}}\label{Dincr} that is actually defined like this: $$ \hbox{\verb|vardef incr suffix $ = $:=$+1; $ enddef;|} $$ -This makes {\tt incr} a function that takes a variable, increments it, and -returns the new value. Undelimited suffix parameters may be parenthesized, -so {\tt incr a} and {\tt incr(a)} are both legal if {\tt a} is a numeric -variable. There is also a similar predefined macro {\tt decr}\index{decr?\texttt{decr}} -that subtracts~1. - -Undelimited text parameters\index{parameter!text} run to the end of a statement. -More precisely, an undelimited text parameter is the list of tokens following the -macro call up to the first ``{\tt ;}\index{semicolon}'' or -``{\tt endgroup}\index{endgroup?\texttt{endgroup}}'' or ``{\tt end}\index{end?\texttt{end}}'' -except that an argument containing ``{\tt begingroup}'' will always -include the matching ``{\tt endgroup}.'' -An example of an undelimited text parameter comes from the predefined macro -{\tt cutdraw}\index{cutdraw?\texttt{cutdraw}}\label{Dctdraw} whose definition is +This makes {\tt incr} a function that takes a variable, increments it, +and returns the new value. Undelimited suffix parameters may be +parenthesized, so {\tt incr a} and {\tt incr(a)} are both legal if {\tt +a} is a numeric variable. There is also a similar predefined macro {\tt +decr}\index{decr?\texttt{decr}} that subtracts~1. + +Undelimited text parameters\index{parameter!text} run to the end of a +statement. More precisely, an undelimited text parameter is the list of +tokens following the macro call up to the first ``{\tt +;}\index{semicolon}'' or ``{\tt +endgroup}\index{endgroup?\texttt{endgroup}}'' or ``{\tt +end}\index{end?\texttt{end}}'' except that an argument containing ``{\tt +begingroup}'' will always include the matching ``{\tt endgroup}.'' An +example of an undelimited text parameter comes from the predefined macro +{\tt cutdraw}\index{cutdraw?\texttt{cutdraw}}\label{Dctdraw} whose +definition is roughly\index{linecap?\texttt{linecap}}\index{butt?\texttt{butt}}\index{interim?\texttt{interim}} $$\begin{verbatim} def cutdraw text t = begingroup interim linecap:=butt; draw t; endgroup enddef; \end{verbatim} $$ -This makes {\tt cutdraw} synonymous with {\tt draw} except for the {\tt linecap} -value. (This macro is provided mainly for compatibility with \MF\index{metafont?\MF}.) +This makes {\tt cutdraw} synonymous with {\tt draw} except for the {\tt +linecap} value. (This macro is provided mainly for compatibility with +\MF\index{metafont?\MF}.) \section{Loops} @@ -3467,38 +3929,43 @@ $$ {\tt for}\, \descr{symbolic token}\, \hbox{\tt =}\, \descr{expression}\, {\tt upto}\, \descr{expression}:\ \descr{loop text}\, {\tt endfor} $$ -It is equally simple to construct a loop that counts downward: just replace -{\tt upto} by {\tt downto}\index{downto?\texttt{downto}}\label{Ddwnto} -make the second \tdescr{expression} smaller than the first. -This section covers more complicated types of progressions, loops where the loop -counter behaves like a suffix parameter, and ways of exiting from a loop. - -The first generalization is suggested by the fact that {\tt upto}\index{upto?\texttt{upto}} -is a predefined macro for\index{step?\texttt{step}}\index{until?\texttt{until}} +It is equally simple to construct a loop that counts downward: just +replace {\tt upto} by {\tt +downto}\index{downto?\texttt{downto}}\label{Ddwnto} make the second +\tdescr{expression} smaller than the first. This section covers more +complicated types of progressions, loops where the loop counter behaves +like a suffix parameter, and ways of exiting from a loop. + +The first generalization is suggested by the fact that {\tt +upto}\index{upto?\texttt{upto}} is a predefined macro +for\index{step?\texttt{step}}\index{until?\texttt{until}} $$ \hbox{\tt step 1 until} $$ -and {\tt downto}\index{downto?\texttt{downto}} is a macro for {\tt step -1 until}. -A loop begining +and {\tt downto}\index{downto?\texttt{downto}} is a macro for {\tt step +-1 until}. A loop begining $$ \hbox{\tt for i=a step b until c} $$ -scans a sequence of {\tt i} values {\tt a}, ${\tt a}+{\tt b}$, ${\tt a}+2{\tt b}$, -\ldots, stopping before {\tt i} passes {\tt c}; i.e., the loop scans {\tt i} values -where ${\tt i}\le {\tt c}$ if ${\tt b}>0$ and ${\tt i}\ge {\tt c}$ if ${\tt i}<0$. - -It is best to use this feature only when the step size is an integer or some -number that can be represented exactly in fixed point arithmetic\index{arithmetic} -as a multiple of $1\over65536$. Otherwise, error will accumulate and the loop -index might not reach the expected termination value. For instance, +scans a sequence of {\tt i} values {\tt a}, ${\tt a}+{\tt b}$, ${\tt +a}+2{\tt b}$, \ldots, stopping before {\tt i} passes {\tt c}; i.e., the +loop scans {\tt i} values where ${\tt i}\le {\tt c}$ if ${\tt b}>0$ and +${\tt i}\ge {\tt c}$ if ${\tt i}<0$. + +It is best to use this feature only when the step size is an integer or +some number that can be represented exactly in fixed point +arithmetic\index{arithmetic} as a multiple of $1\over65536$. Otherwise, +error will accumulate and the loop index might not reach the expected +termination value. For instance, $$ \hbox{\tt for i=0 step .1 until 1: show i; endfor} $$ shows ten {\tt i} values the last of which is 0.90005. -The standard way of avoid the problems associated with non-integer step sizes is -to iterate over integer values and then multiply by a scale factor when using -the loop index as was done in Figures \ref{fig1} and~\ref{fig40}. +The standard way of avoid the problems associated with non-integer step +sizes is to iterate over integer values and then multiply by a scale +factor when using the loop index as was done in Figures \ref{fig1} +and~\ref{fig40}. -Alternatively, the values to iterate over can be given explicitly. Any sequence -of zero or more expressions separated by commas can be used in place of -{\tt a step b upto c}. In fact, the expressions need not all be the same type -and they need not have known values. Thus -$$ \hbox{\tt for t=3.14, 2.78, (a,2a), "hello": show a; endfor} $$ +Alternatively, the values to iterate over can be given explicitly. Any +sequence of zero or more expressions separated by commas can be used in +place of {\tt a step b upto c}. In fact, the expressions need not all +be the same type and they need not have known values. Thus +$$ \hbox{\tt for t=3.14, 2.78, (a,2a), "hello": show t; endfor} $$ shows the four values listed. Note that the loop body in the above example is a statement followed by a @@ -3511,22 +3978,23 @@ is equivalent to $$ \hbox{\tt draw (3,1)--(6,2)--(7,5)--(4,6)--(1,3)--cycle;} $$ (See Figure~\ref{fig17} for a more realistic example of this.) -If a loop is like a macro definition, the loop index is like an -expr parameter\index{parameter!expr}. It can represent any value, but it is +If a loop is like a macro definition, the loop index is like an expr +parameter\index{parameter!expr}. It can represent any value, but it is not a variable and it cannot be changed by an assignment -statement\index{assignment}. In order to do that, you need a -{\tt forsuffixes}\index{forsuffixes?\texttt{forsuffixes}} loop. A {\tt forsuffixes} loop is -a lot like a {\tt for} loop, except the loop index behaves like a -suffix parameter\index{parameter!suffix}. The syntax is +statement\index{assignment}. In order to do that, you need a {\tt +forsuffixes}\index{forsuffixes?\texttt{forsuffixes}} loop. A {\tt +forsuffixes} loop is a lot like a {\tt for} loop, except the loop index +behaves like a suffix parameter\index{parameter!suffix}. The syntax is $$ {\tt forsuffixes}\, \descr{symbolic token}\, \hbox{\tt =}\, \descr{suffix list}:\ \descr{loop text}\, {\tt endfor} $$ -where a \tdescr{suffix list} is a comma-separated list of suffixes. -If some of the suffixes are \tdescr{empty}, the \tdescr{loop text} gets executed -with the loop index parameter set to the empty suffix. +where a \tdescr{suffix list} is a comma-separated list of suffixes. If +some of the suffixes are \tdescr{empty}, the \tdescr{loop text} gets +executed with the loop index parameter set to the empty suffix. -A good example of a {\tt forsuffixes} loop is the definition of the -{\tt dotlabels}\index{dotlabels?\texttt{dotlabels}} macro\index{str?\texttt{str}}: +A good example of a {\tt forsuffixes} loop is the definition of the {\tt +dotlabels}\index{dotlabels?\texttt{dotlabels}} +macro\index{str?\texttt{str}}: $$\begin{verbatim} vardef dotlabels@#(text t) = forsuffixes $=t: dotlabel@#(str$,z$); endfor enddef; @@ -3544,10 +4012,11 @@ $$ {\tt forever}\hbox{\tt :}\, \descr{loop text}\, {\tt endfor} $$ To terminate such a loop when a boolean condition becomes true, use an exit clause\index{exitif?\texttt{exitif}}: $$ {\tt exitif}\, \descr{boolean expression} \hbox{\tt ;} $$ -When the MetaPost interpreter encounters an exit clause, it evaluates the -\tdescr{boolean expression} and exits the current loop if the expression is -true. If it is more convenient to exit the loop when an expression becomes false, -use the predefined macro {\tt exitunless}\index{exitunless?\texttt{exitunless}}. +When the MetaPost interpreter encounters an exit clause, it evaluates +the \tdescr{boolean expression} and exits the current loop if the +expression is true. If it is more convenient to exit the loop when an +expression becomes false, use the predefined macro {\tt +exitunless}\index{exitunless?\texttt{exitunless}}. Thus MetaPost's version of a {\bf while} loop is $$ \hbox{\tt forever: exitunless}\, \descr{boolean expression} \hbox{\tt ;}\, @@ -3558,10 +4027,11 @@ in the \tdescr{loop text}. In fact any {\tt for}, {\tt forever}, or {\tt forsuffixes} loop can contain any number of exit clauses. The summary of loop syntax shown in Figure~\ref{syloop} does not mention -exit clauses explicitly because a \tdescr{loop text} can be virtually any -sequence of tokens. The only restriction is that a \tdescr{loop text} must -be balanced with respect to {\tt for} and {\tt endfor}. Of course this balancing -process treats {\tt forsuffixes} and {\tt forever} just like {\tt for}. +exit clauses explicitly because a \tdescr{loop text} can be virtually +any sequence of tokens. The only restriction is that a \tdescr{loop +text} must be balanced with respect to {\tt for} and {\tt endfor}. Of +course this balancing process treats {\tt forsuffixes} and {\tt forever} +just like {\tt for}. \begin{figure}[htp] \begin{ctabbing} @@ -3593,16 +4063,16 @@ $\tt \descr{suffix list} \rightarrow \descr{suffix} \section{Making Boxes} \label{boxessec} -This section describes auxiliary macros not included in Plain MetaPost that -make it convenient to do things that {\it pic} is good at \cite{ke:pic}. What -follows is a description of how to use the macros contained in the -file {\tt boxes.mp}\index{boxes.mp?\texttt{boxes.mp}}. This file is included in a special -directory reserved for MetaPost macros and support software\footnote{The name -of this directory is likely to be something like \verb|/usr/lib/mp/lib|, but -this is system dependent.} -and can be accessed by giving the MetaPost command {\tt input boxes} before any -figures that use the box making macros. -The syntax for the {\tt input} command is \index{input?\texttt{input}} +This section describes auxiliary macros not included in Plain MetaPost +that make it convenient to do things that {\it pic} is good at +\cite{ke:pic}. What follows is a description of how to use the macros +contained in the file {\tt boxes.mp}\index{boxes.mp?\texttt{boxes.mp}}. +This file is included in a special directory reserved for MetaPost +macros and support software\footnote{The name of this directory is +likely to be something like \verb|/usr/lib/mp/lib|, but this is system +dependent.} and can be accessed by giving the MetaPost command {\tt +input boxes} before any figures that use the box making macros. The +syntax for the {\tt input} command is \index{input?\texttt{input}} $$ {\tt input}\, \descr{file name} $$ where a final ``{\tt .mp}'' can be omitted from the file name. The {\tt input} command looks first in the current directory and then in the special macro @@ -3628,39 +4098,42 @@ The argument to {\tt drawboxed} should be a comma-separated list of box names, where a box name\index{box name} is a \tdescr{suffix} with which {\tt boxit} has been called. -For the command {\tt boxit.bb(pic)}, the box name is {\tt bb} and the contents -of the box is the picture {\tt pic}. In this case, {\tt bb.c} the position -where the center of picture {\tt pic} is to be placed, and {\tt bb.sw}, -{\tt bb.se}, {\tt bb.ne}, and {\tt bb.nw} are the corners of a rectangular path -that will surround the resulting picture. Variables {\tt bb.dx} and {\tt bb.dy} -give the spacing between the shifted version of {\tt pic} and the surrounding -rectangle, and {\tt bb.off} is the amount by which {\tt pic} has to be shifted -to achieve all this. - -When the {\tt boxit} macro is called with box name~$b$, it gives linear equations -that force $b${\tt.sw}, $b${\tt.se}, $b${\tt.ne}, and $b${\tt.nw} to be the -corners of a rectangle -aligned on the $x$ and $y$ axes with the box contents centered inside as -indicated by the gray rectangle in Figure~\ref{fig48}. The values of $b${\tt.dx}, -$b${\tt.dy}, and $b${\tt.c} are left unspecified so that the user can give -equations for positioning the boxes. If no such equations are given, macros -such as {\tt drawboxed} can detect this and give default values. -The default values for {\tt dx} and {\tt dy} variables are controlled by the -internal variables\index{internal variables}\index{variables!internal} -{\tt defaultdx}\index{defaultdx?\texttt{defaultdx}}\label{Ddefaultdx} and +For the command {\tt boxit.bb(pic)}, the box name is {\tt bb} and the +contents of the box is the picture {\tt pic}. In this case, {\tt bb.c} +the position where the center of picture {\tt pic} is to be placed, and +{\tt bb.sw}, {\tt bb.se}, {\tt bb.ne}, and {\tt bb.nw} are the corners +of a rectangular path that will surround the resulting picture. +Variables {\tt bb.dx} and {\tt bb.dy} give the spacing between the +shifted version of {\tt pic} and the surrounding rectangle, and {\tt +bb.off} is the amount by which {\tt pic} has to be shifted to achieve +all this. + +When the {\tt boxit} macro is called with box name~$b$, it gives linear +equations that force $b${\tt.sw}, $b${\tt.se}, $b${\tt.ne}, and +$b${\tt.nw} to be the corners of a rectangle aligned on the $x$ and $y$ +axes with the box contents centered inside as indicated by the gray +rectangle in Figure~\ref{fig48}. The values of $b${\tt.dx}, +$b${\tt.dy}, and $b${\tt.c} are left unspecified so that the user can +give equations for positioning the boxes. If no such equations are +given, macros such as {\tt drawboxed} can detect this and give default +values. The default values for {\tt dx} and {\tt dy} variables are +controlled by the internal variables\index{internal +variables}\index{variables!internal} {\tt +defaultdx}\index{defaultdx?\texttt{defaultdx}}\label{Ddefaultdx} and {\tt defaultdy}\index{defaultdy?\texttt{defaultdy}}\label{Ddefaultdy}. \begin{figure}[htp] -$$ \epsfbox{manfig.48} $$ +$$ \includegraphics{manfig-48} $$ \caption[How a {\tt boxit} picture relates to the associated variables] {The relationship between the picture given to {\tt boxit} and the associated variables. The picture is indicated by a gray rectangle.} \label{fig48} \end{figure} -If $b$ represents a box name, {\tt drawboxed($b$)} draws the rectangular boundary -of box~$b$ and then the contents of the box. This bounding rectangle can be -accessed separately as {\tt bpath~b}, or in general\index{bpath?\texttt{bpath}}\label{Dbpath} +If $b$ represents a box name, {\tt drawboxed($b$)} draws the rectangular +boundary of box~$b$ and then the contents of the box. This bounding +rectangle can be accessed separately as {\tt bpath~$b$}, or in +general\index{bpath?\texttt{bpath}}\label{Dbpath} $$ {\tt bpath}\, \descr{box name} $$ It is useful in combination with operators like {\tt cutbefore}\index{cutbefore?\texttt{cutbefore}} and {\tt cutafter}\index{cutafter?\texttt{cutafter}} @@ -3670,10 +4143,11 @@ to $b${\tt.c},\index{drawarrow?\texttt{drawarrow}} $$ \hbox{\tt drawarrow $p$ cutbefore bpath $a$ cutafter bpath $b$} $$ draws an arrow from the edge of box $a$ to the edge of box $b$. -Figure~\ref{fig49} shows a practical example including some arrows drawn with -{\tt cutafter bpath} \tdescr{box name}. It is -instructive to compare Figure~\ref{fig49} to the similar figure in the pic -manual \cite{ke:pic}. The figure uses a macro\index{boxjoin?\texttt{boxjoin}}\label{Dbxjoin} +Figure~\ref{fig49} shows a practical example including some arrows drawn +with {\tt cutafter bpath} \tdescr{box name}. It is instructive to +compare Figure~\ref{fig49} to the similar figure in the pic manual +\cite{ke:pic}. The figure uses a +macro\index{boxjoin?\texttt{boxjoin}}\label{Dbxjoin} $$ \hbox{\tt boxjoin(} \descr{equation text} \hbox{\tt )} $$ to control the relationship between consecutive boxes. Within the \tdescr{equation text}, {\tt a} and {\tt b} represent the box names given in @@ -3719,7 +4193,7 @@ drawarrow subpath (0,.7) of (z.ptr..{left}ndc3.c) dashed evenly; label.rt(btex \strut ndblock etex, z.ptr); endfig; \end{verbatim} $} -\atop \vcenter{\vskip8pt\hbox{\epsfbox{manfig.49}}} +\atop \vcenter{\vskip8pt\hbox{\includegraphics{manfig-49}}} $$ \caption{MetaPost code and the corresponding figure} \label{fig49} @@ -3735,43 +4209,47 @@ $$ \hbox{\tt a.se=ni.sw; a.ne=ni.nw} $$ The next pair of boxes is box~{\tt ni} and box~{\tt di}. This time the implicitly generated equations are $$ \hbox{\tt ni.se=di.sw; ni.ne=di.nw} $$ -This process continues until a new {\tt boxjoin}\index{boxjoin?\texttt{boxjoin}} is given. -In this case the new declaration is +This process continues until a new {\tt +boxjoin}\index{boxjoin?\texttt{boxjoin}} is given. In this case the new +declaration is $$ \hbox{\tt boxjoin(a.sw=b.nw; a.se=b.ne)} $$ which causes boxes to be stacked below each other. -After calling {\tt boxit} for the first eight boxes {\tt a} through {\tt dk}, -the box heights are constrained to match but the widths are still unknown. -Thus the {\tt drawboxed}\index{drawboxed?\texttt{drawboxed}} macro needs to assign default -values to the \tdescr{box name}{\tt.dx} and \tdescr{box name}{\tt.dy} -variables. First, {\tt di.dx} and {\tt di.dy} get default values so that all -the boxes are forced to be large enough to contain the contents of box~{\tt di}. - -The macro that actually assigns default values to {\tt dx} and {\tt dy} variables -is called {\tt fixsize}\index{fixsize?\texttt{fixsize}}\label{Dfixsiz}. -It takes a list of box names and -considers them one at a time, making sure that each box has a fixed size and -shape. A macro called {\tt fixpos}\index{fixpos?\texttt{fixpos}}\label{Dfixpos} then takes -this same list -of box names and assigns default values to the \tdescr{box name}{\tt.off} -variables as needed to fix the position of each box. By using {\tt fixsize} -to fix the dimensions of each box before assigning default positions to any -of them, the number of needing default positions can usually be cut to at most -one. - -Since the bounding path for a box cannot be computed until the size, shape, and -position of the box is determined, the {\tt bpath}\index{bpath?\texttt{bpath}} macro applies -{\tt fixsize} and {\tt fixpos} to its argument. Other macros that do this +After calling {\tt boxit} for the first eight boxes {\tt a} through {\tt +dk}, the box heights are constrained to match but the widths are still +unknown. Thus the {\tt drawboxed}\index{drawboxed?\texttt{drawboxed}} +macro needs to assign default values to the \tdescr{box name}{\tt.dx} +and \tdescr{box name}{\tt.dy} variables. First, {\tt di.dx} and {\tt +di.dy} get default values so that all the boxes are forced to be large +enough to contain the contents of box~{\tt di}. + +The macro that actually assigns default values to {\tt dx} and {\tt dy} +variables is called {\tt +fixsize}\index{fixsize?\texttt{fixsize}}\label{Dfixsiz}. It takes a +list of box names and considers them one at a time, making sure that +each box has a fixed size and shape. A macro called {\tt +fixpos}\index{fixpos?\texttt{fixpos}}\label{Dfixpos} then takes this +same list of box names and assigns default values to the \tdescr{box +name}{\tt.off} variables as needed to fix the position of each box. By +using {\tt fixsize} to fix the dimensions of each box before assigning +default positions to any of them, the number of needing default +positions can usually be cut to at most one. + +Since the bounding path for a box cannot be computed until the size, +shape, and position of the box is determined, the {\tt +bpath}\index{bpath?\texttt{bpath}} macro applies {\tt fixsize} and {\tt +fixpos} to its argument. Other macros that do this include\index{pic?\texttt{pic}}\label{Dpic} $$ {\tt pic}\, \descr{box name} $$ where the \tdescr{box name} is a suffix, possibly in parentheses. This returns the contents of the named box as a picture positioned so that $$ {\tt draw\ pic} \descr{box name} $$ -draws the box contents without the bounding rectangle. This operation can also -be accomplished by the {\tt drawunboxed}\index{drawunboxed?\texttt{drawunboxed}}\label{Ddrunbx} +draws the box contents without the bounding rectangle. This operation +can also be accomplished by the {\tt +drawunboxed}\index{drawunboxed?\texttt{drawunboxed}}\label{Ddrunbx} macro that takes a comma-separated list of box names. There is also a -{\tt drawboxes}\index{drawboxes?\texttt{drawboxes}}\label{Ddrbxes} macro that draws just the -bounding rectangles. +{\tt drawboxes}\index{drawboxes?\texttt{drawboxes}}\label{Ddrbxes} macro +that draws just the bounding rectangles. Another way to draw empty rectangles is by just saying\label{Deboxit} $$ {\tt boxit} \descr{box name} \hbox{\tt ()} $$ @@ -3797,29 +4275,30 @@ The {\tt circleit} macro defines pair variable just as {\tt boxit} does, except that there are no corner points \tdescr{box name}{\tt.ne}, \tdescr{box name}{\tt.sw}, etc. A call to $$ \hbox{\tt circleit.a(}\ldots \hbox{\tt )} $$ -gives relationships among points {\tt a.c}, {\tt a.s}, -{\tt a.e}, {\tt a.n}, {\tt a.w} -and distances {\tt a.dx} and {\tt a.dy}. Together with {\tt a.c} and {\tt a.off}, -these variables describe how the picture is centered in an oval as can be seen -from the Figure~\ref{fig50}. +gives relationships among points {\tt a.c}, {\tt a.s}, {\tt a.e}, {\tt +a.n}, {\tt a.w} and distances {\tt a.dx} and {\tt a.dy}. Together with +{\tt a.c} and {\tt a.off}, these variables describe how the picture is +centered in an oval as can be seen from the Figure~\ref{fig50}. \begin{figure}[htp] -$$ \epsfbox{manfig.50} $$ +$$ \includegraphics{manfig-50} $$ \caption[How a {\tt circleit} picture relates to the associated variables] {The relationship between the picture given to {\tt circleit} and the associated variables. The picture is indicated by a gray rectangle.} \label{fig50} \end{figure} -The {\tt drawboxed}\index{drawboxed?\texttt{drawboxed}}, {\tt drawunboxed}\index{drawunboxed?\texttt{drawunboxed}}, -{\tt drawboxes}\index{drawboxes?\texttt{drawboxes}}, {\tt pic}\index{pic?\texttt{pic}}, and -{\tt bpath}\index{bpath?\texttt{bpath}} macros work for {\tt circleit} boxes just as they do -for {\tt boxit} boxes. By default, the boundary path for a {\tt circleit} box is -a circle large enough to surround the box contents with a small safety margin -controlled by the -internal variable\index{internal variables}\index{variables!internal} -{\tt circmargin}\label{Dcmargin}. Figure~\ref{fig51} gives -a basic example of the use of {\tt bpath} with {\tt circleit} boxes. +The {\tt drawboxed}\index{drawboxed?\texttt{drawboxed}}, {\tt +drawunboxed}\index{drawunboxed?\texttt{drawunboxed}}, {\tt +drawboxes}\index{drawboxes?\texttt{drawboxes}}, {\tt +pic}\index{pic?\texttt{pic}}, and {\tt +bpath}\index{bpath?\texttt{bpath}} macros work for {\tt circleit} boxes +just as they do for {\tt boxit} boxes. By default, the boundary path +for a {\tt circleit} box is a circle large enough to surround the box +contents with a small safety margin controlled by the internal +variable\index{internal variables}\index{variables!internal} {\tt +circmargin}\label{Dcmargin}. Figure~\ref{fig51} gives a basic example +of the use of {\tt bpath} with {\tt circleit} boxes. \begin{figure}[htbp] $$\begin{verbatim} @@ -3840,10 +4319,10 @@ drawshadowed(a,b); drawarrow a.s -- b.n; endfig; \end{verbatim} -\qquad \mathcenter{\epsfbox{manfig.51}} $$ -\caption[MetaPost code and the resulting figure.] - {MetaPost code and the resulting figure. Note that the {\tt drawshadowed} - macro used here is not part of the {\tt boxit.mp} macro package.} +\qquad \mathcenter{\includegraphics{manfig-51}} $$ +\caption[MetaPost code and the resulting figure.] {MetaPost code and + the resulting figure. Note that the {\tt drawshadowed} macro + used here is not part of the {\tt boxes.mp} macro package.} \label{fig51} \index{drawshadowed?\texttt{drawshadowed}} \end{figure} @@ -3856,10 +4335,11 @@ $$ \hbox{\verb|circleit.ee(btex\strut Stop etex)|} \quad{\rm and}\quad \hbox{\verb|circleit.ee(btex\strut Stop etex)|}. $$ -The general rule is that {\tt bpath.}$c$ comes out circular if $c${\tt.dx}, -$c${\tt.dy}, and $c\hbox{\tt.dx}-c\hbox{\tt.dy}$ are all unknown. Otherwise, the -macros select an oval big enough to contain the given picture with the safety -margin {\tt circmargin}\index{circmargin?\texttt{circmargin}}. +The general rule is that {\tt bpath.}$c$ comes out circular if +$c${\tt.dx}, $c${\tt.dy}, and $c\hbox{\tt.dx}-c\hbox{\tt.dy}$ are all +unknown. Otherwise, the macros select an oval big enough to contain the +given picture with the safety margin {\tt +circmargin}\index{circmargin?\texttt{circmargin}}. \begin{figure}[htp] @@ -3897,7 +4377,7 @@ label.urt(btex$b$etex, cuta(ee,cc) ee.c{(cc.c-ee.c)rotated-15}..cc.c); endfig; \end{verbatim} $} -\atop \vcenter{\vskip8pt\hbox{\epsfbox{manfig.52}}} +\atop \vcenter{\vskip8pt\hbox{\includegraphics{manfig-52}}} $$ \caption{MetaPost code and the corresponding figure} \label{fig52} @@ -3905,24 +4385,150 @@ $$ \end{figure} +\section{Utility Routines} + +\index{utility routines} +\index{mplib?\texttt{mplib}} +\index{metapost/base?\texttt{metapost/base}} + +This section describes some of the utility routines included in the +\texttt{mplib} directory of the development source hierarchy. Future +versions of this documentation may include more; meanwhile, please read +the source files, most have explanatory comments at the top. They are +also included in the MetaPost and larger \TeX\ distributions, typically +in a \texttt{texmf/metapost/base} directory. + + +\subsection{\texttt{TEX.mp}} + +\label{dTEX} +\index{TEX.mp?\texttt{TEX.mp}} +\index{labels, with variable text} +\index{string expressions, as labels} + +\texttt{TEX.mp} provides a way to typeset the text of a MetaPost string +expression. Suppose, for example, you need labels of the form $n_0$, +$n_1$, \ldots, $n_{10}$ across the $x$ axis. You can do this (relatively) +conveniently with \texttt{TEX.mp}, as follows: +$$\begin{verbatim} +input TEX; +beginfig(100) + last := 10; + for i := 0 upto last: + label(TEX("$n_{" & decimal(i) & "}$"), (5mm*i,0)); + endfor + ... +endfig; +\end{verbatim} +$$ +In contrast, the basic \texttt{btex} command (see p.\ \pageref{Dbtex}) +typesets verbatim text. That is, \texttt{btex~s~etex} typesets the +literal character `s'; \texttt{TEX(s)} typesets the value of the +MetaPost text variable~$s$. + +\index{latex?\LaTeX, typesetting labels with} In version 0.9, +\texttt{TEX.mp} acquired two additional routines to facilitate using +\LaTeX\ to typeset labels: \texttt{TEXPRE} and \texttt{TEXPOST}. Their +values are remembered, and included before and after (respectively) each +call to \texttt{TEX}. Otherwise, each \texttt{TEX} call is effectively +typeset independently. \texttt{TEX} calls also do not interfere with +uses of \ttindex{verbatimtex} (p.\ \pageref{Dverbatimtex}). + +Here's the same example as above, using the \LaTeX\ commands \verb|\(| +and \verb|\)|: + +$$\begin{verbatim} +input TEX; +TEXPRE("%&latex" & char(10) & "\documentclass{article}\begin{document}"); +TEXPOST("\end{document}"); +beginfig(100) + last := 10; + for i := 0 upto last: + label(TEX("\( n_{" & decimal(i) & "} \)"), (5mm*i,0)); + endfor + ... +endfig; +\end{verbatim} +$$ +Explanation: +\begin{itemize} + +\item +The \texttt{\%\&latex} causes \LaTeX\ to be invoked instead of \TeX. +(See below, also.) Web2C- and MiKTeX-based \TeX\ implementations, at +least, understand this \texttt{\%\&} specification; see, e.g., the Web2C +documentation for details, \url{http://tug.org/web2c}. (Information on +how to do the same with other systems would be most welcome.) + +\item +The \texttt{char(10)} puts a newline (ASCII character code 10, decimal) +in the output. + +\item +The \verb|\documentclass...| is the usual way to start a \LaTeX\ +document. + +\item +The \verb|TEXPOST("\end{document}")| is not strictly necessary, due to +the behavior of \texttt{mpto}, but it is safer to include it. + +\end{itemize} + +Unfortunately, \TeX\ \verb|\special| instructions vanish in this +process. So it is not possible to use packages such as \texttt{xcolor} +and \texttt{hyperref}. + +In case you're curious, these routines are implemented very simply: they +write \texttt{btex} commands to a temporary file and then use +\texttt{scantokens} (p.\ \pageref{Dscantokens}) to process it. The +\texttt{makempx} mechanism (p.\ \pageref{Dmakempx}) does all the work of +running \TeX. + +The \verb|%&| magic on the first line is not the only way to specify +invoking a different program than (plain) \TeX. It has the advantage of +maximum flexibility: different \texttt{TEX} constructs can use different +\TeX\ processors. But at least two other methods are possible: + +\begin{itemize} +\item Set the environment variable \texttt{TEX} to \texttt{latex}---or +whatever processor you want to invoke. (To handle \ConTeXt\ fragments, +\ttt{texexec} could be used.) This might be convenient when writing a +script, or working on a project that always requires \texttt{latex}. + +\item Invoke MetaPost with the command-line option \ttt{-tex=latex} (or +whatever processor, of course). This might be useful from a Makefile, +or just a one-off run. +\end{itemize} + +\subsection{\texttt{mproof.tex}} + +\index{mproof.tex?\texttt{mproof.tex}} + +\texttt{mproof.tex} is a (plain) \TeX\ routine, not MetaPost at all. It +writes a proof sheet for MetaPost output. Call it like this: + +$$\hbox{\tt tex mproof {\sl MetaPost-output-filename}}$$ +Then process the resulting \texttt{dvi} file as usual. + \section{Debugging} -MetaPost inherits from \MF\index{metafont?\MF} numerous facilities for interactive -debugging, most of which can only be mentioned briefly here. Further information -on error messages, debugging, and generating tracing information can be found in -{\it The\ \MF book} \cite{kn:c}. +MetaPost inherits from \MF\index{metafont?\MF} numerous facilities for +interactive debugging, most of which can only be mentioned briefly here. +Further information on error messages, debugging, and generating tracing +information can be found in {\sl The\ \MF book} \cite{kn:c}. Suppose your input file says $$ \hbox{\tt draw z1--z2;} $$ on line 17 without first giving known values to {\tt z1} and {\tt z2}. -Figure~\ref{errmsg} shows what the MetaPost interpreter prints on your terminal -when it finds the error. The actual error message is the line beginning with -``{\tt !}''; the next six lines give the context that shows exactly what input -was being read when the error was found; and the ``{\tt ?}'' on last line is a -prompt for your response. Since the error message talks about an undefined -$x$~coordinate, this value is printed on the first line after the ``{\tt >>}''. -In this case the $x$~coordinate of {\tt z1} is just the unknown variable {\tt x1}, -so the interpreter prints the variable name {\tt x1} just as it would if it +Figure~\ref{errmsg} shows what the MetaPost interpreter prints on your +terminal when it finds the error. The actual error message is the line +beginning with ``{\tt !}''; the next six lines give the context that +shows exactly what input was being read when the error was found; and +the ``{\tt ?}'' on last line is a prompt for your response. Since the +error message talks about an undefined $x$~coordinate, this value is +printed on the first line after the ``{\tt >>}''. In this case the +$x$~coordinate of {\tt z1} is just the unknown variable {\tt x1}, so the +interpreter prints the variable name {\tt x1} just as it would if it were told to\index{show?\texttt{show}} ``{\tt show x1}'' at this point. \begin{figure}[htp] @@ -3949,35 +4555,36 @@ Each line of input is printed on two lines like this: \descr{descriptor}\ \hbox{Text read so far} \\ && \hbox{Text yet to be read} \end{eqnarray*} -The \tdescr{descriptor} identifies the input source. It is either a line number -like ``{\tt l.17}'' for line 17 of the current file; or it can be a macro name -followed by ``{\tt ->}''; or it is a descriptive phrase in angle brackets. -Thus, the meaning of the context listing in Figure~\ref{errmsg} is that the -interpreter has just read line 17 of the input file up to ``{\tt --},'' the -expansion of the {\tt --} macro has just started, and the initial -``\verb|{|'' has been reinserted to allow for user input before scanning -this token. +The \tdescr{descriptor} identifies the input source. It is either a +line number like ``{\tt l.17}'' for line 17 of the current file; or it +can be a macro name followed by ``{\tt ->}''; or it is a descriptive +phrase in angle brackets. Thus, the meaning of the context listing in +Figure~\ref{errmsg} is that the interpreter has just read line 17 of the +input file up to ``{\tt --},'' the expansion of the {\tt --} macro has +just started, and the initial ``\verb|{|'' has been reinserted to allow +for user input before scanning this token. Among the possible responses to a {\tt ?} prompt are the following: \begin{description} -\item[x] terminates the run so that you can fix you input file and start over. +\item[x] terminates the run so that you can fix your input file and start over. \item[h] prints a help message followed by another {\tt ?} prompt. \item[\tdescr{return}] causes the interpreter to proceed as best it can. \item[?] prints a listing of the options available, followed by another {\tt ?} prompt. \end{description} -Error messages and responses to {\tt show} commands are also written into the -transcript\index{files!transcript} file whose name is obtained from the name -of the main input file by changing ``{\tt .mp}'' to ``{\tt .log}''. When the -internal variable\index{internal variables}\index{variables!internal} -{\tt tracingonline}\index{tracingonline?\texttt{tracingonline}} is at its default -value of zero, some {\tt show} commands print their results in full detail only -in transcript file. +Error messages and responses to {\tt show} commands are also written +into the transcript\index{files!transcript} file whose name is obtained +from the name of the main input file by changing ``{\tt .mp}'' to ``{\tt +.log}''. When the internal variable\index{internal +variables}\index{variables!internal} {\tt +tracingonline}\index{tracingonline?\texttt{tracingonline}} is at its +default value of zero, some {\tt show} commands print their results in +full detail only in the transcript file. -Only one type of {\tt show}\index{show?\texttt{show}} command has been discussed so far: -{\tt show} followed by a comma-separated list of expressions prints symbolic -representations of the expressions. +Only one type of {\tt show}\index{show?\texttt{show}} command has been +discussed so far: {\tt show} followed by a comma-separated list of +expressions prints symbolic representations of the expressions. The {\tt showtoken}\index{showtoken?\texttt{showtoken}}\label{Dshtok} command can be used to show the @@ -3997,10 +4604,11 @@ one of the listed tokens. This even works for {\tt vardef} macros. For example, {\tt showvariable z} yields $$ \hbox{\verb|z@#=macro:->begingroup(x(SUFFIX2),y(SUFFIX2))endgroup|} $$ -There is also a {\tt showdependencies}\index{showdependencies?\texttt{showdependencies}}\label{Dshdep} -command that takes no arguments and prints a list of all {\em dependent} variables -and how the linear equations given so far make them depend on other variables. -Thus after +There is also a {\tt +showdependencies}\index{showdependencies?\texttt{showdependencies}}\label{Dshdep} +command that takes no arguments and prints a list of all {\em dependent} +variables and how the linear equations given so far make them depend on +other variables. Thus after $$ \hbox{\tt z2-z1=(5,10); z1+z2=(a,b);} $$ {\tt showdependencies} prints what is shown in Figure~\ref{shdep}. This could be useful in answering a question like ``What does it mean @@ -4019,30 +4627,29 @@ $$ \label{shdep} \end{figure} -When all else fails, the predefined macro -{\tt tracingall}\index{tracingall?\texttt{tracingall}}\label{Dtall} -causes the interpreter to print a detailed listing of everything it is doing. -Since the tracing information is often quite voluminous, it may be better to use -the {\tt loggingall}\index{loggingall?\texttt{loggingall}}\label{Dlogall} -macro that produces the same information -but only writes it in the transcript\index{files!transcript} file. There is also -a {\tt tracingnone}\index{tracingnone?\texttt{tracingnone}}\label{Dtnone} -macro that turns off all the tracing output. - -Tracing output is controlled by the set of -internal variables\index{internal variables}\index{variables!internal} -summarized below. -When any one of these variables is given a positive value, the corresponding form -of tracing is turned on. Here is the set of tracing variables and what happens -when each of them is positive: +When all else fails, the predefined macro {\tt +tracingall}\index{tracingall?\texttt{tracingall}}\label{Dtall} causes +the interpreter to print a detailed listing of everything it is doing. +Since the tracing information is often quite voluminous, it may be +better to use the {\tt +loggingall}\index{loggingall?\texttt{loggingall}}\label{Dlogall} macro +that produces the same information but only writes it in the +transcript\index{files!transcript} file. There is also a {\tt +tracingnone}\index{tracingnone?\texttt{tracingnone}}\label{Dtnone} macro +that turns off all the tracing output. + +Tracing output is controlled by the set of internal +variables\index{internal variables}\index{variables!internal} summarized +below. When any one of these variables is given a positive value, the +corresponding form of tracing is turned on. Here is the set of tracing +variables and what happens when each of them is positive: \begin{description} \item[{\tt tracingcapsules}]\index{tracingcapsules?\texttt{tracingcapsules}}\label{Dtcapsules}% shows the values of temporary quantities (capsules) when they become known. % \item[{\tt tracingchoices}]\index{tracingchoices?\texttt{tracingchoices}}\label{Dtchoices}% -shows the B\'ezier control\index{control points} points of each new path when they -are chosen. -% +shows the B\'ezier control\index{control points} points of each new path +when they are chosen. % \item[{\tt tracingcommands}]\index{tracingcommands?\texttt{tracingcommands}}\label{Dtcommands}% shows the commands before they are performed. A setting ${}>1$ also shows {\tt if}\index{if?\texttt{if}} tests and loops before they are expanded; @@ -4077,9 +4684,10 @@ MetaPost interpreter's limited resources were used. \section*{Acknowledgement} -I would like to thank Don Knuth for making this work possible by developing -\MF\ and placing it in the public domain. I am also indebted to him for helpful -suggestions, particularly with regard to the treatment of included \TeX\ material. +I would like to thank Don Knuth for making this work possible by +developing \MF\ and placing it in the public domain. I am also indebted +to him for helpful suggestions, particularly with regard to the +treatment of included \TeX\ material. \appendix @@ -4099,44 +4707,49 @@ suggestions, particularly with regard to the treatment of included \TeX\ materia \setcounter{totalnumber}{10} Tables \ref{ivartab}--\ref{pseudotab} summarize the built-in features of -Plain MetaPost and the features defined in the {\tt boxes.mp}\index{boxes.mp?\texttt{boxes.mp}} -macro file. As explained in Section~\ref{boxessec}, the {\tt boxes.mp} macro -file is not automatically preloaded and the macros defined there are not -accessible until you ask for them via the command\index{input?\texttt{input}} +Plain MetaPost and the features defined in the {\tt +boxes.mp}\index{boxes.mp?\texttt{boxes.mp}} macro file. As explained in +Section~\ref{boxessec}, the {\tt boxes.mp} macro file is not +automatically preloaded and the macros defined there are not accessible +until you ask for them via the command\index{input?\texttt{input}} $$ \hbox{\tt input boxes} $$ Features that depend on {\tt boxes.mp} are marked by \bx\ symbols. -Features from the Plain\index{Plain macros} macro package are marked are marked -by \pl\ symbols, and MetaPost primitives are not marked by \bx\ or \pl. -The distinction between primitives and plain macros can be ignored by the casual -user, but it is important to remember that features marked by a \bx\ can only -be used after reading in the {\tt boxes.mp}\index{boxes.mp?\texttt{boxes.mp}} macro file. - -The tables in this appendix give the name each feature, the page number where -it is explained, and a short description. A few features are not explained -elsewhere and have no page number listed. These features exist primarily for -compatibility with \MF\index{metafont?\MF} and are intended to be self-explanatory. -Certain other features from \MF\ are omitted entirely because they are of -limited interest to the MetaPost users and/or would require long explanations. -All of these are documented in {\it The \MF book} \cite{kn:c} as explained -in Appendix~\ref{MPvsMF}. +Features from the Plain\index{Plain macros} macro package are marked by +\pl\ symbols, and MetaPost primitives are not marked by \bx\ or \pl. +The distinction between primitives and plain macros can be ignored by +the casual user, but it is important to remember that features marked by +a \bx\ can only be used after reading in the {\tt +boxes.mp}\index{boxes.mp?\texttt{boxes.mp}} macro file. + +The tables in this appendix give the name of each feature, the page +number where it is explained, and a short description. A few features +are not explained elsewhere and have no page number listed. These +features exist primarily for compatibility with \MF\index{metafont?\MF} +and are intended to be self-explanatory. Certain other features from +\MF\ are omitted entirely because they are of limited interest to the +MetaPost users and/or would require long explanations. All of these are +documented in {\sl The \MF book} \cite{kn:c} as explained in +Appendix~\ref{MPvsMF}. Table~\ref{ivartab} lists internal variables that take on numeric values. Table~\ref{pvartab} lists predefined variables of other types. Table~\ref{consttab} lists predefined constants. Some of these are implemented as variables whose values are intended to be left unchanged. -Tables \ref{optabA}--\ref{optabD} summarize MetaPost operators and list the -possible argument and result types for each one. A ``--'' entry for the left -argument indicates a unary operator; ``--'' entries for both arguments indicate a -nullary operator. Operators that take suffix parameters are not listed in -these tables because they are treated as ``function-like macros''. +Tables \ref{optabA}--\ref{optabD} summarize MetaPost operators and list +the possible argument and result types for each one. A ``--'' entry for +the left argument indicates a unary operator; ``--'' entries for both +arguments indicate a nullary operator. Operators that take suffix +parameters are not listed in these tables because they are treated as +``function-like macros''. -The last two tables are Table~\ref{cmdtab} for commands and Table~\ref{pseudotab} -macros that behave like functions or procedures. Such macros take parenthesized -argument lists and/or suffix parameters, returning either a value whose type is -listed in the table, or nothing. The latter case is for macros that behave -like procedures. Their return values are listed as ``--''. +The last two tables are Table~\ref{cmdtab} for commands and +Table~\ref{pseudotab} macros that behave like functions or procedures. +Such macros take parenthesized argument lists and/or suffix parameters, +returning either a value whose type is listed in the table, or nothing. +The latter case is for macros that behave like procedures. Their return +values are listed as ``--''. The figures in this appendix present the syntax of the MetaPost language starting with expressions in Figures \ref{syexpr1}--\ref{sypseudo}. @@ -4151,7 +4764,7 @@ Figures \ref{syprog} and \ref{sycmds} give the syntax for MetaPost programs, including statements and commands. They do not mention loops\index{loops} and {\tt if}\index{if?\texttt{if}} tests because these constructions do not behave like statements. The syntax -given in Figures \ref{syexpr1}--\ref{pseudotab} applies to the result of +given in Figures \ref{syexpr1}--\ref{sycondloop} applies to the result of expanding all conditionals and loops. Conditionals and loops do have a syntax, but they deal with almost arbitrary sequences of tokens. Figure~\ref{sycondloop} specifies conditionals in terms of @@ -4180,6 +4793,8 @@ $$\begin{tabular}{|l|r|l|} clearance around contents of a circular or oval box\\\hline \tt day& --& the current day of the month\\\hline +\tt defaultcolormodel& --& + the initial color model (default: 5, rgb)\\\hline \bx\tt defaultdx& \pageref{Ddefaultdx}& usual horizontal space around box contents (default 3{\tt bp})\\\hline \bx\tt defaultdy& \pageref{Ddefaultdy}& @@ -4198,10 +4813,15 @@ $$\begin{tabular}{|l|r|l|} controls miter length as in PostScript\\\hline \tt month& --& the current month (e.g, 3 $\equiv$ March)\\\hline +\tt mpprocset& --& + \vtop{\hbox{set this to~1 if you want to include a PostScript +dictionary}\hbox{of abbreviations in the output}}\\\hline \tt pausing& --& ${}>0$ to display lines on the terminal before they are read\\\hline -\tt prologues& \pageref{Dprologs}& +\tt prologues& \pageref{Dprologues}& ${}>0$ to output conforming PostScript using built-in fonts\\\hline +\tt restoreclipcolor& --& + restore the graphics state after clip operations (default: 1)\\\hline \tt showstopping& --& ${}>0$ to stop after each {\tt show} command\\\hline \tt time& --& @@ -4230,6 +4850,8 @@ $$\begin{tabular}{|l|r|l|} ${}>0$ to show memory usage at end of job\\\hline \tt tracingtitles& --& ${}>0$ to show titles online when they appear\\\hline +\tt troffmode& \pageref{Dtroffmode}& + set to~1 if a {\tt -troff} or {\tt -T} option was given\\\hline \tt truecorners& \pageref{Dtruecorn}& ${}>0$ to make {\tt llcorner} etc. ignore {\tt setbounds}\\\hline \tt warningcheck& \pageref{Dwarncheck}& @@ -4322,6 +4944,8 @@ $$\begin{tabular}{|l|l|r|l|} {\tt linejoin} value for mitered joins [0]\\\hline \pl\tt mm& numeric& \pageref{Dmm}& One millimeter in {\tt bp} units [2.83464]\\\hline +\tt mpversion& string& \pageref{Dmpversion}& + MetaPost version number\\\hline \tt nullpicture& picture& \pageref{Dnlpic}& Empty picture\\\hline \pl\tt origin& pair& --& @@ -4378,13 +5002,13 @@ $$\begin{tabular}{|l|l|l|l|r|l|} Concatenation---works for paths $l\hbox{\tt\&}r$ if\\ & path& path& path& & $r$ starts exactly where the $l$ ends\\\hline -\tt \verb|*|& numeric& color& color& \pageref{Dmldiv}& +\tt \verb|*|& numeric& (cmyk)color& (cmyk)color& \pageref{Dmldiv}& Multiplication\\ & & numeric& numeric& & \\ & & pair& pair& & \\\hline -\tt \verb|*|& color& numeric& color& \pageref{Dmldiv}& +\tt \verb|*|& (cmyk)color& numeric& (cmyk)color& \pageref{Dmldiv}& Multiplication\\ & numeric& & numeric& & \\ @@ -4392,7 +5016,7 @@ $$\begin{tabular}{|l|l|l|l|r|l|} \\\hline \tt \verb|**|& numeric& numeric& numeric& \pageref{Dpow}& Exponentiation\\\hline -\tt \verb|+|& color& color& color& \pageref{Dadd}& +\tt \verb|+|& (cmyk)color& (cmyk)color& (cmyk)color& \pageref{Dadd}& Addition\\ & numeric& numeric& numeric& & \\ @@ -4402,19 +5026,19 @@ $$\begin{tabular}{|l|l|l|l|r|l|} Pythagorean addition $\sqrt{l^2+r^2}$\\\hline \tt \verb|+-+|& numeric& numeric& numeric& \pageref{Dpysub}& Pythagorean subtraction $\sqrt{l^2-r^2}$\\\hline -\tt \verb|-|& color& color& color& \pageref{Dadd}& +\tt \verb|-|& (cmyk)color& (cmyk)color& (cmyk)color& \pageref{Dadd}& Subtraction\\ & numeric& numeric& numeric& & \\ & pair& pair& pair& & \\\hline -\tt \verb|-|& --& color& color& \pageref{Dneg}& +\tt \verb|-|& --& (cmyk)color& (cmyk)color& \pageref{Dneg}& Negation\\ & & numeric& numeric& & \\ & & pair& pair& & \\\hline -\tt \verb|/|& color& numeric& color& \pageref{Dmldiv}& +\tt \verb|/|& (cmyk)color& numeric& (cmyk)color& \pageref{Dmldiv}& Division\\ & numeric& & numeric& & \\ @@ -4426,7 +5050,7 @@ $$\begin{tabular}{|l|l|l|l|r|l|} \\ \tt \verb|<>|& pair& pair& & & \\ -& color& color& & & +& (cmyk)color& (cmyk)color& & & \\ & transform& transform& & & \\\hline @@ -4452,6 +5076,8 @@ $$\begin{tabular}{|l|l|l|l|r|l|} box\\ & & pen& & & \\\hline +\tt \verb|blackpart|& --& cmykcolor& numeric& \pageref{Dcmykprt}& + Extract the fourth component\\\hline \tt \verb|bluepart|& --& color& numeric& \pageref{Drgbprt}& Extracts the third component\\\hline \tt \verb|boolean|& --& any& boolean& \pageref{Dboolop}& @@ -4486,6 +5112,10 @@ $$\begin{tabular}{|l|l|l|l|r|l|} \hline \tt \verb|char|& --& numeric& string& \pageref{Dchar}& Character with a given ASCII code\\\hline +\tt \verb|cmykcolor|& --& any& boolean& \pageref{Dccolrop}& + Is the expression of type cmykcolor?\\\hline +\tt \verb|colormodel|& --& image object& numeric& --& + What is the color model of the image object?\\\hline \tt \verb|color|& --& any& boolean& \pageref{Dcolrop}& Is the expression of type color?\\\hline \tt \verb|cosd|& --& numeric& numeric& \pageref{Dcosd}& @@ -4498,6 +5128,8 @@ $$\begin{tabular}{|l|l|l|l|r|l|} Left argument with part before the\\ & & & & & intersection dropped\\\hline +\tt \verb|cyanpart|& --& cmykcolor& numeric& \pageref{Dcmykprt}& + Extract the first component\\\hline \tt \verb|cycle|& --& path& boolean& \pageref{Dcycop}& Determines whether a path is cyclic\\\hline \tt \verb|decimal|& --& numeric& string& \pageref{Ddecop}& @@ -4526,6 +5158,8 @@ $$\begin{tabular}{|l|l|l|l|r|l|} The point size of a font\\\hline \tt \verb|greenpart|& --& color& numeric& \pageref{Drgbprt}& Extract the second component\\\hline +\tt \verb|greypart|& --& numeric& numeric& --& + Extract the first (only) component\\\hline \tt \verb|hex|& --& string& numeric& --& Interpret as a hexadecimal number\\\hline \tt \verb|infont|& string& string& picture& \pageref{Sinfont}& @@ -4560,6 +5194,8 @@ $$\begin{tabular}{|l|l|l|l|r|l|} \\ & & pen& & & \\\hline +\tt \verb|magentapart|& --& cmykcolor& numeric& \pageref{Dcmykprt}& + Extract the second component\\\hline \tt \verb|makepath|& --& pen& path& \pageref{Dmkpath}& Cyclic path bounding the pen shape\\\hline \tt \verb|makepen|& --& path& pen& \pageref{Dmkpen}& @@ -4598,7 +5234,7 @@ $$\begin{tabular}{|l|l|l|l|r|l|} \tt \verb|numeric|& --& any& boolean& \pageref{Dnumop}& Is the expression of type numeric?\\\hline \tt \verb|oct|& --& string& numeric& --& - Interpret a string as an octal number\\\hline + Interpret string as octal number\\\hline \tt \verb|odd|& --& numeric& boolean& --& Is the closest integer odd or even?\\\hline \tt \verb|or|& boolean& boolean& boolean& \pageref{Dor}& @@ -4625,12 +5261,14 @@ $$\begin{tabular}{|l|l|l|l|r|l|} Last B\'ezier control point on path\\ \tt \verb|of|& & & & & segment ending at the given time\\\hline -\tt \verb|redpart|& --& color& numeric& \pageref{Drgbprt}& +\tt \verb|redpart|& --& color& numeric& \pageref{Drgbprt}& Extract the first component\\\hline \tt \verb|reverse|& --& path& path& \pageref{Drevrse}& - `time'-reversed path with beginning\\ + `time'-reversed path, beginning\\ & & & & & swapped with ending\\\hline +\tt \verb|rgbcolor|& --& any& boolean& \pageref{Drcolrop}& + Is the expression of type color?\\\hline \tt \verb|rotated|& picture& numeric& picture& \pageref{Dtranop}& Rotate counterclockwise a given\\ & path& & path& & @@ -4642,27 +5280,32 @@ $$\begin{tabular}{|l|l|l|l|r|l|} & transform& & transform& & \\\hline \pl\tt \verb|round|& --& numeric& numeric& \pageref{Dround}& - round each component to the nearest\\ + round each component to the\\ & & pair& pair& & - integer\\\hline + nearest integer\\\hline \pl\tt \verb|rt|& --& numeric& numeric& \pageref{Drt}& Right side of current pen when\\ & & pair& pair& & centered at given coordinate(s)\\\hline \tt \verb|scaled|& picture& numeric& picture& \pageref{Dtranop}& - Scale all coordinates by the given\\ + Scale all coordinates by the\\ & path& & path& & - amount\\ + given amount\\ & pair& & pair& & \\ & pen& & pen& & \\ & transform& & transform& & \\\hline +\tt \verb|scantokens|& --& string& token sequence& \pageref{Dscantokens}& + Converts a string to a token or \\ +& & & & &token sequence. Provides string\\ +& & & & &to numeric conversion, etc. + \\\hline \tt \verb|shifted|& picture& pair& picture& \pageref{Dtranop}& - Add the given shift amount to each\\ + Add the given shift amount to\\ & path& & path& & - pair of coordinates\\ + each pair of coordinates\\ & pair& & pair& & \\ & pen& & pen& & @@ -4768,6 +5411,8 @@ $$\begin{tabular}{|l|l|l|l|r|l|} $t_{xx}$ entry in transformation matrix\\\hline \tt \verb|xypart|& --& transform& number& \pageref{Dtrprt}& $t_{xy}$ entry in transformation matrix\\\hline +\tt \verb|yellowpart|& --& cmykcolor& numeric& \pageref{Dcmykprt}& + Extract the third component\\\hline \tt \verb|ypart|& --& pair& number& \pageref{Dyprt}& $y$ or $t_y$ component\\ & & transform& & & @@ -4910,6 +5555,8 @@ $$\begin{tabular}{|l|l|l|r|l|} contents\\\hline \bx\tt \verb|drawboxes|& list of suffixes& --& \pageref{Ddrbxes}& Draw the named boxes\\\hline +\pl\tt \verb|drawdot|& pair& --& \pageref{Ddrawdot}& + Draw a dot at the given point\\\hline \pl\tt \verb|drawoptions|& drawing options& --& \pageref{Ddropts}& Set options for drawing commands\\\hline \bx\tt \verb|drawunboxed|& list of suffixes& --& \pageref{Ddrunbx}& @@ -4920,7 +5567,9 @@ $$\begin{tabular}{|l|l|l|r|l|} named boxes\\\hline \bx\tt \verb|fixsize|& list of suffixes& --& \pageref{Dfixsiz}& Solve for size of named boxes\\\hline -\pl\tt \verb|incr|& numeric variable& numeric& \pageref{Dincr}& +\pl\tt \verb|image|& string& picture& \pageref{Dimage}& + Return picture from text\\\hline +\pl\tt \verb|incr|& numeric variable& numeric& \pageref{Dincr}& Increment and return new value\\\hline \pl\tt \verb|label|& suffix, picture, pair& --& \pageref{Dlabel}& Draw picture near given point\\\hline @@ -5026,14 +5675,14 @@ $\tt $\\ $\tt \descr{nullary op} \rightarrow false \;|\; normaldeviate \;|\; nullpicture \;|\; pencircle$\\ $\tt \qquad \;|\; true \;|\; whatever$\\ $\tt \descr{unary op} \rightarrow \descr{type}$\\ -$\tt \qquad \;|\; abs \;|\; angle \;|\; arclength \;|\; ASCII \;|\; bbox \;|\; bluepart \;|\; bot \;|\; ceiling$\\ -$\tt \qquad \;|\; center \;|\; char \;|\; cosd \;|\; cycle \;|\; decimal \;|\; dir \;|\; floor \;|\; fontsize$\\ -$\tt \qquad \;|\; greenpart \;|\; hex \;|\; inverse \;|\; known \;|\; length \;|\; lft \;|\; llcorner$\\ -$\tt \qquad \;|\; lrcorner\;|\; makepath \;|\; makepen \;|\; mexp \;|\; mlog \;|\; not \;|\; oct \;|\; odd$\\ +$\tt \qquad \;|\; abs \;|\; angle \;|\; arclength \;|\; ASCII \;|\; bbox \;|\; blackpart \;|\; bluepart \;|\; bot \;|\; ceiling$\\ +$\tt \qquad \;|\; center \;|\; char \;|\; cosd \;|\; cyanpart \;|\; cycle \;|\; decimal \;|\; dir \;|\; floor \;|\; fontsize$\\ +$\tt \qquad \;|\; greenpart \;|\; greypart \;|\; hex \;|\; inverse \;|\; known \;|\; length \;|\; lft \;|\; llcorner$\\ +$\tt \qquad \;|\; lrcorner\;|\; magentapart \;|\; makepath \;|\; makepen \;|\; mexp \;|\; mlog \;|\; not \;|\; oct \;|\; odd$\\ $\tt \qquad \;|\; redpart \;|\; reverse \;|\; round \;|\; rt \;|\; sind \;|\; sqrt \;|\; top \;|\; ulcorner$\\ $\tt \qquad \;|\; uniformdeviate \;|\; unitvector \;|\; unknown \;|\; urcorner \;|\; xpart \;|\; xxpart$\\ -$\tt \qquad \;|\; xypart \;|\; ypart \;|\; yxpart \;|\; yypart$\\ -$\tt \descr{type} \rightarrow boolean \;|\; color \;|\; numeric \;|\; pair$\\ +$\tt \qquad \;|\; xypart \;|\; yellowpart \;|\; ypart \;|\; yxpart \;|\; yypart$\\ +$\tt \descr{type} \rightarrow boolean \;|\; cmykcolor \;|\; color \;|\; numeric \;|\; pair$\\ $\tt \qquad \;|\; path \;|\; pen \;|\; picture \;|\; string \;|\; transform$\\ $\tt \descr{primary binop} \rightarrow \hbox{\tt *} \;|\; \hbox{\tt /} \;|\; \hbox{\tt **} \;|\; and$\\ $\tt \qquad \;|\; dotprod \;|\; div \;|\; infont \;|\; mod$\\ @@ -5091,6 +5740,7 @@ $\tt \descr{on\hbox{\tt /}off clause} \rightarrow on \descr{numeric tertiary} \; \begin{figure}[htp] \begin{ctabbing} $\tt \descr{boolean expression} \rightarrow \descr{expression}$\\ +$\tt \descr{cmykcolor expression} \rightarrow \descr{expression}$\\ $\tt \descr{color expression} \rightarrow \descr{expression}$\\ $\tt \descr{numeric atom} \rightarrow \descr{atom}$\\ $\tt \descr{numeric expression} \rightarrow \descr{expression}$\\ @@ -5104,6 +5754,7 @@ $\tt \descr{path subexpression} \rightarrow \descr{subexpression}$\\ $\tt \descr{pen expression} \rightarrow \descr{expression}$\\ $\tt \descr{picture expression} \rightarrow \descr{expression}$\\ $\tt \descr{picture variable} \rightarrow \descr{variable}$\\ +$\tt \descr{rgbcolor expression} \rightarrow \descr{expression}$\\ $\tt \descr{string expression} \rightarrow \descr{expression}$\\ $\tt \descr{suffix parameter} \rightarrow \descr{parameter}$\\ $\tt \descr{transform primary} \rightarrow \descr{primary}$ @@ -5200,6 +5851,9 @@ $\tt \qquad \;|\; addto \descr{picture variable} contour \descr{path expression} $\tt \qquad \;|\; addto \descr{picture variable} doublepath \descr{path expression} \descr{option list}$\\ $\tt \descr{option list} \rightarrow \descr{empty} \;|\; \descr{drawing option} \descr{option list}$\\ $\tt \descr{drawing option} \rightarrow withcolor \descr{color expression}$\\ +$\tt \qquad \;|\; withrgcolor \descr{rgbcolor expression} \;|\; withcmykcolor \descr{cmykcolor expression}$\\ +$\tt \qquad \;|\; withgreyscale \descr{numeric expression} \;|\; withoutcolor$\\ +$\tt \qquad \;|\; withprescript \descr{string expression} \;|\; withpostscript \descr{string expression}$\\ $\tt \qquad \;|\; withpen \descr{pen expression} \;|\; dashed \descr{picture expression}$\\ $\tt $\\ $\tt \descr{drawing command} \rightarrow draw \descr{picture expression} \descr{option list}$\\ @@ -5212,6 +5866,12 @@ $\tt \descr{tracing command} \rightarrow tracingall \;|\; loggingall \;|\; traci \caption{The syntax for commands} \index{option list?\tdescr{option list}}\index{picture variable?\tdescr{picture variable}}% \label{sycmds} + +% is this really true? in practice, in real implementations? +%\bigskip +%By the way, the default for \ttindex{randomseed} is, in effect, +%$\textsl{day} + \textsl{time}*\epsilon$. Unfortunately, \textsl{time} +%is in minutes. \end{figure} \begin{figure}[htp] @@ -5245,23 +5905,24 @@ $\tt \descr{suffix list} \rightarrow \descr{suffix} \;|\; \descr{suffix list}\hb \setcounter{totalnumber}{\value{svtotnum}} -\section{MetaPost Versus METAFONT} +\section{MetaPost Versus \MF} \label{MPvsMF} -Since the \MF\index{metafont?\MF} and MetaPost languages have so much in common, expert -users of \MF\ will want to skip most of the explanations in this document and -concentrate on concepts that are unique to MetaPost. The comparisons in this -appendix are intended to help experts that are familiar with {\it The\ \MF book} -as well as other users that want to benefit from Knuth's more detailed -explanations \cite{kn:c}. - -Since \MF\ is intended for making \TeX\ fonts, it has a number of primitives for -generating the {\tt tfm}\index{tfm file?{\tt tfm} file}\index{files!tfm?{\tt tfm}} files that -\TeX\ needs for character dimensions, spacing information, -ligatures\index{ligatures} and kerning\index{kerning}. MetaPost can also be -used for generating fonts, and it also has \MF's primitives for making -{\tt tfm} files. These are listed in Table~\ref{tfmprim}. Explanations can be -found in the \MF\ documentation \cite{kn:c,kn:mf3} +Since the \MF\index{metafont?\MF} and MetaPost languages have so much in +common, expert users of \MF\ will want to skip most of the explanations +in this document and concentrate on concepts that are unique to +MetaPost. The comparisons in this appendix are intended to help experts +that are familiar with {\sl The\ \MF book} as well as other users that +want to benefit from Knuth's more detailed explanations \cite{kn:c}. + +Since \MF\ is intended for making \TeX\ fonts, it has a number of +primitives for generating the {\tt tfm}\index{tfm file?{\tt tfm} +file}\index{files!tfm?{\tt tfm}} files that \TeX\ needs for character +dimensions, spacing information, ligatures\index{ligatures} and +kerning\index{kerning}. MetaPost can also be used for generating fonts, +and it also has \MF's primitives for making {\tt tfm} files. These are +listed in Table~\ref{tfmprim}. Explanations can be found in the \MF\ +documentation \cite{kn:c,kn:mf3}. \begin{table}[htp] $$\begin{tabular}{|l|l|} \hline @@ -5284,25 +5945,27 @@ $$ \label{tfmprim} \end{table} -Even though MetaPost has the primitives for generating fonts, many of the -font-making primitives and internal variables that are part of Plain -\MF\index{metafont?\MF} are not defined in Plain MetaPost\index{Plain macros}. Instead, -there is a separate macro package called {\tt mfplain}\index{mfplain?\texttt{mfplain}} that -defines the macros required to allow MetaPost to process Knuth's Computer Modern -fonts as shown in Table~\ref{mfponly} \cite{kn:e}. -To load these macros, put ``\verb|&mfplain|'' before the name of the -input file. This can be done at the {\tt **} prompt after invoking the MetaPost -interpreter with no arguments, or on a command line that looks something like -this:\footnote{Command line syntax is system dependent. Quotes are needed on -most Unix\reg systems to protect special characters like {\tt\&}.} -$$ \hbox{\verb|mp '&mfplain' cmr10|} $$ +Even though MetaPost has the primitives for generating fonts, many of +the font-making primitives and internal variables that are part of Plain +\MF\index{metafont?\MF} are not defined in Plain MetaPost\index{Plain +macros}. Instead, there is a separate macro package called {\tt +mfplain}\index{mfplain?\texttt{mfplain}} that defines the macros +required to allow MetaPost to process Knuth's Computer Modern fonts as +shown in Table~\ref{mfponly} \cite{kn:e}. To load these macros, put +``\verb|&mfplain|'' before the name of the input file. This can be done +at the {\tt **} prompt after invoking the MetaPost interpreter with no +arguments, or on a command line that looks something like +this:\footnote{Command line syntax is system dependent. Quotes are +needed on most Unix systems to protect special characters like +{\tt\&}.} +$$ \hbox{\verb|mpost '&mfplain' cmr10|} $$ The analog of a \MF\ command line like $$ \hbox{\verb|mf '\mode=lowres; mag=1.2; input cmr10'|} $$ is -$$ \hbox{\verb|mp '&mfplain \mode=lowres; mag=1.2; input cmr10'|} $$ -The result is a set of PostScript files, one for each character in the font. -Some editing would be required in order to merge them into a downloadable Type~3 -PostScript font \cite{ad:red}. +$$ \hbox{\verb|mpost '&mfplain \mode=lowres; mag=1.2; input cmr10'|} $$ +The result is a set of PostScript files, one for each character in the +font. Some editing would be required in order to merge them into a +downloadable Type~3 PostScript font \cite{ad:red}. \begin{table}[htp] $$ @@ -5351,25 +6014,27 @@ openit \end{tabular} \renewcommand{\FancyVerbFormatLine}[1]{#1} $$ -\caption{Macros and internal variables defined only in the {\tt mfplain} package.} +\caption{Macros and internal variables defined only in the {\tt mfplain} +package.} \label{mfponly} \end{table} Another limitation of the {\tt mfplain} package is that certain internal -variables from Plain \MF\index{metafont?\MF} cannot be given reasonable MetaPost -definitions. These include {\tt displaying}, {\tt currentwindow}, -\verb|screen_rows|, and \verb|screen_cols| which depend on \MF's ability to -display images on the computer screen. In addition, \verb|pixels_per_inch| is -irrelevant since MetaPost uses fixed units of PostScript points. - -The reason why some macros and -internal variables\index{internal variables}\index{variables!internal} -are not meaningful in MetaPost -is that \MF\ primitive commands {\tt cull}, {\tt display}, {\tt openwindow}, -{\tt numspecial} and {\tt totalweight} are not implemented in MetaPost. Also not -implemented are a number of internal variables as well as the -\tdescr{drawing option} {\tt withweight}. Here is a complete listing of the -internal variables whose primitive meanings in \MF\ do not make sense in MetaPost: +variables from Plain \MF\index{metafont?\MF} cannot be given reasonable +MetaPost definitions. These include {\tt displaying}, {\tt +currentwindow}, \verb|screen_rows|, and \verb|screen_cols| which depend +on \MF's ability to display images on the computer screen. In addition, +\verb|pixels_per_inch| is irrelevant since MetaPost uses fixed units of +PostScript points. + +The reason why some macros and internal variables\index{internal +variables}\index{variables!internal} are not meaningful in MetaPost is +that \MF\ primitive commands {\tt cull}, {\tt display}, {\tt +openwindow}, {\tt numspecial} and {\tt totalweight} are not implemented +in MetaPost. Also not implemented are a number of internal variables as +well as the \tdescr{drawing option} {\tt withweight}. Here is a +complete listing of the internal variables whose primitive meanings in +\MF\ do not make sense in MetaPost: $$\begin{verbatim} autorounding fillin proofing tracingpens xoffset chardx granularity smoothing turningcheck yoffset @@ -5385,22 +6050,26 @@ but \MF\ copies the string into its ``generic font'' output file, while MetaPost interprets the string as a sequence of PostScript commands that are to be placed at the beginning of the next output file. -All the other differences between \MF\ and MetaPost are features found only in -MetaPost. These are listed in Table~\ref{mponly}. The only commands listed -in this table that the preceding sections do not discuss are +All the other differences between \MF\ and MetaPost are features found +only in MetaPost. These are listed in Table~\ref{mponly}. The only +commands listed in this table that the preceding sections do not discuss +are \verb|extra_beginfig|\index{extra_beginfig?\texttt{extra\_beginfig}}\label{Dxbfig}, -\verb|extra_endfig|\index{extra_endfig?\texttt{extra\_endfig}}\label{Dxefig}, and {\tt mpxbreak}. -The first two are strings that contain extra commands to be processed -by {\tt beginfig}\index{beginfig?\texttt{beginfig}} and {\tt endfig}\index{endfig?\texttt{endfig}} -just as \verb|extra_beginchar| and \verb|extra_endchar| are processed by -{\tt beginchar} and {\tt endchar}. -(The file {\tt boxes.mp}\index{boxes.mp?\texttt{boxes.mp}} uses these features). - -The other new feature listed in Table~\ref{mponly} not listed in the index -is {\tt mpxbreak}\index{mpxbreak?\texttt{mpxbreak}}. This is used to separate blocks of -translated \TeX\index{TeX?\TeX} or troff\index{troff} commands in -{\tt mpx}\index{files!mpx?{\tt mpx}} files. It should be of no concern to -users since {\tt mpx} files are generated automatically. +\verb|extra_endfig|\index{extra_endfig?\texttt{extra\_endfig}}\label{Dxefig}, +and {\tt mpxbreak}. The first two are strings that contain extra +commands to be processed by {\tt +beginfig}\index{beginfig?\texttt{beginfig}} and {\tt +endfig}\index{endfig?\texttt{endfig}} just as \verb|extra_beginchar| and +\verb|extra_endchar| are processed by {\tt beginchar} and {\tt endchar}. +(The file {\tt boxes.mp}\index{boxes.mp?\texttt{boxes.mp}} uses these +features). + +The other new feature listed in Table~\ref{mponly} not listed in the +index is {\tt mpxbreak}\index{mpxbreak?\texttt{mpxbreak}}. This is used +to separate blocks of translated \TeX\index{TeX?\TeX} or +troff\index{troff} commands in {\tt mpx}\index{files!mpx?{\tt mpx}} +files. It should be of no concern to users since {\tt mpx} files are +generated automatically. \begin{table}[htp] $$ @@ -5409,14 +6078,21 @@ $$ \multicolumn 1{|c|} {MetaPost primitives not found in \MF} \\ \hline $\begin{verbatim} -bluepart infont redpart -btex linecap setbounds -clip linejoin tracinglostchars -color llcorner truecorners -dashed lrcorner ulcorner -etex miterlimit urcorner -fontsize mpxbreak verbatimtex -greenpart prologues withcolor +blackpart greenpart setbounds +bluepart greypart tracinglostchars +btex infont troffmode +clip linecap truecorners +cmykcolor linejoin ulcorner +color llcorner urcorner +colormodel lrcorner verbatimtex +cyanpart magentapart withcmykcolor +dashed miterlimit withcolor +defaultcolormodel mpprocset withgreyscale +etex mpxbreak withoutcolor +filenametemplate prologues withpostscript +fontmapfile redpart withprescript +fontmapline restoreclipcolor withrgbcolor +fontsize rgbcolor yellowpart \end{verbatim} $ \\ \hline \multicolumn 1{|c|} @@ -5425,15 +6101,15 @@ $\begin{verbatim} ahangle cutbefore extra_beginfig ahlength cuttings extra_endfig background dashpattern green -bbox defaultfont label -bboxmargin defaultpen labeloffset -beginfig defaultscale mitered -beveled dotlabel red -black dotlabels rounded -blue drawarrow squared -buildcycle drawdblarrow thelabel -butt drawoptions white -center endfig +bbox defaultfont image +bboxmargin defaultpen label +beginfig defaultscale labeloffset +beveled dotlabel mitered +black dotlabels red +blue drawarrow rounded +buildcycle drawdblarrow squared +butt drawoptions thelabel +center endfig white cutafter evenly \end{verbatim} $ \\ \hline @@ -5457,6 +6133,7 @@ $$ \end{document} % Copyright 1990 - 1995 by AT&T Bell Laboratories. +% Updated 2006 by Taco Hoekwater, Karl Berry, and others. % Permission to use, copy, modify, and distribute this software % and its documentation for any purpose and without fee is hereby |