summaryrefslogtreecommitdiff
path: root/systems/doc/metapost/source-manual/mpman.tex
diff options
context:
space:
mode:
Diffstat (limited to 'systems/doc/metapost/source-manual/mpman.tex')
-rw-r--r--systems/doc/metapost/source-manual/mpman.tex6008
1 files changed, 6008 insertions, 0 deletions
diff --git a/systems/doc/metapost/source-manual/mpman.tex b/systems/doc/metapost/source-manual/mpman.tex
new file mode 100644
index 0000000000..ec77468753
--- /dev/null
+++ b/systems/doc/metapost/source-manual/mpman.tex
@@ -0,0 +1,6008 @@
+% $Id: mpman.tex 2139 2018-02-19 14:38:47Z luigi.scarso@gmail.com $
+% MetaPost manual, by John Hobby. License at end.
+\listfiles
+\RequirePackage{ifpdf}
+\ifpdf
+\ifnum\pdftexversion<140
+\else
+\pdfminorversion=5
+\pdfobjcompresslevel=1% Use compressed object streams.
+\fi
+\RequirePackage{cmap}
+\fi
+\documentclass{article} % article is NOT the original style
+\usepackage[nofancy]{svninfo}% Access VCS information.
+\svnInfo $Id: mpman.tex 2140 2019-06-01 14:38:47Z luigi.scarso@gmail.com $
+%\svnInfo $Id: mpman.tex 2139 2018-02-19 14:38:47Z luigi.scarso@gmail.com $
+\newcommand*{\mpversion}{2.00}
+
+\usepackage[T1]{fontenc}
+\usepackage{lmodern}
+\usepackage{textcomp}
+\usepackage{mflogo}
+\usepackage{makeidx}
+\usepackage{fancyvrb}
+\usepackage{ctabbing}
+\RecustomVerbatimEnvironment
+ {verbatim}{BVerbatim}{baseline=c}
+\usepackage{graphicx}
+\usepackage[latin1]{inputenc}
+\usepackage[textwidth=6in,textheight=8.65in]{geometry}
+\usepackage{tocloft}
+ \setlength\cftbeforesecskip{1.3ex plus 0.3ex minus 0.3ex}
+ \setcounter{tocdepth}{2}
+\usepackage{ltxtable}
+
+
+\def\ttindex#1{{\tt #1}\index{#1?\texttt{#1}}}
+\def\ttt{\texttt} % I get tired of typing this out
+
+\def\ConTeXt{Con\TeX t}
+
+\newcommand\descr[1]{{\langle\hbox{#1}\rangle}}
+\newcommand\invisgap{\nobreak\hskip0pt\relax}
+\newcommand\tdescr[1]{{\normalfont$\langle$\invisgap#1\invisgap$\rangle$}}
+
+\newcommand\pl{\dag}
+
+\newcommand\mathcenter[1]{\vcenter{\hbox{#1}}}
+
+
+\renewcommand{\topfraction}{.85}
+\renewcommand{\bottomfraction}{.7}
+\renewcommand{\textfraction}{.15}
+\renewcommand{\floatpagefraction}{.5}
+\renewcommand{\dbltopfraction}{.66}
+\renewcommand{\dblfloatpagefraction}{.66}
+\setcounter{topnumber}{9}
+\setcounter{bottomnumber}{9}
+\setcounter{totalnumber}{20}
+\setcounter{dbltopnumber}{9}
+
+\makeindex
+
+\usepackage{multicol}
+\usepackage[rgb,x11names]{xcolor}% Optimize for screen reading.
+\usepackage{hyperxmp}
+\usepackage{hyperref}
+\hypersetup{
+ pdftitle={MetaPost: A User's Manual},
+ pdfauthor={John D. Hobby and the MetaPost development team},
+ pdfkeywords={MetaPost, PostScript, SVG, PNG, vector graphics language,
+ MetaFont, TeX}
+}
+\hypersetup{
+ pdfstartview={XYZ null null null},% Zoom factor is determined by viewer.
+ colorlinks,
+ linkcolor=RoyalBlue3,
+ urlcolor=Chocolate4,
+ citecolor=SpringGreen3
+}
+\usepackage[all]{hypcap}
+\ifpdf
+\pdfmapfile{=cm2lm.map}% replace CM by LM in figures
+\else
+\DeclareGraphicsExtensions{.mps}
+\DeclareGraphicsRule{mps}{eps}{*}{}
+\usepackage{breakurl}
+\fi
+\begin{document}
+\VerbatimFootnotes
+%%% Title page layout documentation is missing.
+\begin{titlepage}
+ \vbox to \textheight {%
+ \vskip0pt
+ \vfil
+ \vfil
+ \vfil
+ \centerline{\resizebox{3.5in}{!}{\fontseries{b}\selectfont\MP}}
+ \vskip10bp% actually 21bp (-11bp)
+ \centerline{\includegraphics{mpman-60.mps}}
+ \vskip15bp% actually 21bp (-6bp)
+ \centerline{%
+ \resizebox{3.5in}{!}{%
+ \scshape%
+ \fontsize{28bp}{28bp}\selectfont
+ \strut\lowercase{A USER\kern-2bp\lower3bp\hbox{'}S MANUAL}%
+ }%
+ }
+ \vskip-11bp
+ \vfil
+ \vfil
+ \centerline{\large John D. Hobby}
+ \vskip3bp
+ \centerline{and the MetaPost development team}
+ \vskip20.8bp% actually 31.8bp (-11bp)
+ \centerline{\large documented version: \mpversion}
+ \vskip3bp
+\tracingall \centerline{\svnInfoMaxToday} \tracingnone
+ \vskip\baselineskip
+ \centerline{Web page: {\tt https://tug.org/metapost}}
+ \centerline{Mailing list: {\tt https://lists.tug.org/metapost}}
+ \vfil
+ \vfil
+ }
+\end{titlepage}
+
+\setlength{\columnsep}{2.5em}
+\begin{multicols}{2}
+\tableofcontents
+\end{multicols}
+
+\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
+either vector graphics in the Postscript or SVG formats or bitmap
+graphics in the PNG format. 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.
+
+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}. Reading the manual and creating
+moderately complex graphics with MetaPost does not require knowledge of
+\MF\ or access to {\sl The \MF book} \cite{kn:c}. However, to really
+master MetaPost, both are beneficial, since the MetaPost language is
+based on Knuth's \MF\ to a large extent. Appendix~\ref{MPvsMF} gives a
+detailed comparison of MetaPost and \MF.
+
+The basic MetaPost documentation is completed with ``Drawing Boxes with
+MetaPost'' and ``Drawing Graphs with MetaPost''---the manuals of the
+\texttt{boxes} and \texttt{graph} packages originally developed by
+John~D. Hobby.
+
+The MetaPost home page is \url{https://tug.org/metapost}. It has links
+to much additional information, including many articles that have been
+written about MetaPost. For general help and discussion, try the
+\url{metapost@tug.org} mailing list; you can subscribe to this list at
+\url{https://lists.tug.org/metapost}.
+
+The development repository is currently hosted at
+\url{https://serveur-svn.lri.fr/svn/modhel/metapost}; web browsing and
+anonymous svn checkout are allowed with username \texttt{anonsvn} and
+password \texttt{anonsvn}.
+
+If bug reports get no reply from \url{metapost@tug.org}, feel free to
+resend to \url{mp-implementors@tug.org}. (Please do not send reports
+directly to Dr.~Hobby in any event.)
+
+
+\section{Basic Drawing Statements}
+\label{basic}
+
+The simplest drawing statement is the one that draws a single dot with
+the current pen at a given coordinate:
+$$
+\begin{verbatim}
+drawdot (30,0)
+\end{verbatim}
+\index{drawdot?\texttt{drawdot}}
+\label{Ddrawdot}
+$$
+
+MetaPost can also draw straight lines.
+Thus\index{draw?\texttt{draw}}\index{-{}-?\texttt{-{}-}}
+$$ \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:
+$$ \includegraphics{mpman-1.mps} $$
+
+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}}\index{units!bp?\texttt{bp}}\label{Dbp}
+refers to PostScript points (``big points'') and
+\verb|pt|\index{pt?\texttt{pt}}\index{units!pt?\texttt{pt}}\label{Dpt}
+refers to printer's points. Other units of measure include
+\verb|in|\index{in?\texttt{in}}\index{units!in?\texttt{in}}\label{Din}
+for inches,
+\verb|pc|\index{pc?\texttt{pc}}\index{units!pc?\texttt{pc}}\label{Dpc}
+for picas,
+\verb|cm|\index{cm?\texttt{cm}}\index{units!cm?\texttt{cm}}\label{Dcm}
+for centimeters,
+\verb|mm|\index{mm?\texttt{mm}}\index{units!mm?\texttt{mm}}\label{Dmm}
+for millimeters,
+\verb|cc|\index{cc?\texttt{cc}}\index{units!cc?\texttt{cc}}\label{Dcc}
+for ciceros, and
+\verb|dd|\index{dd?\texttt{dd}}\index{units!dd?\texttt{dd}}\label{Ddd}
+for Didot points. 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|). The coordinate \verb|(0,0)|
+can also be referred to as
+\texttt{origin}\index{origin?\texttt{origin}}\label{Dorigin}, as in
+$$ \hbox{\verb|drawdot origin|} $$
+
+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 (actually the pen size) for subsequent
+\verb|draw| or \verb|drawdot| statements to 4 points. (This is about
+eight times the default pen size).
+
+With such a large pen size, the \verb|drawdot| statement draws rather
+bold dots. We can use this to make a grid of dots by nesting
+\verb|drawdot| in a pair of loops:\index{loops}%
+$$
+\begin{verbatim}
+for i=0 upto 2:
+ for j=0 upto 2: drawdot (i*u,j*u); endfor
+endfor
+\end{verbatim}
+\index{for?\texttt{for}}
+\index{endfor?\texttt{endfor}}
+$$
+The outer loop runs for $i=0,1,2$ and the inner loop runs for $j=0,1,2$.
+The result is a three-by-three grid of bold dots as shown in Figure~\ref{fig1}.
+The figure also includes a larger version of the polygonal line diagram that we
+saw before.
+
+\begin{figure}[htp]
+$$ \begin{verbatim}
+beginfig(2);
+u=1cm;
+draw (2u,2u)--(0,0)--(0,3u)--(3u,0)--(0,0);
+pickup pencircle scaled 4pt;
+for i=0 upto 2:
+ for j=0 upto 2: drawdot (i*u,j*u); endfor
+endfor
+endfig;
+\end{verbatim}
+\quad \mathcenter{\includegraphics{mpman-2.mps}}
+$$
+\caption{MetaPost commands and the resulting output}
+\label{fig1}
+\end{figure}
+
+
+\section{The MetaPost Workflow}
+\label{workflow}
+
+Before describing the MetaPost language in detail, let's have a look at
+MetaPost's graphic design workflow. This section also contains a few
+technical details about MetaPost's compilation process, just enough to
+get you started. Section~\ref{workflow2} is more elaborate on this
+topic.
+
+In this manual, we'll assume a stand-alone command-line executable of
+the MetaPost compiler is used, which is usually called
+\texttt{mpost}\index{mpost?\texttt{mpost}}. The syntax and program name
+itself are system-dependent; sometimes it is named \texttt{mp}. The
+executable is actually a small wrapper program around
+\emph{mplib}\index{mplib?\emph{mplib}}, a library containing the
+MetaPost compiler. The library can as well be embedded into third-party
+applications.\footnote{C~API\index{mplib?\emph{mplib}!C~API} and Lua
+ bindings\index{mplib?\emph{mplib}!Lua bindings} are described in file
+ \verb|manual/mplibapi.pdf|\index{mplib?\emph{mplib}!mplibapi.pdf?\texttt{mplibapi.pdf}}
+ as part of the MetaPost distribution.} Section~\ref{mpimport} has
+some brief information on how to use the MetaPost compiler built-into
+Lua\TeX. For more information, please refer to the documentation of the
+embedding application.
+
+The basic MetaPost workflow\index{workflow} is depicted in
+figure~\ref{fig:mpworkflow}. Being a graphics description language,
+creating graphics with MetaPost follows the
+\emph{edit-compile-debug}\index{edit}\index{compile}\index{debug}
+paradigm known from other programming languages.
+
+\begin{figure}[tbp]
+$$ \includegraphics{mpman-charts-2.mps} $$
+\caption{The basic MetaPost workflow}
+\label{fig:mpworkflow}
+\end{figure}
+
+To create graphics with MetaPost, you prepare\index{edit} a text file
+containing code in the MetaPost language and then invoke the
+compiler\index{compile}, usually by giving a command of the form
+$$
+\begin{verbatim}[commandchars=\\\{\}]
+mpost \tdescr{input file}
+\end{verbatim}
+\index{mpost?\texttt{mpost}}
+$$
+on the command-line. MetaPost input files\index{files!input} normally
+have names ending \texttt{.mp}\index{mp file?{\tt mp}
+ file}\index{files!mp?{\tt mp}} but this part of the name can be
+omitted when invoking MetaPost. A complete description of the
+command-line syntax can be found in Section~\ref{refman:commandline}.
+
+Any terminal I/O during the compilation process is summarized in a
+transcript\index{files!transcript}\index{transcript file|see{files,
+ transcript}} file called \texttt{\tdescr{jobname}.log}\index{log
+ file?{\tt log} file}\index{files!log?{\tt log}}, where
+\tdescr{jobname} is the base name of the input file. This includes
+error messages and any MetaPost commands entered in interactive mode.
+
+If all goes well during compilation, MetaPost outputs one or more
+graphic files in a variant of the PostScript format, by default.
+PostScript output can be previewed\index{preview} with any decent
+PostScript viewer, e.g., GSview\index{GSview} or
+PS\_View\index{PSView?PS\_View}. Section~\ref{preview} has some tips
+and discusses several more elaborate ways for previewing PostScript
+output. Particularly, if graphics contain text labels, some more work
+might be required to get robust results in a PostScript viewer.
+MetaPost is also capable of generating graphics in the SVG\index{SVG}
+and PNG\index{PNG} formats. These file types can be previewed with
+certain web browsers, for example Firefox~3\index{Firefox} or
+Konqueror~4.2\index{Konqueror}, or general purpose image viewers.
+
+What does one do with all the graphic files? PostScript files are
+perfectly suitable for inclusion into documents created by
+\TeX\index{TeX?\TeX} or troff\index{troff}. The SVG format, as an XML
+descendant (Extensible Meta Language), is more aiming at automated data
+processing/interchanging. The PNG format is a losslessly compressing
+bitmap format. Both, SVG and PNG graphics, are widely used for web
+applications. Section~\ref{mpimport} deals with the import of MetaPost
+graphics into external applications.
+
+A MetaPost input file\index{files!input}\index{edit}\index{edit}
+normally contains a sequence of
+\verb|beginfig()|\index{beginfig?\texttt{beginfig}},
+\verb|endfig|\index{endfig?\texttt{endfig}} pairs with an
+\verb|end|\index{end?\texttt{end}} statement after the last
+one.\footnote{Omitting the final \verb|end| statement causes MetaPost to
+ enter interactive mode\index{interactive mode} after processing the
+ input file.} These are macros that perform various administrative
+functions and ensure that the results of all drawing operations get
+packaged up and translated into PostScript (or the SVG or PNG format).
+The numeric argument to the \verb|beginfig| macro determines the name of
+the corresponding output file, whose name, by default, is of the form
+\texttt{\tdescr{jobname}.\tdescr{n}}, where \tdescr{n} is the current
+argument to \verb|beginfig| rounded to the nearest integer. As an
+example, if a file is named \texttt{fig.mp} and contains the lines
+$$
+\begin{verbatim}[commandchars=\\\{\}]
+beginfig(1);
+ \tdescr{drawing statements}
+endfig;
+end
+\end{verbatim}
+$$
+the output from statements between \verb|beginfig(1)| and the next
+\verb|endfig| is written in a file \texttt{fig.1}\index{files!output}.
+
+Statements can also appear outside \verb|beginfig| \ldots\
+\verb|endfig|. Such statements are processed, but drawing operations
+generate no visible output. Typically, global configurations are put
+outside \verb|beginfig| \ldots\ \verb|endfig|, e.g., assignments to
+internal variables, such as \texttt{outputtemplate}, or a \LaTeX\
+preamble declaration for enhanced text rendering.
+Comments\index{comments} in MetaPost code are introduced by the percent
+sign~\verb|%|\index{\%?\texttt{\%}!comment}, which causes the remainder
+of the current line to be ignored.
+
+The remainder of this section briefly introduces three assignments to
+internal variables, each one useful by itself, that can often be found
+in MetaPost input files:
+$$
+\begin{verbatim}[commandchars=\\\{\}]
+prologues := 3; \smallskip
+outputtemplate := "%j-%c.mps"; \smallskip
+outputformat := "svg";
+\end{verbatim}
+$$
+
+If your graphics contain text labels, you might want to set variable
+\texttt{prologues} to~3 to make sure the correct fonts are used under
+all possible circumstances. The second assignment changes the output
+file naming scheme to the form \texttt{\tdescr{jobname}-\tdescr{n}.mps}.
+That way, instead of a numeric index, all output files get a uniform
+file extension \texttt{mps}\index{mps file?{\tt mps}
+ file}\index{files!mps?{\tt mps}}, which is typically used for
+MetaPost's PostScript output. The last assignment lets MetaPost write
+output files in the SVG format rather than in the PostScript format.
+More information can be found in Sections~\ref{Dprologues}
+and~\ref{workflow2}.
+
+
+\section{Curves}
+\label{curves}
+
+MetaPost is perfectly happy to draw curved lines as well as straight ones.
+A \verb|draw| statement with the points separated by
+\verb|..|\index{..?\texttt{..}} draws a smooth curve through the points.
+For example consider the result of
+$$ \hbox{\verb|draw z0..z1..z2..z3..z4|} $$
+after defining five points as follows:
+$$\begin{verbatim}
+z0 = (0,0); z1 = (60,40);
+z2 = (40,90); z3 = (10,70);
+z4 = (30,50);
+\end{verbatim}
+$$
+Figure~\ref{fig2} shows the curve with points \verb|z0| through \verb|z4|
+labeled.
+
+\begin{figure}[htp]
+$$ \includegraphics{mpman-3.mps}
+$$
+\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
+$$ \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
+as having two draw statements
+\begin{eqnarray*}
+ \hbox{\verb|draw z0..z1..z2..z3|}\\
+\noalign{\hbox{and}}
+ \hbox{\verb|draw z3--z4--z0|}
+\end{eqnarray*}
+
+\begin{figure}[htp]
+$$ {\includegraphics{mpman-104.mps} \atop (a)}
+ \qquad {\includegraphics{mpman-204.mps} \atop (b)}
+$$
+\caption[Closed curves through five points]
+ {(a)~The result of {\tt draw z0..\linebreak[0]z1..\linebreak[0]%
+ z2..\linebreak[0]z3..\linebreak[0]z4..\linebreak[0]cycle};
+ (b)~the result of {\tt draw z0..\linebreak[0]z1..\linebreak[0]%
+ z2..\linebreak[0]z3--\linebreak[0]z4--\linebreak[0]cycle}.}
+\label{fig3}
+\end{figure}
+
+MetaPost already provides a small selection of basic path shapes that
+can be used to derive custom paths from. The predefined variable
+\texttt{fullcircle}\index{fullcircle?\texttt{fullcircle}}\label{Dfcirc}
+refers to a closed path describing a circle of unit diameter centered on
+the origin. There are also
+\texttt{halfcircle}\index{halfcircle?\texttt{halfcircle}}\label{Dhcirc}
+and
+\texttt{quartercircle}\index{quartercircle?\texttt{quartercircle}}\label{Dqcirc},
+the former being the part of a full circle covering the first and second
+quadrant and the latter covering just the first quadrant. Because of
+the mathematical model that is used to describe paths in MetaPost, all
+these are not exactly circular paths, but very good approximations (see
+Figure~\ref{fig3a}).
+
+\begin{figure}
+$$ \includegraphics{mpman-61.mps} $$
+\caption{A circle and a square with cardinal points. Arrows are
+ pointing to the start and end points of the closed paths.}
+\label{fig3a}
+\end{figure}
+
+Rectangularly shaped paths can be derived from
+\texttt{unitsquare}\index{unitsquare?\texttt{unitsquare}}\label{Dunitsqr},
+a closed path describing a square of unit side length whose lower left
+corner is located at the origin.
+
+\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
+$$ \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
+$0\le t\le5$, where $X(t)$ and $Y(t)$ are piecewise cubic functions. That is,
+there is a different pair of cubic functions for each integer-bounded
+$t$-interval. If ${\tt z0}=(x_0,y_0)$, ${\tt z1}=(x_1,y_1)$,
+${\tt z2}=(x_2,y_2)$, \ldots, MetaPost selects
+B\'ezier control\index{control points} points
+$(x_0^+,y_0^+)$, $(x_1^-,y_1^-)$, $(x_1^+,y_1^+)$, \ldots, where
+\begin{eqnarray*}
+ X(t+i) &=& (1-t)^3x_i + 3t(1-t)^2x_i^+ + 3t^2(1-t)x_{i+1}^- + t^3x_{i+1},\\
+ Y(t+i) &=& (1-t)^3y_i + 3t(1-t)^2y_i^+ + 3t^2(1-t)y_{i+1}^- + t^3y_{i+1}
+\end{eqnarray*}
+for $0\le t\le1$. The precise rules for choosing the B\'ezier control points
+are described in \cite{ho:splin} and in {\sl The \MF book\/}~\cite{kn:c}.
+
+In order for the path to have a continuous slope at $(x_i,y_i)$, the incoming
+and outgoing directions at $(X(i),Y(i))$ must match. Thus the vectors
+$$ (x_i-x_i^-,\,y_i-y_i^-) \qquad \hbox{and}
+ \qquad (x_i^+-x_i,\,y_i^+-y_i)
+$$
+must have the same direction; i.e., $(x_i,y_i)$ must be on the line segment
+between $(x_i^-,y_i^-)$ and $(x_i^+,y_i^+)$. This situation is illustrated
+in Figure~\ref{fig4} where the B\'ezier control points selected by MetaPost
+are connected by dashed lines. For those who are familiar with the interesting
+properties of this construction, MetaPost allows the control points to be
+specified directly in the following format:\index{controls?\texttt{controls}}
+$$ \begin{verbatim}
+draw (0,0)..controls (26.8,-1.8) and (51.4,14.6)
+ ..(60,40)..controls (67.1,61.0) and (59.8,84.6)
+ ..(40,90)..controls (25.4,94.0) and (10.5,84.5)
+ ..(10,70)..controls ( 9.6,58.8) and (18.8,49.6)
+ ..(30,50);
+\end{verbatim}
+$$
+
+For a way to extract the control points of a path, given by the user or
+calculated by MetaPost, see section~\ref{Dprepostctrl}.
+
+\begin{figure}[htp]
+$$ \includegraphics{mpman-5.mps}
+$$
+\caption[A curve and the control polygon]
+ {The result of {\tt draw z0..z1..z2..z3..z4} with the
+ automatically-selected B\'ezier control polygon illustrated by dashed
+ lines.}
+\label{fig4}
+\end{figure}
+
+\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|:
+$$ \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.
+
+\begin{figure}[htp]
+$$ \includegraphics{mpman-6.mps}
+$$
+\caption[A curve and the control polygon]
+ {The result of {\tt draw z0..z1\char`\{up\char`\}..z2\char`\{left\char`\}%
+ ..z3..z4}.}
+\label{fig5}
+\end{figure}
+
+How can the choice of directions at given points on a curve determine whether
+the curvature will be continuous? The reason is that curves used in MetaPost
+come from a family where a path is determined by its endpoints and the
+directions there. Figures \ref{fig6} and~\ref{fig7} give a good idea of what
+this family of curves is like.
+
+\begin{figure}[htp]
+$$ \mathcenter{\includegraphics{mpman-7.mps}} \quad
+\begin{verbatim}
+beginfig(7)
+for a=0 upto 9:
+ draw (0,0){dir 45}..{dir -10a}(6cm,0);
+endfor
+endfig;
+\end{verbatim}
+$$
+\caption{A curve family and the MetaPost instructions for generating it}
+\label{fig6}
+\end{figure}
+
+\begin{figure}[htp]
+$$ \mathcenter{\includegraphics{mpman-8.mps}} \quad
+\begin{verbatim}
+beginfig(8)
+for a=0 upto 7:
+ draw (0,0){dir 45}..{dir 10a}(6cm,0);
+endfor
+endfig;
+\end{verbatim}
+$$
+\caption{Another curve family with the corresponding MetaPost instructions}
+\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}.
+
+The direction
+vectors given in \verb|{}| can be of any length, and they can come before a
+point as well as after one. It is even possible for a path specification
+to have directions given before and after a point. For example a path
+specification containing
+$$ \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}).
+
+\begin{figure}[htp]
+$$ {\mathcenter{\includegraphics{mpman-109.mps}} \atop
+ \hbox{\verb|draw z0{up}..z1{right}..z2{down}|}}
+ \quad
+ {\mathcenter{\includegraphics{mpman-209.mps}} \atop
+ \hbox{\verb|draw z0{up}...z1{right}...z2{down}|}}
+$$
+\caption{Two {\tt draw} statements and the resulting curves.}
+\label{fig8}
+\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}:
+$$ \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
+$$ \hbox{\verb|draw z0..z1..tension 1.5 and 1..z2..z3|} $$
+The tension parameter can be less than one, but it must be at least $3\over4$.
+
+\begin{figure}[htp]
+$$ {\mathcenter{\includegraphics{mpman-110.mps}} \atop (a)}
+ \quad
+ {\mathcenter{\includegraphics{mpman-210.mps}} \atop (b)}
+ \quad
+ {\mathcenter{\includegraphics{mpman-310.mps}} \atop (c)}
+$$
+\caption[Effects of changing the tension parameter]
+ {Results of {\tt draw z0..z1..tension} $\alpha$ {\tt and} $\beta$
+ {\tt ..z2..z3} for various $\alpha$ and $\beta$:
+ (a)~$\alpha=\beta=1$; (b)~$\alpha=\beta=1.3$;
+ (c)~$\alpha=1.5$, $\beta=1$.}
+\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
+$$ \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.
+
+\begin{figure}[htp]
+$$ {\mathcenter{\includegraphics{mpman-111.mps}} \atop c=0}
+ \qquad
+ {\mathcenter{\includegraphics{mpman-211.mps}} \atop c=1}
+ \qquad
+ {\mathcenter{\includegraphics{mpman-311.mps}} \atop c=2}
+ \qquad
+ {\mathcenter{\includegraphics{mpman-411.mps}} \atop c=\infty}
+$$
+\caption[Effects of changing the curl parameter]
+ {Results of {\tt draw z0\char`\{curl c\char`\}..z1..%
+ \char`\{curl c\char`\}z2} for various values
+ of the curl parameter~$c$.}
+\label{fig10}
+\end{figure}
+
+\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
+$$ \hbox{\verb|..controls (30,20)..|} $$
+is equivalent to
+$$ \hbox{\verb|...controls (30,20) and (30,20)..|} $$
+
+\begin{figure}[htp]
+\begin{ctabbing}
+$\descr{path expression} \rightarrow
+ \descr{path subexpression}$\\
+\qquad \= ${}\mid \descr{path subexpression} \descr{direction specifier}$\\
+\> ${}\mid \descr{path subexpression} \descr{path join}$ \verb|cycle|\\
+$\descr{path subexpression} \rightarrow
+ \descr{path knot}$\\
+\> ${}\mid \descr{path expression} \descr{path join} \descr{path knot}$\\
+$\descr{path join} \rightarrow
+ \hbox{\verb|--|}$\\
+\> ${}\mid \descr{direction specifier} \descr{basic path join}
+ \descr{direction specifier}$\\
+$\descr{direction specifier} \rightarrow
+ \descr{empty}$\\
+\> ${}\mid {}$\verb|{curl| $\descr{numeric expression}$\verb|}|\\
+\> ${}\mid {}$\verb|{|$\descr{pair expression}$\verb|}|\\
+\> ${}\mid {}$\verb|{|$\descr{numeric expression}$\verb|,|%
+ $\descr{numeric expression}$\verb|}|\\
+$\descr{basic path join} \rightarrow
+ \hbox{\verb|..|}
+ \mid \hbox{\verb|...|}
+ \mid \hbox{\verb|..|}\descr{tension}\hbox{\verb|..|}
+ \mid \hbox{\verb|..|}\descr{controls}\hbox{\verb|..|}$\\
+$\descr{tension} \rightarrow
+ \hbox{\verb|tension|}\descr{numeric primary}$\\
+\> ${}\mid \hbox{\verb|tension|}\descr{numeric primary}
+ \hbox{\verb|and|}\descr{numeric primary}$\\
+$\descr{controls} \rightarrow
+ \hbox{\verb|controls|}\descr{pair primary}$\\
+\> ${}\mid \hbox{\verb|controls|}\descr{pair primary}
+ \hbox{\verb|and|}\descr{pair primary}$
+\end{ctabbing}
+\caption{The syntax for path construction}
+\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}.
+
+
+\section{Linear Equations}
+\label{lin.eq}
+
+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; 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}
+>> 2
+>> 1
+\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:
+$$ \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:
+$$ \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.
+
+\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
+$$ \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:
+\begin{eqnarray*}
+ &&\hbox{\verb|z1=-z2=(.2in,0);|} \\
+ &&\hbox{\verb|x3=-x6=.3in;|} \\
+ &&\hbox{\verb|x3+y3=x6+y6=1.1in;|}
+\end{eqnarray*}
+Exactly the same points could be obtained by setting their values directly:
+$$ \begin{verbatim}
+z1=(.2in,0); z2=(-.2in,0);
+z3=(.3in,.8in); z6=(-.3in,1.4in);
+\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}\index{[]?\texttt{[]}!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}). $$
+Similarly
+$$ \hbox{\verb|z5=2/3[z3,z6]|} $$
+makes {\tt z5} $2\over3$ of the way from $z3$ to $z6$.
+
+\begin{figure}[htp]
+$$ \begin{verbatim}
+beginfig(13);
+z1=-z2=(.2in,0);
+x3=-x6=.3in;
+x3+y3=x6+y6=1.1in;
+z4=1/3[z3,z6];
+z5=2/3[z3,z6];
+z20=whatever[z1,z3]=whatever[z2,z4];
+z30=whatever[z1,z4]=whatever[z2,z5];
+z40=whatever[z1,z5]=whatever[z2,z6];
+draw z1--z20--z2--z30--z1--z40--z2;
+pickup pencircle scaled 1pt;
+draw z1--z2;
+draw z3--z6;
+endfig;
+\end{verbatim}
+\quad \mathcenter{\includegraphics{mpman-13.mps}}
+$$
+\caption[MetaPost code and figure using linear equations]
+ {MetaPost commands and the resulting figure. Point labels have been
+ added to the figure for clarity.}
+\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
+$$ \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
+$$ \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
+$$ \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}.
+This is how Figure~\ref{fig12} sets {\tt z20}, {\tt z30}, and
+{\tt z40}.
+
+\subsection{Dealing with Unknowns}
+
+A system of equations such as those used in Figure~\ref{fig12} can be given in
+any order as long as all the equations are linear and all the variables can
+be determined before they are needed. This means that the equations
+\begin{eqnarray*}
+ && \hbox{\verb|z1=-z2=(.2in,0);|}\\
+ && \hbox{\verb|x3=-x6=.3in;|}\\
+ && \hbox{\verb|x3+y3=x6+y6=1.1in;|}\\
+ && \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
+$$ \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.
+
+The most natural way to ensure that MetaPost can handle an expression like
+$$ \hbox{\verb|whatever[z1,z3]|} $$
+is to ensure that {\tt z1} and {\tt z3} are both known. However this is not
+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}.
+
+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
+$$ \hbox{\verb|(x20-x1)-(y20-y1)/6=1in;|} $$
+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
+mechanism. Roundoff error
+is normally not a serious problem, but it is likely to cause trouble if you are
+trying to do something like find the intersection of two lines that are almost
+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 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 ``\verb|>> |''. 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{\verb|>> 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}.
+
+\subsection{Data Types}
+\label{datatypes}
+
+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 integer multiples of
+$1\over65536$, the smallest positive value, which is also available as
+the predefined constant
+\texttt{epsilon}\index{epsilon?\texttt{epsilon}}\label{Depsilon}.\footnote{MetaPost
+ can also do arithmetic with higher and (almost) arbitrary precision.
+ See Appendix~\ref{hparith} for more information.} Numeric quantities
+must normally have absolute values less than 4096 but intermediate
+results can be eight times larger. This should not be a problem for
+distances or coordinate values since 4096 PostScript points is more than
+1.4~meters. If you need to work with numbers of magnitude 4096 or more,
+setting the internal variable
+\texttt{warningcheck}\index{warningcheck?\texttt{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.
+
+Paths\index{path type} have already been discussed in the context of {\tt draw}
+statements, but
+that discussion did not mention that paths are first-class objects that can be
+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
+transform,\index{transformed?\texttt{transformed}}
+$$ \hbox{\tt p transformed T} $$
+is a pair of the form
+$$ (t_x+t_{xx}p_x+t_{xy}p_y, t_y+t_{yx}p_x+t_{yy}p_y), $$
+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 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 \ttindex{black}\label{Dblack}, \ttindex{white}\label{Dwhite},
+\ttindex{red}\label{Dred}, \ttindex{green}\label{Dgreen},
+\ttindex{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 CMYK colors deal with
+pigments instead of light rays, the color white would be expressed as
+{\tt (0,0,0,0)} and black as {\tt (0,0,0,1)}. In theory, the colors
+{\tt ($c$,$m$,$y$,1)} and {\tt (1,1,1,$k$)} should result in black for
+any values of $c$, $m$, $y$ and~$k$, too. But in practice, this is
+avoided since it is a waste of colored ink and can lead to
+unsatisfactory results.
+
+A string\index{string type} represents a sequence of characters.
+String constants\index{string constants} are given
+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.
+
+\label{Dscantokens}
+Conversion from strings to other types, notably numeric, can be accomplished by
+the {\tt scantokens}\index{scantokens?\texttt{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.
+
+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}
+$$ {\tt pickup\ }\descr{pen expression} $$
+causes the given pen to be used in subsequent
+\verb|draw|\index{draw?\texttt{draw}} or
+\verb|drawdot|\index{drawdot?\texttt{drawdot}} statements. Normally,
+the pen expression is of the form
+$$ {\tt pencircle\ scaled\ }\descr{numeric primary}. $$
+This defines a circular pen that produces lines of constant thickness.
+If calligraphic effects are desired, the pen expression can be adjusted to give
+an elliptical pen or a polygonal pen.
+
+\subsection{Operators}
+
+There are many different ways to make expressions of the ten 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}
+$\tt \descr{primary} \rightarrow \descr{variable}$\\
+$\tt \qquad \;|\; \hbox{\tt (}\descr{expression}\hbox{\tt )}$\\
+$\tt \qquad \;|\; \descr{nullary op}$\\
+$\tt \qquad \;|\; \descr{of operator} \descr{expression}
+ of \descr{primary}$\\
+$\tt \qquad \;|\; \descr{unary op} \descr{primary}$\\
+$\tt \descr{secondary} \rightarrow \descr{primary}$\\
+$\tt \qquad \;|\; \descr{secondary} \descr{primary binop} \descr{primary}$\\
+$\tt \descr{tertiary} \rightarrow \descr{secondary}$\\
+$\tt \qquad \;|\; \descr{tertiary} \descr{secondary binop}
+ \descr{secondary}$\\
+$\tt \descr{expression} \rightarrow \descr{tertiary}$\\
+$\tt \qquad \;|\; \descr{expression} \descr{tertiary binop}
+ \descr{tertiary}$
+\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{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*x2 + y1*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}.
+
+The basic operations on strings are concatenation\index{concatenation},
+substring construction and calculating the length of a string.
+The \tdescr{tertiary binop} \verb|&|\index{&?\texttt{\&}}\label{Damp}
+implements concatenation; e.g.,
+$$ \hbox{\verb|"abc" & "de"|} $$
+produces the string \verb|"abcde"|. The {\tt
+length}\index{length?\texttt{length}}\label{DlengthString} operator
+returns the number of characters in a string if the argument is a
+\tdescr{string primary}; e.g.,
+$$ \hbox{\verb|length "abcde"|} $$
+returns \verb|5|. Another application of the {\tt length} operator is
+discussed on p.\ \pageref{Dlength}. 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"|
+should be thought of like this
+$$ \includegraphics{mpman-14.mps} $$
+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
+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}}
+$$ \descr{path knot} \rightarrow \descr{pair tertiary} \;|\; \descr{path tertiary}
+$$
+explains the meaning of \tdescr{path knot} in Figure~\ref{sypath}. This means
+that the path expression
+$$ \hbox{\verb|z1+(1,1){right}..z2|} $$
+does not need parentheses around {\tt z1+(1,1)}.
+
+\subsection{Fractions, Mediation, and Unary Operators}
+
+Mediation\index{mediation} expressions do not appear in the basic expression
+syntax of Figure~\ref{syexpr}. Mediation expressions are parsed at the
+\tdescr{primary} level, so the general rule for constructing them is
+$$ \descr{primary} \rightarrow
+ \descr{numeric atom} \hbox{\tt [} \descr{expression}
+ \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}
+$$ \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$.
+
+\begin{figure}[htp]
+\begin{ctabbing}
+$\tt \descr{numeric primary} \rightarrow \descr{numeric atom}$\\
+$\tt \qquad \;|\; \descr{numeric atom}\hbox{\tt [}
+ \descr{numeric expression}\hbox{\tt ,}\descr{numeric expression}\hbox{\tt ]}$\\
+$\tt \qquad \;|\; \descr{of operator} \descr{expression} of \descr{primary}$\\
+$\tt \qquad \;|\; \descr{unary op} \descr{primary}$\\
+$\tt \descr{numeric atom} \rightarrow \descr{numeric variable}$\\
+$\tt \qquad \;|\; \descr{number or fraction}$\\
+$\tt \qquad \;|\; \hbox{\tt (}\descr{numeric expression}\hbox{\tt )}$\\
+$\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}$'}$
+\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{unary op} 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{unary op}. 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 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, 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?\texttt{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 components 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)} $$
+and for a greyscale color {\tt c}, there is only one component%
+\index{greypart?\texttt{greypart}}\label{Dgreyprt}%
+$$ \hbox{\tt greypart c}. $$
+All color component operators are discussed in more detail in
+section~\ref{piccomp}. Part specifiers for transforms are discussed
+in section~\ref{transsec}.
+
+
+\section{Variables}
+\label{vars}
+
+MetaPost allows compound variable names such as {z.a}, {\tt x2r}, {\tt y2r},
+and {\tt z2r}, where {\tt z2r} means {\tt (x2r,y2r)} and {\tt z.a} means
+{\tt (x.a,y.a)}. In fact there is a broad class of suffixes such that
+{\tt z}\tdescr{suffix}\index{suffix?\tdescr{suffix}} means
+$$ (x\descr{suffix},\, y\descr{suffix}). $$
+Since a \tdescr{suffix} is composed of tokens, it is best to begin with a few
+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.
+
+Anything between a pair of double quotes {\tt "} is a
+string constant\index{string constants}. It is
+illegal for a string constant to start on one line and end on a later line.
+Nor can a string constant contain double quotes {\tt "} or anything other than
+printable ASCII characters.
+
+Everything in a line of input other than numbers and string constants is broken
+into symbolic tokens\index{tokens!symbolic}. A symbolic token is a sequence of
+one or more similar characters, where characters are ``similar'' if they occur
+on the same row of Table~\ref{classes}.
+
+\begin{table}
+$$\begin{tabular}{c}
+\verb|ABCDEFGHIJKLMNOPQRSTUVWXYZ_abcdefghijklmnopqrstuvwxyz|\\
+{\tt :<=>|}\\
+\verb|#&@$|\\
+\verb|/*\|\\
+{\tt +-}\\
+{\tt !?}\\
+{\tt '`}\\
+\verb|^~|\\
+\verb|{}|\\
+{\tt [}\\
+{\tt ]}\\
+\end{tabular}
+$$
+\caption{Character classes for tokenization}
+\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.
+
+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{\%?\texttt{\%}!comment}\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
+preceded or followed by digits is part of a number Thus {\tt ..}
+and {\tt ...} are symbolic tokens while {\tt a.b} is just two tokens {\tt a}
+and {\tt b}. It conventional to use periods to separate tokens in this fashion
+when naming a variable that is more than one token long.
+
+\subsection{Variable Declarations}
+\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}.
+
+\begin{figure}[htp]
+\begin{ctabbing}
+$\tt \descr{variable} \rightarrow \descr{tag}\descr{suffix}$\\
+$\tt \descr{suffix} \rightarrow \descr{empty} \;|\;
+ \descr{suffix}\descr{subscript} \;|\; \descr{suffix}\descr{tag}$\\
+$\tt \descr{subscript} \rightarrow \descr{number} \;|\;
+ \hbox{\tt [}\descr{numeric expression}\hbox{\tt ]}$
+\end{ctabbing}
+\caption{The syntax for variable names.}
+\index{suffix?\tdescr{suffix}}\index{subscript?\tdescr{subscript}}
+\label{syvar}
+\end{figure}
+
+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}.
+
+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 nine types: numeric,
+path, transform, color, cmykcolor, 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{arrays}\index{[]?\texttt{[]}!array}
+instead, to declare the whole array:
+$$ \hbox{\tt numeric q[];} $$
+You can also declare ``multidimensional'' arrays\index{arrays!multidimensional}.
+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}
+followed by an optional type specifier \texttt{numeric}\index{internal
+ variables!\texttt{numeric}}\index{variables!internal!\texttt{numeric}}
+or \texttt{string}\index{internal
+ variables!\texttt{string}}\index{variables!internal!\texttt{string}}
+and a list of symbolic tokens. For example,
+$$\begin{verbatim}
+newinternal numeric n, m;
+newinternal string s, t;
+newinternal num;
+\end{verbatim}
+$$
+are valid declarations that declare three internal numeric variables
+\texttt{n}, \texttt{m}, and~\texttt{num} and two internal string
+variables \texttt{s} and~\texttt{t}.
+
+Internal variables always have known values, and these values can only
+be changed by using the assignment\index{assignment} operator
+{\tt:=}\index{:=?\texttt{:=}}. Internal numeric variables are initially
+zero and internal string variables are initially the empty
+string~\verb|""|, except that the Plain\index{Plain macros} macro
+package gives some of the variables different initial values. (The
+Plain macros are normally preloaded automatically as explained in
+Section~\ref{intro}.)
+
+Internal string variables have been introduced in MetaPost
+version~1.200. For backwards compatibility, if the type specifier is
+missing, internal variables default to a \texttt{numeric}\index{internal
+ variables!\texttt{numeric}}\index{variables!internal!\texttt{numeric}}
+type, as in the last example. The declarations \texttt{newinternal
+ numeric;} and \texttt{newinternal string;} are invalid and throw an
+error.
+
+
+\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}}
+$$ {\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}}%
+\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
+internal variable\index{internal variables}\index{variables!internal}
+{\tt
+labeloffset}\index{labeloffset?\texttt{labeloffset}}\label{Dlaboff}.
+
+\begin{figure}[htp]
+$$
+\begin{verbatim}
+beginfig(17);
+a=.7in; b=.5in;
+z0=(0,0);
+z1=-z3=(a,0);
+z2=-z4=(0,b);
+draw z1..z2..z3..z4..cycle;
+draw z1--z0--z2;
+label.top("a", .5[z0,z1]);
+label.lft("b", .5[z0,z2]);
+dotlabel.bot("(0,0)", z0);
+endfig;
+\end{verbatim}
+\qquad \mathcenter{\includegraphics{mpman-17.mps}}
+$$
+\caption{MetaPost code and the resulting output}
+\label{fig16}
+\end{figure}
+
+Figure~\ref{fig16} also illustrates the
+{\tt dotlabel}\index{dotlabel?\texttt{dotlabel}}\label{Ddotlab}
+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. The diameter of the dot drawn by the {\tt dotlabel} statement
+is determined by the value of the internal variable {\tt
+ dotlabeldiam}\index{dotlabeldiam?\texttt{dotlabeldiam}}\label{Ddotlabdiam}.
+Default value is 3bp.
+
+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
+returns the label as a \tdescr{picture primary} instead of actually drawing it.
+Thus
+$$ \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}
+$$ \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);} $$
+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:="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.,
+$$ \hbox{\tt defaultscale := 12pt/fontsize defaultfont;} $$
+
+\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\index{PostScript!fonts} fonts, but the names for
+them are system-dependent. Some typical ones are {\tt ptmr8r} for
+Times-Roman\index{Times-Roman}, \ttt{pplr8r} for Palatino\index{Palatino},
+and \ttt{phvr} for Helvetica\index{Helvetica}. The Fontname document,
+available at \url{http://tug.org/fontname}, has much more information
+about font names and \TeX. A \TeX\index{TeX?\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 itself 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} $$
+in a MetaPost input file, the \tdescr{typesetting commands} get processed by
+\TeX\ and translated into a picture expression
+(actually a \tdescr{picture primary}) that can be used in a {\tt label}
+or {\tt dotlabel} statement. Any spaces after {\tt btex} or before {\tt etex}
+are ignored. For instance, the statement
+$$ \hbox{\verb|label.lrt(btex $\sqrt x$ etex, (3,sqrt 3)*u)|} $$
+in Figure~\ref{fig17} places the label $\sqrt x$ at the lower right of the
+point {\tt (3,sqrt 3)*u}.
+
+\begin{figure}[htp]
+$$
+\begin{verbatim}
+beginfig(18);
+numeric u;
+u = 1cm;
+draw (0,2u)--(0,0)--(4u,0);
+pickup pencircle scaled 1pt;
+draw (0,0){up}
+ for i=1 upto 8: ..(i/2,sqrt(i/2))*u endfor;
+label.lrt(btex $\sqrt x$ etex, (3,sqrt 3)*u);
+label.bot(btex $x$ etex, (2u,0));
+label.lft(btex $y$ etex, (0,u));
+endfig;
+\end{verbatim}
+\qquad \mathcenter{\includegraphics{mpman-18.mps}}
+$$
+\caption{Arbitrary \TeX\ as labels}
+\label{fig17}
+\end{figure}
+
+Figure~\ref{fig18} illustrates some of the more complicated things that can
+be done with labels. Since the result of {\tt btex} \ldots {\tt etex} is
+a picture, it can be operated on like a picture. In particular, it is possible
+to apply transformations to pictures. We have not discussed the syntax for
+this yet, but a \tdescr{picture secondary}
+can be\index{rotated text}\index{rotated?\texttt{rotated}}
+$$ \descr{picture secondary}\, {\tt rotated}\, \descr{numeric primary} $$
+This is used in Figure~\ref{fig18} to rotate the label ``$y$ axis'' so that
+it runs vertically.
+
+\begin{figure}[htp]
+$$
+\begin{verbatim}
+beginfig(19);
+numeric ux, uy;
+120ux=1.2in; 4uy=2.4in;
+draw (0,4uy)--(0,0)--(120ux,0);
+pickup pencircle scaled 1pt;
+draw (0,uy){right}
+ for ix=1 upto 8:
+ ..(15ix*ux, uy*2/(1+cosd 15ix))
+ endfor;
+label.bot(btex $x$ axis etex, (60ux,0));
+label.lft(btex $y$ axis etex rotated 90,
+ (0,2uy));
+label.lft(
+ btex $\displaystyle y={2\over1+\cos x}$ etex,
+ (120ux, 4uy));
+endfig;
+\end{verbatim}
+\qquad \mathcenter{\includegraphics{mpman-19.mps}}
+$$
+\caption{\TeX\ labels with display math, and rotated by MetaPost}
+\label{fig18}
+\end{figure}
+
+Another complication in Figure~\ref{fig18} is the use of the displayed equation
+$$y={2\over 1+\cos x}$$
+as a label. It would be more natural to code this as
+$$ \hbox{\verb|$$y={2\over 1+\cos x}$$|} $$
+but this would not work because
+\TeX\ typesets the labels in ``horizontal mode.''
+
+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: MetaPost stores all {\tt btex}\index{btex?\texttt{btex}}
+\ldots\ {\tt etex}\index{etex?\texttt{etex}} blocks in a temporary
+file and then runs \TeX\ on that file. If the environment variable
+\ttindex{MPTEXPRE} is set to the name of an existing file, its content
+will be prepended to the output file for processing by \TeX. 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.
+
+Once the \TeX\ run is finished, MetaPost translates the resulting
+DVI\index{dvi file?{\tt dvi} file}\index{files!dvi?{\tt dvi}} file into
+low level MetaPost commands that are then read instead of the {\tt btex}
+\ldots\ {\tt etex} blocks. If the main file is {\tt fig.mp}, the
+translated \TeX\ material is placed in a file named {\tt
+ fig.mpx}\index{mpx file?{\tt mpx} file}\index{files!mpx?{\tt mpx}}.
+
+The conversion normally runs silently without any user intervention but
+it could fail, for instance if one of the {\tt btex} \ldots {\tt etex}
+blocks contains an erroneous \TeX\index{TeX?\TeX!errors} command. In
+that case, the \TeX\ input is saved in the file {\tt
+ mpxerr.tex}\index{mpxerr.tex?\texttt{mpxerr.tex}} and the \TeX\ error
+messages appear in {\tt
+ mpxerr.log}\index{mpxerr.log?\texttt{mpxerr.log}}\index{log file?{\tt
+ log} file}\index{files!log?{\tt log}}.
+
+The DVI to MetaPost conversion route {\it does\/} understand virtual
+fonts, so you can use your normal \TeX\ font switching commands inside
+the label.
+
+
+\label{Dmakempx}
+In MetaPost versions before 1.100, the \TeX\ label preprocessing was
+handled by an external program that was called upon automatically by
+MetaPost. On Web2C-based systems, the preprocessor was normally named
+\ttindex{makempx}, which called the utility \ttindex{mpto} for the
+creation of the \TeX\ input file and the utility \texttt{dvitomp}\index{dvitomp?\texttt{dvitomp}} for
+the conversion to low level MetaPost. In the current MetaPost version,
+the work of this program is now done internally. However, if the
+environment variable \ttindex{MPXCOMMAND} is set, the whole label
+conversion mechanism will be delegated to the command given in that
+variable.
+
+
+\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 \dots\\
+&& \verb|label(btex|\, \descr{\TeX\ material using \hbox{\tt mymac.tex}}\,
+ \verb|etex, | \descr{some coordinates} \hbox{\tt );}\\
+&& \qquad \dots
+\end{eqnarray*}
+
+\label{Dtroffmode}
+On Unix\footnote{Unix is a registered trademark of Unix Systems
+Laboratories.}\index{Unix} 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 In PostScript output mode, 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}.
+
+In SVG mode, the text will probably render in a generic sans serif font.
+There may very well be problems with the encoding of non-ASCII characters:
+the font model of SVG is totally different from the model used by MetaPost.
+
+\item In PostScript output mode, 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.
+MetaPost sets \ttt{prologues} to~1 when the {\tt -troff} option is given
+on the command line.
+
+A \ttt{prologues:=1} setting is currently ignored in SVG output
+mode. The value is reserved for future use (possibly for mapping to
+\ttt{font-family}, \ttt{font-weight}, etc. properties).
+
+\item In PostScript output mode, when \ttt{prologues} is 2, the
+MetaPost output is EPSF and assumes
+that the text comes from PostScript\index{PostScript!fonts} 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.
+
+A \ttt{prologues:=2} setting is currently ignored in SVG output mode.
+The value is reserved for future use (possibly for external
+\ttt{font-face} definitions).
+
+\item In PostScript output mode, 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.
+
+In SVG mode, the font glyphs are converted to path definitions that
+are included at the top of the output file.
+
+\end{itemize}
+
+The correct setting for variable \texttt{prologues} depends on how
+MetaPost graphics are post-processed. Here are recommendations for some
+popular use-cases:
+
+\begin{description}
+
+\item[\normalfont\itshape Previewing:] Section~\ref{preview} discusses
+ previewing PostScript output.
+
+\item[\normalfont\itshape \TeX\ and dvips:] When including PostScript
+ figures into a \TeX\ document that is processed by \TeX\ and a DVI
+ output processer, e.g., dvips\index{dvips}, variable
+ \texttt{prologues} should \emph{not} be set to the value~1, unless the
+ used fonts are known to be resident in the PostScript interpreter.
+ Make sure that variable \texttt{prologues} is set to either~0 (font
+ inclusion handled by dvips, but without re-encoding support), 2 (font
+ inclusion by dvips, with font re-encoding if necessary), or~3 (font
+ inclusion and re-encoding by MetaPost). Value~3 is safest, but may
+ result in slightly larger output.
+
+\item[\normalfont\itshape pdf\TeX:] When generating PDF files with
+ pdf\TeX\ (and the mptopdf\index{mptopdf} bundle), variable
+ \texttt{prologues} is not relevant.
+
+\item[\normalfont\itshape PostScript in external applications:] Some
+ text\index{text processor} processors or graphics applications can
+ directly import EPSF files, while for others MetaPost's PostScript
+ output has to be converted to a different vector or even a bitmap
+ format first. In any case, as soon as PostScript graphics generated
+ by MetaPost are leaving the \TeX\ ecosystem, variable
+ \texttt{prologues} should be set to~3, so that all needed fonts are
+ embedded (as a subset).
+
+\item[\normalfont\itshape SVG output:] Converting font glyphs to paths
+ by setting variable \texttt{prologues} to~3 is currently the only
+ reliable way to export text objects to SVG.
+
+\item[\normalfont\itshape PNG output:] Variable \texttt{prologues} has
+ no effect in PNG output mode.
+
+\end{description}
+
+It is worth noting that the value of \ttt{prologues} has no effect on
+\MF\ fonts in your MetaPost files, i.\,e., MetaPost never embeds such
+fonts. Only output drivers, e.\,g., \ttt{dvips} or pdf\LaTeX\ will
+handle those.
+
+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, but have a look at
+section~\ref{mpimport} of this manual for some brief instructions that
+in many cases should work. 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.
+
+\subsection{Font Map Files}
+\label{fontmap}
+
+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\index{PostScript!fonts} 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}\label{Dfontmapfile} and
+\ttindex{fontmapline}\label{Dfontmapline}. Here is a simple example,
+specifying the map file for Latin Modern fonts in YandY (\LaTeX\ LY1)
+encoding:
+\begin{center}\begin{tabular}{l}
+\verb|prologues:=2;|\\
+\verb|fontmapfile "texnansi-lm.map";|\\
+\verb|beginfig(1);|\\
+\verb| draw "Helló, világ" infont "texnansi-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\index{URWPalladioL-Bold}\index{Palatino}
+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 \ttt{prologues} is set to two or three, yet there are no
+\ttt{fontmapfile} statements, MetaPost will attempt to locate a
+default map file, with a preference to read {\tt mpost.map}. If that
+fails, it will also attempt either {\tt troff.map} or {\tt
+pdftex.map}, depending on whether or not troff mode is enabled. 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 \texttt{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}, which 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)} $$
+
+If it is not convenient to use a string constant for the left argument of
+{\tt infont}, you can use\index{char?\texttt{char}}\label{Dchar}
+$$ {\tt char}\, \descr{numeric primary} $$
+to select a character based on its numeric position in the font.
+Thus
+$$ \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.
+
+Bare MetaPost does not do any kind of input reencoding, so when
+you use {\tt infont} string for labels (instead of {\tt btex} \ldots\
+{\tt etex}), the string has to be specified in the font encoding.
+
+
+\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?\texttt{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} is equivalent to
+$$\begin{verbatim}
+(llcorner p--lrcorner p--urcorner p--ulcorner p--cycle)
+\end{verbatim}
+$$
+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]
+$$ \includegraphics{mpman-20.mps} $$
+\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}}
+$$ {\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. The path has to be a cycle, i.e., it must
+be a closed 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|} $$
+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
+$$ {\tt fill}\, \descr{path expression} $$
+the argument should be a cyclic path, i.e., a path that describes a
+closed curve via the \verb|..cycle| or \verb|--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\index{non-zero fill
+ rule}\index{fill rule!non-zero}\index{PostScript!fill
+ rule}~\cite{ad:red2}.
+
+\begin{figure}[htp]
+$$ \begin{verbatim}
+beginfig(21);
+path p;
+p = (-1cm,0)..(0,-1cm)..(1cm,0);
+fill p{up}..(0,0){-1,-2}..{up}cycle;
+draw p..(0,1cm)..cycle;
+endfig;
+\end{verbatim}
+\qquad \mathcenter{\includegraphics{mpman-21.mps}}
+$$
+\caption{MetaPost code and the corresponding output.}
+\label{fig20}
+\end{figure}
+
+The general {\tt fill} statement\index{withcolor?\texttt{withcolor}}\label{Dwithcolor}
+$$ {\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. The $\descr{color expression}$ can have five possible
+values, mapping to four possible color models:
+
+$$
+\begin{tabular}{ll}
+Actual input & Remapped meaning\\\hline
+{\tt withcolor} $\descr{rgbcolor} c$ & withrgbcolor\index{withrgbcolor?\texttt{withrgbcolor}}\label{Dwithrgbcolor} $c$\\
+{\tt withcolor} $\descr{cmykcolor} c$ & withcmykcolor\index{withcmykcolor?\texttt{withcmykcolor}}\label{Dwithcmykcolor} $c$\\
+{\tt withcolor} $\descr{numeric} c$ & withgreyscale\index{withgreyscale?\texttt{withgreyscale}}\label{Dwithgreyscale} $c$\\
+{\tt withcolor} $\descr{false}$ & withoutcolor\index{withoutcolor?\texttt{withoutcolor}}\label{Dwithoutcolor} \\
+{\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
+variable \ttindex{defaultcolormodel}\label{Ddefaultcolormodel}.
+Table~\ref{dfltcmod} lists the valid values.
+\begin{table}
+\centering
+\begin{tabular}{|c|l|}
+\hline
+Value & Color model\\\hline
+1 & no model\\
+3 & greyscale\\
+5 & rgb (default)\\
+7 & cmyk\\
+\hline
+\end{tabular}
+\caption{Supported color models.}
+\label{dfltcmod}
+\end{table}
+
+
+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 {\tt
+ fullcircle}. Path~{\tt ab} is then initialized using a predefined
+macro {\tt buildcycle} that will be discussed shortly.
+
+\begin{figure}[htp]
+$$ \begin{verbatim}
+beginfig(22);
+path a, b, aa, ab;
+a = fullcircle scaled 2cm;
+b = a shifted (0,1cm);
+aa = halfcircle scaled 2cm;
+ab = buildcycle(aa, b);
+picture pa, pb;
+pa = thelabel(btex $A$ etex, (0,-.5cm));
+pb = thelabel(btex $B$ etex, (0,1.5cm));
+fill a withcolor .7white;
+fill b withcolor .7white;
+fill ab withcolor .4white;
+unfill bbox pa;
+draw pa;
+unfill bbox pb;
+draw pb;
+label.lft(btex $U$ etex, (-1cm,.5cm));
+draw bbox currentpicture;
+endfig;
+\end{verbatim}
+\qquad \mathcenter{\includegraphics{mpman-22.mps}}
+$$
+\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
+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}.
+
+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}}
+$$ {\tt draw}\, \descr{picture expression} $$
+adds them to {\tt currentpicture}\index{currentpicture?\texttt{currentpicture}}
+so that they overwrite a portion of what has
+already been drawn. In Figure~\ref{fig21} just the white rectangles produced by
+{\tt unfill} get overwritten.
+
+\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
+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]
+$$ {\includegraphics{mpman-123.mps} \atop (a)}
+ \qquad {\includegraphics{mpman-223.mps} \atop (b)}
+$$
+\caption[A demonstration of cycle building]
+ {(a)~The semicircular path~{\tt aa}
+ with a dashed line marking path {\tt b}; (b)~paths~{\tt aa} and {\tt b}
+ with the portions selected by {\tt buildcycle} shown by heavy lines.}
+\label{fig22}
+\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}}
+$$ \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.
+
+\begin{figure}[htp]
+$$ \begin{verbatim}
+beginfig(24);
+h=2in; w=2.7in;
+path p[], q[], pp;
+for i=2 upto 4: ii:=i**2;
+ p[i] = (w/ii,h){1,-ii}...(w/i,h/i)...(w,h/ii){ii,-1};
+endfor
+q0.5 = (0,0)--(w,0.5h);
+q1.5 = (0,0)--(w/1.5,h);
+pp = buildcycle(q0.5, p2, q1.5, p4);
+fill pp withcolor .7white;
+z0=center pp;
+picture lab; lab=thelabel(btex $f>0$ etex, z0);
+unfill bbox lab; draw lab;
+draw q0.5; draw p2; draw q1.5; draw p4;
+dotlabel.top(btex $P$ etex, p2 intersectionpoint q0.5);
+dotlabel.rt(btex $Q$ etex, p2 intersectionpoint q1.5);
+dotlabel.lft(btex $R$ etex, p4 intersectionpoint q1.5);
+dotlabel.bot(btex $S$ etex, p4 intersectionpoint q0.5);
+endfig;
+\end{verbatim}
+\atop \mathcenter{\includegraphics{mpman-24.mps}}
+$$
+\caption{MetaPost code and the corresponding output.}
+\label{fig23}
+\end{figure}
+
+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.
+
+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}
+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.
+
+\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
+$$ \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
+$$ \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 {\sl The \MF book} \cite[Chapter 14]{kn:c}).
+
+\begin{figure}[htp]
+$$ \includegraphics{mpman-25.mps} $$
+\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}
+$$ {\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
+$$ \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}
+$$ {\tt length}\, \descr{path primary} $$
+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
+$$ {\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$.
+
+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$,
+$$ 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
+$$ p_1\ {\tt cutafter}\ p_2 $$
+tries to cut off the part of $p_1$ after its last intersection with $p_2$.
+
+The control points of a path can be requested by the two operators
+\index{precontrol of?\texttt{precontrol of}}
+\index{postcontrol of?\texttt{postcontrol of}}
+\label{Dprepostctrl}
+\begin{eqnarray*}
+ {\tt precontrol}\, \descr{numeric expression}\, {\tt of}\, \descr{path primary},\\
+ {\tt postcontrol}\, \descr{numeric expression}\, {\tt of}\, \descr{path primary}.
+\end{eqnarray*}
+
+For integer time values~$t$, these operators return the control points
+before and after a cardinal point of a path. A segment
+$z_{t-1}\verb|..|z_t$ of a path~$p$ has therefore control points
+$$ {\tt postcontrol}\ t-1\ {\tt of}\ p
+$$
+and
+$$ {\tt precontrol}\ t\ {\tt of}\ p.
+$$
+
+For decimal time values, {\tt precontrol of} returns the last control
+point of sub-path $(0, t)$ and {\tt postcontrol of} returns the first
+control point of sub-path $(t, \infty)$ of a path. In other words, the
+control points at fractional time values correspond to a virtual
+cardinal point inserted at the given time value without modifying path
+shape.
+
+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}.
+
+\begin{figure}[htp]
+$$ \begin{verbatim}
+beginfig(26);
+numeric scf, #, t[];
+3.2scf = 2.4in;
+path fun;
+# = .1; % Keep the function single-valued
+fun = ((0,-1#)..(1,.5#){right}..(1.9,.2#){right}..{curl .1}(3.2,2#))
+ yscaled(1/#) scaled scf;
+x1 = 2.5scf;
+for i=1 upto 2:
+ (t[i],whatever) =
+ fun intersectiontimes ((x[i],-infinity)--(x[i],infinity));
+ z[i] = point t[i] of fun;
+ z[i]-(x[i+1],0) = whatever*direction t[i] of fun;
+ draw (x[i],0)--z[i]--(x[i+1],0);
+ fill fullcircle scaled 3bp shifted z[i];
+endfor
+label.bot(btex $x_1$ etex, (x1,0));
+label.bot(btex $x_2$ etex, (x2,0));
+label.bot(btex $x_3$ etex, (x3,0));
+draw (0,0)--(3.2scf,0);
+pickup pencircle scaled 1pt;
+draw fun;
+endfig;
+\end{verbatim}
+\atop \includegraphics{mpman-26.mps}
+$$
+\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,
+$$ {\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.
+
+There is also an predefined macro \index{directionpoint
+of?\texttt{directionpoint of}}\label{Ddpntof}
+$$ {\tt directionpoint}\, \descr{pair expression}\, {\tt of}\,
+ \descr{path primary}
+$$
+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 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},
+$$ \hbox{\tt arctime a of p} $$
+gives the time~{\tt t} such that
+$$ \hbox{\tt arclength subpath (0,t) of p} = {\tt a}. $$
+
+The operator {\tt
+ envelope}\index{envelope?\texttt{envelope}}\label{Denvelop} %
+returns the envelope of a path {\tt p} drawn with a polygonal pen,
+and returns an error if the pen is not polygonal.
+Figure~\ref{fig261} shows the envelope of an approximation of an elliptical pen.
+
+\begin{figure}[htp]
+$$ \begin{verbatim}
+beginfig(261);
+path p[] ;
+pen mypen ;
+pen mypenC;
+numeric L ;
+numeric S ;
+L:=10;
+Sa:=1;
+Sb:=2;
+Rot=32;
+p[-1] := ( (Sa*cosd(0),Sb*sind(0)) for i=1 upto L-1:
+ -- (Sa*cosd(i/L*360), Sb*sind(i/L*360)) endfor -- cycle ) rotated Rot;
+mypen := makepen(p[-1]) ;
+mypenC:= (pencircle xscaled 2Sa yscaled 2Sb) rotated Rot;
+p0 := (0,0){down} .. {up} (100,0) ;
+p1 := envelope mypen of p0 ;
+draw p1 withcolor black withpen pencircle scaled 0.2pt ;
+draw p0 withcolor 0.8white withpen mypenC;
+for t=1 upto length(p1):
+ draw (point t of p1) withpen pencircle scaled 0.8pt;
+endfor;
+endfig;
+\end{verbatim}
+\atop \includegraphics[width=0.9\textwidth]{mpman-261.mps}
+$$
+\caption{Example of envelope}
+\label{fig261}
+\end{figure}
+
+
+
+\subsection{Affine Transformations}
+\label{transsec}
+\index{transform type}
+
+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.
+
+Including {\tt scaled} and {\tt yscaled}, there are seven transformation
+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*}
+ (x,y){\tt\ shifted\ }(a,b) &=& (x+a,\, y+b); \\
+ (x,y){\tt\ rotated\ }\theta &=& (x\cos\theta-y\sin\theta,\,
+ x\sin\theta+y\cos\theta); \\
+ (x,y){\tt\ slanted\ }a &=& (x+ay,\, y); \\
+ (x,y){\tt\ scaled\ }a &=& (ax,\, ay); \\
+ (x,y){\tt\ xscaled\ }a &=& (ax,\, y); \\
+ (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
+$$ (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
+$$ \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
+expression of type transform as follows:
+$$ \begin{verbatim}
+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 $90^\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.
+
+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 reflectedabout(}p, q\hbox{\tt )} $$
+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
+$$ \hbox{\tt T = identity reflectedabout((2,0), (0,2))}. $$
+
+\begin{figure}[htp]
+\begin{ctabbing}
+$\tt \descr{pair secondary} \rightarrow
+ \descr{pair secondary} \descr{transformer}$\\
+$\tt \descr{path secondary} \rightarrow
+ \descr{path secondary} \descr{transformer}$\\
+$\tt \descr{picture secondary} \rightarrow
+ \descr{picture secondary} \descr{transformer}$\\
+$\tt \descr{pen secondary} \rightarrow
+ \descr{pen secondary} \descr{transformer}$\\
+$\tt \descr{transform secondary} \rightarrow
+ \descr{transform secondary} \descr{transformer}$\\[6pt]
+$\tt \descr{transformer} \rightarrow rotated \descr{numeric primary}$\\
+$\tt \qquad \;|\; scaled \descr{numeric primary}$\\
+$\tt \qquad \;|\; shifted \descr{pair primary}$\\
+$\tt \qquad \;|\; slanted \descr{numeric primary}$\\
+$\tt \qquad \;|\; transformed \descr{transform primary}$\\
+$\tt \qquad \;|\; xscaled \descr{numeric primary}$\\
+$\tt \qquad \;|\; yscaled \descr{numeric primary}$\\
+$\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 )}$
+\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
+$$ p = q{\tt\ transformed\ }T $$
+then
+$$ q = p{\tt\ transformed\ inverse\ }T. $$
+
+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
+$$ \begin{verbatim}
+(0,1) transformed T' = (3,4);
+(1,1) transformed T' = (7,1);
+(1,0) transformed T' = (4,-3);
+\end{verbatim}
+$$
+allow MetaPost to determine that the transform {\tt T'} is a combination of
+rotation and scaling with
+$$\openup\jot
+ \tabskip=0pt plus 1fil
+ \halign to\displaywidth{\tabskip=0pt
+ \hfil$\displaystyle{#}$& $\displaystyle{{}#}$\hfil \qquad&
+ \hfil$\displaystyle{#}$& $\displaystyle{{}#}$\hfil
+ \tabskip=0pt plus 1fil\cr
+\noalign{\vskip-\jot}
+ t_{xx}&=4,& t_{yx}&=-3,\cr
+ t_{yx}&=3,& t_{yy}&=4,\cr
+ 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}}%
+\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},
+$$
+where {\tt T} is a transform. For instance, Figure~\ref{fig27} uses the
+equations
+$$ \hbox{\tt xxpart T=yypart T; yxpart T=-xypart T} $$
+to specify that {\tt T} is shape preserving; i.e., it is a combination of
+rotating, shifting, and uniform scaling.
+
+\begin{figure}[htp]
+$$\begin{verbatim}
+beginfig(28);
+path p[];
+p1 = fullcircle scaled .6in;
+z1=(.75in,0)=-z3;
+z2=directionpoint left of p1=-z4;
+p2 = z1..z2..{curl1}z3..z4..{curl 1}cycle;
+fill p2 withcolor .4[white,black];
+unfill p1;
+draw p1;
+transform T;
+z1 transformed T = z2;
+z3 transformed T = z4;
+xxpart T=yypart T; yxpart T=-xypart T;
+picture pic;
+pic = currentpicture;
+for i=1 upto 2:
+ pic:=pic transformed T;
+ draw pic;
+endfor
+dotlabels.top(1,2,3); dotlabels.bot(4);
+endfig;
+\end{verbatim}
+\quad \mathcenter{\includegraphics{mpman-28.mps}}
+$$
+\caption{MetaPost code and the resulting ``fractal'' figure}
+\label{fig27}
+\end{figure}
+
+
+\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}}\label{Ddashed}
+$$ {\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}.
+
+\begin{figure}[htp]
+$$ \includegraphics{mpman-29.mps} $$
+\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}}.
+
+\begin{figure}[htp]
+$$ \includegraphics{mpman-30.mps} $$
+\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:
+$$ \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
+last 6bp of the first copy of the dash pattern will merge with the first 6bp of
+the next copy to form a dash 12bp long. The general syntax for the
+{\tt dashpattern} function is shown in Figure~\ref{sydash}.
+
+\begin{figure}[htp]
+\begin{ctabbing}
+$\tt \descr{dash pattern} \rightarrow dashpattern
+ \hbox{\tt (}\descr{on/off list}\hbox{\tt )}$\\
+$\tt \descr{on/off list} \rightarrow
+ \descr{on/off list}\descr{on/off clause} \;|\; \descr{on/off clause}$\\
+$\tt \descr{on/off clause} \rightarrow on \descr{numeric tertiary}
+ \;|\; off \descr{numeric tertiary}$
+\end{ctabbing}
+\caption{The syntax for the {\tt dashpattern} function}
+\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
+$$ \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:
+$$ \includegraphics{mpman-31.mps} $$
+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
+${\rm shift}(P({\tt d}),x)$ be the result of shifting {\tt d} by~$x$.
+The pattern resulting from infinite replication is
+$$ \bigcup_{{\rm integers}\ n} {\rm shift}(P(d),\, n\cdot\ell(d)), $$
+where $\ell(d)$ measures the length of $P(d)$. The most restrictive possible
+definition of this length is $d_{\rm max}-d_{\rm min}$,
+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}}.
+
+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}
+beginfig(32);
+draw dashpattern(on 15bp off 15bp) dashed evenly;
+picture p;
+p=currentpicture;
+currentpicture:=nullpicture;
+draw fullcircle scaled 1cm xscaled 3 dashed p;
+endfig;
+\end{verbatim}
+\quad \mathcenter{\includegraphics{mpman-32.mps}}
+$$
+\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}%
+\index{withprescript?\texttt{withprescript}}\label{Dwithpre}
+$$
+and
+$$
+{\tt withpostscript} \descr{string expression}%
+\index{withpostscript?\texttt{withpostscript}}\label{Dwithpost}
+$$
+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.
+
+When you specify more than one {\tt withprescript} or more than one {\tt
+ withpostscript} option, be wary of the fact that the scripts use a
+form of nesting: the {\tt withprescript} items are written to the
+PostScript file in last in, first out order; whereas the {\tt
+ withpostscript} items are written in first in, first out order.
+
+\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}.
+
+\begin{figure}[htp]
+$$\begin{verbatim}
+beginfig(33);
+for i=0 upto 2:
+ z[i]=(0,40i); z[i+3]-z[i]=(100,30);
+endfor
+pickup pencircle scaled 18;
+draw z0..z3 withcolor .8white;
+linecap:=butt;
+draw z1..z4 withcolor .8white;
+linecap:=squared;
+draw z2..z5 withcolor .8white;
+dotlabels.top(0,1,2,3,4,5);
+endfig; linecap:=rounded;
+\end{verbatim}
+\qquad
+\mathcenter{\includegraphics{mpman-33.mps}}
+$$
+\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.
+
+\begin{figure}[htp]
+$$\begin{verbatim}
+beginfig(34);
+for i=0 upto 2:
+ z[i]=(0,50i); z[i+3]-z[i]=(60,40);
+ z[i+6]-z[i]=(120,0);
+endfor
+pickup pencircle scaled 24;
+draw z0--z3--z6 withcolor .8white;
+linejoin:=mitered;
+draw z1..z4--z7 withcolor .8white;
+linejoin:=beveled;
+draw z2..z5--z8 withcolor .8white;
+dotlabels.bot(0,1,2,3,4,5,6,7,8);
+endfig; linejoin:=rounded;
+\end{verbatim}
+\qquad
+\mathcenter{\includegraphics{mpman-34.mps}}
+$$
+\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.
+
+\begin{figure}[htp]
+$$ \includegraphics{mpman-35.mps} $$
+\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}.
+
+\begin{figure}[htp]
+$$\includegraphics{mpman-36.mps}$$
+\caption{Three ways of drawing arrows.}
+\label{fig36}
+\end{figure}
+
+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$,
+$$ {\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}}%
+\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
+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
+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.
+
+\begin{figure}[htp]
+$$ \includegraphics{mpman-37.mps} $$
+\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}:
+$$ {\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}
+$$ \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
+$$ \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).
+
+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
+$$ \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
+{\tt currentpen}\index{currentpen?\texttt{currentpen}} such that
+{\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
+$$ {\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.
+
+
+\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
+$$ {\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.
+
+\begin{figure}[htp]
+$$\begin{verbatim}
+beginfig(38);
+pickup pencircle scaled .2in yscaled .08 rotated 30;
+x0=x3=x4;
+z1-z0 = .45in*dir 30;
+z2-z3 = whatever*(z1-z0);
+z6-z5 = whatever*(z1-z0);
+z1-z6 = 1.2*(z3-z0);
+rt x3 = lft x2;
+x5 = .55[x4,x6];
+y4 = y6;
+lft x3 = bot y5 = 0;
+top y2 = .9in;
+draw z0--z1--z2--z3--z4--z5--z6 withcolor .7white;
+dotlabels.top(0,1,2,3,4,5,6);
+endfig;
+\end{verbatim}
+\quad \mathcenter{\includegraphics{mpman-38.mps}}
+$$
+\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,
+$$ {\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
+$$ \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
+$$ \hbox{\verb|makepen((-.5,-.5)--(.5,-.5)--(.5,.5)--(-.5,.5)--cycle)|} $$
+
+{\tt pensquare} and {\tt makepen} should not be used with dash
+patterns. See the end of Section~\ref{dashed-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}.
+
+\begin{figure}[htp]
+\begin{ctabbing}
+$\tt \descr{addto command} \rightarrow$\\
+$\tt \qquad addto \descr{picture variable} also
+ \descr{picture expression} \descr{option list}$\\
+$\tt \qquad \;|\; addto \descr{picture variable}
+ contour \descr{path expression} \descr{option list}$\\
+$\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 \;|\; 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}
+\caption{The syntax for primitive drawing statements}
+\label{sydraw}
+\index{option list?\tdescr{option list}}\index{addto also?\texttt{addto also}}\index{addto contour?\texttt{addto contour}}%
+\index{addto doublepath?\texttt{addto doublepath}}\index{withcolor?\texttt{withcolor}}\index{withpen?\texttt{withpen}}%
+\index{dashed?\texttt{dashed}}\index{drawing option?\tdescr{drawing option}}
+\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,
+$$ {\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}.
+
+\begin{table}[htp]
+$$\begin{tabular}{|l|l|} \hline
+\multicolumn1{|c|}{statement}& \multicolumn1{c|}{equivalent primitives}\\ \hline
+{\tt draw} {\it pic}& {\tt addto currentpicture also} {\it pic}\\
+{\tt draw} $p$& {\tt addto currentpicture doublepath} $p$
+ {\tt withpen} $q$\\
+{\tt fill} $c$& {\tt addto currentpicture contour} $c$\\
+{\tt filldraw} $c$& {\tt addto currentpicture contour} $c$ {\tt withpen} $q$\\
+{\tt undraw} {\it pic}& {\tt addto currentpicture also} {\it pic}
+ {\tt withcolor} $b$\\
+{\tt undraw} $p$& {\tt addto currentpicture doublepath} $p$
+ {\tt withpen} $q$
+ {\tt withcolor} $b$\\
+{\tt unfill} $c$& {\tt addto currentpicture contour} $c$
+ {\tt withcolor} $b$\\
+{\tt unfilldraw} $c$& {\tt addto currentpicture contour} $c$ {\tt withpen} $q$
+ {\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.}
+\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}:
+$$ {\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}}.
+Figure~\ref{fig40} illustrates clipping.
+
+\begin{figure}[htp]
+$$\begin{verbatim}
+beginfig(40);
+path p[];
+p1 = (0,0){curl 0}..(5pt,-3pt)..{curl 0}(10pt,0);
+p2 = p1..(p1 yscaled-1 shifted(10pt,0));
+p0 = p2;
+for i=1 upto 3: p0:=p0.. p2 shifted (i*20pt,0);
+ endfor
+for j=0 upto 8: draw p0 shifted (0,j*10pt);
+ endfor
+p3 = fullcircle shifted (.5,.5) scaled 72pt;
+clip currentpicture to p3;
+draw p3;
+endfig;
+\end{verbatim}
+\qquad
+\mathcenter{\includegraphics{mpman-40.mps}}
+$$
+\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}
+$$ {\tt shipout}\, \descr{picture expression} $$
+writes out a picture as a PostScript\index{PostScript} file whose
+file name is determined by
+{\tt outputtemplate}\index{outputtemplate?\texttt{outputtemplate}}
+(see Section~\ref{Doutputtemplate}). By default, the file 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}.
+
+\subsection{Directing Output to a Picture Variable}
+Sometimes, it might be desirable to save the output of a drawing
+operation and re-use them later. This can easily be done with
+MetaPost primitives like \ttt{addto}. On the other hand, since the
+higher-level drawing commands defined in the Plain macro package
+always write to the
+\ttt{currentpicture}\index{currentpicture?\texttt{currentpicture}},
+saving their output required to temporarily save \ttt{currentpicture},
+reset it to \ttt{nullpicture}\index{nullpicture?\texttt{nullpicture}},
+execute the drawing operations, save the \ttt{currentpicture} to a
+new \ttt{picture} variable and finally restore \ttt{currentpicture} to
+the saved state. In MetaPost version~0.60 a new macro
+$$ \hbox{\tt image( $\descr{drawing commands}$ )} $$%
+\index{image?\texttt{image}}\label{Dimage}%
+was introduced that eases this task. It takes as input a sequence of arbitrary
+drawing operations and returns a \ttt{picture} variable containing the
+corresponding output, without affecting {\tt currentpicture}.
+
+As an example, in the code of figure~\ref{fig55} an object \ttt{wheel} has
+been defined that saves the output of two \ttt{draw} operations as follows:
+\begin{figure}[b]
+$$ \includegraphics{mpman-55.mps} $$
+\caption{Copying objects with the \ttt{image} operator.}
+\label{fig55}
+\end{figure}
+$$\begin{verbatim}
+picture wheel;
+wheel := image(
+ draw fullcircle scaled 2u xscaled .8 rotated 30;
+ draw fullcircle scaled .15u xscaled .8 rotated 30;
+);
+\end{verbatim}
+$$
+This \ttt{wheel} object is re-used in the definition of another object \ttt{car}.
+Figure~\ref{fig55} shows three \ttt{car} objects drawn with two different slant
+values.
+
+
+\subsection{Inspecting the Components of a Picture}
+\label{piccomp}
+
+\mbox{}% Start paragraph here.
+\index{setbounds?\texttt{setbounds}|(}%
+\index{for within?\texttt{for within}|(}%
+%
+MetaPost pictures are composed of stroked lines, filled outlines, pieces
+of typeset text, clipping paths\index{clip?\texttt{clip}}, and
+{\tt setbounds}\index{setbounds?\texttt{setbounds}} paths. (A {\tt setbounds}
+path gives an artificial bounding box as is needed for \TeX\ output.)
+A picture can have many components of each type. They can be accessed via
+an iteration of the form
+$$ {\tt for}\ \descr{symbolic token}\ {\tt within}\
+ \descr{picture expression}\hbox{\tt:}\ \descr{loop text}\ {\tt endfor}
+$$\index{for within?\texttt{for within}}\label{Dforwithin}%
+The \tdescr{loop text} can be anything that is balanced with respect to
+{\tt for} and {\tt endfor}. The \tdescr{symbolic token} is a loop variable that
+scans the components of the picture in the order in which they were drawn. The
+component for a clipping or {\tt setbounds} path includes everything the path
+applies to. Thus if a single clipping or {\tt setbounds} path applies to
+everything in the \tdescr{picture expression}, the whole picture could be
+thought of as one big component. In order to make the contents of such a picture
+accessible, the {\tt for}\ldots{\tt within} iteration ignores the enclosing
+clipping or {\tt setbounds} path in this case. The number of components
+that a {\tt for}\ldots {\tt within} iteration would find is returned by
+$$ {\tt length}\ \descr{picture primary}\index{length?\texttt{length}}\label{DlengthPicture}$$
+
+\index{for within?\texttt{for within}|)}
+
+\mbox{}% Start paragraph here.
+\index{stroked?\texttt{stroked}|(}%
+\index{filled?\texttt{filled}|(}%
+\index{textual?\texttt{textual}|(}%
+\index{clipped?\texttt{clipped}|(}%
+\index{bounded?\texttt{bounded}|(}%
+%
+Once the {\tt for}\ldots{\tt within} iteration has found a picture component,
+there are numerous operators for identifying it and extracting relevant
+information. The operator
+$$ {\tt stroked}\ \descr{primary expression} $$\index{stroked?\texttt{stroked}}\label{Dstroked}%
+tests whether the expression is a known picture whose first component is a
+stroked line. Similarly, the {\tt filled}\index{filled?\texttt{filled}}\label{Dfilled}
+and {\tt textual}\index{textual?\texttt{textual}}\label{Dtextual} operators
+return {\tt true} if the first component is a filled outline or a piece of
+typeset text. The {\tt clipped}\index{clipped?\texttt{clipped}}\label{Dclipped}
+and {\tt bounded}\index{bounded?\texttt{bounded}}\label{Dbounded} operators
+test whether the argument is a known picture that starts with a clipping
+path or a {\tt setbounds} path. This is true if the first component is
+clipped or bounded or if the entire picture is enclosed in a clipping or
+{\tt setbounds} path.
+
+\mbox{}% Start paragraph here.
+\index{pathpart?\texttt{pathpart}|(}%
+\index{penpart?\texttt{penpart}|(}%
+\index{dashpart?\texttt{dashpart}|(}%
+%
+There are also numerous part extraction operators that test the first component
+of a picture. If {\tt p} is a picture and {\tt stroked p} is true,
+{\tt pathpart p}\index{pathpart?\texttt{pathpart}}\label{Dpathpart} is the
+path describing the line that got stroked,
+{\tt penpart p}\index{penpart?\texttt{penpart}}\label{Dpenpart} is the pen
+that was used, {\tt dashpart p}\index{dashpart?\texttt{dashpart}}\label{Ddashpart}
+is the dash pattern. If the line is not dashed, {\tt dashpart p}
+returns an empty picture.
+
+The same part extraction operators work when {\tt filled p} is true, except
+that {\tt dashpart p} is not meaningful in that case.
+
+For text components, {\tt textual p} is true,
+{\tt textpart p}\index{textpart?\texttt{textpart}}\label{Dtextpart}
+gives the text that got typeset,
+{\tt fontpart p}\index{fontpart?\texttt{fontpart}}\label{Dfontpart}
+gives the font that was used, and {\tt xpart~p}\index{xpart?\texttt{xpart}}\index{ypart?\texttt{ypart}}\index{xxpart?\texttt{xxpart}}%
+\index{xypart?\texttt{xypart}}\index{yxpart?\texttt{yxpart}}\index{yypart?\texttt{yypart}},
+{\tt ypart~p}, {\tt xxpart~p}, {\tt xypart~p}, {\tt yxpart~p}, {\tt yypart~p}
+tell how the text has been shifted, rotated, and scaled.
+
+\mbox{}% Start paragraph here.
+\index{colorpart?\texttt{colorpart}|(}%
+\index{colormodel?\texttt{colormodel}|(}%
+\index{redpart?\texttt{redpart}|(}%
+\index{greenpart?\texttt{greenpart}|(}%
+\index{bluepart?\texttt{bluepart}|(}%
+\index{cyanpart?\texttt{cyanpart}|(}%
+\index{magentapart?\texttt{magentapart}|(}%
+\index{yellowpart?\texttt{yellowpart}|(}%
+\index{blackpart?\texttt{blackpart}|(}%
+\index{greypart?\texttt{greypart}|(}%
+%
+Finally, for \ttt{stroked}, \ttt{filled} and \ttt{textual} components
+the color can be examined by saying
+$$ {\tt colorpart}\
+\descr{item}\index{colorpart?\texttt{colorpart}}\label{Dcolorpart}
+$$
+This returns the color of a component in its respective color model.
+The color model of a component can be identified by the
+\ttt{colormodel}\index{colormodel?\texttt{colormodel}}\label{Dcolormodel}
+operator (cf. Table~\ref{dfltcmod} on p.~\pageref{dfltcmod}).
+
+For more fine grained color operations there are operators to extract
+single color components of an item. Depending on the color model the
+color of a picture component \ttt{p} is
+$$ \hbox{\tt (cyanpart p, magentapart p, yellowpart p, blackpart p)} $$%
+\index{cyanpart?\texttt{cyanpart}}\index{magentapart?\texttt{magentapart}}\index{yellowpart?\texttt{yellowpart}}\index{blackpart?\texttt{blackpart}}
+or
+$$ \hbox{\tt (redpart p, greenpart p, bluepart p)} $$%
+\index{redpart?\texttt{redpart}}\index{greenpart?\texttt{greenpart}}\index{bluepart?\texttt{bluepart}}
+or
+$$ \hbox{\tt greypart p} $$%
+\index{greypart?\texttt{greypart}}
+or
+$$ \hbox{\tt false}. $$
+
+Note, color part operators {\tt redpart}, {\tt cyanpart} etc. have to
+match the color model of the picture component in question. Applying a
+non-matching color part operator to a picture component triggers an
+error and returns a \ttindex{black} color part in the requested color
+model. That is, for the code
+$$\begin{verbatim}
+picture pic;
+pic := image(fill unitsquare scaled 1cm withcolor (0.3, 0.6, 0.9););
+for item within pic:
+ show greypart item;
+ show cyanpart item;
+ show blackpart item;
+ show redpart item;
+endfor
+\end{verbatim}
+$$
+the output is (omitting the error messages)
+$$\begin{verbatim}
+>> 0
+>> 0
+>> 1
+>> 0.3
+\end{verbatim}
+$$
+since in grey scale color model black is {\tt 0} and in CMYK color model
+black is {\tt (0,0,0,1)}. For the matching RGB color model the true
+color component is returned.
+
+When {\tt clipped p} or {\tt bounded p} is true, {\tt pathpart p} gives the
+clipping or {\tt setbounds} path and the other part extraction operators are
+not meaningful. Such non-meaningful part extractions do not generate
+errors. Instead, they return null values or black color (components):
+the trivial path {\tt (0,0)} for {\tt pathpart},
+{\tt nullpen}\index{nullpen?\texttt{nullpen}}\label{Dnlpen} for {\tt penpart},
+an empty picture for {\tt dashpart},
+the null string for {\tt textpart} or {\tt fontpart},
+zero for {\tt colormodel},
+{\tt greypart},
+{\tt redpart}, {\tt greenpart}, {\tt bluepart},
+{\tt cyanpart}, {\tt magentapart}, {\tt yellowpart},
+one for {\tt blackpart}, and
+black in the current default color model for {\tt colorpart}.
+
+To summarize the discussion of mismatching part operators:
+\begin{enumerate}
+\item Asking for non-meaningful parts of an item---such as the {\tt
+ redpart} of a clipping path, the {\tt textpart} of a stroked item,
+ or the {\tt pathpart} of a textual item---is silently accepted and
+ returns a null value or a black color (component).
+\item Explicitly asking for a color part of a colored item in the wrong
+ color model returns a black color component. This operation triggers
+ an error.
+\end{enumerate}
+
+\index{setbounds?\texttt{setbounds}|)}
+\index{stroked?\texttt{stroked}|)}
+\index{filled?\texttt{filled}|)}
+\index{textual?\texttt{textual}|)}
+\index{clipped?\texttt{clipped}|)}
+\index{bounded?\texttt{bounded}|)}
+\index{pathpart?\texttt{pathpart}|)}
+\index{penpart?\texttt{penpart}|)}
+\index{dashpart?\texttt{dashpart}|)}
+\index{colormodel?\texttt{colormodel}|)}
+\index{colorpart?\texttt{colorpart}|)}
+\index{redpart?\texttt{redpart}|)}
+\index{greenpart?\texttt{greenpart}|)}
+\index{bluepart?\texttt{bluepart}|)}
+\index{cyanpart?\texttt{cyanpart}|)}
+\index{magentapart?\texttt{magentapart}|)}
+\index{yellowpart?\texttt{yellowpart}|)}
+\index{blackpart?\texttt{blackpart}|)}
+\index{greypart?\texttt{greypart}|)}
+
+
+\subsection{Decomposing the Glyphs of a Font}
+\label{glyphs}
+
+MetaPost provides a primitive to convert a
+glyph\index{glyph}\index{font!glyph} of a font in the Adobe Type~1
+Font\index{PostScript!fonts}\index{font!PostScript}\index{Adobe Type~1
+ Font}\index{font!Adobe Type~1} format into its constituent filled
+paths---the strokes---and store them in a picture variable. A glyph is
+the visual representation of a character in a font. A
+character\index{character}\index{font!character} is a certain
+slot\index{slot}\index{font!slot} (index) in a font with an associated
+meaning, e.g., the capital letter~``M'' or the exclamation mark. The
+meaning of a slot is defined by the font
+encoding\index{encoding}\index{font!encoding}. In general, the same
+character is represented by different glyphs in different fonts.
+Figure~\ref{glyphsample} shows some glyphs for the character at slot~103
+in the T1 encoding, i.e., the lower-case letter~``g''. All glyphs are
+at the same nominal size. Note, how glyphs may extend beyond their
+bounding box.
+\begin{figure}[htp]
+ \centering
+ \setlength{\fboxsep}{0pt}
+ \setlength{\fboxrule}{.125pt}
+ \fontsize{56pt}{56pt}\selectfont
+ \newcommand*{\showglyph}[4]{% a glyph with its bounding box
+ \fbox{\usefont{#1}{#2}{#3}{#4}g}%
+ }
+ \makebox[0pt][c]{% base line
+ \rule{.7\textwidth}{.125pt}%
+ }%
+ \makebox[0pt][c]{% glyphs
+ \showglyph{T1}{lmr}{m}{n}\hspace{.3em}
+ \showglyph{T1}{qag}{m}{n}\hspace{.3em}
+ \showglyph{T1}{qpl}{m}{it}\hspace{.3em}
+ \showglyph{T1}{qzc}{m}{it}%
+ }
+ \caption{Different glyphs representing the same character.}
+ \label{glyphsample}
+\end{figure}
+
+The glyphs of an Adobe Type~1
+font\index{PostScript!fonts}\index{font!PostScript}\index{Adobe Type~1
+ Font}\index{font!Adobe Type~1} are composed of two types of contours:
+Clockwise oriented contours add to the shape of a glyph and are filled
+with black ink. Counter-clockwise oriented contours
+erase\index{erasing} parts of other contours, i.e., make them
+transparent again. To save the contours of a glyph in a picture, the
+\verb|glyph|\index{glyph?\texttt{glyph}}\label{Dglyph} operator can be
+used. There are two ways to identify a glyph in a font:
+\begin{eqnarray*}
+ & \verb|glyph|\, \descr{numeric expression}\, \verb|of|\,
+ \descr{string expression}\\
+ \noalign{\hbox{and}}
+ & \verb|glyph|\, \descr{string expression}\, \verb|of|\,
+ \descr{string expression}\rlap{\quad\mbox{.}}
+\end{eqnarray*}
+
+If the first argument is a numeric expression, it has to be a slot
+number between 0 and~255. Fractional slot numbers are rounded to the
+nearest integer value. Slot numbers outside the allowed range trigger
+an error. If the first argument is string, it has to be a CharString
+name\index{CharString name} in the PostScript font's source file. A
+CharString name is a unique text label for a glyph in a PostScript font
+(a font encoding actually maps CharStrings to slots). This second
+syntax can be used to address glyphs without having to think about font
+encodings. The second argument to the \verb|glyph| operator is a string
+containing a font name (section~\ref{text} has more on font names).
+
+The \verb|glyph| operator looks-up the font name in the font map to
+determine the encoding and to find the font's PostScript source file.
+It returns a picture consisting of the glyph's contour lines, explicitly
+filled black and white in the greyscale color model according to the
+rules laid out above. Additionally, the contours are sorted, such that
+all black contours are drawn before white contours. The filling and
+sorting is necessary for the picture to resembles the corresponding
+glyph visually\footnote{Plain contours already carry enough information
+ to completely reconstruct a glyph, the orientation of a contour can be
+ computed from its cardinal and control points. MetaPost has a
+ \texttt{turningnumber}\index{turningnumber?\texttt{turningnumber}}\label{Dturningnumber}
+ primitive to do that.}, since Adobe Type~1
+fonts\index{PostScript!fonts}\index{font!PostScript}\index{Adobe Type~1
+ Font}\index{font!Adobe Type~1} use a generalized variant of the
+non-zero winding number fill rule\index{non-zero fill rule}\index{fill
+ rule!non-zero}\index{PostScript!fill rule}, which MetaPost doesn't
+implement (MetaPost cannot handle non-contiguous paths). As a side
+effect, the interiors of the erasing\index{erasing} contours are an
+opaque white in the returned picture, while they were transparent in the
+original glyph. One can think of erasing contours to be unfilled (see
+p.~\pageref{Dunfill}). For instance, the following code saves the
+contours of the lower case letter~``g'', bound to slot~103 in the OT1
+encoding\index{OT1 encoding}\index{encoding!OT1}, in the
+Computer\index{Computer Modern Roman} Modern Roman font in a picture
+variable:
+
+$$
+\begin{verbatim}
+fontmapline "cmr10 CMR10 <cmr10.pfb";
+picture g;
+g := glyph 103 of "cmr10";
+\end{verbatim}
+$$
+
+The \verb|glyph| operator returns an empty picture, if the
+\texttt{.tfm}\index{tfm file?{\tt tfm} file}\index{files!tfm?{\tt tfm}}
+or \texttt{.pfb}\index{pfb file?{\tt pfb} file}\index{files!pfb?{\tt
+ pfb}} file cannot be found, if the encoding given in the font map
+cannot be found or the slot number is not covered by the encoding or if
+the CharString name cannot be found. Note, while MetaPost delegates the
+actual font handling to a rendering application for \verb|infont| and
+\verb|btex| \ldots\ \verb|etex| blocks, the \verb|glyph| operator
+directly operates on font ressources. For that reason, a font map entry
+is mandatory for the font in question, given either by
+\verb|fontmapline| or \verb|fontmapfile| (see
+section~\ref{Dfontmapline}).
+
+In Figure~\ref{fig56}, the contours of the upper case letter~``\v{D}''
+in the Latin\index{Latin Modern Roman} Modern Roman font are saved in a
+picture variable. The glyph is identified by its CharString name
+``Dcaron''\index{Dcaron}. The code then iterates over all contours and
+draws them together with their cardinal (black) and control points
+(red). As it turns out, many of the control points coincide with
+cardinal points in this glyph.
+
+\begin{figure}[htb]
+$$
+\begin{verbatim}
+fontmapfile "=lm-ec.map";
+beginfig(56);
+ picture q;
+ path p;
+ interim ahlength := 12bp;
+ interim ahangle := 25;
+ q := glyph "Dcaron" of "ec-lmr10" scaled .2;
+ for item within q:
+ p := pathpart item;
+ drawarrow p withcolor (.6,.9,.6)
+ withpen pencircle scaled 1.5;
+ for j=0 upto length p:
+ pickup pencircle scaled .7;
+ draw (point j of p -- precontrol j of p)
+ dashed evenly withcolor blue;
+ draw (point j of p -- postcontrol j of p)
+ dashed evenly withcolor blue;
+ pickup pencircle scaled 3;
+ draw precontrol j of p withcolor red;
+ draw postcontrol j of p withcolor red;
+ pickup pencircle scaled 2;
+ draw point j of p withcolor black;
+ endfor
+ endfor
+endfig;
+\end{verbatim}
+\qquad
+\mathcenter{\includegraphics{mpman-56.mps}}
+$$
+\caption{Iterating over the contours of a glyph}
+\label{fig56}
+\end{figure}
+
+The contours in a picture returned by the \verb|glyph| operator are no
+raw copies of the contours found in the font sources, but the
+\verb|glyph| operator applies a number of transformations to them.
+First, the direction of all contours is reversed, so that contours
+filled black become counter-clockwise oriented (mathematically positive)
+and contours filled white become clockwise oriented (mathematically
+negative). Second, in an Adobe Type~1
+font\index{PostScript!fonts}\index{font!PostScript}\index{Adobe Type~1
+ Font}\index{font!Adobe Type~1}, contours are in general closed by
+repeating the starting point before applying the \verb|closepath|
+operator\index{PostScript!closepath operator?\texttt{closepath}
+ operator}. The MetaPost representation of such a path would be:
+$$
+z_0\verb|..|\mbox{\itshape controls}\verb|..|z_1\verb|..| \cdots
+\verb|..|z_n\verb|..|\mbox{\itshape controls}\verb|..|z_0\verb|--cycle|
+$$
+However, a more natural MetaPost representation of that path would be:
+$$
+z_0\verb|..|\mbox{\itshape controls}\verb|..|z_1\verb|..| \cdots
+\verb|..|z_n\verb|..|\mbox{\itshape controls}\verb|..cycle|
+$$
+The \verb|glyph| operator transforms all paths into the latter
+representation, i.e., the last point is removed, whenever it matches the
+starting point. Finally, the picture returned by the \verb|glyph|
+operator is scaled, such that one font design unit\index{font!design
+ unit} equals one PostScript
+point\index{point!PostScript}\index{PostScript!point} (bp). A usual
+font design unit is a thousandth part of the font design
+size\index{font!design size}. Therefore, the returned picture will
+typically have a height of around 1000bp.
+
+Converting a text into plain curves is part of a process oftentimes
+called ``flattening\index{flattening}'' a document. During flattening,
+all hinting information in fonts are lost. Hinting information aid a
+rendering application in aligning certain parts of a glyph on a
+low-resolution output device. A flattened text may therefore look
+distorted on screen. In SVG output, all text is automatically
+flattened, if the internal variable
+\verb|prologues|\index{prologues?\texttt{prologues}} is set to~3 (see
+section~\ref{Dprologues}).
+
+
+\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.
+
+Macros with no arguments are very simple.
+A macro definition\index{replacement text?\tdescr{replacement text}}%
+\index{def?\texttt{def}}\index{enddef?\texttt{enddef}}
+$$ {\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
+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:
+$$\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.)
+
+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}}
+$$ {\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:
+\begin{eqnarray*}
+&& \hbox{\tt x23 = 3.1;}\\
+&& \hbox{\tt beginfig(17);}\\
+&& \qquad \vdots\\
+&& \hbox{\tt y3a=1; x23=2;}\\
+&& \qquad \vdots\\
+&& \hbox{\tt endfig;}\\
+&& \hbox{\tt show x23, y3a;}
+\end{eqnarray*}
+The result of the {\tt show}\index{show?\texttt{show}} command is
+$$\begin{verbatim}
+>> 3.1
+>> y3a
+\end{verbatim}
+$$
+indicating that {\tt x23} has returned to its former value of {\tt 3.1} and
+{\tt y3a} is completely unknown as it was at {\tt beginfig(17)}.
+
+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
+$$ {\tt save}\, \descr{symbolic token list} $$
+where \tdescr{symbolic token list} is a comma-separated list of
+tokens:\index{tokens!symbolic}
+\begin{ctabbing}
+$\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?\texttt{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}}
+$$ \hbox{\verb|>> %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}}
+$$ \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:
+\begin{eqnarray*}
+&& \hbox{\tt begingroup interim linecap:=butt;}\\
+&& {\tt draw}\, \descr{path expression}\, \hbox{\tt dashed evenly; endgroup}
+\end{eqnarray*}
+This saves the value of the
+internal variable\index{internal variables}\index{variables!internal}
+{\tt linecap} and temporarily
+gives it a new value without forgetting that {\tt linecap} is an internal
+variable. The general syntax is
+$$ {\tt interim}\, \descr{internal variable} \mathrel{\hbox{\tt:=}}
+ \descr{numeric expression} \;|\; \descr{string expression}
+$$
+
+
+\subsection{Parameterized Macros}
+
+The basic idea behind parameterized macros is to achieve greater flexibility by
+allowing auxiliary information to be passed to a macro. We have already seen
+that macro definitions can have formal parameters that represent expressions
+to be given when the macro is called. For instance a definition such as
+$$ \hbox{\tt def rotatedaround(expr z, d) = } \descr{replacement text}\,
+ {\tt enddef}
+$$
+allows the MetaPost interpreter to understand macro calls of the form
+$$\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}}
+$$ \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}}
+$$ {\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}}
+$$ {\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{middlepoint?\texttt{middlepoint}} 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;
+\end{verbatim}
+$$
+The complete syntax for {\tt if} tests is shown in Figure~\ref{syif}.
+It allows multiple {\tt if} tests like
+$$ \hbox{\tt if $e_1$: \ldots\ else: if $e_2$: \ldots\ else: \ldots\ fi fi} $$
+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
+middlepoint} like this:
+$$\begin{verbatim}
+def middlepoint(expr a) = if path a: (point .5*length a of
+ else: .5(llcorner a + urcorner fi a) enddef;
+\end{verbatim}
+$$
+
+\begin{figure}[htp]
+\begin{ctabbing}
+$\tt \descr{if test} \rightarrow if \descr{boolean expression} \hbox{\tt :}
+ \descr{balanced tokens} \descr{alternatives} fi$\\
+$\tt \descr{alternatives} \rightarrow \descr{empty}$\\
+$\tt \qquad \;|\; else\hbox{\tt :} \descr{balanced tokens}$\\
+$\tt \qquad \;|\; elseif \descr{boolean expression} \hbox{\tt :}
+ \descr{balanced tokens} \descr{alternatives}$
+\end{ctabbing}
+\caption{The syntax for {\tt if} tests.}
+\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.
+
+\begin{figure}[htp]
+$$\begin{verbatim}
+beginfig(42);
+pair a,b,c,d;
+b=(0,0); c=(1.5in,0); a=(0,.6in);
+d-c = (a-b) rotated 25;
+dotlabel.lft("a",a);
+dotlabel.lft("b",b);
+dotlabel.bot("c",c);
+dotlabel.llft("d",d);
+z0=.5[a,d];
+z1=.5[b,c];
+(z.p-z0) dotprod (d-a) = 0;
+(z.p-z1) dotprod (c-b) = 0;
+draw a--d;
+draw b--c;
+draw z0--z.p--z1;
+draw_marked(a--b, 1);
+draw_marked(c--d, 1);
+draw_marked(a--z.p, 2);
+draw_marked(d--z.p, 2);
+draw_marked(b--z.p, 3);
+draw_marked(c--z.p, 3);
+mark_angle(z.p, b, a, 1);
+mark_angle(z.p, c, d, 1);
+mark_angle(z.p, c, b, 2);
+mark_angle(c, b, z.p, 2);
+mark_rt_angle(z.p, z0, a);
+mark_rt_angle(z.p, z1, b);
+endfig;
+\end{verbatim}
+\quad \mathcenter{\includegraphics{mpman-42.mps}}
+$$
+\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}}.
+
+\begin{figure}[htp]
+$$\begin{verbatim}
+marksize=4pt;
+
+def draw_mark(expr p, a) =
+ begingroup
+ save t, dm; pair dm;
+ t = arctime a of p;
+ dm = marksize*unitvector direction t of p
+ rotated 90;
+ draw (-.5dm.. .5dm) shifted point t of p;
+ endgroup
+enddef;
+
+def draw_marked(expr p, n) =
+ begingroup
+ save amid;
+ amid = .5*arclength p;
+ for i=-(n-1)/2 upto (n-1)/2:
+ draw_mark(p, amid+.6marksize*i);
+ endfor
+ draw p;
+ endgroup
+enddef;
+\end{verbatim}
+$$
+\caption{Macros for drawing a path {\tt p} with {\tt n} cross marks.}
+\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.
+
+\begin{figure}[htp]
+$$\begin{verbatim}
+angle_radius=8pt;
+
+def mark_angle(expr a, b, c, n) =
+ begingroup
+ save s, p; path p;
+ p = unitvector(a-b){(a-b)rotated 90}..unitvector(c-b);
+ s = .9marksize/length(point 1 of p - point 0 of p);
+ if s<angle_radius: s:=angle_radius; fi
+ draw_marked(p scaled s shifted b, n);
+ endgroup
+enddef;
+
+def mark_rt_angle(expr a, b, c) =
+ draw ((1,0)--(1,1)--(0,1))
+ zscaled (angle_radius*unitvector(a-b)) shifted b
+enddef;
+\end{verbatim}
+$$
+\caption{Macros for marking angles.}
+\label{markangle}
+\end{figure}
+
+
+\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
+$$ \hbox{\tt show hide(numeric a,b; a+b=3; a-b=1) a;} $$
+prints ``\verb|>> 2|.''
+
+If the {\tt hide} macro were not predefined, it could be defined like this:
+$$\begin{verbatim}
+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
+$$\begin{verbatim}
+def dashpattern(text t) =
+ begingroup save on, off;
+\end{verbatim}
+$$
+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}}
+$$ \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
+$-\hbox{\tt d[i]}$.
+
+\begin{figure}[htp]
+$$\begin{verbatim}
+def getmid(suffix p) =
+ pair p.mid[], p.off[], p.dir[];
+ for i=0 upto 36:
+ p.dir[i] = dir(5*i);
+ p.mid[i]+p.off[i] = directionpoint p.dir[i] of p;
+ p.mid[i]-p.off[i] = directionpoint -p.dir[i] of p;
+ endfor
+enddef;
+
+def joinup(suffix pt, d)(expr n) =
+ begingroup
+ save res, g; path res;
+ res = pt[0]{d[0]};
+ for i=1 upto n:
+ g:= if (pt[i]-pt[i-1]) dotprod d[i] <0: - fi 1;
+ res := res{g*d[i-1]}...{g*d[i]}pt[i];
+ endfor
+ res
+ endgroup
+enddef;
+
+beginfig(45)
+path p, q;
+p = ((5,2)...(3,4)...(1,3)...(-2,-3)...(0,-5)...(3,-4)
+ ...(5,-3)...cycle) scaled .3cm shifted (0,5cm);
+getmid(p);
+draw p;
+draw joinup(p.mid, p.dir, 36)..cycle;
+q = joinup(p.off, p.dir, 36);
+draw q..(q rotated 180)..cycle;
+drawoptions(dashed evenly);
+for i=0 upto 3:
+ draw p.mid[9i]-p.off[9i]..p.mid[9i]+p.off[9i];
+ draw -p.off[9i]..p.off[9i];
+endfor
+endfig;
+\end{verbatim}
+\quad \mathcenter{\includegraphics{mpman-45.mps}}
+$$
+\caption{MetaPost code and the corresponding figure}
+\label{fig45}
+\end{figure}
+
+A definition that starts
+$$ \hbox{\tt def joinup(suffix pt, d)(expr n) =} $$
+might suggest that calls to the {\tt joinup} macro should have two sets of
+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
+$$ \hbox{\tt foo(a,b)(c)} $$
+in which case the text parameter is ``{\tt a,b}'' and the expr parameter is
+{\tt c}, but
+$$ \hbox{\tt foo(a,b,c)} $$
+sets the text parameter to ``{\tt a,b,c}'' and leaves the MetaPost interpreter
+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.''
+
+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{[]}!vardef macro?\texttt{vardef} macro}. 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
+$$ \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:
+$$ \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:
+$$ \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}.
+
+In general,
+$$ {\tt vardef}\, \descr{generic variable} \hbox{\verb|@#|} $$
+is an alternative to {\tt vardef} \tdescr{generic variable} that causes the
+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}.
+
+\begin{itemize}
+\item Vardef macros are automatically surrounded by {\tt begingroup}
+and {\tt endgroup}.
+\item The name of a vardef macro can be more than one token long and it can
+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).
+\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.
+
+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:
+$$ \hbox{\tt vardef round primary u =}\, \descr{replacement text}\,
+ \hbox{\tt enddef;}
+$$
+The {\tt u} parameter is an expr parameter\index{parameter!expr} and it can be
+used exactly like the expr parameter defined using the ordinary
+$$ \hbox{\tt (expr u)} $$
+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}}
+$$ \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:
+$$ \hbox{\tt vardef direction expr t of p =}\, \descr{replacement text}\,
+ \hbox{\tt enddef;}
+$$
+
+Macros can also be defined to behave like binary operators. For instance, the
+definition of the {\tt dotprod} macro has the
+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}.''
+
+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:
+$$ \hbox{\tt def foo(text a) expr b =}\, \descr{replacement text}\,
+ \hbox{\tt enddef;}
+$$
+This defines a macro {\tt foo} to take a text parameter in parentheses followed
+by an expression.
+
+\begin{figure}[htp]
+\begin{ctabbing}
+$\tt \descr{macro definition} \rightarrow
+ \descr{macro heading} \hbox{\tt =} \descr{replacement text}\, enddef$\\
+$\tt \descr{macro heading} \rightarrow def\, \descr{symbolic token}
+ \descr{delimited part} \descr{undelimited part}$\\
+$\tt \qquad \;|\; vardef\, \descr{generic variable} \descr{delimited part}
+ \descr{undelimited part}$\\
+$\tt \qquad \;|\; vardef\, \descr{generic variable} \hbox{\tt @\#}
+ \descr{delimited part} \descr{undelimited part}$\\
+$\tt \qquad \;|\; \descr{binary def} \descr{parameter}
+ \descr{symbolic token} \descr{parameter}$\\
+$\tt \descr{delimited part} \rightarrow \descr{empty}$\\
+$\tt \qquad \;|\; \descr{delimited part}
+ \hbox{\tt (}\descr{parameter type} \descr{parameter tokens}\hbox{\tt )}$\\
+$\tt \descr{parameter type} \rightarrow expr \;|\; suffix \;|\; text$\\
+$\tt \descr{parameter tokens} \rightarrow \descr{parameter} \;|\;
+ \descr{parameter tokens}\hbox{\tt ,} \descr{parameter}$\\
+$\tt \descr{parameter} \rightarrow \descr{symbolic token}$\\
+$\tt \descr{undelimited part} \rightarrow \descr{empty}$\\
+$\tt \qquad \;|\; \descr{parameter type} \descr{parameter}$\\
+$\tt \qquad \;|\; \descr{precedence level} \descr{parameter}$\\
+$\tt \qquad \;|\; expr\, \descr{parameter}\, of\, \descr{parameter}$\\
+$\tt \descr{precedence level} \rightarrow primary \;|\; secondary \;|\;
+ tertiary$\\
+$\tt \descr{binary def} \rightarrow primarydef \;|\; secondarydef \;|\;
+ tertiatydef$
+\end{ctabbing}
+\caption{The syntax for macro definitions}
+\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
+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
+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}.)
+
+
+\section{Loops}
+
+Numerous examples in previous sections have used simple {\tt for} loops of the
+form\index{loops}\index{for?\texttt{for}}\index{endfor?\texttt{endfor}}
+$$ {\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}}
+$$ \hbox{\tt step 1 until} $$
+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 b}<0$. For ${\tt b}=0$ the loop never
+terminates, even if ${\tt a}={\tt c}$.
+
+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}.
+
+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
+semicolon. It is common for the body of a loop to be one or more statements,
+but this need not be the case. A loop is like a macro definition followed by
+calls to the macro. The loop body can be virtually any sequence of tokens as
+long as they make sense together. Thus, the (ridiculous) statement
+$$ \hbox{\verb|draw for p=(3,1),(6,2),(7,5),(4,6),(1,3): p-- endfor cycle;|} $$
+is equivalent to
+$$ \hbox{\verb|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
+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
+$$ {\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.
+
+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;
+\end{verbatim}
+$$
+This should make it clear why the parameter to {\tt dotlabels} has to be a
+comma-separated list of suffixes. Most macros that accept variable-length
+comma-separated lists
+use them in {\tt for} or {\tt forsuffixes} loops in this fashion as values to
+iterate over.
+
+When there are no values to iterate over, you can use a
+{\tt forever}\index{forever?\texttt{forever}} loop:
+$$ {\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}}.
+
+Thus MetaPost's version of a {\bf while} loop is
+$$ \hbox{\tt forever: exitunless}\, \descr{boolean expression} \hbox{\tt ;}\,
+ \descr{loop text}\, {\tt endfor}
+$$
+The exit clause could equally well come just before {\tt endfor} or anywhere
+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}.
+
+\begin{figure}[htp]
+\begin{ctabbing}
+$\tt \descr{loop} \rightarrow \descr{loop header}\hbox{\tt :}\,
+ \descr{loop text} endfor$\\
+$\tt \descr{loop header} \rightarrow for\, \descr{symbolic token}\,
+ \hbox{\tt =}\, \descr{progression}$\\
+$\tt \qquad \;|\; for\, \descr{symbolic token}\, \hbox{\tt =}\,
+ \descr{for list}$\\
+$\tt \qquad \;|\; forsuffixes\, \descr{symbolic token}\, \hbox{\tt =}\,
+ \descr{suffix list}$\\
+$\tt \qquad \;|\; forever$\\
+$\tt \descr{progression} \rightarrow \descr{numeric expression}\, upto\,
+ \descr{numeric expression}$\\
+$\tt \qquad \;|\; \descr{numeric expression}\, downto\,
+ \descr{numeric expression}$\\
+$\tt \qquad \;|\; \descr{numeric expression}\, step\,
+ \descr{numeric expression}\, until\, \descr{numeric expression} $\\
+$\tt \descr{for list} \rightarrow \descr{expression}
+ \;|\; \descr{for list}\hbox{\tt ,}\, \descr{expression}$\\
+$\tt \descr{suffix list} \rightarrow \descr{suffix}
+ \;|\; \descr{suffix list}\hbox{\tt ,}\, \descr{suffix}$
+\end{ctabbing}
+\caption{The syntax for loops}
+\label{syloop}
+\end{figure}
+
+
+\section{Reading and Writing Files}
+File access was one of the new language features introduced in version~0.60
+of the MetaPost language. A new operator
+$$ {\tt readfrom}\ \descr{file name} $$\index{readfrom?\texttt{readfrom}}\label{Dreadfrom}%
+returns a string giving the next line of input from the named
+file\index{files!reading}. The \tdescr{file name} can be any primary
+expression of type string. If the file has ended or cannot be read, the
+result is a string consisting of a single null character. The preloaded
+{\tt plain} macro package introduces the name
+{\tt EOF}\index{EOF?\texttt{EOF}}\label{Deof} for this string. After
+{\tt readfrom} has returned {\tt EOF}, additional reads from the same file
+cause the file to be reread from the start.
+
+All files opened by \ttt{readfrom} that have not completely been read
+yet are closed\index{files!closing} automatically when the program
+terminates, but there exists a command
+$${\tt closefrom}\ \descr{file name}$$%
+\index{closefrom?\texttt{closefrom}}\label{Dclosefrom}%
+to close files opened by {\tt readfrom} explicitly. It is wise to
+manually close files you do not need to read completely (i.e. until {\tt
+ EOF} is returned) because otherwise such files will continue to use
+internal resources and perhaps cause a \ttt{capacity exceeded!} error.
+
+The opposite of {\tt readfrom} is the command
+$$ {\tt write}\ \descr{string expression}\ {\tt to}\ \descr{file name} $$%
+\index{write to?\texttt{write to}}\label{Dwrite}%
+This writes\index{files!writing} a line of text to the specified output file,
+opening the file first if necessary. All such files are
+closed\index{files!closing} automatically when the program terminates. They
+can also be closed explicitly by using {\tt EOF}\index{EOF?\texttt{EOF}}
+as the \tdescr{string expression}. The only way to tell if a {\tt write}
+command has succeeded is to close the file and use {\tt readfrom} to look
+at it.
+
+
+\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 {\tt verbatimtex}\index{verbatimtex?\texttt{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}\index{\%?\texttt{\%}!magic comment!\%\&?\texttt{\%\&}} 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}
+
+
+\section{Another Look at the MetaPost Workflow}
+\label{workflow2}
+
+\index{workflow}
+
+In Section~\ref{workflow} we already had a brief look at how MetaPost
+compiles input files and generates output files. This section contains
+some more information and discusses internal variables that can be used
+to control MetaPost's run-time behavior, previewing PostScript output,
+debugging MetaPost code, and importing MetaPost graphics into
+third-party applications.
+
+\subsection{Customizing Run-Time Behavior}
+
+\index{runtime behavior!customize}
+
+MetaPost knows and obeys a number of internal\index{internal
+ variables}\index{variables!internal} variables that have no direct
+impact on drawing commands, but can be used to customize the way the
+MetaPost compiler processes input files. The following paragraphs
+describe those variables (in no particular order).
+
+\paragraph{Date and Time}
+
+MetaPost provides a number of internal numeric variables that store the
+date and time a job was started, i.e., the MetaPost executable was
+called on the command-line. Variables
+\texttt{year}\index{year?\texttt{year}}\label{Dyear},
+\texttt{month}\index{month?\texttt{month}}\label{Dmonth},
+\texttt{day}\index{day?\texttt{day}}\label{Dday},
+\texttt{hour}\index{hour?\texttt{hour}}\label{Dhour}, and
+\texttt{minute}\index{minute?\texttt{minute}}\label{Dminute} should be
+self-explanatory. Variable
+\texttt{time}\index{time?\texttt{time}}\label{Dtime} returns the number
+of minutes past midnight, since the job was started, i.e.,
+$\texttt{time} = 60*\texttt{hour} + \texttt{minute}$.
+
+\paragraph{Output File Names}
+
+As discussed in Section~\ref{workflow}, by default, every
+\verb|beginfig| \ldots\ \verb|endfig| group in an input file corresponds
+to an output file that follows the naming scheme
+\texttt{\tdescr{jobname}.\tdescr{n}}. That is, all files have varying
+numeric file extensions. MetaPost provides a template mechanism that
+allows for more flexible output file names. The template mechanism uses
+\texttt{printf}-style escape sequences that are re-evaluated at ship-out
+time, i.e., before each figure is written to disk.
+
+To configure the output file naming scheme a string containing the
+corresponding escape sequences has to be assigned to the internal string
+variable
+\verb|outputtemplate|\index{outputtemplate?\texttt{outputtemplate}}\label{Doutputtemplate}.
+The escape sequences provided are listed in
+table~\ref{tab:outputtemplate}. As an example, if this code is saved in
+a file \texttt{fig.mp},
+$$
+\begin{verbatim}
+outputtemplate := "%j-%c.mps";
+beginfig(1);
+ drawdot origin;
+endfig;
+end
+\end{verbatim}
+$$
+it will create the output file \texttt{fig-1.mps} instead of
+\texttt{fig.1}. The file extension \texttt{mps}\index{mps file?{\tt
+ mps} file}\index{files!mps?{\tt mps}} is conventionally chosen for
+MetaPost's PostScript output (see Section~\ref{mpimport}). For SVG and
+PNG output one would want to use file extensions \texttt{svg}\index{svg
+ file?{\tt svg} file}\index{files!svg?{\tt svg}} and
+\texttt{png}\index{png file?{\tt png} file}\index{files!png?{\tt png}}
+instead.
+
+\begin{table}
+ \centering
+ \begin{tabular}{|>{\ttfamily}l|l|>{\ttfamily}l|}
+ \hline
+ \multicolumn1{|c|}{Escape sequence} & \multicolumn1{c|}{Meaning} & \multicolumn1{c|}{Alternative}\\\hline
+ \%\%\index{\%?\texttt{\%}!outputtemplate escape sequence?\texttt{outputtemplate} escape sequence!\%\%?\texttt{\%\%}} & percent sign &\\
+ \%\{\tdescr{internal variable}\}\index{\%?\texttt{\%}!outputtemplate
+ escape sequence?\texttt{outputtemplate} escape sequence!\%\{...\}?\texttt{\%\{\tdescr{internal variable}\}}} & evaluate internal variable &\\
+ \%j\index{\%?\texttt{\%}!outputtemplate escape sequence?\texttt{outputtemplate} escape sequence!\%j?\texttt{\%j}} & current jobname & \%\{jobname\}\\
+ \%c\index{\%?\texttt{\%}!outputtemplate escape sequence?\texttt{outputtemplate} escape sequence!\%c?\texttt{\%c}} & charcode value (\texttt{beginfig} argument) & \%\{charcode\}\\
+ \%y\index{\%?\texttt{\%}!outputtemplate escape sequence?\texttt{outputtemplate} escape sequence!\%y?\texttt{\%y}} & current year & \%\{year\}\\
+ \%m\index{\%?\texttt{\%}!outputtemplate escape sequence?\texttt{outputtemplate} escape sequence!\%m?\texttt{\%m}} & month (numeric) & \%\{month\}\\
+ \%d\index{\%?\texttt{\%}!outputtemplate escape sequence?\texttt{outputtemplate} escape sequence!\%d?\texttt{\%d}} & day of the month & \%\{day\}\\
+ \%H\index{\%?\texttt{\%}!outputtemplate escape sequence?\texttt{outputtemplate} escape sequence!\%H?\texttt{\%H}} & hour & \%\{hour\}\\
+ \%M\index{\%?\texttt{\%}!outputtemplate escape sequence?\texttt{outputtemplate} escape sequence!\%M?\texttt{\%M}} & minute & \%\{minute\}\\
+ \hline
+ \end{tabular}
+ \caption{Allowed escape sequences for \ttt{outputtemplate}}
+ \label{tab:outputtemplate}
+\end{table}
+
+In single-letter escape sequences referring to internal numerics, the
+corresponding value is rounded to the nearest integer before it is
+converted to a string expression. In such escape sequences, a number
+from the range 0 to~99 can optionally be placed directly after \verb|%|
+that determines the minimum number of digits in the resulting string
+expression, like \verb|%2m|. If the decimal representation of the
+internal variable requires more digits, actual string length will exceed
+the requested length. If less digits are required, the string is padded
+to the requested length with zeros from left.
+
+In single-letter escape sequences referring to internal string
+variables, like \verb|%j|, and in the \verb|%{...}| escape sequence,
+neither rounding nor zero-padding take place.
+
+For backwards compatibility, the
+\verb|%c|\index{\%?\texttt{\%}!outputtemplate escape
+ sequence?\texttt{outputtemplate} escape sequence!\%c?\texttt{\%c}}
+escape sequence is handled special. If the result of rounding the
+charcode value is negative, \verb|%c| evaluates to the string \verb|ps|.
+This transformation can be bypassed by using \verb|%{charcode}| instead
+of \verb|%c|. But note, that this bypasses rounding and zero-padding as
+well.
+
+The template mechanism can also be used for naming graphic files
+individually, yet keeping all sources in one file. Collecting, e.g.,
+different diagram sources in a single file \texttt{fig.mp}, it might be
+easier to recall the correct diagram names in a \TeX\ document than with
+numbered file names. Note, the argument to \verb|beginfig| is not
+relevant as long as there's no \verb|%c| pattern in the file name
+template string.
+$$
+\begin{verbatim}
+outputtemplate := "fig-quality.mps";
+beginfig(1);
+ ...
+endfig;
+
+outputtemplate := "fig-cost-vs-productivity.mps";
+beginfig(2);
+ ...
+endfig;
+\end{verbatim}
+$$
+
+To ensure compatibility with older files, the default value of
+\verb|outputtemplate| is \verb|%j.%c|. If you assign an empty string,
+it will revert to that default. MetaPost versions~1.000 to~1.102 used a
+different template mechanism, see Section~\ref{Dfilenametemplate} for
+more information.
+
+During \texttt{shipout}\index{shipout?\texttt{shipout}}, the name of the
+output file to be written is stored in an internal string variable
+\texttt{outputfilename}\index{outputfilename?\texttt{outputfilename}}\label{Doutputfilename}.
+It remains available until the next \texttt{shipout} command. The
+variable is initially empty.
+
+\paragraph{Output Format}
+
+MetaPost can generate graphics in three output formats:
+
+\begin{itemize}
+\item Encapsulated PostScript\index{PostScript!structured}
+ (EPSF\index{EPSF}),
+\item Scalable Vector Graphics (SVG\index{SVG}) following version~1.1 of
+ the SVG specification~\cite{w3c:svg1.1} (since MetaPost version
+ 1.200),
+\item Portable Network Graphics (PNG), a losslessly compressing bitmap
+ format (since MetaPost version 1.800).
+\end{itemize}
+By default, MetaPost outputs PostScript files---hence the name MetaPost.
+The output format can be changed by assigning values \verb|"svg"| or
+\verb|"png"| to the internal string variable\index{internal
+ variables}\index{variables!internal}
+\verb|outputformat|\index{outputformat?\texttt{outputformat}}\label{Doutputformat}:
+$$
+\begin{verbatim}
+outputformat := "svg";
+\end{verbatim}
+$$
+Other values make MetaPost fall back to PostScript output. Variable
+\verb|outputformat| is case-sensitive, so assigning it the string
+\verb|"SVG"| enables PostScript output, too. Default value of variable
+\verb|outputformat| is \verb|"eps"|.
+
+\paragraph{Bitmap output} To create bitmap output in the PNG format,
+MetaPost utilizes the Cairo\index{Cairo} \cite{lib:cairo} graphics
+library.\footnote{The Cairo library version is printed when MetaPost is
+ run with the \texttt{-version} command-line switch.} Bitmap
+conversion can be controlled from within MetaPost using three internal
+variables: \texttt{outputformatoptions}, \texttt{hppp}, and
+\texttt{vppp}.
+
+\begin{table}
+ \centering
+ \begin{tabular}{|>{\ttfamily}l|>{\ttfamily}l|l|}
+ \hline
+ \multicolumn1{|c|}{Key} & \multicolumn1{c|}{Values} & \multicolumn1{c|}{Meaning}\\\hline
+ format &
+ rgba\index{rgba?\texttt{rgba}|see{\texttt{outputformatoptions},
+ \texttt{format}}} & RGB color space\index{PNG!color space!RGBA}
+ with alpha channel\index{PNG!alpha channel}\\
+ & rgb\index{rgb?\texttt{rgb}|see{\texttt{outputformatoptions},
+ \texttt{format}}} & RGB color space\index{PNG!color space!RGB}\\
+ & graya\index{graya?\texttt{graya}|see{\texttt{outputformatoptions},
+ \texttt{format}}} & gray scale color space\index{PNG!color
+ space!gray scale with alpha} with alpha channel\index{PNG!alpha
+ channel}\\
+ & gray\index{gray?\texttt{gray}|see{\texttt{outputformatoptions},
+ \texttt{format}}} & gray scale color space\index{PNG!color
+ space!gray scale}\\
+ \hline
+ antialias &
+ none\index{none?\texttt{none}|see{\texttt{outputformatoptions},
+ \texttt{antialias}}} & no anti aliasing\index{PNG!anti
+ aliasing}\\
+ & fast\index{fast?\texttt{fast}|see{\texttt{outputformatoptions},
+ \texttt{antialias}}} & fastest anti aliasing algorithm\\
+ & good\index{good?\texttt{good}|see{\texttt{outputformatoptions},
+ \texttt{antialias}}} & better quality, but slower\\
+ & best\index{best?\texttt{best}|see{\texttt{outputformatoptions},
+ \texttt{antialias}}} & best quality, slowest\\
+ \hline
+ \end{tabular}
+ \caption{Valid keys and values in variable \texttt{outputformatoptions}.}
+ \label{tab:outputformatoptions}
+\end{table}
+
+Variable
+\texttt{outputformatoptions}\index{outputformatoptions?\texttt{outputformatoptions}}\label{Doutputformatoptions}
+is a string containing a list of \tdescr{key}\verb|=|\tdescr{value}
+pairs separated by spaces (no other spaces are allowed). Key
+\texttt{format}\index{format?\texttt{format}|see{outputformatoptions,
+ \texttt{format}}}\index{outputformatoptions?\texttt{outputformatoptions}!format?\texttt{format}}
+determines color space of the written PNG file. Key
+\texttt{antialias}\index{antialias?\texttt{antialias}|see{outputformatoptions,
+ \texttt{antialias}}}\index{outputformatoptions?\texttt{outputformatoptions}!antialias?\texttt{antialias}}
+determines what level of anti aliasing\index{anti aliasing|see{PNG, anti
+ aliasing}}\index{PNG!anti aliasing} is applied during vector graphic
+to bitmap conversion. The set of accepted values and their meanings can
+be found in table~\ref{tab:outputformatoptions}. An assignment that
+would match the compiled-in default setup would look like
+
+$$
+\begin{verbatim}
+outputformatoptions := "format=rgba antialias=fast";
+\end{verbatim}
+$$
+Keys not given in an assignment to \texttt{outputformatoptions} are
+reset to their default value. By default, this variable is empty.
+
+PNG files have a transparent background\index{background in PNG output}
+if output color space provides an alpha channel\index{alpha
+ channel|see{PNG, alpha channel}}\index{PNG!alpha channel}
+(\texttt{format}\index{outputformatoptions?\texttt{outputformatoptions}!format?\texttt{format}}
+is \texttt{rgba} or \texttt{graya}). Otherwise background becomes
+white. Color channels have a bit-depth of~8 in output. Colors not
+supported by the output format, e.g., CMYK colors, are transformed to a
+color with a similar visual impression. Here's how colors are
+transformed during bitmap conversion. Let's recall that color
+components in a MetaPost picture are in the range $[0;1]$ (see the
+discussion of color types in Section~\ref{datatypes}). Whatever input
+and output color spaces are used, all colors found in a picture are
+initially converted to RGB color space. A gray scale color with
+intensity $i$ is converted to an RGB color with all components set
+to~$i$. RGB colors are left unchanged. A CMYK color with components
+$(c,m,y,k)$ is converted to an RGB color with components $(r,g,b)$ using
+equations
+\begin{eqnarray}
+ r &=& 1 - k - c\\
+ g &=& 1 - k - m\\
+ b &=& 1 - k - y
+\end{eqnarray}
+with results clipped to the range $[0;1]$. If requested by the output
+format (\texttt{gray} or \texttt{graya}), such a color is further
+converted to a gray color with intensity
+\begin{eqnarray}
+j = 0.2126 \cdot r + 0.7152 \cdot g + 0.0722 \cdot b
+\end{eqnarray}
+
+Note, colors are exact in PNG output if input and output color spaces
+are compatible, i.e., both are RGB or gray scale or output in RGB color
+space contains only gray scale colors. Users that care about color
+conversion can apply the necessary transformations explicitly in a
+\texttt{for within~\tdescr{\mbox{picture}}}\index{for within?\texttt{for
+ within}} loop inside
+\texttt{extra\_endfig}\index{extra_endfig?\texttt{extra\_endfig}} (see
+Section~\ref{Dforwithin} and Appendix~\ref{Dxefig}). MetaPost has no
+built-in color management support. The built-in conversions are
+provided just as a convenience.
+
+Resolution of PNG output is always 72~dpi\index{dpi}\index{units!dpi}
+(dots per inch). Two internal variables
+\texttt{hppp}\index{hppp?\texttt{hppp}}\label{Dhppp} and
+\texttt{vppp}\index{vppp?\texttt{vppp}}\label{Dvppp} are used by the PNG
+backend to decide on the scale of the generated bitmap. These two
+variables have already been present in \MF\ and have been revived when
+MetaPost acquired the bitmap backend in version 1.800. But there's a
+catch: In \MF, variables \texttt{hppp} and \texttt{vppp} refer to
+horizontal and vertical scale in \emph{pixels per
+ point}\index{units!pixels per point} and values larger than~1 result
+in output of larger dimensions. In MetaPost, the meaning of both
+variables is the other way around. They refer to horizontal and
+vertical scale in \emph{points per pixel}\index{units!points per pixel}
+and values larger than~1 result in output of smaller dimensions.
+Default value for both variables is $1.0$, i.e., one MetaPost point per
+pixel.
+
+\paragraph{PostScript Dictionary}
+
+For PostScript output, MetaPost can define a dictionary of abbreviations
+of the PostScript commands, e.g., \verb|l| instead of \verb|lineto|, to
+reduce the size of output files. Setting the internal variable
+\texttt{mpprocset}\index{mpprocset?\texttt{mpprocset}}\label{Dmpprocset}
+to~1 makes MetaPost create an extended preamble setting-up the
+dictionary. Default value of variable \texttt{mpprocset} is~0, that is,
+no dictionary is used. For SVG and PNG output, variable
+\texttt{mpprocset} is not relevant.
+
+\paragraph{Version Number}
+
+The version number of the MetaPost compiler can be determined from
+within a MetaPost program via the predefined constant string
+\texttt{mpversion}\index{mpversion?\texttt{mpversion}}\label{Dmpversion}
+(since version~0.9). For instance the following code
+$$
+\begin{verbatim}
+message "mp = " & mpversion;
+\end{verbatim}
+$$
+writes
+$$
+\begin{verbatim}[commandchars=\\\{\}]
+mp = \mpversion
+\end{verbatim}
+$$
+to the console and the transcript file. Variable \texttt{mpversion} can
+be used to execute code depending on the MetaPost version like this:
+$$
+\begin{verbatim}[commandchars=\\\{\}]
+if unknown mpversion: string mpversion; mpversion := "0.000"; fi
+if scantokens(mpversion) < 1.200:
+ errmessage "MetaPost v1.200 or later required (found v" & mpversion & ")";
+else:
+ \tdescr{code}
+fi
+\end{verbatim}
+$$
+The first line is optional and only added to handle ancient MetaPost
+versions gracefully that don't even know about variable
+\textrm{mpversion} (prior to v0.9). The second test does the actual
+work.
+
+The version number is also written to output files and the transcript
+file. For PostScript output, the version number can be found in the
+\texttt{Creator}\index{Creator comment in PostScript
+ output?\texttt{Creator} comment in PostScript output|see{PostScript,
+ \texttt{Creator} comment}}\index{PostScript!Creator
+ comment?\texttt{Creator} comment} comment. SVG files contain a simple
+comment line near the beginning of the file. For PNG output, the
+version number can be found in a text chunk with keyword
+\texttt{Software}\index{Software keyword in PNG text
+ chunk?\texttt{Software} keyword in PNG text chunk|see{PNG, text
+ chunk}}\index{text chunk|see{PNG, text chunk}}\index{PNG!text
+ chunk}. The transcript\index{files!transcript} file starts with a
+banner line that identifies the version\index{version number} of the
+MetaPost compiler.
+
+\subsection{Previewing PostScript Output}
+\label{preview}
+\index{preview!PostScript}
+
+Previewing MetaPost's PostScript output is not difficult, but there are
+some catches that one should know about. This section deals with the
+following questions: How can graphics be clipped to their true bounding
+box in the PostScript viewer application? Why are my text labels
+rendered with an ugly font (or not at all) and how to avoid that? How
+can several graphics be combined into a multi-page document that can be
+previewed within one instance of the viewer application?
+
+\subsubsection{Bounding Box}
+\index{bounding box}
+\index{PostScript!bounding box}
+
+With default settings, MetaPost writes very much stripped-down
+PostScript code, containing only the bare graphics code, but no other
+ressources, like fonts etc. The PostScript code is somewhat deficient,
+because it fails to correctly identify as Encapsulated PostScript
+(EPSF\index{EPSF}) in the header. Note, Encapsulated PostScript files
+don't have an associated page size, but provide bounding box
+information, because they are meant for inclusion into other documents.
+Instead MetaPost output wrongly pretends to be full PostScript
+(PS\index{PS}), which it is not.
+
+This is just fine for including MetaPost graphics in, say, \TeX\
+documents (see Section~\ref{mpimport}), but some PostScript viewers have
+difficulties rendering those PostScript files correctly. As an example,
+because of the wrong ``PS'' header, GSview\index{GSview}---not knowing
+better---ignores bounding box information and then clips all contents to
+a (configurable) page size. Graphic elements laying outside those fixed
+page boundaries are therefore not visible, e.g., when they have negative
+coordinates.
+
+To avoid such situations, the first rule when previewing MetaPost's
+PostScript output is to put the line
+$$
+\begin{verbatim}
+prologues := 2;
+\end{verbatim}
+\index{prologues?\texttt{prologues}}
+$$
+before the first \verb|beginfig| in MetaPost input files (see the
+discussion about \texttt{prologues} in Section~\ref{Dprologues}). That
+way, MetaPost's PostScript output correctly identifies as Encapsulated
+PostScript and viewer applications should always obey the file's
+bounding box for on-screen rendering.
+
+A workaround for MetaPost's deficient default PostScript code that can
+sometimes be seen is to move the lower left corner of a figure to the
+origin as a last operation by saying
+$$
+\begin{verbatim}[commandchars=\\\{\}]
+\color{gray}currentpicture := currentpicture shifted -llcorner currentpicture;
+\end{verbatim}
+\index{currentpicture?\texttt{currentpicture}}
+\index{llcorner?\texttt{llcorner}}
+$$
+before \verb|endfig|. But this doesn't prevent from clipping on the
+right and upper page boundaries. Additionally, the line is required for
+all figures, cluttering source code, and it alters all coordinates in
+PostScript output, which might complicate debugging. Applying such a
+manual transformation is therefore not recommended (which is why the
+line is grayed out). Instead, users are advised to adjust
+\texttt{prologues} once in the preamble of the input file and enable
+clipping to the bounding box in the PostScript viewer. For
+GSview\index{GSview}, that can be done by activating \texttt{Options}
+$\rightarrow$ \texttt{EPS Clip} and optionally \texttt{Options}
+$\rightarrow$ \texttt{Show Bounding Box} for verification.
+
+\subsubsection{Text Labels}
+
+Another popular previewing issue concerns graphics that contain text
+labels. An observation MetaPost users can often make is that text
+labels in graphics are rendered with wrong fonts, wrong glyphs, and
+sometimes even not at all. The reason is that with default settings,
+again, MetaPost's PostScript output is deficient, in that it uses a
+simple, non-standard way to declare what fonts are used in a graphic.
+Setting variable \texttt{prologues} to~2, as shown in the previous
+section, makes MetaPost generate more complex PostScript code to declare
+all needed PostScript\index{PostScript!fonts} fonts and embed the
+necessary encoding information. If the PostScript viewer can provide
+the requested fonts, this might be sufficient to get text labels
+rendered correctly. If you still observe wrong or missing glyphs you
+should put the line
+$$
+\begin{verbatim}
+prologues := 3;
+\end{verbatim}
+\index{prologues?\texttt{prologues}}
+$$
+into the preamble of the input file. That way, MetaPost embeds the used
+PostScript\index{PostScript!fonts} fonts into the output file so that
+they are always available (see the discussion about \texttt{prologues}
+in Section~\ref{Dprologues}). Note, this might enlarge the size of
+output files considerably. Additionally, fonts might be embedded
+multiple times when several graphics using the same fonts are included
+into a document. For that reason, it is recommended to reset variable
+\texttt{prologues} to~0 before finally including MetaPost graphics into
+external documents.
+
+\subsubsection{Proof Sheets}
+\index{proof sheets}
+
+If you have lots of figures in a source file and need to preview many of
+them at the same time, opening every graphic in a new instance of the
+viewer application and switching between them back and forth can get
+cumbersom. An alternative is to collect all graphics generated from a
+MetaPost input file in a proof sheet, a multi-page document, that can be
+previewed and navigated in a single instance of the viewer application.
+The MetaPost distribution contains two (plain) \TeX\ scripts,
+\texttt{mproof.tex} and \texttt{mpsproof.tex}, that help with the latter
+approach.
+
+\paragraph{\texttt{mproof.tex}}
+\index{mproof.tex?\texttt{mproof.tex}}
+
+To write a proof sheet for MetaPost output, call \texttt{mproof.tex} as
+$$
+\begin{verbatim}[commandchars=\\\{\}]
+tex mproof \tdescr{MetaPost output files}
+\end{verbatim}
+$$
+Then process the resulting \texttt{.dvi}\index{dvi file?{\tt dvi}
+ file}\index{files!dvi?{\tt dvi}} file as usual. That way, there's no
+need to care about different settings of variable
+\texttt{prologues}\index{prologues?\texttt{prologues}}, since in proof
+sheets MetaPost graphics are already embedded.
+
+Note, the parameters after \texttt{mproof} are an explicit list of
+MetaPost output files, possibly generated from different input files.
+On shells that support POSIX\index{shell patterns}\index{POSIX!shell
+ patterns} shell patterns, these can be used to avoid typing a long
+list of files. As an example, for a file \texttt{fig.mp} containing
+three figures with charcodes 1, 2, and~3, the proof sheet can be
+generated by calling
+$$
+\begin{verbatim}
+tex mproof fig.?
+\end{verbatim}
+$$
+The pattern \texttt{fig.?} is automatically expanded to \texttt{fig.1
+ fig.2 fig.3} by the shell (but not necessarily in numerically
+increasing order) before \TeX\ is run. If there were an output file
+\texttt{fig.10}, using patterns \texttt{fig.??} or \texttt{fig.*} to
+cover two-digit indices would fail, since those covered the source file
+\texttt{fig.mp} as well. To avoid that, output file names have to be
+made more significant, e.g., by setting variable \texttt{outputtemplate}
+to \verb|%j-%c.mps| (see Section~\ref{Doutputtemplate}). The proof sheet
+can then be generated with
+$$
+\begin{verbatim}
+tex mproof *.mps
+\end{verbatim}
+$$
+
+\paragraph{\texttt{mpsproof.tex}}
+\index{mpsproof.tex?\texttt{mpsproof.tex}}
+
+An alternative to \texttt{mproof.tex} is the script
+\texttt{mpsproof.tex}, which is similar, but more powerful. While the
+former script only runs with \TeX\ and requires a DVI output driver to
+generate PostScript files, \texttt{mpsproof.tex} can as well be run
+through pdf\TeX\ to directly generate PDF files. Additionally, it
+provides some command-line options.
+
+With the
+\verb|\noheaders|\index{mpsproof.tex?\texttt{mpsproof.tex}!noheaders?\texttt{\textbackslash
+ noheaders}} option, file names, date stamps, and page numbers are
+omitted from the proof sheet. Use it like
+$$
+\begin{verbatim}[commandchars=\|\{\}]
+tex mpsproof \noheaders |tdescr{MetaPost output files}
+\end{verbatim}
+$$
+
+The
+\verb|\bbox|\index{mpsproof.tex?\texttt{mpsproof.tex}!bbox?\texttt{\textbackslash
+ bbox}} option can be used to generate an output file that has
+exactly the same page size as a figure's bounding box (\verb|\bbox| is
+actually an alias for the longer
+\verb|\encapsulate|\index{mpsproof.tex?\texttt{mpsproof.tex}!encapsulate?\texttt{\textbackslash
+ encapsulate}}). With this option only one figure can be processed
+at a time, e.g.,
+$$
+\begin{verbatim}
+pdftex mpsproof \bbox fig.1
+\end{verbatim}
+$$
+
+\paragraph{Alternatives} Other alternatives for previewing MetaPost
+figures, which are not part of the MetaPost distribution, are the
+mptopdf\index{mptopdf} bundle or the Perl script \ttindex{mpstoeps.pl}.
+There is also an online compiler and viewer for MetaPost code at
+\url{http://tlhiv.org/mppreview/}.
+
+\subsection{Debugging}
+\label{debug}
+
+\index{debug}
+
+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{\verb|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 ``\verb|>>|''. 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]
+$$\begin{verbatim}
+>> x1
+! Undefined x coordinate has been replaced by 0.
+<to be read again>
+ {
+--->{
+ curl1}..{curl1}
+l.17 draw z1--
+ z2;
+?
+\end{verbatim}
+$$
+\caption{An example of an error message.}
+\label{errmsg}
+\end{figure}
+
+The context listing may seem a little confusing at first, but it really just
+gives a few lines of text showing how much of each line has been read so far.
+Each line of input is printed on two lines like this:
+\begin{eqnarray*}
+ \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 ``\verb|--|,'' the expansion of the \verb|--| 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 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}
+
+This interactive mode is not only entered when MetaPost finds an error
+in the code. It can be explicitly entered by the \ttindex{errmessage}
+command. The \ttindex{message}\label{Dmessage} command writes a string
+argument to a new line on the terminal. The
+\ttindex{errmessage}\label{Derrmessage} command is similar, but the
+string argument is preceded by \verb|"! "| and followed by~\verb|"."|.
+Additionally, some lines of context are appended as in MetaPost's normal
+error messages. If the user now types ``h'', the most recent
+\ttindex{errhelp}\label{Derrhelp} string will be shown (unless it was
+empty).
+
+\begin{figure}[htp]
+\begin{ctabbing}
+$\tt \descr{message command} \rightarrow errhelp \descr{string expression}$\\
+$\tt \qquad \;|\; errmessage \descr{string expression}$\\
+$\tt \qquad \;|\; message \descr{string expression}$
+\end{ctabbing}
+\caption{The syntax for message commands}
+\label{symsg}
+\end{figure}
+
+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}''\index{mp
+ file?{\tt mp} file}\index{files!mp?{\tt mp}} to ``{\tt
+ .log}''\index{log file?{\tt log} file}\index{files!log?{\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.
+
+The {\tt showtoken}\index{showtoken?\texttt{showtoken}}\label{Dshtok}
+command can be used to show the
+parameters and replacement text of a macro. It takes a comma-separated list of
+tokens and identifies each one. If the token is a primitive as in
+``\verb|showtoken +|'' it is just identified as being itself:
+$$ \hbox{\verb|> +=+|} $$
+Applying {\tt showtoken} to a variable or a {\tt vardef} macro yields
+$$ \hbox{\tt > } \descr{token}\hbox{\tt =variable} $$
+
+To get more information about a variable, use
+{\tt showvariable}\index{showvariable?\texttt{showvariable}}\label{Dshvar}
+instead of {\tt showtoken}. The
+argument to {\tt showvariable} is a comma-separated list of symbolic tokens
+and the result is a description of all the variables whose names begin with
+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
+$$ \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
+`{\tt !\ Undefined x coordinate}?' I thought the equations given so far would
+determine {\tt x1}.''
+
+\begin{figure}[htp]
+$$\begin{verbatim}
+x2=0.5a+2.5
+y2=0.5b+5
+x1=0.5a-2.5
+y1=0.5b-5
+\end{verbatim}
+$$
+\caption{The result of {\tt z2-z1=(5,10); z1+z2=(a,b); showdependencies;}}
+\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:
+\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. %
+\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;
+a setting ${}>2$ shows algebraic operations before they are performed.
+%
+\item[{\tt tracingequations}]\index{tracingequations?\texttt{tracingequations}}\label{Dtequations}%
+shows each variable when it becomes known.
+%
+\item[{\tt tracinglostchars}]\index{tracinglostchars?\texttt{tracinglostchars}}\label{Dtlostchars}%
+warns about characters omitted from a picture because they are not in the font
+being used to typeset labels.
+%
+\item[{\tt tracingmacros}]\index{tracingmacros?\texttt{tracingmacros}}\label{Dtmacros}%
+shows macros before they are expanded.
+%
+\item[{\tt tracingoutput}]\index{tracingoutput?\texttt{tracingoutput}}\label{Dtoutput}%
+shows pictures as they are being shipped out as PostScript files.
+%
+\item[{\tt tracingrestores}]\index{tracingrestores?\texttt{tracingrestores}}\label{Dtrestores}%
+shows symbols and internal variables as they are being restored at the end
+of a group.
+%
+\item[{\tt tracingspecs}]\index{tracingspecs?\texttt{tracingspecs}}\label{Dtspecs}%
+shows the outlines generated when drawing with a
+polygonal pen\index{pens!polygonal}.
+%
+\item[{\tt tracingstats}]\index{tracingstats?\texttt{tracingstats}}\label{Dtstats}
+shows in the transcript file at the end of the job how many of the
+MetaPost interpreter's limited resources were used.
+\end{description}
+
+\subsection{Importing MetaPost Graphics into External Applications}
+\label{mpimport}
+
+MetaPost is very well suited for creating graphics that are to be
+included into third-party applications, such as text documents,
+presentations or web pages, because MetaPost outputs graphics in vector
+formats, which can be scaled without quality degradation. However,
+practice shows, that vector graphics, too, are best created with a rough
+target size already in mind. Scaling a vector graphic calls for
+non-proportional scaling of certain technical parameters, such as line
+width, arrow size or fonts. Otherwise, with growing scale factors
+scalable graphics tend to change their visual character. Additionally,
+during import into a main document, they'll likely fail to match, e.g.,
+stroke width of the document. To circumvent this, it is advisable to
+apply only small post-processing scale factors to vector graphics. The
+following sections briefly discuss how to import MetaPost graphics into
+documents with selected applications.
+
+\subsubsection{\TeX\ and Friends}
+\label{teximport}
+\index{TeX?\TeX!and friends}
+
+MetaPost graphics in the PostScript\index{PostScript} format can be
+easily integrated into documents prepared with \TeX\ and friends.
+MetaPost's PostScript output is a low-featured dialect of the Postscript
+language, called \emph{purified EPS}\index{EPS!purified}, which can be
+converted into the Portable Document Format (PDF\index{PDF}) language
+on-the-fly. For that reason, external MetaPost graphics can be used on
+both routes: a) using the traditional \TeX\ engine together with an
+external PostScript output driver and b) using newer \TeX\ engines, like
+pdf\TeX\ or its successor Lua\TeX, which contain a built-in PDF output
+driver. Lua\TeX\ can additionally process embedded MetaPost code
+natively, falling back to the built-in \emph{mplib} library.
+
+Figure~\ref{fig:teximport} shows the process of including an external
+MetaPost graphic into a \TeX\ document using the PostScript route. In
+the \TeX\ source a ``magic macro'' provided by the format or an external
+package is used for including a graphic file. During the typesetting
+stage, the macro only reads bounding box information off the PostScript
+file and reserves the required space on the page via an empty box. The
+file reference is passed-on to the output driver and only then, finally,
+the file is embedded into the document. The freely available program
+\ttindex{dvips} is used as an output driver in this
+example.\footnote{The C source for \ttt{dvips} comes with the web2c
+ \TeX\ distribution. Similar programs are available from other
+ sources.} The next paragraphs give more detailed information on some
+popular combinations of \TeX\ formats and engines.
+
+\begin{figure}
+$$ \includegraphics{mpman-charts-1.mps} $$
+\caption{A diagram of the processing for a \TeX\ document embedding
+ MetaPost figures}
+\label{fig:teximport}
+\end{figure}
+
+\paragraph{Plain \TeX\ Format}
+\label{plaintexformat}
+\index{TeX?\TeX!format, plain!importing MetaPost files}
+
+For users of the Plain \TeX\ format and the traditional \TeX\
+engine\index{TeX?\TeX!engine} with Device Independend output
+(DVI\index{dvi file?{\tt dvi} file}) the
+\ttt{epsf}\index{epsf.tex?\texttt{epsf.tex}} package provides the
+``magic macro''
+$$ \verb|\epsfbox{|\descr{filename}\verb|}|%
+\index{epsfbox?\texttt{\string\epsfbox}} $$
+for embedding graphics, e.g., \verb|\epsfbox{fig.1}|.
+
+Users of the pdf\TeX\ engine\index{pdfTeX?pdf\TeX!engine} should refer
+to the standalone macros of the mptopdf\index{mptopdf} bundle, which can
+be found at \url{http://context.aanhet.net/mptopdf.htm}.
+
+With the Lua\TeX\ engine\index{LuaTeX?Lua\TeX!engine}, embedding
+external graphics works the same as with pdf\TeX. Additionally,
+Lua\TeX\ users can inline MetaPost code directly into Plain \TeX\
+documents. Lua\TeX\ is able to process such MetaPost code snippets,
+falling back to the built-in \emph{mplib}\index{mplib?\emph{mplib}}
+library. Note, \emph{mplib} doesn't support
+\verb|verbatimtex|\slash\verb|btex| \ldots\ \verb|etex| constructs,
+currently. Here is an example of a MetaPost graphic inlined into a
+Plain \TeX\ document. For more information, please refer to the
+Lua\TeX~\cite[chap.~4.8]{luatex:manual} and
+\ttindex{luamplib}~\cite{hagen:luamplib} documentation.
+
+$$\begin{verbatim}
+\input luamplib.sty
+\mplibcode
+beginfig(1);
+ ...
+endfig;
+\endmplibcode
+\bye
+\end{verbatim}
+$$
+
+\paragraph{\LaTeX\ Format}
+\label{latexformat}
+\index{LaTeX?\LaTeX!format!importing MetaPost files}
+\index{TeX?\TeX!engine}
+\index{pdfTeX?pdf\TeX!engine}
+
+For users of the \LaTeX\ format and the traditional \TeX\ engine with
+Device Independent output (DVI\index{dvi file?{\tt dvi} file}) the
+well-known \ttindex{graphics} (or \ttindex{graphicx}) package aids in
+external graphics inclusion. The package supports different engines,
+guessing the correct output driver automatically, and can handle several
+graphic formats. The ``magic macro'' is
+$$ \verb|\includegraphics{|\descr{filename}\verb|}|%
+\index{includegraphics?\texttt{\string\includegraphics}} $$
+
+In DVI output driver mode the \ttt{graphics} package assumes all files
+with an unknown file extension, such as \texttt{.1} etc., to be in the
+EPS\index{EPS} format. It therefore handles MetaPost files with a
+numeric default file extension correctly (see~\cite{reckdahl:epslatex}
+for more information).
+
+When using the pdf\TeX\ engine with a built-in PDF output driver, the
+situation is a bit different. Only files with file extension
+\texttt{.mps}\index{mps file?{\tt mps} file}\index{files!mps?{\tt mps}}
+are recognized as purified EPS\index{EPS!purified} and can be converted
+to PDF\index{PDF} on-the-fly. The recommended procedure for embedding
+MetaPost graphics into \LaTeX\ documents compiled with pdf\TeX\ is
+therefore to change MetaPost's output file name extension via
+\verb|outputtemplate|\index{outputtemplate?\texttt{outputtemplate}} (see
+p.~\pageref{Doutputtemplate}). In the \LaTeX\ document include the
+graphic files with full name, e.g.,
+$$\begin{verbatim}
+\includegraphics{fig-1.mps}
+\end{verbatim}
+$$
+
+Note, the latter approach works with the \ttindex{dvips} driver, too.
+Even though, again, this time \ttt{.mps} is an unknown file extension,
+triggering EPS file handling in a fall-back procedure. This property of
+the \ttt{graphics} package, which comes in handy for MetaPost files, is
+the reason many MetaPost source files start with the line
+$$\begin{verbatim}
+outputtemplate := "%j-%c.mps";
+\end{verbatim}
+$$
+
+With the Lua\TeX\ engine\index{LuaTeX?Lua\TeX!engine}, embedding
+external graphics works the same as with pdf\TeX. Additionally,
+Lua\TeX\ users can inline MetaPost code directly into La\TeX\ documents.
+Lua\TeX\ is able to process such MetaPost code snippets, falling back to
+the built-in \emph{mplib}\index{mplib?\emph{mplib}} library. Note,
+\emph{mplib} doesn't support \verb|verbatimtex|\slash\verb|btex| \ldots\
+\verb|etex| constructs, currently. Here is an example of a MetaPost
+graphic inlined into a \LaTeX\ document. For more information, please
+refer to the Lua\TeX~\cite[chap.~4.8]{luatex:manual} and
+\ttindex{luamplib}~\cite{hagen:luamplib} documentation.
+$$\begin{verbatim}
+\documentclass{article}
+\usepackage{luamplib}
+\begin{document}
+\begin{mplibcode}
+beginfig(1);
+ ...
+endfig;
+\end{mplibcode}
+\end{document}
+\end{verbatim}
+$$
+
+\paragraph{Con\TeX t Format}
+\label{contextformat}
+\index{ConTeXt?Con\TeX t!format!importing MetaPost files}
+
+In Con\TeX t\index{ConTeXt?Con\TeX t} graphics support is integrated in
+the kernel, covering advanced features like shading, transparency, color
+spaces or image inclusion. The ``magic macro'' for embedding external
+graphics is
+$$ \verb|\externalfigure[|\descr{filename}\verb|]|%
+\index{externalfigure?\texttt{\string\externalfigure}} $$
+%
+The macro can handle numbered files as well as files with the \ttt{mps}
+suffix.
+
+Alternatively, Con\TeX t users can inline MetaPost code in the document
+source, which allows for more natural interfacing with document
+properties, font support, and automatic processing~\cite{hagen:metafun}.
+Here is an example of a MetaPost graphic inlined into a Con\TeX t
+document.
+$$\begin{verbatim}[commandchars=|\[\]]
+\starttext
+\startuseMPgraphic{|tdescr[name]}
+ ...
+\stopuseMPgraphic
+\useMPgraphic{|tdescr[name]}
+\stoptext
+\end{verbatim}
+$$
+
+Con\TeX t MkIV, being based on the Lua\TeX\ engine, provides a much
+tighter integration of MetaPost than older versions, since it can
+fall-back to the built-in \emph{mplib}\index{mplib?\emph{mplib}}
+library.
+
+\subsubsection{Troff}
+\label{troffimport}
+\index{troff!importing MetaPost files}
+
+It is also possible to include MetaPost output in a GNU
+troff\index{troff} document. The procedure is similar to
+Figure~\ref{fig:teximport}: the \ttindex{grops} output processor
+includes PostScript files when they are requested via troff's
+\ttt{\string\X}\index{X?\texttt{\string\X}} command. The
+\ttt{-mpspic}\index{mpspic?\texttt{-mpspic}} macro package provides a
+command \verb|.PSPIC|\index{PSPIC?\texttt{.PSPIC}}, which does just that
+when including an encapsulated PostScript file in the source code. For
+instance, the troff command
+$$ \hbox{\verb|.PSPIC fig.1|} $$
+includes \ttt{fig.1}, using the natural height and width of the
+image as given in the file's bounding box.
+
+\subsubsection{Web Applications}
+\label{webimport}
+
+An SVG\index{svg file?{\tt svg} file}\index{files!svg?{\tt svg}} file
+\texttt{fig.svg} can be easily embedded into
+HTML\index{HTML}\index{files!HTML} documents with the following code
+snippet:
+$$\begin{verbatim}
+<p>
+ <object data="fig.svg" type="image/svg+xml" width="300" height="200">
+ </object>
+</p>
+\end{verbatim}
+\index{object tag?\texttt{object} tag|see{HTML, tags, \texttt{object}}}
+\index{HTML!tags!object?\texttt{object}}
+$$
+The code is similar for PNG\index{png file?{\tt png}
+ file}\index{files!png?{\tt png}} files:
+$$\begin{verbatim}
+<p>
+ <img src="fig.png" alt="A picture.">
+</p>
+\end{verbatim}
+\index{img tag?\texttt{img} tag|see{HTML, tags, \texttt{img}}}
+\index{HTML!tags!img?\texttt{img}}
+$$
+The \texttt{width} and \texttt{height} attributes used above allow for
+scaling a graphic to an arbitrary size. More information about HTML
+tags and attributes can be found in an HTML reference.
+
+SVG and PNG files can also be imported by various interactive graphics
+editing programs, for example GIMP\index{GIMP} or
+Inkscape\index{Inkscape}. See Section~\ref{Dprologues} for information
+on font handling in SVG graphics.
+
+
+\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.
+
+
+\appendix
+\include{mpman-app-numbersystems}
+\include{mpman-app-refman}
+\include{mpman-app-legacy}
+
+
+\bibliographystyle{plain}
+\bibliography{mpman}
+
+
+\printindex
+
+
+\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
+% granted, provided that the above copyright notice appear in all
+% copies and that both that the copyright notice and this
+% permission notice and warranty disclaimer appear in supporting
+% documentation, and that the names of AT&T Bell Laboratories or
+% any of its entities not be used in advertising or publicity
+% pertaining to distribution of the software without specific,
+% written prior permission.
+
+% AT&T disclaims all warranties with regard to this software,
+% including all implied warranties of merchantability and fitness.
+% In no event shall AT&T be liable for any special, indirect or
+% consequential damages or any damages whatsoever resulting from
+% loss of use, data or profits, whether in an action of contract,
+% negligence or other tortious action, arising out of or in
+% connection with the use or performance of this software.
+
+% In addition, John Hobby, the original author of MetaPost and this
+% manual, makes the following requests:
+% - I request that it remain clear that I am the author of
+% "A User's Manual for MetaPost" and "Drawing Graphs with MetaPost".
+% - I request to be consulted before significant changes are made.
+
+%%% Local Variables:
+%%% mode: latex
+%%% TeX-PDF-mode: t
+%%% TeX-master: t
+%%% End: