summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/metapost/base/source/mpman.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/metapost/base/source/mpman.tex')
-rw-r--r--Master/texmf-dist/doc/metapost/base/source/mpman.tex4221
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