doc 5

git-svn-id: svn://tug.org/texlive/trunk@81 c570f23f-e606-0410-a88d-b1316a301751
author: Karl Berry <karl@freefriends.org> 2006-01-09 00:45:48 +0000
committer: Karl Berry <karl@freefriends.org> 2006-01-09 00:45:48 +0000
commit: 5dc602d16c5be2fd035b254ca23484a90aebd6dc (patch)
tree: 72efb15fba318cc2096a8cc6999ed3fa0bff317d /Master/texmf-dist/doc/metapost/base
parent: b4fc5f639874db951177ec539299d20908adb654 (diff)
29 files changed, 9822 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/metapost/base/Makefile b/Master/texmf-dist/doc/metapost/base/Makefile
new file mode 100644
index 00000000000..18eff80e6b2
--- /dev/null
+++ b/Master/texmf-dist/doc/metapost/base/Makefile
@@ -0,0 +1,125 @@
+# Makefile for texmf/doc/metapost:
+# ================================
+
+MP	= mp
+
+#DVIPS	= dvips -Pold
+DVIPS	= dvips -Pold -D300
+
+LATEX	= latex
+BIBTEX	= bibtex
+
+TROFF	= troff -Tpost -ms -mpictures | dpost
+GROFF	= groff -Tps -mgs
+
+###
+
+MPMAN_FIGS = \
+	manfig.0   manfig.2   manfig.3   manfig.104 manfig.204 manfig.5   \
+	manfig.6   manfig.7   manfig.8   manfig.109 manfig.209 manfig.110 \
+	manfig.210 manfig.310 manfig.111 manfig.211 manfig.311 manfig.411 \
+	manfig.13  manfig.14  manfig.17  manfig.18  manfig.19  manfig.20  \
+	manfig.21  manfig.22  manfig.123 manfig.223 manfig.24  manfig.25  \
+	manfig.26  manfig.28  manfig.29  manfig.30  manfig.31  manfig.32  \
+	manfig.33  manfig.34  manfig.35  manfig.36  manfig.37  manfig.38  \
+	manfig.40  manfig.42  manfig.45  manfig.48  manfig.49  manfig.50  \
+	manfig.51  manfig.52
+
+MPGRAPH_FIGS = \
+	mpgraph.1  mpgraph.2  mpgraph.3  mpgraph.4  mpgraph.5  mpgraph.6  \
+	mpgraph.7  mpgraph.8  mpgraph.9  mpgraph.10 mpgraph.11
+MPGRPAH_DATA = \
+	agepop91.d agepopm.d countries.d energy.d lead.d matmul.d timepop.d
+
+EXAMPLE_FIGS = \
+	examples.1 examples.2 examples.3 examples.4 examples.5 examples.6 \
+	examples.7 examples.8 examples.9 
+
+###
+
+default: all
+all: mpman.ps mpgraph.ps mpintro.ps
+
+### MetaPost manuals
+
+mpman.ps: mpman.dvi $(MPMAN_FIGS)
+	@echo "WARNING: mpman.dvi was build using the obsolete font rpsyr."
+	@echo "You can safely ignore one warning about a checksum mismatch."
+	$(DVIPS) mpman.dvi -o mpman.ps
+
+mpgraph.ps: mpgraph.dvi $(MPGRAPH_FIGS)
+	@echo "WARNING: mpgraph.dvi was build using the obsolete versions of"
+	@echo "the fonts logo10 logo8 logosl10. You can safely ignore dvips's"
+	@echo "checksum warnings for these fonts."
+	$(DVIPS) mpgraph.dvi -o mpgraph.ps
+
+$(MPMAN_FIGS): manfig.mp
+	$(MP) manfig.mp
+
+$(MPGRAPH_FIGS): mpgraph.mp $(MPGRAPH_DATA)
+	$(MP) mpgraph.mp
+
+### LaTeX example
+
+mpintro.ps: mpintro.dvi $(EXAMPLE_FIGS)
+
+mpintro.dvi: mpintro.tex mpintro.bib
+	$(LATEX) mpintro
+	$(BIBTEX) mpintro
+	$(LATEX) mpintro
+	$(LATEX) mpintro
+
+$(EXAMPLE_FIGS): examples.mp
+	$(MP) examples.mp
+
+### troff and/or groff example
+
+grdemo.ps: grdemo.ms figs.1
+	cat grdemo.ms | $(GROFF) > grdemo.ps
+
+demo.ps: demo.ms figs.1 /usr/lib/tmac/tmac.pictures
+	cat demo.ms | $(TROFF) > demo.ps
+
+figs.1: figs.mp
+	test -d /usr/lib/font/devpost || $(MAKE) /usr/lib/font/devpost
+	test -d /usr/lib/font/devpost && $(MP) -T figs.mp
+
+/usr/lib/tmac/tmac.pictures:
+	@echo
+	@echo "WARNING: You don't seem to have the troff \`mpictures' macros"
+	@echo "which are needed to typeset the \`demo.ps' example document."
+	@echo "If your troff implementation doesn't provide these macros"
+	@echo "you're out of luck, I'm afraid.  Sorry, I can't help you!"
+	@echo 
+	@echo "Perhaps you may want to try \`grdemo.ps' as an alternative"
+	@echo "if you have GNU groff installed on your system?"
+	@echo
+	@false
+
+/usr/lib/font/devpost:
+	@echo
+	@echo "WARNING: You don't seem to have a suitable troff implementation"
+	@echo "on your system that matches the assumptions built into the"
+	@echo "MetaPost support programs.  To run MetaPost in troff mode"
+	@echo "you'll probably need a troff implementation from Bell Labs."
+	@echo "Using GNU groff as an alternative won't work, I'm afraid."
+	@echo
+	@false
+	
+
+### pattern rules
+
+.dvi.ps:
+	$(DVIPS) $< -o $@
+
+### cleanup targets
+
+clean:
+	rm -f $(MPMAN_FIGS) $(MPGRAPH_FIGS) $(EXAMPLE_FIGS)
+	rm -f *.mpx *.log *.aux mpxerr*
+
+distclean: clean
+	rm -f mpman.ps mpgraph.ps mpintro.ps
+
+.PHONY: clean
+.SUFFIXES: .dvi .ps
diff --git a/Master/texmf-dist/doc/metapost/base/grdemo.pdf b/Master/texmf-dist/doc/metapost/base/grdemo.pdf
new file mode 100644
index 00000000000..2769c05b35a
--- /dev/null
+++ b/Master/texmf-dist/doc/metapost/base/grdemo.pdf
diff --git a/Master/texmf-dist/doc/metapost/base/index.html b/Master/texmf-dist/doc/metapost/base/index.html
new file mode 100644
index 00000000000..3880ff99aa8
--- /dev/null
+++ b/Master/texmf-dist/doc/metapost/base/index.html
@@ -0,0 +1,62 @@
+<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
+<HTML>
+<HEAD>
+<TITLE>Index of texmf/doc/metapost/</TITLE>
+<!-- Created: UV, 1996/12/27 -->
+<!-- $Id: //depot/Master/texmf-dist/doc/metapost/base/index.html#3 $  $Date: 2004/06/20 $  $Author: karl $ -->
+</HEAD>
+
+<BODY>
+<H1>Index of <CODE>texmf/doc/metapost/</CODE></H1>
+
+<HR>
+
+<P> This page provides access to documentation about the MetaPost
+system by John Hobby, including the MetaPost program and standard
+MetaPost macro packages.
+</P>
+
+<P> Additional information about the MetaPost system
+can be found on John Hobby's WWW pages at
+<A HREF="http://plan9.bell-labs.com/who/hobby/MetaPost.html">
+http://plan9.bell-labs.com/who/hobby/MetaPost.html</A>.  Other links are
+available from <A HREF="http://tug.org/metapost.html">TUG's MetaPost web
+page</A>.
+</P>
+
+<H2>Index</H2>
+<DL>
+  <DT><A HREF="mpintro.pdf">
+      <CITE>The MetaPost System</CITE></A> (PDF)<BR>
+  <DD>Introduction to MetaPost, and also an example document for using
+      MetaPost with LaTeX.
+
+  <DT><A HREF="mpman.pdf">
+      <CITE>A User's Manual for MetaPost</CITE></A> (PDF)<BR>
+  <DD>AT&amp;T Bell Labs, CSTR 162, by John Hobby, 1992.<BR>
+      The primary manual for the MetaPost system, which includes
+      a description of most standard MetaPost macro packages.
+
+  <DT><A HREF="mpgraph.pdf">
+      <CITE>Drawing Graphs with MetaPost</CITE></A> (PDF)<BR>
+  <DD>AT&amp;T Bell Labs, CSTR 164, by John Hobby, 1993.<BR>
+      The manual for the MetaPost <code>graph.mp</code> package
+      and a few specialized features of the MetaPost program
+      that were added after the publication of the user manual.
+
+  <DT><A HREF="grdemo.pdf">
+      <CITE>MetaPost with groff</CITE></A> (PDF)<BR>
+  <DD>Example of using MetaPost with groff.
+
+  <DT><A HREF="source/">source</A><BR>
+  <DD>Subdirectory with all the MetaPost, TeX, and roff sources.
+
+</DL>
+<BR>
+
+
+<!-- hhmts start -->
+Last modified: $Date: 2004/06/20 $
+<!-- hhmts end -->
+</BODY>
+</HTML>
diff --git a/Master/texmf-dist/doc/metapost/base/mpgraph.pdf b/Master/texmf-dist/doc/metapost/base/mpgraph.pdf
new file mode 100644
index 00000000000..d4b2b3df1d0
--- /dev/null
+++ b/Master/texmf-dist/doc/metapost/base/mpgraph.pdf
diff --git a/Master/texmf-dist/doc/metapost/base/mpintro.pdf b/Master/texmf-dist/doc/metapost/base/mpintro.pdf
new file mode 100644
index 00000000000..b6c896c5de4
--- /dev/null
+++ b/Master/texmf-dist/doc/metapost/base/mpintro.pdf
diff --git a/Master/texmf-dist/doc/metapost/base/mpman.pdf b/Master/texmf-dist/doc/metapost/base/mpman.pdf
new file mode 100644
index 00000000000..c9546984f9e
--- /dev/null
+++ b/Master/texmf-dist/doc/metapost/base/mpman.pdf
diff --git a/Master/texmf-dist/doc/metapost/base/source/Makefile b/Master/texmf-dist/doc/metapost/base/source/Makefile
new file mode 100644
index 00000000000..ce7f3098a02
--- /dev/null
+++ b/Master/texmf-dist/doc/metapost/base/source/Makefile
@@ -0,0 +1,31 @@
+# Makefile for mpman and mpgraph.
+# (../Makefile has rules for building grdemo and mpintro.)
+# 
+%.pdf: %.ps
+	ps2pdf $< || rm -f $@
+
+%.ps: %.dvi
+	dvips -t letter $< -o $@ || rm -f $@
+
+all: mpman.pdf mpgraph.pdf
+
+mpgraph.dvi: mpgraph.tex mpgraph.bib mpgraph.mp
+	mpost mpgraph
+	latex mpgraph
+	bibtex mpgraph
+	latex mpgraph
+	latex mpgraph
+
+mpman.dvi: mpman.tex mpman.bib mpman.ist manfig.mp 
+	mpost manfig
+	latex mpman
+	bibtex mpman
+	latex mpman
+	latex mpman
+	makeindex -s mpman.ist mpman
+	latex mpman
+
+clean distclean:
+	rm -f manfig.[0-9]* mpgraph.[0-9]*
+	rm -f *.aux *.bbl *.blg *.dvi *.log *.mpx *.pdf *.ps
+	rm -f *.idx *.ilg *.ind *.toc
diff --git a/Master/texmf-dist/doc/metapost/base/source/README b/Master/texmf-dist/doc/metapost/base/source/README
new file mode 100644
index 00000000000..117f8773fa7
--- /dev/null
+++ b/Master/texmf-dist/doc/metapost/base/source/README
@@ -0,0 +1,32 @@
+This is the source for the documentation for MetaPost, consisting of
+"A User's Manual for MetaPost" and "Drawing Graphs with MetaPost",
+written by John D. Hobby.  They were converted to more modern LaTeX by
+Dylan Thurston.  The manual may be freely used and modified, but John
+Hobby makes these 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.
+
+See the end of mpman.tex or mpgraph.tex for the precise conditions.
+
+Included files:
+
+README
+agepop91.d
+agepopm.d
+countries.d
+ctabbing.sty
+energy.d
+lead.d
+manfig.mp
+matmul.d
+mpgraph.bib
+mpgraph.mp
+mpgraph.tex
+mpman.bib
+mpman.ist
+mpman.tex
+timepop.d
+
+See the Makefile for the sequence of commands to create the DVI/PS/PDF output.
diff --git a/Master/texmf-dist/doc/metapost/base/source/agepop91.d b/Master/texmf-dist/doc/metapost/base/source/agepop91.d
new file mode 100644
index 00000000000..5dfaeb31449
--- /dev/null
+++ b/Master/texmf-dist/doc/metapost/base/source/agepop91.d
@@ -0,0 +1,85 @@
+00 4011000
+01 3969000
+02 3806000
+03 3718000
+04 3717000
+05 3702000
+06 3681000
+07 3575000
+08 3512000
+09 3767000
+10 3703000
+11 3662000
+12 3484000
+13 3414000
+14 3409000
+15 3293000
+16 3362000
+17 3360000
+18 3391000
+19 3836000
+20 4120000
+21 4009000
+22 3767000
+23 3664000
+24 3812000
+25 3866000
+26 4069000
+27 4242000
+28 4086000
+29 4580000
+30 4501000
+31 4432000
+32 4387000
+33 4387000
+34 4534000
+35 4325000
+36 4201000
+37 4132000
+38 3788000
+39 4127000
+40 3836000
+41 3721000
+42 3634000
+43 3589000
+44 3998000
+45 2834000
+46 2823000
+47 2850000
+48 2857000
+49 2737000
+50 2528000
+51 2340000
+52 2298000
+53 2280000
+54 2200000
+55 2129000
+56 2195000
+57 2068000
+58 1946000
+59 2085000
+60 2124000
+61 2100000
+62 2076000
+63 2145000
+64 2138000
+65 2072000
+66 2069000
+67 2026000
+68 1911000
+69 1960000
+70 1886000
+71 1731000
+72 1649000
+73 1518000
+74 1458000
+75 1405000
+76 1334000
+77 1244000
+78 1204000
+79 1091000
+80  970000
+81  883000
+82  799000
+83  739000
+84  644000
+\ No newline at end of file
diff --git a/Master/texmf-dist/doc/metapost/base/source/agepopm.d b/Master/texmf-dist/doc/metapost/base/source/agepopm.d
new file mode 100644
index 00000000000..85c86e1b52a
--- /dev/null
+++ b/Master/texmf-dist/doc/metapost/base/source/agepopm.d
@@ -0,0 +1,85 @@
+00 4.011
+01 3.969
+02 3.806
+03 3.718
+04 3.717
+05 3.702
+06 3.681
+07 3.575
+08 3.512
+09 3.767
+10 3.703
+11 3.662
+12 3.484
+13 3.414
+14 3.409
+15 3.293
+16 3.362
+17 3.36
+18 3.391
+19 3.836
+20 4.12
+21 4.009
+22 3.767
+23 3.664
+24 3.812
+25 3.866
+26 4.069
+27 4.242
+28 4.086
+29 4.58
+30 4.501
+31 4.432
+32 4.387
+33 4.387
+34 4.534
+35 4.325
+36 4.201
+37 4.132
+38 3.788
+39 4.127
+40 3.836
+41 3.721
+42 3.634
+43 3.589
+44 3.998
+45 2.834
+46 2.823
+47 2.85
+48 2.857
+49 2.737
+50 2.528
+51 2.34
+52 2.298
+53 2.28
+54 2.2
+55 2.129
+56 2.195
+57 2.068
+58 1.946
+59 2.085
+60 2.124
+61 2.1
+62 2.076
+63 2.145
+64 2.138
+65 2.072
+66 2.069
+67 2.026
+68 1.911
+69 1.96
+70 1.886
+71 1.731
+72 1.649
+73 1.518
+74 1.458
+75 1.405
+76 1.334
+77 1.244
+78 1.204
+79 1.091
+80 0.97
+81 0.883
+82 0.799
+83 0.739
+84 0.644
+\ No newline at end of file
diff --git a/Master/texmf-dist/doc/metapost/base/source/countries.d b/Master/texmf-dist/doc/metapost/base/source/countries.d
new file mode 100644
index 00000000000..d1e43598200
--- /dev/null
+++ b/Master/texmf-dist/doc/metapost/base/source/countries.d
@@ -0,0 +1,60 @@
+20.910 75.7 US
+ 1.831 66.7 Alg
+ 1.694 70.9 Arg
+16.430 77.3 Aus
+ 0.180 53.0 Ban
+15.620 77.1 Bel
+ 3.090 65.2 Brz
+ 5.530 72.7 Bul
+ 0.404 54.9 Bur
+20.240 77.5 Can
+ 1.809 73.4 Chl
+ 0.547 70.0 Chn
+ 7.390 74.6 Tai
+ 1.139 71.0 Col
+ 7.876 72.9 Cze
+ 1.342 60.8 Egy
+ 0.120 51.3 Eth
+17.000 77.8 Fra
+17.446 75.8 Ger
+ 0.350 54.6 Gha
+ 5.286 77.7 Gre
+ 6.119 71.6 Hun
+ 0.321 57.2 Ind
+ 0.479 61.0 Inn
+ 1.440 64.5 Irn
+14.940 78.1 Ita
+22.900 79.2 Jap
+ 0.338 61.5 Ken
+ 0.205 52.6 Mad
+ 2.099 68.1 Mal
+ 2.170 72.2 Mex
+ 0.866 64.6 Mor
+ 0.078 47.4 Moz
+ 0.150 50.6 Nep
+14.980 77.8 Nth
+ 0.239 48.9 Nig
+ 1.427 69.0 NKo
+ 0.330 56.6 Pak
+ 1.903 64.3 Per
+ 0.697 64.6 Phi
+ 4.625 72.9 Pol
+ 4.323 74.7 Por
+ 4.896 71.9 Rom
+ 2.253 64.2 SAf
+ 4.920 69.7 SKo
+ 9.226 69.8 USS
+ 9.471 78.3 Spn
+ 0.409 71.1 Sri
+ 0.608 53.0 Sud
+21.900 77.8 Swe
+27.510 79.1 Swi
+ 1.608 69.4 Syr
+ 0.105 52.0 Tnz
+ 1.246 68.5 Tha
+ 1.380 69.8 Tur
+ 0.233 51.0 Uga
+14.580 76.5 UK
+ 2.158 74.2 Ven
+ 2.474 73.0 Yug
+ 0.258 53.9 Zai
+\ No newline at end of file
diff --git a/Master/texmf-dist/doc/metapost/base/source/ctabbing.sty b/Master/texmf-dist/doc/metapost/base/source/ctabbing.sty
new file mode 100644
index 00000000000..2f60af48011
--- /dev/null
+++ b/Master/texmf-dist/doc/metapost/base/source/ctabbing.sty
@@ -0,0 +1,17 @@
+
+% The ctabbing environment is a centered tabbing environment suitable for
+% displaying program fragments.  The vertical spacing is exactly like that
+% for normal text in a center environment.  This is achieved by setting
+% \@minipagetrue to fool \tabbing into thinking that it starts a minipage
+% and should therefore avoid all vertical space at the top.  (Note that any
+% space at all would defeat the \vtop command in \ctabbing.)  The
+% \vskip-\lastskip and \prevdepth saving commands avoid extra space after
+% \endtabbing
+
+\newdimen\ct@pd
+
+\def\ctabbing{\center\leavevmode\vtop\bgroup\@minipagetrue\begingroup\tabbing}
+
+\def\endctabbing{\endtabbing\endgroup\vskip-\lastskip
+                \global\ct@pd\prevdepth \egroup
+                \endcenter \global\prevdepth\ct@pd}
diff --git a/Master/texmf-dist/doc/metapost/base/source/demo.ms b/Master/texmf-dist/doc/metapost/base/source/demo.ms
new file mode 100644
index 00000000000..736c8641fbd
--- /dev/null
+++ b/Master/texmf-dist/doc/metapost/base/source/demo.ms
@@ -0,0 +1,105 @@
+.so /usr/lib/tmac/tmac.pictures
+.nr PS 11
+.nr VS 13
+.TL
+MetaPost with troff 
+.LP
+Since MetaPost is a picture-drawing language that outputs PostScript, it is
+necessary to use the
+.ft CW
+-mpictures
+.ft
+macro package.  Suppose you have written some figures in MetaPost and placed
+the input in a file \f(CWfigures.mp\fR.
+Running
+.nf
+.ft CW
+             mp -T figures
+.ft
+.fi
+to invoke the MetaPost interpreter produces output files
+\f(CWfigures.1\fR, \f(CWfigures.2\fR, .\|.\|.
+via macro calls such as
+.nf
+.ft CW
+            .BP figures.1 height width
+.ft
+.fi
+as explained in the
+.ft CW
+-mpictures
+.ft
+documentation. Note that the picture gets rescaled if the height and width
+in the \f(CW.BP\fR command don't match \fImp\fR's idea of the picture dimensions.
+.PP
+For instance,
+.BP figs.1 1.08i 1.5i
+this figure was derived from a file
+.ft CW
+figs.mp
+.ft
+and included at this point by invoking the \f(CW.BP\fR
+macro with height 1.08 inches and width 1.5 inches.  The macro tries to run text
+around the picture, but this can be stopped
+by using the \f(CW.EP\fR macro as was done here.
+.EP
+The file
+.ft CW
+figs.mp
+.ft
+looks like this:
+.nf
+.ft CW
+.nr PS 9
+.nr VS 11
+prologues:=1;
+input boxes
+beginfig(1);
+pair shadowshift; shadowshift=(1,-1)*bp;
+
+def drawshadowed(text t) =
+  forsuffixes $=t:
+    fill bpath$ shifted shadowshift;
+    unfill bpath$;
+    drawboxed($);
+  endfor
+enddef;
+
+boxit.a(btex \\s8A\\s+2 \\(lh a etex);
+circleit.b(btex $e sup {i omega t}$ etex rotated 20);
+b.w - a.e = (10bp,0);
+drawshadowed(a,b);
+draw a.e..b.w;
+
+draw bbox currentpicture dashed evenly;
+endfig;
+.nr PS 11
+.nr VS 13
+.ft
+.fi
+.PP
+Note that the typesetting commands in the
+\f(CWbtex\fR.\|.\|.\f(CWetex\fR blocks in the above example are processed by
+.nf
+.ft CW
+             eqn -d\\$\\$ | troff;
+.ft
+.fi
+If a different \fItroff\fR pipeline is desired, it can be specified via the
+.ft CW
+TROFF
+.ft
+environment variable.  For example,
+.nf
+.ft CW
+             TROFF='tbl | eqn -d\\$\\$ | troff -Tpost'
+.ft
+.fi
+adds \fItbl\fR to the pipeline.
+.PP
+Macro definitions and such can be added via the standard
+\f(CWverbatimtex\fR.\|.\|.\f(CWetex\fR mechanism that adds the given material
+to the \fItroff\fR input.  Such material should not generate any output since
+this would get mixed up with the next \f(CWbtex\fR.\|.\|.\f(CWetex\fR block.
+Thus, newlines between \f(CWverbatimtex\fR and \f(CWetex\fR must be
+protected with \f(CW\\\fR.
diff --git a/Master/texmf-dist/doc/metapost/base/source/energy.d b/Master/texmf-dist/doc/metapost/base/source/energy.d
new file mode 100644
index 00000000000..5b0b25596c7
--- /dev/null
+++ b/Master/texmf-dist/doc/metapost/base/source/energy.d
@@ -0,0 +1,75 @@
+1900 7.02  0.369 0.254 0.25
+1901 7.631 0.402 0.283 0.264
+1902 7.869 0.515 0.301 0.289
+1903 9.303 0.583 0.319 0.321
+1904 9.159 0.679 0.333 0.354
+1905 10.228 0.781 0.377 0.386
+1906 10.794 0.734 0.418 0.414
+1907 12.517 0.963 0.437 0.441
+1908 10.828 1.035 0.432 0.476
+1909 12.008 1.062 0.517 0.513
+1910 13.074 1.215 0.547 0.539
+1911 12.933 1.279 0.551 0.565
+1912 13.936 1.293 0.604 0.585
+1913 14.86  1.441 0.626 0.609
+1914 13.382 1.541 0.636 0.636
+1915 13.857 1.63  0.676 0.659
+1916 15.39  1.744 0.81  0.681
+1917 16.987 1.945 0.855 0.7
+1918 17.69  2.064 0.775 0.701
+1919 14.444 2.195 0.802 0.718
+1920 17.175 2.569 0.883 0.738
+1921 13.195 2.739 0.732 0.62
+1922 12.452 3.234 0.843 0.643
+1923 17.163 4.248 1.113 0.685
+1924 14.905 4.141 1.263 0.648
+1925 15.195 4.43  1.314 0.668
+1926 17.165 4.471 1.452 0.728
+1927 15.599 5.227 1.598 0.776
+1928 15.034 5.229 1.734 0.854
+1929 15.892 5.842 2.118 0.816
+1930 14.011 5.208 2.148 0.752
+1931 11.526 4.936 1.869 0.668
+1932 9.38   4.554 1.729 0.713
+1933 9.999  5.253 1.733 0.711
+1934 10.867 5.267 1.97 0.698
+1935 11.081 5.78 2.136 0.806
+1936 12.89  6.378 2.411 0.812
+1937 12.99  7.419 2.684 0.871
+1938 10.303 7.043 2.565 0.866
+1939 11.653 7.337 2.763 0.838
+1940 13.38  7.849 2.979 0.88
+1941 14.903 8.133 3.162 0.934
+1942 16.799 8.043 3.436 1.136
+1943 17.003 8.733 3.839 1.304
+1944 17.851 9.732 4.176 1.344
+1945 16.529 9.939 4.423 1.442
+1946 15.526 10.057 4.55 1.406
+1947 17.975 10.771 5.012 1.296
+1948 17.158 11.717 5.615 1.369
+1949 12.557 10.683 5.911 1.425
+1950 14.647 11.449 6.841 1.415
+1951 15.066 13.037 8.106 1.424
+1952 13.262 13.282 8.705 1.466
+1953 12.767 13.671 9.116 1.413
+1954 11.001 13.247 9.488 1.36
+1955 12.745 14.445 10.532 1.36
+1956 13.747 15.344 11.252 1.435
+1957 13.444 15.346 11.885 1.422
+1958 11.201 14.154 12.244 1.592
+1959 11.105 14.662 13.361 1.551
+1960 11.14  14.664 14.135 1.608
+1961 10.751 15.185 14.691 1.656
+1962 11.211 15.495 15.365 1.816
+1963 12.176 15.741 16.271 1.768
+1964 12.854 15.691 17.138 1.886
+1965 13.485 15.93  17.652 2.059
+1966 13.836 16.925 18.984 2.062
+1967 14.215 18.1   20.087 2.347
+1968 13.955 18.593 21.548 2.349
+1969 14.223 18.886 22.838 2.648
+1970 15.248 19.772 24.154 2.63
+
+Cols 2-5: U.S. annual production of
+2) coal, 3) crude oil, 4) natural gas, 5) hydroelectric power
+in quadrillions of British thermal units.
+\ No newline at end of file
diff --git a/Master/texmf-dist/doc/metapost/base/source/examples.mp b/Master/texmf-dist/doc/metapost/base/source/examples.mp
new file mode 100644
index 00000000000..0e2a8dc0a65
--- /dev/null
+++ b/Master/texmf-dist/doc/metapost/base/source/examples.mp
@@ -0,0 +1,247 @@
+beginfig(1);
+a=.7in; b=0.5in;
+z0=(0,0); z1=(a,0); z2=(0,b);
+z0=.5[z1,z3]=.5[z2,z4];
+draw z1..z2..z3..z4..cycle;
+drawarrow z0..z1;
+drawarrow z0..z2;
+label.top(btex $a$ etex, .5[z0,z1]);
+label.lft(btex $b$ etex, .5[z0,z2]);
+endfig;
+
+
+
+
+beginfig(2);
+
+h=2in; w=2.7in;
+path p[], q[], pp;
+for i=1.5,2,4:
+  ii := i**2;
+  p[i] = (w/ii,h){1/ii,-1}...(w/i,h/i)...(w,h/ii){1,-1/ii};
+endfor
+for i=.5,1.5:
+  q[i] = origin..(w,i*h) cutafter p1.5;
+endfor
+
+pp = buildcycle(q0.5, p2, q1.5, p4);
+
+fill pp withcolor .8white;
+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;
+makelabel.top(btex $P$ etex, p2 intersectionpoint q0.5);
+makelabel.rt(btex $Q$ etex, p2 intersectionpoint q1.5);
+endfig;
+
+
+
+
+beginfig(3);
+
+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#))
+  scaled scf yscaled(1/#);
+
+vardef vertline primary x = (x,-infinity)..(x,infinity) enddef;
+primarydef f atx x = (f intersectionpoint vertline x) enddef;
+primarydef f whenx x = xpart(f intersectiontimes vertline x) enddef;
+
+z1a = (2.5scf,0);
+z1 = fun atx x1a;
+y2a=0; z1-z2a=whatever*direction fun whenx x1 of fun;
+z2 = fun atx x2a;
+y3a=0; z2-z3a=whatever*direction fun whenx x2 of fun;
+
+draw fun withpen pencircle scaled 1pt;
+drawarrow (0,0)..(3.2scf,0);
+
+label.bot(btex $x_1$ etex, z1a);
+draw z1a..z1 dashed evenly;
+makelabel(nullpicture, z1);
+draw z1..z2a withpen pencircle scaled .3;
+label.bot(btex $x_2$ etex, z2a);
+draw z2a..z2 dashed evenly;
+makelabel(nullpicture, z2);
+draw z2..z3a withpen pencircle scaled .3;
+label.bot(btex $x_3$ etex, z3a);
+endfig;
+
+
+
+beginfig(4);
+for i=0 upto 2:
+  z[i]=(0,40i); z[i+3]-z[i]=(100,30);
+endfor
+pickup pencircle scaled 18;
+def gray = withcolor .8white enddef;
+draw z0..z3 gray;
+linecap:=butt; draw z1..z4 gray;
+linecap:=squared; draw z2..z5 gray;
+labels.top(0,1,2,3,4,5);
+endfig; linecap:=rounded;
+
+
+
+beginfig(5);
+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;
+def gray = withcolor .8white enddef;
+draw z0--z3--z6 gray;
+linejoin:=mitered; draw z1..z4--z7 gray;
+linejoin:=beveled; draw z2..z5--z8 gray;
+labels.bot(0,1,2,3,4,5,6,7,8);
+endfig; linejoin:=rounded;
+
+
+
+input boxes
+
+
+\beginfig(6);
+fill unitsquare xscaled 1.1in yscaled .7in withcolor .9white;
+boxit(currentpicture);
+dx = dy = .25in;
+clearit; drawboxed();
+forsuffixes $=n,c: makelabel.top(str $, $); endfor
+makelabel.bot("s",s);
+forsuffixes $=ne,e,se: makelabel.rt(str $, $); endfor
+forsuffixes $=nw,w,sw: makelabel.lft(str $, $); endfor
+pickup pencircle scaled .3bp;
+vardef larrow@#(expr a, da, s) =
+  drawdblarrow a..a+da; label@#(s,a+.5da); enddef;
+larrow.rt(n, (0,-dy), "dy");
+larrow.rt(s, (0,dy), "dy");
+larrow.top(e, (-dx,0), "dx");
+larrow.top(w, (dx,0), "dx");
+endfig;
+
+
+
+beginfig(7);
+boxjoin(a.se=b.sw; a.ne=b.nw );
+boxit.a(btex $\cdots$ etex);
+boxit.ni(btex $n_i$ etex);
+boxit.di(btex $d_i$ etex);
+boxit.nii(btex $n_{i+1}$ etex);
+boxit.dii(btex $d_{i+1}$ etex);
+boxit.aa(pic_.a);
+boxit.nk(btex $n_k$ etex);
+boxit.dk(btex $d_k$ etex);
+
+di.dy = 2;
+drawboxed(a,ni,di,nii,dii,aa,nk,dk);
+label.lft("ndtable:", a.w);
+
+boxjoin(a.sw=b.nw; a.se=b.ne);
+interim defaultdy:=7;
+boxit.ba();
+boxit.bb();
+boxit.bc();
+boxit.bd(btex $\vdots$ etex);
+boxit.be();
+boxit.bf();
+bd.dx = 8;
+ba.ne = a.sw - (15,10);
+
+drawboxed(ba,bb,bc,bd,be,bf);
+label.lft("hashtab:", ba.w);
+
+def ndblock suffix $ =
+  boxjoin(a.sw=b.nw; a.se=b.ne);
+  forsuffixes $$=$a,$b,$c:
+    boxit$$(); ($$dx,$$dy)=(5.5,4);
+  endfor;
+enddef;
+
+ndblock nda;
+ndblock ndb;
+ndblock ndc;
+nda.a.c - bb.c = ndb.a.c - nda.c.c = (whatever,0);
+xpart ndb.c.se = xpart ndc.a.ne = xpart di.c;
+ndc.a.c - be.c = (whatever,0);
+
+drawboxes(nda.a,nda.b,nda.c, ndb.a,ndb.b,ndb.c, ndc.a,ndc.b,ndc.c);
+
+drawarrow bb.c .. nda.a.w;
+drawarrow be.c .. ndc.a.w;
+drawarrow nda.c.c .. ndb.a.w;
+drawarrow nda.a.c{right}..{curl0}ni.c cutafter bpath ni;
+drawarrow nda.b.c{right}..{curl0}di.c cutafter bpath di;
+drawarrow ndc.a.c{right}..{curl0}nii.c cutafter bpath nii;
+drawarrow ndc.b.c{right}..{curl0}dii.c cutafter bpath dii;
+drawarrow ndb.a.c{right}..nk.c cutafter bpath nk;
+drawarrow ndb.b.c{right}..dk.c cutafter bpath dk;
+
+x.ptr = xpart aa.c;
+y.ptr = ypart ndc.a.ne;
+drawarrow subpath (0,.7) of (z.ptr..{left}ndc.c.c) dashed evenly;
+label.rt(btex ndblock etex, z.ptr);
+endfig;
+
+
+
+
+beginfig(8)
+interim circmargin := .07in;
+fill unitsquare xscaled 1.1in yscaled .7in withcolor .9white;
+circleit(currentpicture);
+dx = dy;
+clearit; drawboxed();
+forsuffixes $=n,c: makelabel.top(str $, $); endfor
+makelabel.bot("s",s);
+makelabel.rt("e", e);
+makelabel.lft("w", w);
+pickup pencircle scaled .3bp;
+vardef larrow@#(expr a, da, s) =
+  drawdblarrow a..a+da; label@#(s,a+.5da); enddef;
+larrow.rt(n, (0,-dy), "dy");
+larrow.rt(s, (0,dy), "dy");
+larrow.top(e, (-dx,0), "dx");
+larrow.top(w, (dx,0), "dx");
+endfig;
+
+
+
+
+beginfig(9);
+vardef cuta(suffix a,b) expr p =
+  drawarrow p cutbefore bpath.a cutafter bpath.b;
+  point .5*length p of p
+enddef;
+
+vardef self@# expr p =
+  cuta(@#,@#) @#.c{curl0}..@#.c+p..{curl0}@#.c  enddef;
+
+verbatimtex \def\stk#1#2{$\displaystyle{\matrix{#1\cr#2\cr}}$} etex
+circleit.aa("Start"); aa.dx=aa.dy;
+circleit.bb(btex \stk B{(a|b)^*a} etex);
+circleit.cc(btex \stk C{b^*} etex);
+circleit.dd(btex \stk D{(a|b)^*ab} etex);
+circleit.ee("Stop"); ee.dx=ee.dy;
+
+numeric hsep;
+bb.c-aa.c = dd.c-bb.c = ee.c-dd.c = (hsep,0);
+cc.c-bb.c = (0,.8hsep);
+xpart(ee.e - aa.w) = 3.8in;
+drawboxed(aa,bb,cc,dd,ee);
+
+label.ulft(btex$b$etex, cuta(aa,cc) aa.c{dir50}..cc.c);
+label.top(btex$b$etex, self.cc(0,30pt));
+label.rt(btex$a$etex, cuta(cc,bb) cc.c..bb.c);
+label.top(btex$a$etex, cuta(aa,bb) aa.c..bb.c);
+label.llft(btex$a$etex, self.bb(-20pt,-35pt));
+label.top(btex$b$etex, cuta(bb,dd) bb.c..dd.c);
+label.top(btex$b$etex, cuta(dd,ee) dd.c..ee.c);
+label.lrt(btex$a$etex, cuta(dd,bb) dd.c..{dir140}bb.c);
+label.bot(btex$a$etex, cuta(ee,bb) ee.c..tension1.3 ..{dir115}bb.c);
+label.urt(btex$b$etex, cuta(ee,cc) ee.c{(cc.c-ee.c)rotated-15}..cc.c);
+endfig;
+
+end
diff --git a/Master/texmf-dist/doc/metapost/base/source/figs.mp b/Master/texmf-dist/doc/metapost/base/source/figs.mp
new file mode 100644
index 00000000000..67c86a098d1
--- /dev/null
+++ b/Master/texmf-dist/doc/metapost/base/source/figs.mp
@@ -0,0 +1,22 @@
+input boxes
+beginfig(1);
+pair shadowshift; shadowshift=(1,-1)*bp;
+
+def drawshadowed(text t) =
+  forsuffixes $=t:
+    fill bpath$ shifted shadowshift;
+    unfill bpath$;
+    drawboxed($);
+  endfor
+enddef;
+
+boxit.a(btex \s8A\s+2 \(lh a etex);
+circleit.b(btex $e sup {i omega t}$ etex rotated 20);
+b.w - a.e = (10,0)*bp;
+drawshadowed(a,b);
+draw a.e..b.w;
+
+draw bbox currentpicture dashed evenly;
+endfig;
+
+end
diff --git a/Master/texmf-dist/doc/metapost/base/source/grdemo.ms b/Master/texmf-dist/doc/metapost/base/source/grdemo.ms
new file mode 100644
index 00000000000..fbcbfaceff4
--- /dev/null
+++ b/Master/texmf-dist/doc/metapost/base/source/grdemo.ms
@@ -0,0 +1,124 @@
+.nr PS 11
+.nr VS 13
+.TL
+MetaPost with groff 
+.LP
+Since MetaPost is a picture-drawing language that outputs PostScript,
+it is necessary to use the
+.ft CW
+-mpspic
+.ft
+macro package, which is automatically included when \fIgroff\fR 
+is invoked with the
+.ft CW
+-Tps
+.ft 
+option to prepare output for PostScript printers or previewers.
+.PP
+Suppose you have written some figures in MetaPost and placed
+the input in a file \f(CWfigures.mp\fR.
+Running
+.nf
+.ft CW
+             mp -T figures
+.ft
+.fi
+to invoke the MetaPost interpreter produces output files
+\f(CWfigures.1\fR, \f(CWfigures.2\fR, .\|.\|. 
+which can be included in a \fIgroff\fR document via macro calls 
+such as
+.nf
+.ft CW
+            .PSPIC figures.1 width height
+.ft
+.fi
+as explained in the \fIgrops\fR(1) documentation. 
+Note that the picture gets rescaled if the height and width
+in the \f(CW.PSPIC\fR command don't match \fImp\fR's idea of 
+the picture dimensions.
+.PP
+For instance,
+.PSPIC figs.1 1.5i 1.08i
+this figure was derived from a file
+.ft CW
+figs.mp
+.ft
+and included at this point by invoking the \f(CW.PSPIC\fR macro 
+with height 1.08 inches and width 1.5 inches.  
+.PP
+The file
+.ft CW
+figs.mp
+.ft
+looks like this:
+.nf
+.ft CW
+.nr PS 9
+.nr VS 11
+prologues:=1;
+input boxes
+beginfig(1);
+pair shadowshift; shadowshift=(1,-1)*bp;
+
+def drawshadowed(text t) =
+  forsuffixes $=t:
+    fill bpath$ shifted shadowshift;
+    unfill bpath$;
+    drawboxed($);
+  endfor
+enddef;
+
+boxit.a(btex \\s8A\\s+2 \\(lh a etex);
+circleit.b(btex $e sup {i omega t}$ etex rotated 20);
+b.w - a.e = (10bp,0);
+drawshadowed(a,b);
+draw a.e..b.w;
+
+draw bbox currentpicture dashed evenly;
+endfig;
+.nr PS 11
+.nr VS 13
+.ft
+.fi
+.PP
+Note that the typesetting commands in the
+\f(CWbtex\fR.\|.\|.\f(CWetex\fR blocks in the above example 
+are processed by
+.nf
+.ft CW
+             eqn -d\\$\\$ | troff -Tpost
+.ft
+.fi
+If a different \fItroff\fR pipeline is desired, it can be specified 
+via the
+.ft CW
+TROFF
+.ft
+environment variable.  For example,
+.nf
+.ft CW
+             TROFF='tbl | eqn -d\\$\\$ | troff -Tpost'
+.ft
+.fi
+adds \fItbl\fR to the pipeline in addition to \fIeqn\fR.
+.PP
+Macro definitions and such can be added via the standard
+\f(CWverbatimtex\fR.\|.\|.\f(CWetex\fR mechanism that adds the 
+given material to the \fItroff\fR input.  Such material should 
+not generate any output since this would get mixed up with the 
+next \f(CWbtex\fR.\|.\|.\f(CWetex\fR block.  Thus, newlines between 
+\f(CWverbatimtex\fR and \f(CWetex\fR must be protected with \f(CW\\\fR.
+.PP
+Unfortunately, typesetting of \f(CWbtex\fR.\|.\|.\f(CWetex\fR blocks
+currently doesn't work with \fIgroff\fR and equires a UNIX
+\fItroff\fR implementation, because MetaPost's \f(CWdmp\fR
+post-processor can't handle \fIgroff\fR's extended font and output
+file formats documented in \fIgroff_font\fR(5) and \fIgroff_out\fR(5).
+Nevertheless, using \fItroff\fR to prepare figures with MetaPost 
+and \fIgroff\fR to typeset them may still be a useful combination 
+if your \fItroff\fR implementation doesn't provide the
+.ft CW
+-mpictures
+.ft 
+macro packages.
+
diff --git a/Master/texmf-dist/doc/metapost/base/source/lead.d b/Master/texmf-dist/doc/metapost/base/source/lead.d
new file mode 100644
index 00000000000..8e95355af1c
--- /dev/null
+++ b/Master/texmf-dist/doc/metapost/base/source/lead.d
@@ -0,0 +1,24 @@
+80 70.6
+81 56.4
+82 54.4
+83 46.4
+84 40.1
+85 20.1
+86 8.4
+87 8.0
+88 7.6
+89 7.2
+90 7.1
+
+82 .484
+83 .413
+84 .381
+85 .258
+86 .151
+87 .108
+88 .087
+89 .074
+90 .070
+
+First: National lead emissions in thousands of metric tons
+Second: Average lead level in micrograms per cubic meter of air
+\ No newline at end of file
diff --git a/Master/texmf-dist/doc/metapost/base/source/manfig.mp b/Master/texmf-dist/doc/metapost/base/source/manfig.mp
new file mode 100644
index 00000000000..e024f62ffb5
--- /dev/null
+++ b/Master/texmf-dist/doc/metapost/base/source/manfig.mp
@@ -0,0 +1,859 @@
+%% This is for the MathTime version that uses PostScript outline fonts
+%% ----------------------------------------------------------------
+%verbatimtex \documentstyle[times]{article}
+%	\begin{document}
+%etex
+%defaultfont := "rptmr";
+%% ----------------------------------------------------------------
+
+beginfig(0);
+draw (20,20)--(0,0)--(0,30)--(30,0)--(0,0);
+endfig;
+
+
+beginfig(2); numeric u;
+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:
+    draw (i*u,j*u);
+  endfor
+endfor
+endfig;
+
+
+beginfig(3);
+z0 = (0,0);    z1 = (60,40);
+z2 = (40,90);  z3 = (10,70);
+z4 = (30,50);
+draw z0..z1..z2..z3..z4;
+dotlabels.top(0,2,4);
+dotlabels.lft(3);
+dotlabels.lrt(1);
+endfig;
+
+
+beginfig(104);
+z0 = (0,0);    z1 = (60,40);
+z2 = (40,90);  z3 = (10,70);
+z4 = (30,50);
+draw z0..z1..z2..z3..z4..cycle;
+dotlabels.top(2,4);
+dotlabels.lft(0,3);
+dotlabels.lrt(1);
+endfig;
+
+
+beginfig(204);
+z0 = (0,0);    z1 = (60,40);
+z2 = (40,90);  z3 = (10,70);
+z4 = (30,50);
+draw z0..z1..z2..z3--z4--cycle;
+dotlabels.top(2,4);
+dotlabels.lft(0,3);
+dotlabels.lrt(1);
+endfig;
+
+
+beginfig(5);
+z0 = (0,0);    z1 = (60,40);
+z2 = (40,90);  z3 = (10,70);
+z4 = (30,50);
+path p; p = z0..z1..z2..z3..z4;
+draw p;
+for t=0 upto 3:
+  draw point t of p--postcontrol t of p
+    --precontrol t+1 of p--point t+1 of p
+    dashed (evenly scaled .5);
+endfor
+dotlabels.top(0,2,4);
+dotlabels.lft(3);
+dotlabels.lrt(1);
+endfig;
+
+
+beginfig(6);
+z0 = (0,0);    z1 = (60,40);
+z2 = (40,90);  z3 = (10,70);
+z4 = (30,50);
+draw z0..z1{up}..z2{left}..z3..z4;
+dotlabels.top(0,2,4);
+dotlabels.lft(3);
+dotlabels.lrt(1);
+endfig;
+
+
+beginfig(7)
+for a=0 upto 9:
+  draw (0,0){dir 45}..{dir -10a}(6cm,0);
+endfor
+endfig;
+
+beginfig(8)
+for a=0 upto 7:
+  draw (0,0){dir 45}..{dir 10a}(6cm,0);
+endfor
+endfig;
+
+
+beginfig(109);
+z2=-z0=(1in,0); z1=(0,.2in);
+draw z0{up}..z1{right}..z2{down};
+dotlabels.bot(0,1,2);
+endfig;
+
+
+beginfig(209);
+z2=-z0=(1in,0); z1=(0,.2in);
+draw z0{up}...z1{right}...z2{down};
+dotlabels.bot(0,1,2);
+endfig;
+
+
+beginfig(110);
+numeric u; 10u=1.5in;
+-z0=z3=(5u,0);
+(-x1,y1)=z2=(3u,2u);
+draw z0..z1..z2..z3;
+dotlabels.bot(0,1,2,3);
+endfig;
+
+
+beginfig(210);
+numeric u; 10u=1.5in;
+-z0=z3=(5u,0);
+(-x1,y1)=z2=(3u,2u);
+draw z0..z1..tension 1.3..z2..z3;
+dotlabels.bot(0,1,2,3);
+endfig;
+
+
+beginfig(310);
+numeric u; 10u=1.5in;
+-z0=z3=(5u,0);
+(-x1,y1)=z2=(3u,2u);
+draw z0..z1..tension 1.5 and 1..z2..z3;
+dotlabels.bot(0,1,2,3);
+endfig;
+
+
+beginfig(111);
+numeric u, c; 10u=1.4in; c=0;
+z1=(0,0); (x0,-y0)=z2=(2u,5u);
+draw z0{curl c}..z1..{curl c}z2;
+dotlabels.rt(0,1,2);
+endfig;
+
+
+beginfig(211);
+numeric u, c; 10u=1.4in; c=1;
+z1=(0,0); (x0,-y0)=z2=(2u,5u);
+draw z0{curl c}..z1..{curl c}z2;
+dotlabels.rt(0,1,2);
+endfig;
+
+
+beginfig(311);
+numeric u, c; 10u=1.4in; c=2;
+z1=(0,0); (x0,-y0)=z2=(2u,5u);
+draw z0{curl c}..z1..{curl c}z2;
+dotlabels.rt(0,1,2);
+endfig;
+
+
+beginfig(411);
+numeric u, c; 10u=1.4in; c=infinity;
+z1=(0,0); (x0,-y0)=z2=(2u,5u);
+draw z0{curl c}..z1..{curl c}z2;
+dotlabels.rt(0,1,2);
+endfig;
+
+
+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;
+%
+dotlabels.bot(1,2);
+dotlabels.rt(3);
+dotlabels.lft(6);
+dotlabels.top(20,30,40);
+endfig;
+
+
+vardef llet(expr c) =
+  c infont defaultfont scaled magstep3
+enddef;
+
+primarydef p centered h =
+  (p shifted (h - xpart .5[llcorner p,lrcorner p], 0))
+enddef;
+
+beginfig(14);
+string s; s = "abcde";
+numeric u,n, ytop, ybot;
+n = 5;
+ytop = 3bp + ypart urcorner llet(s);
+ybot = -3bp + ypart llcorner llet(s);
+ytop - ybot = u;
+draw (n*u,ybot)--(0,ybot)--(0,ytop)--(n*u,ytop);
+for i=1 upto n:
+  draw (i*u,ybot)..(i*u,ytop);
+  draw llet(substring (i-1,i) of s) centered ((i-.5)*u);
+  label.bot(decimal i, (i*u,ybot));
+endfor
+picture llab; llab = btex \llap{$x={}$}0 etex;
+z0 = urcorner llab;
+draw llab shifted (-.5*x0, ybot-labeloffset-y0);
+endfig;
+
+
+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;
+
+
+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;
+
+
+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;
+
+
+beginfig(20);
+picture p;
+p = "testing" infont "rptmr" scaled 7;
+draw p;
+draw llcorner p--lrcorner p--urcorner p--ulcorner p--cycle;
+dotlabel.lft(btex \tt llcorner etex, llcorner p);
+dotlabel.rt(btex \tt lrcorner etex, lrcorner p);
+dotlabel.lft(btex \tt ulcorner etex, ulcorner p);
+dotlabel.rt(btex \tt urcorner etex, urcorner p);
+endfig;
+
+
+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;
+
+
+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;
+
+
+beginfig(123);
+path aa, b;
+b = a shifted (0,1cm);
+aa = halfcircle scaled 2cm;
+draw aa;
+draw b dashed evenly;
+z1 = aa intersectionpoint reverse b;
+z2 = reverse aa intersectionpoint b;
+dotlabel.rt(btex 1 etex, z1);
+dotlabel.lft(btex 2 etex, z2);
+label.bot(btex \tt aa etex, point 0 of aa);
+label.bot(btex \tt b etex, point 2 of b);
+endfig;
+
+beginfig(223);
+path aa, b;
+b = a shifted (0,1cm);
+aa = halfcircle scaled 2cm;
+numeric t[], tt[];
+(t1,8-tt1) = aa intersectiontimes reverse b;
+(4-t2,tt2) = reverse aa intersectiontimes b;
+pickup(pencircle scaled .3);
+draw aa;
+draw b;
+pickup(pencircle scaled .8);
+draw subpath (t1,t2) of aa;
+draw subpath (tt2,tt1) of b;
+dotlabel.rt(btex 1 etex, point t1 of aa);
+dotlabel.lft(btex 2 etex, point t2 of aa);
+label.bot(btex \tt aa etex, point 0 of aa);
+label.bot(btex \tt b etex, point 2 of b);
+endfig;
+
+
+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;
+
+
+beginfig(25);
+numeric u;
+u = .2in;
+path a, b;
+a = (0,0){up}..(4u,0)..(8u,0)..(8u,4u);
+b = (10u,3u)..(5u,u)..(-u,u);
+numeric t; t=0;
+forsuffixes $=bot, llft, lrt, lft:
+  dotlabel$(decimal t, point t of a);
+  t:=t+1;
+endfor
+for i=0 upto 2:
+   dotlabel.top(decimal i, point i of b);
+endfor
+pickup(pencircle scaled .3);
+draw a;
+pickup(pencircle scaled .8);
+draw b;
+% intersections (atime, btime):
+% (0.2501,1.77225)
+% (2.58316,0.23619)
+% (0.75288,1.40094)
+endfig;
+
+
+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;
+
+
+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;
+
+
+beginfig(29);
+if unknown withdots:	% So this works w/o MetaPost version 0.5
+  picture withdots; withdots=dashpattern(off 2.5 on 0 off 2.5);
+fi
+z0 = (0,0);
+z1 = (2in-2bp,0);
+for i=1 upto 4:
+  z[2i]-z[2i-2] = z[2i+1]-z[2i-1] = (0,14pt);
+endfor
+draw z0..z1 dashed evenly;
+label.rt(btex \tt dashed evenly etex, z1);
+draw z2..z3 dashed evenly scaled 2;
+label.rt(btex \tt dashed evenly scaled 2 etex, z3);
+draw z4..z5 dashed evenly scaled 4;
+label.rt(btex \tt dashed evenly scaled 4 etex, z5);
+draw z6..z7 dashed withdots;
+label.rt(btex \tt dashed withdots etex, z7);
+draw z8..z9 dashed withdots scaled 2;
+label.rt(btex \tt dashed withdots scaled 2 etex, z9);
+endfig;
+
+
+beginfig(30);
+picture e[]; e4=evenly scaled 4;
+z0 = (0,0);
+z1 = (2in,0);
+for i=1 upto 3:
+  z[2i]-z[2i-2] = z[2i+1]-z[2i-1] = (0,14pt);
+endfor
+dotlabels.lft(0,2,4,6);
+draw z0..z1 dashed e4;
+dotlabel.rt(btex 1 \tt\ draw z0..z1 dashed e4 etex, z1);
+draw z2..z3 dashed e4 shifted (6bp,0);
+dotlabel.rt(btex 3 \tt\ draw z2..z3 dashed e4 shifted (6bp,0) etex, z3);
+draw z4..z5 dashed e4 shifted (12bp,0);
+dotlabel.rt(btex 5 \tt\ draw z4..z5 dashed e4 shifted (12bp,0) etex, z5);
+draw z6..z7 dashed e4 shifted (18bp,0);
+dotlabel.rt(btex 7 \tt\ draw z6..z7 dashed e4 shifted (18bp,0) etex, z7);
+endfig;
+
+
+beginfig(31);
+picture d; d = dashpattern(on 6bp  off 12bp  on 6bp);
+draw d;
+endfig;
+
+
+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;
+
+
+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;
+
+
+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;
+
+
+beginfig(35);
+z2a=(0,0);
+(-x1a,y1a) = -z3a = .5in*unitvector(6,1);
+z1b - z1a = .75*z1a rotated -90;
+z2b - z1b = whatever*(z2a-z1a);
+z3b - z2b = whatever*(z3a-z2a);
+y2b = 0;
+z3b - z3a = whatever*(z3a rotated 90);
+z0b-z1b = z0a-z1a = z1a;
+x4a=x2a; x4b=x2b;
+y4a = y4b = 1.3*y3b;
+fill z1a--z2a--z3a--z3b--z2b--z1b--cycle withcolor .8 white;
+for p= z2a--z4a, z2b--z4b, z0a--z1a, z0b--z1b:
+   draw p dashed evenly;
+endfor
+drawdblarrow z4a--z4b;
+drawdblarrow z0a--z0b;
+label.bot(btex miter length etex, .5[z4a,z4b]);
+label.ulft(btex line width etex, .5[z0a,z0b]);
+endfig;
+
+
+beginfig(36);
+z[-1]=(0,0); z0=(1in,0);
+for i=1 upto 6:
+  z[i]-z[i-2] = (0,-15pt);
+  if x[i]=0: label.lft(decimal i, z[i]);
+  fi
+endfor
+drawarrow z1..z2;
+drawarrow reverse(z3..z4);
+drawdblarrow z5..z6;
+label.rt(btex 2 \tt\ drawarrow z1..z2 etex, z2);
+label.rt(btex 4 \tt\ drawarrow reverse(z3..z4) etex, z4);
+label.rt(btex 6 \tt\ drawdblarrow z5..z6 etex, z6);
+endfig;
+
+
+beginfig(37);
+path p, q, r;
+ahlength := 1.5cm;
+pickup pencircle scaled .2cm;
+p = (0,0)..{right}(2.5cm,2cm);
+q = counterclockwise arrowhead p;
+z0 = directionpoint up of q;
+z.a = directionpoint right of q;
+z.b = directionpoint (-1,-1) of q;
+drawarrow p withcolor .4white;
+pickup defaultpen;
+undraw p;
+undraw q;
+ahlength:=4bp;
+z.a1-z0 = .3cm*unitvector(z.a-z0) rotated 90;
+z.a1-z.a2 = z0-z.a;
+z.b1-z0 = .3cm*unitvector(z.b-z0) rotated -90;
+z.b1-z.b2 = z0-z.b;
+z.ab = whatever[z.a1,z.a2] = whatever[z.b1,z.b2];
+z.a0-z.ab = .4cm*unitvector(z.a1-z.a2);
+z.b0-z.ab = .4cm*unitvector(z.b1-z.b2);
+drawdblarrow z.a1..z.a2;
+label.lrt(btex \tt ahlength etex, .9[z.a1,z.a2]);
+draw z.a1..z.a0 dashed evenly;
+drawdblarrow z.b1..z.b2;
+label.urt(btex \tt ahlength etex, .9[z.b1,z.b2]);
+draw z.b1..z.b0 dashed evenly;
+r = z.a0{(z.a2-z.a0) rotated 90}..{(z.b2-z.b0)rotated 90}z.b0;
+draw r;
+label.rt(btex \tt ahangle etex, point .5 of r);
+endfig;
+
+
+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;
+
+
+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;
+
+
+marksize=4pt;
+angle_radius=8pt;
+
+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;
+
+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;
+
+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;
+
+
+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;
+
+
+input boxes
+
+
+\beginfig(48);
+fill unitsquare xscaled 1.1in yscaled .7in withcolor .9white;
+boxit(currentpicture);
+dx = dy = .25in;
+clearit; drawboxed();
+forsuffixes $=n,c: makelabel.top(str $, $); endfor
+makelabel.bot("s",s);
+forsuffixes $=ne,e,se: makelabel.rt(str $, $); endfor
+forsuffixes $=nw,w,sw: makelabel.lft(str $, $); endfor
+pickup pencircle scaled .3bp;
+vardef larrow@#(expr a, da, s) =
+  drawdblarrow a..a+da; label@#(s,a+.5da); enddef;
+larrow.rt(n, (0,-dy), "dy");
+larrow.rt(s, (0,dy), "dy");
+larrow.top(e, (-dx,0), "dx");
+larrow.top(w, (dx,0), "dx");
+endfig;
+
+
+beginfig(49);
+boxjoin(a.se=b.sw; a.ne=b.nw);
+boxit.a(btex\strut$\cdots$ etex);    boxit.ni(btex\strut$n_i$ etex);
+boxit.di(btex\strut$d_i$ etex);      boxit.ni1(btex\strut$n_{i+1}$ etex);
+boxit.di1(btex\strut$d_{i+1}$ etex); boxit.aa(btex\strut$\cdots$ etex);
+boxit.nk(btex\strut$n_k$ etex);      boxit.dk(btex\strut$d_k$ etex);
+drawboxed(di,a,ni,ni1,di1,aa,nk,dk); label.lft("ndtable:", a.w);
+interim defaultdy:=7bp;
+boxjoin(a.sw=b.nw; a.se=b.ne);
+boxit.ba(); boxit.bb(); boxit.bc();
+boxit.bd(btex $\vdots$ etex); boxit.be(); boxit.bf();
+bd.dx=8bp; ba.ne=a.sw-(15bp,10bp);
+drawboxed(ba,bb,bc,bd,be,bf); label.lft("hashtab:",ba.w);
+vardef ndblock suffix $ =
+  boxjoin(a.sw=b.nw; a.se=b.ne);
+  forsuffixes $$=$1,$2,$3: boxit$$(); ($$dx,$$dy)=(5.5bp,4bp);
+  endfor; enddef;
+ndblock nda;  ndblock ndb;  ndblock ndc;
+nda1.c-bb.c = ndb1.c-nda3.c = (whatever,0);
+xpart ndb3.se = xpart ndc1.ne = xpart di.c;
+ndc1.c - be.c = (whatever,0);
+drawboxed(nda1,nda2,nda3, ndb1,ndb2,ndb3, ndc1,ndc2,ndc3);
+drawarrow bb.c -- nda1.w;
+drawarrow be.c -- ndc1.w;
+drawarrow nda3.c -- ndb1.w;
+drawarrow nda1.c{right}..{curl0}ni.c cutafter bpath ni;
+drawarrow nda2.c{right}..{curl0}di.c cutafter bpath di;
+drawarrow ndc1.c{right}..{curl0}ni1.c cutafter bpath ni1;
+drawarrow ndc2.c{right}..{curl0}di1.c cutafter bpath di1;
+drawarrow ndb1.c{right}..nk.c cutafter bpath nk;
+drawarrow ndb2.c{right}..dk.c cutafter bpath dk;
+x.ptr=xpart aa.c;   y.ptr=ypart ndc1.ne;
+drawarrow subpath (0,.7) of (z.ptr..{left}ndc3.c) dashed evenly;
+label.rt(btex \strut ndblock etex, z.ptr); endfig;
+
+
+\beginfig(50)
+interim circmargin := .07in;
+fill unitsquare xscaled 1.1in yscaled .7in withcolor .9white;
+circleit(currentpicture);
+dx = dy;
+clearit; drawboxed();
+forsuffixes $=n,c: makelabel.top(str $, $); endfor
+makelabel.bot("s",s);
+makelabel.rt("e", e);
+makelabel.lft("w", w);
+pickup pencircle scaled .3bp;
+vardef larrow@#(expr a, da, s) =
+  drawdblarrow a..a+da; label@#(s,a+.5da); enddef;
+larrow.rt(n, (0,-dy), "dy");
+larrow.rt(s, (0,dy), "dy");
+larrow.top(e, (-dx,0), "dx");
+larrow.top(w, (dx,0), "dx");
+endfig;
+
+
+
+vardef drawshadowed(text t) =
+  fixsize(t);
+  forsuffixes s=t:
+    fill bpath.s shifted (1pt,-1pt);
+    unfill bpath.s;
+    drawboxed(s);
+  endfor
+enddef;
+
+beginfig(51)
+circleit.a(btex Box 1 etex);
+circleit.b(btex Box 2 etex);
+b.n = a.s - (0,20pt);
+drawshadowed(a,b);
+drawarrow a.s -- b.n;
+endfig;
+
+
+vardef cuta(suffix a,b) expr p =
+  drawarrow p cutbefore bpath.a cutafter bpath.b;
+  point .5*length p of p
+enddef;
+
+vardef self@# expr p =
+  cuta(@#,@#) @#.c{curl0}..@#.c+p..{curl0}@#.c  enddef;
+
+beginfig(52);
+verbatimtex \def\stk#1#2{$\displaystyle{\matrix{#1\cr#2\cr}}$} etex
+circleit.aa(btex\strut Start etex); aa.dx=aa.dy;
+circleit.bb(btex \stk B{(a|b)^*a} etex);
+circleit.cc(btex \stk C{b^*} etex);
+circleit.dd(btex \stk D{(a|b)^*ab} etex);
+circleit.ee(btex\strut Stop etex); ee.dx=ee.dy;
+numeric hsep;
+bb.c-aa.c = dd.c-bb.c = ee.c-dd.c = (hsep,0);
+cc.c-bb.c = (0,.8hsep);
+xpart(ee.e - aa.w) = 3.8in;
+drawboxed(aa,bb,cc,dd,ee);
+label.ulft(btex$b$etex, cuta(aa,cc) aa.c{dir50}..cc.c);
+label.top(btex$b$etex, self.cc(0,30pt));
+label.rt(btex$a$etex, cuta(cc,bb) cc.c..bb.c);
+label.top(btex$a$etex, cuta(aa,bb) aa.c..bb.c);
+label.llft(btex$a$etex, self.bb(-20pt,-35pt));
+label.top(btex$b$etex, cuta(bb,dd) bb.c..dd.c);
+label.top(btex$b$etex, cuta(dd,ee) dd.c..ee.c);
+label.lrt(btex$a$etex, cuta(dd,bb) dd.c..{dir140}bb.c);
+label.bot(btex$a$etex, cuta(ee,bb) ee.c..tension1.3 ..{dir115}bb.c);
+label.urt(btex$b$etex, cuta(ee,cc) ee.c{(cc.c-ee.c)rotated-15}..cc.c);
+endfig;
+
+
+end
+\ No newline at end of file
diff --git a/Master/texmf-dist/doc/metapost/base/source/matmul.d b/Master/texmf-dist/doc/metapost/base/source/matmul.d
new file mode 100644
index 00000000000..c0e781d4a51
--- /dev/null
+++ b/Master/texmf-dist/doc/metapost/base/source/matmul.d
@@ -0,0 +1,21 @@
+20	.007861  ordinary MM: size, seconds
+30	.022051
+40	.050391
+60	.15922
+80	.4031
+120	1.53
+160	3.915
+240	18.55
+320	78.28
+480	279.24
+
+20	.006611  Strassen: size, seconds
+30	.020820
+40	.049219
+60	.163281
+80	.3975
+120	1.3125
+160	3.04
+240	9.95
+320	22.17
+480	72.60
+\ No newline at end of file
diff --git a/Master/texmf-dist/doc/metapost/base/source/mpgraph.bib b/Master/texmf-dist/doc/metapost/base/source/mpgraph.bib
new file mode 100644
index 00000000000..b95ad5af223
--- /dev/null
+++ b/Master/texmf-dist/doc/metapost/base/source/mpgraph.bib
@@ -0,0 +1,96 @@
+@string{jcompstatg = {Journal of Computational and Statistical Graphics}}
+
+@incollection{BenKer90,
+	author = "Jon L. Bentley and Brian W. Kernighan",
+	title = "Grap---A language for Typesetting Graphs",
+	booktitle = "Unix Research System Papers",
+	publisher = "{AT\&T} Bell Laboratories",
+	address = "Murray Hill, New Jersey",
+	edition = "Tenth",
+	volume = "{II}",
+	pages = "109--146",
+	year = 1990
+}
+@book{Cleve85,
+	author = "William S. Cleveland",
+	title = "The Elements of Graphing Data",
+	publisher = "Hobart Press",
+	address = "Summit, New Jersey",
+	year = 1985
+}
+@book{Cleve93,
+	author = "Cleveland, William S.",
+	title = "Visualizing Data",
+	publisher = "Hobart Press",
+	address = "Summit, New Jersey",
+	year= "to appear",
+}
+@book{Tufte83,
+	author = "Edward R. Tufte",
+	title = "Visual Display of Quantitative Information",
+	publisher = "Graphics Press",
+	address = "Box 430, Cheshire, Connecticut 06410",
+	year = 1983
+}
+@article{Cleve93a,
+	author = "Cleveland, William S.",
+	title = "A Model for Studying Display Methods of Statistical
+		Graphics (with discussion)",
+	journal = jcompstatg,
+	year = "to appear",
+	volume = 3
+}
+@book{Census92,
+	author = "U.S. Bureau of the Census",
+	title = "Statistical Abstracts of the United States: 1992",
+	edition = "112th",
+	address = "Washington, D.C.",
+	year = 1992
+}
+@book{LaTeXman,
+	author = "Leslie Lamport",
+	title = "{\LaTeX}: A Document Preparation System",
+	publisher = "Addison Wesley",
+	address = "Reading, Massachusetts",
+	year = 1986
+}
+@book{ad:red,
+	author = "Adobe Systems Inc.",
+	title = "{P}ost{S}cript Language Reference Manual",
+	publisher = "Addison Wesley",
+	address = "Reading, Massachusetts",
+	edition = "second",
+	year = 1990
+}
+
+@inproceedings{ho:mp4,
+	author = "John D. Hobby",
+	title = "Introduction to {MetaPost}",
+	booktitle = "Euro{\TeX} '92 Proceedings",
+	month = sep,
+	year = 1992,
+	pages = "21--36"
+}
+[An updated version appeared in the April 1999 Issue of "Eutupon",
+ the news lettter for the Greek TeX friends group.
+]
+
+@techreport{ho:mp3,
+	title = "A User's manual for {MetaPost}",
+	author = "John D. Hobby",
+	institution = "AT\&T Bell Laboratories",
+	address = "Murray Hill, New Jersey",
+	type = "Computing Science Technical Report",
+	number = "no.~162",
+	note = {Available as http://cm.bell-labs.com/cs/cstr/162.ps.gz},
+	month = apr,
+	year = 1992
+}
+@book{kn:d,
+	author = "Donald E. Knuth",
+	note = "Volume D of {\it Computers and Typesetting}",
+	title = "{\MF} the Program",
+	publisher = "Addison Wesley",
+	address = "Reading, Massachusetts",
+	year = 1986
+}
+\ No newline at end of file
diff --git a/Master/texmf-dist/doc/metapost/base/source/mpgraph.mp b/Master/texmf-dist/doc/metapost/base/source/mpgraph.mp
new file mode 100644
index 00000000000..1621f3a8605
--- /dev/null
+++ b/Master/texmf-dist/doc/metapost/base/source/mpgraph.mp
@@ -0,0 +1,129 @@
+input graph
+
+
+beginfig(1);
+draw begingraph(3in,2in);
+  gdraw "agepop91.d";
+  endgraph;
+endfig;
+
+
+beginfig(2);
+draw begingraph(3in,2in);
+  gdraw "agepop91.d" plot btex$\bullet$etex;
+  endgraph;
+endfig;
+
+
+beginfig(3);
+draw begingraph(3in,2in);
+  glabel.lft(btex \vbox{\hbox{Population} \hbox{in millions}} etex, OUT);
+  glabel.bot(btex Age in years etex, OUT);
+  gdraw "agepopm.d";
+  endgraph;
+endfig;
+
+
+beginfig(4);
+draw begingraph(3in,2in);
+ glabel.lft(btex \vbox{\hbox{Population} \hbox{in millions}} etex, OUT);
+ glabel.bot(btex Age in years etex, OUT);
+ setrange(origin, whatever,whatever);
+ gdraw "agepopm.d";
+ endgraph;
+endfig;
+
+
+beginfig(5);
+draw begingraph(2.3in,2in);
+ setcoords(log,log);
+ glabel.lft(btex Seconds etex,OUT);
+ glabel.bot(btex Matrix size etex,
+   OUT);
+ gdraw "matmul.d" dashed evenly;
+ glabel.ulft(btex Standard etex,8);
+ gdraw "matmul.d";
+ glabel.lrt(btex Strassen etex,7);
+ endgraph;
+endfig;
+
+
+beginfig(6);
+draw begingraph(6.5cm,4.5cm);
+ setrange(80,0, 90,whatever);
+ glabel.bot(btex Year etex, OUT);
+ glabel.lft(btex \vbox{\hbox{Emissions in} \hbox{thousands of}
+   \hbox{metric tons} \hbox{(heavy line)}}etex, OUT);
+ gdraw "lead.d" withpen pencircle scaled 1.5pt;
+ autogrid(,otick.lft);
+ setcoords(linear,linear);
+ setrange(80,0, 90,whatever);
+ glabel.rt(btex \vbox{\hbox{Micrograms} \hbox{per cubic}
+   \hbox{meter of air} \hbox{(thin line)}}etex, OUT);
+ gdraw "lead.d";
+ autogrid(otick.bot,otick.rt);
+ endgraph;
+endfig;
+
+
+input sarith
+
+beginfig(7);
+vardef newy(expr y) = (256/75)*y + mlog y enddef;
+draw begingraph(3in,2in);
+ glabel.lft(btex \vbox{\hbox{Population} \hbox{in millions}} etex, OUT);
+ path p;
+ gdata("timepop.d", $, augment.p($1, newy(Scvnum $2)); );
+ gdraw p;
+ for y=5,10,20,50,100,150,200,250:
+   grid.lft(format("%g",y), newy(y)) withcolor .85white;
+ endfor
+ autogrid(grid.bot,) withcolor .85white;
+ frame.llft;
+ endgraph;
+endfig;
+
+beginfig(8);
+defaultfont:="cmr7";
+draw begingraph(3in,2in);
+  glabel.lft(btex \vbox{\hbox{Life}\hbox{expectancy}} etex, OUT);
+  glabel.bot(btex Per capita G.N.P. (thousands of dollars) etex, OUT);
+  setcoords(log,linear);
+  gdata("countries.d", s,
+    glabel(s3, s1, s2);
+  )
+  endgraph;
+endfig;
+
+
+beginfig(9);
+draw begingraph(3in,2in);
+  glabel.lft(btex \vbox{\hbox{Quadrillions}\hbox{of BTU}} etex, OUT);
+  path p[];
+  numeric t;
+  gdata("energy.d", $,
+    t:=0; augment.p1($1,0);
+    for j=2 upto 5:
+       t:=t+scantokens $[j]; augment.p[j]($1,t);
+    endfor)
+  picture lab[];
+  lab2=btex coal etex; lab3=btex crude oil etex;
+  lab4=btex natural gas etex; lab5=btex hydroelectric etex;
+  for j=5 downto 2:
+    gfill p[j]--reverse p[j-1]--cycle withcolor .16j*white;
+    glabel.lft(image(unfill bbox lab[j]; draw lab[j]), .7+length p[j]);
+  endfor
+  endgraph;
+endfig;
+
+
+beginfig(10);
+draw format("%g",2+2);
+endfig;
+
+beginfig(11);
+draw format("%3g","6.022e23");
+endfig;
+
+
+end
+\ No newline at end of file
diff --git a/Master/texmf-dist/doc/metapost/base/source/mpgraph.tex b/Master/texmf-dist/doc/metapost/base/source/mpgraph.tex
new file mode 100644
index 00000000000..104b70bf917
--- /dev/null
+++ b/Master/texmf-dist/doc/metapost/base/source/mpgraph.tex
@@ -0,0 +1,1109 @@
+\documentclass{article} % article is NOT the original style
+\usepackage{makeidx}
+\usepackage{fancyvrb}
+\usepackage{ctabbing}
+\RecustomVerbatimEnvironment{verbatim}{BVerbatim}{baseline=c}
+\usepackage{epsf}
+\usepackage[textwidth=6in,textheight=8.75in]{geometry}
+
+\newcommand\descr[1]{{\langle\hbox{\rm#1}\rangle}}
+\newcommand\invisgap{\nobreak\hskip0pt\relax}
+\newcommand\tdescr[1]{$\langle$\invisgap{\rm#1}\invisgap$\rangle$}
+\newcommand\Ignore[1]{} % For fooling delatex so spell will work
+
+\newfont\psyvii{rpsyr at 7pt}
+\newcommand\regmark{$^{\hbox{\psyvii\char'322}}$}   % Registered trademark
+\newcommand\logofn{\global\font\logofn=logo8 \logofn}
+\newcommand\logo{\global\font\logo=logo10 \logo}
+\newcommand\logosl{\global\font\logosl=logosl10 \logosl}
+\newcommand\MF{{\ifdim \fontdimen6\font <9pt \def\logo{\logofn}\fi
+        \ifdim \fontdimen1\font >0pt \def\logo{\logosl}\fi
+        {\logo META}\-{\logo FONT}}}
+
+\newcommand\mathcenter[1]{\vcenter{\hbox{#1}}}
+
+\author{John D. Hobby}
+\title{Drawing Graphs with {MetaPost}}
+\date{}
+
+
+\newcommand\myabstract{%
+This paper describes a graph-drawing package that has been implemented
+as an extension to the MetaPost graphics language.  MetaPost has
+a powerful macro facility for implementing such extensions.  There are
+also some new language features that support the graph macros.
+Existing features for generating and manipulating pictures
+allow the user to do things that would be difficult to achieve
+in a stand-alone graph package.}
+
+\newcommand\mykeywords{%
+    typesetting; graphs; MetaPost}
+
+
+
+\begin{document}
+  \maketitle
+  \begin{abstract} \myabstract \end{abstract}
+  \ifx\keywords\undefined \else
+    \begin{keywords} \mykeywords \end{keywords}
+  \fi
+
+
+\section{Introduction}
+\label{intro}
+
+MetaPost is a batch-oriented graphics language based on Knuth's \MF\footnote{\MF\
+is a trademark of Addison Wesley Publishing Company.}, but with
+PostScript\footnote{PostScript is a registered trademark of Adobe Systems Inc.}
+output and numerous features for integrating text and graphics.
+The author has tried to make this paper as independent as possible of the
+user's manual~\cite{ho:mp3}, but fully appreciating all the material requires
+some knowledge of the MetaPost language.
+
+We concentrate on the mechanics of producing particular kinds of graphs
+because the question of what type of graph is best in a given situation
+is covered elsewhere; e.g., Cleveland~\cite{Cleve85,Cleve93,Cleve93a} and
+Tufte~\cite{Tufte83}.
+The goal is to provide at least the power of UNIX\footnote{UNIX is a registered
+trademark of UNIX System Laboratories, Inc.} {\it
+grap\/}~\cite{BenKer90}, but within the MetaPost language.
+Hence the package is implemented using MetaPost's powerful macro facility.
+
+The graph macros provide the following functionality:
+\begin{enumerate}
+\item Automatic scaling
+\item Automatic generation and labeling of tick marks or grid lines
+\item Multiple coordinate systems
+\item Linear and logarithmic scales
+\item Separate data files
+\item Ability to handle numbers outside the usual range
+\item Arbitrary plotting symbols
+\item Drawing, filling, and labeling commands for graphs
+\end{enumerate}
+In addition to these items, the user also has access to all the features
+described in the MetaPost user's manual~\cite{ho:mp3}.
+These include access to almost all the features of PostScript\regmark,
+ability to use and manipulate typeset text,
+ability to solve linear equations,
+and data types for points, curves, pictures, and coordinate transformations.
+
+Section~\ref{grmac} describes the graph macros from a user's perspective
+and presents several examples.  Sections \ref{nummac} and~\ref{formsec} discuss
+auxiliary packages for manipulating and typesetting numbers and Section~\ref{concl}
+gives some concluding remarks.  Appendix~\ref{summsec} summarizes the graph-drawing
+macros, and Appendix~\ref{nfeats} describes some recent additions to the MetaPost
+language that have not been presented elsewhere.
+
+
+\section{Using the Graph Macros}
+\label{grmac}
+
+A MetaPost input file that uses the graph macros should begin with
+$$ \hbox{\tt input graph} $$
+This reads a macro file {\tt graph.mp} and defines the graph-drawing commands
+explained below.  The rest of the file should be one or more instances of
+$$ \vbox{\hbox{\tt beginfig($\descr{figure number}$);}
+        \hbox{\tt $\descr{graphics commands}$ endfig;}}
+$$
+followed by {\tt end}.
+
+The following \tdescr{graphics commands} suffice to generate the graph in
+Figure~\ref{fig1} from the data file {\tt agepop91.d}:
+$$\begin{verbatim}
+draw begingraph(3in,2in);
+  gdraw "agepop91.d";
+  endgraph;
+\end{verbatim}
+$$
+(Each line of {\tt agepop91.d} gives an age followed the estimated number of
+Americans of that age in 1991 \cite{Census92}.)
+
+\begin{figure}[htp]
+$$ \epsfbox{mpgraph.1} $$
+\caption{A graph of the 1991 age distribution in the United States}
+\label{fig1}
+\end{figure}
+
+\subsection{Basic Graph-Drawing Commands}
+
+% begingraph, endgraph, gdraw
+
+All graphs should begin with
+$$ \hbox{\tt begingraph($\descr{width}$,$\descr{height}$);} $$
+and end with {\tt endgraph}.  This is syntactically a \tdescr{picture expression},
+so it should be preceded by {\tt draw} and followed by a semicolon as in the
+example.\footnote{See the User's Manual~\cite{ho:mp3} for explanations of {\tt draw}
+commands and syntactic elements like \tdescr{picture expression}.}
+The \tdescr{width} and \tdescr{height} give the dimensions of the
+graph itself without the axis labels.
+
+The command
+$$ {\tt gdraw}\ \descr{expression}\ \descr{option list} $$
+draws a graph line.  If the \tdescr{expression} is of type string, it names a data
+file; otherwise it is a path that gives the function to draw.  The
+\tdescr{option list} is zero or more drawing options
+$$ {\tt withpen} \descr{pen expression}
+   \mid {\tt withcolor} \descr{color expression}
+   \mid {\tt dashed} \descr{picture expression}
+$$
+that give the line width, color, or dash pattern as explained in the User's
+Manual~\cite{ho:mp3}.
+
+% plot <picture>
+
+In addition to the standard drawing options, the \tdescr{option list} in a
+{\tt gdraw} statement can contain
+$$ {\tt plot}\ \descr{picture expression} $$
+The \tdescr{picture expression} gives a plotting symbol to be drawn at each
+path knot.  The {\tt plot} option suppresses line drawing so that%
+\footnote{Troff users should replace {\tt btex \$\string\bullet\$ etex} with
+{\tt btex \string\(bu etex}.}
+\Ignore{\)}% Help delatex so spell will work
+$$ \hbox{\verb|gdraw "agepop91.d" plot btex $\bullet$ etex|} $$
+generates only bullets as shown in Figure~\ref{fig2}.
+(Following the {\tt plot} option with a {\tt withpen} option would
+cause the line to reappear superimposed on the plotting symbols.)
+
+\begin{figure}[htp]
+$$ \epsfbox{mpgraph.2} $$
+\caption{The 1991 age distribution plotted with bullets}
+\label{fig2}
+\end{figure}
+
+% glabel, gdotlabel, OUT
+
+The {\tt glabel} and {\tt gdotlabel} commands add labels to a graph.  The
+syntax for {\tt glabel} is
+$$ {\tt glabel.}\ \descr{label suffix}
+    \hbox{\tt ($\descr{string or picture expression}$, $\descr{location}$)}
+    \ \descr{option list}
+$$
+where \tdescr{location} identifies the location being labeled and
+\tdescr{label suffix} tells how the label is offset relative to that location.
+The {\tt gdotlabel} command is identical, except it marks the location with a
+dot.  A \tdescr{label suffix} is as in plain MetaPost:
+\tdescr{empty} centers the label on the location;
+{\tt lft}, {\tt rt}, {\tt top}, {\tt bot} offset the label horizontally or
+vertically; and {\tt ulft}, {\tt urt}, {\tt llft}, {\tt lrt} give diagonal
+offsets.  The \tdescr{location} can be a pair of graph coordinates, a knot
+number on the last {\tt gdraw} path, or the special location {\tt OUT}.
+Thus
+$$ \hbox{\verb|gdotlabel.top(btex $(50,0)$ etex, 50,0)|} $$
+would put a dot at graph coordinates {\tt(50,0)} and place the typeset text
+``$(50,0)$'' above it.  Alternatively,
+$$ \hbox{\verb|glabel.ulft("Knot3", 3)|} $$
+typesets the string {\tt "Knot3"} and places it above and to the left of
+Knot~3 of the last {\tt gdraw} path.  (The knot number 3 the path's ``time''
+parameter~\cite[Section 8.2]{ho:mp3}.)
+
+The \tdescr{location} {\tt OUT} places a label relative to the whole graph.
+For example, replacing ``{\tt gdraw "agepop91.d"}'' with
+$$\begin{verbatim}
+glabel.lft(btex \vbox{\hbox{Population} \hbox{in millions}} etex, OUT);
+glabel.bot(btex Age in years etex, OUT);
+gdraw "agepopm.d";
+\end{verbatim}
+$$
+in the input for Figure~\ref{fig1} generates Figure~\ref{fig3}.
+This improves the graph by adding axis labels and using a new data file
+{\tt agepopm.d} where the populations have been divided by one million to avoid
+large numbers.  We shall see later that simple transformations such as this can
+be achieved without generating new data files.
+
+\begin{figure}[htp]
+$$ \epsfbox{mpgraph.3} $$
+\caption{An improved version of the 1991 age distribution graph}
+\label{fig3}
+\end{figure}
+
+All flavors of \TeX\ can handle multi-line labels via the \verb|\hbox| within
+\verb|\vbox| arrangement used above, but \LaTeX\ users will find it more natural
+to use the {\tt tabular} environment~\cite{LaTeXman}.
+Troff user's can use nofill mode:
+$$\begin{verbatim}
+btex .nf
+Population
+in millions etex
+\end{verbatim}
+$$
+
+
+\subsection{Coordinate Systems}
+\label{coords}
+
+The graph macros automatically shift and rescale coordinates from data files,
+{\tt gdraw} paths, and {\tt glabel} locations to fit the graph.  Whether the
+range of $y$~coordinates is 0.64 to 4.6 or 640,000 to 4,600,000, they
+get scaled to fill about 88\% of the height specified in the {\tt begingraph}
+statement.  Of course line widths, labels, and plotting symbols are not
+rescaled.
+
+% setrange
+
+The {\tt setrange} command controls the shifting and rescaling process by
+specifying the minimum and maximum graph coordinates:
+$$ \hbox{\tt setrange($\descr{coordinates}$,\,$\descr{coordinates}$)} $$
+where
+\begin{ctabbing}
+$\tt \descr{coordinates} \rightarrow \descr{pair expression}$\\
+$\tt \qquad \;|\; \descr{numeric or string expression}\hbox{\tt ,}
+        \descr{numeric or string expression}$
+\end{ctabbing}
+The first \tdescr{coordinates} give $(x_{\rm min},y_{\rm min})$ and the second give
+$(x_{\rm max},y_{\rm max})$.  The lines $x=x_{\rm min}$, $x=x_{\rm max}$,
+$y=y_{\rm min}$, and $y=y_{\rm max}$ define the rectangular frame around the graph
+in Figures \ref{fig1}--\ref{fig3}.  For example, an adding a statement
+$$ \hbox{\tt setrange(origin, whatever,\,whatever)} $$
+to the input for Figure~\ref{fig3} yields Figure~\ref{fig4}.
+The first \tdescr{coordinates} are given by the predefined pair constant
+{\tt origin}, and the other coordinates are left unspecified.  Any unknown
+value would work as well, but {\tt whatever} is the standard MetaPost
+representation for an anonymous unknown value.
+
+\begin{figure}[htp]
+$$ \begin{verbatim}
+draw begingraph(3in,2in);
+ glabel.lft(btex \vbox{\hbox{Population} \hbox{in millions}} etex, OUT);
+ glabel.bot(btex Age in years etex, OUT);
+ setrange(origin, whatever,whatever);
+ gdraw "agepopm.d";
+ endgraph;
+\end{verbatim}
+\atop
+\epsfbox{mpgraph.4}
+$$
+\caption{The 1991 age distribution graph and the input that creates it.}
+\label{fig4}
+\end{figure}
+
+% strings for big coordinates
+
+Notice that the syntax for {\tt setrange} allows coordinate values to be given
+as strings.  Many commands in the graph package allow this option.  It is
+provided because the MetaPost language uses fixed point numbers that must be
+less than 32768.  This limitation is not as serious as it sounds because good
+graph design dictates that coordinate values should be ``of reasonable
+magnitude''~\cite{Cleve85,Tufte83}.  If you really want $x$ and $y$
+to range from 0 to 1,000,000,
+$$ \hbox{\tt setrange(origin, "1e6",\,"1e6")} $$
+does the job.  Any fixed or floating point representation is acceptable
+as long as the exponent is introduced by the letter ``{\tt e}''.
+
+% setcoords
+
+Coordinate systems need not be linear.  The {\tt setcoords} command allows
+either or both axes to have logarithmic spacing:
+\begin{ctabbing}
+$\tt \descr{coordinate setting} \rightarrow setcoords\hbox{\tt (}
+        \descr{coordinate type}\hbox{\tt ,}\,\descr{coordinate type}\hbox{\tt )}$\\
+$\tt \descr{coordinate type} \rightarrow
+        log \;|\; linear \;|\; \hbox{\tt -}log \;|\; \hbox{\tt -}linear$
+\end{ctabbing}
+A negative \tdescr{coordinate type} makes $x$ (or $y$) run backwards so it is
+largest on the left side (or bottom) of the graph.
+
+Figure~\ref{fig5} graphs execution times for two matrix multiplication algorithms
+using
+$$ \hbox{\tt setcoords(log,log)} $$
+to specify logarithmic spacing on both axes.  The data file {\tt matmul.d} gives
+timings for both algorithms:\\
+\hbox to\hsize{\footnotesize\hfil$
+\begin{verbatim}
+20      .007861  standard MM: size, seconds
+30      .022051
+40      .050391
+60      .15922
+80      .4031
+120     1.53
+160     3.915
+240     18.55
+320     78.28
+480     279.24
+
+20      .006611  Strassen: size, seconds
+30      .020820
+40      .049219
+60      .163281
+80      .3975
+120     1.3125
+160     3.04
+240     9.95
+320     22.17
+480     72.60
+\end{verbatim}
+\hfil$}
+A blank line in a data file ends a data set.  Subsequent {\tt gdraw} commands
+access additional data sets by just naming the same data file again.
+Since each line gives one $x$~coordinate and one $y$~coordinate, commentary
+material after the second data field on a line is ignored.
+
+\begin{figure}[htp]
+$$ \mathcenter{\epsfbox{mpgraph.5}}
+ \quad
+\begin{BVerbatim}[baseline=c]
+draw begingraph(2.3in,2in);
+ setcoords(log,log);
+ glabel.lft(btex Seconds etex,OUT);
+ glabel.bot(btex Matrix size etex,
+   OUT);
+ gdraw "matmul.d" dashed evenly;
+ glabel.ulft(btex Standard etex,8);
+ gdraw "matmul.d";
+ glabel.lrt(btex Strassen etex,7);
+ endgraph;
+\end{BVerbatim}
+$$
+\caption{Timings for two matrix multiplication algorithms with the corresponding
+        MetaPost input.}
+\label{fig5}
+\end{figure}
+
+Placing a {\tt setcoords} command between two {\tt gdraw} commands graphs two
+functions in different coordinate systems as shown in Figure~\ref{fig6}.
+Whenever you give a {\tt setcoords} command, the interpreter examines what has
+been drawn, selects appropriate $x$ and $y$ ranges, and scales everything to
+fit.  Everything drawn afterward is in  a new coordinate system that need not
+have anything in common with the old coordinates unless {\tt setrange} commands
+enforce similar coordinate ranges.  For instance, the two {\tt setrange}
+commands force both coordinate systems to have $x$ ranging from 80 to~90 and
+$y$~starting at 0.
+
+\begin{figure}[htp]
+$$ \begin{verbatim}
+draw begingraph(6.5cm,4.5cm);
+ setrange(80,0, 90,whatever);
+ glabel.bot(btex Year etex, OUT);
+ glabel.lft(btex \vbox{\hbox{Emissions in} \hbox{thousands of}
+   \hbox{metric tons} \hbox{(heavy line)}}etex, OUT);
+ gdraw "lead.d" withpen pencircle scaled 1.5pt;
+ autogrid(,otick.lft);
+ setcoords(linear,linear);
+ setrange(80,0, 90,whatever);
+ glabel.rt(btex \vbox{\hbox{Micrograms} \hbox{per cubic}
+   \hbox{meter of air} \hbox{(thin line)}}etex, OUT);
+ gdraw "lead.d";
+ autogrid(otick.bot,otick.rt);
+ endgraph;
+\end{verbatim}
+  \atop
+\mathcenter{\epsfbox{mpgraph.6}}
+$$
+\caption{Annual lead emissions and average level at atmospheric monitoring
+        stations in the United States.  The MetaPost input is shown above
+        the graph.}
+\label{fig6}
+\end{figure}
+
+% autogrid
+
+When you use multiple coordinate systems, you have to specify where the axis
+labels go.  The default is to put tick marks on the bottom and the left side of
+the frame using the coordinate system in effect when the {\tt endgraph} command
+is interpreted.  Figure~\ref{fig6} uses the
+$$ \hbox{\tt autogrid(,otick.lft)} $$
+to label the left side of the graph with the $y$~coordinates in effect before
+the {\tt setcoords} command.  This suppresses the default axis labels, so another
+{\tt autogrid} command is needed to label the bottom and right sides of the
+graph using the new coordinate system.  The general syntax is
+$$ \hbox{$\tt autogrid\hbox{\tt (}\descr{axis label command}\hbox{\tt ,}\,
+        \descr{axis label command}\hbox{\tt )}\ \descr{option list}$}
+$$
+where
+\begin{ctabbing}
+$\tt \descr{axis label command} \rightarrow \descr{empty}
+        \;|\; \descr{grid or tick}\, \descr{label suffix}$\\
+$\tt \descr{grid or tick} \rightarrow grid \;|\; itick \;|\; otick$
+\end{ctabbing}
+The \tdescr{label suffix} should be {\tt lft}, {\tt rt}, {\tt top},
+or {\tt bot}.
+
+The first argument to {\tt autogrid} tells how to label the $x$~axis and the
+second argument does the same for~$y$.  An \tdescr{empty} argument suppresses
+labeling for that axis.  Otherwise, the \tdescr{label suffix} tells which side
+of the graph gets the numeric label.  Be careful to use {\tt bot} or {\tt top}
+for the $x$~axis and {\tt lft} or {\tt rt} for the $y$~axis.  Use {\tt otick}
+for outward tick marks, {\tt itick} for inward tick marks, and {\tt grid} for
+grid lines.  The \tdescr{option list} tells how to draw the tick marks or grid
+lines.  Grid lines tend to be a little overpowering, so it is a good idea to
+give a {\tt withcolor} option to make them light gray so they do not make the
+graph too busy.
+
+
+\subsection{Explicit Grids and Framing}
+
+% otick, itick, grid, (format)
+
+In case {\tt autogrid} is not flexible enough, axis label commands generate
+grid lines or tick marks one at a time.  The syntax is
+$$ \descr{grid or tick}\hbox{\tt .}\descr{label suffix}
+        \hbox{\tt ($\descr{label format}$,\,$\descr{numeric or string expression}$)}
+        \ \descr{option list}
+$$
+where \tdescr{grid or tick} and \tdescr{label suffix} are as in {\tt autogrid},
+and \tdescr{label format} is either a format string like \verb|"%g"| or a
+picture containing the typeset numeric label.
+
+The axis label commands use a macro
+$$ \hbox{\tt format($
+        \descr{format string}$,\,$\descr{numeric or string expression}$)}
+$$
+to typeset numeric labels.  Full details appear in Section~\ref{formsec},
+but when the \tdescr{format string} is \verb|"%g"|, it uses decimal notation
+unless the number is large enough or small enough to require scientific notation.
+
+The example in Figure~\ref{fig7} invokes
+$$ \hbox{\verb|format("%g",y)|} $$
+explicitly so that grid lines can be placed at transformed coordinates.
+It defines the transformation ${\tt newy}(y)=y/75+\ln y$ and shows that
+this function increases almost linearly.\footnote{The manual~\cite{ho:mp3}
+explains how {\tt vardef} defines functions and {\tt mlog} computes logarithms.}
+This is a little like using logarithmic $y$-coordinates, except that $y$ is
+mapped to $y/75+\ln y$ instead of just $\ln y$.
+
+\begin{figure}[htp]
+$$ \begin{verbatim}
+vardef newy(expr y) = (256/75)*y + mlog y enddef;
+draw begingraph(3in,2in);
+ glabel.lft(btex \vbox{\hbox{Population} \hbox{in millions}} etex, OUT);
+ gdraw "ttimepop.d";
+ for y=5,10,20,50,100,150,200,250:
+   grid.lft(format("%g",y), newy(y)) withcolor .85white;
+ endfor
+ autogrid(grid.bot,) withcolor .85white;
+ frame.llft;
+ endgraph;
+\end{verbatim}
+   \atop
+   \epsfbox{mpgraph.7}
+$$
+\caption{Population of the United States in millions versus time with the
+        population re-expressed as $p/75+\ln p$.  The MetaPost input shown
+        above the graph assumes a data file {\tt ttimepop.d} that gives
+        (year, $p/75+\ln p$) pairs.}
+\label{fig7}
+\end{figure}
+
+% frame
+
+Figure~\ref{fig7} uses the command
+$$ \hbox{\tt frame.} \descr{label suffix}\ \descr{option list} $$
+to draw a special frame around the graph.  In this case the \tdescr{label suffix}
+is {\tt llft} to draw just the bottom and left sides of the frame.  Suffixes
+{\tt lrt}, {\tt ulft}, and {\tt urt} draw other combinations of two sides;
+suffixes {\tt lft}, {\tt rt}, {\tt top}, {\tt bot} draw one side, and \tdescr{empty}
+draws the whole frame.  For example
+$$ \hbox{\verb|frame dashed evenly|} $$
+draws all four sides with dashed lines.  The default four-sided frame is drawn
+only when there is no explicit {\tt frame} command.
+
+% auto, (sarith.mp)
+
+To label an axis as {\tt autogrid} does but with the labels transformed
+somehow, use
+$$ \hbox{{\tt auto.x}\quad or\quad {\tt auto.y}} $$
+for positioning tick marks or grid lines.  These macros produce comma-separated
+lists for use in {\tt for} loops.  Any $x$ or $y$ values in these lists that
+cannot be represented accurately within MetaPost's fixed-point number system
+are given as strings.  A standard macro package that is loaded via
+$$ \hbox{\tt input sarith}  $$
+defines arithmetic operators that work on numbers or strings.  Binary operators
+{\tt Sadd}, {\tt Ssub}, {\tt Smul}, and {\tt Sdiv} do addition, subtraction
+multiplication, and division.
+
+One possible application is rescaling data.
+Figure~\ref{fig4} used a special data file {\tt agepopm.d} that had $y$~values
+divided by one million.  This could be avoided by replacing
+``{\tt gdraw "agepopm.d"}'' by
+$$\begin{verbatim}
+gdraw "agepop91.d";
+for u=auto.y: otick.lft(format("%g",u Sdiv "1e6"), u); endfor
+autogrid(otick.bot,)
+\end{verbatim}
+$$
+
+
+\subsection{Processing Data Files}
+\label{dfilesec}
+
+% gdata
+
+The most general tool for processing data files is the {\tt gdata} command:
+$$ \hbox{\tt gdata(} \descr{string expression} \hbox{\tt,}\, \descr{variable}
+        \hbox{\tt,}\, \descr{commands} \hbox{\tt )}
+$$
+It takes a file name, a variable~$v$, and a list of commands to be executed for
+each line of the data file.  The commands are executed with {\tt i} set to the
+input line number and strings $v${\tt 1}, $v${\tt 2}, $v${\tt 3}, \ldots\ set
+to the input fields on the current line.  A null string marks the end of the
+$v$ array.
+
+Using a {\tt glabel} command inside of {\tt gdata} generates a scatter plot
+as shown in Figure~\ref{fig8}.  The data file {\tt countries.d} begins
+$$\begin{verbatim}
+20.910 75.7 US
+ 1.831 66.7 Alg
+\end{verbatim}
+$$
+where the last field in each line gives the label to be plotted.  Setting
+{\tt defaultfont} in the first line of input selects a small font for these
+labels.  Without these labels, no {\tt gdata} command would be needed.
+Replacing the {\tt gdata} command with
+$$ \hbox{\verb|gdraw "countries.d" plot btex$\circ$etex|} $$
+would change the abbreviated country names to open circles.
+
+\begin{figure}[htp]
+$$\begin{verbatim}
+defaultfont:="cmr7";
+draw begingraph(3in,2in);
+  glabel.lft(btex \vbox{\hbox{Life}\hbox{expectancy}} etex, OUT);
+  glabel.bot(btex Per capita G.N.P. (thousands of dollars) etex, OUT);
+  setcoords(log,linear);
+  gdata("countries.d", s,
+    glabel(s3, s1, s2);
+  )
+  endgraph;
+\end{verbatim}
+ \atop
+ \epsfbox{mpgraph.8}
+$$
+\caption{A scatter plot and the commands that generated it}
+\label{fig8}
+\end{figure}
+
+Both {\tt gdraw} and {\tt gdata} ignore an optional initial `\%' on each input
+line, parse data fields separated by white space, and stop if they encounter an
+input line with no data fields.  Leading percent signs make graph data
+look like MetaPost comments so that numeric data can be placed at the beginning
+of a MetaPost input file.
+
+% augment
+
+It is often useful to construct one or more paths when reading a data file
+with {\tt gdata}.  The {\tt augment} command is designed for this:
+$$ \hbox{\tt augment.} \descr{path variable} \hbox{\tt(}\descr{coordinates}\hbox{\tt)}
+$$
+If the path variable does not have a known value, it becomes a path of length
+zero at the given coordinates; otherwise a line segment to the given coordinates
+is appended to the path.  The \tdescr{coordinates} may be a pair expression or
+any combination of strings and numerics as explained at the beginning of
+Section~\ref{coords}.
+
+If a file {\tt timepop.d} gives $t$,~$p$ pairs, {\tt augment} can be used like
+this to graph {\tt newy(}$p${\tt)} versus~$t$:
+$$\begin{verbatim}
+path p;
+gdata("timepop.d", s, augment.p(s1, newy(scantokens s2)); );
+gdraw p;
+\end{verbatim}
+$$
+(MetaPost's {\tt scantokens} primitive interprets a string as if it were the
+contents of an input file.  This finds the numeric value of data field
+{\tt s2}.)
+
+% gfill (energy.d)
+
+Figure~\ref{fig9} shows how to use {\tt augment} to read multiple column data
+and make multiple paths.  Paths {\tt p2}, {\tt p3}, {\tt p4}, {\tt p5} give
+cumulative totals for columns 2 through 5 and pictures {\tt lab2} through
+{\tt lab5} give corresponding labels.  The expression
+$$ \hbox{\verb|image(unfill bbox lab[j]; draw lab[j])|} $$
+executes the given drawing commands and returns the resulting picture:
+``{\tt unfill bbox lab[j]}'' puts down a white background and ``{\tt draw
+lab[j]}'' puts the label on the background.
+The {\tt gfill} command is just like {\tt gdraw}, except it takes a cyclic
+path and fills the interior with a solid color.  The color is black unless
+a {\tt withcolor} clause specifies another color.
+See the manual~\cite{ho:mp3} for
+explanations of {\tt for} loops, arrays, colors, and path construction
+operators like \verb|--|, {\tt cycle}, and {\tt reverse}.
+
+\begin{figure}[htp]
+$$\begin{verbatim}
+draw begingraph(3in,2in);
+  glabel.lft(btex \vbox{\hbox{Quadrillions}\hbox{of BTU}} etex, OUT);
+  path p[];
+  numeric t;
+  gdata("energy.d", $,
+    t:=0; augment.p1($1,0);
+    for j=2 upto 5:
+       t:=t+scantokens $[j]; augment.p[j]($1,t);
+    endfor)
+  picture lab[];
+  lab2=btex coal etex; lab3=btex crude oil etex;
+  lab4=btex natural gas etex; lab5=btex hydroelectric etex;
+  for j=5 downto 2:
+    gfill p[j]--reverse p[j-1]--cycle withcolor .16j*white;
+    glabel.lft(image(unfill bbox lab[j]; draw lab[j]), .7+length p[j]);
+  endfor
+  endgraph;
+\end{verbatim}
+ \atop
+ \epsfbox{mpgraph.9}
+$$
+\caption{A graph of U.S. annual energy production
+        and the commands that generated it}
+\label{fig9}
+\end{figure}
+
+
+\section{Manipulating Big Numbers}
+\label{nummac}
+
+MetaPost inherits a fixed-point number system from Knuth's \MF~\cite{kn:d}.
+Numbers are expressed in multiples of $2^{-16}$ and they must have absolute
+value less than 32768.  Knuth chose this system because it is perfectly adequate
+for font design, and it guaranteed to give identical results on all types of
+computers.  Fixed-point numbers are seldom a problem in MetaPost because all
+computations are based on coordinates that are limited by the size the paper on
+which the output is to be printed.  This does not hold for the input data in a
+graph-drawing application.  Although graphs look best when coordinate axes are
+labeled with numbers of reasonable magnitude, the strict limits of fixed-point
+arithmetic would be inconvenient.
+
+% Sadd, Ssub, Smul, Sdiv
+
+A simple way to handle large numbers is to include the line
+$$ \hbox{\tt input sarith} $$
+and then use binary operators {\tt Sadd}, {\tt Ssub}, {\tt Smul}, and {\tt Sdiv}
+in place of \verb|+|, \verb|-|, \verb|*|, and \verb|/|.  These operators are
+inefficient but very flexible.  They accept numbers or strings and return
+strings in exponential notation with the exponent marked by ``{\tt e}'';
+e.g., \verb|"6.7e-11"| means $6.7\times10^{-11}$.
+
+% Sabs, Sleq, Sneq
+
+The unary operator\footnote{The argument to a unary operator need not be
+parenthesized unless it is an expression involving binary operators.}
+$$ {\tt Sabs}\ \descr{string} $$
+finds a string the represents the absolute value.  Binary operators {\tt Sleq}
+and {\tt Sneq} perform numeric comparisons on strings and return boolean
+results.
+
+% Scvnum
+
+The operation
+$$ {\tt Scvnum}\ \descr{string} $$
+finds the numeric value for a string if this can be done without overflowing
+MetaPost's fixed-point number system.  If the string does not contain
+``{\tt e}'', it is much more efficient to use the primitive operation
+$$ {\tt scantokens}\ \descr{string} $$
+
+% Mten
+
+The above operators are based on a low-level package that manipulates numbers
+in ``{\tt Mlog} form.''  A number $x$ in {\tt Mlog} form represents
+$$ \mu^{2^{16}x}, \quad {\rm where\ } \mu=-e^{2^{-24}}. $$
+Any value between $1.61\times10^{-28}$ and $3.88\times10^{55}$ can be
+represented this way.  (There is a constant {\tt Mten} such that $k*{\tt Mten}$
+represents $10^k$ for any integer~$k$ in the interval $[-29,55]$.)
+
+% Mreadpath, Gpaths
+
+The main reason for mentioning {\tt Mlog} form is that it allows graph data
+to be manipulated as a MetaPost path.  The function
+$$ \hbox{\tt Mreadpath($\descr{file name}$)} $$
+reads a data file and returns a path where all the coordinates are in
+{\tt Mlog} form.  An internal variable {\tt Gpaths} determines whether
+{\tt gdraw} and {\tt gfill} expect paths to be given in {\tt Mlog} form.
+For example, this graphs the data in {\tt agepop91.d} with $y$ coordinates
+divided by one million:
+$$\begin{verbatim}
+interim Gpaths:=log;
+gdraw Mreadpath("agepop91.d") shifted (0,-6*Mten);
+\end{verbatim}
+$$
+
+
+\section{Typesetting Numbers}
+\label{formsec}
+
+% format
+
+The graph package needs to compute axis labels and then typeset them.
+The macro
+$$ \hbox{\tt format($\descr{string expression}$,\,%
+        $\descr{numeric or string expression}$)} $$
+does this.  You must first {\tt input graph} or {\tt input format} to load the
+macro file.  The macro takes a format string and a number to typeset and returns
+a picture containing the typeset result.  Thus
+$$ \hbox{\verb|format("%g",2+2)|}\quad {\rm yields}\quad \epsfbox{mpgraph.10} $$
+and
+$$ \hbox{\verb|format("%3g","6.022e23")|}
+        \quad {\rm yields}\quad \epsfbox{mpgraph.11}
+$$
+
+A format string consists of
+\begin{itemize}
+\item an optional initial string not containing a percent sign,
+\item a percent sign,
+\item an optional numeric precision $p$,
+\item one of the conversion letters {\tt e}, {\tt f}, {\tt g}, {\tt G},
+\item an optional final string $\beta$.
+\end{itemize}
+The initial and final strings are typeset in the default font (usually
+{\tt cmr10}), and the typeset number is placed between them.  For the {\tt e}
+and {\tt g} formats, the precision~$p$ is the number of significant digits
+allowed after rounding; for {\tt f} and {\tt G}, the number is rounded to the
+nearest multiple of $10^{-p}$.  If the precision is not specified, the default
+is $p=3$.  The {\tt e} format always uses scientific
+notation and the {\tt f} format uses ordinary decimal notation but reverts to
+scientific notation if the number is at least 10000.  The {\tt g} and {\tt G}
+formats also revert to scientific notation for non-zero numbers of magnitude
+less than 0.001.
+
+% init_numbers
+
+The {\tt format} macro needs a set of templates to determine what font to use,
+how to position the exponent, etc.  The templates are normally initialized
+automatically, but it is possible to set them explicitly by passing five picture
+expressions to {\tt init\_numbers}.  For instance, the default definition for
+\TeX\ users is
+$$\begin{verbatim}
+init_numbers(btex$-$etex, btex$1$etex, btex${\times}10$etex,
+    btex${}^-$etex, btex${}^2$etex)
+\end{verbatim}
+$$
+The first argument tells how to typeset a leading minus sign;
+the second argument is an example of a 1-digit mantissa;
+third comes whatever to put after the mantissa in scientific notation;
+next come a leading minus sign for the exponent and a sample 1-digit exponent.
+
+% Fe_plus, Fe_base
+
+Picture variable \verb|Fe_plus| gives a leading plus sign for positive numbers,
+and \verb|Fe_base| gives whatever should precede the exponent when typesetting
+a power of ten.  Calling \verb|init_numbers| initializes \verb|Fe_plus| to an
+empty picture and constructs \verb|Fe_base| from its second and third arguments.
+
+
+
+\section{Conclusion}
+\label{concl}
+
+The graph package makes it convenient to generate graphs from within the MetaPost
+language.  The primary benefits are the power of the MetaPost language and its
+ability to interact with \TeX\ or troff for typesetting labels.  Typeset labels
+can be stored in picture variables and manipulated in various ways such measuring
+the bounding box and providing a white background.
+
+We have seen how to generate shaded regions and control line width, color, and
+styles of dashed lines.  Numerous other variations are possible.
+The full MetaPost language~\cite{ho:mp3} provides many other potentially useful
+features.  It also has enough computing power to be useful for generating and
+processing data.
+
+
+
+\appendix
+\section{Summary of the Graph Package}
+\label{summsec}
+
+% Not described elsewhere: gdrawarrow, gdrawdblarrow, Gmarks, Gminlog, Autoform
+
+In the following descriptions, italic letters such as $w$ and $h$ denote
+expression parameters and words in angle brackets denote other syntactic
+elements.  Unless specified otherwise, expression parameters can be either
+numerics or strings.  An \tdescr{option list} is a list of drawing options such
+as {\tt withcolor .5white} or {\tt dashed evenly};
+a \tdescr{label suffix} is one of {\tt lft}, {\tt rt}, {\tt top}, {\tt bot},
+{\tt ulft}, {\tt urt}, {\tt llft}, {\tt lrt}.
+
+\subsection{Graph Administration}
+
+\begin{description}
+\item[{\tt begingraph($w$,$h$)}]
+        Begin a new graph with the frame width and height given by numeric
+        parameters $w$ and $h$.
+\item[{\tt endgraph}]
+        End a graph and return the resulting picture.
+\item[{\tt setcoords($t_x$,\,$t_y$)}]
+        Set up a new coordinate system as specified by numeric flags $t_x$,
+        $t_y$.  Flag values are $\pm{\tt linear}$ and $\pm{\tt log}$.
+\item[{\tt setrange($\descr{coordinates}$,\,$\descr{coordinates}$)}]
+        Set the lower and upper limits for the current coordinate system.
+        Each \tdescr{coordinates} can be a single pair expression or two
+        numeric or string expressions.
+\end{description}
+
+\subsection{Drawing and Labeling}
+
+All of the drawing and labeling commands can be followed by an
+\tdescr{option list}.  In addition to the usual MetaPost drawing options, the
+list can contain a {\tt plot} \tdescr{picture} clause to plot a specified
+picture at each data point.
+
+The drawing and labeling commands are closely related to a set of similarly
+named commands in plain MetaPost.  The {\tt gdrawarrow} and {\tt gdrawdblarrow}
+commands are included to maintain this relationship.
+
+\begin{description}
+\item[{\tt gdotlabel.$\descr{label suffix}$($p$,\,$\descr{location}$)}]
+        This is like {\tt glabel} except it also puts a dot at the location
+        being labeled.
+\item[{\tt gdraw $p$}]
+        Draw path $p$, or if $p$ is a string, read coordinate pairs from
+        file~$p$ and draw a polygonal line through them.
+\item[{\tt gdrawarrow $p$}]
+        This is like {\tt dgraw} $p$ except it adds an arrowhead at the end of
+        the path.
+\item[{\tt gdrawdblarrow $p$}]
+        This is like {\tt dgraw} $p$ except it adds an arrowheads at each end of
+        the path.
+\item[{\tt gfill $p$}]
+        Fill cyclic path~$p$ or read coordinates from the file named by
+        string~$p$ and fill the resulting polygonal outline.
+\item[{\tt glabel.$\descr{label suffix}$($p$,\,$\descr{location}$)}]
+        If $p$ is not a picture, it should be a string.  Typeset it using
+        {\tt defaultfont}, then place it near the given location and offset as
+        specified by the \tdescr{label suffix}.  The \tdescr{location} can be
+        $x$~and $y$ coordinates, a pair giving $x$~and $y$, a numerc value giving
+        a time on the last path drawn, or {\tt OUT} to label the outside of the
+        graph.
+\end{description}
+
+\subsection{Grids, Tick Marks, and Framing}
+
+\begin{description}
+\item[{\tt auto.}$\descr{{\tt x} or {\tt y}}$]
+        Generate default $x$ or $y$ coordinates for tick marks.
+\item[{\tt autogrid($\descr{axis label command}$,\,$\descr{axis label command}$)}]
+        Draw default axis labels using the specified commands for the $x$ and
+        $y$ axes.  An \tdescr{axis label command} may be \tdescr{empty} or it
+        may be {\tt itick}, {\tt otick}, or {\tt grid} followed by a
+        \tdescr{label suffix}.
+\item[{\tt frame.}$\descr{label suffix}$\ $\descr{option list}$]
+        Draw a frame around the graph, or draw the part of the frame specified
+        by the \tdescr{label suffix}.
+\item[{\tt grid.}$\descr{label suffix}$($f$,$z$)]
+        Draw a grid line across the graph from the side specified by the
+        \tdescr{label suffix}, and label it there using format string~$f$ and
+        coordinate value~$z$.  If $f$ is a picture, it gives the label.
+\item[{\tt itick.}$\descr{label suffix}$($f$,$z$)]
+        This is like {\tt grid} except it draws an inward tick mark.
+\item[{\tt otick.}$\descr{label suffix}$($f$,$z$)]
+        This is like {\tt grid} except it draws an outward tick mark.
+\end{description}
+
+\subsection{Miscellaneous Commands}
+
+\begin{description}
+\item[{\tt augment.$\descr{variable}$($\descr{coordinates}$)}]
+        Append \tdescr{coordinates} to the path stored in \tdescr{variable}.
+\item[{\tt format($f$,\,$x$)}]
+        Typeset $x$ according to format string~$f$ and return the resulting
+        picture.
+\item[{\tt gdata($f$,\,$\descr{variable}$,\,$\descr{commands}$)}]
+        Read the file named by string~$f$ and execute \tdescr{commands} for each
+        input line using the \tdescr{variable} as an array to store data fields.
+\item[{\tt init\_numbers($s$,\,$m$,\,$x$,\,$t$,\,$e$)}]
+        Provide five pictures as templates for future {\tt format} operations:
+        $s$ is a leading minus; $m$ is a sample mantissa; $x$ follows the
+        mantissa; $t$ is a leading minus for the exponent~$e$.
+\item[{\tt Mreadpath($f$)}]
+        Read a path for the data file named by string~$f$ and return it in
+        ``{\tt Mlog} form''.
+\end{description}
+
+\subsection{Arithmetic on Numeric Strings}
+
+It is necessary to {\tt input sarith} before using the following macros:
+\begin{description}
+\item[{\tt Sabs $x$}]
+        Compute $|x|$ and return a numeric string.
+\item[{\tt $x$ Sadd $y$}]
+        Compute $x+y$ and return a numeric string.
+\item[{\tt Scvnum $x$}]
+        Return the numeric value for string $x$.
+\item[{\tt $x$ Sdiv $y$}]
+        Compute $x/y$ and return a numeric string.
+\item[{\tt $x$ Sleq $y$}]
+        Return the boolean result of the comparison $x\leq y$.
+\item[{\tt $x$ Smul $y$}]
+        Compute $x*y$ and return a numeric string.
+\item[{\tt $x$ Sneq $y$}]
+        Return the boolean result of the comparison $x\neq y$.
+\item[{\tt $x$ Ssub $y$}]
+        Compute $x-y$ and return a numeric string.
+\end{description}
+
+\subsection{Internal Variables and Constants}
+
+\begin{description}
+\item[{\tt Autoform}]
+        Format string used by {\tt autogrid}.  Default: \verb|"%g"|.
+\item[{\tt Fe\_base}]
+        What precedes the exponent when typesetting a power of ten.
+\item[{\tt Fe\_plus}]
+        Picture of the leading plus sign for positive exponents.
+\item[{\tt Gmarks}]
+        Minimum number of tick marks per axis for {\tt auto} and {\tt autogrid}.
+        Default: 4.
+\item[{\tt Gminlog}]
+        Minimum largest/smallest ratio for logarithmic spacing with {\tt auto}
+        and {\tt autogrid}.  Default: 3.0.
+\item[{\tt Gpaths}]
+        Code for coordinates used in {\tt gdraw} and {\tt gfill} paths:
+        {\tt linear} for standard form, {log} for ``{\tt Mlog} form''.
+\item[{\tt Mten}]
+        The ``{\tt Mlog} form'' for 10.0
+\end{description}
+
+
+
+\section{New Language Features}
+\label{nfeats}
+
+The {\tt graph.mp} macros and the arithmetic routines in {\tt marith.mp}
+and {\tt sarith.mp} use various language features that were introduced
+in Version 0.60 of the MetaPost language.  We summarize these features here
+because they are not covered in existing documentation \cite{ho:mp3,ho:mp4}.
+Also new is the built-in macro
+$$ \hbox{\tt image($\descr{drawing commands}$)} $$
+that was used in Section~\ref{dfilesec} to find the picture produced by a
+sequence of drawing commands.
+
+\subsection{Reading and Writing Files}
+
+A new operator
+$$ {\tt readfrom}\ \descr{file name} $$
+returns a string giving the next line of input from the named file.  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} 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.
+
+The opposite of {\tt readfrom} is the command
+$$ {\tt write}\ \descr{string expression}\ {\tt to} \descr{file name} $$
+This writes a line of text to the specified output file, opening the file
+first if necessary.  All such files are closed automatically when the
+program terminates.  They can also be closed explicitly by using {\tt 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.
+
+\subsection{Extracting Information from Pictures}
+
+MetaPost pictures are composed of stroked lines, filled outlines, pieces
+of typeset text, clipping paths, and {\tt 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}
+$$
+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.
+
+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} $$
+tests whether the expression is a known picture whose first component is a
+stroked line.  Similarly, the {\tt filled} and {\tt textual} operators
+return {\tt true} if the first component is a filled outline or a piece of
+typeset text.  The {\tt clipped} and {\tt bounded} 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.
+
+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} is the path describing the line that got stroked,
+{\tt penpart p} is the pen that was used, {\tt dashpart p} is the dash
+pattern, and the color is
+$$ \hbox{\tt (redpart p, greenpart p, bluepart p)} $$
+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} gives the text that got
+typeset, {\tt fontpart p} gives the font that was used, and {\tt xpart~p},
+{\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.  The {\tt redpart},
+{\tt greenpart}, and {\tt bluepart} operators also work for text components.
+
+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---they return null values instead:
+the trivial path {\tt (0,0)} for {\tt pathpart},
+{\tt nullpen} for {\tt penpart},
+an empty picture for {\tt dashpart},
+zero for {\tt redpart}, {\tt greenpart}, {\tt bluepart},
+and the null string for {\tt textpart} or {\tt fontpart}.
+
+One final operator for extracting information from a picture is
+$$ {\tt length}\ \descr{picture primary} $$
+This returns the number of components that a {\tt for}\ldots {\tt within}
+iteration would find.
+
+\subsection{Other New Features}
+
+The {\tt marith.mp} and {\tt sarith.mp} packages use numbers of magnitude
+4096 more.  Since such numbers can cause overflow problems in MetaPost's
+linear equation solving and path fitting algorithms, they are normally
+allowed only as intermediate results.  This limitation is removed when
+the internal variable {\tt warningcheck} is zero.  In earlier versions
+of MetaPost, the limitation could be removed for variables but explicit
+constants were always restricted to be less than 4096.
+
+For completeness, we also mention one other new feature of MetaPost
+Version 0.60.  When \TeX\ material is included in a picture via the
+{\tt btex}\ldots{\tt etex} feature, the thickness of horizontal and
+vertical rules gets rounded to exactly the right number of pixels; i.e.,
+interpreting MetaPost output according to the PostScript\regmark\ scan
+conversion rules~\cite{ad:red} makes the pixel width equal to the ceiling
+of the unrounded width.  In fact, a similar relationship holds for all line
+widths.  The generated PostScript sets line widths by first transforming
+to device coordinates and rounding appropriately.
+
+
+
+
+
+
+\bibliographystyle{plain}
+\bibliography{mpgraph}
+
+
+
+
+\end{document}
+
+
+
+% Copyright 1990 - 1995 by AT&T Bell Laboratories.
+
+% 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.
diff --git a/Master/texmf-dist/doc/metapost/base/source/mpintro.bib b/Master/texmf-dist/doc/metapost/base/source/mpintro.bib
new file mode 100644
index 00000000000..dc90248f30b
--- /dev/null
+++ b/Master/texmf-dist/doc/metapost/base/source/mpintro.bib
@@ -0,0 +1,48 @@
+@techreport{CSTR116,
+	author = "Kernighan, Brian W.",
+	title = "{PIC}---A Graphics Language for Typesetting",
+	type = "Computing Science Technical Report",
+	number = 116,
+	institution = "AT\&T Bell Laboratories",
+	address = "Murray Hill, New Jersey",
+	year = 1984
+}
+@incollection{ke:pic,
+	author = "Kernighan, Brian W.",
+	title = "Pic---A Graphics Language for Typesetting",
+	booktitle = "Unix Research System Papers, Tenth Edition",
+	publisher = "AT\&T Bell Laboratories",
+	pages = "53--77",
+	year = 1990
+}
+@book{kn:c,
+	key = "Knuth",
+	author = "D. E. Knuth",
+	title = "Computers and Typesetting",
+	volume = "C",
+	subtitle = "The {\MF}book",
+	publisher = "Addison Wesley",
+	address = "Reading, Massachusetts",
+	year = 1986
+}
+@article{ho:mp1,
+	key = "Hobby",
+	author = "J. D. Hobby",
+	title = "A {\MF}-like System with {P}ost{S}cript Output",
+	journal = "Tugboat, the\/ {\TeX} User's Group Newsletter",
+	volume = 10,
+	number = 4,
+	pages = "505--512",
+	month = dec,
+	year = 1989
+}
+@book{kn:d,
+	key = "Knuth",
+	author = "D. E. Knuth",
+	title = "Computers and Typesetting",
+	volume = "D",
+	subtitle = "{\MF} the Program",
+	publisher = "Addison Wesley",
+	address = "Reading, Massachusetts",
+	year = 1986
+}
diff --git a/Master/texmf-dist/doc/metapost/base/source/mpintro.tex b/Master/texmf-dist/doc/metapost/base/source/mpintro.tex
new file mode 100644
index 00000000000..99e487c46dd
--- /dev/null
+++ b/Master/texmf-dist/doc/metapost/base/source/mpintro.tex
@@ -0,0 +1,878 @@
+\documentstyle{article}
+\input epsf
+
+\author{John D. Hobby}
+\title{The MetaPost System}
+
+\font\textt=cmtex10
+
+\makeatletter
+\def\logo{\global\font\logo=logo10 at1\@ptsize\p@ \logo}
+\def\logosl{\global\font\logosl=logosl10 at1\@ptsize\p@ \logosl}
+\def\MF{{\ifdim \fontdimen\@ne\font >\z@ \def\logo{\logosl}\fi
+	{\logo META}\-{\logo FONT}}}
+\makeatother
+
+\def\descr#1{{\langle\hbox{#1}\rangle}}
+\def\lit#1{{\hbox{\textt#1}}}
+\def\okbreak{\vfil\penalty2000 \vfilneg}
+
+{\obeylines\obeyspaces\gdef\startverbatim{%
+\vcenter\bgroup\textt\catcode`\$=12\catcode`\}=12\catcode`\{=12\catcode`\_=12%
+\catcode`\\=12\catcode`\#=12\catcode`\^=12\catcode`\%=0%
+\obeyspaces\let =\ \obeylines\let^^M=\cr\halign\bgroup##\hfil}}
+\def\stopverbatim{\egroup\egroup}
+
+\begin{document}
+\maketitle
+
+\begin{abstract}
+The MetaPost system implements a picture-drawing language very much like Knuth's
+\MF\ except that it outputs PostScript commands instead of run-length-encoded
+bitmaps.  MetaPost is a powerful language for producing figures for documents
+to be printed on PostScript printers.  It provides easy access to all the
+features of PostScript and it includes facilities for integrating text and
+graphics.
+
+This document describes the system and its implementation.  It also includes
+basic user documentation to be used in conjunction with {\it The \MF book}.
+Much of the source code was copied from the \MF\ sources by permission from
+the author.
+\end{abstract}
+
+
+\section{Overview}
+The MetaPost system is based on Knuth's \MF\footnote{\MF\ is a trademark
+of Addison Wesley Publishing company.}~\cite{kn:c} and much of the source
+code is copied with permission from the \MF\ sources.  MetaPost is a graphics
+language like \MF, but with new primitives for integrating text and graphics and
+for accessing special features of PostScript\footnote{PostScript is a
+trademark of Adobe Systems Inc.} such as clipping, shading, and
+dashed lines.  The language has the main features of \MF\ including first-class
+objects for curves, pictures, affine transformations, and pen shapes.
+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.
+
+While MetaPost could be used as a tool for generating PostScript fonts,
+the intended application is to generate figures for \TeX\footnote{\TeX\ is a
+trademark of the American Mathematical Society.} and {\it troff\/} documents.
+The figures can be integrated into a \TeX\ document via a freely available
+program called {\tt dvips} as shown in Figure~1.\footnote{The C source for
+{\tt dvips} comes with the web2c \TeX\ distribution. Similar programs are
+available from other sources.}  A similar procedure works with troff: the
+{\tt dpost} output processor includes PostScript figures when they are
+requested via troff's {\tt \char`\\X} command.
+
+\begin{figure}[htp]
+$$ \def\fbox#1{\hbox{\vrule
+	\vbox{\hrule\kern5pt\hbox{\kern5pt\hbox{#1}\kern5pt}\kern5pt\hrule}%
+	\vrule}}
+   \vbox{
+    \halign{$\hfil#\hfil$&\hskip1in$\hfil#\hfil$\cr
+	\hbox{Figures in MetaPost}&
+	\hbox{\TeX\ Document}
+	\cr
+	\bigg\downarrow&
+	\bigg\downarrow
+	\cr
+	\fbox{\vrule height.2in depth.133in width0pt
+		\kern .1in MetaPost\kern.1in}
+	&
+	\fbox{\vrule height.2in depth.133in width0pt
+		\kern .167in \TeX\kern.167in}
+	\cr
+	\bigg\downarrow&
+	\bigg\downarrow
+	\cr
+	\hbox{Figures in PostScript}&
+	\hbox{{\tt dvi} file}
+	\cr
+	\bigg\downarrow&
+	\bigg\downarrow
+	\cr
+	\fbox{\vrule height.2in depth.133in width0pt
+		\kern 1in {\tt dvips} \kern1in}
+	\span\omit\cr
+	\bigg\downarrow\span\omit\cr
+	\hbox{PostScript}\span\omit\cr}}
+   \atop
+   \vbox{\noindent Fig.~1: A diagram of the processing for a \TeX\ document with figures
+	done in Meta\-Post}
+$$
+\end{figure}
+
+Other than the new commands for integrating text and accessing features of
+PostScript, the main difference between the \MF\ and MetaPost languages is
+that the latter deals with continuous pictures rather than discrete ones.
+This affects the coordinate system and some of the subtler aspects of the
+language as outlined in the next two sections.
+
+Sections \ref{basic} and \ref{advanced} give a short summary of the language
+with numerous examples.  Then Section~\ref{impsec} describes the implementation.
+A preliminary description of the language has already appeared~\cite{ho:mp1}.
+
+\section{Introduction to MetaPost}
+\label{basic}
+MetaPost is a lot like Knuth's \MF\
+except that it outputs PostScript programs instead
+of bitmaps.  Knuth describes the \MF\ language in {\sl The \MF book\/}.~\cite{kn:d}
+
+This document introduces MetaPost via examples and references to key parts of
+{\sl The \MF book}.  It is a good idea to start by reading chapters 2~and 3
+in {\sl The \MF book}.  The introductory material in these chapters applies
+to MetaPost except that coordinates are in units of
+PostScript points by default (72 units per inch).
+
+To see MetaPost in action, consider a file \lit{fig.mp} containing the
+following text:\vadjust{\okbreak}
+$$ \startverbatim
+beginfig(1);
+a=.7in; b=0.5in;
+z0=(0,0); z1=(a,0); z2=(0,b);
+z0=.5[z1,z3]=.5[z2,z4];
+draw z1..z2..z3..z4..cycle;
+drawarrow z0..z1;
+drawarrow z0..z2;
+label.top(btex $a$ etex, .5[z0,z1]);
+label.lft(btex $b$ etex, .5[z0,z2]);
+endfig;
+end
+%stopverbatim$$
+Then the command \lit{mp} \lit{fig} produces an output file \lit{fig.1}
+that can be included in a
+\TeX\ document.  After \lit{\string\input} \lit{epsf} the \TeX\ commands
+\lit{\$\$\string\epsfbox\char`\{fig.1\char`\}\$\$} produce
+$$ \epsfbox{examples.1} $$
+The \lit{beginfig(1)} line means that everything up to the next
+\lit{endfig} is to be used to create \lit{fig.1}.  If there
+were more than one figure in \lit{fig.mp}, there would be additional
+\lit{beginfig} $\ldots$ \lit{endfig} blocks.
+
+The \lit{drawarrow} macro has been specially developed for MetaPost.
+There is also a command called \lit{drawdblarrow} that draws the
+following path with arrowheads on both ends.  The line beginning with
+\lit{label.top} is a call to a standard macro for positioning text just
+above a given point.  In this case, the point \lit{.5[z0,z1]} is the
+midpoint of the segment from \lit{z0} to \lit{z1} and the text is
+generated by the \TeX\ commands \lit{\$a\$}.  In addition to \lit{label.top}
+and \lit{label.lft}, there is also \lit{label.bot}, \lit{label.rt},
+and four other versions \lit{label.ulft} for upper-left etc.  Just
+plain \lit{label} without any suffix centers the
+label on the given point.
+
+The discussion of pens in Chapter~4 of {\sl The \MF book\/} applies
+to MetaPost as well, but simple figures often do not need to refer to
+pens explicitly because they can just use the default pen which is a
+circle $0.5{\it bp}$ in diameter.\footnote{The letters ``{\it bp}''
+stand for ``big point'' ($1\over72$ inch).  This is one of the standard
+units of measure in \TeX\ and \MF\ and it is the default unit for
+MetaPost. A complete listing of predefined units is given on page~92 of
+{\sl The \MF book}.} This produces lines of uniform thickness
+$0.5{\it bp}$ regardless of the direction of the line.
+
+Chapter 5 of {\sl The \MF book\/} does not apply to MetaPost.
+In particular, there is no \lit{mode\_setup} macro or ``sharped units''
+and \lit{mp} does not output \lit{gf} files.  MetaPost does have
+a set of preloaded macros but they are not the same as \MF's plain base.
+If there were an
+analogous chapter about running MetaPost, it would probably mention that
+\lit{mp} skips over \lit{btex} $\ldots$ \lit{etex} blocks
+and depends on a preprocessor to translate them into low level MetaPost
+commands.  If the main file is \lit{fig.mp}, the translated \TeX\
+material is placed in a file named \lit{fig.mpx}.  This is normally
+done silently without any user intervention but it could fail if one of
+the \lit{btex} $\ldots$ \lit{etex} blocks contains an erroneous
+\TeX\ command.  If this happens, the erroneous \TeX\ input is saved in
+the file \lit{mpxerr.tex} and the error messages appear in
+\lit{mpxerr.log}.
+
+If there is a need for \TeX\ macro definitions or any other auxiliary
+\TeX\ commands, they can be enclosed in a
+\lit{verbatimtex} $\ldots$ \lit{etex} block.  The difference between
+\lit{btex} and \lit{verbatimtex} is that the former generates a picture
+expression while the latter does not.
+
+On Unix systems, an environment variable can be used to specify that
+\lit{btex} $\ldots$ \lit{etex} and \lit{verbatimtex} $\ldots$ \lit{etex}
+blocks are in {\it troff\/} instead of \TeX.  When using this option,
+it is a good idea to give the MetaPost command \lit{prologues:=1}.
+This tells \lit{mp} to output structured PostScript and assume that
+text comes from built-in PostScript fonts.
+
+Chapters 6--10 of {\sl The \MF book\/} cover important aspects of \MF\
+that are almost identical in MetaPost.  The only change to the tokenization
+process described in Chapter~6 is that \TeX\ material can contain
+percent signs and unmatched double quote characters so these are
+treated like spaces when skipping \TeX\ material.  The preprocessor gives
+\TeX\ everything between \lit{btex} and \lit{etex} except for leading
+and trailing spaces.
+
+Chapters 7--10 discuss the types of variables and expressions that \MF\
+understands.  MetaPost has an additional type ``\lit{color}'' that is
+a lot like \lit{pair} except that it has three components instead of
+two.  The operations allowed on colors are addition, subtraction, scalar
+multiplication, and scalar division.  MetaPost also understands mediation
+expressions involving colors since
+\lit{.3[w,b]} is equivalent to \lit{w+.3(b-w)} which is allowed
+even when \lit{w} and \lit{b} are colors.  Colors can be specified
+in terms of the predefined constants \lit{black}, \lit{white},
+\lit{red}, \lit{green}, \lit{blue}, or the red, green, and blue
+components can be given explicitly.  Black is \lit{(0,0,0)} and white
+is \lit{(1,1,1)}.  There is no restriction against colors ``blacker
+than black'' or ``whiter than white'' except all components are snapped
+back to the $[0,1]$ range when a color is given in an output file.
+MetaPost solves linear equations involving colors the same way it does
+so for pairs.  (This is explained in Chapter~9).
+
+Let's consider another example that uses some of the ideas discussed above.
+The MetaPost program\vadjust{\okbreak}
+$$ \startverbatim
+beginfig(2);
+h=2in; w=2.7in;
+path p[], q[], pp;
+for i=1.5,2,4: ii:=i**2;
+  p[i] = (w/ii,h){1/ii,-1}...(w/i,h/i)...(w,h/ii){1,-1/ii};
+endfor
+for i=.5,1.5: q[i] = origin..(w,i*h) cutafter p1.5; endfor
+pp = buildcycle(q0.5, p2, q1.5, p4);
+fill pp withcolor .8white;
+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;
+makelabel.top(btex $P$ etex, p2 intersectionpoint q0.5);
+makelabel.rt(btex $Q$ etex, p2 intersectionpoint q1.5);
+endfig;
+%stopverbatim$$
+produces the following figure:\vadjust{\okbreak}
+$$ \epsfbox{examples.2} $$
+
+The third line declares arrays of paths \lit{p} and \lit{q} as explained
+in Chapter~7.  Note that \lit{q1.5} is the same as \lit{q[i]} when
+$\lit{i}=1.5$.  The \lit{for} loops make each \lit{p[i]}
+an approximation to an arc of the hyperbola
+$$xy={wh\over i^2} $$
+and each \lit{q[i]} a segment of slope $ih/w$.  (Loops are discussed in
+Chapter~19 of {\sl The \MF book\/}).
+
+The \lit{cutafter} operator is used to cut off the part of \lit{q[i]} after
+the intersection with \lit{p1.5}.  (There is no ``\lit{draw} \lit{p1.5}'' in
+the input for the above figure so this hyperbola is invisible).  There is also a
+\lit{cutbefore} operator defined to make
+$$ a \lit{ cutbefore } b $$
+what's left of path~$a$ when everything before its intersection with~$b$ is
+removed.  In case of multiple intersections \lit{cutbefore} and \lit{cutafter}
+try to cut off as little as possible.
+
+The shaded region in the above figure is due to the line
+$$ \lit{fill pp withcolor .8white} $$
+The boundary of this region is the path \lit{pp} that the \lit{buildcycle}
+macro creates by piecing together the four paths given as arguments.  In other
+words, \lit{pp} is constructed by going along \lit{q0.5} until it
+intersects \lit{p2}, then going along \lit{p2} until hitting
+\lit{q1.5}, etc.  It turns out that this requires going backwards along
+\lit{p2} and \lit{q1.5}.  The \lit{buildcycle} macro tries to avoid
+going backwards if it has a choice as to which intersection points to choose,
+but in this example each pair of consecutive path arguments has a unique
+intersection point.  It is generally a good idea to avoid multiple intersections
+because they can lead to unpleasant surprises.
+
+The \lit{fill} and \lit{unfill} macros in plain MetaPost are similar to
+the corresponding macros discussed in Chapter~13 of {\sl The \MF book\/}
+but MetaPost assigns colors to regions rather than assigning weights to pixels.
+There is no \lit{cull} command or \lit{withweight} option in MetaPost.
+The \lit{unfill} macro used to erase the rectangle containing the label
+``$f>0$'' in the above figure works by specifying ``\lit{withcolor}
+\lit{background}''
+where \lit{background}'' is usually equal to \lit{white}.  The complete
+syntax for primitive drawing commands in MetaPost is as follows:
+$$\tabskip=0.0pt plus 1000.0pt minus 1000.0pt
+  \halign to\hsize{$#$\hfil\cr
+  \descr{picture command} \rightarrow
+     \descr{addto command} \mid \descr{clip command} \cr
+  \descr{addto command} \rightarrow {} \cr
+  \qquad \lit{addto }\descr{picture variable} \lit{ also }
+     \descr{picture expression} \descr{with list} \cr
+  \qquad {}\mid \lit{addto } \descr{picture variable} \lit{ contour }
+     \descr{path expression} \descr{with list} \cr
+  \qquad {}\mid \lit{addto } \descr{picture variable} \lit{ doublepath }
+     \descr{path expression} \descr{with list} \cr
+  \descr{with list} \rightarrow \descr{empty} \mid
+     \descr{with clause} \descr{with list} \cr
+  \descr{with clause} \rightarrow \lit{withcolor } \descr{color expression}\cr
+  \qquad {} \mid \lit{withpen } \descr{pen expression}
+     \mid \lit{dashed } \descr{picture expression}\cr
+  \descr{clip command} \rightarrow \lit{clip }
+     \descr{picture variable} \lit{ to } \descr{path expression} \cr}
+$$
+If $P$ stands for \lit{currentpicture}, $q$ stands for
+\lit{currentpen}, and $b$ stands for \lit{background}, the standard
+drawing macros have roughly the following meanings:
+$$ \tabskip=0.0pt plus 1000.0pt minus 1000.0pt
+  \halign to\hsize{$#$\hfil&\quad means\quad $#$\hfil\cr
+  \lit{draw }p&		\lit{addto }P\lit{ doublepath }p\lit{ withpen }q\cr
+  \lit{fill }c&		\lit{addto }P\lit{ contour }c\cr
+  \lit{filldraw }c&	\lit{addto }P\lit{ contour }c\lit{ withpen }q\cr
+  \lit{undraw }p&		\lit{addto }P\lit{ doublepath }p\lit{ withpen }q
+	\lit{ withcolor }b\cr
+  \lit{unfill }c&		\lit{addto }P\lit{ contour }c\lit{ withcolor }b\cr
+  \lit{unfilldraw }c&	\lit{addto }P\lit{ contour }c\lit{ withpen }q
+	\lit{ withcolor }b\cr}
+$$
+The expressions denoted by $c$ in the table must be cyclic paths, while path
+expressions $p$ need not be cyclic.  It is also possible to use \lit{draw}
+and \lit{undraw} when the argument is a picture~$r$:
+$$ \tabskip=0.0pt plus 1000.0pt minus 1000.0pt
+  \halign to\hsize{$#$\hfil&\quad means\quad $#$\hfil\cr
+  \lit{draw }r&		\lit{addto }P\lit{ also }r\cr
+  \lit{undraw }r&	\lit{addto }P\lit{ also }r\lit{ withcolor }b\cr}
+$$
+
+The argument to \lit{unfill} in the last example is \lit{bbox lab}.
+This is a call to a standard macro that gives the bounding box of a picture
+as a rectangular path.  The \lit{center} macro used two lines previously
+makes \lit{z0} the center of the bounding box for path \lit{pp}.  (This
+works for paths and pictures).  The expression
+$$ \lit{thelabel(btex \$f>0\$ etex, z0)} $$
+computes a picture containing the text ``$f>0$'' centered on the point
+\lit{z0}.
+
+Here is the complete syntax for labeling commands:
+$$\tabskip=0.0pt plus 1000.0pt minus 1000.0pt
+  \halign to\hsize{$#$\hfil\cr
+  \descr{label command} \rightarrow
+	\descr{command name} \descr{position suffix}
+	(\descr{label text},\ \descr{label loc}) \cr
+  \qquad {}\mid \lit{labels} \descr{position suffix} (\descr{suffix list}) \cr
+  \descr{command name} \rightarrow \lit{label}
+	\mid \lit{thelabel} \mid \lit{makelabel} \cr
+  \descr{position suffix} \rightarrow
+	\descr{empty} \mid \lit{.lft} \mid \lit{.rt} \mid \lit{.top}
+	\mid \lit{.bot} \cr
+  \qquad {}\mid \lit{.ulft} \mid \lit{.urt} \mid \lit{.llft}
+	\mid \lit{.lrt}\cr
+  \descr{label text} \rightarrow \descr{picture expression}
+	\mid \descr{string expression} \cr
+  \descr{label loc} \rightarrow \descr{pair expression} \cr
+  \descr{suffix list} \rightarrow \descr{suffix}
+	\mid \descr{suffix}, \descr{suffix list} \cr}
+$$
+The \lit{label} command adds text to \lit{currentpicture} near the
+position $\descr{label loc}$ as determined by the $\descr{position suffix}$.
+An empty suffix centers the label and the other options offset it slightly so
+that it does not overlap the $\descr{label loc}$.  Using \lit{thelabel} just
+creates a picture expression rather than actually adding it to
+\lit{currentpicture}. Using \lit{makelabel} instead of \lit{label} adds a dot
+at the location being labeled.  Finally, the \lit{labels}
+command does
+$$ \lit{makelabel} \descr{position suffix}
+	(\lit{str}\,\descr{suffix},\,\lit{z}\descr{suffix})
+$$
+for each $\descr{suffix}$ in the $\descr{suffix list}$, using the \lit{str}
+operator to convert the suffix to a string.  Thus \lit{labels.top(1,2a)} places
+labels ``\lit{1}'' and ``\lit{2a}'' just above \lit{z1} and \lit{z2a}.
+
+The examples given so far have all used $\descr{label text}$ of the form
+$$ \lit{btex}\ \descr{\TeX\ commands}\ \lit{etex}.
+$$
+This gets converted into a picture expression.  If the label is simple enough,
+it can be given directly as a string expression in which case it is typeset
+in \lit{defaultfont} at \lit{defaultscale} times its design size.
+Normally,
+$$ \lit{defaultfont="cmr10"}
+   \quad{\rm and}\quad \lit{defaultscale=1},
+$$
+but these can be reset if desired.  Using \lit{cmtex10} instead of
+\lit{cmr10} would allow the label to contain spaces and special characters.
+If there is any doubt about what the design size is, use the \lit{fontsize}
+operator to find it as follows:
+$$ \lit{defaultfont:="Times";}
+   \qquad \lit{defaultscale:=10/fontsize "Times"}
+$$
+
+Notice that a $\descr{with clause}$ can be
+``\lit{dashed} $\descr{picture expression}$.''  The picture
+gives a template that tells how the line being drawn is to be dashed.  There
+is a standard template called \lit{evenly} that makes dashes $3bp$ long
+separated by gaps of length $3bp$.  It is possible to scale the template in
+order to get a finer or coarser pattern.  Thus
+$$ \lit{draw z1..z2 dashed evenly scaled 2} $$
+draws a line with dashes $6bp$ long with gaps of $6bp$.
+
+The following MetaPost input illustrates the use of dashed
+lines:\vadjust{\okbreak}
+$$ \startverbatim
+beginfig(3);
+3.2scf = 2.4in;
+path fun;
+# = .1;
+fun = ((0,-1#)..(1,.5#){right}..(1.9,.2#){right}
+       ..{curl .1}(3.2,2#))  scaled scf yscaled(1/#);
+vardef vertline primary x = (x,-infinity)..(x,infinity) enddef;
+primarydef f atx x = (f intersectionpoint vertline x) enddef;
+primarydef f whenx x = xpart(f intersectiontimes vertline x)
+  enddef;
+z1a = (2.5scf,0);
+z1 = fun atx x1a;
+y2a=0; z1-z2a=whatever*direction fun whenx x1 of fun;
+z2 = fun atx x2a;
+y3a=0; z2-z3a=whatever*direction fun whenx x2 of fun;
+draw fun withpen pencircle scaled 1pt;
+drawarrow (0,0)..(3.2scf,0);
+label.bot(btex $x_1$ etex, z1a);
+draw z1a..z1 dashed evenly;
+makelabel(nullpicture, z1);
+draw z1..z2a withpen pencircle scaled .3;
+label.bot(btex $x_2$ etex, z2a);
+draw z2a..z2 dashed evenly;
+makelabel(nullpicture, z2);
+draw z2..z3a withpen pencircle scaled .3;
+label.bot(btex $x_3$ etex, z3a);
+endfig;
+%stopverbatim$$
+This produces the following figure:\vadjust{\okbreak}
+$$ \epsfbox{examples.3} $$
+
+The above figure uses some of the more advanced properties of paths discussed
+in Chapter~14 of {\sl The \MF book}.  All of this material applies to
+MetaPost as well as \MF\ except for the explanation of ``strange paths'' which
+fortunately cannot occur in MetaPost.  The parts most relevant to this figure
+are the explanation of ``curl'' specifications and the \lit{direction},
+\lit{intersectiontimes}, and \lit{intersectionpoint} operators.
+In order to ensure that the path \lit{fun} makes $y$ a unique function
+of~$x$, the path is first constructed with the $y$-coordinates compressed
+by a factor of ten.  The final ``\lit{yscaled(1/\char`\#)}'' restores
+the original aspect ratio after MetaPost has chosen a cubic spline that
+interpolates the given points.
+
+The \lit{yscaled} operator is an example of a very important class of
+operators that apply affine transformations to pairs, paths, pens, pictures,
+and other transforms.  The discussion in Chapter~15 is relevant and
+important.  The only differences are that MetaPost has no
+{\it currenttransform} and there is no restriction on the type of
+transformations that can be applied to pictures.
+
+\section{More Advanced Topics}
+\label{advanced}
+MetaPost does have pens like those in \MF\ but they aren't very important
+to the casual user except occasionally to specify changes in line widths
+as in the preceding figure.  Anyone reading the description in Chapter~16 of
+{\sl The \MF book} should beware that there is no such thing as a
+``future pen'' in MetaPost and elliptical pens are never converted into
+polygons.  Furthermore, there is no need for \lit{cutoff} and
+\lit{cutdraw} because the same effect can be achieved by setting the
+internal parameter \lit{linecap:=butt}.\vadjust{\okbreak}
+$$\startverbatim
+beginfig(4);
+for i=0 upto 2:
+  z[i]=(0,40i); z[i+3]-z[i]=(100,30);
+endfor
+pickup pencircle scaled 18;
+def gray = withcolor .8white enddef;
+draw z0..z3 gray;
+linecap:=butt; draw z1..z4 gray;
+linecap:=squared; draw z2..z5 gray;
+labels.top(0,1,2,3,4,5);
+endfig; linecap:=rounded;
+%stopverbatim
+\qquad
+\vcenter{\epsfbox{examples.4}}
+$$
+
+There is also a \lit{linejoin} parameter as illustrated below.
+The default values of \lit{linecap} and \lit{linejoin} are both
+\lit{rounded}.\vadjust{\okbreak}
+$$ \startverbatim
+beginfig(5);
+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;
+def gray = withcolor .8white enddef;
+draw z0--z3--z6 gray;
+linejoin:=mitered; draw z1..z4--z7 gray;
+linejoin:=beveled; draw z2..z5--z8 gray;
+labels.bot(0,1,2,3,4,5,6,7,8);
+endfig; linejoin:=rounded;
+%stopverbatim
+\qquad
+\vcenter{\epsfbox{examples.5}}
+\mskip-54mu % allow it to hang into the margin
+$$
+
+Another way to adjust the behavior of drawing commands is by giving the
+declaration
+$$ \lit{drawoptions}(\descr{with list}) $$
+For instance,
+$$ \lit{drawoptions(withcolor blue)} $$
+gives subsequent drawing commands the default color blue.  This can still
+be overridden by giving another \lit{withcolor} clause as in
+$$ \lit{draw p withcolor red} $$
+The options apply only to relevant drawing commands:
+$$ \lit{drawoptions(dashed dd)} $$
+will affect \lit{draw} commands but not fill commands.
+
+Chapters 17--20 of {\sl The \MF book} describe the programming constructs
+necessary to customize the language to a particular problem.  These features
+work the same way in MetaPost but a few additional comments are needed.
+These chapters mention certain macros from plain \MF\ that are not in the
+plain macro package for MetaPost.  Generally if it sounds as though it's
+for making fonts, MetaPost doesn't have it.  Remember that \lit{beginfig}
+and \lit{endfig} play the role of \MF's \lit{beginchar} and \lit{endchar}.
+Look in the file \lit{plain.mp} in the standard macro area if there is any
+doubt about what macros are predefined.  This file is also a good source of
+examples.
+
+Chapter 17 explains how the \lit{interim} statement makes temporary changes
+to internal quantities.  This works the same way in MetaPost except that
+the example involving {\it autorounding} is inappropriate because MetaPost
+doesn't have that particular quantity.  Here is a complete list of the
+internal quantities found in \MF\ but not MetaPost:
+$$\vcenter{\hsize=.8\hsize \raggedright \multiply\rightskip by3 \textt\noindent
+	\lit{autorounding}, \lit{fillin}, \lit{granularity}, \lit{hppp},
+	\lit{proofing}, \lit{smoothing}, \lit{tracingedges},
+	\lit{tracingpens}, \lit{turningcheck}, \lit{vppp}, \lit{xoffset},
+	\lit{yoffset}}
+$$
+The following additional quantities are defined in plain \MF\ but not in
+plain MetaPost:
+$$\vcenter{\hsize=.8\hsize \raggedright \multiply\rightskip by3 \textt\noindent
+	\lit{pixels\_per\_inch}, \lit{blacker}, \lit{o\_correction},
+	\lit{displaying}, \lit{screen\_rows}, \lit{screen\_cols},
+	\lit{currentwindow}}
+$$
+
+There are also some internal quantities that are unique to MetaPost.
+The \lit{linecap} and \lit{linejoin} parameters have already been mentioned.
+There is also a \lit{miterlimit} parameter that behaves like the similarly
+named parameter in PostScript.  Another parameter, \lit{tracing\_lost\_chars}
+suppresses error messages about attempts to typeset missing characters.
+This is probably only relevant when using string parameters in the labeling
+macros since expressions generated by \lit{btex} $\ldots$ \lit{etex}
+blocks are not likely to use missing characters.
+
+The \lit{prologues} parameter was referred to earlier when we recommended
+setting it to one when including MetaPost output in a {\it troff\/} document.
+Any positivie value causes the output files to be ``conforming PostScript''
+that assumes only standard Adobe fonts are used.  This makes the output
+more portable but on most implementations, it precludes the use of the use
+of \TeX\ fonts such as \lit{cmr10}.  Software for sending \TeX\ output to
+PostScript printers generally downloads such fonts one character at a time
+and does not make them available in included PostScript figures.
+
+Plain MetaPost also has
+internals \lit{bboxmargin}, \lit{labeloffset} and \lit{ahangle}
+as well as \lit{defaultscale} which controls the size of the default label
+font as explained above.  The \lit{bboxmargin} parameter is the amount of
+extra space that the \lit{bbox} operator leaves; \lit{labeloffset} gives the
+distance by which labels are offset from the point being labeled;
+\lit{ahangle} is the angle of the pointed ends of arrowheads
+($45^\circ$ by default).  There is also a path \lit{ahcirc} that controls
+the size of the arrowheads.  The statement
+$$ \lit{ahcirc := fullcircle scaled d} $$
+changes the arrowhead length to $\lit{d}/2$.
+
+The only relevant new material in {\sl The \MF book\/} not mentioned so far
+is in Chapters 21--22 and Appendix~D.  Chapters 23 and~24 do not apply to
+MetaPost at all.  The grammar given in Chapters 25 and~26 isn't exactly a
+grammar of MetaPost, but most of the differences have been mentioned above.
+There are \lit{redpart}, \lit{bluepart}, and \lit{greenpart} operators for
+colors and there is no \lit{totalweight} operator.  The new primitive for
+label text in pictures is
+$$ \descr{picture secondary} \rightarrow
+	\descr{picture secondary} \lit{ infont } \descr{string primary}
+$$
+Bounding box information can be obtained via the operators
+\begin{eqnarray*}
+  \descr{pair primary} &\rightarrow& \descr{corner selector}
+	\descr{picture primary}\\
+  \descr{corner selector} &\rightarrow& \lit{llcorner} \mid \lit{urcorner}
+	\mid \lit{lrcorner} \mid \lit{urcorner}
+\end{eqnarray*}
+The main reason for having these in the MetaPost language is for measuring
+text but they work for pictures containing any mixture of text and graphics.
+
+The command
+$$ \lit{special }\descr{string expression} $$
+adds a line of text at the beginning of the next output file.  For instance,
+the following commands add PostScript definitions that allow MetaPost output
+to use the built-in font \lit{Times-Roman}.
+$$ \startverbatim
+special "/Times-Roman /Times-Roman def";
+special "/fshow {exch findfont exch scalefont setfont show}";
+special " bind def";
+%stopverbatim
+$$
+A similar definition is generated automatically when you set \lit{prologues:=1}.
+With \lit{prologues=0}, it is assumed that the program that translates \TeX\
+output and includes PostScript figures will add the necessary definition.%
+\footnote{A full description of how to avoid including your
+output in a \TeX\ document is beyond the scope of this documentation.
+MetaPost output generated with \lit{prologues:=1} can be sent directly to a
+PostScript printer if it uses only built-in fonts like \lit{Helvetica}.}
+
+Another new feature of MetaPost that needs further explanation is the idea of
+a dash pattern.  It is easiest if you can just get by with the dash pattern
+called \lit{evenly} that is defined in plain MetaPost, but it seems necessary
+to give the exact rules just in case they are needed.
+
+A dash pattern is a picture containing one or more horizontal
+line segments.  It doesn't matter what pen is used to draw the line segments.
+MetaPost behaves as though the dash pattern is replicated to form an
+infinitely long horizontal dashed line to be used as a template for dashed
+lines.  For example, the following commands create a dash pattern~\lit{dd}:
+$$\startverbatim
+draw (1,0)..(3.0); draw (5,0)..(6,0);
+picture dd; dd=currentpicture; clearit;
+%stopverbatim
+$$
+Lining up an infinite number of copies of \lit{dd} produces a set of line
+segments
+$$ \{\,(5i,0)\ldots(5i+3,0) \mid \hbox{for all integer $i$}\,\}. $$
+This template is used by starting from the $y$-axis and going to the right,
+producing dashes $3bp$ long separated by gaps of length $2bp$.
+
+In this example, successive copies of \lit{dd} are offset by $5bp$ because
+the range of $x$ coordinates covered by the line segments in \lit{dd} is
+$6-1$ or $5bp$.  The offset can be increased by shifting the dash pattern
+vertically so that it lies at a $y$-coordinate greater that $5bp$ in
+absolute value.  The rule is that the horizontal offset between copies of
+the dash pattern is the maximum of $|y|$ and the range of $x$-coordinates.
+
+\bigbreak
+\centerline{\bf Making Boxes}
+\nobreak\medskip
+There are auxiliary macros not included in plain MetaPost that make it
+convenient to do things that {\it pic} is good at.  What follows
+is a description of how to use the macros contained in the file \lit{boxes.mp}.
+This may be of some interest to users who don't need these macros but want to
+see additional examples of what can be done in MetaPost.
+
+The main idea is that one should say
+$$ \lit{boxit} \descr{suffix}(\descr{picture expression}) $$
+in order to create pair variables $\descr{suffix}\lit{.c}$,
+$\descr{suffix}\lit{.n}$, $\descr{suffix}\lit{.e}$, etc.  These can then be
+used for positioning the picture before drawing it with a separate command such
+as
+$$ \lit{drawboxed}(\descr{suffix}) $$
+The command \lit{boxit.bb(pic)} makes \lit{bb.c} the position where the center
+of picture \lit{pic} is to be placed and defines \lit{bb.sw}, \lit{bb.se},
+\lit{bb.ne}, and \lit{bb.nw} to be the corners of a rectangular path that will
+surround the resulting picture.  Variables \lit{bb.dx} and \lit{bb.dy} give
+the spacing between the shifted version of \lit{pic} and the surrounding
+rectangle and \lit{bb.off} is the amount by which \lit{pic} has to be shifted
+to achieve all this.
+
+The \lit{boxit} macro gives linear equations that force \lit{bb.sw},
+\lit{bb.se}, $\ldots$ to be the corners of a rectangle aligned on the $x$ and
+$y$ axes with the picture \lit{pic} centered inside.  The values of \lit{bb.dx},
+\lit{bb.dy}, and \lit{bb.c} are left unspecified so that the user can give
+equations for positioning the boxes.  If no such equations are given, macros
+such as \lit{drawbox} can detect this and give default values.\vadjust{\okbreak}
+$$ \epsfbox{examples.6} $$
+
+\okbreak
+
+The following example shows how this works in practice.
+$$ \startverbatim
+input boxes
+beginfig(7); boxjoin(a.se=b.sw; a.ne=b.nw);
+boxit.a(btex $\cdots$ etex);    boxit.ni(btex $n_i$ etex);
+boxit.di(btex $d_i$ etex);      boxit.nii(btex $n_{i+1}$ etex);
+boxit.dii(btex $d_{i+1}$ etex); boxit.aa(pic_.a);
+boxit.nk(btex $n_k$ etex);      boxit.dk(btex $d_k$ etex);
+di.dy = 2;
+drawboxed(a,ni,di,nii,dii,aa,nk,dk); label.lft("ndtable:", a.w);
+boxjoin(a.sw=b.nw; a.se=b.ne);
+interim defaultdy:=7;
+boxit.ba(); boxit.bb(); boxit.bc();
+boxit.bd(btex $\vdots$ etex); boxit.be(); boxit.bf();
+bd.dx=8; ba.ne=a.sw-(15,10);
+drawboxed(ba,bb,bc,bd,be,bf); label.lft("hashtab:",ba.w);
+def ndblock suffix $ =
+  boxjoin(a.sw=b.nw; a.se=b.ne);
+  forsuffixes $$=$a,$b,$c: boxit$$(); ($$dx,$$dy)=(5.5,4);
+  endfor; enddef;
+ndblock nda;  ndblock ndb;  ndblock ndc;
+nda.a.c-bb.c = ndb.a.c-nda.c.c = (whatever,0);
+xpart ndb.c.se = xpart ndc.a.ne = xpart di.c;
+ndc.a.c - be.c = (whatever,0);
+drawboxes(nda.a,nda.b,nda.c,ndb.a,ndb.b,ndb.c,ndc.a,ndc.b,ndc.c);
+drawarrow bb.c .. nda.a.w;
+drawarrow be.c .. ndc.a.w;
+drawarrow nda.c.c .. ndb.a.w;
+drawarrow nda.a.c{right}..{curl0}ni.c cutafter bpath ni;
+drawarrow nda.b.c{right}..{curl0}di.c cutafter bpath di;
+drawarrow ndc.a.c{right}..{curl0}nii.c cutafter bpath nii;
+drawarrow ndc.b.c{right}..{curl0}dii.c cutafter bpath dii;
+drawarrow ndb.a.c{right}..nk.c cutafter bpath nk;
+drawarrow ndb.b.c{right}..dk.c cutafter bpath dk;
+x.ptr=xpart aa.c;   y.ptr=ypart ndc.a.ne;
+drawarrow subpath (0,.7) of (z.ptr..{left}ndc.c.c);
+label.rt(btex ndblock etex, z.ptr); endfig;
+%stopverbatim
+$$
+It is instructive to compare the MetaPost output below with the similar figure
+in the {\it pic} manual \cite{ke:pic}.\vadjust{\okbreak}
+$$ \epsfbox{examples.7} $$
+
+The second line of input for the above figure contains
+$$ \lit{boxjoin(a.se=b.sw; a.ne=b.nw)} $$
+This causes boxes to line up horizontally by giving additional equations that
+are invoked each time some box \lit{a} is followed by some other box~\lit{b}.
+These equations are first invoked on the next line when box~\lit{a} is followed
+by box~\lit{ni}.  This yields
+$$ \lit{a.se=ni.sw; a.ne=ni.nw} $$
+The next pair of boxes is box~\lit{ni} and box~\lit{di}. This time the
+implicitly generated equations are
+$$ \lit{ni.se=di.sw; ni.ne=di.nw} $$
+This process continues until a new \lit{boxjoin} is given.  In this case the
+new declaration is
+$$ \lit{boxjoin(a.sw=b.nw; a.se=b.ne)} $$
+which causes boxes to be stacked below each other.
+
+After calling \lit{boxit} for the first eight boxes \lit{a} through \lit{dk},
+the example gives the single equation $\lit{di.dy}=2$ followed by a call to
+\lit{drawboxed} that draws the eight boxes with the given text inside of them.
+The equation forces there to be $2bp$ of space above and below the contents
+of box~\lit{di} (the label ``$d_i$'').  Since this doesn't fully specify the
+sizes and positions of the boxes, the \lit{drawboxed} macro starts by
+selecting default values, setting \lit{a.dx} through \lit{dk.dx} equal to
+the default value of $3bp$.
+
+The argument to boxit can be omitted as in \lit{boxit.ba()}
+or \lit{boxit.bb()}.  This is like calling \lit{boxit} with an empty picture.
+Alternatively the argument can be a string expression instead of a picture
+expression in which case the string is typeset in the default font.
+
+In addition to the corner points \lit{a.sw}, \lit{a.se}, $\ldots$, a command
+like \lit{boxit.a} defines points \lit{a.w}, \lit{a.s}, \lit{a.e} and
+\lit{a.n} at the midpoints of the outer rectangle.
+If this bounding rectangle is needed for something other than just being drawn
+by the \lit{drawboxed} macro, it can be referred to as \lit{bpath.a} or in
+general
+$$ \lit{bpath} \descr{box name} $$
+
+The \lit{bpath} macro is used in the arguments to \lit{drawarrow} in the
+previous example.  For instance
+$$ \lit{nda.a.c\char`\{right\char`\}..\char`\{curl0\char`\}ni.c} $$
+is a path from the center of box \lit{nda.a} to the center of box \lit{ni}.
+Following this with ``\lit{cutafter} \lit{bpath.ni}'' makes the arrow
+go towards the center of the box but stop when it hits the outer rectangle.
+
+The next example also uses this technique of cutting connecting arrows when
+they hit a bounding path, but in this case the bounding paths are circles
+and ovals instead of rectangles.  The circles and ovals are created by using
+\lit{circleit} in place of \lit{boxit}.  Saying \lit{circleit.a(pic)}
+defines points \lit{a.c}, \lit{a.s}, \lit{a.e}, \lit{a.n}, \lit{a.w}
+and distances \lit{a.dx} and \lit{a.dy}.  These variables describe how the
+picture is centered in an oval as can be seen from the following
+diagram:\vadjust{\okbreak}
+$$ \epsfbox{examples.8} $$
+
+\okbreak
+
+Here is the input for the figure that uses \lit{circleit}:
+$$\startverbatim
+beginfig(9);
+vardef cuta(suffix a,b) expr p =
+  drawarrow p cutbefore bpath.a cutafter bpath.b;
+  point .5*length p of p
+enddef;
+vardef self@# expr p =
+  cuta(@#,@#) @#.c{curl0}..@#.c+p..{curl0}@#.c  enddef;
+verbatimtex
+  \def\stk#1#2{$\displaystyle{\matrix{#1\cr#2\cr}}$} etex
+circleit.aa("Start"); aa.dx=aa.dy;
+circleit.bb(btex \stk B{(a|b)^*a} etex);
+circleit.cc(btex \stk C{b^*} etex);
+circleit.dd(btex \stk D{(a|b)^*ab} etex);
+circleit.ee("Stop"); ee.dx=ee.dy;
+numeric hsep;
+bb.c-aa.c = dd.c-bb.c = ee.c-dd.c = (hsep,0);
+cc.c-bb.c = (0,.8hsep);
+xpart(ee.e - aa.w) = 3.8in;
+drawboxed(aa,bb,cc,dd,ee);
+label.ulft(btex$b$etex, cuta(aa,cc) aa.c{dir50}..cc.c);
+label.top(btex$b$etex, self.cc(0,30pt));
+label.rt(btex$a$etex, cuta(cc,bb) cc.c..bb.c);
+label.top(btex$a$etex, cuta(aa,bb) aa.c..bb.c);
+label.llft(btex$a$etex, self.bb(-20pt,-35pt));
+label.top(btex$b$etex, cuta(bb,dd) bb.c..dd.c);
+label.top(btex$b$etex, cuta(dd,ee) dd.c..ee.c);
+label.lrt(btex$a$etex, cuta(dd,bb) dd.c..{dir140}bb.c);
+label.bot(btex$a$etex,
+  cuta(ee,bb) ee.c..tension1.3 ..{dir115}bb.c);
+label.urt(btex$b$etex,
+  cuta(ee,cc) ee.c{(cc.c-ee.c)rotated-15}..cc.c);
+endfig;
+%stopverbatim
+$$
+The ``boxes'' produced when using \lit{circleit} come out circular unless
+something forces a different aspect ratio.\vadjust{\okbreak}
+$$ \epsfbox{examples.9} $$
+
+In the above figure, the equations \lit{aa.dx=aa.dy} and \lit{ee.dx=ee.dy} after
+$$ \lit{circleit.aa("Start")}
+    \quad{\rm and}\quad \lit{circleit.ee("Stop")}
+$$
+make the start and stop nodes non-circular.
+
+The general rule is that $\lit{bpath.}c$ comes out circular if
+$c\lit{.dx}$, $c\lit{.dy}$, and $c\lit{.dx}-c\lit{.dy}$ are all unspecified.
+Otherwise the macros select an oval just big enough to contain the given
+picture.  (The margin of safety is given by the internal parameter
+\lit{circmargin}).
+
+There is also a \lit{pic} macro that makes $\lit{pic.}c$ the picture that
+goes inside $\lit{bpath.}c$  In addition to the \lit{drawboxed} macro
+that draws the picture and the surrounding rectangle or oval, there are
+\lit{drawunboxed} and \lit{drawboxes} macros that draw the pictures and
+the surrounding paths separately.
+
+\section{Implementation}
+\label{impsec}
+
+The MetaPost interpreter is written in Knuth's {\tt WEB} language which
+can be thought of as PASCAL with macros.  This choice allows the
+sharing of code with the \MF\ interpreter.~\cite{kn:d}  Indeed, about
+three fourths of the code in the main source file {\tt mp.web} is copied
+from this source by permission from the author.
+
+In accordance with the standard methodology for {\tt WEB} programs,
+parts of the program that are specific to the UNIX\footnote{UNIX is a
+registered trademark of UNIX System Laboratories.} system are given in a
+separate file {\tt mp.ch} that
+the {\tt tangle} processor merges with {\tt mp.web} to form a PASCAL
+program.  (It is then automatically translated into C using a
+special-purpose translator that is included with the UNIX version
+of \TeX.)  The only other code required by the MetaPost interpreter
+is a short external C program {\tt mpext.c} and a small include file
+{\tt mp.h} to tie it all together.
+
+In addition to the main interpreter, there are some programs that control
+the translation of typesetting commands in \lit{btex} $\ldots$ \lit{etex}
+blocks.  When the interpreter encounters \lit{btex} in some input file
+\lit{foo.mp}, it needs to start reading from an auxiliary file \lit{foo.mpx}.
+This file should contain translations of the  \lit{btex} $\ldots$ \lit{etex}
+blocks in \lit{foo.mp} into low-level MetaPost commands.  If \lit{foo.mpx} is
+out of date or does not exist, the MetaPost interpreter invokes a shell script
+that generates the file.
+
+The generation of an auxiliary file \lit{foo.mpx} from an input file
+\lit{foo.mp} is a three step process:  a C~program called \lit{mptotex}
+strips out the \TeX\ commands; then \TeX\ produces a binary file that
+gives low-level typesetting instructions; and finally, a {\tt WEB} program
+\lit{dvitomp} writes equivalent MetaPost commands in the \lit{foo.mpx}
+file.  When using troff, C~programs \lit{mptotr} and \lit{dmp} replace
+\lit{mptotex} and \lit{dvitomp}.
+
+
+
+\bibliographystyle{plain}
+\bibliography{mpintro}
+
+
+\end{document}
diff --git a/Master/texmf-dist/doc/metapost/base/source/mpman.bib b/Master/texmf-dist/doc/metapost/base/source/mpman.bib
new file mode 100644
index 00000000000..ef846d5a79b
--- /dev/null
+++ b/Master/texmf-dist/doc/metapost/base/source/mpman.bib
@@ -0,0 +1,80 @@
+@string{dcg = "Discrete and Computational Geometry"}
+
+@techreport{CSTR116,
+	author = "Kernighan, Brian W.",
+	title = "{PIC}---A Graphics Language for Typesetting",
+	type = "Computing Science Technical Report",
+	number = 116,
+	institution = "AT\&T Bell Laboratories",
+	address = "Murray Hill, New Jersey",
+	year = 1984
+}
+@incollection{ke:pic,
+	author = "Kernighan, Brian W.",
+	title = "Pic---A Graphics Language for Typesetting",
+	booktitle = "Unix Research System Papers, Tenth Edition",
+	publisher = "AT\&T Bell Laboratories",
+	pages = "53--77",
+	year = 1990
+}	
+@book{kn:a,
+	author = "D. E. Knuth",
+	note = "Volume A of {\it Computers and Typesetting}",
+	title = "The {\TeX}book",
+	publisher = "Addison Wesley",
+	address = "Reading, Massachusetts",
+	year = 1986
+}
+@book{kn:c,
+	author = "D. E. Knuth",
+	note = "Volume C of {\it Computers and Typesetting}",
+	title = "The {\MF}book",
+	publisher = "Addison Wesley",
+	address = "Reading, Massachusetts",
+	year = 1986
+}
+@article{kn:mf3,
+	author = "D. E. Knuth",
+	title = "The New Versions of {\TeX} and {\MF}",
+	journal = "{TUG}boat, the\/ {\TeX} User's Group Newsletter",
+	volume = 10,
+	number = 3,
+	pages = "325--328",
+	month = nov,
+	year = 1989
+}
+@book{kn:e,
+	author = "D. E. Knuth",
+	note = "Volume E of {\it Computers and Typesetting}",
+	title = "Computer Modern Typefaces",
+	publisher = "Addison Wesley",
+	address = "Reading, Massachusetts",
+	year = 1986
+}
+@book{ad:red,
+	author = "{Adobe Systems Inc.}",
+	title = "{P}ost{S}cript Language Reference Manual",
+	publisher = "Addison Wesley",
+	address = "Reading, Massachusetts",
+	year = 1986
+}
+@article{ho:mp1,
+	author = "J. D. Hobby",
+	title = "A {\MF}-like System with {P}ost{S}cript Output",
+	journal = "{TUG}boat, the\/ {\TeX} User's Group Newsletter",
+	volume = 10,
+	number = 4,
+	pages = "505--512",
+	month = dec,
+	year = 1989
+}
+@article{ho:splin,
+	key = "Hobby",
+	author = "J. D. Hobby",
+	title = "Smooth, Easy to Compute Interpolating Splines",
+	journal = dcg,
+	volume = 1,
+	number = 2,
+	pagest = "123--140",
+	year = 1986
+}
+\ No newline at end of file
diff --git a/Master/texmf-dist/doc/metapost/base/source/mpman.ist b/Master/texmf-dist/doc/metapost/base/source/mpman.ist
new file mode 100644
index 00000000000..c808a5544bf
--- /dev/null
+++ b/Master/texmf-dist/doc/metapost/base/source/mpman.ist
@@ -0,0 +1,4 @@
+% MakeIndex style file  mpman.ist
+
+% @ is a valid character in some entries
+actual '?' % ? instead of @
diff --git a/Master/texmf-dist/doc/metapost/base/source/mpman.tex b/Master/texmf-dist/doc/metapost/base/source/mpman.tex
new file mode 100644
index 00000000000..4c75733f3ba
--- /dev/null
+++ b/Master/texmf-dist/doc/metapost/base/source/mpman.tex
@@ -0,0 +1,5483 @@
+\documentclass{article} % article is NOT the original style
+\usepackage{makeidx}
+\usepackage{fancyvrb}
+\usepackage{ctabbing}
+\RecustomVerbatimEnvironment
+  {verbatim}{BVerbatim}{baseline=c}
+\usepackage{epsf}
+\usepackage[textwidth=6in,textheight=8.75in]{geometry}
+\usepackage{tocloft}
+\setlength\cftbeforesecskip{1.5ex plus 0.2ex minus 0.1ex}
+
+  \makeatletter
+  \def\logo{\global\font\logo=logo10 at1\@ptsize\p@ \logo}
+  \def\logosl{\global\font\logosl=logosl10 at1\@ptsize\p@ \logosl}
+  \def\MF{{\ifdim \fontdimen\@ne\font >\z@ \def\logo{\logosl}\fi
+        {\logo META}\-{\logo FONT}}}
+  \makeatother
+
+% \def\MF{{META\-FONT}}     % Replacement for the above when using times.sty
+
+
+\newfont\psyvii{rpsyr at 7pt}
+\newcommand\reg{$^{\hbox{\psyvii\char'322}}$}   % Registered trademark
+
+\newcommand\descr[1]{{\langle\hbox{#1}\rangle}}
+\newcommand\invisgap{\nobreak\hskip0pt\relax}
+\newcommand\tdescr[1]{$\langle$\invisgap#1\invisgap$\rangle$}
+
+\newcommand\pl{\dag}
+\newcommand\bx{\ddag}
+
+\newcommand\mathcenter[1]{\vcenter{\hbox{#1}}}
+
+
+\renewcommand{\topfraction}{.85}
+\renewcommand{\bottomfraction}{.7}
+\renewcommand{\textfraction}{.15}
+\renewcommand{\floatpagefraction}{.66}
+\renewcommand{\dbltopfraction}{.66}
+\renewcommand{\dblfloatpagefraction}{.66}
+\setcounter{topnumber}{9}
+\setcounter{bottomnumber}{9}
+\setcounter{totalnumber}{20}
+\setcounter{dbltopnumber}{9}
+
+\makeindex
+
+\begin{document}
+\VerbatimFootnotes
+\author{John D. Hobby}
+\title{A User's Manual for MetaPost}
+\date{}
+\maketitle
+
+\begin{abstract}
+The MetaPost system implements a picture-drawing language very much like Knuth's
+\MF\ except that it outputs PostScript commands instead of run-length-encoded
+bitmaps.  MetaPost is a powerful language for producing figures for documents
+to be printed on PostScript printers.  It provides easy access to all the
+features of PostScript and it includes facilities for integrating text and
+graphics.
+
+This document serves as an introductory user's manual.  It does not require
+knowledge of \MF\ or access to {\it The \MF book}, but both are beneficial.
+An appendix explains the differences between MetaPost and \MF.
+\end{abstract}
+\thispagestyle{empty}
+\newpage
+\setcounter{page}{1}
+\pagestyle{plain}
+\pagenumbering{roman}
+\tableofcontents
+\newpage
+\setcounter{page}{1}
+\pagestyle{headings}
+\pagenumbering{arabic}
+\setlength{\parskip}{1ex plus 0.5ex minus 0.2ex}
+
+\section{Introduction}
+\label{intro}
+
+MetaPost is a programming language much like Knuth's \MF\footnote{\MF\ is a
+trademark of Addison Wesley Publishing company.}\index{metafont?\MF}~\cite{kn:c}
+except that it outputs PostScript programs instead of bitmaps.  Borrowed from \MF\
+are the basic tools for creating and manipulating pictures. These include numbers,
+coordinate pairs, cubic splines, affine transformations, text strings, and boolean
+quantities.  Additional features facilitate integrating text and graphics and
+accessing special features of PostScript\footnote{PostScript is a
+trademark of Adobe Systems Inc.}\index{PostScript} such as clipping, shading, and
+dashed lines.
+Another feature borrowed from \MF\ is the ability to solve linear equations
+that are given implicitly, thus allowing many programs to be written in a
+largely declarative style.  By building complex operations
+from simpler ones, MetaPost achieves both power and flexibility.
+
+MetaPost is particularly
+well-suited to generating figures for technical documents where some aspects of a
+picture may be controlled by mathematical or geometrical constraints that are
+best expressed symbolically.  In other words, MetaPost is not meant to take the
+place of a freehand drawing tool or even an interactive graphics editor.
+It is really a programming language for generating graphics, especially figures
+for \TeX\footnote{\TeX\ is a trademark of the American Mathematical
+Society.}\index{TeX?\TeX} and troff\index{troff} documents.
+The figures can be integrated into a \TeX\ document via a freely available
+program called {\tt dvips}\index{dvips} as shown in
+Figure~\ref{fig0}.\footnote{The C
+source for {\tt dvips} comes with the web2c \TeX\ distribution. Similar programs
+are available from other sources.}  A similar procedure works with troff: the
+{\tt dpost} output processor includes PostScript figures when they are
+requested via troff's {\tt \char`\\X} command.
+
+\begin{figure}[htp]
+$$ \def\fbox#1{\hbox{\vrule
+        \vbox{\hrule\kern5pt\hbox{\kern5pt\hbox{#1}\kern5pt}\kern5pt\hrule}%
+        \vrule}}
+   \vbox{
+    \halign{$\hfil#\hfil$&\hskip1in$\hfil#\hfil$\cr
+        \hbox{Figures in MetaPost}&
+        \hbox{\TeX\ Document}
+        \cr
+        \bigg\downarrow&
+        \bigg\downarrow
+        \cr
+        \fbox{\vrule height.2in depth.133in width0pt
+                \kern .1in MetaPost\kern.1in}
+        &
+        \fbox{\vrule height.2in depth.133in width0pt
+                \kern .167in \TeX\kern.167in}
+        \cr
+        \bigg\downarrow&
+        \bigg\downarrow
+        \cr
+        \hbox{Figures in PostScript}&
+        \hbox{{\tt dvi} file}
+        \cr
+        \bigg\downarrow&
+        \bigg\downarrow
+        \cr
+        \fbox{\vrule height.2in depth.133in width0pt
+                \kern 1in {\tt dvips} \kern1in}
+        \span\omit\cr
+        \bigg\downarrow\span\omit\cr
+        \hbox{PostScript}\span\omit\cr}}
+$$
+\caption[A diagram of the processing for a document with MetaPost figures]
+        {A diagram of the processing for a \TeX\ document with figures
+        in MetaPost}
+\label{fig0}
+\end{figure}
+
+To use MetaPost, you prepare an input file containing MetaPost code and then
+invoke MetaPost, usually by giving a command of the form\index{mp?\texttt{mp}}
+$$ {\tt mp}\, \descr{file name} $$
+(This syntax could be system dependent).
+MetaPost input files\index{files!input} normally have names ending ``{\tt .mp}''
+but this part of the name can be omitted when invoking MetaPost.  For an input
+file {\tt foo.mp}
+$$ \hbox{\tt mp foo} $$
+invokes MetaPost and produces output files with names like {\tt foo.1} and
+{\tt foo.2}.  Any terminal I/O is summarized in a
+transcript\index{files!transcript}\index{transcript file}
+file called {\tt foo.log}.  This includes
+error messages and any MetaPost commands entered interactively.%
+\footnote{A {\tt *}\index{*?\texttt{*}} prompt is used for interactive input and a
+{\tt **}\index{**?\texttt{**}} prompt
+indicates that an input file name is expected.  This can be avoided by invoking
+MetaPost on a file that ends with an {\tt end}\index{end?\texttt{end}} command.}
+The transcript file starts with a banner line that tells what version of MetaPost
+you are using.
+
+This document introduces the MetaPost language, beginning with the features that
+are easiest to use and most important for simple applications.  The first few
+sections describe the language as it appears to the novice user with key parameters
+at their default values.  Some features described in these sections are part of a
+predefined macro package called Plain.  Later sections summarize the
+complete language and distinguish between primitives and preloaded macros
+from the Plain macro package\index{Plain macros}.
+Since much of the language is identical to Knuth's \MF, the appendix gives a
+detailed comparison so that advanced users can learn more about MetaPost by
+reading {\sl The \MF book\/}.~\cite{kn:c}
+
+
+\section{Basic Drawing Statements}
+\label{basic}
+
+The simplest drawing statements are the ones that generate 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:
+$$ \epsfbox{manfig.0} $$
+
+What is meant by coordinates like \verb|(30,0)|?  MetaPost uses the same default
+coordinate system that PostScript\index{PostScript} does.  This means that
+\verb|(30,0)| is 30 units
+to the right of the origin, where a unit is $1\over72$ of an inch.  We shall refer
+to this default unit as a
+{\sl PostScript point\/}\index{PostScript!point}\index{point!PostScript}
+to distinguish it from the standard printer's point\index{point!printer's}
+which is $1\over72.27$ inches.
+
+MetaPost uses the same names for units of measure that \TeX\ and \MF\ do.  Thus
+\verb|bp|\index{bp?\texttt{bp}}\label{Dbp} refers to PostScript points (``big points'')
+and \verb|pt|\index{pt?\texttt{pt}}\label{Dpt} refers to printer's points.
+Other units of measure
+include \verb|in|\index{in?\texttt{in}}\label{Din} for inches,
+\verb|cm|\index{cm?\texttt{cm}}\label{Dcm} for centimeters,
+and \verb|mm|\index{mm?\texttt{mm}}\label{Dmm} for
+millimeters.  For example,
+$$ \hbox{\verb|(2cm,2cm)--(0,0)--(0,3cm)--(3cm,0)--(0,0)|} $$
+generates a larger version of the above diagram.  It is OK to say \verb|0| instead
+\verb|0cm| because {\tt cm} is really just a conversion factor and {\tt 0cm} just
+multiplies the conversion factor by zero.  (MetaPost understands constructions
+like {\tt 2cm}\index{multiplication!implicit} as shorthand for \verb|2*cm|).
+
+It is often convenient to introduce your own scale factor, say $u$.
+Then you can define coordinates in terms of $u$ and decide later whether you want
+to begin with \verb|u=1cm| or \verb|u=0.5cm|.  This gives you control over what
+gets scaled and what does not so that changing $u$ will not affect features such
+as line widths.
+
+There are many ways to affect the appearance of a line besides just changing its
+width, so the width-control mechanisms allow a lot of generality that we do not need
+yet.  
+This leads to the strange looking statement\index{pickup?\texttt{pickup}}\index{pencircle?\texttt{pencircle}}%
+\index{scaled?\texttt{scaled}}
+$$ \hbox{\verb|pickup pencircle scaled 4pt|} $$
+for setting the line width for subsequent \verb|draw| statements to 4 points.
+(This is about eight times the default line width).
+
+With such a wide line width, even a line of zero length comes out as a big bold
+dot\index{dots}.  We can use this to make a grid of bold dots by having one
+\verb|draw| statement
+for each grid point.  Such a repetitive sequence of \verb|draw| statements is
+best written as a pair of nested loops:\index{loops}%
+\index{for?\texttt{for}}\index{endfor?\texttt{endfor}}
+$$\begin{verbatim}
+for i=0 upto 2:
+  for j=0 upto 2:  draw (i*u,j*u);  endfor
+endfor
+\end{verbatim}
+$$
+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:  draw (i*u,j*u);  endfor
+endfor
+endfig;
+\end{verbatim}
+\quad \mathcenter{\epsfbox{manfig.2}}
+$$
+\caption{MetaPost commands and the resulting output}
+\label{fig1}
+\end{figure}
+
+Note that the program in Figure~\ref{fig1} starts with
+\verb|beginfig(2)|\index{beginfig?\texttt{beginfig}} and
+ends with \verb|endfig|\index{endfig?\texttt{endfig}}.
+These are macros that perform various administrative
+functions and ensure that the results of all the \verb|draw| statements get
+packaged up and translated into PostScript.  A MetaPost input file normally
+contains a sequence of \verb|beginfig|, \verb|endfig| pairs with an
+{\tt end}\index{end?\texttt{end}}
+statement after the last one.  If this file is named {\tt fig.mp}, the output
+from \verb|draw| statements between \verb|beginfig(1)| and the next \verb|endfig|
+is written in a file {\tt fig.1}\index{files!output}.
+In other words, the numeric argument to the \verb|beginfig| macro determines the
+name of the corresponding output file.
+
+What does one do with all the PostScript files?  They can be included as figures
+in a \TeX\index{TeX?\TeX} or troff\index{troff} document if you have an
+output driver that can handle
+encapsulated PostScript figures.  If your standard \TeX\ macro directory contains
+a file {\tt epsf.tex}\index{epsf.tex?\texttt{epsf.tex}}, you can probably include {\tt fig.1}
+in a \TeX\ document as follows:
+$$ \begin{array}{c}
+        \hbox{\verb|\input epsf        |}\\
+        \vdots\\
+        \hbox{\verb|$$\epsfbox{fig.1}$$|}
+  \end{array}
+$$
+The \verb|\epsfbox| macro figures out how much room to leave for the figure and
+uses \TeX's \verb|\special| command to insert a request for {\tt fig.1}.
+
+It is also possible to include MetaPost output in a {\em troff\/} document.
+The {\tt -mpictures\/} macro package defines a command \verb|.BP| that includes
+an encapsulated PostScript file.  For instance, the {\em troff\/} command
+$$ \hbox{\verb|.BP fig.1 3c 3c|} $$
+includes {\tt fig.1} and specifies that its height and width are both three
+centimeters.
+
+
+\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|..| 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]
+$$ \epsfbox{manfig.3}
+$$
+\caption[A curve through points 0, 1, 2, 3, and 4]
+        {The result of {\tt draw z0..z1..z2..z3..z4}}
+\label{fig2}
+\end{figure}
+
+There are many other ways to draw a curved path through the same five points.
+To make a smooth closed curve, connect \verb|z4| back to the beginning by
+appending \verb|..cycle|\index{cycle?\texttt{cycle}} to the \verb|draw| statement as shown
+in Figure~\ref{fig3}a.  It is also possible in a single \verb|draw| statement
+to mix curves and straight lines as shown in Figure~\ref{fig3}b.  Just use
+\verb|--| where you want straight lines and \verb|..| where you want curves.
+Thus
+$$ \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]
+$$ {\epsfbox{manfig.104} \atop (a)}
+  \qquad {\epsfbox{manfig.204} \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}
+
+\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}
+$$
+
+\begin{figure}[htp]
+$$ \epsfbox{manfig.5}
+$$
+\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]
+$$ \epsfbox{manfig.6}
+$$
+\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{\epsfbox{manfig.7}} \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{\epsfbox{manfig.8}} \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{\epsfbox{manfig.109}} \atop
+    \hbox{\verb|draw z0{up}..z1{right}..z2{down}|}}
+  \quad
+   {\mathcenter{\epsfbox{manfig.209}} \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.6 and 1..z2..z3|} $$
+The tension parameter can be less than one, but it must be at least $3\over4$.
+
+\begin{figure}[htp]
+$$ {\mathcenter{\epsfbox{manfig.110}} \atop (a)}
+  \quad
+   {\mathcenter{\epsfbox{manfig.210}} \atop (b)}
+  \quad
+   {\mathcenter{\epsfbox{manfig.310}} \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{\epsfbox{manfig.111}} \atop c=0}
+  \qquad
+   {\mathcenter{\epsfbox{manfig.211}} \atop c=1}
+  \qquad
+   {\mathcenter{\epsfbox{manfig.311}} \atop c=2}
+  \qquad
+   {\mathcenter{\epsfbox{manfig.411}} \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; 2*a=b+3;|} $$
+and deduce that $a=2$ and $b=1$.  The same equations can be written slightly more
+compactly by stringing them together with multiple equal signs:
+$$ \hbox{\verb|a+b = 2*a-b = 3;|} $$
+Whichever way you give the equations, you can then give the command\index{show?\texttt{show}}
+$$ \hbox{\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,.6in); z6=(-.3in,1.2in);
+\end{verbatim}
+$$
+
+After reading the equations, the MetaPost interpreter knows the values of
+{\tt z1}, {\tt z2},
+{\tt z3}, and~{\tt z6}.  The next step in the construction of Figure~\ref{fig12}
+is to define points {\tt z4} and {\tt z5} equally spaced along the line from
+{\tt z3} to {\tt z6}.  Since this operation comes up often, MetaPost has a special
+syntax for it.  This mediation construction\index{mediation}
+$$ \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{\epsfbox{manfig.13}}
+$$
+\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 ``{\tt >>} ''.
+Other types of results are printed similarly, except that complicated values are
+sometimes not printed on standard output.  This produces a reference to the
+transcript file\index{files!transcript} that looks like this:
+$$ \hbox{\tt >> picture (see the transcript file)} $$
+If you want to the full results of {\tt show} statements to be printed on your
+terminal, assign a positive value to the
+internal\index{internal variables} variable\index{variables!internal}
+{\tt tracingonline}\index{tracingonline?\texttt{tracingonline}}\label{Dtonline}.
+
+\subsection{Data Types}
+
+MetaPost actually has nine basic data types\index{types}: numeric,
+pair, path, transform,
+color, string, boolean, picture, and pen.  Let us consider these one at a time
+beginning with the numeric type.
+
+Numeric\index{numeric type} quantities in MetaPost are represented in fixed
+point arithmetic\index{arithmetic} as
+integer multiples of $1\over65536$.  They 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
+{\tt warningcheck}\index{warningcheck}\label{Dwarncheck} to zero
+suppresses the warning messages about large numeric quantities.
+
+The pair\index{pair type} type is represented as a pair of numeric quantities.
+We have seen that pairs
+are used to give coordinates in {\tt draw} statements.  Pairs can be added,
+subtracted, used in mediation expressions, or multiplied or divided by numerics.
+
+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 a lot like the pair type, except that it
+has three components
+instead of two.  Like pairs, colors can be added, subtracted, used in mediation
+expressions, or multiplied or divided by numerics.  Colors can be specified
+in terms of the predefined constants {\tt black}\index{black?\texttt{black}}\label{Dblack},
+{\tt white}\index{white?\texttt{white}}\label{Dwhite}, {\tt red}\index{red?\texttt{red}}\label{Dred},
+{\tt green}\index{green?\texttt{green}}\label{Dgreen},
+{\tt blue}\index{blue?\texttt{blue}}\label{Dblue}, or the red, green,
+and blue components can be given explicitly.  Black is {\tt (0,0,0)} and white
+is {\tt (1,1,1)}.  A level of gray such as {\tt (.4,.4,.4)} can be specified
+as {\tt 0.4white}.  There is no restriction against colors ``blacker
+than black'' or ``whiter than white'' except all components are snapped
+back to the $[0,1]$ range when a color is given in a PostScript\index{PostScript}
+output file.  MetaPost solves linear equations involving colors the same way it
+does for pairs.
+
+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.
+
+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 {\tt draw} 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 nine basic types, but
+most of the operations fit into a fairly simple syntax with four levels of
+precedence as shown in Figure~\ref{syexpr}.  There are
+primaries\index{primary?\tdescr{primary}}, secondaries\index{secondary?\tdescr{secondary}},
+tertiaries\index{tertiary?\tdescr{tertiary}}, and expressions\index{expression?\tdescr{expression}}
+of each of the basic types, so the syntax rules could
+be specialized to deal with items such as \tdescr{numeric primary},
+\tdescr{boolean tertiary}, etc.  This allows the result type for an operation
+to depend on the choice of operator and the types of its operands.  For example,
+the {\tt <} relation is a \tdescr{tertiary binary} that can be applied
+to a \tdescr{numeric expression} and a \tdescr{numeric tertiary} to give a
+\tdescr{boolean expression}.  The same operator can accept other operand types
+such as \tdescr{string expression} and \tdescr{string tertiary}, but an error
+message results if the operand types do not match.
+
+\begin{figure}[htp]
+\begin{ctabbing}
+$\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*y1 + x2*y2}.
+
+The additive operators {\tt +} and {\tt -}\label{Dadd} are
+\tdescr{secondary binops} that
+operate on numerics, pairs, or colors and produce results of the same type.
+Other operators that fall in this category are ``Pythagorean addition''
+\verb|++|\index{++?\texttt{++}}\label{Dpyadd} and
+``Pythagorean subtraction'' \verb|+-+|\index{+-+?\texttt{+-+}}\label{Dpysub}:
+\verb|a++b| means $\sqrt{a^2+b^2}$ and \verb|a+-+b| means $\sqrt{a^2-b^2}$.
+There are too many other operators to list here, but some of the most important
+are the boolean operators {\tt and}\index{and?\texttt{and}} and {\tt or}\index{or?\texttt{or}}.
+The {\tt and} operator is a
+\tdescr{primary binop} and the {\tt or} operator is a \tdescr{secondary binop}.
+
+The basic operations on strings are concatenation\index{concatenation} and
+substring construction.
+The \tdescr{tertiary binop} \verb|&|\index{&?\texttt{\&}}\label{Damp}
+implements concatenation; e.g.,
+$$ \hbox{\verb|"abc" & "de"|} $$
+produces the string \verb|"abcde"|.
+For substring construction, the
+\tdescr{of operator} {\tt substring}\index{substring of?\texttt{substring of}}\label{Dsubstr}
+is used like this:
+$$ {\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
+$$ \epsfbox{manfig.14} $$
+and {\tt substring (2,4) of "abcde"} is {\tt "cd"}.  This takes a little getting
+used to but it tends to avoid annoying ``off by one'' errors.
+
+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{primary binop} such as {\tt sqrt}\index{sqrt?\texttt{sqrt}}\label{Dsqrt}
+makes the difference clear:
+$$ \hbox{\tt sqrt 2/3} $$
+means $\sqrt{2\over3}$ while
+$$ \hbox{\tt sqrt(1+1)/3} $$
+means $\sqrt 2/3$.
+Operators such as {\tt sqrt} can be written in standard functional notation,
+but it is often unnecessary to parenthesize the argument.  This applies to any
+function that is parsed as a \tdescr{primary binop}.  For instance
+{\tt abs(x)}\index{abs?\texttt{abs}}\label{Dabs} and {\tt abs x} both compute the
+absolute value of {\tt x}.  The same holds for the
+{\tt round}\index{round?\texttt{round}}\label{Dround},
+{\tt floor}\index{floor?\texttt{floor}}\label{Dfloor},
+{\tt ceiling}\index{ceiling?\texttt{ceiling}}\label{Dceil},
+{\tt sind}\index{sind?\texttt{sind}}\label{Dsind},
+and {\tt cosd}\index{cosd?\texttt{cosd}}\label{Dcosd}
+functions.  The last two of these compute trigonometric functions of angles in
+degrees.
+
+Not all unary operators take numeric arguments and return numeric results.
+For instance, the {\tt abs}\index{abs?\texttt{abs}} operator can be applied to a pair
+to compute the Euclidean length of a vector.  Applying the
+{\tt unitvector}\index{unitvector?\texttt{unitvector}}\label{Duvec} operator to a pair produces
+the same pair rescaled so that its Euclidean length is~1.
+The {\tt decimal}\index{decimal?\texttt{decimal}}\label{Ddecop}
+operator takes a number and returns the string representation.
+The {\tt angle}\index{angle?\texttt{angle}}\label{Dangle}
+operator takes a pair and computes the two-argument arctangent; i.e., {\tt angle}
+is the inverse of the {\tt dir} operator that was discussed in
+Section~\ref{tenscurl}.  There is also an operator
+{\tt cycle}\index{cycle?\texttt{cycle}}\label{Dcycop}
+that takes a \tdescr{path primary} and returns a boolean result indicating whether
+the path is a closed curve.
+
+There is a whole class of other operators that classify expressions and return
+boolean results.  A type name such as {\tt pair}\index{pair?\texttt{pair}} can operate on
+any type of \tdescr{primary} and return a boolean result indicating whether the
+argument is a {\tt pair}\label{Dpairop}.  Similarly, each of the following can
+be used as a unary operator:
+{\tt numeric}\index{numeric?\texttt{numeric}}\label{Dnumop},
+{\tt boolean}\index{boolean?\texttt{boolean}}\label{Dboolop},
+{\tt color}\index{color?\texttt{color}}\label{Dcolrop},
+{\tt string}\index{string?\texttt{string}}\label{Dstrgop},
+{\tt transform}\index{transform?\texttt{transform}}\label{Dtrnfop},
+{\tt path}\index{path?\texttt{path}}\label{Dpathop},
+{\tt pen}\index{pen?\texttt{pen}}\label{Dpenop},
+and {\tt picture}\index{picture?\texttt{picture}}\label{Dpictop}.
+Besides just testing the type of a \tdescr{primary}, you can use the
+{\tt known}\index{known?\texttt{known}}\label{Dknown} and
+{\tt unknown}\index{unknown?\texttt{unknown}}\label{Dunknwn} operators to
+test if it has a completely known value.
+
+Even a number can behave like an operator in some contexts.
+This refers to the trick that allows {\tt 3x}\index{multiplication, implicit} and
+{\tt 3cm} as alternatives to {\tt 3*x} and {\tt 3*cm}.  The rule is that a
+\tdescr{number or fraction} that is not followed by {\tt +}, {\tt -}, or another
+\tdescr{number or fraction} can serve as a \tdescr{primary binop}.
+Thus {\tt 2/3x}\index{parsing irregularities}
+is two thirds of {\tt x} but {\tt (2)/3x} is $2\over3x$ and {\tt 3 3} is illegal.
+
+There are also operators for extracting numeric subfields from pairs, colors,
+and even transforms.  If {\tt p} is a \tdescr{pair primary},
+{\tt xpart p}\index{xpart?\texttt{xpart}}\label{Dxprt} and
+{\tt ypart p}\index{ypart}\label{Dyprt} extract its
+components so that
+$$ \hbox{\tt (xpart p, ypart p)} $$
+is equivalent to~{\tt p} even if {\tt p} is an unknown pair that is being used
+in a linear equation.  Similarly, a color {\tt c} is equivalent
+to\index{redpart?\texttt{redpart}}\index{greenpart?\texttt{greenpart}}\index{bluepart?\texttt{bluepart}}\label{Drgbprt}
+$$ \hbox{\tt (redpart c, greenpart c, bluepart c)} $$
+The part specifiers for transforms will be discussed later.
+
+
+\section{Variables}
+\label{vars}
+
+MetaPost allows compound variable names such as {x.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{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 eight types: numeric, path, transform, color, string, boolean, picture,
+and pen.  The only restriction is that you cannot give explicit numeric subscripts
+in a variable declaration.  Do not give the illegal declaration
+$$ \hbox{\tt numeric q1, q2, q3;} $$
+use the generic subscript\index{subscript!generic} symbol {\tt []}\index{[]?\texttt{[]}}
+instead, to declare the whole array:
+$$ \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 a list of symbolic tokens.  For example,
+$$ \hbox{\tt newinternal a, b, c;} $$
+causes {\tt a}, {\tt b}, and {\tt c} to behave like internal variables.  Such
+variables always have known numeric values, and these values can only be changed
+by using the assignment\index{assignment} operator {\tt:=}\index{:=?\texttt{:=}}.
+Internal variables are initially zero
+except that the Plain\index{Plain macros} macro package gives some of them nonzero
+initial values.  (The Plain macros are normally preloaded automatically as
+explained in Section~\ref{intro}.)
+
+
+\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{\epsfbox{manfig.17}}
+$$
+\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 exactly
+like the {\tt label} statement except that it adds a dot at the indicated
+coordinates.  For example
+$$ \hbox{\tt dotlabel.bot("(0,0)", z0)} $$
+places a dot at {\tt z0} and then puts the label ``(0,0)'' just below the dot.
+Another alternative is the macro
+{\tt thelabel}\index{thelabel?\texttt{thelabel}}\label{Dthelab}.  This has
+the same syntax as the {\tt label} and {\tt dotlabel} statements except that it
+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:="Times-Roman"} $$
+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;} $$
+
+When you change {\tt defaultfont}, the new font name should be something that
+\TeX\ would understand since MetaPost gets height and width information by reading
+the {\tt tfm}\index{tfm file?{\tt tfm} file}\index{files!tfm?{\tt tfm}} file.
+(This is explained in {\it The \TeX book\/}.~\cite{kn:a})
+It should be possible to use built-in PostScript fonts, but the names for them
+are system-dependent.  Some systems may use {\tt rptmr} or {\tt ps-times-roman}
+instead of {\tt Times-Roman}.
+A \TeX\index{TeX?\TeX} font such as {\tt cmr10} is a little dangerous because it does
+not have a space character or certain ASCII symbols.  In addition, MetaPost does
+not use the ligatures\index{ligatures} and kerning\index{kerning} information
+that comes with a \TeX\ font.
+
+
+\subsection{Typesetting Your Labels}
+
+\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{\epsfbox{manfig.18}}
+$$
+\caption{MetaPost code and the resulting output}
+\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{\epsfbox{manfig.19}}
+$$
+\caption{MetaPost code and the resulting output}
+\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.''
+
+Here is how \TeX\ material gets translated into a form MetaPost understands:
+The MetaPost processor skips over
+{\tt btex}\index{btex?\texttt{btex}} \ldots\ {\tt etex}\index{etex?\texttt{etex}} blocks
+and depends on a preprocessor to translate them into low level MetaPost
+commands.  If the main file is {\tt fig.mp}, the translated \TeX\
+material is placed in a file named {\tt fig.mpx}\index{files!mpx?{\tt mpx}}.
+This is normally
+done silently without any user intervention but it could fail if one of
+the {\tt btex} $\ldots$ {\tt etex} blocks contains an erroneous
+\TeX\index{TeX?\TeX!errors} command.  Then the erroneous \TeX\ input
+is saved in the file {\tt mpxerr.tex}\index{mpxerr.tex?\texttt{mpxerr.tex}} and the error
+messages appear in {\tt mpxerr.log}\index{mpxerr.log?\texttt{mpxerr.log}}.
+
+\TeX\ macro definitions or any other auxiliary
+\TeX\ commands can be enclosed in a
+{\tt verbatimtex}\index{verbatimtex?\texttt{verbatimtex}} \ldots\ {\tt etex}\index{etex?\texttt{etex}} block.
+The difference between
+{\tt btex} and {\tt verbatimtex} is that the former generates a picture
+expression while the latter only adds material for \TeX\ to process.
+For instance, if you want \TeX\ to typeset labels using macros defined in
+{\tt mymac.tex}, your MetaPost input file would look something like this:
+\begin{eqnarray*}
+&& \verb|verbatimtex \input mymac etex|\\
+&& \verb|beginfig(1);|\\
+&& \qquad \vdots\\
+&& \verb|label(btex|\, \descr{\TeX\ material using \hbox{\tt mymac.tex}}\,
+        \verb|etex, | \descr{some coordinates} \hbox{\tt );}\\
+&& \qquad \vdots
+\end{eqnarray*}
+
+On Unix\footnote{Unix is a registered trademark of Unix Systems
+Laboratories.}\index{Unix\reg}
+systems, an environment variable can be used to specify that
+{\tt btex} $\ldots$ {\tt etex} and {\tt verbatimtex} $\ldots$ {\tt etex}
+blocks are in troff\index{troff} instead of \TeX.  When using this option,
+it is a good idea to start your MetaPost input file with the assignment
+{\tt prologues:=1}\index{prologues?\texttt{prologues}}\label{Dprologs}.  Giving this
+internal variable\index{internal variables}\index{variables!internal}
+a positive value causes causes output to be formatted as
+``structured PostScript''\index{PostScript!structured} generated on the
+assumption that text comes from built-in PostScript fonts.  This makes MetaPost
+output much more portable, but it has an important drawback:  It generally
+does not work when you use \TeX\ fonts, since programs that translate \TeX\
+output into PostScript\index{PostScript} need to make special provisions for
+\TeX\index{TeX?\TeX!fonts} fonts in
+included figures and the standard PostScript structuring rules do not allow
+for this.  The details on how to include PostScript figures in a paper done
+in \TeX\ or troff are system-dependent.  They can generally be found in
+manual pages and other on-line documentation.  A file called {\tt dvips.tex}
+is distributed electronically along with the dvips\index{dvips} \TeX\ output
+processor.
+
+
+\subsection{The {\tt infont} operator}
+\label{Sinfont}
+
+Regardless of whether you use \TeX\ or troff, all the real work of adding
+text to pictures is done by a MetaPost primitive operator called
+{\tt infont}\index{infont?\texttt{infont}}.  It is a
+\tdescr{primary binop}\index{primary binop?\tdescr{primary binop}} that takes a
+\tdescr{string secondary} as its
+left argument and a \tdescr{string primary} as its right argument.  The left
+argument is text, and the right argument is a font name.
+The result of the operation is a \tdescr{picture secondary} that can then be
+transformed in various ways.  One possibility is enlargement by a given factor
+via the syntax\index{scaled?\texttt{scaled}}
+$$ \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 "Times-Roman"} $$
+is a picture containing character {\tt n+64} of the Times-Roman font.
+
+\subsection{Measuring Text}
+\label{meas}
+
+MetaPost makes readily available the physical dimensions\index{size}
+of pictures generated by the {\tt infont} operator.  There are
+unary operators {\tt llcorner}\index{llcorner?\texttt{llcorner}}\label{Dcornop},
+{\tt lrcorner}\index{lrcorner?\texttt{lrcorner}}, {\tt urcorner}\index{urcorner?\texttt{urcorner}},
+{\tt ulcorner}\index{ulcorner?\texttt{ulcorner}}, and {\tt center}\index{center}\label{Dcenter}
+that take a \tdescr{picture primary} and return the corners of its ``bounding
+box'' as illustrated in Figure~\ref{bbox}.  The {\tt center} operator also
+accepts \tdescr{path primary} and \tdescr{pen primary} operands.
+In MetaPost Version 0.30 and higher, {\tt llcorner}, {\tt lrcorner}, etc.
+accept all three argument types as well.
+
+The argument type restrictions on the corner operators are not very important
+because their main purpose is to allow {\tt label} and {\tt dotlabel} statements
+to center their text properly.
+The predefined macro\index{bbox?\texttt{bbox}}\label{Dbbox}
+$$ {\tt bbox}\, \descr{picture primary} $$
+finds a rectangular path that represents the bounding box of a given picture.
+If {\tt p} is a picture, {\tt bbox p} equivalent to
+$$ \hbox{\tt (llcorner p--lrcorner p--urcorner p--ulcorner p--cycle)} $$
+except that it allows for a small amount of extra space around {\tt p} as specified
+by the internal variable\index{internal variables}\index{variables!internal}
+{\tt bboxmargin}\index{bboxmargin?\texttt{bboxmargin}}\label{Dbbmargin}.
+
+\begin{figure}[htp]
+$$ \epsfbox{manfig.20} $$
+\caption{A bounding box and its corner points.}
+\label{bbox}
+\end{figure}
+
+Note that MetaPost computes the bounding box of a {\tt btex}\index{btex?\texttt{btex}}
+\ldots\ {\tt etex}\index{etex?\texttt{etex}} picture just the way \TeX\index{TeX?\TeX} does.
+This is quite natural, but it has certain implications in view of the fact that
+\TeX\ has features like {\tt\string\strut}\index{strut?{\tt\string\strut}} and
+{\tt\string\rlap}\index{rlap?{\tt\string\rlap}} that allow \TeX\ users to lie about the
+dimensions of a box.
+
+When \TeX\ commands that lie about the dimensions of a box are translated in to
+low-level MetaPost code, a {\tt setbounds}\index{setbounds?\texttt{setbounds}}\label{Dsetbnd}
+statement does the lying:\index{picture variable?\tdescr{picture variable}}
+$$ {\tt setbounds}\, \descr{picture variable}\, {\tt to}\, \descr{path expression}
+$$
+makes the \tdescr{picture variable} behave as if its bounding box were the same
+as the given path.  To get the true bounding box of such a picture, assign a
+positive value to the
+internal variable\index{internal variables}\index{variables!internal}
+{\tt truecorners}\index{truecorners?\texttt{truecorners}}\label{Dtruecorn}:\footnote{The
+{\tt setbounds} and
+{\tt truecorners} features are only found in MetaPost version 0.30 and higher.}
+i.e.,
+$$ \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 {\tt ..cycle} or {\tt --cycle} notation.  For example, the {\tt fill}
+statement in Figure~\ref{fig20} builds a closed path by extending the roughly
+semicircular path~{\tt p}.
+This path has a counter-clockwise orientation, but that does not matter because
+the {\tt fill} statement uses PostScript's\index{PostScript} non-zero
+winding\index{winding number} number rule~\cite{ad:red}.
+
+\begin{figure}[htp]
+$$ \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{\epsfbox{manfig.21}}
+$$
+\caption{MetaPost code and the corresponding output.}
+\label{fig20}
+\end{figure}
+
+The general {\tt fill} statement\index{withcolor?\texttt{withcolor}}
+$$ {\tt fill}\, \descr{path expression}\,
+        {\tt withcolor}\, \descr{color expression}
+$$
+specifies a shade of gray or (if you have a color printer) some
+rainbow color.
+
+Figure~\ref{fig21} illustrates several applications of the fill command to fill
+areas with shades of gray.  The paths involved are intersecting circles {\tt a}
+and {\tt b} and a path {\tt ab} that bounds the region inside both circles.
+Circles {\tt a} and {\tt b} are derived from a predefined path
+{\tt fullcircle}\index{fullcircle?\texttt{fullcircle}}\label{Dfcirc}
+that approximates a circle of unit diameter centered on the origin.  There is
+also a predefined path {\tt halfcircle}\index{halfcircle?\texttt{halfcircle}}\label{Dhcirc}
+that is the part
+of {\tt fullcircle} above the $x$ axis. Path~{\tt ab} is the initialized
+using a predefined macro {\tt buildcycle} that will be discussed shortly.
+
+\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{\epsfbox{manfig.22}}
+$$
+\caption{MetaPost code and the corresponding output.}
+\index{fullcircle?\texttt{fullcircle}}\index{halfcircle?\texttt{halfcircle}}\index{buildcycle?\texttt{buildcycle}}
+\label{fig21}
+\end{figure}
+
+Filling circle {\tt a} with the light gray color {\tt .7white} and then doing the
+same with circle {\tt b} doubly fills the region where the disks overlap.  The
+rule is that each {\tt fill} statement assigns the given color to all points in
+the region covered, wiping out whatever was there previously including lines and
+text as well as filled regions.  Thus it is important to give {\tt fill} commands
+in the right order.
+In the above example, the overlap region gets the same color twice,
+leaving it light gray after the first two {\tt fill} statements.  The third fill
+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 pieces of paths {\tt aa} and {\tt b}.
+The {\tt buildcycle} macro detects the two intersections\index{intersections}
+labeled 1 and 2 in
+Figure~\ref{fig22}b.  Then it constructs the cyclic path shown in bold in the
+figure by going forward along path {\tt aa} from intersection~1 to
+intersection~2 and then forward around the counter-clockwise path {\tt b} back to
+intersection~1.  It turns out that {\tt buildcycle(a,b)} would have produced the
+same result, but the reasoning behind this is a little confusing.
+
+
+\begin{figure}[htp]
+$$ {\epsfbox{manfig.123} \atop (a)}
+ \qquad {\epsfbox{manfig.223} \atop (b)}
+$$
+\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{\epsfbox{manfig.24}}
+$$
+\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 {\it The \MF book}.\cite[Chapter 14]{kn:c})
+
+\begin{figure}[htp]
+$$ \epsfbox{manfig.25} $$
+\caption{Two intersecting paths with time values marked on each path.}
+\label{fig24}
+\end{figure}
+
+The {\tt intersectiontimes} operator is more flexible than {\tt intersectionpoint}
+because there are a number of things that can be done with time values on a path.
+One of the most important is just to ask ``where is path {\tt p} at
+time {\tt t}?''  The construction\index{point of?\texttt{point of}}\label{Dpntof}
+$$ {\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$.
+
+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 \epsfbox{manfig.26}
+$$
+\caption{MetaPost code and the resulting figure}
+\label{fig25}
+\end{figure}
+
+If you know a slope and you want to find a point on a curve where the tangent
+line has that slope,
+the {\tt directiontime}\index{directiontime of?\texttt{directiontime of}}\label{Ddtimof}
+operator inverts the {\tt direction
+of} operation.  Given a direction vector and a path,
+$$ {\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 is related to the more familiar concept of
+arc length.\index{arc length}\footnote{The
+{\tt arclength} and {\tt arctime} operators are only found in MetaPost
+version 0.50 and higher.}
+The expression
+$$ \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}. $$
+
+\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 $45^\circ$,
+and shifting by $(1,1)$.''  This works because {\tt identity} is the identity
+transformation which does nothing; i.e., {\tt transformed identity} is a no-op.
+
+The syntax for transform expressions and transformation operators is given in
+Figure~\ref{sytrans}.  It includes two more options for
+\tdescr{transformer}:\index{reflectedabout?\texttt{reflectedabout}}
+$$ \hbox{\tt reflectededabout(}p, q\hbox{\tt )} $$
+reflects about the line defined by points $p$ and $q$; and\index{rotatedaround?\texttt{rotatedaround}}
+$$ \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{\epsfbox{manfig.28}}
+$$
+\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}}
+$$ {\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]
+$$ \epsfbox{manfig.29} $$
+\caption[Dashed lines and the corresponding dash patters]
+        {Dashed lines each labeled with the \tdescr{dash pattern} used to create
+        it.}
+\label{fig28}
+\end{figure}
+
+Another way to change a dash pattern is to alter its phase by shifting it
+horizontally.  Shifting to the right makes the dashes move forward along the
+path and shifting to the left moves them backward.  Figure~\ref{fig29} illustrates
+this effect.  The dash pattern can be thought of as an infinitely repeating pattern
+strung out along a horizontal line where the portion of the line to the right of
+the $y$~axis is laid out along the path to be dashed\index{dash pattern?\tdescr{dash pattern}}.
+
+\begin{figure}[htp]
+$$ \epsfbox{manfig.30} $$
+\caption[Dashed lines and the corresponding dash patters]
+        {Dashed lines and the MetaPost statements for drawing them where {\tt e4}
+        refers to the dash pattern {\tt evenly scaled 4}.}
+\label{fig29}
+\end{figure}
+
+When you shift a dash pattern so that the $y$~axis crosses the middle of a dash,
+the first dash gets truncated.  Thus the line with dash pattern {\tt e4} starts
+with a dash of length 12bp followed by a 12bp gap and another 12bp dash, etc.,
+while {\tt e4 shifted (-6bp,0)} produces a 6bp dash, a 12 bp gap, then a
+12bp dash, etc.  This dash pattern could be specified more directly via the
+{\tt dashpattern}\index{dash pattern?\texttt{dash pattern}}\label{Ddshpat} function:
+$$ \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:
+$$ \epsfbox{manfig.31} $$
+The lines in this example are specified as having width zero, but this does not
+matter because the line width is ignored when a picture is used as a dash pattern.
+
+The general rule for interpreting a picture {\tt d} as a dash pattern is that
+the line segments in {\tt d} are projected onto the $x$-axis and the resulting
+pattern is replicated to infinity in both directions by placing copies of the
+pattern end-to-end.  The actual dash lengths are obtained by starting at $x=0$
+and scanning in the positive $x$ direction.
+
+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{\epsfbox{manfig.32}}
+$$
+\caption{MetaPost code and the corresponding output}
+\label{fig32}
+\end{figure}
+
+
+\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{\epsfbox{manfig.33}}
+$$
+\caption{MetaPost code and the corresponding output}
+\label{fig33}
+\end{figure}
+
+Another parameter borrowed from PostScript affects the way a {\tt draw} statement
+treats sharp corners\index{corners} in the path to be drawn.
+The {\tt linejoin}\index{linejoin?\texttt{linejoin}}\label{Dlinejoin} parameter can
+be {\tt rounded}\index{rounded?\texttt{rounded}}\label{Drnded},
+{\tt beveled}\index{beveled?\texttt{beveled}}\label{Dbvled},
+or {\tt mitered}\index{mitered?\texttt{mitered}}\label{Dmitred} as shown in Figure~\ref{fig34}.
+The default value for plain MetaPost is {\tt rounded} which gives the effect of
+drawing with a circular brush.
+
+\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{\epsfbox{manfig.34}}
+$$
+\caption{MetaPost code and the corresponding output}
+\label{fig34}
+\end{figure}
+
+When {\tt linejoin} is {\tt mitered}, sharp corners generate long pointed features
+as shown in Figure~\ref{fig35}.  Since this might be undesirable, there is an
+internal variable\index{internal variables}\index{variables!internal}
+called {\tt miterlimit}\index{miterlimit?\texttt{miterlimit}}\label{Dmiterlim} that controls how
+extreme the situation can get before the mitered join is replaced by a beveled
+join.  For Plain MetaPost, {\tt miterlimit} has a default value of 10.0 and line
+joins revert to beveled when the ratio of miter length to line width
+reaches this value.
+
+\begin{figure}[htp]
+$$ \epsfbox{manfig.35} $$
+\caption{The miter length and line width whose ratio is limited by
+        {\tt miterlimit}.}
+\label{fig35}
+\end{figure}
+
+The {\tt linecap}, {\tt linejoin}, and {\tt miterlimit} parameters are especially
+important because they also affect things that get drawn behind the scenes.
+For instance, Plain MetaPost has statements for drawing
+arrows\index{arrows}, and the arrowheads are slightly rounded when {\tt linejoin}
+is {\tt rounded}.  The effect depends on the line width and is quite subtle at the
+default line width of 0.5bp as shown in Figure~\ref{fig36}.
+
+\begin{figure}[htp]
+$$\epsfbox{manfig.36}$$
+\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]
+$$ \epsfbox{manfig.37} $$
+\caption[A large arrowhead with key parameters labeled.]
+        {A large arrowhead with key parameters labeled and paths used to
+        draw it marked with white lines.}
+\label{fig37}
+\end{figure}
+
+The arrowhead is created by filling the triangular region that is outlined
+in white in Figure~\ref{fig37} and then drawing around it with the currently
+picked up pen.  This combination of filling and drawing can be combined into
+a single {\tt filldraw} statement\index{filldraw?\texttt{filldraw}}\label{Dfildrw}:
+$$ {\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}
+
+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{\epsfbox{manfig.38}}
+$$
+\caption{MetaPost code and the resulting ``calligraphic'' figure.}
+\label{fig38}\index{lft?\texttt{lft}}\index{bot?\texttt{bot}}\index{top?\texttt{top}}
+\end{figure}
+
+Figure~\ref{fig38} demonstrates operators {\tt lft}\index{lft?\texttt{lft}}\label{Dlft},
+{\tt rt}\index{rt?\texttt{rt}}\label{Drt}, {\tt top}\index{top?\texttt{top}}\label{Dtop},
+and {\tt bot}\index{bot?\texttt{bot}}\label{Dbot}
+that answer the question, ``If the current pen is placed at the position
+given by the argument, where will its left, right, top, or bottom edge be?''
+In this case the current pen is the ellipse given in the {\tt pickup} statement
+and its bounding box is 0.1734 inches wide and 0.1010 inches high, so
+{\tt rt x3} is ${\tt x3}+{\tt 0.0867in}$ and {\tt bot y5} is
+${\tt y5}-{\tt 0.0505in}$.
+The {\tt lft}, {\tt rt}, {\tt top}, and {\tt bot} operators also accept arguments
+of type pair in which case they compute the $x$ and~$y$ coordinates of the
+leftmost, rightmost, topmost, or bottommost point on the pen shape.  For example,
+$$ {\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{\tt makepen((-.5,-.5)--(.5,-.5)--(.5,.5)--(-.5,.5)--cycle)} $$
+
+The inverse of {\tt makepen} is the
+{\tt makepath}\index{makepath?\texttt{makepath}}\label{Dmkpath} operator
+that takes a \tdescr{pen primary} and returns the corresponding path.  Thus
+{\tt makepath pencircle} produces a circular path identical to
+{\tt fullcircle}\index{fullcircle?\texttt{fullcircle}}.  This also works for a polygonal pen
+so that
+$$ {\tt 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 \;|\; 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{\epsfbox{manfig.40}}
+$$
+\caption{MetaPost code and the resulting ``clipped'' figure.}
+\label{fig40}
+\end{figure}
+
+All the primitive drawing operations would be useless without one last operation
+called {\tt shipout}.  The statement\index{shipout?\texttt{shipout}}\label{Dship}
+$$ {\tt shipout}\, \descr{picture expression} $$
+This writes out a picture as a PostScript\index{PostScript} file whose name ends
+{\tt.}{\it nnn}, where {\tt nnn} is the decimal representation of the value of
+the internal variable\index{internal variables}\index{variables!internal}
+{\tt charcode}\index{charcode?\texttt{charcode}}\label{Dcharcode}.
+(The name ``{\tt charcode}'' is for compatibility with \MF\index{metafont?\MF}.)
+Normally, {\tt beginfig}\index{beginfig?\texttt{beginfig}} sets {\tt charcode}, and
+{\tt endfig}\index{endfig?\texttt{endfig}} invokes {\tt shipout}.
+
+\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} 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}
+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{\tt >> \%CAPSULE}{\it nnnn} $$
+where {\it nnnn} is an identification number that is chosen when {\tt save}
+makes the name question mark disappear.
+
+In spite of the versatility of {\tt save}, it cannot be used to make local changes
+to any of MetaPost's
+internal variables\index{internal variables}\index{variables!internal}.
+A statement such as\index{linecap?\texttt{linecap}}
+$$ \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}
+$$
+
+
+\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{midpoint?\texttt{midpoint}} macro with type test looks like this:
+$$\begin{verbatim}
+def middlepoint(expr a) = if path a: (point .5*length a of a)
+  else: .5(llcorner a + urcorner a) fi enddef;
+\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 midpoint} like this:
+$$\begin{verbatim}
+def midpoint(expr a) = if path a: (point .5*length a of
+  else: .5(llcorner a + urcorner fi  a) enddef;
+\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{\epsfbox{manfig.42}}
+$$
+\caption{MetaPost code and the corresponding figure}
+\label{fig42}
+\end{figure}
+
+The task of the \verb|draw_marked|\index{draw_marked?\texttt{draw\_marked}} macro is to draw a path
+with a given number of cross marks near its midpoint.  A convenient starting place
+is the subproblem of drawing a single cross mark perpendicular to a path {\tt p}
+at some time {\tt t}. The \verb|draw_mark|\index{draw_mark?\texttt{draw\_mark}} macro in
+Figure~\ref{drawmarked} does this by first finding a vector {\tt dm} perpendicular
+to~{\tt p} at~{\tt t}.  To simplify positioning the cross mark,
+the \verb|draw_marked| macro is defined to take an arc length\index{arc length}
+{\tt a} along {\tt p} and use the {\tt arctime}\index{arctime} operator to
+compute~{\tt t}
+
+With the subproblem of drawing a single mark out of the way, the \verb|draw_marked|
+macro only needs to draw the path and call \verb|draw_mark| with the appropriate
+arc length values.  The \verb|draw_marked| macro in Figure~\ref{drawmarked}
+uses {\tt n} equally-spaced {\tt a} values centered on
+{\tt .5*arclength~p}\index{arclength?\texttt{arclength}}.
+
+\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{\epsfbox{manfig.45}}
+$$
+\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{[]}}.
+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 i}<0$.
+
+It is best to use this feature only when the step size is an integer or some
+number that can be represented exactly in fixed point arithmetic\index{arithmetic}
+as a multiple of $1\over65536$.  Otherwise, error will accumulate and the loop
+index might not reach the expected termination value.  For instance,
+$$ \hbox{\tt for i=0 step .1 until 1: show i; endfor} $$
+shows ten {\tt i} values the last of which is 0.90005.
+
+The standard way of avoid the problems associated with non-integer step sizes is
+to iterate over integer values and then multiply by a scale factor when using
+the loop index as was done in Figures \ref{fig1} and~\ref{fig40}.
+
+Alternatively, the values to iterate over can be given explicitly.  Any sequence
+of zero or more expressions separated by commas can be used in place of
+{\tt a step b upto c}.  In fact, the expressions need not all be the same type
+and they need not have known values.  Thus
+$$ \hbox{\tt for t=3.14, 2.78, (a,2a), "hello": show a; endfor} $$
+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{\tt draw for p=(3,1),(6,2),(7,5),(4,6),(1,3): p-- endfor cycle;} $$
+is equivalent to
+$$ \hbox{\tt draw (3,1)--(6,2)--(7,5)--(4,6)--(1,3)--cycle;} $$
+(See Figure~\ref{fig17} for a more realistic example of this.)
+
+If a loop is like a macro definition, the loop index is like an
+expr parameter\index{parameter!expr}.  It can represent any value, but it is
+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{Making Boxes}
+\label{boxessec}
+
+This section describes auxiliary macros not included in Plain MetaPost that
+make it convenient to do things that {\it pic} is good at \cite{ke:pic}.  What
+follows is a description of how to use the macros contained in the
+file {\tt boxes.mp}\index{boxes.mp?\texttt{boxes.mp}}.  This file is included in a special
+directory reserved for MetaPost macros and support software\footnote{The name
+of this directory is likely to be something like \verb|/usr/lib/mp/lib|, but
+this is system dependent.}
+and can be accessed by giving the MetaPost command {\tt input boxes} before any
+figures that use the box making macros.
+The syntax for the {\tt input} command is \index{input?\texttt{input}}
+$$ {\tt input}\, \descr{file name} $$
+where a final ``{\tt .mp}'' can be omitted from the file name.  The {\tt input}
+command looks first in the current directory and then in the special macro
+directory.  Users interested in writing macros may want to look at the
+{\tt boxes.mp} file in this directory.
+
+\subsection{Rectangular Boxes}
+
+The main idea of the box-making macros is that one should
+say\index{boxit?\texttt{boxit}}\label{Dboxit}
+$$ {\tt boxit.} \descr{suffix}
+   \hbox{\tt(} \descr{picture expression} \hbox{\tt)}
+$$
+where the \tdescr{suffix} does not start with a subscript.\footnote{Some early
+versions of the box making macros did not allow any subscripts in the
+{\tt boxit} suffix.}
+This creates pair variables \tdescr{suffix}{\tt.c},
+\tdescr{suffix}{\tt.n}, \tdescr{suffix}{\tt.e}, \ldots\ that can then be
+used for positioning the picture before drawing it with a separate command such
+as\index{drawboxed?\texttt{drawboxed}}\label{Ddrbxed}
+$$ \hbox{\tt drawboxed(} \descr{suffix list} \hbox{\tt )} $$
+The argument to {\tt drawboxed} should be a comma-separated list of box names,
+where a box name\index{box name} is a \tdescr{suffix} with which {\tt boxit}
+has been called.
+
+For the command {\tt boxit.bb(pic)}, the box name is {\tt bb} and the contents
+of the box is the picture {\tt pic}.  In this case, {\tt bb.c} the position
+where the center of picture {\tt pic} is to be placed, and {\tt bb.sw},
+{\tt bb.se}, {\tt bb.ne}, and {\tt bb.nw} are the corners of a rectangular path
+that will surround the resulting picture.  Variables {\tt bb.dx} and {\tt bb.dy}
+give the spacing between the shifted version of {\tt pic} and the surrounding
+rectangle, and {\tt bb.off} is the amount by which {\tt pic} has to be shifted
+to achieve all this.
+
+When the {\tt boxit} macro is called with box name~$b$, it gives linear equations
+that force $b${\tt.sw}, $b${\tt.se}, $b${\tt.ne}, and $b${\tt.nw} to be the
+corners of a rectangle
+aligned on the $x$ and $y$ axes with the box contents centered inside as
+indicated by the gray rectangle in Figure~\ref{fig48}.  The values of $b${\tt.dx},
+$b${\tt.dy}, and $b${\tt.c} are left unspecified so that the user can give
+equations for positioning the boxes.  If no such equations are given, macros
+such as {\tt drawboxed} can detect this and give default values.
+The default values for {\tt dx} and {\tt dy} variables are controlled by the
+internal variables\index{internal variables}\index{variables!internal}
+{\tt defaultdx}\index{defaultdx?\texttt{defaultdx}}\label{Ddefaultdx} and
+{\tt defaultdy}\index{defaultdy?\texttt{defaultdy}}\label{Ddefaultdy}.
+
+\begin{figure}[htp]
+$$ \epsfbox{manfig.48} $$
+\caption[How a {\tt boxit} picture relates to the associated variables]
+        {The relationship between the picture given to {\tt boxit} and the
+        associated variables.  The picture is indicated by a gray rectangle.}
+\label{fig48}
+\end{figure}
+
+If $b$ represents a box name, {\tt drawboxed($b$)} draws the rectangular boundary
+of box~$b$ and then the contents of the box.  This bounding rectangle can be
+accessed separately as {\tt bpath~b}, or in general\index{bpath?\texttt{bpath}}\label{Dbpath}
+$$ {\tt bpath}\, \descr{box name} $$
+It is useful in combination with operators like
+{\tt cutbefore}\index{cutbefore?\texttt{cutbefore}} and {\tt cutafter}\index{cutafter?\texttt{cutafter}}
+in order to control paths that enter the box.
+For example, if $a$ and $b$ are box names and $p$ is a path from $a${\tt.c}
+to $b${\tt.c},\index{drawarrow?\texttt{drawarrow}}
+$$ \hbox{\tt drawarrow $p$ cutbefore bpath $a$ cutafter bpath $b$} $$
+draws an arrow from the edge of box $a$ to the edge of box $b$.
+
+Figure~\ref{fig49} shows a practical example including some arrows drawn with
+{\tt cutafter bpath} \tdescr{box name}.  It is
+instructive to compare Figure~\ref{fig49} to the similar figure in the pic
+manual \cite{ke:pic}.  The figure uses a macro\index{boxjoin?\texttt{boxjoin}}\label{Dbxjoin}
+$$ \hbox{\tt boxjoin(} \descr{equation text} \hbox{\tt )} $$
+to control the relationship between consecutive boxes.  Within the
+\tdescr{equation text}, {\tt a} and {\tt b} represent the box names given in
+consecutive calls to {\tt boxit} and the \tdescr{equation text} gives equations
+to control the relative sizes and positions of the boxes.
+
+\begin{figure}[htp]
+$$\hbox{$\begin{verbatim}
+input boxes
+beginfig(49);
+boxjoin(a.se=b.sw; a.ne=b.nw);
+boxit.a(btex\strut$\cdots$ etex);    boxit.ni(btex\strut$n_i$ etex);
+boxit.di(btex\strut$d_i$ etex);      boxit.ni1(btex\strut$n_{i+1}$ etex);
+boxit.di1(btex\strut$d_{i+1}$ etex); boxit.aa(btex\strut$\cdots$ etex);
+boxit.nk(btex\strut$n_k$ etex);      boxit.dk(btex\strut$d_k$ etex);
+drawboxed(di,a,ni,ni1,di1,aa,nk,dk); label.lft("ndtable:", a.w);
+interim defaultdy:=7bp;
+boxjoin(a.sw=b.nw; a.se=b.ne);
+boxit.ba(); boxit.bb(); boxit.bc();
+boxit.bd(btex $\vdots$ etex); boxit.be(); boxit.bf();
+bd.dx=8bp; ba.ne=a.sw-(15bp,10bp);
+drawboxed(ba,bb,bc,bd,be,bf); label.lft("hashtab:",ba.w);
+vardef ndblock suffix $ =
+  boxjoin(a.sw=b.nw; a.se=b.ne);
+  forsuffixes $$=$1,$2,$3: boxit$$(); ($$dx,$$dy)=(5.5bp,4bp);
+  endfor; enddef;
+ndblock nda;  ndblock ndb;  ndblock ndc;
+nda1.c-bb.c = ndb1.c-nda3.c = (whatever,0);
+xpart ndb3.se = xpart ndc1.ne = xpart di.c;
+ndc1.c - be.c = (whatever,0);
+drawboxed(nda1,nda2,nda3, ndb1,ndb2,ndb3, ndc1,ndc2,ndc3);
+drawarrow bb.c -- nda1.w;
+drawarrow be.c -- ndc1.w;
+drawarrow nda3.c -- ndb1.w;
+drawarrow nda1.c{right}..{curl0}ni.c cutafter bpath ni;
+drawarrow nda2.c{right}..{curl0}di.c cutafter bpath di;
+drawarrow ndc1.c{right}..{curl0}ni1.c cutafter bpath ni1;
+drawarrow ndc2.c{right}..{curl0}di1.c cutafter bpath di1;
+drawarrow ndb1.c{right}..nk.c cutafter bpath nk;
+drawarrow ndb2.c{right}..dk.c cutafter bpath dk;
+x.ptr=xpart aa.c;   y.ptr=ypart ndc1.ne;
+drawarrow subpath (0,.7) of (z.ptr..{left}ndc3.c) dashed evenly;
+label.rt(btex \strut ndblock etex, z.ptr); endfig;
+\end{verbatim}
+$}
+\atop \vcenter{\vskip8pt\hbox{\epsfbox{manfig.49}}}
+$$
+\caption{MetaPost code and the corresponding figure}
+\label{fig49}
+\end{figure}
+
+For example, the second line of input for the above figure contains
+$$ \hbox{\tt boxjoin(a.se=b.sw; a.ne=b.nw)} $$
+This causes boxes to line up horizontally by giving additional equations that
+are invoked each time some box {\tt a} is followed by some other box~{\tt b}.
+These equations are first invoked on the next line when box~{\tt a} is followed
+by box~{\tt ni}.  This yields
+$$ \hbox{\tt a.se=ni.sw; a.ne=ni.nw} $$
+The next pair of boxes is box~{\tt ni} and box~{\tt di}. This time the
+implicitly generated equations are
+$$ \hbox{\tt ni.se=di.sw; ni.ne=di.nw} $$
+This process continues until a new {\tt boxjoin}\index{boxjoin?\texttt{boxjoin}} is given.
+In this case the new declaration is
+$$ \hbox{\tt boxjoin(a.sw=b.nw; a.se=b.ne)} $$
+which causes boxes to be stacked below each other.
+
+After calling {\tt boxit} for the first eight boxes {\tt a} through {\tt dk},
+the box heights are constrained to match but the widths are still unknown.
+Thus the {\tt drawboxed}\index{drawboxed?\texttt{drawboxed}} macro needs to assign default
+values to the \tdescr{box name}{\tt.dx} and \tdescr{box name}{\tt.dy}
+variables.  First, {\tt di.dx} and {\tt di.dy} get default values so that all
+the boxes are forced to be large enough to contain the contents of box~{\tt di}.
+
+The macro that actually assigns default values to {\tt dx} and {\tt dy} variables
+is called {\tt fixsize}\index{fixsize?\texttt{fixsize}}\label{Dfixsiz}.
+It takes a list of box names and
+considers them one at a time, making sure that each box has a fixed size and
+shape.  A macro called {\tt fixpos}\index{fixpos?\texttt{fixpos}}\label{Dfixpos} then takes
+this same list
+of box names and assigns default values to the \tdescr{box name}{\tt.off}
+variables as needed to fix the position of each box.  By using {\tt fixsize}
+to fix the dimensions of each box before assigning default positions to any
+of them, the number of needing default positions can usually be cut to at most
+one.
+
+Since the bounding path for a box cannot be computed until the size, shape, and
+position of the box is determined, the {\tt bpath}\index{bpath?\texttt{bpath}} macro applies
+{\tt fixsize} and {\tt fixpos} to its argument.  Other macros that do this
+include\index{pic?\texttt{pic}}\label{Dpic}
+$$ {\tt pic}\, \descr{box name} $$
+where the \tdescr{box name} is a suffix, possibly in parentheses.  This returns
+the contents of the named box as a picture positioned so that
+$$ {\tt draw\ pic} \descr{box name} $$
+draws the box contents without the bounding rectangle.  This operation can also
+be accomplished by the {\tt drawunboxed}\index{drawunboxed?\texttt{drawunboxed}}\label{Ddrunbx}
+macro that takes a comma-separated list of box names.  There is also a
+{\tt drawboxes}\index{drawboxes?\texttt{drawboxes}}\label{Ddrbxes} macro that draws just the
+bounding rectangles.
+
+Another way to draw empty rectangles is by just saying\label{Deboxit}
+$$ {\tt boxit} \descr{box name} \hbox{\tt ()} $$
+with no picture argument as is done several times in Figure~\ref{fig49}.
+This is like calling {\tt boxit} with an empty picture.
+Alternatively the argument can be a string\label{Dsboxit} expression
+instead of a picture
+expression in which case the string is typeset in the default font.
+
+
+\subsection{Circular and Oval Boxes}
+
+Circular and oval boxes are a lot like rectangular boxes except for the shape
+of the bounding path.  Such boxes are set up by the
+{\tt circleit}\index{circleit?\texttt{circleit}}\label{Dcircit} macro:
+$$ {\tt circleit} \descr{box name}
+   \hbox{\tt(} \descr{box contents} \hbox{\tt)}
+$$
+where \tdescr{box name} is a suffix and \tdescr{box contents} is either a
+picture expression, a string expression, or \tdescr{empty}.
+
+The {\tt circleit} macro defines pair variable just as {\tt boxit} does, except
+that there are no corner points \tdescr{box name}{\tt.ne},
+\tdescr{box name}{\tt.sw}, etc.  A call to
+$$ \hbox{\tt circleit.a(}\ldots \hbox{\tt )} $$
+gives relationships among points {\tt a.c}, {\tt a.s},
+{\tt a.e}, {\tt a.n}, {\tt a.w}
+and distances {\tt a.dx} and {\tt a.dy}.  Together with {\tt a.c} and {\tt a.off},
+these variables describe how the picture is centered in an oval as can be seen
+from the Figure~\ref{fig50}.
+
+\begin{figure}[htp]
+$$ \epsfbox{manfig.50} $$
+\caption[How a {\tt circleit} picture relates to the associated variables]
+        {The relationship between the picture given to {\tt circleit} and the
+        associated variables.  The picture is indicated by a gray rectangle.}
+\label{fig50}
+\end{figure}
+
+The {\tt drawboxed}\index{drawboxed?\texttt{drawboxed}}, {\tt drawunboxed}\index{drawunboxed?\texttt{drawunboxed}},
+{\tt drawboxes}\index{drawboxes?\texttt{drawboxes}}, {\tt pic}\index{pic?\texttt{pic}}, and
+{\tt bpath}\index{bpath?\texttt{bpath}} macros work for {\tt circleit} boxes just as they do
+for {\tt boxit} boxes.  By default, the boundary path for a {\tt circleit} box is
+a circle large enough to surround the box contents with a small safety margin
+controlled by the
+internal variable\index{internal variables}\index{variables!internal}
+{\tt circmargin}\label{Dcmargin}.  Figure~\ref{fig51} gives
+a basic example of the use of {\tt bpath} with {\tt circleit} boxes.
+
+\begin{figure}[htbp]
+$$\begin{verbatim}
+vardef drawshadowed(text t) =
+  fixsize(t);
+  forsuffixes s=t:
+    fill bpath.s shifted (1pt,-1pt);
+    unfill bpath.s;
+    drawboxed(s);
+  endfor
+enddef;
+
+beginfig(51)
+circleit.a(btex Box 1 etex);
+circleit.b(btex Box 2 etex);
+b.n = a.s - (0,20pt);
+drawshadowed(a,b);
+drawarrow a.s -- b.n;
+endfig;
+\end{verbatim}
+\qquad \mathcenter{\epsfbox{manfig.51}} $$
+\caption[MetaPost code and the resulting figure.]
+        {MetaPost code and the resulting figure.  Note that the {\tt drawshadowed}
+        macro used here is not part of the {\tt boxit.mp} macro package.}
+\label{fig51}
+\index{drawshadowed?\texttt{drawshadowed}}
+\end{figure}
+
+A full example of {\tt circleit} boxes appears in Figure~\ref{fig52}.
+The oval boundary paths around ``Start'' and ``Stop'' are due to the equations
+$$ \hbox{\tt aa.dx=aa.dy;} \quad {\rm and}\quad \hbox{\tt ee.dx=ee.dy} $$
+after
+$$ \hbox{\verb|circleit.ee(btex\strut Stop etex)|}
+    \quad{\rm and}\quad
+   \hbox{\verb|circleit.ee(btex\strut Stop etex)|}.
+$$
+The general rule is that {\tt bpath.}$c$ comes out circular if $c${\tt.dx},
+$c${\tt.dy}, and $c\hbox{\tt.dx}-c\hbox{\tt.dy}$ are all unknown.  Otherwise, the
+macros select an oval big enough to contain the given picture with the safety
+margin {\tt circmargin}\index{circmargin?\texttt{circmargin}}.
+
+
+\begin{figure}[htp]
+$$\hbox{$\begin{verbatim}
+vardef cuta(suffix a,b) expr p =
+  drawarrow p cutbefore bpath.a cutafter bpath.b;
+  point .5*length p of p
+enddef;
+
+vardef self@# expr p =
+  cuta(@#,@#) @#.c{curl0}..@#.c+p..{curl0}@#.c  enddef;
+
+beginfig(52);
+verbatimtex \def\stk#1#2{$\displaystyle{\matrix{#1\cr#2\cr}}$} etex
+circleit.aa(btex\strut Start etex); aa.dx=aa.dy;
+circleit.bb(btex \stk B{(a|b)^*a} etex);
+circleit.cc(btex \stk C{b^*} etex);
+circleit.dd(btex \stk D{(a|b)^*ab} etex);
+circleit.ee(btex\strut Stop etex); ee.dx=ee.dy;
+numeric hsep;
+bb.c-aa.c = dd.c-bb.c = ee.c-dd.c = (hsep,0);
+cc.c-bb.c = (0,.8hsep);
+xpart(ee.e - aa.w) = 3.8in;
+drawboxed(aa,bb,cc,dd,ee);
+label.ulft(btex$b$etex, cuta(aa,cc) aa.c{dir50}..cc.c);
+label.top(btex$b$etex, self.cc(0,30pt));
+label.rt(btex$a$etex, cuta(cc,bb) cc.c..bb.c);
+label.top(btex$a$etex, cuta(aa,bb) aa.c..bb.c);
+label.llft(btex$a$etex, self.bb(-20pt,-35pt));
+label.top(btex$b$etex, cuta(bb,dd) bb.c..dd.c);
+label.top(btex$b$etex, cuta(dd,ee) dd.c..ee.c);
+label.lrt(btex$a$etex, cuta(dd,bb) dd.c..{dir140}bb.c);
+label.bot(btex$a$etex, cuta(ee,bb) ee.c..tension1.3 ..{dir115}bb.c);
+label.urt(btex$b$etex, cuta(ee,cc) ee.c{(cc.c-ee.c)rotated-15}..cc.c);
+endfig;
+\end{verbatim}
+$}
+\atop \vcenter{\vskip8pt\hbox{\epsfbox{manfig.52}}}
+$$
+\caption{MetaPost code and the corresponding figure}
+\label{fig52}
+\index{self?\texttt{self}}
+\end{figure}
+
+
+\section{Debugging}
+
+MetaPost inherits from \MF\index{metafont?\MF} numerous facilities for interactive
+debugging, most of which can only be mentioned briefly here.  Further information
+on error messages, debugging, and generating tracing information can be found in
+{\it The\ \MF book} \cite{kn:c}.
+
+Suppose your input file says
+$$ \hbox{\tt draw z1--z2;} $$
+on line 17 without first giving known values to {\tt z1} and {\tt z2}.
+Figure~\ref{errmsg} shows what the MetaPost interpreter prints on your terminal
+when it finds the error.  The actual error message is the line beginning with
+``{\tt !}''; the next six lines give the context that shows exactly what input
+was being read when the error was found; and the ``{\tt ?}'' on last line is a
+prompt for your response.  Since the error message talks about an undefined
+$x$~coordinate, this value is printed on the first line after the ``{\tt >>}''.
+In this case the $x$~coordinate of {\tt z1} is just the unknown variable {\tt x1},
+so the interpreter prints the variable name {\tt x1} just as it would if it
+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 ``{\tt --},'' the
+expansion of the {\tt --} macro has just started, and the initial
+``\verb|{|'' has been reinserted to allow for user input before scanning
+this token.
+
+Among the possible responses to a {\tt ?} prompt are the following:
+\begin{description}
+\item[x] terminates the run so that you can fix you input file and start over.
+\item[h] prints a help message followed by another {\tt ?} prompt.
+\item[\tdescr{return}] causes the interpreter to proceed as best it can.
+\item[?] prints a listing of the options available, followed by another
+        {\tt ?} prompt.
+\end{description}
+
+Error messages and responses to {\tt show} commands are also written into the
+transcript\index{files!transcript} file whose name is obtained from the name
+of the main input file by changing ``{\tt .mp}'' to ``{\tt .log}''.  When the
+internal variable\index{internal variables}\index{variables!internal}
+{\tt tracingonline}\index{tracingonline?\texttt{tracingonline}} is at its default
+value of zero, some {\tt show} commands print their results in full detail only
+in transcript file.
+
+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}
+
+
+\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
+
+\section{Reference Manual}
+
+\let\svtopfrac=\topfraction     % prepare to restore values at end of this appendix
+\let\svtxtfrac=\textfraction    % grouping would fail because \setcounter is global
+\newcounter{svtopnum}
+\newcounter{svtotnum}
+\setcounter{svtopnum}{\value{topnumber}}
+\setcounter{svtotnum}{\value{totalnumber}}
+
+\renewcommand\topfraction{1.0}  % set values to allow *lots* of figures and tables
+\renewcommand\textfraction{0.0}
+\setcounter{topnumber}{10}
+\setcounter{totalnumber}{10}
+
+Tables \ref{ivartab}--\ref{pseudotab} summarize the built-in features of
+Plain MetaPost and the features defined in the {\tt boxes.mp}\index{boxes.mp?\texttt{boxes.mp}}
+macro file.  As explained in Section~\ref{boxessec}, the {\tt boxes.mp} macro
+file is not automatically preloaded and the macros defined there are not
+accessible until you ask for them via the command\index{input?\texttt{input}}
+$$ \hbox{\tt input boxes} $$
+
+Features that depend on {\tt boxes.mp} are marked by \bx\ symbols.
+Features from the Plain\index{Plain macros} macro package are marked are marked
+by \pl\ symbols, and MetaPost primitives are not marked by \bx\ or \pl.
+The distinction between primitives and plain macros can be ignored by the casual
+user, but it is important to remember that features marked by a \bx\ can only
+be used after reading in the {\tt boxes.mp}\index{boxes.mp?\texttt{boxes.mp}} macro file.
+
+The tables in this appendix give the name each feature, the page number where
+it is explained, and a short description.  A few features are not explained
+elsewhere and have no page number listed.  These features exist primarily for
+compatibility with \MF\index{metafont?\MF} and are intended to be self-explanatory.
+Certain other features from \MF\ are omitted entirely because they are of
+limited interest to the MetaPost users and/or would require long explanations.
+All of these are documented in {\it The \MF book} \cite{kn:c} as explained
+in Appendix~\ref{MPvsMF}.
+
+Table~\ref{ivartab} lists internal variables that take on numeric values.
+Table~\ref{pvartab} lists predefined variables of other types.
+Table~\ref{consttab} lists predefined constants.  Some of these are implemented
+as variables whose values are intended to be left unchanged.
+
+Tables \ref{optabA}--\ref{optabD} summarize MetaPost operators and list the
+possible argument and result types for each one.  A ``--'' entry for the left
+argument indicates a unary operator; ``--'' entries for both arguments indicate a
+nullary operator.  Operators that take suffix parameters are not listed in
+these tables because they are treated as ``function-like macros''.
+
+The last two tables are Table~\ref{cmdtab} for commands and Table~\ref{pseudotab}
+macros that behave like functions or procedures.  Such macros take parenthesized
+argument lists and/or suffix parameters, returning either a value whose type is
+listed in the table, or nothing.  The latter case is for macros that behave
+like procedures.  Their return values are listed as ``--''.
+
+The figures in this appendix present the syntax of the MetaPost language
+starting with expressions in Figures \ref{syexpr1}--\ref{sypseudo}.
+Although the productions sometimes specify types for expressions, primaries,
+secondaries, and tertiaries, no attempt is made to give separate syntaxes
+for \tdescr{numeric expression}, \tdescr{pair expression}, etc.
+The simplicity of the productions in Figure~\ref{sytypexpr} is due to this
+lack of type information.  Type information
+can be found in Tables \ref{ivartab}--\ref{pseudotab}.
+
+Figures \ref{syprog} and \ref{sycmds} give the syntax for MetaPost programs,
+including statements and commands.  They do not mention loops\index{loops}
+and {\tt if}\index{if?\texttt{if}}
+tests because these constructions do not behave like statements.  The syntax
+given in Figures \ref{syexpr1}--\ref{pseudotab} applies to the result of
+expanding all conditionals and loops.  Conditionals and loops do have a
+syntax, but they deal with almost arbitrary sequences of tokens.
+Figure~\ref{sycondloop} specifies conditionals in terms of
+\tdescr{balanced tokens} and loops in terms of \tdescr{loop text}, where
+\tdescr{balanced tokens} is any sequence of tokens balanced with respect
+to {\tt if} and {\tt fi}, and \tdescr{loop text} is a sequence of tokens
+balanced with respect to {\tt for}, {\tt forsuffixes}, {\tt forever},
+and {\tt endfor}.
+
+\begin{table}[htp]
+\caption{Internal variables with numeric values}
+$$\begin{tabular}{|l|r|l|}
+\hline
+\multicolumn1{|c}{Name}&  \multicolumn1{|c}{Page}&  \multicolumn1{|c|}{Explanation}\\
+\hline
+\hline
+\pl\tt  ahangle&        \pageref{Dahangle}&
+        angle for arrowheads in degrees (default: 45)\\\hline
+\pl\tt  ahlength&       \pageref{Dahlength}&
+        size of arrowheads (default: 4{\tt bp})\\\hline
+\pl\tt  bboxmargin&     \pageref{Dbbmargin}&
+        extra space allowed by {\tt bbox} (default 2{\tt bp})\\\hline
+\tt     charcode&       \pageref{Dcharcode}&
+        the number of the next character to be output\\\hline
+\bx\tt  circmargin&     \pageref{Dcmargin}&
+        clearance around contents of a circular or oval box\\\hline
+\tt     day&    --&
+        the current day of the month\\\hline
+\bx\tt  defaultdx&      \pageref{Ddefaultdx}&
+        usual horizontal space around box contents (default 3{\tt bp})\\\hline
+\bx\tt  defaultdy&      \pageref{Ddefaultdy}&
+        usual vertical space around box contents (default 3{\tt bp})\\\hline
+\pl\tt  defaultpen&     \pageref{Ddefaultpen}&
+        numeric index used by {\tt pickup} to select default pen\\\hline
+\pl\tt  defaultscale&   \pageref{Ddfscale}&
+        font scale factor for label strings (default 1)\\\hline
+\pl\tt  labeloffset&    \pageref{Dlaboff}&
+        offset distance for labels (default 3{\tt bp})\\\hline
+\tt     linecap&        \pageref{Dlinecap}&
+        0 for butt, 1 for round, 2 for square\\\hline
+\tt     linejoin&       \pageref{Dlinejoin}&
+        0 for mitered, 1 for round, 2 for beveled\\\hline
+\tt     miterlimit&     \pageref{Dmiterlim}&
+        controls miter length as in PostScript\\\hline
+\tt     month&  --&
+        the current month (e.g, 3 $\equiv$ March)\\\hline
+\tt     pausing&        --&
+        ${}>0$ to display lines on the terminal before they are read\\\hline
+\tt     prologues&      \pageref{Dprologs}&
+        ${}>0$ to output conforming PostScript using built-in fonts\\\hline
+\tt     showstopping&   --&
+        ${}>0$ to stop after each {\tt show} command\\\hline
+\tt     time&   --&
+        the number of minutes past midnight when this job started\\\hline
+\tt     tracingcapsules&        \pageref{Dtcapsules}&
+        ${}>0$ to show capsules too\\\hline
+\tt     tracingchoices& \pageref{Dtchoices}&
+        ${}>0$ to show the control points chosen for paths\\\hline
+\tt     tracingcommands&        \pageref{Dtcommands}&
+        ${}>0$ to show commands and operations as they are performed\\\hline
+\tt     tracingequations&       \pageref{Dtequations}&
+        ${}>0$ to show each variable when it becomes known\\\hline
+\tt     tracinglostchars&       \pageref{Dtlostchars}&
+        ${}>0$ to show characters that aren't {\tt infont}\\\hline
+\tt     tracingmacros&  \pageref{Dtmacros}&
+        ${}>0$ to show macros before they are expanded\\\hline
+\tt     tracingonline&  \pageref{Dtonline}&
+        ${}>0$ to show long diagnostics on the terminal\\\hline
+\tt     tracingoutput&  \pageref{Dtoutput}&
+        ${}>0$ to show digitized edges as they are output\\\hline
+\tt     tracingrestores&        \pageref{Dtrestores}&
+        ${}>0$ to show when a variable or internal is restored\\\hline
+\tt     tracingspecs&   \pageref{Dtspecs}&
+        ${}>0$ to show path subdivision when using a polygonal a pen\\\hline
+\tt     tracingstats&   \pageref{Dtstats}&
+        ${}>0$ to show memory usage at end of job\\\hline
+\tt     tracingtitles&  --&
+        ${}>0$ to show titles online when they appear\\\hline
+\tt     truecorners&    \pageref{Dtruecorn}&
+        ${}>0$ to make {\tt llcorner} etc. ignore {\tt setbounds}\\\hline
+\tt     warningcheck&   \pageref{Dwarncheck}&
+        controls error message when variable value is large\\\hline
+\tt     year&   --&
+        the current year (e.g., 1992)\\\hline
+\end{tabular}
+$$
+\label{ivartab}%
+\index{day?\texttt{day}}\index{month?\texttt{month}}\index{pausing?\texttt{pausing}}\index{showstopping?\texttt{showstopping}}%
+\index{time?\texttt{time}}\index{tracingtitles?\texttt{tracingtitles}}\index{year?\texttt{year}}
+\end{table}
+
+\begin{table}[htp]
+\caption{Other Predefined Variables}
+$$\begin{tabular}{|l|l|r|l|}
+\hline
+\multicolumn1{|c}{Name}&  \multicolumn1{|c}{Type}&  \multicolumn1{|c}{Page}&
+        \multicolumn1{|c|}{Explanation}\\
+\hline
+\hline
+\pl\tt  background&     color&  \pageref{Dbground}&
+        Color for {\tt unfill} and {\tt undraw} (usually white)\\\hline
+\pl\tt  currentpen&     pen&    \pageref{Dcurpen}&
+        Last pen picked up (for use by the {\tt draw} command)\\\hline
+\pl\tt  currentpicture& picture&        \pageref{Dcurpic}&
+        Accumulate results of {\tt draw} and {\tt fill} commands\\\hline
+\pl\tt  cuttings&       path&   \pageref{Dcuttings}&
+        subpath cut off by last {\tt cutbefore} or {\tt cutafter}\\\hline
+\pl\tt  defaultfont&    string& \pageref{Ddffont}&
+        Font used by label commands for typesetting strings\\\hline
+\pl\tt  extra\_beginfig&        string& \pageref{Dxbfig}&
+        Commands for {\tt beginfig} to scan\\\hline
+\pl\tt  extra\_endfig&  string& \pageref{Dxefig}&
+        Commands for {\tt endfig} to scan\\\hline
+\end{tabular}
+$$
+\label{pvartab}
+\end{table}
+
+\begin{table}[htp]
+\caption{Predefined Constants}
+$$\begin{tabular}{|l|l|r|l|}
+\hline
+\multicolumn1{|c}{Name}&  \multicolumn1{|c}{Type}&  \multicolumn1{|c}{Page}&
+        \multicolumn1{|c|}{Explanation}\\
+\hline
+\hline
+\pl\tt  beveled&        numeric&        \pageref{Dbvled}&
+        {\tt linejoin} value for beveled joins [2]\\\hline
+\pl\tt  black&  color&  \pageref{Dblack}&
+        Equivalent to {\tt (0,0,0)}\\\hline
+\pl\tt  blue&   color&  \pageref{Dblue}&
+        Equivalent to {\tt (0,0,1)}\\\hline
+\pl\tt  bp&     numeric&        \pageref{Dbp}&
+        One PostScript point in {\tt bp} units [1]\\\hline
+\pl\tt  butt&   numeric&        \pageref{Dbutt}&
+        {\tt linecap} value for butt end caps [0]\\\hline
+\pl\tt  cc&     numeric&        --&
+        One cicero in {\tt bp} units [12.79213]\\\hline
+\pl\tt  cm&     numeric&        \pageref{Dcm}&
+        One centimeter in {\tt bp} units [28.34645]\\\hline
+\pl\tt  dd&     numeric&        --&
+        One didot point in {\tt bp} units [1.06601]\\\hline
+\pl\tt  ditto&  string& --&
+        The {\tt "} character as a string of length 1\\\hline
+\pl\tt  down&   pair&   \pageref{Ddown}&
+        Downward direction vector $(0,-1)$\\\hline
+\pl\tt  epsilon&        numeric&        --&
+        Smallest positive MetaPost number [$1\over65536$]\\\hline
+\pl\tt  evenly& picture&        \pageref{Devenly}&
+        Dash pattern for equal length dashes\\\hline
+\tt     false&  boolean&        \pageref{Dfalse}&
+        The boolean value {\it false\/}\\\hline
+\pl\tt  fullcircle&     path&   \pageref{Dfcirc}&
+        Circle of diameter 1 centered on $(0,0)$\\\hline
+\pl\tt  green&  color&  \pageref{Dgreen}&
+        Equivalent to {\tt (0,1,0)}\\\hline
+\pl\tt  halfcircle&     path&   \pageref{Dhcirc}&
+        Upper half of a circle of diameter 1\\\hline
+\pl\tt  identity&       transform&      \pageref{Dident}&
+        Identity transformation\\\hline
+\pl\tt  in&     numeric&        \pageref{Din}&
+        One inch in {\tt bp} units [72]\\\hline
+\pl\tt  infinity&       numeric&        \pageref{Dinf}&
+        Large positive value [4095.99998]\\\hline
+\pl\tt  left&   pair&   \pageref{Dleft}&
+        Leftward direction $(-1,0)$\\\hline
+\pl\tt  mitered&        numeric&        \pageref{Dmitred}&
+        {\tt linejoin} value for mitered joins [0]\\\hline
+\pl\tt  mm&     numeric&        \pageref{Dmm}&
+        One millimeter in {\tt bp} units [2.83464]\\\hline
+\tt     nullpicture&    picture&        \pageref{Dnlpic}&
+        Empty picture\\\hline
+\pl\tt  origin& pair&   --&
+        The pair $(0,0)$\\\hline
+\pl\tt  pc&     numeric&        --&
+        One pica in {\tt bp} units [11.95517]\\\hline
+\tt     pencircle&      pen&    \pageref{Dpncirc}&
+        Circular pen of diameter 1\\\hline
+\pl\tt  pensquare&      pen&    \pageref{Dpnsqr}&
+        square pen of height 1 and width 1\\\hline
+\pl\tt  pt&     numeric&        \pageref{Dpt}&
+        One printer's point in {\tt bp} units [0.99626]\\\hline
+\pl\tt  quartercircle&  path&   --&
+        First quadrant of a circle of diameter 1\\\hline
+\pl\tt  red&    color&  \pageref{Dred}&
+        Equivalent to {\tt (1,0,0)}\\\hline
+\pl\tt  right&  pair&   \pageref{Dright}&
+        Rightward direction $(1,0)$\\\hline
+\pl\tt  rounded&        numeric&        \pageref{Drnded}&
+        {\tt linecap} and {\tt linejoin} value for round joins\\
+\tt     &       &       &
+        and end caps [1]\\\hline
+\pl\tt  squared&        numeric&        \pageref{Dsqred}&
+        {\tt linecap} value for square end caps [2]\\\hline
+\tt     true&   boolean&        \pageref{Dtrue}&
+        The boolean value {\tt true}\\\hline
+\pl\tt  unitsquare&     path&   --&
+        The path {\tt (0,0)--(1,0)--(1,1)--(0,1)--cycle}\\\hline
+\pl\tt  up&     pair&   \pageref{Dup}&
+        Upward direction $(0,1)$\\\hline
+\pl\tt  white&  color&  \pageref{Dwhite}&
+        Equivalent to {\tt (1,1,1)}\\\hline
+\pl\tt  withdots&       picture&        \pageref{Dwdots}&
+        Dash pattern that produces dotted lines\\\hline
+\end{tabular}
+$$
+\label{consttab}%
+\index{cc?\texttt{cc}}\index{dd?\texttt{dd}}\index{ditto?\texttt{ditto}}\index{epsilon?\texttt{epsilon}}%
+\index{origin?\texttt{origin}}\index{pc?\texttt{pc}}\index{quartercircle?\texttt{quartercircle}}%
+\index{unitsquare?\texttt{unitsquare}}
+\end{table}
+
+\begin{table}[htp]
+\caption{Operators (Part 1)}
+$$\begin{tabular}{|l|l|l|l|r|l|}
+\hline
+\multicolumn1{|c}{Name}&  \multicolumn3{|c}{Argument/result types}&
+        \multicolumn1{|c}{Page}& \multicolumn1{|c|}{Explanation}\\
+\cline{2-4}
+&       Left&   Right&  Result&         & \\
+\hline
+\hline
+\tt \verb|&|&   string& string& string& \pageref{Damp}&
+        Concatenation---works for paths $l\hbox{\tt\&}r$ if\\
+&       path&   path&   path&   &
+        $r$ starts exactly where the $l$ ends\\\hline
+\tt \verb|*|&   numeric&        color&  color&  \pageref{Dmldiv}&
+        Multiplication\\
+&       &       numeric&        numeric&        &
+        \\
+&       &       pair&   pair&   &
+        \\\hline
+\tt \verb|*|&   color&  numeric&        color&  \pageref{Dmldiv}&
+        Multiplication\\
+&       numeric&        &       numeric&        &
+        \\
+&       pair&   &       pair&   &
+        \\\hline
+\tt \verb|**|&  numeric&        numeric&        numeric&        \pageref{Dpow}&
+        Exponentiation\\\hline
+\tt \verb|+|&   color&  color&  color&  \pageref{Dadd}&
+        Addition\\
+&       numeric&        numeric&        numeric&        &
+        \\
+&       pair&   pair&   pair&   &
+        \\\hline
+\tt \verb|++|&  numeric&        numeric&        numeric&        \pageref{Dpyadd}&
+        Pythagorean addition $\sqrt{l^2+r^2}$\\\hline
+\tt \verb|+-+|& numeric&        numeric&        numeric&        \pageref{Dpysub}&
+        Pythagorean subtraction $\sqrt{l^2-r^2}$\\\hline
+\tt \verb|-|&   color&  color&  color&  \pageref{Dadd}&
+        Subtraction\\
+&       numeric&        numeric&        numeric&        &
+        \\
+&       pair&   pair&   pair&   &
+        \\\hline
+\tt \verb|-|&   --&     color&  color&  \pageref{Dneg}&
+        Negation\\
+&       &       numeric&        numeric&        &
+        \\
+&       &       pair&   pair&   &
+        \\\hline
+\tt \verb|/|&   color&  numeric&        color&  \pageref{Dmldiv}&
+        Division\\
+&       numeric&        &       numeric&        &
+        \\
+&       pair&   &       pair&   &
+        \\\hline
+\tt \verb|< = >|&       string& string& boolean&        \pageref{Dcmpar}&
+        Comparison operators\\
+\tt \verb|<= >=|&       numeric&        numeric&        &       &
+        \\
+\tt \verb|<>|&  pair&   pair&   &       &
+        \\
+&       color&  color&  &       &
+        \\
+&       transform&      transform&      &       &
+        \\\hline
+\pl\tt \verb|abs|&      --&     numeric&        numeric&        \pageref{Dabs}&
+        Absolute value\\
+&       &       pair&   &       &
+        \\\hline
+\tt \verb|and|& boolean&        boolean&        boolean&        \pageref{Dand}&
+        Logical and\\\hline
+\tt \verb|angle|&       --&     pair&   numeric&        \pageref{Dangle}&
+        2$-$argument arctangent (in degrees)\\\hline
+\tt \verb|arclength|&   --&     path&   numeric&        \pageref{Darclng}&
+        Arc length of a path\\\hline
+\tt \verb|arctime|&     numeric&        path&   numeric&        \pageref{Darctim}&
+        Time on a path where arclength from\\
+\tt \verb|of|&  &       &       &       &
+        the start reaches a given value\\\hline
+\tt \verb|ASCII|&       --&     string& numeric&        --&
+        ASCII value of first character in string\\\hline
+\pl\tt \verb|bbox|&     --&     picture&        path&   \pageref{Dbbox}&
+        A rectangular path for the bounding\\
+&       &       path&   &       &
+        box\\
+&       &       pen&    &       &
+        \\\hline
+\tt \verb|bluepart|&    --&     color&  numeric&        \pageref{Drgbprt}&
+        Extracts the third component\\\hline
+\tt \verb|boolean|&     --&     any&    boolean&        \pageref{Dboolop}&
+        Is the expression of type boolean?\\\hline
+\tt \verb|bot|& --&     numeric&        numeric&        \pageref{Dbot}&
+        Bottom of current pen when centered\\
+&       &       pair&   pair&   &
+        at the given coordinate(s)\\\hline
+\pl\tt \verb|ceiling|&  --&     numeric&        numeric&        \pageref{Dceil}&
+        Least integer greater than or equal to\\\hline
+\pl\tt \verb|center|&   --&     picture&        pair&   \pageref{Dcenter}&
+        Center of the bounding box\\
+&       &       path&   &       &
+        \\
+&       &       pen&    &       &
+        \\\hline
+\end{tabular}
+$$
+\index{ASCII?\texttt{ASCII}}%
+\label{optabA}
+\end{table}
+
+\begin{table}[htp]
+\caption{Operators (Part 2)}
+$$\begin{tabular}{|l|l|l|l|r|l|}
+\hline
+\multicolumn1{|c}{Name}&  \multicolumn3{|c}{Argument/result types}&
+        \multicolumn1{|c}{Page}& \multicolumn1{|c|}{Explanation}\\
+\cline{2-4}
+&       Left&   Right&  Result&         & \\
+\hline
+\hline
+\tt \verb|char|&        --&     numeric&        string& \pageref{Dchar}&
+        Character with a given ASCII code\\\hline
+\tt \verb|color|&       --&     any&    boolean&        \pageref{Dcolrop}&
+        Is the expression of type color?\\\hline
+\tt \verb|cosd|&        --&     numeric&        numeric&        \pageref{Dcosd}&
+        Cosine of angle in degrees\\\hline
+\pl\tt \verb|cutafter|& path&   path&   path&   \pageref{Dcuta}&
+        Left argument with part after the\\
+&       &       &       &       &
+        intersection dropped\\\hline
+\pl\tt \verb|cutbefore|&        path&   path&   path&   \pageref{Dcutb}&
+        Left argument with part before the\\
+&       &       &       &       &
+        intersection dropped\\\hline
+\tt \verb|cycle|&       --&     path&   boolean&        \pageref{Dcycop}&
+        Determines whether a path is cyclic\\\hline
+\tt \verb|decimal|&     --&     numeric&        string& \pageref{Ddecop}&
+        The decimal representation\\\hline
+\pl\tt \verb|dir|&      --&     numeric&        pair&   \pageref{Ddirop}&
+        $(\cos\theta,\sin\theta)$ given $\theta$ in degrees\\\hline
+\pl\tt \verb|direction|&        numeric&        path&   pair&   \pageref{Ddirof}&
+        The direction of a path at a given\\
+\tt \verb| of|& &       &       &       &
+        `time'\\\hline
+\pl\tt \verb|direction-|&       pair&   path&   numeric&        \pageref{Ddpntof}&
+        Point where a path has a given\\
+\tt \verb|point of|&    &       &       &       &
+        direction\\\hline
+\tt \verb|direction-|&  pair&   path&   numeric&        \pageref{Ddtimof}&
+        `Time' when a path has a given\\
+\tt \verb|time of|&     &       &       &       &
+        direction\\\hline
+\pl\tt \verb|div|&      numeric&        numeric&        numeric&        --&
+        Integer division $\lfloor l/r\rfloor$\\\hline
+\pl\tt \verb|dotprod|&  pair&   pair&   numeric&        \pageref{Ddprod}&
+        vector dot product\\\hline
+\tt \verb|floor|&       --&     numeric&        numeric&        \pageref{Dfloor}&
+        Greatest integer less than or equal to\\\hline
+\tt \verb|fontsize|&    --&     string& numeric&        \pageref{Dfntsiz}&
+        The point size of a font\\\hline
+\tt \verb|greenpart|&   --&     color&  numeric&        \pageref{Drgbprt}&
+        Extract the second component\\\hline
+\tt \verb|hex|& --&     string& numeric&        --&
+        Interpret as a hexadecimal number\\\hline
+\tt \verb|infont|&      string& string& picture&        \pageref{Sinfont}&
+        Typeset string in given font\\\hline
+\pl\tt \verb|intersec-|&        path&   path&   pair&   \pageref{Disecpt}&
+        An intersection point\\
+\tt \verb| tionpoint|&  &       &       &       &
+        \\\hline
+\tt \verb|intersec-|&   path&   path&   pair&   \pageref{Disectt}&
+        Times ($t_l,t_r)$ on paths $l$ and $r$\\
+\tt \verb|tiontimes|&   &       &       &       &
+        when the paths intersect\\\hline
+\pl\tt \verb|inverse|&  --&     transform&      transform&      \pageref{Dinv}&
+        Invert a transformation\\\hline
+\tt \verb|known|&       --&     any&    boolean&        \pageref{Dknown}&
+        Does argument have a known value?\\\hline
+\tt \verb|length|&      --&     path&   numeric&        \pageref{Dlength}&
+        Number of arcs in a path\\\hline
+\pl\tt \verb|lft|&      --&     numeric&        numeric&        \pageref{Dlft}&
+        Left side of current pen when its\\
+&       &       pair&   pair&   &
+        center is at the given coordinate(s)\\\hline
+\tt \verb|llcorner|&    --&     picture&        pair&   \pageref{Dcornop}&
+        Lower-left corner of bounding box\\
+&       &       path&   &       &
+        \\
+&       &       pen&    &       &
+        \\\hline
+\tt \verb|lrcorner|&    --&     picture&        pair&   \pageref{Dcornop}&
+        Lower-left corner of bounding box\\
+&       &       path&   &       &
+        \\
+&       &       pen&    &       &
+        \\\hline
+\tt \verb|makepath|&    --&     pen&    path&   \pageref{Dmkpath}&
+        Cyclic path bounding the pen shape\\\hline
+\tt \verb|makepen|&     --&     path&   pen&    \pageref{Dmkpen}&
+        A polygonal pen made from the\\
+&       &       &       &       &
+        convex hull of the path knots\\\hline
+\tt \verb|mexp|&        --&     numeric&        numeric&        --&
+        The function $\exp(x/256)$\\\hline
+\tt \verb|mlog|&        --&     numeric&        numeric&        --&
+        The function $256\ln(x)$\\\hline
+\pl\tt \verb|mod|&      --&     numeric&        numeric&        --&
+        The remainder function $l-r\lfloor l/r\rfloor$\\\hline
+\tt \verb|normal-|&     --&     --&     numeric&        --&
+        Choose a random number with\\
+\tt \verb|deviate|&     &       &       &       &
+        mean 0 and standard deviation 1\\\hline
+\end{tabular}
+$$
+\index{div?\texttt{div}}\index{hex?\texttt{hex}}\index{mexp?\texttt{mexp}}\index{mlog?\texttt{mlog}}%
+\index{mod?\texttt{mod}}\index{normaldeviate?\texttt{normaldeviate}}%
+\label{optabB}
+\end{table}
+
+\begin{table}[htp]
+\caption{Operators (Part 3)}
+$$\begin{tabular}{|l|l|l|l|r|l|}
+\hline
+\multicolumn1{|c}{Name}&  \multicolumn3{|c}{Argument/result types}&
+        \multicolumn1{|c}{Page}& \multicolumn1{|c|}{Explanation}\\
+\cline{2-4}
+&       Left&   Right&  Result&         & \\
+\hline
+\hline
+\tt \verb|not|& --&     boolean&        boolean&        \pageref{Dnot}&
+        Logical negation\\\hline
+\tt \verb|numeric|&     --&     any&    boolean&        \pageref{Dnumop}&
+        Is the expression of type numeric?\\\hline
+\tt \verb|oct|& --&     string& numeric&        --&
+        Interpret a string as an octal number\\\hline
+\tt \verb|odd|& --&     numeric&        boolean&        --&
+        Is the closest integer odd or even?\\\hline
+\tt \verb|or|&  boolean&        boolean&        boolean&        \pageref{Dor}&
+        Logical inclusive or\\\hline
+\tt \verb|pair|&        --&     any&    boolean&        \pageref{Dpairop}&
+        Is the expression of type pair?\\\hline
+\tt \verb|path|&        --&     any&    boolean&        \pageref{Dpathop}&
+        Is the expression of type path?\\\hline
+\tt \verb|pen|& --&     any&    boolean&        \pageref{Dpenop}&
+        Is the expression of type pen?\\\hline
+\tt \verb|penoffset|&   pair&   pen&    pair&   --&
+        Point on the pen furthest to the\\
+\tt \verb|of|&  &       &       &       &
+        right of the given direction\\\hline
+\tt \verb|picture|&     --&     any&    boolean&        \pageref{Dpictop}&
+        Is the expression of type picture?\\\hline
+\tt \verb|point of|&    numeric&        path&   pair&   \pageref{Dpntof}&
+        Point on a path given a time value\\\hline
+\tt \verb|postcontrol|& numeric&        path&   pair&   --&
+        First B\'ezier control point on path\\
+\tt \verb|of|&  &       &       &       &
+        segment starting at the given time\\\hline
+\tt \verb|precontrol|&  numeric&        path&   pair&   --&
+        Last B\'ezier control point on path\\
+\tt \verb|of|&  &       &       &       &
+        segment ending at the given time\\\hline
+\tt \verb|redpart|&     --&     color&  numeric&        \pageref{Drgbprt}&
+        Extract the first component\\\hline
+\tt \verb|reverse|&     --&     path&   path&   \pageref{Drevrse}&
+        `time'-reversed path with beginning\\
+&       &       &       &       &
+        swapped with ending\\\hline
+\tt \verb|rotated|&     picture&        numeric&        picture&        \pageref{Dtranop}&
+        Rotate counterclockwise a given\\
+&       path&   &       path&   &
+        number of degrees\\
+&       pair&   &       pair&   &
+        \\
+&       pen&    &       pen&    &
+        \\
+&       transform&      &       transform&      &
+        \\\hline
+\pl\tt \verb|round|&    --&     numeric&        numeric&        \pageref{Dround}&
+        round each component to the nearest\\
+&       &       pair&   pair&   &
+        integer\\\hline
+\pl\tt \verb|rt|&       --&     numeric&        numeric&        \pageref{Drt}&
+        Right side of current pen when\\
+&       &       pair&   pair&   &
+        centered at given coordinate(s)\\\hline
+\tt \verb|scaled|&      picture&        numeric&        picture&        \pageref{Dtranop}&
+        Scale all coordinates by the given\\
+&       path&   &       path&   &
+        amount\\
+&       pair&   &       pair&   &
+        \\
+&       pen&    &       pen&    &
+        \\
+&       transform&      &       transform&      &
+        \\\hline
+\tt \verb|shifted|&     picture&        pair&   picture&        \pageref{Dtranop}&
+        Add the given shift amount to each\\
+&       path&   &       path&   &
+        pair of coordinates\\
+&       pair&   &       pair&   &
+        \\
+&       pen&    &       pen&    &
+        \\
+&       transform&      &       transform&      &
+        \\\hline
+\tt \verb|sind|&        --&     numeric&        numeric&        \pageref{Dsind}&
+        Sine of an angle in degrees\\\hline
+\tt \verb|slanted|&     picture&        numeric&        picture&        \pageref{Dtranop}&
+        Apply the slanting transformation\\
+&       path&   &       path&   &
+        that maps $(x,y)$ into $(x+sy,y)$,\\
+&       pair&   &       pair&   &
+        where $s$ is the numeric argument\\
+&       pen&    &       pen&    &
+        \\
+&       transform&      &       transform&      &
+        \\\hline
+\tt \verb|sqrt|&        --&     numeric&        numeric&        \pageref{Dsqrt}&
+        Square root\\\hline
+\tt \verb|str|& --&     suffix& string& \pageref{Dstr}&
+        String representation for a suffix\\\hline
+\end{tabular}
+$$
+\index{oct?\texttt{oct}}\index{odd?\texttt{odd}}\index{penoffset?\texttt{penoffset}}\index{postcontrol?\texttt{postcontrol}}%
+\index{precontrol?\texttt{precontrol}}%
+\label{optabC}
+\end{table}
+
+\begin{table}[htp]
+\caption{Operators (Part 4)}
+$$\begin{tabular}{|l|l|l|l|r|l|}
+\hline
+\multicolumn1{|c}{Name}&  \multicolumn3{|c}{Argument/result types}&
+        \multicolumn1{|c}{Page}& \multicolumn1{|c|}{Explanation}\\
+\cline{2-4}
+&       Left&   Right&  Result&         & \\
+\hline
+\hline
+\tt \verb|string|&      --&     any&    boolean&        \pageref{Dstrgop}&
+        Is the expression of type string?\\\hline
+\tt \verb|subpath|&     pair&   path&   path&   \pageref{Dsubpth}&
+        Portion of a path for given range\\
+\tt \verb|of|&  &       &       &       &
+        of time values\\\hline
+\tt \verb|substring|&   pair&   string& string& \pageref{Dsubstr}&
+        Substring bounded by given indices\\
+\tt \verb|of|&  &       &       &       &
+        \\\hline
+\pl\tt \verb|top|&      --&     numeric&        numeric&        \pageref{Dtop}&
+        Top of current pen when centered\\
+&       &       pair&   pair&   &
+        at the given coordinate(s)\\\hline
+\tt \verb|transform|&   --&     any&    boolean&        \pageref{Dtrnfop}&
+        Is the argument of type transform?\\\hline
+\tt \verb|transformed|& picture&        transform&      picture&        \pageref{Dtrfrmd}&
+        Apply the given transform to all\\
+&       path&   &       path&   &
+        coordinates\\
+&       pair&   &       pair&   &
+        \\
+&       pen&    &       pen&    &
+        \\
+&       transform&      &       transform&      &
+        \\\hline
+\tt \verb|ulcorner|&    --&     picture&        pair&   \pageref{Dcornop}&
+        Upper-left corner of bounding box\\
+&       &       path&   &       &
+        \\
+&       &       pen&    &       &
+        \\\hline
+\tt \verb|uniform-|&    --&     numeric&        numeric&        --&
+        Random number between zero and\\
+\tt \verb|deviate|&     &       &       &       &
+        the value of the argument\\\hline
+\pl\tt \verb|unitvector|&       --&     pair&   pair&   \pageref{Duvec}&
+        Rescale a vector so its length is 1\\\hline
+\tt \verb|unknown|&     --&     any&    boolean&        \pageref{Dunknwn}&
+        Is the value unknown?\\\hline
+\tt \verb|urcorner|&    --&     picture&        pair&   \pageref{Dcornop}&
+        Upper-left corner of bounding box\\
+&       &       path&   &       &
+        \\
+&       &       pen&    &       &
+        \\\hline
+\pl\tt \verb|whatever|& --&     --&     numeric&        \pageref{Dwhatev}&
+        Create a new anonymous unknown\\\hline
+\tt \verb|xpart|&       --&     pair&   number& \pageref{Dxprt}&
+        $x$ or $t_x$ component\\
+&       &       transform&      &       &
+        \\\hline
+\tt \verb|xscaled|&     picture&        numeric&        picture&        \pageref{Dtranop}&
+        Scale all $x$ coordinates by the\\
+&       path&   &       path&   &
+        given amount\\
+&       pair&   &       pair&   &
+        \\
+&       pen&    &       pen&    &
+        \\
+&       transform&      &       transform&      &
+        \\\hline
+\tt \verb|xxpart|&      --&     transform&      number& \pageref{Dtrprt}&
+        $t_{xx}$ entry in transformation matrix\\\hline
+\tt \verb|xypart|&      --&     transform&      number& \pageref{Dtrprt}&
+        $t_{xy}$ entry in transformation matrix\\\hline
+\tt \verb|ypart|&       --&     pair&   number& \pageref{Dyprt}&
+        $y$ or $t_y$ component\\
+&       &       transform&      &       &
+        \\\hline
+\tt \verb|yscaled|&     picture&        numeric&        picture&        \pageref{Dtranop}&
+        Scale all $y$ coordinates by the\\
+&       path&   &       path&   &
+        given amount\\
+&       pair&   &       pair&   &
+        \\
+&       pen&    &       pen&    &
+        \\
+&       transform&      &       transform&      &
+        \\\hline
+\tt \verb|yxpart|&      --&     transform&      number& \pageref{Dtrprt}&
+        $t_{yx}$ entry in transformation matrix\\\hline
+\tt \verb|yypart|&      --&     transform&      number& \pageref{Dtrprt}&
+        $t_{yy}$ entry in transformation matrix\\\hline
+\tt \verb|zscaled|&     picture&        pair&   picture&        \pageref{Dtranop}&
+        Rotate and scale all coordinates so\\
+&       path&   &       path&   &
+        that $(1,0)$ is mapped into the\\
+&       pair&   &       pair&   &
+        given pair; i.e., do complex\\
+&       pen&    &       pen&    &
+        multiplication.\\
+&       transform&      &       transform&      &
+        \\\hline
+\end{tabular}
+$$
+\index{uniformdeviate?\texttt{uniformdeviate}}%
+\label{optabD}
+\end{table}
+
+\begin{table}[htp]
+\caption{Commands}
+$$\begin{tabular}{|l|r|l|}
+\hline
+\multicolumn1{|c}{Name}&  \multicolumn1{|c}{Page}&  \multicolumn1{|c|}{Explanation}\\
+\hline
+\hline
+\tt \verb|addto|&       \pageref{sydraw}&
+        Low-level command for drawing and filling\\\hline
+\tt \verb|clip|&        \pageref{Dclip}&
+        Applies a clipping path to a picture\\\hline
+\pl\tt \verb|cutdraw|&  \pageref{Dctdraw}&
+        Draw with butt end caps\\\hline
+\pl\tt \verb|draw|&     \pageref{curves}&
+        Draw a line or a picture\\\hline
+\pl\tt \verb|drawarrow|&        \pageref{Ddrwarr}&
+        Draw a line with an arrowhead at the end\\\hline
+\pl\tt \verb|drawdblarrow|&     \pageref{Ddrwdar}&
+        Draw a line with arrowheads at both ends\\\hline
+\pl\tt \verb|fill|&     \pageref{Dfill}&
+        Fill inside a cyclic path\\\hline
+\pl\tt \verb|filldraw|& \pageref{Dfildrw}&
+        Draw a cyclic path and fill inside it\\\hline
+\tt \verb|interim|&     \pageref{Dinterm}&
+        Make a local change to an internal variable\\\hline
+\tt \verb|let|& --&
+        Assign one symbolic token the meaning of another\\\hline
+\pl\tt \verb|loggingall|&       \pageref{Dlogall}&
+        Turn on all tracing (log file only)\\\hline
+\tt \verb|newinternal|& \pageref{Dnewint}&
+        Declare new internal variables\\\hline
+\pl\tt \verb|pickup|&   \pageref{Dpickup}&
+        Specify new pen for line drawing\\\hline
+\tt \verb|save|&        \pageref{Dsave}&
+        Make variables local\\\hline
+\tt \verb|setbounds|&   \pageref{Dsetbnd}&
+        Make a picture lie about its bounding box\\\hline
+\tt \verb|shipout|&     \pageref{Dship}&
+        Low-level command to output a figure\\\hline
+\tt \verb|show|&        \pageref{Dshow}&
+        print out expressions symbolically\\\hline
+\tt \verb|showdependencies|&    \pageref{Dshdep}&
+        print out all unsolved equations\\\hline
+\tt \verb|showtoken|&   \pageref{Dshtok}&
+        print an explanation of what a token is\\\hline
+\tt \verb|showvariable|&        \pageref{Dshvar}&
+        print variables symbolically\\\hline
+\tt \verb|special|&     \pageref{Dspecl}&
+        print a string directly in the PostScript output file\\\hline
+\pl\tt \verb|tracingall|&       \pageref{Dtall}&
+        Turn on all tracing\\\hline
+\pl\tt \verb|tracingnone|&      \pageref{Dtnone}&
+        Turn off all tracing\\\hline
+\pl\tt \verb|undraw|&   \pageref{Dundraw}&
+        Erase a line or a picture\\\hline
+\pl\tt \verb|unfill|&   \pageref{Dunfill}&
+        Erase inside a cyclic path\\\hline
+\pl\tt \verb|unfilldraw|&       \pageref{Dunfdrw}&
+        Erase a cyclic path and its inside\\\hline
+\end{tabular}
+$$
+\index{let?\texttt{let}}%
+\label{cmdtab}
+\end{table}
+
+\begin{table}[htp]
+\caption{Function-Like Macros}
+$$\begin{tabular}{|l|l|l|r|l|}
+\hline
+\multicolumn1{|c}{Name}&  \multicolumn1{|c}{Arguments}&
+        \multicolumn1{|c}{Result}&  \multicolumn1{|c}{Page}&
+        \multicolumn1{|c|}{Explanation}\\
+\hline
+\hline
+\bx\tt \verb|boxit|&    suffix, picture&        --&     \pageref{Dboxit}&
+        Define a box containing the picture\\\hline
+\bx\tt \verb|boxit|&    suffix, string& --&     \pageref{Dsboxit}&
+        Define a box containing text\\\hline
+\bx\tt \verb|boxit|&    suffix, \tdescr{empty}& --&     \pageref{Deboxit}&
+        Define an empty box\\\hline
+\bx\tt \verb|boxjoin|&  equations&      --&     \pageref{Dbxjoin}&
+        Give equations for connecting boxes\\\hline
+\bx\tt \verb|bpath|&    suffix& path&   \pageref{Dbpath}&
+        A box's bounding circle or rectangle\\\hline
+\pl\tt \verb|buildcycle|&       list of paths&  path&   \pageref{buildcy}&
+        Build a cyclic path\\\hline
+\bx\tt \verb|circleit|& suffix, picture&        --&     \pageref{Dcircit}&
+        Put picture in a circular box\\\hline
+\bx\tt \verb|circleit|& suffix, picture&        --&     \pageref{Dcircit}&
+        Put a string in a circular box\\\hline
+\bx\tt \verb|circleit|& suffix, \tdescr{empty}& --&     \pageref{Dcircit}&
+        Define an empty circular box\\\hline
+\pl\tt \verb|dashpattern|&      on/off distances&       picture&        \pageref{Ddshpat}&
+        Create a pattern for dashed lines\\\hline
+\pl\tt \verb|decr|&     numeric variable&       numeric&        \pageref{Dincr}&
+        Decrement and return new value\\\hline
+\pl\tt \verb|dotlabel|& suffix, picture, pair&  --&     \pageref{Ddotlab}&
+        Mark point and draw picture nearby\\\hline
+\pl\tt \verb|dotlabel|& suffix, string, pair&   --&     \pageref{Ddotlab}&
+        Mark point and place text nearby\\\hline
+\pl\tt \verb|dotlabels|&        suffix, point numbers&  --&     \pageref{Ddotlbs}&
+        Mark {\tt z} points with their numbers\\\hline
+\bx\tt \verb|drawboxed|&        list of suffixes&       --&     \pageref{Ddrbxed}&
+        Draw the named boxes and their\\
+&       &       &       &
+        contents\\\hline
+\bx\tt \verb|drawboxes|&        list of suffixes&       --&     \pageref{Ddrbxes}&
+        Draw the named boxes\\\hline
+\pl\tt \verb|drawoptions|&      drawing options&        --&     \pageref{Ddropts}&
+        Set options for drawing commands\\\hline
+\bx\tt \verb|drawunboxed|&      list of suffixes&       --&     \pageref{Ddrunbx}&
+        Draw contents of named boxes\\\hline
+\bx\tt \verb|fixpos|&   list of suffixes&       --&     \pageref{Dfixpos}&
+        Solve for the size and position of the\\
+&       &       &       &
+        named boxes\\\hline
+\bx\tt \verb|fixsize|&  list of suffixes&       --&     \pageref{Dfixsiz}&
+        Solve for size of named boxes\\\hline
+\pl\tt \verb|incr|&     numeric variable&       numeric&        \pageref{Dincr}&
+        Increment and return new value\\\hline
+\pl\tt \verb|label|&    suffix, picture, pair&  --&     \pageref{Dlabel}&
+        Draw picture near given point\\\hline
+\pl\tt \verb|label|&    suffix, string, pair&   --&     \pageref{Dlabel}&
+        Place text near given point\\\hline
+\pl\tt \verb|labels|&   suffix, point numbers&  --&     \pageref{Dlabels}&
+        Draw {\tt z} point numbers; no dots\\\hline
+\pl\tt \verb|max|&      list of numerics&       numeric&        --&
+        Find the maximum\\\hline
+\pl\tt \verb|max|&      list of strings&        string& --&
+        Find the lexicographically last string\\\hline
+\pl\tt \verb|min|&      list of numerics&       numeric&        --&
+        Find the minimum\\\hline
+\pl\tt \verb|min|&      list of strings&        string& --&
+        Find the lexicographically first string\\\hline
+\bx\tt \verb|pic|&      suffix& picture&        \pageref{Dpic}&
+        Box contents shifted into position\\\hline
+\pl\tt \verb|thelabel|& suffix, picture, pair&  picture&        \pageref{Dthelab}&
+        Picture shifted as if to label a point\\\hline
+\pl\tt \verb|thelabel|& suffix, string, pair&   picture&        \pageref{Dthelab}&
+        text positioned as if to label a point\\\hline
+\pl\tt \verb|z|&        suffix& pair&   \pageref{Dzconv}&
+        The pair ${\tt x}\descr{suffix},{\tt y}\descr{suffix})$\\\hline
+\end{tabular}
+$$
+\index{min?\texttt{min}}\index{max?\texttt{max}}%
+\label{pseudotab}
+\end{table}
+
+\clearpage
+
+\begin{figure}[htp]
+\begin{ctabbing}
+$\tt \descr{atom} \rightarrow \descr{variable} \;|\; \descr{argument}$\\
+$\tt \qquad \;|\; \descr{number or fraction}$\\
+$\tt \qquad \;|\; \descr{internal variable}$\\
+$\tt \qquad \;|\; \hbox{\tt (}\descr{expression}\hbox{\tt )}$\\
+$\tt \qquad \;|\; begingroup \descr{statement list} \descr{expression} endgroup$\\
+$\tt \qquad \;|\; \descr{nullary op}$\\
+$\tt \qquad \;|\; btex \descr{typesetting commands} etex$\\
+$\tt \qquad \;|\; \descr{pseudo function}$\\
+$\tt \descr{primary} \rightarrow \descr{atom}$\\
+$\tt \qquad \;|\; \hbox{\tt (}\descr{numeric expression}\hbox{\tt ,} \descr{numeric expression}\hbox{\tt )}$\\
+$\tt \qquad \;|\; \hbox{\tt (}\descr{numeric expression}\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 \qquad \;|\; str \descr{suffix}$\\
+$\tt \qquad \;|\; z \descr{suffix}$\\
+$\tt \qquad \;|\; \descr{numeric atom}\hbox{\tt [}\descr{expression}\hbox{\tt ,}\descr{expression}\hbox{\tt ]}$\\
+$\tt \qquad \;|\; \descr{scalar multiplication op} \descr{primary}$\\
+$\tt \descr{secondary} \rightarrow \descr{primary}$\\
+$\tt \qquad \;|\; \descr{secondary} \descr{primary binop} \descr{primary}$\\
+$\tt \qquad \;|\; \descr{secondary} \descr{transformer}$\\
+$\tt \descr{tertiary} \rightarrow \descr{secondary}$\\
+$\tt \qquad \;|\; \descr{tertiary} \descr{secondary binop} \descr{secondary}$\\
+$\tt \descr{subexpression} \rightarrow \descr{tertiary}$\\
+$\tt \qquad \;|\; \descr{path expression} \descr{path join} \descr{path knot}$\\
+$\tt \descr{expression} \rightarrow \descr{subexpression}$\\
+$\tt \qquad \;|\; \descr{expression} \descr{tertiary binop} \descr{tertiary}$\\
+$\tt \qquad \;|\; \descr{path subexpression} \descr{direction specifier}$\\
+$\tt \qquad \;|\; \descr{path subexpression} \descr{path join} cycle$\\
+$\tt $\\
+$\tt \descr{path knot} \rightarrow \descr{tertiary}$\\
+$\tt \descr{path join} \rightarrow --$\\
+$\tt \qquad \;|\; \descr{direction specifier} \descr{basic path join} \descr{direction specifier}$\\
+$\tt \descr{direction specifier} \rightarrow \descr{empty}$\\
+$\tt \qquad \;|\; \char`\{curl \descr{numeric expression}\char`\}$\\
+$\tt \qquad \;|\; \char`\{\descr{pair expression}\char`\}$\\
+$\tt \qquad \;|\; \char`\{\descr{numeric expression}\hbox{\tt ,}\descr{numeric expression}\char`\}$\\
+$\tt \descr{basic path join} \rightarrow \hbox{\tt ..} \;|\; \hbox{\tt ...} \;|\; \hbox{\tt ..}\descr{tension}\hbox{\tt ..} \;|\; \hbox{\tt ..}\descr{controls}\hbox{\tt ..}$\\
+$\tt \descr{tension} \rightarrow tension \descr{numeric primary}$\\
+$\tt \qquad \;|\; tension \descr{numeric primary} and \descr{numeric primary}$\\
+$\tt \descr{controls} \rightarrow controls \descr{pair primary}$\\
+$\tt \qquad \;|\; controls \descr{pair primary} and \descr{pair primary}$\\
+$\tt $\\
+$\tt \descr{argument} \rightarrow \descr{symbolic token}$\\
+$\tt \descr{number or fraction} \rightarrow \descr{number}\hbox{\tt /}\descr{number}$\\
+$\tt \qquad \;|\; \descr{number not followed by `\hbox{\tt /}\tdescr{number}'}$\\
+$\tt \descr{scalar multiplication op} \rightarrow + \;|\; -$\\
+$\tt \qquad \;|\; \descr{`\tdescr{number or fraction}' not followed by `\tdescr{add op}\tdescr{number}'}$
+\end{ctabbing}
+\caption{Part 1 of the syntax for expressions}
+\index{expression?\tdescr{expression}}\index{nullary op?\tdescr{nullary op}}\index{of operator?\tdescr{of operator}}%
+\index{path knot?\tdescr{path knot}}\index{primary?\tdescr{primary}}\index{primary binop?\tdescr{primary binop}}%
+\index{secondary?\tdescr{secondary}}\index{secondary binop?\tdescr{secondary binop}}\index{suffix?\tdescr{suffix}}%
+\index{tertiary?\tdescr{tertiary}}\index{tertiary binop?\tdescr{tertiary binop}}\index{unary op?\tdescr{unary op}}%
+\label{syexpr1}
+\end{figure}
+
+\begin{figure}[htp]
+\begin{ctabbing}
+$\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 )}$\\
+$\tt $\\
+$\tt \descr{nullary op} \rightarrow false \;|\; normaldeviate \;|\; nullpicture \;|\; pencircle$\\
+$\tt \qquad \;|\; true \;|\; whatever$\\
+$\tt \descr{unary op} \rightarrow \descr{type}$\\
+$\tt \qquad \;|\; abs \;|\; angle \;|\; arclength \;|\; ASCII \;|\; bbox \;|\; bluepart \;|\; bot \;|\; ceiling$\\
+$\tt \qquad \;|\; center \;|\; char \;|\; cosd \;|\; cycle \;|\; decimal \;|\; dir \;|\; floor \;|\; fontsize$\\
+$\tt \qquad \;|\; greenpart \;|\; hex \;|\; inverse \;|\; known \;|\; length \;|\; lft \;|\; llcorner$\\
+$\tt \qquad \;|\; lrcorner\;|\; makepath \;|\; makepen \;|\; mexp \;|\; mlog \;|\; not \;|\; oct \;|\; odd$\\
+$\tt \qquad \;|\; redpart \;|\; reverse \;|\; round \;|\; rt \;|\; sind \;|\; sqrt \;|\; top \;|\; ulcorner$\\
+$\tt \qquad \;|\; uniformdeviate \;|\; unitvector \;|\; unknown \;|\; urcorner \;|\; xpart \;|\; xxpart$\\
+$\tt \qquad \;|\; xypart \;|\; ypart \;|\; yxpart \;|\; yypart$\\
+$\tt \descr{type} \rightarrow boolean \;|\; color \;|\; numeric \;|\; pair$\\
+$\tt \qquad \;|\; path \;|\; pen \;|\; picture \;|\; string \;|\; transform$\\
+$\tt \descr{primary binop} \rightarrow \hbox{\tt *} \;|\; \hbox{\tt /} \;|\; \hbox{\tt **} \;|\; and$\\
+$\tt \qquad \;|\; dotprod \;|\; div \;|\; infont \;|\; mod$\\
+$\tt \descr{secondary binop} \rightarrow + \;|\; - \;|\; ++ \;|\; +-+ \;|\; or$\\
+$\tt \qquad \;|\; intersectionpoint \;|\; intersectiontimes$\\
+$\tt \descr{tertiary binop} \rightarrow \hbox{\tt \&} \;|\; \hbox{\verb|<|} \;|\; \hbox{\verb|<=|} \;|\; \hbox{\verb|<>|} \;|\; \hbox{\tt =} \;|\; \hbox{\verb|>|} \;|\; \hbox{\verb|>=|}$\\
+$\tt \qquad \;|\; cutafter \;|\; cutbefore$\\
+$\tt \descr{of operator} \rightarrow arctime \;|\; direction \;|\; directiontime \;|\; directionpoint$\\
+$\tt \qquad \;|\; penoffset \;|\; point \;|\; postcontrol \;|\; precontrol \;|\; subpath$\\
+$\tt \qquad \;|\; substring$\\
+$\tt $\\
+$\tt \descr{variable} \rightarrow \descr{tag}\descr{suffix}$\\
+$\tt \descr{suffix} \rightarrow \descr{empty} \;|\; \descr{suffix}\descr{subscript} \;|\; \descr{suffix}\descr{tag}$\\
+$\tt \qquad \;|\; \descr{suffix parameter}$\\
+$\tt \descr{subscript} \rightarrow \descr{number} \;|\; \hbox{\tt [}\descr{numeric expression}\hbox{\tt ]}$\\
+$\tt $\\
+$\tt \descr{internal variable} \rightarrow ahangle \;|\; ahlength \;|\; bboxmargin$\\
+$\tt \qquad \;|\; charcode \;|\; day \;|\; defaultpen \;|\; defaultscale \;|\; labeloffset$\\
+$\tt \qquad \;|\; linecap \;|\; linejoin \;|\; miterlimit \;|\; month \;|\; pausing$\\
+$\tt \qquad \;|\; prologues \;|\; showstopping \;|\; time \;|\; tracingoutput$\\
+$\tt \qquad \;|\; tracingcapsules \;|\; tracingchoices \;|\; tracingcommands$\\
+$\tt \qquad \;|\; tracingequations \;|\; tracinglostchars \;|\; tracingmacros$\\
+$\tt \qquad \;|\; tracingonline \;|\; tracingrestores \;|\; tracingspecs$\\
+$\tt \qquad \;|\; tracingstats \;|\; tracingtitles \;|\; truecorners$\\
+$\tt \qquad \;|\; warningcheck \;|\; year$\\
+$\tt \qquad \;|\; \descr{symbolic token defined by {\tt newinternal}}$
+\end{ctabbing}
+\caption{Part 2 of the syntax for expressions}
+\index{nullary op?\tdescr{nullary op}}\index{of operator?\tdescr{of operator}}\index{primary binop?\tdescr{primary binop}}%
+\index{secondary binop?\tdescr{secondary binop}}\index{subscript?\tdescr{subscript}}\index{suffix?\tdescr{suffix}}%
+\index{tertiary binop?\tdescr{tertiary binop}}\index{unary op?\tdescr{unary op}}%
+\label{syexpr2}
+\end{figure}
+
+\begin{figure}[htp]
+\begin{ctabbing}
+$\tt \descr{pseudo function} \rightarrow min\hbox{\tt (}\descr{expression list}\hbox{\tt )}$\\
+$\tt \qquad \;|\; max\hbox{\tt (}\descr{expression list}\hbox{\tt )}$\\
+$\tt \qquad \;|\; incr\hbox{\tt (}\descr{numeric variable}\hbox{\tt )}$\\
+$\tt \qquad \;|\; decr\hbox{\tt (}\descr{numeric variable}\hbox{\tt )}$\\
+$\tt \qquad \;|\; dashpattern\hbox{\tt (}\descr{on\hbox{\tt /}off list}\hbox{\tt )}$\\
+$\tt \qquad \;|\; interpath\hbox{\tt (}\descr{numeric expression}\hbox{\tt ,} \descr{path expression}\hbox{\tt ,} \descr{path expression}\hbox{\tt )}$\\
+$\tt \qquad \;|\; buildcycle\hbox{\tt (}\descr{path expression list}\hbox{\tt )}$\\
+$\tt \qquad \;|\; thelabel\descr{label suffix}\hbox{\tt (}\descr{expression}\hbox{\tt ,} \descr{pair expression}\hbox{\tt )}$\\
+$\tt \descr{path expression list} \rightarrow \descr{path expression}$\\
+$\tt \qquad \;|\; \descr{path expression list}\hbox{\tt ,} \descr{path expression}$\\
+$\tt \descr{on\hbox{\tt /}off list} \rightarrow \descr{on\hbox{\tt /}off list}\descr{on\hbox{\tt /}off clause} \;|\; \descr{on\hbox{\tt /}off clause}$\\
+$\tt \descr{on\hbox{\tt /}off clause} \rightarrow on \descr{numeric tertiary} \;|\; off \descr{numeric tertiary}$
+\end{ctabbing}
+\caption{The syntax for function-like macros}
+\index{label suffix?\tdescr{label suffix}}%
+\label{sypseudo}
+\end{figure}
+
+\begin{figure}[htp]
+\begin{ctabbing}
+$\tt \descr{boolean expression} \rightarrow \descr{expression}$\\
+$\tt \descr{color expression} \rightarrow \descr{expression}$\\
+$\tt \descr{numeric atom} \rightarrow \descr{atom}$\\
+$\tt \descr{numeric expression} \rightarrow \descr{expression}$\\
+$\tt \descr{numeric primary} \rightarrow \descr{primary}$\\
+$\tt \descr{numeric tertiary} \rightarrow \descr{tertiary}$\\
+$\tt \descr{numeric variable} \rightarrow \descr{variable} \;|\; \descr{internal variable}$\\
+$\tt \descr{pair expression} \rightarrow \descr{expression}$\\
+$\tt \descr{pair primary} \rightarrow \descr{primary}$\\
+$\tt \descr{path expression} \rightarrow \descr{expression}$\\
+$\tt \descr{path subexpression} \rightarrow \descr{subexpression}$\\
+$\tt \descr{pen expression} \rightarrow \descr{expression}$\\
+$\tt \descr{picture expression} \rightarrow \descr{expression}$\\
+$\tt \descr{picture variable} \rightarrow \descr{variable}$\\
+$\tt \descr{string expression} \rightarrow \descr{expression}$\\
+$\tt \descr{suffix parameter} \rightarrow \descr{parameter}$\\
+$\tt \descr{transform primary} \rightarrow \descr{primary}$
+\end{ctabbing}
+\caption{Miscellaneous productions needed to complete the BNF}
+\label{sytypexpr}
+\end{figure}
+
+\begin{figure}[htp]
+\begin{ctabbing}
+$\tt \descr{program} \rightarrow \descr{statement list} end$\\
+$\tt \descr{statement list} \rightarrow \descr{empty} \;|\; \descr{statement list} \hbox{\tt ;} \descr{statement}$\\
+$\tt \descr{statement} \rightarrow \descr{empty}$\\
+$\tt \qquad \;|\; \descr{equation} \;|\; \descr{assignment}$\\
+$\tt \qquad \;|\; \descr{declaration} \;|\; \descr{macro definition}$\\
+$\tt \qquad \;|\; \descr{compound} \;|\; \descr{pseudo procedure}$\\
+$\tt \qquad \;|\; \descr{command}$\\
+$\tt \descr{compound} \rightarrow begingroup \descr{statement list} endgroup$\\
+$\tt \qquad \;|\; beginfig\hbox{\tt (}\descr{numeric expression}\hbox{\tt );} \descr{statement list}\hbox{\tt ;} endfig$\\
+$\tt $\\
+$\tt \descr{equation} \rightarrow \descr{expression} \hbox{\tt =} \descr{right-hand side}$\\
+$\tt \descr{assignment} \rightarrow \descr{variable} \hbox{\tt :=} \descr{right-hand side}$\\
+$\tt \qquad \;|\; \descr{internal variable} \hbox{\tt :=} \descr{right-hand side}$\\
+$\tt \descr{right-hand side} \rightarrow \descr{expression} \;|\; \descr{equation} \;|\; \descr{assignment}$\\
+$\tt $\\
+$\tt \descr{declaration} \rightarrow \descr{type} \descr{declaration list}$\\
+$\tt \descr{declaration list} \rightarrow \descr{generic variable}$\\
+$\tt \qquad \;|\; \descr{declaration list}\hbox{\tt ,} \descr{generic variable}$\\
+$\tt \descr{generic variable} \rightarrow \descr{symbolic token} \descr{generic suffix}$\\
+$\tt \descr{generic suffix} \rightarrow \descr{empty} \;|\; \descr{generic suffix} \descr{tag}$\\
+$\tt \qquad \;|\; \descr{generic suffix} \hbox{\tt []}$\\
+$\tt $\\
+$\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{\verb|@#|} \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 \;|\; tertiarydef$\\
+$\tt $\\
+$\tt \descr{pseudo procedure} \rightarrow drawoptions\hbox{\tt (}\descr{option list}\hbox{\tt )}$\\
+$\tt \qquad \;|\; label\descr{label suffix}\hbox{\tt (}\descr{expression}\hbox{\tt ,} \descr{pair expression}\hbox{\tt )}$\\
+$\tt \qquad \;|\; dotlabel\descr{label suffix}\hbox{\tt (}\descr{expression}\hbox{\tt ,} \descr{pair expression}\hbox{\tt )}$\\
+$\tt \qquad \;|\; labels\descr{label suffix}\hbox{\tt (}\descr{point number list}\hbox{\tt )}$\\
+$\tt \qquad \;|\; dotlabels\descr{label suffix}\hbox{\tt (}\descr{point number list}\hbox{\tt )}$\\
+$\tt \descr{point number list} \rightarrow \descr{suffix} \;|\; \descr{point number list}\hbox{\tt ,} \descr{suffix}$\\
+$\tt \descr{label suffix} \rightarrow \descr{empty} \;|\; lft \;|\; rt \;|\; top \;|\; bot \;|\; ulft \;|\; urt \;|\; llft \;|\; lrt$
+\end{ctabbing}
+\caption{Overall syntax for MetaPost programs}
+\index{generic variable?\tdescr{generic variable}}\index{label suffix?\tdescr{label suffix}}\index{replacement text?\tdescr{replacement text}}%
+\index{suffix?\tdescr{suffix}}%
+\label{syprog}
+\end{figure}
+
+\begin{figure}[htp]
+\begin{ctabbing}
+$\tt \descr{command} \rightarrow clip \descr{picture variable} to \descr{path expression}$\\
+$\tt \qquad \;|\; interim \descr{internal variable} \hbox{\tt :=} \descr{right-hand side}$\\
+$\tt \qquad \;|\; let \descr{symbolic token} \hbox{\tt =} \descr{symbolic token}$\\
+$\tt \qquad \;|\; newinternal \descr{symbolic token list}$\\
+$\tt \qquad \;|\; pickup \descr{expression}$\\
+$\tt \qquad \;|\; randomseed \hbox{\tt :=} \descr{numeric expression}$\\
+$\tt \qquad \;|\; save \descr{symbolic token list}$\\
+$\tt \qquad \;|\; setbounds \descr{picture variable} to \descr{path expression}$\\
+$\tt \qquad \;|\; shipout \descr{picture expression}$\\
+$\tt \qquad \;|\; special \descr{string expression}$\\
+$\tt \qquad \;|\; \descr{addto command}$\\
+$\tt \qquad \;|\; \descr{drawing command}$\\
+$\tt \qquad \;|\; \descr{font metric command}$\\
+$\tt \qquad \;|\; \descr{show command}$\\
+$\tt \qquad \;|\; \descr{tracing command}$\\
+$\tt $\\
+$\tt \descr{show command} \rightarrow show \descr{expression list}$\\
+$\tt \qquad \;|\; showvariable \descr{symbolic token list}$\\
+$\tt \qquad \;|\; showtoken \descr{symbolic token list}$\\
+$\tt \qquad \;|\; showdependencies$\\
+$\tt $\\
+$\tt \descr{symbolic token list} \rightarrow \descr{symbolic token}$\\
+$\tt \qquad \;|\; \descr{symbolic token}\hbox{\tt ,} \descr{symbolic token list}$\\
+$\tt \descr{expression list} \rightarrow \descr{expression} \;|\; \descr{expression list}\hbox{\tt ,} \descr{expression}$\\
+$\tt $\\
+$\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 \;|\; withpen \descr{pen expression} \;|\; dashed \descr{picture expression}$\\
+$\tt $\\
+$\tt \descr{drawing command} \rightarrow draw \descr{picture expression} \descr{option list}$\\
+$\tt \qquad \;|\; \descr{fill type} \descr{path expression} \descr{option list}$\\
+$\tt \descr{fill type} \rightarrow fill \;|\; draw \;|\; filldraw \;|\; unfill \;|\; undraw \;|\; unfilldraw$\\
+$\tt \qquad \;|\; drawarrow \;|\; drawdblarrow \;|\; cutdraw$\\
+$\tt $\\
+$\tt \descr{tracing command} \rightarrow tracingall \;|\; loggingall \;|\; tracingnone$
+\end{ctabbing}
+\caption{The syntax for commands}
+\index{option list?\tdescr{option list}}\index{picture variable?\tdescr{picture variable}}%
+\label{sycmds}
+\end{figure}
+
+\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}$\\
+$\tt $\\
+$\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 conditionals and loops}
+\index{balanced tokens?\tdescr{balanced tokens}}\index{suffix?\tdescr{suffix}}%
+\label{sycondloop}
+\end{figure}
+
+\clearpage
+
+\let\topfraction=\svtopfrac     % restore values from the start of this appendix
+\let\textfraction=\svtxtfrac
+\setcounter{topnumber}{\value{svtopnum}}
+\setcounter{totalnumber}{\value{svtotnum}}
+
+
+\section{MetaPost Versus METAFONT}
+\label{MPvsMF}
+
+Since the \MF\index{metafont?\MF} and MetaPost languages have so much in common, expert
+users of \MF\ will want to skip most of the explanations in this document and
+concentrate on concepts that are unique to MetaPost.  The comparisons in this
+appendix are intended to help experts that are familiar with {\it The\ \MF book}
+as well as other users that want to benefit from Knuth's more detailed
+explanations \cite{kn:c}.
+
+Since \MF\ is intended for making \TeX\ fonts, it has a number of primitives for
+generating the {\tt tfm}\index{tfm file?{\tt tfm} file}\index{files!tfm?{\tt tfm}} files that
+\TeX\ needs for character dimensions, spacing information,
+ligatures\index{ligatures} and kerning\index{kerning}.  MetaPost can also be
+used for generating fonts, and it also has \MF's primitives for making
+{\tt tfm} files.  These are listed in Table~\ref{tfmprim}.  Explanations can be
+found in the \MF\ documentation \cite{kn:c,kn:mf3}
+
+\begin{table}[htp]
+$$\begin{tabular}{|l|l|}  \hline
+commands&               {\tt charlist}, {\tt extensible},
+                        {\tt fontdimen}, {\tt headerbyte}               \\
+        &               {\tt kern}, {\tt ligtable}                      \\ \hline
+ligtable operators&     \verb!::!, \verb!=:!, \verb!=:|!, \verb!=:|>!,
+                        \verb!|=:!, \verb!|=:>!,                        \\
+        &               \verb!|=:|!, \verb!|=:|>!, \verb!|=:|>>!,
+                        \verb!||:!                                      \\ \hline
+internal variables\index{internal variables}\index{variables!internal}&
+                        {\tt boundarychar}, {\tt chardp},
+                        {\tt charext}, {\tt charht},                    \\
+        &               {\tt charic}, {\tt charwd},
+                        {\tt designsize}, {\tt fontmaking}              \\ \hline
+other operators&        {\tt charexists}                                \\ \hline
+\end{tabular}
+$$
+\caption{MetaPost primitives for making {\tt tfm} files.}
+\label{tfmprim}
+\end{table}
+
+Even though MetaPost has the primitives for generating fonts, many of the
+font-making primitives and internal variables that are part of Plain
+\MF\index{metafont?\MF} are not defined in Plain MetaPost\index{Plain macros}.  Instead,
+there is a separate macro package called {\tt mfplain}\index{mfplain?\texttt{mfplain}} that
+defines the macros required to allow MetaPost to process Knuth's Computer Modern
+fonts as shown in Table~\ref{mfponly} \cite{kn:e}.
+To load these macros, put ``\verb|&mfplain|'' before the name of the
+input file.  This can be done at the {\tt **} prompt after invoking the MetaPost
+interpreter with no arguments, or on a command line that looks something like
+this:\footnote{Command line syntax is system dependent.  Quotes are needed on
+most Unix\reg systems to protect special characters like {\tt\&}.}
+$$ \hbox{\verb|mp '&mfplain' cmr10|} $$
+The analog of a \MF\ command line like
+$$ \hbox{\verb|mf '\mode=lowres; mag=1.2; input cmr10'|} $$
+is
+$$ \hbox{\verb|mp '&mfplain \mode=lowres; mag=1.2; input cmr10'|} $$
+The result is a set of PostScript files, one for each character in the font.
+Some editing would be required in order to merge them into a downloadable Type~3
+PostScript font \cite{ad:red}.
+
+\begin{table}[htp]
+$$
+\renewcommand{\FancyVerbFormatLine}[1]{\hbox{#1}\strut}
+\begin{tabular}{|l|} \hline
+\multicolumn 1{|c|}
+{Defined in the {\tt mfplain} package}          \\ \hline
+\begin{verbatim}
+beginchar                              font_identifier
+blacker                                font_normal_shrink
+capsule_def                            font_normal_space
+change_width                           font_normal_stretch
+define_blacker_pixels                  font_quad
+define_corrected_pixels                font_size
+define_good_x_pixels                   font_slant
+define_good_y_pixels                   font_x_height
+define_horizontal_corrected_pixels     italcorr
+define_pixels                          labelfont
+define_whole_blacker_pixels            makebox
+define_whole_pixels                    makegrid
+define_whole_vertical_blacker_pixels   maketicks
+define_whole_vertical_pixels           mode_def
+endchar                                mode_setup
+extra_beginchar                        o_correction
+extra_endchar                          proofrule
+extra_setup                            proofrulethickness
+font_coding_scheme                     rulepen
+font_extra_space                       smode
+\end{verbatim}
+                                               \\ \hline
+\multicolumn 1{|c|}
+{Defined as no-ops in the {\tt mfplain} package}\\ \hline
+\begin{verbatim}
+cullit                                 proofoffset
+currenttransform                       screenchars
+gfcorners                              screenrule
+grayfont                               screenstrokes
+hround                                 showit
+imagerules                             slantfont
+lowres_fix                             titlefont
+nodisplays                             unitpixel
+notransforms                           vround
+openit
+\end{verbatim}
+                                       \\ \hline
+\end{tabular}
+\renewcommand{\FancyVerbFormatLine}[1]{#1}
+$$
+\caption{Macros and internal variables defined only in the {\tt mfplain} package.}
+\label{mfponly}
+\end{table}
+
+Another limitation of the {\tt mfplain} package is that certain internal
+variables from Plain \MF\index{metafont?\MF} cannot be given reasonable MetaPost
+definitions.  These include {\tt displaying}, {\tt currentwindow},
+\verb|screen_rows|, and \verb|screen_cols| which depend on \MF's ability to
+display images on the computer screen.  In addition, \verb|pixels_per_inch| is
+irrelevant since MetaPost uses fixed units of PostScript points.
+
+The reason why some macros and
+internal variables\index{internal variables}\index{variables!internal}
+are not meaningful in MetaPost
+is that \MF\ primitive commands {\tt cull}, {\tt display}, {\tt openwindow},
+{\tt numspecial} and {\tt totalweight} are not implemented in MetaPost.  Also not
+implemented are a number of internal variables as well as the
+\tdescr{drawing option} {\tt withweight}.  Here is a complete listing of the
+internal variables whose primitive meanings in \MF\ do not make sense in MetaPost:
+$$\begin{verbatim}
+autorounding fillin       proofing     tracingpens   xoffset
+chardx       granularity  smoothing    turningcheck  yoffset
+chardy       hppp         tracingedges vppp
+\end{verbatim}
+$$
+
+There is also one \MF\ primitive that has a slightly different meaning in
+MetaPost.  Both languages allow statements of the
+form\index{special?\texttt{special}}\label{Dspecl}
+$$ {\tt special}\, \descr{string expression} \hbox{\tt;} $$
+but \MF\ copies the string into its ``generic font'' output file, while
+MetaPost interprets the string as a sequence of PostScript commands that are
+to be placed at the beginning of the next output file.
+
+All the other differences between \MF\ and MetaPost are features found only in
+MetaPost.  These are listed in Table~\ref{mponly}.  The only commands listed
+in this table that the preceding sections do not discuss are
+\verb|extra_beginfig|\index{extra_beginfig?\texttt{extra\_beginfig}}\label{Dxbfig},
+\verb|extra_endfig|\index{extra_endfig?\texttt{extra\_endfig}}\label{Dxefig}, and {\tt mpxbreak}.
+The first two are strings that contain extra commands to be processed
+by {\tt beginfig}\index{beginfig?\texttt{beginfig}} and {\tt endfig}\index{endfig?\texttt{endfig}}
+just as \verb|extra_beginchar| and \verb|extra_endchar| are processed by
+{\tt beginchar} and {\tt endchar}.
+(The file {\tt boxes.mp}\index{boxes.mp?\texttt{boxes.mp}} uses these features).
+
+The other new feature listed in Table~\ref{mponly} not listed in the index
+is {\tt mpxbreak}\index{mpxbreak?\texttt{mpxbreak}}.  This is used to separate blocks of
+translated \TeX\index{TeX?\TeX} or troff\index{troff} commands in
+{\tt mpx}\index{files!mpx?{\tt mpx}} files. It should be of no concern to
+users since {\tt mpx} files are generated automatically.
+
+\begin{table}[htp]
+$$
+\renewcommand{\FancyVerbFormatLine}[1]{\hbox{#1}\strut}
+\begin{tabular}{|l|} \hline
+\multicolumn 1{|c|}
+{MetaPost primitives not found in \MF}          \\ \hline
+$\begin{verbatim}
+bluepart         infont           redpart
+btex             linecap          setbounds
+clip             linejoin         tracinglostchars
+color            llcorner         truecorners
+dashed           lrcorner         ulcorner
+etex             miterlimit       urcorner
+fontsize         mpxbreak         verbatimtex
+greenpart        prologues        withcolor
+\end{verbatim}
+$                                               \\ \hline
+\multicolumn 1{|c|}
+{Variables and Macros defined only in Plain MetaPost}\\ \hline
+$\begin{verbatim}
+ahangle          cutbefore        extra_beginfig
+ahlength         cuttings         extra_endfig
+background       dashpattern      green
+bbox             defaultfont      label
+bboxmargin       defaultpen       labeloffset
+beginfig         defaultscale     mitered
+beveled          dotlabel         red
+black            dotlabels        rounded
+blue             drawarrow        squared
+buildcycle       drawdblarrow     thelabel
+butt             drawoptions      white
+center           endfig
+cutafter         evenly
+\end{verbatim}
+$                                       \\ \hline
+\end{tabular}
+\renewcommand{\FancyVerbFormatLine}[1]{#1}
+$$
+\caption{Macros and internal variables defined in MetaPost but not \MF.}
+\label{mponly}
+\end{table}
+
+
+
+
+\bibliographystyle{plain}
+\bibliography{mpman}
+
+
+\printindex
+
+
+\end{document}
+
+% Copyright 1990 - 1995 by AT&T Bell Laboratories.
+
+% 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.
diff --git a/Master/texmf-dist/doc/metapost/base/source/timepop.d b/Master/texmf-dist/doc/metapost/base/source/timepop.d
new file mode 100644
index 00000000000..2b1555289c2
--- /dev/null
+++ b/Master/texmf-dist/doc/metapost/base/source/timepop.d
@@ -0,0 +1,21 @@
+1790   3.93
+1800   5.31
+1810   7.24
+1820   9.64
+1830  12.87
+1840  17.07
+1850  23.19
+1860  31.44
+1870  39.82
+1880  50.16
+1890  62.95
+1900  75.99
+1910  91.97
+1920 105.71
+1930 122.78
+1940 131.67
+1950 150.70
+1960 179.32
+1970 203.30
+1980 226.55
+1990 248.71
+\ No newline at end of file
author	Karl Berry <karl@freefriends.org>	2006-01-09 00:45:48 +0000
committer	Karl Berry <karl@freefriends.org>	2006-01-09 00:45:48 +0000
commit	5dc602d16c5be2fd035b254ca23484a90aebd6dc (patch)
tree	72efb15fba318cc2096a8cc6999ed3fa0bff317d /Master/texmf-dist/doc/metapost/base
parent	b4fc5f639874db951177ec539299d20908adb654 (diff)