diff options
Diffstat (limited to 'Master/texmf-dist/doc/metapost/base')
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 Binary files differnew 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&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&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 Binary files differnew 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 Binary files differnew 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 Binary files differnew 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 |