diff options
Diffstat (limited to 'Master/texmf-dist/doc/metapost/base/source-manual')
40 files changed, 16342 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/metapost/base/source-manual/Makefile b/Master/texmf-dist/doc/metapost/base/source-manual/Makefile new file mode 100644 index 00000000000..21eaebfcf74 --- /dev/null +++ b/Master/texmf-dist/doc/metapost/base/source-manual/Makefile @@ -0,0 +1,73 @@ +# Makefile for MetaPost documentation. Public domain. +# Rules for the groff/troff docs are in TeX Live, +# texmf-dist/doc/metapost/base/Makefile. + +latex = latex +pdflatex = pdflatex +dvips = dvips +bibtex = bibtex +mpost = mpost -tex=tex +mkindex = makeindex -c -s mpman.ist + +all: pdf +pdf: mpman.pdf mpgraph.pdf mpboxes.pdf +ps: mpman.ps mpgraph.ps mpboxes.ps + +mpboxes.pdf: mpboxes.tex mpboxes.bib mpboxes.mp + $(mpost) mpboxes + $(pdflatex) mpboxes + $(bibtex) mpboxes + $(pdflatex) mpboxes + $(mkindex) mpboxes + $(pdflatex) mpboxes + +mpgraph.pdf: mpgraph.tex mpgraph.bib mpgraph.mp + $(mpost) mpgraph + $(pdflatex) mpgraph + $(bibtex) mpgraph + $(pdflatex) mpgraph + $(pdflatex) mpgraph + +mpman.pdf: mpman.tex mpman-app-legacy.tex mpman-app-optab.tex mpman-app-refman.tex mpman.bib mpman.ist mpman.mp + $(mpost) mpman + $(pdflatex) mpman + $(bibtex) mpman + $(pdflatex) mpman + $(pdflatex) mpman + $(mkindex) mpman + $(pdflatex) mpman + +mpboxes.ps: mpboxes.tex mpboxes.bib mpboxes.mp + $(mpost) mpboxes + $(latex) mpboxes + $(bibtex) mpboxes + $(latex) mpboxes + $(latex) mpboxes + $(mkindex) mpboxes + $(latex) mpboxes + $(dvips) mpboxes + +mpgraph.ps: mpgraph.tex mpgraph.bib mpgraph.mp + $(mpost) mpgraph + $(latex) mpgraph + $(bibtex) mpgraph + $(latex) mpgraph + $(latex) mpgraph + $(dvips) mpgraph + +mpman.ps: mpman.tex mpman-app-legacy.tex mpman-app-optab.tex mpman-app-refman.tex mpman.bib mpman.ist mpman.mp + $(mpost) mpman + $(latex) mpman + $(bibtex) mpman + $(latex) mpman + $(latex) mpman + $(mkindex) mpman + $(latex) mpman + $(dvips) mpman + +clean: + rm -f *.aux *.bbl *.blg *.dvi *.log *.mpx *.mps + rm -f *.idx *.ilg *.ind *.toc *.out + +distclean: clean + rm -f mp*.pdf mp*.ps diff --git a/Master/texmf-dist/doc/metapost/base/source-manual/README b/Master/texmf-dist/doc/metapost/base/source-manual/README new file mode 100644 index 00000000000..61cdd102fc8 --- /dev/null +++ b/Master/texmf-dist/doc/metapost/base/source-manual/README @@ -0,0 +1,60 @@ +Public domain. + +This is the source for the documentation for MetaPost, consisting of +"A User's Manual for MetaPost", "Drawing Boxes with MetaPost", +"Drawing Graphs with MetaPost" and the introductory article "The +MetaPost System", written by John D. Hobby. +They were converted to more modern LaTeX by Dylan Thurston and are +currently maintained by Troy Henderson and Stephan Hennig. 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. +Auxiliary files (and the MetaPost software itself) are public domain, +including the data (.d) files here, which due to file format limitations +cannot incorporate a license themselves. + +Included files: + +Makefile +README +TODO +agepop91.d +agepopm.d +cm2lm.map +countries.d +ctabbing.sty +demo.ms +energy.d +figs.1 +figs.mp +grdemo-doc.ms +grdemo-doc.pdf +grdemo-doc.ps +grdemo.eps +grdemo.mp +grdemo.ms +grdemo.pdf +lead.d +matmul.d +mp.1 +mpboxes.bib +mpboxes.mp +mpboxes.tex +mpgraph.bib +mpgraph.mp +mpgraph.tex +mpintro.bib +mpintro.mp +mpintro.tex +mpman-optab.tex +mpman.bib +mpman.ist +mpman.mp +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-manual/TODO b/Master/texmf-dist/doc/metapost/base/source-manual/TODO new file mode 100644 index 00000000000..4aea80f9d41 --- /dev/null +++ b/Master/texmf-dist/doc/metapost/base/source-manual/TODO @@ -0,0 +1,77 @@ +This file contains an unsorted list of tasks to be done on the
+MetaPost manual. Feel free to add new, move or remove finished
+items.
+
+Where to put new items?
+-----------------------
+Section 'Wanted For Release' contains items that we want to be
+finished before the next release. Even minor issues can and
+should be added here.
+
+Items in section 'Mid Term Issues' have no dead-line, but should
+be self-contained enough to be done independent from other stuff.
+
+Items in section 'Long Term Issues' are less actively worked on.
+The reason they are less actively worked on is not lack of
+importance, but lack of developer resources. Nevertheless, they
+are on the agenda. Contributions are welcome!
+
+How to pick items?
+------------------
+You can indicate interest or active work on an item by putting your
+initials in parenthese in front of that item and checking the
+modified TODO file into the repository. That way, anybody who is
+subscribed to the metapost-commits list is notified of your
+interest. Additionally, it is wise to communicate that you're
+working on an issue (you didn't remember adding yourself) on the
+mp-implementors list or alternatively the metapost list.
+
+
+*****************************
+*** Wanted For Release ***
+*****************************
+
+mpman.tex
+* Describe environment variables.
+* Add note on postcontrol and precontrol when discussing control points.
+* Add description of interaction mode commands.
+
+
+
+
+*****************************
+*** Mid Term Issues ***
+*****************************
+
+* Revise introduction.
+* Move prologues discussion to section 3.
+* More information and examples on alternatives for calling TeX
+ or LaTeX from within MetaPost.
+* (SH) Revise (and add more) flow charts for MetaPost workflow.
+* Information on using MetaPost from within LaTeX (emp), ConTeXt
+ and LuaTeX.
+* Why is verbatimtex\end{document}etex "safer", cf. sec. 13.1?
+* Discuss difference between "draw <pic> withpen" and
+ "label(<pic>, ...) withpen" (when label bug is fixed).
+* Add a sub-section discussing colours in section 9.
+* (SH) Colour cars and change code example in section 9.9.
+* Describe mpware in section "Legacy information".
+
+
+
+
+*****************************
+*** Long Term Issues ***
+*****************************
+
+* Add decent title graphics.
+* Review presentation of primitives and plain macros in appendix A.
+* Build reference manual automatically from mp.web (as a separate manual?).
+* Make manual sources compatible with preview mode (Emacs).
+* Make manual sources LaTeX2e conform.
+* Make manual sources look nice in Emacs (AUCTeX font-locking).
+* Review overall layout of the manuals (type area, float placement,
+ listing presentation etc.)
+
+
+
diff --git a/Master/texmf-dist/doc/metapost/base/source-manual/agepop91.d b/Master/texmf-dist/doc/metapost/base/source-manual/agepop91.d new file mode 100644 index 00000000000..2dcd5dc0da3 --- /dev/null +++ b/Master/texmf-dist/doc/metapost/base/source-manual/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 diff --git a/Master/texmf-dist/doc/metapost/base/source-manual/agepopm.d b/Master/texmf-dist/doc/metapost/base/source-manual/agepopm.d new file mode 100644 index 00000000000..7451d4601b5 --- /dev/null +++ b/Master/texmf-dist/doc/metapost/base/source-manual/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 diff --git a/Master/texmf-dist/doc/metapost/base/source-manual/cm2lm.map b/Master/texmf-dist/doc/metapost/base/source-manual/cm2lm.map new file mode 100644 index 00000000000..44228da8144 --- /dev/null +++ b/Master/texmf-dist/doc/metapost/base/source-manual/cm2lm.map @@ -0,0 +1,8 @@ +%%% This map file replaces Computer Modern fonts by Latin Modern.
+cmmi7 CMMI7 < lm-mathit.enc < lmmi7.pfb
+cmmi10 CMMI10 < lm-mathit.enc < lmmi10.pfb
+cmr7 CMR7 < lm-rm.enc < lmr7.pfb
+cmr10 CMR10 < lm-rm.enc < lmr10.pfb
+cmsy7 CMSY7 < lm-mathsy.enc < lmsy7.pfb
+cmsy10 CMSY10 < lm-mathsy.enc < lmsy10.pfb
+cmtt10 CMTT10 < lm-rm.enc < lmtt10.pfb
diff --git a/Master/texmf-dist/doc/metapost/base/source-manual/countries.d b/Master/texmf-dist/doc/metapost/base/source-manual/countries.d new file mode 100644 index 00000000000..2b372f882c9 --- /dev/null +++ b/Master/texmf-dist/doc/metapost/base/source-manual/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 diff --git a/Master/texmf-dist/doc/metapost/base/source-manual/ctabbing.sty b/Master/texmf-dist/doc/metapost/base/source-manual/ctabbing.sty new file mode 100644 index 00000000000..b61ec6ed784 --- /dev/null +++ b/Master/texmf-dist/doc/metapost/base/source-manual/ctabbing.sty @@ -0,0 +1,18 @@ +% Public domain. +% +% 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-manual/demo.ms b/Master/texmf-dist/doc/metapost/base/source-manual/demo.ms new file mode 100644 index 00000000000..736c8641fbd --- /dev/null +++ b/Master/texmf-dist/doc/metapost/base/source-manual/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-manual/energy.d b/Master/texmf-dist/doc/metapost/base/source-manual/energy.d new file mode 100644 index 00000000000..0a8fa42d584 --- /dev/null +++ b/Master/texmf-dist/doc/metapost/base/source-manual/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. diff --git a/Master/texmf-dist/doc/metapost/base/source-manual/examples.mp b/Master/texmf-dist/doc/metapost/base/source-manual/examples.mp new file mode 100644 index 00000000000..2f58ad0f9c4 --- /dev/null +++ b/Master/texmf-dist/doc/metapost/base/source-manual/examples.mp @@ -0,0 +1,251 @@ +% Examples for MetaPost doc, by John Hobby. Public domain. + +filenametemplate "%j-%c.mps"; + +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; +dotlabels.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; +dotlabels.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-manual/figs.1 b/Master/texmf-dist/doc/metapost/base/source-manual/figs.1 new file mode 100644 index 00000000000..b47233e3adb --- /dev/null +++ b/Master/texmf-dist/doc/metapost/base/source-manual/figs.1 @@ -0,0 +1,227 @@ +%!PS-Adobe-3.0 EPSF-3.0 +%%BoundingBox: -6 -13 65 17 +%%Creator: MetaPost +%%CreationDate: 1995.04.06:1004 +%%Pages: 1 +%%DocumentFonts: Times-Roman Times-Italic Symbol + /rptmr /Times-Roman def + /rptmri /Times-Italic def + /rpsyr /Symbol def +/fshow {exch findfont exch scalefont setfont show}bind def +%%EndProlog +%%Page: 1 1 +newpath -2 -4.08002 moveto +29.24002 -4.08002 lineto +29.24002 7.36008 lineto +-2 7.36008 lineto + closepath fill + 1 setgray +newpath -3 -3.08002 moveto +28.24002 -3.08002 lineto +28.24002 8.36008 lineto +-3 8.36008 lineto + closepath fill + 0 setgray +0 0 moveto +(A) rptmr 8.00009 fshow + 0 0.32968 dtransform truncate idtransform setlinewidth pop [] 0 setdash + 1 setlinejoin 10 setmiterlimit +newpath 8.65166 3.8902 moveto +8.65166 4.13197 lineto +8.76155 4.24187 lineto +8.95937 4.24187 lineto +9.04727 4.15395 lineto +9.09123 4.02208 lineto +9.09123 3.95615 lineto +9.04727 3.82426 lineto +8.89342 3.73636 lineto +8.71759 3.7803 lineto +8.65166 3.8902 lineto + closepath stroke +newpath 9.1352 4.26384 moveto +9.1352 4.3078 lineto +9.46486 4.37373 lineto +9.79454 4.4177 lineto +10.12422 4.43967 lineto +10.4539 4.46164 lineto +10.78358 4.48363 lineto +11.11325 4.48363 lineto +11.44293 4.5056 lineto +11.77261 4.5056 lineto +12.1023 4.5056 lineto +12.43198 4.48363 lineto +12.76164 4.46164 lineto +13.09132 4.43967 lineto +13.421 4.3957 lineto +13.75069 4.35176 lineto +14.08037 4.3078 lineto +14.41003 4.26384 lineto +14.73972 4.17592 lineto +15.0694 4.08801 lineto +15.39908 3.97812 lineto +15.72876 3.86823 lineto +16.05843 3.6924 lineto +16.23427 3.56053 lineto +16.3002 3.36272 lineto +16.34415 3.03304 lineto +16.36613 2.7693 lineto +16.3881 2.32973 lineto +16.4101 1.75829 lineto +16.4101 1.62642 lineto +16.3881 1.31871 lineto +16.36613 1.18684 lineto +16.25624 0.94508 lineto +15.94855 0.74727 lineto +15.61887 0.6154 lineto +15.28918 0.54947 lineto +14.9595 0.57144 lineto +14.62982 0.63737 lineto +14.30016 0.68134 lineto +13.97047 0.70331 lineto +13.6408 0.70331 lineto +13.31111 0.65936 lineto +12.98143 0.59341 lineto +12.65176 0.52748 lineto +12.32208 0.50551 lineto +11.9924 0.50551 lineto +11.66272 0.59341 lineto +11.55283 0.74727 lineto +11.55283 1.03299 lineto +11.66272 1.18684 lineto +11.9924 1.27475 lineto +12.32208 1.27475 lineto +12.65176 1.27475 lineto +12.98143 1.29674 lineto +13.26715 1.31871 lineto +13.31111 1.36267 lineto +13.31111 1.47256 lineto +13.20122 1.56047 lineto +12.87154 1.56047 lineto +12.54187 1.5385 lineto +12.21219 1.5385 lineto +11.8825 1.5385 lineto +11.55283 1.5385 lineto +11.22314 1.56047 lineto +11.00337 1.67036 lineto +10.93742 1.84619 lineto +10.93742 2.00005 lineto +10.98138 2.1539 lineto +11.13524 2.28577 lineto +11.46492 2.32973 lineto +11.79459 2.3517 lineto +12.12427 2.3517 lineto +12.45395 2.3517 lineto +12.73967 2.37369 lineto +12.78363 2.41765 lineto +12.78363 2.57149 lineto +12.7177 2.61545 lineto +12.38802 2.61545 lineto +12.05833 2.61545 lineto +11.72865 2.61545 lineto +11.39897 2.61545 lineto +11.0693 2.61545 lineto +10.73962 2.65941 lineto +10.5638 2.81325 lineto +10.51984 3.01106 lineto +10.51984 3.12096 lineto +10.5638 3.29678 lineto +10.73962 3.47261 lineto +11.0693 3.53854 lineto +11.39897 3.53854 lineto +11.72865 3.56053 lineto +12.05833 3.5825 lineto +12.38802 3.5825 lineto +12.49791 3.62646 lineto +12.51988 3.67043 lineto +12.51988 3.75833 lineto +12.47592 3.82426 lineto +12.16823 3.84625 lineto +11.83855 3.84625 lineto +11.50887 3.84625 lineto +11.1792 3.82426 lineto +10.84952 3.82426 lineto +10.51984 3.82426 lineto +10.19016 3.80229 lineto +9.86047 3.7803 lineto +9.5308 3.75833 lineto +9.20113 3.75833 lineto +9.20113 3.82426 lineto +9.24509 3.91219 lineto +9.24509 4.10999 lineto +9.1352 4.26384 lineto + closepath stroke +newpath 16.498 3.71437 moveto +16.498 3.86823 lineto +16.54196 4.00009 lineto +16.78372 4.17592 lineto +17.1134 4.24187 lineto +17.26726 4.1979 lineto +17.33319 4.06604 lineto +17.35516 3.97812 lineto +17.39912 3.67043 lineto +17.4211 3.47261 lineto +17.44308 3.16492 lineto +17.46506 2.81325 lineto +17.48705 2.41765 lineto +17.48705 1.31871 lineto +17.46506 0.98903 lineto +17.4211 0.8132 lineto +17.28923 0.74727 lineto +16.95955 0.68134 lineto +16.67383 0.76926 lineto +16.62987 0.9231 lineto +16.62987 1.14288 lineto +16.65186 1.47256 lineto +16.65186 1.69235 lineto +16.62987 1.69235 lineto +16.6079 2.32973 lineto +16.58592 2.65941 lineto +16.56393 2.92314 lineto +16.54196 3.23085 lineto +16.51999 3.47261 lineto +16.498 3.71437 lineto + closepath stroke +20.8 0 moveto +(a) rptmr 10.00005 fshow + 0 0.5 dtransform truncate idtransform setlinewidth pop +newpath -3 -3.08002 moveto +28.24002 -3.08002 lineto +28.24002 8.36008 lineto +-3 8.36008 lineto + closepath stroke +newpath 62.48819 1.64003 moveto +62.48819 8.05983 57.2839 13.26411 50.8641 13.26411 curveto +44.4443 13.26411 39.24002 8.05983 39.24002 1.64003 curveto +39.24002 -4.77977 44.4443 -9.98405 50.8641 -9.98405 curveto +57.2839 -9.98405 62.48819 -4.77977 62.48819 1.64003 curveto closepath fill + 1 setgray +newpath 61.48819 2.64003 moveto +61.48819 9.05983 56.2839 14.26411 49.8641 14.26411 curveto +43.4443 14.26411 38.24002 9.05983 38.24002 2.64003 curveto +38.24002 -3.77977 43.4443 -8.98405 49.8641 -8.98405 curveto +56.2839 -8.98405 61.48819 -3.77977 61.48819 2.64003 curveto closepath fill + 0 setgray +gsave [0.9397 0.34203 -0.34203 0.9397 44.11798 -3.62311 ] concat 0 0 moveto +(e) rptmri 10.00005 fshow grestore +gsave [0.9397 0.34203 -0.34203 0.9397 47.91821 2.01683 ] concat 0 0 moveto +(i) rptmri 6.99997 fshow grestore +gsave [0.9397 0.34203 -0.34203 0.9397 50.26746 2.87189 ] concat 0 0 moveto +(w) rpsyr 6.99997 fshow grestore +gsave [0.9397 0.34203 -0.34203 0.9397 55.24785 4.68463 ] concat 0 0 moveto +(t) rptmri 6.99997 fshow grestore +newpath 61.48819 2.64003 moveto +61.48819 9.05983 56.2839 14.26411 49.8641 14.26411 curveto +43.4443 14.26411 38.24002 9.05983 38.24002 2.64003 curveto +38.24002 -3.77977 43.4443 -8.98405 49.8641 -8.98405 curveto +56.2839 -8.98405 61.48819 -3.77977 61.48819 2.64003 curveto closepath stroke + 1 setlinecap +newpath 28.24002 2.64003 moveto +38.24002 2.64003 lineto stroke + [3 3 ] 0 setdash +newpath -5.25 -11.98405 moveto +64.48819 -11.98405 lineto +64.48819 16.51411 lineto +-5.25 16.51411 lineto + closepath stroke +showpage +%%EOF diff --git a/Master/texmf-dist/doc/metapost/base/source-manual/figs.mp b/Master/texmf-dist/doc/metapost/base/source-manual/figs.mp new file mode 100644 index 00000000000..c8e87ba5629 --- /dev/null +++ b/Master/texmf-dist/doc/metapost/base/source-manual/figs.mp @@ -0,0 +1,24 @@ +% Examples for MetaPost doc, by John Hobby. Public domain. + +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-manual/grdemo-doc.ms b/Master/texmf-dist/doc/metapost/base/source-manual/grdemo-doc.ms new file mode 100644 index 00000000000..19c0ed030d7 --- /dev/null +++ b/Master/texmf-dist/doc/metapost/base/source-manual/grdemo-doc.ms @@ -0,0 +1,184 @@ +.\" grdemo-doc.ms +.\" +. +.nr PS 11 +.nr VS 13 +. +.TL +MetaPost with groff +. +.LP +John Hobby's MetaPost program had an \f[I]AT&T troff\/\f[P]interface which +have been changed to use \f[I]GNU troff\/\f[P] instead. +. +. +.SH +Usage +. +.LP +Since MetaPost is a picture-drawing language that outputs PostScript, it is +necessary to use the \f[CW]\%-mpspic\f[P] macro package, which is +automatically included when \f[I]groff\/\f[P](1) is invoked with the +\f[CW]\%-Tps\f[P] 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[CW]\%figures.mp\f[P]. +Running +. +.DS I +.ft CW +mp -T figures +.ft +.DE +. +to invoke the MetaPost interpreter produces output files +\f[CW]\%figures.1\f[P], \f[CW]\%figures.2\f[P], \&.\|.\|. +. +.PP +Standalone EPS pictures can be produced from such files by +\f[CW]\%fixgrofffonts\f[P], that fixes comments according to +Adobe Document Structuring Conventions (DSC), embeds +font reencoding commands and non-standard fonts. +. +.DS I +.nf +.ft CW +fixgrofffonts < figures.1 > figures1.eps +fixgrofffonts < figures.2 > figures2.eps +\&... +.ft +.fi +.DE +. +.PP +Before these figures can be included into \f[I]groff\/\f[P], they have to +be processed with the \f[CW]\%fixmp\f[P] script: +It adds an encoding vector for all text fonts back to the file (which +MetaPost can't add itself) and changes the Adobe Document Structuring +Conventions (DSC) comments to something \f[I]groff\/\f[P] can handle. +. +.DS I +.nf +.ft CW +fixmp < figures.1 > figures.1ps +fixmp < figures.2 > figures.2ps +\&... +.ft +.fi +.DE +. +Now the converted files can be included in a \f[I]groff\/\f[P] document via +macro calls such as +. +.DS I +.ft CW +\&.PSPIC figures.1ps [width [height]] +.ft +.DE +. +as explained in the \f[I]grops\/\f[P](1) documentation. +Note that the picture gets rescaled if the height and width in the +\f[CW]\%.PSPIC\f[P] command don't match \f[I]mp\/\f[P]'s idea of the +picture dimensions. +. +. +.SH +An example +. +.PSPIC grdemo.1ps +. +.LP +This figure was derived from a file \f[CW]\%grdemo.mp\f[P] and included at +this point by invoking the \f[CW]\%.PSPIC\f[P] macro (omitting the height +and width parameters to avoid rescaling). +. +.PP +The file \f[CW]\%grdemo.mp\f[P] looks like this: +. +.DS I +.nf +.ft CW +.ps 9 +.vs 11 +verbatimtex +\&.EQ +delim $$ +\&.EN +\e# etex + +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 \e[12] \es8A\es+2 \e[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; + + label.top(btex \e[Cs] \e[Po] \e[Eu] etex, a.n); + label.llft(btex \e[Fn] etex, a.s); + + draw bbox currentpicture dashed evenly; +endfig; + +end +.ps 11 +.vs 13 +.ft +.fi +.DE +. +. +.SH +Changing GNU troff pipeline +.PP +Note that, by default, the typesetting commands in the \f[CW]\%btex\f[P] +\&.\|.\|.\& \f[CW]\%etex\f[P] blocks in the above example +are processed by +. +.DS I +.ft CW +eqn -Tps -d\e$\e$ | troff -Tps +.ft +.DE +. +If a different \f[I]troff\/\f[P] pipeline must be used it can be +specified via the \f[CW]\%TROFF\f[P] environment variable. +For \f[I]groff\f[P], the following is recommended: +. +.DS I +.ft CW +TROFF='groff -teZ' +.ft +.DE +. +It adds \f[I]tbl\/\f[P] to the pipeline in addition to \f[I]eqn\f[P], +producing output for \f[I]groff\/\f[P]'s default `ps' device. Note that +you then have to specify the left and right delimiters of \f[I]eqn\/\f[P]'s +in-line equations within the document (which is good practice anyway). +. +.PP +Macro definitions and such can be added via the standard +\f[CW]\%verbatimtex\f[P] \&.\|.\|.\& \f[CW]\%etex\f[P] mechanism that adds +the given material to the \f[I]troff\/\f[P] input. +Such material should not generate any output since this would get mixed up +with the next \f[CW]\%btex\f[P] .\|.\|.\& \f[CW]\%etex\f[P] block. +Note the comment escape right before the first \f[CW]\%etex\f[P] command in +the above example to avoid an empty line. +. +.\" eof diff --git a/Master/texmf-dist/doc/metapost/base/source-manual/grdemo-doc.ps b/Master/texmf-dist/doc/metapost/base/source-manual/grdemo-doc.ps new file mode 100644 index 00000000000..f60e465bf14 --- /dev/null +++ b/Master/texmf-dist/doc/metapost/base/source-manual/grdemo-doc.ps @@ -0,0 +1,1025 @@ +%!PS-Adobe-3.0 +%%Creator: groff version 1.19.3 +%%CreationDate: Sun Mar 12 16:21:58 2006 +%%DocumentNeededResources: font Symbol +%%+ font ZapfDingbats +%%+ font Times-Bold +%%+ font Times-Roman +%%+ font Times-Italic +%%+ font Courier +%%DocumentSuppliedResources: file grdemo.1ps +%%+ procset grops 1.19 3 +%%+ font FreeEuro +%%+ font ZapfDingbats-Reverse +%%+ font Symbol-Slanted +%%Pages: 2 +%%PageOrder: Ascend +%%DocumentMedia: Default 595 842 0 () () +%%Orientation: Portrait +%%EndComments +%%BeginDefaults +%%PageMedia: Default +%%EndDefaults +%%BeginProlog +%%BeginResource: procset grops 1.19 3 +%!PS-Adobe-3.0 Resource-ProcSet +/setpacking where{ +pop +currentpacking +true setpacking +}if +/grops 120 dict dup begin +/SC 32 def +/A/show load def +/B{0 SC 3 -1 roll widthshow}bind def +/C{0 exch ashow}bind def +/D{0 exch 0 SC 5 2 roll awidthshow}bind def +/E{0 rmoveto show}bind def +/F{0 rmoveto 0 SC 3 -1 roll widthshow}bind def +/G{0 rmoveto 0 exch ashow}bind def +/H{0 rmoveto 0 exch 0 SC 5 2 roll awidthshow}bind def +/I{0 exch rmoveto show}bind def +/J{0 exch rmoveto 0 SC 3 -1 roll widthshow}bind def +/K{0 exch rmoveto 0 exch ashow}bind def +/L{0 exch rmoveto 0 exch 0 SC 5 2 roll awidthshow}bind def +/M{rmoveto show}bind def +/N{rmoveto 0 SC 3 -1 roll widthshow}bind def +/O{rmoveto 0 exch ashow}bind def +/P{rmoveto 0 exch 0 SC 5 2 roll awidthshow}bind def +/Q{moveto show}bind def +/R{moveto 0 SC 3 -1 roll widthshow}bind def +/S{moveto 0 exch ashow}bind def +/T{moveto 0 exch 0 SC 5 2 roll awidthshow}bind def +/SF{ +findfont exch +[exch dup 0 exch 0 exch neg 0 0]makefont +dup setfont +[exch/setfont cvx]cvx bind def +}bind def +/MF{ +findfont +[5 2 roll +0 3 1 roll +neg 0 0]makefont +dup setfont +[exch/setfont cvx]cvx bind def +}bind def +/level0 0 def +/RES 0 def +/PL 0 def +/LS 0 def +/MANUAL{ +statusdict begin/manualfeed true store end +}bind def +/PLG{ +gsave newpath clippath pathbbox grestore +exch pop add exch pop +}bind def +/BP{ +/level0 save def +1 setlinecap +1 setlinejoin +72 RES div dup scale +LS{ +90 rotate +}{ +0 PL translate +}ifelse +1 -1 scale +}bind def +/EP{ +level0 restore +showpage +}def +/DA{ +newpath arcn stroke +}bind def +/SN{ +transform +.25 sub exch .25 sub exch +round .25 add exch round .25 add exch +itransform +}bind def +/DL{ +SN +moveto +SN +lineto stroke +}bind def +/DC{ +newpath 0 360 arc closepath +}bind def +/TM matrix def +/DE{ +TM currentmatrix pop +translate scale newpath 0 0 .5 0 360 arc closepath +TM setmatrix +}bind def +/RC/rcurveto load def +/RL/rlineto load def +/ST/stroke load def +/MT/moveto load def +/CL/closepath load def +/Fr{ +setrgbcolor fill +}bind def +/setcmykcolor where{ +pop +/Fk{ +setcmykcolor fill +}bind def +}if +/Fg{ +setgray fill +}bind def +/FL/fill load def +/LW/setlinewidth load def +/Cr/setrgbcolor load def +/setcmykcolor where{ +pop +/Ck/setcmykcolor load def +}if +/Cg/setgray load def +/RE{ +findfont +dup maxlength 1 index/FontName known not{1 add}if dict begin +{ +1 index/FID ne +2 index/UniqueID ne +and +{def}{pop pop}ifelse +}forall +/Encoding exch def +dup/FontName exch def +currentdict end definefont pop +}bind def +/DEFS 0 def +/EBEGIN{ +moveto +DEFS begin +}bind def +/EEND/end load def +/CNT 0 def +/level1 0 def +/PBEGIN{ +/level1 save def +translate +div 3 1 roll div exch scale +neg exch neg exch translate +0 setgray +0 setlinecap +1 setlinewidth +0 setlinejoin +10 setmiterlimit +[]0 setdash +/setstrokeadjust where{ +pop +false setstrokeadjust +}if +/setoverprint where{ +pop +false setoverprint +}if +newpath +/CNT countdictstack def +userdict begin +/showpage{}def +/setpagedevice{}def +mark +}bind def +/PEND{ +cleartomark +countdictstack CNT sub{end}repeat +level1 restore +}bind def +end def +/setpacking where{ +pop +setpacking +}if +%%EndResource +%%EndProlog +%%BeginSetup +%%BeginFeature: *PageSize Default +<< /PageSize [ 595 842 ] /ImagingBBox null >> setpagedevice +%%EndFeature +%%IncludeResource: font Symbol +%%IncludeResource: font ZapfDingbats +%%IncludeResource: font Times-Bold +%%IncludeResource: font Times-Roman +%%IncludeResource: font Times-Italic +%%IncludeResource: font Courier +%%BeginResource: font FreeEuro +%!PS-AdobeFont-1.0: FreeEuro 001.001 +%%Title: FreeEuro +%Version: 001.001 +%%CreationDate: Sun Jan 8 10:14:22 2006 +%%Creator: root +%Copyright: Created by Werner Lemberg with PfaEdit 1.0 +%Copyright: (http://pfaedit.sf.net); the serif shapes are based on the +%Copyright: Omega fonts created by Yannis Haralambous. +% Generated by FontForge 20060105 (http://fontforge.sf.net/) +%%EndComments + +FontDirectory/FreeEuro known{/FreeEuro findfont dup/UniqueID known{dup +/UniqueID get 4166882 eq exch/FontType get 1 eq and}{pop false}ifelse +{save true}{false}ifelse}{false}ifelse +11 dict begin +/FontType 1 def +/FontMatrix [0.001 0 0 0.001 0 0 ]readonly def +/FontName /FreeEuro def +/FontBBox {4 -23 903 710 }readonly def +/UniqueID 4166882 def +/PaintType 0 def +/FontInfo 10 dict dup begin + /version (001.001) readonly def + /Notice (Created by Werner Lemberg with PfaEdit 1.0 \050http://pfaedit.sf.net\051; the serif shapes are based on the Omega fonts created by Yannis Haralambous.) readonly def + /FullName (FreeEuro) readonly def + /FamilyName (FreeEuro) readonly def + /Weight (Medium) readonly def + /FSType 12 def + /ItalicAngle 0 def + /isFixedPitch false def + /UnderlinePosition -100 def + /UnderlineThickness 50 def +end readonly def +/Encoding 256 array + 0 1 255 { 1 index exch /.notdef put} for +dup 0/Euro.symbol put +dup 1/Euro.symbol.bold put +dup 2/Euro.symbol.slanted put +dup 3/Euro.symbol.bold.slanted put +dup 4/Euro.serif put +dup 5/Euro.serif.bold put +dup 6/Euro.serif.italic put +dup 7/Euro.serif.bold.italic put +dup 8/Euro.sansserif put +dup 9/Euro.sansserif.bold put +dup 10/Euro.sansserif.slanted put +dup 11/Euro.sansserif.bold.slanted put +dup 12/Euro.mono put +dup 13/Euro.mono.bold put +dup 14/Euro.mono.slanted put +dup 15/Euro.mono.bold.slanted put +readonly def +currentdict end +currentfile eexec +743F8413F3636CA85A9FFEFB50B4BB27302A5A63F932884E18BF5153AD36053037D1C6CD +04294AF6A35612DB9108AC8514CB5C4A8469971B75A09F9E662068B0685490EA8C73F2DE +2FBBCF85D15AB9385E529DAB15A40D408002E88D0C107F711BC66BF0F2E92FDDC6B188F9 +1EEB6B86050D5032E6ABCB11E343C6D795217B5973972E99A9420651ACF3B8FD4CAD1DA4 +B00642AD077A5B86240F89F2BC011009CB2CF173FF68E9A88F0018F187D5E036FE8D904F +211842FF01AA7CAADDEB9E5A534FA3F90BDB8F6FFE24F7AC6E7BD0A74CF29EBBA51871F0 +D1FF3262EA3CAFF583545FAB762B8D9BF14C8845C4EDB387B1248A4BCCB70AEDC6C67CF6 +C4648FA00124C44166D66DE1573C926CD9C6AE4F8B89E5987035D23195432204B648D458 +39F1769201B7C68828B3E49DFEF3065D705C2EBFFFB05B8A865CE4888872146C99671EFA +EE1F514B94B86A47AAA5F21A39786E77D443FA4CF8B525C98FC02459528C08410C679440 +CC3A160C40B14E03FAB3E267943E1FBACDD4C082777B31AD3591DAEA25DC60E0EE11AB59 +52C58879FCB35A54009A156730AF209A8D4F00CF7DD9870C8DC3E48C19BED68742376268 +0408FFD4A34A0D8659D44FADC9FC9D3084601C93FD9FCA770B1191500ECB12C8DBDB2032 +007CECE3C6A2CC8593386DC1464B94A09EA2A83438C71ACC7CAD72D074ABF6FB98EFC81B +6A3D672D2DCC637F34ACF18D469ED29FE2C49062380E6A32850F696834FC8E46A924164A +C64DF8F848D4D000EB6FD06A44D0320975A8EEE85173E4D7E39EC9DB03A8ED20DAED86D2 +73CE5762A5D35D1A81987F9CD9921E39C2C5CEDD661C3B3EE86B703C101C410E41648347 +7599C4CCB91234510ABAC16898D9D10E30B5FC1BABE78DF2A009E09E52816F2413899184 +AB8F942A496B56C9FDE630B13AD9F0996ADE29CABAF1443452B427A2280AD00B85F4657C +65B47E929FB0A2A31F257B24FE4ECBAFC878C306094088E00DB2DA6D36CECE30971846B6 +39DA9BA989109507FF21FD7198736278ED1CD021BFE7689D93B425D8B6CCCF07D37C22D7 +966FB87EFBE8F6A86D4F0C4BD38F5F3A41DCEDA924FD5F0D8FF089A0F44DFD37498507D3 +2A383FC717537744CC6868EB913D5C08CD0A3F935145FD5D811F01870F6136F4EFF757C5 +D03E73FC22F88624116C08C225C1711C96A01656999AAF7414163E75548AB89F8AA85F20 +9FA6EC242ECDA0953DC61EAE4107610380DFE2807101BDBA51391685990B3D1FFEFEC97E +0F0DE04283920370575AC06B8597EE756EEF7A3543A3E5F1B74343702A201C43411E7B76 +DC6422E2529E740A6BC6BD44ABAACD955406734AF0852471CC7B49325286AFFD2F9CFD04 +BB9CA4D0F6F0494CED1D2984E2C607FD2CE5C5A1F538CF9107771E691FAD51AE5DA70748 +F14F2FF7CE61292F6FA50D4510E4100360A4A2EBF7F9A03F7A4DAC981C6DE582BAFEBC23 +AD97EB56656A218B24D47C4345B398C14ECF5B76037D83FEB71E65F89C01133A5228496C +DF4BCC8BD4C615C9725511A2376A01C80F1EF38757CF104DD0809121EF1A2B9F11B5BDC7 +8E4F5A1463F37E952891370E1887644D26751A261FB5EE78BEA745F4F44A9B00098EDC4E +3547F5AE50DCBF29EF5BF82D653A148D340BC600EB411F4EA8A6A2D0B548D0B217E78943 +BDAED70072716A4406D685B55C2C0F490D2B472C49B278DB78E9914C3623825E595A541F +509F0E7BB1A827F4E6B0EA42C668932AB48D7B4A21AC0DA7451924D1AA7CDBE80C94F109 +1A4D91C3B908060FEB07D1B454A4CE4A60F8FACA6930313E09D5F11D1D8437E6B65EEE5B +B5570C3B66ABC491BD8CF63C2C62BC7B38A0CDFFE9D75627E6D3B23B608C7EEBD8FC655C +D197D28E8EB319814EA71B6AD63A966DB61D9C3C7D788683559C49338D037A235FD56FA0 +059DDC6017F0919926C323327C204139F07810575A8749877FB2C0C53AF4E3962613A0E8 +7D7C37A9974105992FC6B754CF23017C2E5851BCC90F48D6847EF1EF59E42032AFE03A98 +DB363827CA07E337A5852BE832772A2981864B8C1EDAD8759ACBC132ADD0BB360F40BAFD +FC7E5D32D724CF82FD3342D431F8F4CD9BDE2B07C8D8EED411E3A5889A8163CD1E2C2786 +F78AD3C1D9879FD6E93BD1FD8949DE47A8BCD219422B2F1316950B72E1E5170701795A0A +80709E894C218AA64DF5684719830066B995785AB9F1603FFDCEA945FEC09F57BF886F01 +A95811C7D4200E11C7CB373AAA4301E58F74E77519E11A89751A338B38D115B365547271 +DB19E51B85B30D1EB8E3E0B95436262D52471D65BBCF5DD94F6FF1210BF09628191F8F04 +3ED7109DE2AD284954564A1C80811B9AF1686DB799D36B50EB095AF37B9117992BB6B8F9 +0CE43ED10F9D0CE4B8ED76549239A626809ECA3D5A90E23D3CFBC776D6D816A293F2A80B +7267D1842FA102BAD77A2A775CB55473F40D3976AFC77ECDA131FF663A12795528A7EC15 +1D7854E759321709A8F4750716C949D71D332F9B0B80130916826F07E0165A5A1C5F3D8E +EF8CDB4EE3F688867FDDD47B4D67AD677F3134D90E07A1F0A8690169AC2E176BCB7CF260 +A70E374F3EC834E3B83D19CE3A52883024D2976E8E02C0B320CFD7B8BF66D11FBBF49353 +647AC4AB23A2A5689506AB83AD60AF8783E04815CABE60A3243FC633FD12D6DA50036691 +D3A0FBD4AD1309289565FC0C449510AD58085356AD829538B97A501FA73CEB693F09D551 +8FEAE6DE59FD7871AAED96A27127286C09FDD5A1EAE421CC38F56A4AF6AD5FA9BF96BF00 +2BE0A49BE6F27636DEB364A0762BCFF054020850C9222940B0E8A08E6A77240E1A0F42DC +07DAD0283BCD9DAC20E2A7542F5D74FC90D2661AD95350566F27125160C0525364D8B764 +E06FBC0F85531185F8B92B4ADE928B2CF0DD4736CAA76F6659D128E416E9792F24CB6B41 +CF369FF2BF9C360FA006938067DA606B2B19C8599FB28306FDACBF29841A169F6368384E +32B6BAD4179E345AB2B3CAB35E29E154228DCDC3D4C3317295A050A8AA86273BF7178A07 +65B598EE7061AE13B11B670F2E5F90F9FDD2F09A84F247DF9C90698A44A29BEC87B3C606 +E46A35D94986363CFEB26524FD7FB88092978128B0D246934D93BF90CDD94F7D243113C0 +8BDD1E09E4AC9F6E7A5A4FDB89150632CA41E3320D6B5AC722B27984D238D29A20F69BFD +1AB94BFA39EE52371CBEC64E16E37319ED189F2CC3992EC03A780AE4AFAEAC4FFB7A8340 +36F307F1BAB17477BF14809DA90E0AFBD0E3182D7E40A1EB1AABA8C64D9CA02044E85A82 +7FDB6C215F77FADC0443A04083E23DF21523DE178DF165F369E93AD21F34B4D72C24D5F4 +D6D19BE8F5B01AFCBBEC537C509FD7B388AA66A3E4CBCAA85601C20BEBBD2D3F11CE1CBC +E7D8FA53FA83710A80D8795AA5FF3C2E7F063DC05DC002E8278DCC1FAF9909FFE55A633D +86BE4C570BD9820327490CA61CA4FDDE381CDF70D97FF279F6A458E5D7B8DE5E1384F894 +3064F4F17D369F014D5A68C9F2E170BB59634AF060678CB4DC84450B94E34CA704B5DCE3 +67125FEE35A1B0A27F40E38D00CB779ACB34284080D5D78E30DE6233F0AD3FC22D170A60 +E2B7D4F206862D1890D16E3C9D720CCA05930814E00337AD8607098C68CBEB919504277D +B3AB769CD77745B375945BC4246B813F828099DAB82512936FE106B368F189ACE1A2EAE1 +4CF5FE1C91BD0D79CE179D34A0E85F8F1BFDEF9F28C1F26924D630E845CAA19BADC44B7B +ED9C6452C0AD01D108967D85E0779AEE557A9207164D22DFF7BCCE92D5CB9809ADFD332F +9567C92510CFC94796AA5A312C4484183B66C44DED8476F974CE6FEBFE86178B99F1820B +07B3D7C80F5CCCAE591BD8920814B4398A502756D3C945D07C6CD9FC2414086434151E87 +30C14D38764C532BDD5830E24C16BFF8CC19181621DD26E67259711E6CC43ED8AAE343B4 +B728BFD242C6C314B3D453DD3B3BC3986E736B4085C8D7498C9778538AC0F2DE17B9F89A +60082B571BE433119A9522F93A4C1222A26F94A199D71F50FA5BA94CDA733E26A43A3002 +564A841FCCC267EF8F1556CF85C8AF4A649F0AC533E0E859E3E2723525FCEC1B6E6A3CE9 +0B66D585B1E7C4B953ECF941B12D3003FE14852B7978126BE4B58DF8924651697B79F333 +F2D5BC34458DFD36826F8DFD374D0D59DD01FFC2C455B1A12AC80380F48A742013D0C3D9 +C7E040364633F0476D1ECE1870386871CE95099A30F881EBE00F6E140FE58F8C1D5F2B37 +35D12A9FF60157F8691DD64E60EF9B957C586D4E2E9D5474634F7AA44D50B11B001C66CC +F283185C6E65E32D2F2B8127B986CF62455067A5E621738C8A381D2B6A033F6C389BE878 +3179A54AD38D69223AD779A159B2D7D0AD1670A03171EB4C27930E1878037813CBC46214 +7486F3B8E9F7016C9E2E4C60B03A4C976D48EE3A20131AA00F4B79707FD801B3F7A7759A +3AFF3F6CEE749F2B32B01A582DC408384B8749307794914EAF7A0300E1C9AEF42DFFD828 +C5EE7D9730CE489F0A98C81E166B2B1EED3BCFACC370709947CFD29DEAD86C58FCF6AEA4 +8D670583BCA7018853B781340D7F4D1F2FA5703EDA8F1815F74407B4617016AD9BDF1F49 +340E7D89AF7CB5818B996201512968AA2B3D71C468C69DB46E514EC3CCBA360B3E80972D +86145148DC0BDD4ADDDFDC7D835DAAC0AA9B96DDD91973288B3A2A28BD6BB415C2A79818 +7F58F3402DA53B0600FA53A01AEEBCE5081BCC0645348BD1772C54A608E88499CE0103EA +C4ABC7FD74256C4F16A977BDF7F13843BFC6CCF16092740D9C1E7561EFD4EC6A3A30460E +A434D1921727FA26D9F56627DCD6AF95951E602936C4AC6C7A6F6DFEF2C0CE0571458B27 +BB31DA11C9E09DD3917F61140EFC4F059AC2FAC839BDDC0695B293C42BD17B1895A6B2B2 +F955821C5CE356B1AA33C5F361BB0F43828A20B9F193E71E057F45B6CC8ABE53EEFF801F +2B6CFB31B6DEB5D84EB8525B938AC424B3486DEA14982E5CF7F2D2C92F2D9B28033DE0C3 +4B610505771E0B1BE6AF03552EB8B44EC1190DAEB15DAAF21E7F2D437780484F0535D8ED +941A8FA13D379B911FC7AC99E4657DABD37891C467E8854DEAD2E34E05962F0EEC30B5D4 +B8FA6EBA42C102564A2FCDF679AFB7FC145C98EDCC81BF33DCFEB593CF8E7C2F6E9E22B7 +8B1DEE3B75C0E87AB95C6341A1D09948BF338B682F515D89230F8CDBFC72D56A00003EAD +F5BC0A6CC1A802A80480D6CEBA34631C7892909E049473E8328295069C0845571ECC9980 +CD8BCEB4C930C06601BFBE690FA0BB34631C7FF64D91A31BDF9035EC6E44EA12A79DF384 +FD82092DEAFB2D2E1B0C8ED903BCA55382F98FA5346ACC20900D86E64FF528C604D6815E +3DEFC5F71EBBBAC2B5787B2F25AE820AFDD4038CD58B0F1710C1EEC7DA521071DCCFB9BF +24C9EA1049EF59E61D20BFD50BCB5D8CBD0DC266B8836F34EB94858A54CE0C9E6088188A +EDE0BE39FAFE697AA6C8805CAD63DEE8A0CA226C91405DE5FE7FE8820124D6D79EA5F956 +8C5CBFEA24C4F3D601428329453F226C4C3E3E429E429C2E96DF25EE1DD7B5B12B2C1DA7 +CB0EE6EB0D018C2DD437A6883D2C2E57B9CB264CD3369C20AB831CDDAC5F57E550727C0B +CC9715B2C87C26C0A9A6A2F173C7B03F12F993B217466E7896E4764C6AF20CDF0634205F +3E38E6C8C6DE3A4269C5C6CF03E49D60F0E2F3D7B3ED302C3BDA4EC6332867A19C9CE8FD +6E2D0F2C597E11896A3E6EDC4B616F76B3355DFBF26DB2199963252C93AE423F1AE6683F +115E9B68672BFF4C9134EED4C51AE587CC859F742A283F3C9B6088B0B9E65A1EA521578A +E67D7396907129B83C1C9E2302D5FF46FCBF408E0FA69AA8F6E7193AE9E9DD5254201317 +B3D304BDCA689B683568BCAD9539C4D6BDA50814D8F251A70E76E7A5EECF719DD1655DA0 +605D9EFC940A8CF0FDEBC7146DE12F108959280903C34C69DC92F8205F2EE1D52F483AA7 +7E02F277A1186849056036CB24AB238AF08C903C4CEB4851991C24A8158EAE8D8F3BE56C +355FC26D7BBD2849B7ED9E1A25DFE98BC62A6797615BCE59DEAAFD5B6D08298E2DDAA611 +3DE60AB83FF7687B7ADD6706822270ECA925B559F2F9EC59C9AB0F365868DEC3122EE67F +BAFE7EBFACEC14D4D40C55F94ABBE8CE82CEA67FC1415D127786071CC06DCB653CCDED0B +40A9D49994865CF45BA494AC11543A0546DC37417BD01DB100273EE3F0E7D12093E50FD0 +E71B9A0326E8F35FCD86B3285781008ED03FCA1850D685CA5B62518C9194A0C7E8CFD5A9 +FF6A0EF508ADBCEDAB7C7144272F8C7DB274CE7AA09CFABCCA3E6967EF259A72C3B8F4FD +4605CBB99CE88B679F3EC9486C442B05D776B9D7FA8C04203DBDF33C0CF45B15E68C9376 +168229CC5176BC1E9707853192BD0C394E2D8880050594675F5B83488026791AEB1E6D79 +A424B8F90149F4855EF1BDF6CF0137D459D2A22DA3FF00743B52B2F9C316262EE53AE760 +43E2F267C2598CE66CFEAEF1459C307CA9B3FD8E897C93426545B80834EA16764633B2C5 +5B31557E6B5398F17D0BE5CC1348FE71014EF3BA2F917589AE4A4C9D8EF22A6D0A288557 +C4B2F2ABF2C30E778A5F21AA16BDD04CD8433514FBC7F81583F5D9CE3DE38542DCA55FFC +9142EB3B797946A7A121C134C82DAED820D3FF0E7053B40134353012A44B15506385533D +0702662BC8545130B7717B5E99BDC18E8473D2920C80CAD8F61D352C2B3718567B0BDFDF +F063D2E1A568D6B17412149E4C9AFE3FD3F8186A8274FC01CA07504BE6751A7BDE74719E +970A9F1744917E3521C4988E547EC1B63D33AD86390DB6CDBA9436884CEAA6064E383B61 +68BD405523A23D32B571E534354E1BD4EA3EDB7D1BBF2D0F6D6B36993DB0DF94C18BEBE2 +6F4B6475306784C091E139A759F627843CED43666D95AE257E650DDA0F6C0458CF27885F +25D59FE5601777ADCCB42ABC20F960B17A2669B4277AEE51A3D33BB1914FC5985236A6E0 +0C32956A1CAB55DD020DAFA2BAE36638E5F5866AEAB8E3439EFEA9266CB28B9DBA4B1746 +046A71E3BF05F37FF84CEFD66479640C3BB43D915BFA3AF6F3916F2AAAE39DD4317563C2 +26E361EE278E9FE076EE6B4733720C53918CA5CC9C5F4C6C7A36D8E49A591074AEFF0363 +09E5834A3978ACEB9016F116D20B6854BC59484F344D069768C6DFC503EB95C9FEA0521B +FD6E1C99FCD1268D18C1DD428C66DE9145071190FB17464C8C4FE87D9C0F3DA5FC3E933D +7375E88DC3BA96858D671A6616F52E70EC6B5795114C3F03F8C78CC388AC01866B347196 +40705C2EA04CC1369A88B3A242FFCB32B48024742A03C94A6E715EF09F06CC999CA1E593 +AB6013B7E25685C4FA93429EE0613E3DA07C94D82B9A739B954BD6EA1E2A9DE55461211B +4FBCCFF6BD480C845DC4B075B33551C760FE3D8F5EDB1201269AF48C8F8E96AFB5C7F767 +20AD3F9BDB225AF317770F1C2644589EDB5639376E30DB053930511FEE7C9FF81F6B76ED +57E4C6CF157AF5EE0D8E05F0B9F1276385B3C4EF779593B0120AAE0073880C0DE6F76906 +8B96E92133050EF7BA0A6585AB37880501F42477E0AB8A5D314F7A5A1B760142A42A40F2 +2A12F0F79C747F8C57C688C5937BCCF9B217647EA1D7C16936055814F9260C647045F3C8 +997D40B7BB690B654B9F243D2FC9343C7BAEC4F79AC5CA9C8A43E414B4BC6A6B02828CC2 +1432BBC6E49EAB7DAE35926C6B0BFBC6AC3831834CF54A732E8531AC7D0A3AF62A5FF8F2 +4B59EF71698824E2AC5E4DC2D5C58B9FFA80817C4DA7638CE5B6F0F33164FCCDA6F82933 +AE42A26BA9AA939A7DBD55F35C29BB9D192251E945D9890F48F63D7BB58269031899F7D5 +A52C1747CBEE945D55154AD30301FCC6345DF34A177E9CAB110D7A52B63B131A1F7D7165 +BB5AC4B1842B9A1F3D86F521E4107B40963BB34CC61B10F79D936736DEAC7F25BBDEC228 +E7838F1032154ADF35F333077483AFCDD50410C07707A47F9306BF794A15B5452EEB34FA +48A8C1BAA627EBB16BEBE9369AE7D100CF8D14E5B70613C8C8A53CA82495E8BAE8990ABE +0ACC0B2E9CC44191A50417657662385821B1C897C88AB2A0B149090CE11B940AC6DDB64D +0BF745858A1A56F811F1DE81458F50A704EA30F5F1918D9B5481E6E4681B389C447A65E3 +56A12C8592C8709C09135B06994590DD0B87D2952C871EF0B7365D04928A7B19AB3A10EF +40B0BA1DAB4D3DC5789EBDB23E98698963FBD74DAAB6C8885A88634E9857CBCB163B1D0E +32DF259DFEF7217D6744CC6F34E0D96C7BC93CC0A19F4EFBDAB6338CB56B46E538EE92B4 +353AA6663AC42A2EF78E4A228886577678FF36E5ED221A807E009D33A737F89F80461FA5 +5741EEF636D19FAD5870AF6F436DFCEA130C102156F134F77DFE4933628DBE64B477555D +81CE6131866AA5712347043CF70634F92D5B984445D32A545607B62BA1C12D37FB6B17F3 +84838E274818032AD7A07CDF1F504B3CB5C5C9D8D16342CAB18697A5821B2E219D14F15C +AAFB33A44E4E6D18C4DC64F79DDCBF2BFF7B3FE05709420DBBC24B8C23822755062B9784 +69AF6B01CDC9C45E55A71BC5BE1EDFDC23C430D61FF776BB4B2AB69BD391758462A9700E +21B81CE478207D443C5A868946969DA1E63AA939D3563605C83C2AB2C5E7551169F466D7 +41FDCEE57EEE7897C41F0409AB61E86C947C83850C23DE579ED1A7EF7F941522F41337A7 +F2FF06D4D5CC4A9436A2CEB91B1D9218F46BCC3A1A5C57539BD6A56C6755A8ADD89884F1 +2FF46C13248D02EACB04008BCE1CCC3DA9CB7D4EF0AF02A97734C95D8C45CC360AAA467E +97858E0B66978BB46353E9C0A653E49CC1E63C119FA50441846E5AE38D551BDF3A7CBD2B +8E51C2C088A617B68E21DD2F44EF5033CD252A75C80F16F6C45EBC84E17FA58F8DA6800B +8F61B060F54124F1B1F12AE75059159AF036C25DD06F4EEF5D8048079AC6CCB1BD5DA270 +005EC1428BC3F7A6369EC13EC8F99F77892D163FE605B8609940E1B27D784C57B7842BD7 +10C78480BF7EE7CF9BC29064CBCBE8B3B584C453C29851C39438E10BB9CAD4B2776B0899 +EDFF8CC4D35C8DF827743DC5D85681F4A7B9EAB43E133384B072F0D7A86EC6BFD5989503 +A95AA4DFF2FCB6BCEC468DFF75D20F9FD35015D4F98D65160E9EF8E1AE723433114B5458 +7B0A7314D320A942440D3D37F3BE4164C5D796C5D3597222EC88C7A14503EF964643B095 +E2F113FA22EA7999905633109628F97982451A9810D6A1DD84EB108D7A26E04C1C00488D +322774F47B555B28D24732E6C0D4D701933C9506D379B3E5BC10609B167C1064F34A4327 +A50D0D2FB470994714FB881EE3B88B054633BFF034650C0C4E4AE5720C35C7F3E4CD30E3 +6B26D8CD1813A7703867952488E01B23FDF799AE3AB35E4880E41B4DDBCF8CB4FA68423E +2D5E122264F8378BB8EA414C83D95A4A6D85995CE64A50B39C8E5F94955CDDBD88804D42 +279515FC1129FD2F50A170B214BED20695CCE59EAE0ACE91FCE6DD217B3A737A9DCAE11E +A0C746306AA9447F469BE68D8488E392D00583BAF1E63782C73D5201359CE7A768F24489 +0FA50098398CB006F74E9877E9E4373228269506F44931115C0E44654AFD6B48E3E2F6DD +47E738DE4CDC5344E1C26FAE5B73B9844F5CB2292D675CE88C2078DBDA11C2A9A58F4B10 +42850802766C9387734F22288F12E1F0D211FE150294FDD1744D8001AB95D9D63FD5C916 +B7886A1D6A076D14AD0B6D65E63D49CBC825E85CCFE3E6119DD05D6450980900600A0A07 +4BE3EE6801DAA9670D1BD6F7FE3332BF9B16C9D7DF782547006BF79DD5286A899E1153F1 +077B7AD8CDAC2724E1689A95B958D24566EA5759AF2276E2558AC8A110EA5CAB9C1BE598 +4031BBCA618B7EA15E87379927AF1D58AF01217B45B9CC67F79D96977624A9A01B1AA7A3 +1D0E4B61F6FC96A620867BAB29A7331DE35BC73E29DD89DEC1B5CA163679017FD5D52D6E +F359C8ACD7D149B509EB1E9EA1EBDDD572720F11A390AC61F898295FCCA27F466787CE24 +3C889A45EB97AE0AD87B5DB995DECB80D8A73592C9E17F02ED6BEFD6CFC5E56275366022 +E3EE687762FDB605B7221C7004DA9E8B594D6CA0B0AA5AD97D0231C228E38D21F2652470 +2524A76555EA690062A1C811C7708F33A432E4B93683D416BC6BFD9A3A9CD114ECEAD652 +98376657CFC1B1826B77B533314A3962ABA6137CF6502713BDA51FFC763CF78C7A0AFC99 +CD496DFE069FACD2669351BED17106952A3E55A13210C5024885CAF002343A31D1E64745 +E973853B94DE520B204922CE2063140C7403D7E038EA2D21D86A72E417DEF576BC60ED61 +B74A8237ABEBD176625ADC0B1475EF4D985D05148D0233041FB5F02920F4F4C769E2DF96 +8463AB7054465464844A2A1F1C427B9369BBF6221B0D557C1F1AFF62F710BA060FAA89D7 +3C6E7F5B09B2D1E192F47743BE288AB84682254C54ECDB6FB52E1013CFD075D0430D321D +C0A9B30AA8D1BF0676816E3FB7BB53E19B9C782E3B15732AF9A233408CD12FCBB1D3A963 +3910D9E4F84F1D89B0A26AFC1DF439654005CEDFD46A9B5FC815C91E72631D255475710A +CADB424EC5D2A86681422B36B8A6BE4DCA28EA5A919D9EE1B4F722518925484A59C6A972 +F68A0BC736BEBEF281DFA37F4F51BE2746644CAAC585DE766DCDF6443263C9A403E4E110 +32721D8C79C005B982D7B1A3E19AEAF0C89A2AB06841D677F79C3152E4B130B122BFC8ED +D6EFFAC69BA8C66C47F3D5321FB8A9C7156CFA2F0F577DF1CA2D8E9C6D854B401FF8DCF3 +BFBA7C98B11B3F128EA81DD1BB7B4FC24943B43772A6E731876CF46608CB88EB143AE9B1 +7D72DE503210705410B26CF1D70D7D4B98A2C4AC6F7AEBCE59BAB09F1C4D4E97EC3A9D91 +15554C98E2FC7DF130D4548875C0ECF16614BFDAC96E9230FAAB82C6EBDAA0EBCCD1ABC9 +F9DB0B987DF58240B927A6AF8BF1CA62C39DA2DFDF36DA884F67553F058CE4718777EDED +34E30501AC3DD9B8F9008463A33AA8612595E855D009CF9F7C1BDAC1DBD1483BCFF8A7DD +346DC22F31646C0CF07C753596AFC285F6136BF7E3C83B0FB75D9BDFA9979C0930A245D2 +7899ECA0F64F12C390EA7293E5EFA7A1D0721AAF72B313E6A14FD20B1B5AD9F3BE0F071E +33E89D4F5CC7111B4C06F18782A5A8F840CF27EE20B8BDC0B16E295D4AC30C2E079F75CB +23A338BB99D059095BE8E7D2FEE1BC421BEAFC536D2E2C40E05B6EF3CF483A34CE506816 +2CE04C4F2D9F17748F9FAFB67F046A168F4545D80ECF05266556DA6E75B018F790D5B821 +B5F9D115BA8E3A7B273B92E6E111CD257A6B12F4F25956AF908C8CEC671DBB796FA93893 +18D5B8473A04B63E0F751744D8050A1D266A15656A016697A9CA765660B5728E9BAC77CE +F7EFA339B522C2C52E6C678C550388136C678B2CD1027214D0D086028A29DD4785EEB512 +BD60CF2132746757559BE4C6B802792700B911D098F4A95A758B6E30285F906B6EE7B60D +991F86B1961FDC2BD5A9FA8F68E488AD57494765D9822A469FCAC1BDCE3F3685B09550D4 +49CE97D9FA83F187923C4DE772464EFE98A9789B93E5691C621E9B79F227041D22CB05A0 +22282BAA61BFC04863CEB7BA282CE68AE91CCDC2717747B3BCD808136F779DADFDBEECFF +E610CEE002874E4B33EF0ED4602073C56693BA2479D885F53FE4F5C68DF9C6B09D021342 +C117F488BFC7F2A7BADC2E059F0BF05AED5F6B8467CBE018D7AC442BC3526F8566A71B4A +69E93874F74F3B751B8C6811992D47DC4D080461269C6EB18AE76ECC66479B6A53E1984F +A17E13F546FD4AC12024A1ACE29C9BDCD47274E480017759381B2081349FF3AC5BAA1902 +2D9EB3DDC8471B0D2D58E3717973F7B7CD8E8AEAA301A676579AD57D112CF6D8F659B8CC +E055A155AB0F6C6B8A3254ADBD5E6BBAA336327F3AE20C109CA8C46EF35814473457E3F2 +EC80EE99547B84377DF391B0A9B2F60B818A0A3D49D5E36A2D7A05F4F77F964F81CC51D2 +272CD30B52AFB7AEE06129977A0AF98BFF236EADF92CD7508A2F3FE853EE26530922A59B +639571AA10FA5FC0E1315B7215B76045E18141403E4B0B2A9EB724E69BB40AC1AB479216 +1686D2B0DF545D0FA08CFACB8C8145AA9FB982222EE247B7DF2D5F2B33A9B6AE29CC6166 +3F642883EB6757DB8F1845E1727B7AADAE2FD8E560922467E79EF1803A03C9D51F649DD4 +16C75835F9EEB1FA6FAE978B1B7B7792FB24EDFD9EF55E67CB02D5C23C9628F126BD3A12 +31869DAE5FBBCE60133DEB7D33F1E0ADFD9927A3E9E42B6AB0E5D703BD7271A179985FC3 +D91C2D161B76F70987073647B26542C83A34172663F6793DE8B8D9BCD72CCD48DF5563C0 +FBFA6CC45D99AB78CD6ED8B861948E54DFE9C99E169E35A88D03C1C9A7C84720A3956B00 +0842CF8C515E3A722DDD0B6627926110B335744866564CC638901758FE0EFA98F4E3F4CF +DF911E5E395EC3D17807D7483008A95BA603AB80FB6A359BA3F0A8ADFE60F9CBADF67441 +1D0BE41B802B3EC9075DC1EB375EDCD27E113B4B1EA3C8ED0B1BBB2A3DB934CDC5CDA9B6 +0F85B33DD71FCA5B25B0AAA6B528229D84E1E7B97CB72C0F20248509A2B6CC53E5B7B694 +24FD8BFAE39C66E86DCEE0B602C9102A0575F15693B3C0A268C1C3F897F57E1CC5A58ADA +4222A57B2A53B234BA19ADA37208C16B1B757E106D5D8AF0AFFD6BBA6E753805BBC2E9A4 +450A78025400D18B8FDCA54A18440331E48E52E3C4CA80FC171B02293CED081E887215EA +D34DCF1D6FC2FE86502262006977878E4960326634F1A1EC8D2D96CF51EECDDD6D7CB410 +6D2B37136A13B4D2B67A2DCC74365A27E72B263FCF506B34116BB93BF76DA0C813CE6F63 +639BA86D000BEEED941AC2096A7F1C714615CE20F920BC4427BBB157105FC8FCC3D5FA6C +9C0D797AB7ECA5DA2B5DF210C4523E406821B704383C63055EB87E8C82E68ABB062487C8 +834EB35BA973902999E27D9A7D143536CB253195A3801FAF741C1588C808A1 +0000000000000000000000000000000000000000000000000000000000000000 +0000000000000000000000000000000000000000000000000000000000000000 +0000000000000000000000000000000000000000000000000000000000000000 +0000000000000000000000000000000000000000000000000000000000000000 +0000000000000000000000000000000000000000000000000000000000000000 +0000000000000000000000000000000000000000000000000000000000000000 +0000000000000000000000000000000000000000000000000000000000000000 +0000000000000000000000000000000000000000000000000000000000000000 +cleartomark +{restore}if +%%EndResource +%%BeginResource: font ZapfDingbats-Reverse +%!PS-Adobe-3.0 Resource-Font +%%DocumentNeededResources: font ZapfDingbats +/ZapfDingbats findfont[-1 0 0 1 0 0]makefont +dup length 1 add dict begin +{ +exch dup dup/FID ne exch/UniqueID ne and{ +exch def +}{ +pop pop +}ifelse +}forall +/FontName/ZapfDingbats-Reverse def +/Metrics 202 dict dup begin +/space[0 -278]def +/a1[-939 -974]def +/a2[-926 -961]def +/a202[-939 -974]def +/a3[-945 -980]def +/a4[-685 -719]def +/a5[-754 -789]def +/a119[-755 -790]def +/a118[-756 -791]def +/a117[-655 -690]def +/a11[-925 -960]def +/a12[-904 -939]def +/a13[-520 -549]def +/a14[-821 -855]def +/a15[-876 -911]def +/a16[-898 -933]def +/a105[-876 -911]def +/a17[-910 -945]def +/a18[-939 -974]def +/a19[-721 -755]def +/a20[-811 -846]def +/a21[-727 -762]def +/a22[-726 -761]def +/a23[-572 -571]def +/a24[-641 -677]def +/a25[-728 -763]def +/a26[-725 -760]def +/a27[-724 -759]def +/a28[-719 -754]def +/a6[-459 -494]def +/a7[-517 -552]def +/a8[-502 -537]def +/a9[-542 -577]def +/a10[-657 -692]def +/a29[-751 -786]def +/a30[-753 -788]def +/a31[-753 -788]def +/a32[-755 -790]def +/a33[-758 -793]def +/a34[-759 -794]def +/a35[-781 -816]def +/a36[-788 -823]def +/a37[-754 -789]def +/a38[-806 -841]def +/a39[-788 -823]def +/a40[-798 -833]def +/a41[-781 -816]def +/a42[-796 -831]def +/a43[-888 -923]def +/a44[-709 -744]def +/a45[-688 -723]def +/a46[-714 -749]def +/a47[-756 -790]def +/a48[-757 -792]def +/a49[-660 -695]def +/a50[-741 -776]def +/a51[-733 -768]def +/a52[-757 -792]def +/a53[-724 -759]def +/a54[-672 -707]def +/a55[-673 -708]def +/a56[-647 -682]def +/a57[-666 -701]def +/a58[-791 -826]def +/a59[-780 -815]def +/a60[-754 -789]def +/a61[-754 -789]def +/a62[-673 -707]def +/a63[-651 -687]def +/a64[-661 -696]def +/a65[-654 -689]def +/a66[-752 -786]def +/a67[-752 -787]def +/a68[-678 -713]def +/a69[-756 -791]def +/a70[-749 -785]def +/a71[-756 -791]def +/a72[-838 -873]def +/a73[-726 -761]def +/a74[-727 -762]def +/a203[-727 -762]def +/a75[-724 -759]def +/a204[-724 -759]def +/a76[-857 -892]def +/a77[-857 -892]def +/a78[-753 -788]def +/a79[-749 -784]def +/a81[-403 -438]def +/a82[-103 -138]def +/a83[-242 -277]def +/a84[-380 -415]def +/a97[-357 -392]def +/a98[-358 -392]def +/a99[-633 -668]def +/a100[-632 -668]def +/a101[-697 -732]def +/a102[-488 -544]def +/a103[-510 -544]def +/a104[-875 -910]def +/a106[-632 -667]def +/a107[-725 -760]def +/a108[-760 -760]def +/a112[-741 -776]def +/a111[-561 -595]def +/a110[-659 -694]def +/a109[-592 -626]def +/a120[-753 -788]def +/a121[-753 -788]def +/a122[-753 -788]def +/a123[-753 -788]def +/a124[-753 -788]def +/a125[-753 -788]def +/a126[-753 -788]def +/a127[-753 -788]def +/a128[-753 -788]def +/a129[-753 -788]def +/a130[-753 -788]def +/a131[-753 -788]def +/a132[-753 -788]def +/a133[-753 -788]def +/a134[-753 -788]def +/a135[-753 -788]def +/a136[-753 -788]def +/a137[-753 -788]def +/a138[-753 -788]def +/a139[-753 -788]def +/a140[-753 -788]def +/a141[-753 -788]def +/a142[-753 -788]def +/a143[-753 -788]def +/a144[-753 -788]def +/a145[-753 -788]def +/a146[-753 -788]def +/a147[-753 -788]def +/a148[-753 -788]def +/a149[-753 -788]def +/a150[-753 -788]def +/a151[-753 -788]def +/a152[-753 -788]def +/a153[-753 -788]def +/a154[-753 -788]def +/a155[-753 -788]def +/a156[-753 -788]def +/a157[-753 -788]def +/a158[-753 -788]def +/a159[-753 -788]def +/a160[-859 -894]def +/a161[-803 -838]def +/a163[-982 -1016]def +/a164[-423 -458]def +/a196[-713 -748]def +/a165[-889 -924]def +/a192[-713 -748]def +/a166[-883 -918]def +/a167[-892 -927]def +/a168[-893 -928]def +/a169[-893 -928]def +/a170[-799 -834]def +/a171[-838 -873]def +/a172[-793 -828]def +/a173[-889 -924]def +/a162[-889 -924]def +/a174[-882 -917]def +/a175[-895 -930]def +/a176[-896 -931]def +/a177[-428 -463]def +/a178[-848 -883]def +/a179[-801 -836]def +/a193[-801 -836]def +/a180[-832 -867]def +/a199[-832 -867]def +/a181[-661 -696]def +/a200[-661 -696]def +/a182[-839 -874]def +/a201[-839 -874]def +/a183[-725 -760]def +/a184[-911 -946]def +/a197[-737 -771]def +/a185[-830 -865]def +/a194[-737 -771]def +/a198[-854 -888]def +/a186[-932 -967]def +/a195[-854 -888]def +/a187[-796 -831]def +/a188[-837 -873]def +/a189[-892 -927]def +/a190[-935 -970]def +/a191[-884 -918]def +/a205[-474 -509]def +/a206[-375 -410]def +/a85[-474 -509]def +/a86[-375 -410]def +/a87[-199 -234]def +/a88[-199 -234]def +/a89[-355 -390]def +/a90[-355 -390]def +/a91[-241 -276]def +/a92[-241 -276]def +/a93[-282 -317]def +/a94[-282 -317]def +/a95[-299 -334]def +/a96[-299 -334]def +end def +/ZapfDingbats-Reverse currentdict end definefont pop +%%EndResource +%%BeginResource: font Symbol-Slanted +%!PS-Adobe-3.0 Resource-Font +%%DocumentNeededResources: font Symbol +/MakeTransformedFont{ +findfont dup maxlength dict begin +{ +exch dup dup/FID ne exch/UniqueID ne and{ +exch def +}{ +pop pop +}ifelse +}forall +/FontBBox +currentdict/FontBBox get +4 array copy def +FontBBox aload pop +4 index transform 4 2 roll +4 index transform 4 2 roll +FontBBox astore pop +FontMatrix exch matrix concatmatrix +/FontMatrix exch def +dup/FontName exch def +currentdict end +definefont pop +}bind def +/Symbol-Slanted +[.89 0.0 15.5 dup sin exch cos div .89 0.0 0.0] +/Symbol +MakeTransformedFont +%%EndResource +grops begin/DEFS 1 dict def DEFS begin/u{.001 mul}bind def end/RES 72 +def/PL 841.89 def/LS false def/ENC0[/asciicircum/asciitilde/Scaron +/Zcaron/scaron/zcaron/Ydieresis/trademark/quotesingle/Euro/.notdef +/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef +/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef +/.notdef/.notdef/.notdef/space/exclam/quotedbl/numbersign/dollar/percent +/ampersand/quoteright/parenleft/parenright/asterisk/plus/comma/hyphen +/period/slash/zero/one/two/three/four/five/six/seven/eight/nine/colon +/semicolon/less/equal/greater/question/at/A/B/C/D/E/F/G/H/I/J/K/L/M/N/O +/P/Q/R/S/T/U/V/W/X/Y/Z/bracketleft/backslash/bracketright/circumflex +/underscore/quoteleft/a/b/c/d/e/f/g/h/i/j/k/l/m/n/o/p/q/r/s/t/u/v/w/x/y +/z/braceleft/bar/braceright/tilde/.notdef/quotesinglbase/guillemotleft +/guillemotright/bullet/florin/fraction/perthousand/dagger/daggerdbl +/endash/emdash/ff/fi/fl/ffi/ffl/dotlessi/dotlessj/grave/hungarumlaut +/dotaccent/breve/caron/ring/ogonek/quotedblleft/quotedblright/oe/lslash +/quotedblbase/OE/Lslash/.notdef/exclamdown/cent/sterling/currency/yen +/brokenbar/section/dieresis/copyright/ordfeminine/guilsinglleft +/logicalnot/minus/registered/macron/degree/plusminus/twosuperior +/threesuperior/acute/mu/paragraph/periodcentered/cedilla/onesuperior +/ordmasculine/guilsinglright/onequarter/onehalf/threequarters +/questiondown/Agrave/Aacute/Acircumflex/Atilde/Adieresis/Aring/AE +/Ccedilla/Egrave/Eacute/Ecircumflex/Edieresis/Igrave/Iacute/Icircumflex +/Idieresis/Eth/Ntilde/Ograve/Oacute/Ocircumflex/Otilde/Odieresis +/multiply/Oslash/Ugrave/Uacute/Ucircumflex/Udieresis/Yacute/Thorn +/germandbls/agrave/aacute/acircumflex/atilde/adieresis/aring/ae/ccedilla +/egrave/eacute/ecircumflex/edieresis/igrave/iacute/icircumflex/idieresis +/eth/ntilde/ograve/oacute/ocircumflex/otilde/odieresis/divide/oslash +/ugrave/uacute/ucircumflex/udieresis/yacute/thorn/ydieresis]def +/Courier@0 ENC0/Courier RE/Times-Italic@0 ENC0/Times-Italic RE +/Times-Roman@0 ENC0/Times-Roman RE/Times-Bold@0 ENC0/Times-Bold RE +%%EndSetup +%%Page: 1 1 +%%BeginPageSetup +BP +%%EndPageSetup +/F0 13/Times-Bold@0 SF(MetaP)232.652 127 Q(ost with gr)-.26 E(off)-.234 +E/F1 11/Times-Roman@0 SF 1.485(John Hobby')72 169.9 R 4.235(sM)-.605 G +1.485(etaPost program had an)-4.235 F/F2 11/Times-Italic@0 SF -.407(AT) +4.235 G 1.485(&T tr).407 F(of)-.495 E(f)-.198 E F1(interf)2.156 E 1.485 +(ace which ha)-.11 F 1.815 -.165(ve b)-.22 H 1.484(een changed to use) +.165 F F2(GNU tr)72 182.9 Q(of)-.495 E(f)-.198 E F1(instead.)4.906 E/F3 +11/Times-Bold@0 SF(Usage)72 208.9 Q F1 1.123 +(Since MetaPost is a picture-dra)72 225.8 R 1.123 +(wing language that outputs PostScript, it is necessary to use the)-.165 +F/F4 11/Courier@0 SF(-mpspic)72 238.8 Q F1 1.668 +(macro package, which is automatically included when)4.419 F F2(gr)4.418 +E(of)-.495 E(f)-.198 E F1 1.668(\(1\) is in)2.156 F -.22(vo)-.44 G -.11 +(ke).22 G 4.418(dw).11 G 1.668(ith the)-4.418 F F4(-Tps)72 251.8 Q F1 +(option to prepare output for PostScript printers or pre)2.75 E(vie) +-.275 E(wers.)-.275 E 3.517(Suppose you ha)99.5 268.7 R 3.847 -.165 +(ve w)-.22 H 3.518 +(ritten some \214gures in MetaPost and placed the input in a \214le).165 +F F4(figures.mp)72 281.7 Q F1 5.5(.R)C(unning)-5.5 E F4(mp -T figures) +108 301.2 Q F1(to in)72 320.7 Q -.22(vo)-.44 G .22 -.11(ke t).22 H +(he MetaPost interpreter produces output \214les).11 E F4(figures.1)2.75 +E F1(,)A F4(figures.2)2.75 E F1 2.75(,.)C 1.833(..)-.917 G .476 +(Standalone EPS pictures can be produced from such \214les by)99.5 337.6 +R F4(fixgrofffonts)3.225 E F1 3.225(,t)C .475(hat \214x)-3.225 F(es) +-.165 E .641(comments according to Adobe Document Structuring Con)72 +350.6 R -.165(ve)-.44 G .641(ntions \(DSC\), embeds font reencod-).165 F +(ing commands and non-standard fonts.)72 363.6 Q F4 +(fixgrofffonts < figures.1 > figures1.eps)108 383.1 Q +(fixgrofffonts < figures.2 > figures2.eps)108 396.1 Q(...)108 409.1 Q F1 +.469(Before these \214gures can be included into)99.5 432.5 R F2(gr) +3.219 E(of)-.495 E(f)-.198 E F1 3.219(,t)2.156 G(he)-3.219 E 3.219(yh) +-.165 G -2.475 -.22(av e)-3.219 H .469(to be processed with the)3.439 F +F4(fixmp)3.219 E F1 1.415(script: It adds an encoding v)72 445.5 R 1.415 +(ector for all te)-.165 F 1.416 +(xt fonts back to the \214le \(which MetaPost can')-.165 F 4.166(ta) +-.198 G(dd)-4.166 E .303 +(itself\) and changes the Adobe Document Structuring Con)72 458.5 R +-.165(ve)-.44 G .302(ntions \(DSC\) comments to something).165 F F2(gr) +72 471.5 Q(of)-.495 E(f)-.198 E F1(can handle.)4.906 E F4 +(fixmp < figures.1 > figures.1ps)108 491 Q +(fixmp < figures.2 > figures.2ps)108 504 Q(...)108 517 Q F1(No)72 536.5 +Q 2.75(wt)-.275 G(he con)-2.75 E -.165(ve)-.44 G +(rted \214les can be included in a).165 E F2(gr)2.75 E(of)-.495 E(f) +-.198 E F1(document via macro calls such as)4.906 E F4 +(.PSPIC figures.1ps [width [height]])108 556 Q F1 .615(as e)72 575.5 R +.615(xplained in the)-.165 F F2(gr)3.366 E(ops)-.495 E F1 .616 +(\(1\) documentation.).297 F .616 +(Note that the picture gets rescaled if the height and)6.116 F +(width in the)72 588.5 Q F4(.PSPIC)2.75 E F1(command don')2.75 E 2.75 +(tm)-.198 G(atch)-2.75 E F2(mp)2.75 E F1 1.21 -.605('s i).209 H +(dea of the picture dimensions.).605 E F3(An example)72 614.5 Q -6 -17 +79 79 -39 39 248.5 666.5 PBEGIN +%%BeginDocument: grdemo.1ps +%!PS-Adobe-3.0 EPSF-3.0 +%%BoundingBox: -6 -17 73 22 +%%HiResBoundingBox: -5.5 -16.14502 72.741 21.95007 +%%Creator: MetaPost 0.901 +%%CreationDate: 2006.03.12:1621 +%%Pages: 1 +%%DocumentNeededResources: font Times-Roman +%%+ font ZapfDingbats-Reverse +%%+ font Times-Italic +%%+ font Symbol-Slanted +%%+ font FreeEuro +%%EndComments +%%BeginSetup + /ptmr8g ENC0 /Times-Roman RE + /ptmr8g /ptmr8g def + /zfzdrr /ZapfDingbats-Reverse def + /ptmri8g ENC0 /Times-Italic RE + /ptmri8g /ptmri8g def + /fsyro /Symbol-Slanted def + /zfeu /FreeEuro def +/fshow {exch findfont exch scalefont setfont show}bind def +%%EndSetup +%%Page: 1 1 +newpath -2 -4.125 moveto +38.60602 -4.125 lineto +38.60602 8.78003 lineto +-2 8.78003 lineto + closepath fill + 1 setgray +newpath -3 -3.125 moveto +37.60602 -3.125 lineto +37.60602 9.78003 lineto +-3 9.78003 lineto + closepath fill + 0 setgray +0 0 moveto +(\275) ptmr8g 10.00005 fshow +10 0 moveto +(A) ptmr8g 8.00009 fshow +18.276 0 moveto +(+) zfzdrr 10.00005 fshow +30.166 0 moveto +(a) ptmr8g 10.00005 fshow + 0 0.5 dtransform truncate idtransform setlinewidth pop [] 0 setdash + 1 setlinejoin 10 setmiterlimit +newpath -3 -3.125 moveto +37.60602 -3.125 lineto +37.60602 9.78003 lineto +-3 9.78003 lineto + closepath stroke +newpath 70.491 2.32751 moveto +70.491 8.37088 65.59187 13.27 59.54851 13.27 curveto +53.50514 13.27 48.60602 8.37088 48.60602 2.32751 curveto +48.60602 -3.71585 53.50514 -8.61497 59.54851 -8.61497 curveto +65.59187 -8.61497 70.491 -3.71585 70.491 2.32751 curveto closepath fill + 1 setgray +newpath 69.491 3.32751 moveto +69.491 9.37088 64.59187 14.27 58.54851 14.27 curveto +52.50514 14.27 47.60602 9.37088 47.60602 3.32751 curveto +47.60602 -2.71585 52.50514 -7.61497 58.54851 -7.61497 curveto +64.59187 -7.61497 69.491 -2.71585 69.491 3.32751 curveto closepath fill + 0 setgray +gsave [0.9397 0.34203 -0.34203 0.9397 53.5435 -2.70255 ] concat 0 0 moveto +(e) ptmri8g 10.00005 fshow grestore +gsave [0.9397 0.34203 -0.34203 0.9397 56.45497 2.82672 ] concat 0 0 moveto +(i) ptmri8g 6.99997 fshow grestore +gsave [0.9397 0.34203 -0.34203 0.9397 58.2902 3.4947 ] concat 0 0 moveto +(w) fsyro 6.99997 fshow grestore +gsave [0.9397 0.34203 -0.34203 0.9397 63.22362 5.29033 ] concat 0 0 moveto +(t) ptmri8g 6.99997 fshow grestore +newpath 69.491 3.32751 moveto +69.491 9.37088 64.59187 14.27 58.54851 14.27 curveto +52.50514 14.27 47.60602 9.37088 47.60602 3.32751 curveto +47.60602 -2.71585 52.50514 -7.61497 58.54851 -7.61497 curveto +64.59187 -7.61497 69.491 -2.71585 69.491 3.32751 curveto closepath stroke + 1 setlinecap +newpath 37.60602 3.32751 moveto +47.60602 3.32751 lineto stroke +6.09799 12.92004 moveto +(\244) ptmr8g 10.00005 fshow +13.59799 12.92004 moveto +(\243) ptmr8g 10.00005 fshow +21.09799 12.92004 moveto +(\004) zfeu 10.00005 fshow +10.203 -12.00502 moveto +(\204) ptmr8g 10.00005 fshow + [3 3 ] 0 setdash +newpath -5.25 -15.89502 moveto +72.491 -15.89502 lineto +72.491 21.70007 lineto +-5.25 21.70007 lineto + closepath stroke +showpage +%%EOF +%%EndDocument +end PEND F1 2.21(This \214gure w)72 683.4 R 2.21(as deri)-.11 F -.165 +(ve)-.275 G 4.96(df).165 G 2.21(rom a \214le)-4.96 F F4(grdemo.mp)4.959 +E F1 2.209(and included at this point by in)4.959 F -.22(vo)-.44 G 2.209 +(king the).22 F F4(.PSPIC)72 696.4 Q F1 +(macro \(omitting the height and width parameters to a)2.75 E -.22(vo) +-.22 G(id rescaling\).).22 E(The \214le)99.5 713.3 Q F4(grdemo.mp)2.75 E +F1(looks lik)2.75 E 2.75(et)-.11 G(his:)-2.75 E 0 Cg EP +%%Page: 2 2 +%%BeginPageSetup +BP +%%EndPageSetup +/F0 11/Times-Roman@0 SF(-2-)281.587 49 Q/F1 9/Courier@0 SF(verbatimtex) +108 83 Q(.EQ)108 94 Q(delim $$)108 105 Q(.EN)108 116 Q(\\# etex)108 127 +Q(input boxes)108 149 Q(beginfig\(1\);)108 171 Q(pair shadowshift;)118.8 +182 Q(shadowshift = \(1, -1\) * bp;)118.8 193 Q +(def drawshadowed\(text t\) =)118.8 215 Q(forsuffixes $=t:)129.6 226 Q +(fill bpath$ shifted shadowshift;)140.4 237 Q(unfill bpath$;)140.4 248 Q +(drawboxed\($\);)140.4 259 Q(endfor)129.6 270 Q(enddef;)118.8 281 Q +(boxit.a\(btex \\[12] \\s8A\\s+2 \\[lh] a etex\);)118.8 303 Q +(circleit.b\(btex $e sup {i omega t}$ etex rotated 20\);)118.8 314 Q +(b.w - a.e = \(10bp, 0\);)118.8 336 Q(drawshadowed\(a, b\);)118.8 358 Q +(draw a.e .. b.w;)118.8 369 Q +(label.top\(btex \\[Cs] \\[Po] \\[Eu] etex, a.n\);)118.8 391 Q +(label.llft\(btex \\[Fn] etex, a.s\);)118.8 402 Q +(draw bbox currentpicture dashed evenly;)118.8 424 Q(endfig;)108 435 Q +(end)108 457 Q/F2 11/Times-Bold@0 SF(Changing GNU tr)72 489.5 Q +(off pipeline)-.198 E F0 .378(Note that, by def)99.5 506.4 R .378 +(ault, the typesetting commands in the)-.11 F/F3 11/Courier@0 SF(btex) +3.128 E F0 1.833(...)3.128 G F3(etex)1.295 E F0 .378(blocks in the abo) +3.128 F -.165(ve)-.165 G -.165(ex)72 519.4 S(ample are processed by).165 +E F3(eqn -Tps -d\\$\\$ | troff -Tps)108 538.9 Q F0 .411(If a dif)72 +558.4 R(ferent)-.275 E/F4 11/Times-Italic@0 SF(tr)3.161 E(of)-.495 E(f) +-.198 E F0 .41(pipeline must be used it can be speci\214ed via the)5.317 +F F3(TROFF)3.16 E F0(en)3.16 E .41(vironment v)-.44 F(ariable.)-.275 E +-.165(Fo)72 571.4 S(r).165 E F4(gr)2.75 E(of)-.495 E(f)-.198 E F0 2.75 +(,t)C(he follo)-2.75 E(wing is recommended:)-.275 E F3 +(TROFF='groff -teZ')108 590.9 Q F0 1.576(It adds)72 610.4 R F4(tbl)4.326 +E F0 1.576(to the pipeline in addition to)4.887 F F4(eqn)4.326 E F0 +4.326(,p)C 1.576(roducing output for)-4.326 F F4(gr)4.327 E(of)-.495 E +(f)-.198 E F0 2.787 -.605('s d)2.156 H(ef).605 E 1.577(ault `ps' de)-.11 +F(vice.)-.275 E .847(Note that you then ha)72 623.4 R 1.177 -.165(ve t) +-.22 H 3.597(os).165 G .847(pecify the left and right delimiters of) +-3.597 F F4(eqn)3.597 E F0 2.056 -.605('s i).264 H .846 +(n-line equations within).605 F +(the document \(which is good practice an)72 636.4 Q(yw)-.165 E(ay\).) +-.11 E .235(Macro de\214nitions and such can be added via the standard) +99.5 653.3 R F3(verbatimtex)2.986 E F0 1.833(...)2.986 G F3(etex)1.153 E +F0(mech-)2.986 E .556(anism that adds the gi)72 666.3 R -.165(ve)-.275 G +3.306(nm).165 G .556(aterial to the)-3.306 F F4(tr)3.306 E(of)-.495 E(f) +-.198 E F0 3.306(input. Such)5.462 F .556 +(material should not generate an)3.306 F 3.306(yo)-.165 G(ut-)-3.306 E +.118(put since this w)72 679.3 R .118(ould get mix)-.11 F .118 +(ed up with the ne)-.165 F(xt)-.165 E F3(btex)2.868 E F0 1.833(...)2.868 +G F3(etex)1.035 E F0 2.868(block. Note)2.868 F .118(the comment escape) +2.868 F(right before the \214rst)72 692.3 Q F3(etex)2.75 E F0 +(command in the abo)2.75 E .33 -.165(ve ex)-.165 H(ample to a).165 E +-.22(vo)-.22 G(id an empty line.).22 E 0 Cg EP +%%Trailer +end +%%EOF diff --git a/Master/texmf-dist/doc/metapost/base/source-manual/grdemo.eps b/Master/texmf-dist/doc/metapost/base/source-manual/grdemo.eps new file mode 100644 index 00000000000..ae476c19730 --- /dev/null +++ b/Master/texmf-dist/doc/metapost/base/source-manual/grdemo.eps @@ -0,0 +1,779 @@ +%!PS-Adobe-3.0 EPSF-3.0 +%%BoundingBox: -6 -17 73 22 +%%HiResBoundingBox: -5.5 -16.14502 72.741 21.95007 +%%Creator: MetaPost 0.901 +%%CreationDate: 2006.03.12:1621 +%%Pages: 1 +%%DocumentNeededResources: font Times-Roman ZapfDingbats Times-Italic Symbol +%%DocumentSuppliedResources: encoding groffEncoding +%%+ font ZapfDingbats-Reverse Symbol-Slanted FreeEuro +%%EndComments +%%BeginSetup +%%IncludeResource: font Times-Roman +%%IncludeResource: font ZapfDingbats +%%IncludeResource: font Times-Italic +%%IncludeResource: font Symbol +%%BeginResource: font Symbol-Slanted +%!PS-Adobe-3.0 Resource-Font +%%DocumentNeededResources: font Symbol +/MakeTransformedFont{ +findfont dup maxlength dict begin +{ +exch dup dup/FID ne exch/UniqueID ne and{ +exch def +}{ +pop pop +}ifelse +}forall +/FontBBox +currentdict/FontBBox get +4 array copy def +FontBBox aload pop +4 index transform 4 2 roll +4 index transform 4 2 roll +FontBBox astore pop +FontMatrix exch matrix concatmatrix +/FontMatrix exch def +dup/FontName exch def +currentdict end +definefont pop +}bind def +%%IncludeResource: font Symbol +/Symbol-Slanted +[.89 0.0 15.5 dup sin exch cos div .89 0.0 0.0] +/Symbol +MakeTransformedFont +%%EndResource +%%BeginResource: font ZapfDingbats-Reverse +%!PS-Adobe-3.0 Resource-Font +%%DocumentNeededResources: font ZapfDingbats +%%IncludeResource: font ZapfDingbats +/ZapfDingbats findfont[-1 0 0 1 0 0]makefont +dup length 1 add dict begin +{ +exch dup dup/FID ne exch/UniqueID ne and{ +exch def +}{ +pop pop +}ifelse +}forall +/FontName/ZapfDingbats-Reverse def +/Metrics 202 dict dup begin +/space[0 -278]def +/a1[-939 -974]def +/a2[-926 -961]def +/a202[-939 -974]def +/a3[-945 -980]def +/a4[-685 -719]def +/a5[-754 -789]def +/a119[-755 -790]def +/a118[-756 -791]def +/a117[-655 -690]def +/a11[-925 -960]def +/a12[-904 -939]def +/a13[-520 -549]def +/a14[-821 -855]def +/a15[-876 -911]def +/a16[-898 -933]def +/a105[-876 -911]def +/a17[-910 -945]def +/a18[-939 -974]def +/a19[-721 -755]def +/a20[-811 -846]def +/a21[-727 -762]def +/a22[-726 -761]def +/a23[-572 -571]def +/a24[-641 -677]def +/a25[-728 -763]def +/a26[-725 -760]def +/a27[-724 -759]def +/a28[-719 -754]def +/a6[-459 -494]def +/a7[-517 -552]def +/a8[-502 -537]def +/a9[-542 -577]def +/a10[-657 -692]def +/a29[-751 -786]def +/a30[-753 -788]def +/a31[-753 -788]def +/a32[-755 -790]def +/a33[-758 -793]def +/a34[-759 -794]def +/a35[-781 -816]def +/a36[-788 -823]def +/a37[-754 -789]def +/a38[-806 -841]def +/a39[-788 -823]def +/a40[-798 -833]def +/a41[-781 -816]def +/a42[-796 -831]def +/a43[-888 -923]def +/a44[-709 -744]def +/a45[-688 -723]def +/a46[-714 -749]def +/a47[-756 -790]def +/a48[-757 -792]def +/a49[-660 -695]def +/a50[-741 -776]def +/a51[-733 -768]def +/a52[-757 -792]def +/a53[-724 -759]def +/a54[-672 -707]def +/a55[-673 -708]def +/a56[-647 -682]def +/a57[-666 -701]def +/a58[-791 -826]def +/a59[-780 -815]def +/a60[-754 -789]def +/a61[-754 -789]def +/a62[-673 -707]def +/a63[-651 -687]def +/a64[-661 -696]def +/a65[-654 -689]def +/a66[-752 -786]def +/a67[-752 -787]def +/a68[-678 -713]def +/a69[-756 -791]def +/a70[-749 -785]def +/a71[-756 -791]def +/a72[-838 -873]def +/a73[-726 -761]def +/a74[-727 -762]def +/a203[-727 -762]def +/a75[-724 -759]def +/a204[-724 -759]def +/a76[-857 -892]def +/a77[-857 -892]def +/a78[-753 -788]def +/a79[-749 -784]def +/a81[-403 -438]def +/a82[-103 -138]def +/a83[-242 -277]def +/a84[-380 -415]def +/a97[-357 -392]def +/a98[-358 -392]def +/a99[-633 -668]def +/a100[-632 -668]def +/a101[-697 -732]def +/a102[-488 -544]def +/a103[-510 -544]def +/a104[-875 -910]def +/a106[-632 -667]def +/a107[-725 -760]def +/a108[-760 -760]def +/a112[-741 -776]def +/a111[-561 -595]def +/a110[-659 -694]def +/a109[-592 -626]def +/a120[-753 -788]def +/a121[-753 -788]def +/a122[-753 -788]def +/a123[-753 -788]def +/a124[-753 -788]def +/a125[-753 -788]def +/a126[-753 -788]def +/a127[-753 -788]def +/a128[-753 -788]def +/a129[-753 -788]def +/a130[-753 -788]def +/a131[-753 -788]def +/a132[-753 -788]def +/a133[-753 -788]def +/a134[-753 -788]def +/a135[-753 -788]def +/a136[-753 -788]def +/a137[-753 -788]def +/a138[-753 -788]def +/a139[-753 -788]def +/a140[-753 -788]def +/a141[-753 -788]def +/a142[-753 -788]def +/a143[-753 -788]def +/a144[-753 -788]def +/a145[-753 -788]def +/a146[-753 -788]def +/a147[-753 -788]def +/a148[-753 -788]def +/a149[-753 -788]def +/a150[-753 -788]def +/a151[-753 -788]def +/a152[-753 -788]def +/a153[-753 -788]def +/a154[-753 -788]def +/a155[-753 -788]def +/a156[-753 -788]def +/a157[-753 -788]def +/a158[-753 -788]def +/a159[-753 -788]def +/a160[-859 -894]def +/a161[-803 -838]def +/a163[-982 -1016]def +/a164[-423 -458]def +/a196[-713 -748]def +/a165[-889 -924]def +/a192[-713 -748]def +/a166[-883 -918]def +/a167[-892 -927]def +/a168[-893 -928]def +/a169[-893 -928]def +/a170[-799 -834]def +/a171[-838 -873]def +/a172[-793 -828]def +/a173[-889 -924]def +/a162[-889 -924]def +/a174[-882 -917]def +/a175[-895 -930]def +/a176[-896 -931]def +/a177[-428 -463]def +/a178[-848 -883]def +/a179[-801 -836]def +/a193[-801 -836]def +/a180[-832 -867]def +/a199[-832 -867]def +/a181[-661 -696]def +/a200[-661 -696]def +/a182[-839 -874]def +/a201[-839 -874]def +/a183[-725 -760]def +/a184[-911 -946]def +/a197[-737 -771]def +/a185[-830 -865]def +/a194[-737 -771]def +/a198[-854 -888]def +/a186[-932 -967]def +/a195[-854 -888]def +/a187[-796 -831]def +/a188[-837 -873]def +/a189[-892 -927]def +/a190[-935 -970]def +/a191[-884 -918]def +/a205[-474 -509]def +/a206[-375 -410]def +/a85[-474 -509]def +/a86[-375 -410]def +/a87[-199 -234]def +/a88[-199 -234]def +/a89[-355 -390]def +/a90[-355 -390]def +/a91[-241 -276]def +/a92[-241 -276]def +/a93[-282 -317]def +/a94[-282 -317]def +/a95[-299 -334]def +/a96[-299 -334]def +end def +/ZapfDingbats-Reverse currentdict end definefont pop +%%EndResource +%%BeginResource: font FreeEuro +%!PS-AdobeFont-1.0: FreeEuro 001.001 +%%Title: FreeEuro +%Version: 001.001 +%%CreationDate: Sun Jan 8 10:14:22 2006 +%%Creator: root +%Copyright: Created by Werner Lemberg with PfaEdit 1.0 +%Copyright: (http://pfaedit.sf.net); the serif shapes are based on the +%Copyright: Omega fonts created by Yannis Haralambous. +% Generated by FontForge 20060105 (http://fontforge.sf.net/) +%%EndComments + +FontDirectory/FreeEuro known{/FreeEuro findfont dup/UniqueID known{dup +/UniqueID get 4166882 eq exch/FontType get 1 eq and}{pop false}ifelse +{save true}{false}ifelse}{false}ifelse +11 dict begin +/FontType 1 def +/FontMatrix [0.001 0 0 0.001 0 0 ]readonly def +/FontName /FreeEuro def +/FontBBox {4 -23 903 710 }readonly def +/UniqueID 4166882 def +/PaintType 0 def +/FontInfo 10 dict dup begin + /version (001.001) readonly def + /Notice (Created by Werner Lemberg with PfaEdit 1.0 \050http://pfaedit.sf.net\051; the serif shapes are based on the Omega fonts created by Yannis Haralambous.) readonly def + /FullName (FreeEuro) readonly def + /FamilyName (FreeEuro) readonly def + /Weight (Medium) readonly def + /FSType 12 def + /ItalicAngle 0 def + /isFixedPitch false def + /UnderlinePosition -100 def + /UnderlineThickness 50 def +end readonly def +/Encoding 256 array + 0 1 255 { 1 index exch /.notdef put} for +dup 0/Euro.symbol put +dup 1/Euro.symbol.bold put +dup 2/Euro.symbol.slanted put +dup 3/Euro.symbol.bold.slanted put +dup 4/Euro.serif put +dup 5/Euro.serif.bold put +dup 6/Euro.serif.italic put +dup 7/Euro.serif.bold.italic put +dup 8/Euro.sansserif put +dup 9/Euro.sansserif.bold put +dup 10/Euro.sansserif.slanted put +dup 11/Euro.sansserif.bold.slanted put +dup 12/Euro.mono put +dup 13/Euro.mono.bold put +dup 14/Euro.mono.slanted put +dup 15/Euro.mono.bold.slanted put +readonly def +currentdict end +currentfile eexec +743F8413F3636CA85A9FFEFB50B4BB27302A5A63F932884E18BF5153AD36053037D1C6CD +04294AF6A35612DB9108AC8514CB5C4A8469971B75A09F9E662068B0685490EA8C73F2DE +2FBBCF85D15AB9385E529DAB15A40D408002E88D0C107F711BC66BF0F2E92FDDC6B188F9 +1EEB6B86050D5032E6ABCB11E343C6D795217B5973972E99A9420651ACF3B8FD4CAD1DA4 +B00642AD077A5B86240F89F2BC011009CB2CF173FF68E9A88F0018F187D5E036FE8D904F +211842FF01AA7CAADDEB9E5A534FA3F90BDB8F6FFE24F7AC6E7BD0A74CF29EBBA51871F0 +D1FF3262EA3CAFF583545FAB762B8D9BF14C8845C4EDB387B1248A4BCCB70AEDC6C67CF6 +C4648FA00124C44166D66DE1573C926CD9C6AE4F8B89E5987035D23195432204B648D458 +39F1769201B7C68828B3E49DFEF3065D705C2EBFFFB05B8A865CE4888872146C99671EFA +EE1F514B94B86A47AAA5F21A39786E77D443FA4CF8B525C98FC02459528C08410C679440 +CC3A160C40B14E03FAB3E267943E1FBACDD4C082777B31AD3591DAEA25DC60E0EE11AB59 +52C58879FCB35A54009A156730AF209A8D4F00CF7DD9870C8DC3E48C19BED68742376268 +0408FFD4A34A0D8659D44FADC9FC9D3084601C93FD9FCA770B1191500ECB12C8DBDB2032 +007CECE3C6A2CC8593386DC1464B94A09EA2A83438C71ACC7CAD72D074ABF6FB98EFC81B +6A3D672D2DCC637F34ACF18D469ED29FE2C49062380E6A32850F696834FC8E46A924164A +C64DF8F848D4D000EB6FD06A44D0320975A8EEE85173E4D7E39EC9DB03A8ED20DAED86D2 +73CE5762A5D35D1A81987F9CD9921E39C2C5CEDD661C3B3EE86B703C101C410E41648347 +7599C4CCB91234510ABAC16898D9D10E30B5FC1BABE78DF2A009E09E52816F2413899184 +AB8F942A496B56C9FDE630B13AD9F0996ADE29CABAF1443452B427A2280AD00B85F4657C +65B47E929FB0A2A31F257B24FE4ECBAFC878C306094088E00DB2DA6D36CECE30971846B6 +39DA9BA989109507FF21FD7198736278ED1CD021BFE7689D93B425D8B6CCCF07D37C22D7 +966FB87EFBE8F6A86D4F0C4BD38F5F3A41DCEDA924FD5F0D8FF089A0F44DFD37498507D3 +2A383FC717537744CC6868EB913D5C08CD0A3F935145FD5D811F01870F6136F4EFF757C5 +D03E73FC22F88624116C08C225C1711C96A01656999AAF7414163E75548AB89F8AA85F20 +9FA6EC242ECDA0953DC61EAE4107610380DFE2807101BDBA51391685990B3D1FFEFEC97E +0F0DE04283920370575AC06B8597EE756EEF7A3543A3E5F1B74343702A201C43411E7B76 +DC6422E2529E740A6BC6BD44ABAACD955406734AF0852471CC7B49325286AFFD2F9CFD04 +BB9CA4D0F6F0494CED1D2984E2C607FD2CE5C5A1F538CF9107771E691FAD51AE5DA70748 +F14F2FF7CE61292F6FA50D4510E4100360A4A2EBF7F9A03F7A4DAC981C6DE582BAFEBC23 +AD97EB56656A218B24D47C4345B398C14ECF5B76037D83FEB71E65F89C01133A5228496C +DF4BCC8BD4C615C9725511A2376A01C80F1EF38757CF104DD0809121EF1A2B9F11B5BDC7 +8E4F5A1463F37E952891370E1887644D26751A261FB5EE78BEA745F4F44A9B00098EDC4E +3547F5AE50DCBF29EF5BF82D653A148D340BC600EB411F4EA8A6A2D0B548D0B217E78943 +BDAED70072716A4406D685B55C2C0F490D2B472C49B278DB78E9914C3623825E595A541F +509F0E7BB1A827F4E6B0EA42C668932AB48D7B4A21AC0DA7451924D1AA7CDBE80C94F109 +1A4D91C3B908060FEB07D1B454A4CE4A60F8FACA6930313E09D5F11D1D8437E6B65EEE5B +B5570C3B66ABC491BD8CF63C2C62BC7B38A0CDFFE9D75627E6D3B23B608C7EEBD8FC655C +D197D28E8EB319814EA71B6AD63A966DB61D9C3C7D788683559C49338D037A235FD56FA0 +059DDC6017F0919926C323327C204139F07810575A8749877FB2C0C53AF4E3962613A0E8 +7D7C37A9974105992FC6B754CF23017C2E5851BCC90F48D6847EF1EF59E42032AFE03A98 +DB363827CA07E337A5852BE832772A2981864B8C1EDAD8759ACBC132ADD0BB360F40BAFD +FC7E5D32D724CF82FD3342D431F8F4CD9BDE2B07C8D8EED411E3A5889A8163CD1E2C2786 +F78AD3C1D9879FD6E93BD1FD8949DE47A8BCD219422B2F1316950B72E1E5170701795A0A +80709E894C218AA64DF5684719830066B995785AB9F1603FFDCEA945FEC09F57BF886F01 +A95811C7D4200E11C7CB373AAA4301E58F74E77519E11A89751A338B38D115B365547271 +DB19E51B85B30D1EB8E3E0B95436262D52471D65BBCF5DD94F6FF1210BF09628191F8F04 +3ED7109DE2AD284954564A1C80811B9AF1686DB799D36B50EB095AF37B9117992BB6B8F9 +0CE43ED10F9D0CE4B8ED76549239A626809ECA3D5A90E23D3CFBC776D6D816A293F2A80B +7267D1842FA102BAD77A2A775CB55473F40D3976AFC77ECDA131FF663A12795528A7EC15 +1D7854E759321709A8F4750716C949D71D332F9B0B80130916826F07E0165A5A1C5F3D8E +EF8CDB4EE3F688867FDDD47B4D67AD677F3134D90E07A1F0A8690169AC2E176BCB7CF260 +A70E374F3EC834E3B83D19CE3A52883024D2976E8E02C0B320CFD7B8BF66D11FBBF49353 +647AC4AB23A2A5689506AB83AD60AF8783E04815CABE60A3243FC633FD12D6DA50036691 +D3A0FBD4AD1309289565FC0C449510AD58085356AD829538B97A501FA73CEB693F09D551 +8FEAE6DE59FD7871AAED96A27127286C09FDD5A1EAE421CC38F56A4AF6AD5FA9BF96BF00 +2BE0A49BE6F27636DEB364A0762BCFF054020850C9222940B0E8A08E6A77240E1A0F42DC +07DAD0283BCD9DAC20E2A7542F5D74FC90D2661AD95350566F27125160C0525364D8B764 +E06FBC0F85531185F8B92B4ADE928B2CF0DD4736CAA76F6659D128E416E9792F24CB6B41 +CF369FF2BF9C360FA006938067DA606B2B19C8599FB28306FDACBF29841A169F6368384E +32B6BAD4179E345AB2B3CAB35E29E154228DCDC3D4C3317295A050A8AA86273BF7178A07 +65B598EE7061AE13B11B670F2E5F90F9FDD2F09A84F247DF9C90698A44A29BEC87B3C606 +E46A35D94986363CFEB26524FD7FB88092978128B0D246934D93BF90CDD94F7D243113C0 +8BDD1E09E4AC9F6E7A5A4FDB89150632CA41E3320D6B5AC722B27984D238D29A20F69BFD +1AB94BFA39EE52371CBEC64E16E37319ED189F2CC3992EC03A780AE4AFAEAC4FFB7A8340 +36F307F1BAB17477BF14809DA90E0AFBD0E3182D7E40A1EB1AABA8C64D9CA02044E85A82 +7FDB6C215F77FADC0443A04083E23DF21523DE178DF165F369E93AD21F34B4D72C24D5F4 +D6D19BE8F5B01AFCBBEC537C509FD7B388AA66A3E4CBCAA85601C20BEBBD2D3F11CE1CBC +E7D8FA53FA83710A80D8795AA5FF3C2E7F063DC05DC002E8278DCC1FAF9909FFE55A633D +86BE4C570BD9820327490CA61CA4FDDE381CDF70D97FF279F6A458E5D7B8DE5E1384F894 +3064F4F17D369F014D5A68C9F2E170BB59634AF060678CB4DC84450B94E34CA704B5DCE3 +67125FEE35A1B0A27F40E38D00CB779ACB34284080D5D78E30DE6233F0AD3FC22D170A60 +E2B7D4F206862D1890D16E3C9D720CCA05930814E00337AD8607098C68CBEB919504277D +B3AB769CD77745B375945BC4246B813F828099DAB82512936FE106B368F189ACE1A2EAE1 +4CF5FE1C91BD0D79CE179D34A0E85F8F1BFDEF9F28C1F26924D630E845CAA19BADC44B7B +ED9C6452C0AD01D108967D85E0779AEE557A9207164D22DFF7BCCE92D5CB9809ADFD332F +9567C92510CFC94796AA5A312C4484183B66C44DED8476F974CE6FEBFE86178B99F1820B +07B3D7C80F5CCCAE591BD8920814B4398A502756D3C945D07C6CD9FC2414086434151E87 +30C14D38764C532BDD5830E24C16BFF8CC19181621DD26E67259711E6CC43ED8AAE343B4 +B728BFD242C6C314B3D453DD3B3BC3986E736B4085C8D7498C9778538AC0F2DE17B9F89A +60082B571BE433119A9522F93A4C1222A26F94A199D71F50FA5BA94CDA733E26A43A3002 +564A841FCCC267EF8F1556CF85C8AF4A649F0AC533E0E859E3E2723525FCEC1B6E6A3CE9 +0B66D585B1E7C4B953ECF941B12D3003FE14852B7978126BE4B58DF8924651697B79F333 +F2D5BC34458DFD36826F8DFD374D0D59DD01FFC2C455B1A12AC80380F48A742013D0C3D9 +C7E040364633F0476D1ECE1870386871CE95099A30F881EBE00F6E140FE58F8C1D5F2B37 +35D12A9FF60157F8691DD64E60EF9B957C586D4E2E9D5474634F7AA44D50B11B001C66CC +F283185C6E65E32D2F2B8127B986CF62455067A5E621738C8A381D2B6A033F6C389BE878 +3179A54AD38D69223AD779A159B2D7D0AD1670A03171EB4C27930E1878037813CBC46214 +7486F3B8E9F7016C9E2E4C60B03A4C976D48EE3A20131AA00F4B79707FD801B3F7A7759A +3AFF3F6CEE749F2B32B01A582DC408384B8749307794914EAF7A0300E1C9AEF42DFFD828 +C5EE7D9730CE489F0A98C81E166B2B1EED3BCFACC370709947CFD29DEAD86C58FCF6AEA4 +8D670583BCA7018853B781340D7F4D1F2FA5703EDA8F1815F74407B4617016AD9BDF1F49 +340E7D89AF7CB5818B996201512968AA2B3D71C468C69DB46E514EC3CCBA360B3E80972D +86145148DC0BDD4ADDDFDC7D835DAAC0AA9B96DDD91973288B3A2A28BD6BB415C2A79818 +7F58F3402DA53B0600FA53A01AEEBCE5081BCC0645348BD1772C54A608E88499CE0103EA +C4ABC7FD74256C4F16A977BDF7F13843BFC6CCF16092740D9C1E7561EFD4EC6A3A30460E +A434D1921727FA26D9F56627DCD6AF95951E602936C4AC6C7A6F6DFEF2C0CE0571458B27 +BB31DA11C9E09DD3917F61140EFC4F059AC2FAC839BDDC0695B293C42BD17B1895A6B2B2 +F955821C5CE356B1AA33C5F361BB0F43828A20B9F193E71E057F45B6CC8ABE53EEFF801F +2B6CFB31B6DEB5D84EB8525B938AC424B3486DEA14982E5CF7F2D2C92F2D9B28033DE0C3 +4B610505771E0B1BE6AF03552EB8B44EC1190DAEB15DAAF21E7F2D437780484F0535D8ED +941A8FA13D379B911FC7AC99E4657DABD37891C467E8854DEAD2E34E05962F0EEC30B5D4 +B8FA6EBA42C102564A2FCDF679AFB7FC145C98EDCC81BF33DCFEB593CF8E7C2F6E9E22B7 +8B1DEE3B75C0E87AB95C6341A1D09948BF338B682F515D89230F8CDBFC72D56A00003EAD +F5BC0A6CC1A802A80480D6CEBA34631C7892909E049473E8328295069C0845571ECC9980 +CD8BCEB4C930C06601BFBE690FA0BB34631C7FF64D91A31BDF9035EC6E44EA12A79DF384 +FD82092DEAFB2D2E1B0C8ED903BCA55382F98FA5346ACC20900D86E64FF528C604D6815E +3DEFC5F71EBBBAC2B5787B2F25AE820AFDD4038CD58B0F1710C1EEC7DA521071DCCFB9BF +24C9EA1049EF59E61D20BFD50BCB5D8CBD0DC266B8836F34EB94858A54CE0C9E6088188A +EDE0BE39FAFE697AA6C8805CAD63DEE8A0CA226C91405DE5FE7FE8820124D6D79EA5F956 +8C5CBFEA24C4F3D601428329453F226C4C3E3E429E429C2E96DF25EE1DD7B5B12B2C1DA7 +CB0EE6EB0D018C2DD437A6883D2C2E57B9CB264CD3369C20AB831CDDAC5F57E550727C0B +CC9715B2C87C26C0A9A6A2F173C7B03F12F993B217466E7896E4764C6AF20CDF0634205F +3E38E6C8C6DE3A4269C5C6CF03E49D60F0E2F3D7B3ED302C3BDA4EC6332867A19C9CE8FD +6E2D0F2C597E11896A3E6EDC4B616F76B3355DFBF26DB2199963252C93AE423F1AE6683F +115E9B68672BFF4C9134EED4C51AE587CC859F742A283F3C9B6088B0B9E65A1EA521578A +E67D7396907129B83C1C9E2302D5FF46FCBF408E0FA69AA8F6E7193AE9E9DD5254201317 +B3D304BDCA689B683568BCAD9539C4D6BDA50814D8F251A70E76E7A5EECF719DD1655DA0 +605D9EFC940A8CF0FDEBC7146DE12F108959280903C34C69DC92F8205F2EE1D52F483AA7 +7E02F277A1186849056036CB24AB238AF08C903C4CEB4851991C24A8158EAE8D8F3BE56C +355FC26D7BBD2849B7ED9E1A25DFE98BC62A6797615BCE59DEAAFD5B6D08298E2DDAA611 +3DE60AB83FF7687B7ADD6706822270ECA925B559F2F9EC59C9AB0F365868DEC3122EE67F +BAFE7EBFACEC14D4D40C55F94ABBE8CE82CEA67FC1415D127786071CC06DCB653CCDED0B +40A9D49994865CF45BA494AC11543A0546DC37417BD01DB100273EE3F0E7D12093E50FD0 +E71B9A0326E8F35FCD86B3285781008ED03FCA1850D685CA5B62518C9194A0C7E8CFD5A9 +FF6A0EF508ADBCEDAB7C7144272F8C7DB274CE7AA09CFABCCA3E6967EF259A72C3B8F4FD +4605CBB99CE88B679F3EC9486C442B05D776B9D7FA8C04203DBDF33C0CF45B15E68C9376 +168229CC5176BC1E9707853192BD0C394E2D8880050594675F5B83488026791AEB1E6D79 +A424B8F90149F4855EF1BDF6CF0137D459D2A22DA3FF00743B52B2F9C316262EE53AE760 +43E2F267C2598CE66CFEAEF1459C307CA9B3FD8E897C93426545B80834EA16764633B2C5 +5B31557E6B5398F17D0BE5CC1348FE71014EF3BA2F917589AE4A4C9D8EF22A6D0A288557 +C4B2F2ABF2C30E778A5F21AA16BDD04CD8433514FBC7F81583F5D9CE3DE38542DCA55FFC +9142EB3B797946A7A121C134C82DAED820D3FF0E7053B40134353012A44B15506385533D +0702662BC8545130B7717B5E99BDC18E8473D2920C80CAD8F61D352C2B3718567B0BDFDF +F063D2E1A568D6B17412149E4C9AFE3FD3F8186A8274FC01CA07504BE6751A7BDE74719E +970A9F1744917E3521C4988E547EC1B63D33AD86390DB6CDBA9436884CEAA6064E383B61 +68BD405523A23D32B571E534354E1BD4EA3EDB7D1BBF2D0F6D6B36993DB0DF94C18BEBE2 +6F4B6475306784C091E139A759F627843CED43666D95AE257E650DDA0F6C0458CF27885F +25D59FE5601777ADCCB42ABC20F960B17A2669B4277AEE51A3D33BB1914FC5985236A6E0 +0C32956A1CAB55DD020DAFA2BAE36638E5F5866AEAB8E3439EFEA9266CB28B9DBA4B1746 +046A71E3BF05F37FF84CEFD66479640C3BB43D915BFA3AF6F3916F2AAAE39DD4317563C2 +26E361EE278E9FE076EE6B4733720C53918CA5CC9C5F4C6C7A36D8E49A591074AEFF0363 +09E5834A3978ACEB9016F116D20B6854BC59484F344D069768C6DFC503EB95C9FEA0521B +FD6E1C99FCD1268D18C1DD428C66DE9145071190FB17464C8C4FE87D9C0F3DA5FC3E933D +7375E88DC3BA96858D671A6616F52E70EC6B5795114C3F03F8C78CC388AC01866B347196 +40705C2EA04CC1369A88B3A242FFCB32B48024742A03C94A6E715EF09F06CC999CA1E593 +AB6013B7E25685C4FA93429EE0613E3DA07C94D82B9A739B954BD6EA1E2A9DE55461211B +4FBCCFF6BD480C845DC4B075B33551C760FE3D8F5EDB1201269AF48C8F8E96AFB5C7F767 +20AD3F9BDB225AF317770F1C2644589EDB5639376E30DB053930511FEE7C9FF81F6B76ED +57E4C6CF157AF5EE0D8E05F0B9F1276385B3C4EF779593B0120AAE0073880C0DE6F76906 +8B96E92133050EF7BA0A6585AB37880501F42477E0AB8A5D314F7A5A1B760142A42A40F2 +2A12F0F79C747F8C57C688C5937BCCF9B217647EA1D7C16936055814F9260C647045F3C8 +997D40B7BB690B654B9F243D2FC9343C7BAEC4F79AC5CA9C8A43E414B4BC6A6B02828CC2 +1432BBC6E49EAB7DAE35926C6B0BFBC6AC3831834CF54A732E8531AC7D0A3AF62A5FF8F2 +4B59EF71698824E2AC5E4DC2D5C58B9FFA80817C4DA7638CE5B6F0F33164FCCDA6F82933 +AE42A26BA9AA939A7DBD55F35C29BB9D192251E945D9890F48F63D7BB58269031899F7D5 +A52C1747CBEE945D55154AD30301FCC6345DF34A177E9CAB110D7A52B63B131A1F7D7165 +BB5AC4B1842B9A1F3D86F521E4107B40963BB34CC61B10F79D936736DEAC7F25BBDEC228 +E7838F1032154ADF35F333077483AFCDD50410C07707A47F9306BF794A15B5452EEB34FA +48A8C1BAA627EBB16BEBE9369AE7D100CF8D14E5B70613C8C8A53CA82495E8BAE8990ABE +0ACC0B2E9CC44191A50417657662385821B1C897C88AB2A0B149090CE11B940AC6DDB64D +0BF745858A1A56F811F1DE81458F50A704EA30F5F1918D9B5481E6E4681B389C447A65E3 +56A12C8592C8709C09135B06994590DD0B87D2952C871EF0B7365D04928A7B19AB3A10EF +40B0BA1DAB4D3DC5789EBDB23E98698963FBD74DAAB6C8885A88634E9857CBCB163B1D0E +32DF259DFEF7217D6744CC6F34E0D96C7BC93CC0A19F4EFBDAB6338CB56B46E538EE92B4 +353AA6663AC42A2EF78E4A228886577678FF36E5ED221A807E009D33A737F89F80461FA5 +5741EEF636D19FAD5870AF6F436DFCEA130C102156F134F77DFE4933628DBE64B477555D +81CE6131866AA5712347043CF70634F92D5B984445D32A545607B62BA1C12D37FB6B17F3 +84838E274818032AD7A07CDF1F504B3CB5C5C9D8D16342CAB18697A5821B2E219D14F15C +AAFB33A44E4E6D18C4DC64F79DDCBF2BFF7B3FE05709420DBBC24B8C23822755062B9784 +69AF6B01CDC9C45E55A71BC5BE1EDFDC23C430D61FF776BB4B2AB69BD391758462A9700E +21B81CE478207D443C5A868946969DA1E63AA939D3563605C83C2AB2C5E7551169F466D7 +41FDCEE57EEE7897C41F0409AB61E86C947C83850C23DE579ED1A7EF7F941522F41337A7 +F2FF06D4D5CC4A9436A2CEB91B1D9218F46BCC3A1A5C57539BD6A56C6755A8ADD89884F1 +2FF46C13248D02EACB04008BCE1CCC3DA9CB7D4EF0AF02A97734C95D8C45CC360AAA467E +97858E0B66978BB46353E9C0A653E49CC1E63C119FA50441846E5AE38D551BDF3A7CBD2B +8E51C2C088A617B68E21DD2F44EF5033CD252A75C80F16F6C45EBC84E17FA58F8DA6800B +8F61B060F54124F1B1F12AE75059159AF036C25DD06F4EEF5D8048079AC6CCB1BD5DA270 +005EC1428BC3F7A6369EC13EC8F99F77892D163FE605B8609940E1B27D784C57B7842BD7 +10C78480BF7EE7CF9BC29064CBCBE8B3B584C453C29851C39438E10BB9CAD4B2776B0899 +EDFF8CC4D35C8DF827743DC5D85681F4A7B9EAB43E133384B072F0D7A86EC6BFD5989503 +A95AA4DFF2FCB6BCEC468DFF75D20F9FD35015D4F98D65160E9EF8E1AE723433114B5458 +7B0A7314D320A942440D3D37F3BE4164C5D796C5D3597222EC88C7A14503EF964643B095 +E2F113FA22EA7999905633109628F97982451A9810D6A1DD84EB108D7A26E04C1C00488D +322774F47B555B28D24732E6C0D4D701933C9506D379B3E5BC10609B167C1064F34A4327 +A50D0D2FB470994714FB881EE3B88B054633BFF034650C0C4E4AE5720C35C7F3E4CD30E3 +6B26D8CD1813A7703867952488E01B23FDF799AE3AB35E4880E41B4DDBCF8CB4FA68423E +2D5E122264F8378BB8EA414C83D95A4A6D85995CE64A50B39C8E5F94955CDDBD88804D42 +279515FC1129FD2F50A170B214BED20695CCE59EAE0ACE91FCE6DD217B3A737A9DCAE11E +A0C746306AA9447F469BE68D8488E392D00583BAF1E63782C73D5201359CE7A768F24489 +0FA50098398CB006F74E9877E9E4373228269506F44931115C0E44654AFD6B48E3E2F6DD +47E738DE4CDC5344E1C26FAE5B73B9844F5CB2292D675CE88C2078DBDA11C2A9A58F4B10 +42850802766C9387734F22288F12E1F0D211FE150294FDD1744D8001AB95D9D63FD5C916 +B7886A1D6A076D14AD0B6D65E63D49CBC825E85CCFE3E6119DD05D6450980900600A0A07 +4BE3EE6801DAA9670D1BD6F7FE3332BF9B16C9D7DF782547006BF79DD5286A899E1153F1 +077B7AD8CDAC2724E1689A95B958D24566EA5759AF2276E2558AC8A110EA5CAB9C1BE598 +4031BBCA618B7EA15E87379927AF1D58AF01217B45B9CC67F79D96977624A9A01B1AA7A3 +1D0E4B61F6FC96A620867BAB29A7331DE35BC73E29DD89DEC1B5CA163679017FD5D52D6E +F359C8ACD7D149B509EB1E9EA1EBDDD572720F11A390AC61F898295FCCA27F466787CE24 +3C889A45EB97AE0AD87B5DB995DECB80D8A73592C9E17F02ED6BEFD6CFC5E56275366022 +E3EE687762FDB605B7221C7004DA9E8B594D6CA0B0AA5AD97D0231C228E38D21F2652470 +2524A76555EA690062A1C811C7708F33A432E4B93683D416BC6BFD9A3A9CD114ECEAD652 +98376657CFC1B1826B77B533314A3962ABA6137CF6502713BDA51FFC763CF78C7A0AFC99 +CD496DFE069FACD2669351BED17106952A3E55A13210C5024885CAF002343A31D1E64745 +E973853B94DE520B204922CE2063140C7403D7E038EA2D21D86A72E417DEF576BC60ED61 +B74A8237ABEBD176625ADC0B1475EF4D985D05148D0233041FB5F02920F4F4C769E2DF96 +8463AB7054465464844A2A1F1C427B9369BBF6221B0D557C1F1AFF62F710BA060FAA89D7 +3C6E7F5B09B2D1E192F47743BE288AB84682254C54ECDB6FB52E1013CFD075D0430D321D +C0A9B30AA8D1BF0676816E3FB7BB53E19B9C782E3B15732AF9A233408CD12FCBB1D3A963 +3910D9E4F84F1D89B0A26AFC1DF439654005CEDFD46A9B5FC815C91E72631D255475710A +CADB424EC5D2A86681422B36B8A6BE4DCA28EA5A919D9EE1B4F722518925484A59C6A972 +F68A0BC736BEBEF281DFA37F4F51BE2746644CAAC585DE766DCDF6443263C9A403E4E110 +32721D8C79C005B982D7B1A3E19AEAF0C89A2AB06841D677F79C3152E4B130B122BFC8ED +D6EFFAC69BA8C66C47F3D5321FB8A9C7156CFA2F0F577DF1CA2D8E9C6D854B401FF8DCF3 +BFBA7C98B11B3F128EA81DD1BB7B4FC24943B43772A6E731876CF46608CB88EB143AE9B1 +7D72DE503210705410B26CF1D70D7D4B98A2C4AC6F7AEBCE59BAB09F1C4D4E97EC3A9D91 +15554C98E2FC7DF130D4548875C0ECF16614BFDAC96E9230FAAB82C6EBDAA0EBCCD1ABC9 +F9DB0B987DF58240B927A6AF8BF1CA62C39DA2DFDF36DA884F67553F058CE4718777EDED +34E30501AC3DD9B8F9008463A33AA8612595E855D009CF9F7C1BDAC1DBD1483BCFF8A7DD +346DC22F31646C0CF07C753596AFC285F6136BF7E3C83B0FB75D9BDFA9979C0930A245D2 +7899ECA0F64F12C390EA7293E5EFA7A1D0721AAF72B313E6A14FD20B1B5AD9F3BE0F071E +33E89D4F5CC7111B4C06F18782A5A8F840CF27EE20B8BDC0B16E295D4AC30C2E079F75CB +23A338BB99D059095BE8E7D2FEE1BC421BEAFC536D2E2C40E05B6EF3CF483A34CE506816 +2CE04C4F2D9F17748F9FAFB67F046A168F4545D80ECF05266556DA6E75B018F790D5B821 +B5F9D115BA8E3A7B273B92E6E111CD257A6B12F4F25956AF908C8CEC671DBB796FA93893 +18D5B8473A04B63E0F751744D8050A1D266A15656A016697A9CA765660B5728E9BAC77CE +F7EFA339B522C2C52E6C678C550388136C678B2CD1027214D0D086028A29DD4785EEB512 +BD60CF2132746757559BE4C6B802792700B911D098F4A95A758B6E30285F906B6EE7B60D +991F86B1961FDC2BD5A9FA8F68E488AD57494765D9822A469FCAC1BDCE3F3685B09550D4 +49CE97D9FA83F187923C4DE772464EFE98A9789B93E5691C621E9B79F227041D22CB05A0 +22282BAA61BFC04863CEB7BA282CE68AE91CCDC2717747B3BCD808136F779DADFDBEECFF +E610CEE002874E4B33EF0ED4602073C56693BA2479D885F53FE4F5C68DF9C6B09D021342 +C117F488BFC7F2A7BADC2E059F0BF05AED5F6B8467CBE018D7AC442BC3526F8566A71B4A +69E93874F74F3B751B8C6811992D47DC4D080461269C6EB18AE76ECC66479B6A53E1984F +A17E13F546FD4AC12024A1ACE29C9BDCD47274E480017759381B2081349FF3AC5BAA1902 +2D9EB3DDC8471B0D2D58E3717973F7B7CD8E8AEAA301A676579AD57D112CF6D8F659B8CC +E055A155AB0F6C6B8A3254ADBD5E6BBAA336327F3AE20C109CA8C46EF35814473457E3F2 +EC80EE99547B84377DF391B0A9B2F60B818A0A3D49D5E36A2D7A05F4F77F964F81CC51D2 +272CD30B52AFB7AEE06129977A0AF98BFF236EADF92CD7508A2F3FE853EE26530922A59B +639571AA10FA5FC0E1315B7215B76045E18141403E4B0B2A9EB724E69BB40AC1AB479216 +1686D2B0DF545D0FA08CFACB8C8145AA9FB982222EE247B7DF2D5F2B33A9B6AE29CC6166 +3F642883EB6757DB8F1845E1727B7AADAE2FD8E560922467E79EF1803A03C9D51F649DD4 +16C75835F9EEB1FA6FAE978B1B7B7792FB24EDFD9EF55E67CB02D5C23C9628F126BD3A12 +31869DAE5FBBCE60133DEB7D33F1E0ADFD9927A3E9E42B6AB0E5D703BD7271A179985FC3 +D91C2D161B76F70987073647B26542C83A34172663F6793DE8B8D9BCD72CCD48DF5563C0 +FBFA6CC45D99AB78CD6ED8B861948E54DFE9C99E169E35A88D03C1C9A7C84720A3956B00 +0842CF8C515E3A722DDD0B6627926110B335744866564CC638901758FE0EFA98F4E3F4CF +DF911E5E395EC3D17807D7483008A95BA603AB80FB6A359BA3F0A8ADFE60F9CBADF67441 +1D0BE41B802B3EC9075DC1EB375EDCD27E113B4B1EA3C8ED0B1BBB2A3DB934CDC5CDA9B6 +0F85B33DD71FCA5B25B0AAA6B528229D84E1E7B97CB72C0F20248509A2B6CC53E5B7B694 +24FD8BFAE39C66E86DCEE0B602C9102A0575F15693B3C0A268C1C3F897F57E1CC5A58ADA +4222A57B2A53B234BA19ADA37208C16B1B757E106D5D8AF0AFFD6BBA6E753805BBC2E9A4 +450A78025400D18B8FDCA54A18440331E48E52E3C4CA80FC171B02293CED081E887215EA +D34DCF1D6FC2FE86502262006977878E4960326634F1A1EC8D2D96CF51EECDDD6D7CB410 +6D2B37136A13B4D2B67A2DCC74365A27E72B263FCF506B34116BB93BF76DA0C813CE6F63 +639BA86D000BEEED941AC2096A7F1C714615CE20F920BC4427BBB157105FC8FCC3D5FA6C +9C0D797AB7ECA5DA2B5DF210C4523E406821B704383C63055EB87E8C82E68ABB062487C8 +834EB35BA973902999E27D9A7D143536CB253195A3801FAF741C1588C808A1 +0000000000000000000000000000000000000000000000000000000000000000 +0000000000000000000000000000000000000000000000000000000000000000 +0000000000000000000000000000000000000000000000000000000000000000 +0000000000000000000000000000000000000000000000000000000000000000 +0000000000000000000000000000000000000000000000000000000000000000 +0000000000000000000000000000000000000000000000000000000000000000 +0000000000000000000000000000000000000000000000000000000000000000 +0000000000000000000000000000000000000000000000000000000000000000 +cleartomark +{restore}if +%%EndResource +/RE{ +findfont +dup maxlength 1 index/FontName known not{1 add}if dict begin +{ +1 index/FID ne{def}{pop pop}ifelse +}forall +/Encoding exch def +dup/FontName exch def +currentdict end definefont pop +}bind def +%!PS-Adobe-3.0 Resource-Encoding +% +% @psencodingfile{ +% author = "Werner Lemberg, Michail Vidiassov", +% version = "1.0", +% date = "2006-Feb-03", +% filename = "groff.enc", +% license = "public domain", +% email = "groff@gnu.org", +% docstring = "Groff default text encoding. Used with MetaPost." +% } + +%%BeginResource: encoding groffEncoding +/groffEncoding [ +% 0x00 | 0 + /asciicircum /asciitilde /Scaron /Zcaron + /scaron /zcaron /Ydieresis /trademark + /quotesingle /Euro /.notdef /.notdef + /.notdef /.notdef /.notdef /.notdef +% 0x10 | 16 + /.notdef /.notdef /.notdef /.notdef + /.notdef /.notdef /.notdef /.notdef + /.notdef /.notdef /.notdef /.notdef + /.notdef /.notdef /.notdef /.notdef +% 0x20 | 32 + /space /exclam /quotedbl /numbersign + /dollar /percent /ampersand /quoteright + /parenleft /parenright /asterisk /plus + /comma /hyphen /period /slash +% 0x30 | 48 + /zero /one /two /three + /four /five /six /seven + /eight /nine /colon /semicolon + /less /equal /greater /question +% 0x40 | 64 + /at /A /B /C + /D /E /F /G + /H /I /J /K + /L /M /N /O +% 0x50 | 80 + /P /Q /R /S + /T /U /V /W + /X /Y /Z /bracketleft + /backslash /bracketright /circumflex /underscore +% 0x60 | 96 + /quoteleft /a /b /c + /d /e /f /g + /h /i /j /k + /l /m /n /o +% 0x70 | 112 + /p /q /r /s + /t /u /v /w + /x /y /z /braceleft + /bar /braceright /tilde /.notdef +% 0x80 | 128 + /quotesinglbase /guillemotleft /guillemotright /bullet + /florin /fraction /perthousand /dagger + /daggerdbl /endash /emdash /ff + /fi /fl /ffi /ffl +% 0x90 | 144 + /dotlessi /dotlessj /grave /hungarumlaut + /dotaccent /breve /caron /ring + /ogonek /quotedblleft /quotedblright /oe + /lslash /quotedblbase /OE /Lslash +% 0xA0 | 160 + /.notdef /exclamdown /cent /sterling + /currency /yen /brokenbar /section + /dieresis /copyright /ordfeminine /guilsinglleft + /logicalnot /minus /registered /macron +% 0xB0 | 176 + /degree /plusminus /twosuperior /threesuperior + /acute /mu /paragraph /periodcentered + /cedilla /onesuperior /ordmasculine /guilsinglright + /onequarter /onehalf /threequarters /questiondown +% 0xC0 | 192 + /Agrave /Aacute /Acircumflex /Atilde + /Adieresis /Aring /AE /Ccedilla + /Egrave /Eacute /Ecircumflex /Edieresis + /Igrave /Iacute /Icircumflex /Idieresis +% 0xD0 | 208 + /Eth /Ntilde /Ograve /Oacute + /Ocircumflex /Otilde /Odieresis /multiply + /Oslash /Ugrave /Uacute /Ucircumflex + /Udieresis /Yacute /Thorn /germandbls +% 0xE0 | 224 + /agrave /aacute /acircumflex /atilde + /adieresis /aring /ae /ccedilla + /egrave /eacute /ecircumflex /edieresis + /igrave /iacute /icircumflex /idieresis +% 0xF0 | 240 + /eth /ntilde /ograve /oacute + /ocircumflex /otilde /odieresis /divide + /oslash /ugrave /uacute /ucircumflex + /udieresis /yacute /thorn /ydieresis +] def +%%EndResource + +% eof +%%BeginProlog + /ptmr8g groffEncoding /Times-Roman RE + /ptmr8g /ptmr8g def + /zfzdrr /ZapfDingbats-Reverse def + /ptmri8g groffEncoding /Times-Italic RE + /ptmri8g /ptmri8g def + /fsyro /Symbol-Slanted def + /zfeu /FreeEuro def +/fshow {exch findfont exch scalefont setfont show}bind def +%%EndSetup +%%Page: 1 1 +newpath -2 -4.125 moveto +38.60602 -4.125 lineto +38.60602 8.78003 lineto +-2 8.78003 lineto + closepath fill + 1 setgray +newpath -3 -3.125 moveto +37.60602 -3.125 lineto +37.60602 9.78003 lineto +-3 9.78003 lineto + closepath fill + 0 setgray +0 0 moveto +(\275) ptmr8g 10.00005 fshow +10 0 moveto +(A) ptmr8g 8.00009 fshow +18.276 0 moveto +(+) zfzdrr 10.00005 fshow +30.166 0 moveto +(a) ptmr8g 10.00005 fshow + 0 0.5 dtransform truncate idtransform setlinewidth pop [] 0 setdash + 1 setlinejoin 10 setmiterlimit +newpath -3 -3.125 moveto +37.60602 -3.125 lineto +37.60602 9.78003 lineto +-3 9.78003 lineto + closepath stroke +newpath 70.491 2.32751 moveto +70.491 8.37088 65.59187 13.27 59.54851 13.27 curveto +53.50514 13.27 48.60602 8.37088 48.60602 2.32751 curveto +48.60602 -3.71585 53.50514 -8.61497 59.54851 -8.61497 curveto +65.59187 -8.61497 70.491 -3.71585 70.491 2.32751 curveto closepath fill + 1 setgray +newpath 69.491 3.32751 moveto +69.491 9.37088 64.59187 14.27 58.54851 14.27 curveto +52.50514 14.27 47.60602 9.37088 47.60602 3.32751 curveto +47.60602 -2.71585 52.50514 -7.61497 58.54851 -7.61497 curveto +64.59187 -7.61497 69.491 -2.71585 69.491 3.32751 curveto closepath fill + 0 setgray +gsave [0.9397 0.34203 -0.34203 0.9397 53.5435 -2.70255 ] concat 0 0 moveto +(e) ptmri8g 10.00005 fshow grestore +gsave [0.9397 0.34203 -0.34203 0.9397 56.45497 2.82672 ] concat 0 0 moveto +(i) ptmri8g 6.99997 fshow grestore +gsave [0.9397 0.34203 -0.34203 0.9397 58.2902 3.4947 ] concat 0 0 moveto +(w) fsyro 6.99997 fshow grestore +gsave [0.9397 0.34203 -0.34203 0.9397 63.22362 5.29033 ] concat 0 0 moveto +(t) ptmri8g 6.99997 fshow grestore +newpath 69.491 3.32751 moveto +69.491 9.37088 64.59187 14.27 58.54851 14.27 curveto +52.50514 14.27 47.60602 9.37088 47.60602 3.32751 curveto +47.60602 -2.71585 52.50514 -7.61497 58.54851 -7.61497 curveto +64.59187 -7.61497 69.491 -2.71585 69.491 3.32751 curveto closepath stroke + 1 setlinecap +newpath 37.60602 3.32751 moveto +47.60602 3.32751 lineto stroke +6.09799 12.92004 moveto +(\244) ptmr8g 10.00005 fshow +13.59799 12.92004 moveto +(\243) ptmr8g 10.00005 fshow +21.09799 12.92004 moveto +(\004) zfeu 10.00005 fshow +10.203 -12.00502 moveto +(\204) ptmr8g 10.00005 fshow + [3 3 ] 0 setdash +newpath -5.25 -15.89502 moveto +72.491 -15.89502 lineto +72.491 21.70007 lineto +-5.25 21.70007 lineto + closepath stroke +showpage +%%EOF diff --git a/Master/texmf-dist/doc/metapost/base/source-manual/grdemo.mp b/Master/texmf-dist/doc/metapost/base/source-manual/grdemo.mp new file mode 100644 index 00000000000..14fb7609259 --- /dev/null +++ b/Master/texmf-dist/doc/metapost/base/source-manual/grdemo.mp @@ -0,0 +1,37 @@ +verbatimtex +.EQ +delim $$ +.EN +\# etex + +prologues := 2; + +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 \[12] \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; + + label.top(btex \[Cs] \[Po] \[Eu] etex, a.n); + label.llft(btex \[Fn] etex, a.s); + + draw bbox currentpicture dashed evenly; +endfig; + +end diff --git a/Master/texmf-dist/doc/metapost/base/source-manual/grdemo.ms b/Master/texmf-dist/doc/metapost/base/source-manual/grdemo.ms new file mode 100644 index 00000000000..fbcbfaceff4 --- /dev/null +++ b/Master/texmf-dist/doc/metapost/base/source-manual/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-manual/lead.d b/Master/texmf-dist/doc/metapost/base/source-manual/lead.d new file mode 100644 index 00000000000..2d09412438e --- /dev/null +++ b/Master/texmf-dist/doc/metapost/base/source-manual/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 diff --git a/Master/texmf-dist/doc/metapost/base/source-manual/manfig.mp b/Master/texmf-dist/doc/metapost/base/source-manual/manfig.mp new file mode 100644 index 00000000000..f9665370b0d --- /dev/null +++ b/Master/texmf-dist/doc/metapost/base/source-manual/manfig.mp @@ -0,0 +1,825 @@ +% Figures for MetaPost manual, by John Hobby. Public domain. + +filenametemplate "%j-%c.mps"; + +%%% This redefinition of dotlabel draws dots as a closed path +%%% which are rendered more smoothly in Adobe Reader. +vardef dotlabel@#(expr s,z) text t_ = + label@#(s,z) t_; + addto currentpicture + contour (makepath pencircle scaled dotlabeldiam) shifted z t_; +enddef; + + +%%% TeX macro \place is only used in figure 0. +verbatimtex +\input texnames.sty +\def\place#1{\vphantom{FiMP}\smash{#1}} +etex + +%%% The boxes package is only used in figure 0. +input boxes + +beginfig(0); +ba.dy = bb.dy = d.dy = 12bp; +d.dx = 100bp; +boxit.aa(btex \place{Figures in MetaPost} etex); +boxit.ab(btex \place{\TeX\ Document} etex); +boxit.ba(btex \hbox to 75bp {\hfil\place{MetaPost}\hfil} etex); +boxit.bb.(btex \hbox to 75bp {\hfil\place{\TeX\ or \LaTeX}\hfil} etex); +boxit.ca(btex \place{Figures in PostScript} etex); +boxit.cb(btex \place{{\tt dvi} file} etex); +boxit.d(btex \place{\tt dvips} etex); +boxit.e(btex PostScript etex); +boxit.f(btex \vbox{ + \hbox to 50bp {\hfil\hbox{bounding}\hfil} + \hbox to 50bp {\hfil\hbox{box}\hfil} + } etex scaled .8); +ba.n - aa.s = ca.n - ba.s += bb.n - ab.s = cb.n - bb.s += e.n - d.s = down * 25bp; +ypart cb.s - ypart d.n = 25bp; +e.s = origin; +ypart ca.s = ypart cb.s; +xpart aa.n = xpart 0.1[d.nw,d.ne]; +xpart ab.n = xpart 0.9[d.nw,d.ne]; +drawunboxed(aa,ab,ca,cb,e); +drawboxed(ba,bb,d); +drawarrow aa.s -- top ba.n; drawarrow ab.s -- top bb.n; +drawarrow ba.s -- top ca.n; drawarrow bb.s -- top cb.n; +drawarrow ca.s -- top 0.1[d.nw,d.ne]; +drawarrow cb.s -- top 0.9[d.nw,d.ne]; +drawarrow d.s -- top e.n; +path p; +p = ca.e{right} .. {right}bb.w; +f.c = point .5 of p; +drawunboxed(f); +draw p cutafter bpath f dashed evenly; +drawarrow p cutbefore subpath (1,3) of bpath f dashed evenly; +endfig; + + +beginfig(1); +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: + drawdot (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 "ptmr8r" 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; + + +beginfig(55) +picture wheel, car; +path body; + u := 5bp; + % Use a calligraphic pen. + pickup pencircle scaled .1u yscaled .6 rotated 30; + % Define a wheel object. + wheel := image( + draw fullcircle scaled 2u xscaled .8 rotated 30; + draw fullcircle scaled .1u xscaled .8 rotated 30 + withpen currentpen scaled .5; + ); + % Construct path for car body. + body := (3.2u,0){right}..(4.5u,1.5u){up}..(1.5u,2.5u){dir(-170)} + ..(1.5u,4.25u){up}...(0,5u){left}; + body := body .. reverse body reflectedabout (origin, (0,u)); + % Define a car object. + car := image( + draw wheel shifted (2u, 0);% Draw two wheels. + draw wheel shifted (-2u, 0); + draw (-.8u,0){dir(5)}..(.8u,0);% Draw connection betweeen wheels. + draw body;% Draw body. + % Draw speed indicators. + for i=1.5, 2, 2.5: + draw (5u, u*i){right}..{dir(-10)}(6.5u,u*i*.95); + endfor + ) shifted (0, u) slanted -.2 rotated 1;% Introduce asymmetries. + % Draw two cars and a faster one. + draw car shifted (5u,0); + draw car shifted (20u,0); + draw car slanted -.25 shifted (45u,0); + % Draw motorway. + draw (-5u,-u)...(25u,-.5u)...(60u,-u) + withpen currentpen scaled 4 withcolor .7white; +endfig; + +%%% Title page rule. +beginfig(60); + pickup pencircle scaled 1.1bp; + linecap := rounded; + draw origin--(4.38in,0); +endfig; + +end diff --git a/Master/texmf-dist/doc/metapost/base/source-manual/matmul.d b/Master/texmf-dist/doc/metapost/base/source-manual/matmul.d new file mode 100644 index 00000000000..6a0afe941ce --- /dev/null +++ b/Master/texmf-dist/doc/metapost/base/source-manual/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 diff --git a/Master/texmf-dist/doc/metapost/base/source-manual/mp.1 b/Master/texmf-dist/doc/metapost/base/source-manual/mp.1 new file mode 100644 index 00000000000..76df137ca79 --- /dev/null +++ b/Master/texmf-dist/doc/metapost/base/source-manual/mp.1 @@ -0,0 +1,289 @@ +.\" MetaPost man page, by John Hobby. Public domain. +.TH MP 1 +.CT 1 writing_other +.SH NAME +mp, MetaPost \- system for drawing pictures +.SH SYNOPSIS +.B mp +[ +.B -I +] +[ +.B -T +] +[ +.I first-line +] +.SH DESCRIPTION +.I Mp +interprets the MetaPost language and produces +.I PostScript +pictures. The MetaPost language is similar to Knuth's +.I METAFONT +with additional features for including +.IR tex (1) +or +.IR troff (1) +commands and accessing features of PostScript not found in METAFONT. +The +.B -T +flag selects +.I troff +instead of +.IR tex . +.PP +An argument given on the command line +behaves as the first input line. +That can be either a (possibly truncated) file name +or a sequence MetaPost commands starting with +.L \e +and including an +.L input +command. Thus +.L mp figs +processes the file +.LR figs.mp . +The basename of +.L figs +becomes the +.IR jobname , +and is used in forming output file names. If no file is named, the +jobname becomes +.LR mpout . +The default +.L .mp +extension can be overridden by specifying an extension explicitly. +.PP +There is normally one output file for each picture generated, +and the output files are named +.IR jobname.nnn , +where +.I nnn +is a number passed to the +.L beginfig +macro. The output file name +can also be +.IB jobname .ps +if this number is negative. +.PP +The output files can be used as figures in a TeX document by including +.ce +.BI "\especial{psfile=" jobname.nnn } +in the TeX document. Alternatively, one can +.L \einput epsf.tex +and then use the macro +.BI "\eepsfbox{" jobname.nnn } +to produce a box of the appropriate size containing the figure. +.TP +.BI btex " TeX commands " etex +This causes +.I mp +to generate a MetaPost picture expression that corresponds to the +TeX commands. If the TeX commands generate +more than one line of text, it must be in a +.L \evbox +or a minipage environment. +.TP +.BI verbatimtex " TeX commands " etex +This is ignored by +.I mp +except that the TeX commands are passed on to TeX. When using LaTeX +instead of TeX the input file must start with a +.L verbatimtex +block that gives the +.L \edocumentstyle +and +.L "\ebegin{document}" +commands. +.PP +Since most TeX fonts have to be downloaded as bitmaps, the +.L btex +feature works best when the output of +.L mp +is to be included in a TeX document so that +.IR dvips (1) +can download the fonts. For self-contained PostScript output that can be +used directly or included in a +.I troff +document, start your MetaPost input file with the command +.L "prologues:=1" +and stick to standard PostScript fonts. TeX and MetaPost use the names in the +third column of the file +.LR /usr/lib/mp/trfonts.map . +.PP +MetaPost output can be included in a +.I troff +document via the +.L "-mpictures" +macro package. In this case +.I mp +should be invoked with the +.B -T +flag so that the commands between +.L btex +and +.L etex +or between +.L verbatimtex +and +.L etex +are interpreted as +.I troff +instead of TeX. (This automatically sets +.L prologues:=1 +). +.PP +Here is a list of the environment variables affect the behavior of +.IR mp : +.TF MPXCOMMAND +.TP +.B MPINPUTS +Search path for +.L \einput +files. +It should be colon-separated, +and start with dot. +Default: +.L .:/usr/lib/mp +.TP +.B MFINPUTS +Auxiliary search path for +.L \einput +files with +.L .mf +extensions. +.TP +.B TEXFONTS +Search path for font metric files. +.TP +.B MPXCOMMAND +The name of a shell script that converts embedded typesetting commands +to a form that +.I mp +understands. +Defaults: +.L /usr/lib/mp/bin/makempx +for +.I tex +and +.L /usr/lib/mp/bin/troffmpx +for +.I troff +.TP +.B TEX +The version of TeX to use when processing +.L btex +and +.L verbatimtex +commands. Default: +.L tex +.TP +.B TROFF +The +.I troff +pipeline for +.L btex +and +.L verbatimtex +commands. Default: +.L eqn -d\e$\e$ | troff +.TP +.B MPMEMS +Search path for +.L .mem +files. Default: +.L .:/usr/lib/mp +.TP +.B MPPOOL +Search path for strings. +Default: +.L .:/usr/lib/mp +.TP +.B MPEDITOR +A command for invoking an editor with +.L %s +in place of the file name and +.L %d +in place of the line number. +.TP +.B TEXVFONTS +Search path for virtual fonts. +.TP +.B MPTEXPRE +Name of a file that is prepended before running tex. +If this file exists, +.I mp +behaves as if the file were inside of a +.L verbatimtex +block at the beginning of each input file. Default: +.L mptexpre.tex +.PD +.PP +A +.L .mem +file is a binary file that permits fast loading of fonts and macro packages. +.I Mp +reads the default +.F plain.mem +unless another +.L .mem +file is specified at the start of the first line with an +.L & +just before it. There is also an +.F mfplain.mem +that simulates plain METAFONT so that +.I mp +can read +.L .mf +fonts. (Plain METAFONT is described in +.I The +.IR METAFONTbook ). +.PP +Experts can create +.L .mem +files be invoking +.I mp +with the +.B -I +switch and giving macro definitions followed by a +.L dump +command. +.PP +The MetaPost language is similar to METAFONT, but the manual +.I A User's Manual for MetaPost +assumes no knowledge of METAFONT. MetaPost does not have bitmap +output commands or METAFONT's online display mechanism. +.SH FILES +.TF /usr/lib/mp/trfonts.map +.TP +.F /usr/lib/mp/* +macros, +.L .mem +files, and tables for handling included +.I tex +and +.I troff +.TP +.F /usr/lib/mp/bin +Directory for programs that handle included +.I tex +and +.IR troff . +.F /usr/lib/mp/trfonts.map +table of corresponding font names for +.IR troff , +PostScript, and TeX +.TP +.F /usr/lib/mp/examples.mp +The source file for a few sample figures. +.IR troff . +.SH "SEE ALSO" +.IR tex (1), +.br +Donald E. Knuth, +.I The METAFONTbook, +Addison Wesley, 1986, +.br +John D. Hobby, +.I A User's Manual for MetaPost +CSTR 162. diff --git a/Master/texmf-dist/doc/metapost/base/source-manual/mpboxes.bib b/Master/texmf-dist/doc/metapost/base/source-manual/mpboxes.bib new file mode 100644 index 00000000000..6adf4cd1c7a --- /dev/null +++ b/Master/texmf-dist/doc/metapost/base/source-manual/mpboxes.bib @@ -0,0 +1,20 @@ +% BibTeX entries for MetaPost doc, by John Hobby. Public domain. + +@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 +} +} diff --git a/Master/texmf-dist/doc/metapost/base/source-manual/mpboxes.mp b/Master/texmf-dist/doc/metapost/base/source-manual/mpboxes.mp new file mode 100644 index 00000000000..10ec530dbe4 --- /dev/null +++ b/Master/texmf-dist/doc/metapost/base/source-manual/mpboxes.mp @@ -0,0 +1,146 @@ +% Figures for MetaPost doc, by John Hobby. Public domain. + +input boxes + +if scantokens(mpversion) < 1.200: + filenametemplate +else: + outputtemplate := +fi +"%j-%c.mps"; + +%%% This redefinition of dotlabel draws dots as a closed path +%%% which are rendered more smoothly in Adobe Reader. +vardef dotlabel@#(expr s,z) text t_ = + label@#(s,z) t_; + addto currentpicture + contour (makepath pencircle scaled dotlabeldiam) shifted z t_; +enddef; + + +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 diff --git a/Master/texmf-dist/doc/metapost/base/source-manual/mpboxes.tex b/Master/texmf-dist/doc/metapost/base/source-manual/mpboxes.tex new file mode 100644 index 00000000000..a167df8e267 --- /dev/null +++ b/Master/texmf-dist/doc/metapost/base/source-manual/mpboxes.tex @@ -0,0 +1,572 @@ +\listfiles +\RequirePackage{ifpdf} +\ifpdf +\ifnum\pdftexversion<140 +\else +\pdfminorversion=5 +\pdfobjcompresslevel=1% Use compressed object streams. +\fi +\RequirePackage{cmap} +\fi +\documentclass{article} % article is NOT the original style +\usepackage[T1]{fontenc} +\usepackage{lmodern} +\usepackage{textcomp} +\usepackage{mflogo} +\usepackage{makeidx} +\usepackage{fancyvrb} +\usepackage{ctabbing} +\RecustomVerbatimEnvironment{verbatim}{BVerbatim}{baseline=c} +\usepackage{graphics} +\usepackage[textwidth=6in,textheight=8.65in]{geometry} +\usepackage{multicol} +\usepackage{ltxtable} + +\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 + +\newcommand\mathcenter[1]{\vcenter{\hbox{#1}}} + +\makeindex + +\author{John D. Hobby} +\title{Drawing Boxes with {MetaPost}} +\date{} + +\newcommand\myabstract{% + This paper describes a package for drawing boxes of different shapes. + The \texttt{boxes} package has been implemented as an extension to the + MetaPost graphics language and is a mandatory part of every MetaPost + installation.} + +\newcommand\mykeywords{% + typesetting; graphs; MetaPost} + +\usepackage[rgb,x11names]{xcolor}% Optimize for screen reading. +\usepackage{hyperxmp} +\usepackage{hyperref} +\hypersetup{ + pdftitle={Drawing Boxes with MetaPost}, + pdfauthor={John D. Hobby and the MetaPost development team}, + pdfkeywords={typesetting, boxes, MetaPost, TeX} +} +\hypersetup{ + pdfstartview={XYZ null null null},% Zoom factor is determined by viewer. + colorlinks, + linkcolor=RoyalBlue3, + urlcolor=Chocolate4, + citecolor=SpringGreen3 +} +\usepackage[all]{hypcap} +\ifpdf +\pdfmapfile{=cm2lm.map}% replace CM by LM in figures +\else +\DeclareGraphicsExtensions{.mps} +\DeclareGraphicsRule{mps}{eps}{*}{} +\usepackage{breakurl} +\fi + + +\begin{document} + \maketitle + \begin{abstract} \myabstract \end{abstract} + \ifx\keywords\undefined \else + \begin{keywords} \mykeywords \end{keywords} + \fi + +\setlength{\columnsep}{2.5em} +\begin{multicols}{2} +\tableofcontents +\end{multicols} + + +\section{Introduction} +\label{intro} + +This document 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 \texttt{/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. + +Since the advent of the \texttt{boxes} package several alternative +packages for drawing boxes of all kinds have been developed by the +MetaPost community. The most widely known ones are +\texttt{MetaObj}\index{MetaObj?\texttt{MetaObj}}, +\texttt{MetaUML}\index{MetaUML?\texttt{MetaUML}}, +\texttt{expressg}\index{expressg?\texttt{expressg}}, and +\texttt{blockdraw\_mp}\index{blockdraw\_mp?\texttt{blockdraw\_mp}}. If +you intend to create lots of structural drawings, flow charts, +\emph{etc.}, those packages might be an interesting ressource, too. + + +\section{Rectangular Boxes} +\label{rectbox} + +\mbox{}% Start paragraph. +\index{variables!box|(}% +\index{box variables|see{variables, box}}% +% +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|see{variables, internal}}\index{variables!internal} {\tt +defaultdx}\index{defaultdx?\texttt{defaultdx}}\label{Ddefaultdx} and +{\tt defaultdy}\index{defaultdy?\texttt{defaultdy}}\label{Ddefaultdy}.% +% +\index{variables!box|)} + +\begin{figure}[htp] +$$ \includegraphics{mpboxes-48.mps} $$ +\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{\includegraphics{mpboxes-49.mps}}} +$$ +\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. + + +\section{Circular and Oval Boxes} +\label{circbox} + +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}. + +\mbox{}% Start paragraph. +\index{variables!box|(}% +% +The {\tt circleit} macro defines pair variables 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}.% +% +\index{variables!box|)} + +\begin{figure}[htp] +$$ \includegraphics{mpboxes-50.mps} $$ +\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{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{\includegraphics{mpboxes-51.mps}} $$ +\caption[MetaPost code and the resulting figure.] {MetaPost code and + the resulting figure. Note that the {\tt drawshadowed} macro + used here is not part of the {\tt boxes.mp} macro package.} +\label{fig51} +\index{drawshadowed?\texttt{drawshadowed}} +\end{figure} + +\mbox{}% Start paragraph. +\index{variables!box|(}% +% +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}}.% +% +\index{variables!box|)} + +\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{\includegraphics{mpboxes-52.mps}}} +$$ +\caption{MetaPost code and the corresponding figure} +\label{fig52} +\end{figure} + + + +\appendix +\section{Reference manual} +\label{refman} + +Tables~\ref{pseudotab} to~\ref{ivartab} summarize macros, box variables +and internal variables provided by the \texttt{boxes} package. + +\begin{table}[hp] +\centering +\caption{\strut Function-Like Macros} +\label{pseudotab} +\begin{tabular}[t]{|>{\ttfamily}l|l|l|r|>{\arraybackslash}p{2.5in}|} +\hline +\multicolumn1{|c}{Name}& \multicolumn1{|c}{Arguments}& + \multicolumn1{|c}{Result}& \multicolumn1{|c}{Page}& + \multicolumn1{|c|}{Explanation}\\ +\hline +\hline +boxit\index{boxit?\texttt{boxit}}& suffix, picture& --& \pageref{Dboxit}& + Define a box containing the picture\\\hline +boxit\index{boxit?\texttt{boxit}}& suffix, string& --& \pageref{Dsboxit}& + Define a box containing text\\\hline +boxit\index{boxit?\texttt{boxit}}& suffix, \tdescr{empty}& --& \pageref{Deboxit}& + Define an empty box\\\hline +boxjoin\index{boxjoin?\texttt{boxjoin}}& equations& --& \pageref{Dbxjoin}& + Give equations for connecting boxes\\\hline +bpath\index{bpath?\texttt{bpath}}& suffix& path& \pageref{Dbpath}& + A box's bounding circle or rectangle\\\hline +circleit\index{circleit?\texttt{circleit}}& suffix, picture& --& \pageref{Dcircit}& + Put picture in a circular box\\\hline +circleit\index{circleit?\texttt{circleit}}& suffix, picture& --& \pageref{Dcircit}& + Put a string in a circular box\\\hline +circleit\index{circleit?\texttt{circleit}}& suffix, \tdescr{empty}& --& \pageref{Dcircit}& + Define an empty circular box\\\hline +drawboxed\index{drawboxed?\texttt{drawboxed}}& list of suffixes& --& \pageref{Ddrbxed}& + Draw the named boxes and their contents\\\hline +drawboxes\index{drawboxes?\texttt{drawboxes}}& list of suffixes& --& \pageref{Ddrbxes}& + Draw the named boxes\\\hline +drawunboxed\index{drawunboxed?\texttt{drawunboxed}}& list of suffixes& --& \pageref{Ddrunbx}& + Draw contents of named boxes\\\hline +fixpos\index{fixpos?\texttt{fixpos}}& list of suffixes& --& \pageref{Dfixpos}& + Solve for the size and position of the named boxes\\\hline +fixsize\index{fixsize?\texttt{fixsize}}& list of suffixes& --& \pageref{Dfixsiz}& + Solve for size of named boxes\\\hline +pic\index{pic?\texttt{pic}}& suffix& picture& \pageref{Dpic}& + Box contents shifted into position\\\hline +\end{tabular} +\end{table} + +\begin{table}[hp] +\centering +\caption{\strut Box variables} +\label{boxvartab} +\index{variables!box} +\begin{tabular}[t]{|>{\ttfamily $\descr{box name}$.}l|>{\arraybackslash}p{2in}|c|} +\hline +\multicolumn1{|c|}{Variable}& \multicolumn1{c|}{Explanation}& Validity\\ +\hline +\hline +c ¢er point &\\ +n &top center point &\\ +s &bottom center point &\\ +w ¢er left point &\\ +e ¢er right point &\\ +nw &top left corner &\texttt{boxit} only\\ +ne &top right corner &\texttt{boxit} only\\ +sw &bottom left corner &\texttt{boxit} only\\ +se &bottom right corner &\texttt{boxit} only\\ +dx &horizontal clearance &\\ +dy &vertical clearance &\\ +off &actual location of box contents &\\ +\hline +\end{tabular} +\end{table} + +\begin{table}[hp] +\centering +\caption{\strut Internal variables with numeric values} +\label{ivartab} +\index{variables!internal} +\begin{tabular}[t]{|>{\ttfamily}l|r|>{\arraybackslash}p{3.5in}|} +\hline +\multicolumn1{|c}{Name}& \multicolumn1{|c}{Page}& \multicolumn1{|c|}{Explanation}\\ +\hline +\hline +circmargin\index{circmargin?\texttt{circmargin}}& \pageref{Dcmargin}& + clearance around contents of a circular or oval box\\\hline +defaultdx\index{defaultdx?\texttt{defaultdx}}& \pageref{Ddefaultdx}& + usual horizontal space around box contents (default 3{\tt bp})\\\hline +defaultdy\index{defaultdy?\texttt{defaultdy}}& \pageref{Ddefaultdy}& + usual vertical space around box contents (default 3{\tt bp})\\\hline +\end{tabular} +\end{table} + + +\bibliographystyle{plain} +\bibliography{mpboxes} + +\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. + +%%% Local Variables: +%%% mode: latex +%%% TeX-PDF-mode: t +%%% TeX-master: t +%%% End: diff --git a/Master/texmf-dist/doc/metapost/base/source-manual/mpgraph.bib b/Master/texmf-dist/doc/metapost/base/source-manual/mpgraph.bib new file mode 100644 index 00000000000..27ef07de1ff --- /dev/null +++ b/Master/texmf-dist/doc/metapost/base/source-manual/mpgraph.bib @@ -0,0 +1,98 @@ +% BibTeX entries for MetaPost doc, by John Hobby. Public domain. + +@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, revised 1994" +} +@book{Cleve93, + author = "Cleveland, William S.", + title = "Visualizing Data", + publisher = "Hobart Press", + address = "Summit, New Jersey", + year= 1993, +} +@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 +} diff --git a/Master/texmf-dist/doc/metapost/base/source-manual/mpgraph.mp b/Master/texmf-dist/doc/metapost/base/source-manual/mpgraph.mp new file mode 100644 index 00000000000..2c94edfe549 --- /dev/null +++ b/Master/texmf-dist/doc/metapost/base/source-manual/mpgraph.mp @@ -0,0 +1,141 @@ +% Figures for MetaPost doc, by John Hobby. Public domain. + +input graph + +if scantokens(mpversion) < 1.200: + filenametemplate +else: + outputtemplate := +fi +"%j-%c.mps"; + +%if false: %% Begin skipping already debugged figures +%fi input sarith %% End skipping of already debugged figures + +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 withpen nullpen; + 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; + gdraw p; + 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 diff --git a/Master/texmf-dist/doc/metapost/base/source-manual/mpgraph.tex b/Master/texmf-dist/doc/metapost/base/source-manual/mpgraph.tex new file mode 100644 index 00000000000..759c6e85061 --- /dev/null +++ b/Master/texmf-dist/doc/metapost/base/source-manual/mpgraph.tex @@ -0,0 +1,1044 @@ +% $Id: mpgraph.tex 870 2009-03-06 11:04:56Z stephanhennig $ +% MetaPost graph doc, by John Hobby. License at end. +\listfiles +\RequirePackage{ifpdf} +\ifpdf +\ifnum\pdftexversion<140 +\else +\pdfminorversion=5 +\pdfobjcompresslevel=1% Use compressed object streams. +\fi +\RequirePackage{cmap} +\fi +\documentclass{article} % article is NOT the original style +\usepackage[T1]{fontenc} +\usepackage{lmodern} +\usepackage{textcomp} +\usepackage{mflogo} +\usepackage{makeidx} +\usepackage{fancyvrb} +\usepackage{ctabbing} +\RecustomVerbatimEnvironment{verbatim}{BVerbatim}{baseline=c} +\usepackage{graphics} +\usepackage[textwidth=6in,textheight=8.65in]{geometry} +\usepackage{multicol} + +\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 + +\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} + +\usepackage[rgb,x11names]{xcolor}% Optimize for screen reading. +\usepackage{hyperxmp} +\usepackage{hyperref} +\hypersetup{ + pdftitle={Drawing Graphs with MetaPost}, + pdfauthor={John D. Hobby and the MetaPost development team}, + pdfkeywords={typesetting, graphs, MetaPost, TeX} +} +\hypersetup{ + pdfstartview={XYZ null null null},% Zoom factor is determined by viewer. + colorlinks, + linkcolor=RoyalBlue3, + urlcolor=Chocolate4, + citecolor=SpringGreen3 +} +\usepackage[all]{hypcap} +\ifpdf +\pdfmapfile{=cm2lm.map}% replace CM by LM in figures +\else +\DeclareGraphicsExtensions{.mps} +\DeclareGraphicsRule{mps}{eps}{*}{} +\usepackage{breakurl} +\fi + + +\begin{document} + \maketitle + \begin{abstract} \myabstract \end{abstract} + \ifx\keywords\undefined \else + \begin{keywords} \mykeywords \end{keywords} + \fi + +\setlength{\columnsep}{2.5em} +\begin{multicols}{2} +\tableofcontents +\end{multicols} + +\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, +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. + + +\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] +$$ \includegraphics{mpgraph-1.mps} $$ +\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] +$$ \includegraphics{mpgraph-2.mps} $$ +\caption{The 1991 age distribution plotted with bullets} +\label{fig2} +\end{figure} + +Watch out for the following: the \tdescr{picture expression} is placed +with the lower-left corner at the path knot, not its center. If you +want it to be dead-center, you have to correct the placement +yourself. For the example above, you need something like this instead: + +\medskip +\begin{verbatim} +def MPbullet = + btex \lower\fontdimen22\cmsy \hbox to 0pt{\hss\cmsy\char15\hss} etex +enddef; +\end{verbatim} + +\medskip\noindent +followed by: +$$ \hbox{\verb|gdraw "agepop91.d" plot MPbullet|} $$ + + +% 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] +$$ \includegraphics{mpgraph-3.mps} $$ +\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 +\includegraphics{mpgraph-4.mps} +$$ +\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{\includegraphics{mpgraph-5.mps}} + \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{\includegraphics{mpgraph-6.mps}} +$$ +\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); + path p; + gdata("timepop.d", $, augment.p($1, newy(Scvnum $2)); ); + gdraw p withpen nullpen; + 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; + gdraw p; + frame.llft; + endgraph; +\end{verbatim} + \atop + \includegraphics{mpgraph-7.mps} +$$ +\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 + \includegraphics{mpgraph-8.mps} +$$ +\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 + \includegraphics{mpgraph-9.mps} +$$ +\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 \includegraphics{mpgraph-10.mps} $$ +and +$$ \hbox{\verb|format("%3g","6.022e23")|} + \quad {\rm yields}\quad \includegraphics{mpgraph-11.mps} +$$ + +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} + + +\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. + +%%% Local Variables: +%%% mode: latex +%%% TeX-PDF-mode: t +%%% TeX-master: t +%%% End: diff --git a/Master/texmf-dist/doc/metapost/base/source-manual/mpintro.bib b/Master/texmf-dist/doc/metapost/base/source-manual/mpintro.bib new file mode 100644 index 00000000000..4b1c745c88e --- /dev/null +++ b/Master/texmf-dist/doc/metapost/base/source-manual/mpintro.bib @@ -0,0 +1,50 @@ +% BibTeX entries for MetaPost doc, by John Hobby. Public domain. + +@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-manual/mpintro.tex b/Master/texmf-dist/doc/metapost/base/source-manual/mpintro.tex new file mode 100644 index 00000000000..559456af209 --- /dev/null +++ b/Master/texmf-dist/doc/metapost/base/source-manual/mpintro.tex @@ -0,0 +1,859 @@ +% $Id: mpintro.tex 501 2008-04-27 17:38:51Z stephanhennig $ +% MetaPost doc, by John Hobby. +\documentclass{article} +\usepackage{graphicx} +\usepackage{ifpdf} +\ifpdf +\else +\DeclareGraphicsExtensions{.mps} +\DeclareGraphicsRule{mps}{eps}{*}{} +\fi + +\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 grops} output processor includes PostScript figures when they are +requested via troff's {\tt \char`\\X} command. + +\begin{figure}[htp] +\centering +\includegraphics{manfig-0} +\caption{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.\footnote{For importing MetaPost graphics into +\LaTeX\ documents please refer to section \emph{Using MetaPost graphics +in \TeX, \LaTeX, pdf\LaTeX, pdf\TeX, Con\TeX{}t and troff} in the +MetaPost manual.} +After \lit{\string\input} \lit{epsf} the \TeX\ commands +\lit{\$\$\string\epsfbox\char`\{fig.1\char`\}\$\$} produce +$$ \includegraphics{examples-1.mps} $$ +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} +$$ \includegraphics{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} +$$ \includegraphics{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; +dotlabels.top(0,1,2,3,4,5); +endfig; linecap:=rounded; +%stopverbatim +\qquad +\vcenter{\includegraphics{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; +dotlabels.bot(0,1,2,3,4,5,6,7,8); +endfig; linejoin:=rounded; +%stopverbatim +\qquad +\vcenter{\includegraphics{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} +$$ \includegraphics{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} +$$ \includegraphics{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} +$$ \includegraphics{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} +$$ \includegraphics{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-manual/mplibapi.tex b/Master/texmf-dist/doc/metapost/base/source-manual/mplibapi.tex new file mode 100644 index 00000000000..a18e5e01fb0 --- /dev/null +++ b/Master/texmf-dist/doc/metapost/base/source-manual/mplibapi.tex @@ -0,0 +1,1101 @@ + +\def\MPLIB{MPlib} +\def\MP{MetaPost} +\def\POSTSCRIPT{PostScript} +\def\PS{PostScript} +\def\TFM{{\sc tfm}} +\def\LUA{Lua} + +\def\luatex#1{#1} + +\setupinteraction[state=start] % don't forget this line! +\placebookmarks[section,subsection,subsubsection][section] +% \setupinteractionscreen[option=bookmark] + +\definefontsynonym[TitleFont][Sans] +\definefontsynonym[SubTitleFont][Sans] + +\def\StartTitlePage% + {\bgroup%\startstandardmakeup + \setupalign[middle] + \hbox{}\vfil + \let\\=\crlf} + +\def\StopTitlePage% + {\vfil + \page\egroup%\stopstandardmakeup + } + +\usetypescript[palatino] +\switchtobodyfont[palatino,10pt] + +\nonknuthmode + +\def\ctypedef#1#2#3{\subsubsection[#2]{\type{#1#2#3}}\bookmark{#2}} +\def\cenumeration#1{\subsubsection{\type{#1}}\bookmark{#1}} +\def\cfunction#1#2#3{\subsubsection[#2]{\type{#1#2#3}}\bookmark{#2}} + + +\starttext + +\StartTitlePage +\centerline{\definedfont[TitleFont at 50pt]{\MPLIB}} +\blank[3*line] +\centerline{\definedfont[SubTitleFont at 24pt]{API documentation}} +\blank[3*line] +\centerline{Taco Hoekwater, July 2008} +\StopTitlePage + +\section{Table of contents} + +\placecontent[criterium=all,level=subsection] + +\page + +\section{Introduction} + +This document describes the API to \MPLIB, allowing you to use +\MPLIB\ in your own applications. One such application is writing +bindings to interface with other programming languages. The +bindings to the \LUA\ scripting language is part of the \MPLIB\ +distribution and also covered by this manual. + +This is a first draft of both this document as well as the API, so +there may be errors or omissions in this document or strangenesses in +the API. If you believe something can be improved, please do not +hesitate to let us know. The contact email address is {\tt +metapost@tug.org}. + +The C paragraphs in this document assume you understand C code, the +Lua paragraphs assume you understand Lua code, and familiarity with +\MP\ is assumed throughout. + +\subsection{Simple \MPLIB\ use} + +There are two different approaches possible when running \MPLIB. The first +method is most suitable for programs that function as a command-line +frontend. It uses \quote{normal} \MP\ interface with I/O to and from files, +and needs very little setup to run. On the other hand, it also gives +almost no chance to control the \MPLIB\ behaviour. + +Here is a C language example of how to do this: + + +\starttyping +#include <stdlib.h> +#include "mplib.h" +int main (int argc, char **argv) { + MP mp; + MP_options *opt = mp_options(); + opt->command_line = argv[1]; + mp = mp_initialize(opt); + if (mp) { + int history = mp_run(mp); + mp_finish(mp); + exit (history); + } else { + exit (EXIT_FAILURE); + } +} +\stoptyping + +This example will run in \quote{inimpost} mode. + +\subsection{Embedded \MPLIB\ use} + +The second method does not run a file, but instead repeatedly executes +chunks of \MP\ language input that are passed to the library as +strings, with the output redirected to internal buffers instead of +directly to files. + +Here is an example of how this second approach works, now using the +\LUA\ bindings: + +\starttyping +local mplib = require('mplib') +local mp = mplib.new ({ ini_version = false, + mem_name = 'plain' }) +if mp then + local l = mp:execute([[beginfig(1); + fill fullcircle scaled 20; + endfig; + ]]) + if l and l.fig and l.fig[1] then + print (l.fig[1]:postscript()) + end + mp:finish(); +end +\stoptyping + +This example loads a previously generated \quote{plain} mem file. + + +\section{C API for core \MPLIB} + +All of the types, structures, enumerations and functions that are +described in this section are defined in the header file \type{mplib.h}. + +\subsection{Structures} + +\ctypedef{}{MP_options}{} + +This is a structure that contains the configurable parameters for a new \MPLIB\ instance. Because \MP\ differentiates +between \type{-ini} and \type{non-ini} modes, there are three types of settings: Those that apply in both cases, and +those that apply in only one of those cases. + +\starttabulate[|l|l|l|p|] +\NC int \NC ini_version \NC 1 \NC set this to zero if you want to load a mem file.\NC \NR +\NC int \NC error_line \NC 79 \NC maximal length of error message lines\NC \NR +\NC int \NC half_error_line \NC 50 \NC halfway break point for error contexts\NC\NR +\NC int \NC max_print_line \NC 100 \NC maximal length of file output\NC \NR +\NC unsigned \NC hash_size \NC 16384 \NC size of the internal hash (always a multiple of 2). + ignored in \type{non-ini} mode, read from mem file\NC \NR +\NC int \NC param_size \NC 150 \NC number of simultaneously active macro parameters. + ignored in \type{non-ini} mode, read from mem file\NC \NR +\NC int \NC max_in_open \NC 10 \NC maximum level of \type{input} nesting. + ignored in \type{non-ini} mode, read from mem file\NC \NR +\NC int \NC main_memory \NC 5000 \NC size of the main memory array in 8-byte words; + in \type{non-ini} mode only used if larger than the + value stored in the mem file\NC\NR +\NC void * \NC userdata \NC NULL \NC for your personal use only, not used by the library\NC \NR +\NC char * \NC banner \NC NULL \NC string to use instead of default banner\NC \NR +\NC int \NC print_found_names\NC 0 \NC controls whether the asked name or the actual found + name of the file is used in messages\NC \NR +\NC int \NC file_line_error_style\NC 0 \NC when this option is nonzero, the library will use \type{file:line:error} + style formatting for error messages that occur while reading + from input files\NC \NR +\NC char * \NC command_line \NC NULL \NC input file name and rest of command line; + only used by \type{mp_run} interface\NC \NR +\NC int \NC interaction \NC 0 \NC explicit \type{mp_interaction_mode} (see below)\NC \NR +\NC int \NC noninteractive \NC 0 \NC set this nonzero to suppress user interaction, + only sensible if you want to use \type{mp_execute}\NC \NR +\NC int \NC random_seed \NC 0 \NC set this nonzero to force a specific random seed\NC \NR +\NC int \NC troff_mode \NC 0 \NC set this nonzero to initialize \quote{troffmode} \NC \NR +\NC char * \NC mem_name \NC NULL \NC explicit mem name to use instead of \type{plain.mem}. + ignored in \type{-ini} mode.\NC \NR +\NC char * \NC job_name \NC NULL \NC explicit job name to use instead of first input file\NC \NR +\NC mp_file_finder \NC find_file \NC NULL \NC function called for finding files \NC \NR +\NC mp_editor_cmd \NC run_editor \NC NULL \NC function called after \quote{E} error response\NC \NR +\NC mp_makempx_cmd \NC run_make_mpx \NC NULL \NC function called for the creation of mpx files\NC \NR +\stoptabulate + +To create an \type{MP_options} structure, you have to use the \type{mp_options()} function. + +\ctypedef{}{MP}{} + +This type is an opaque pointer to a \MPLIB\ instance, it is what you +have pass along as the first argument to (almost) all the \MPLIB\ +functions. The actual C structure it points to has hundreds of fields, +but you should not use any of those directly. All confuration is done +via the \type{MP_options} structure, and there are accessor functions +for the fields that can be read out. + +\ctypedef{}{mp_run_data}{} + +When the \MPLIB\ instance is not interactive, any output is redirect +to this structure. There are a few string output streams, and a +linked list of output images. + +\starttabulate[|l|l|p|] +\NC mp_stream \NC term_out \NC holds the terminal output \NC \NR +\NC mp_stream \NC error_out \NC holds error messages \NC \NR +\NC mp_stream \NC log_out \NC holds the log output \NC \NR +\NC mp_edge_object *\NC edges \NC linked list of generated pictures \NC \NR +\stoptabulate + +\type{term_out} is equivalent to \type{stdout} in interactive use, and +\type{error_out} is equivalent to \type{stderr}. The \type{error_out} +is currently only used for memory allocation errors, the \MP\ error +messages are written to \type{term_out} (and are often duplicated to +\type{log_out} as well). + +You need to include \type{mplibps.h} to be able to actually make use this list of images, +see the next section for the details on \type{mp_edge_object} lists. + +See next paragraph for \type{mp_stream}. + +\ctypedef{}{mp_stream}{} + +This contains the data for a stream as well as some internal +bookkeeping variables. The fields that are of interest to you are: + +\starttabulate[|l|l|p|] +\NC size_t \NC size \NC the internal buffer size\NC \NR +\NC char * \NC data \NC the actual data. \NC \NR +\stoptabulate + +There is nothing in the stream unless the \type{size} field is +nonzero. There will not be embedded zeroes in \type{data}. + +If \type{size} is nonzero, \type{strlen(data)} is guaranteed to be +less than that, and may be as low as zero (if \MPLIB\ has written an +empty string). + +\subsection{Function prototype typedefs} + +The following three function prototypes define functions that you can +pass to \MPLIB\ insert the \type{MP_options} structure. + +\ctypedef{char * }{(*mp_file_finder)}{ (MP, const char*, const char*, int)} + +\MPLIB\ calls this function whenever it needs to find a file. If you +do not set up the matching option field (\type{MP_options.find_file}), +\MPLIB\ will only be able to find files in the current directory. + +The three function arguments are the requested file name, the file +mode (either \type{"r"} or \type{"w"}), and the file type (an +\type{mp_filetype}, see below). + +The return value is a new string indicating the disk file name to be +used, or NULL if the named file can not be found. If the mode is +\type{"w"}, it is usually best to simply return a copy of the first +argument. + + +\ctypedef{void }{(*mp_editor_cmd)}{(MP, char*, int)} + +This function is executed when a user has pressed \quote{E} as reply to an +\MP\ error, so it will only ever be called when \MPLIB\ in interactive mode. +The function arguments are the file name and the line number. When +this function is called, any open files are already closed. + +\ctypedef{int }{(*mp_makempx_cmd)}{(MP, char*, char *)} + +This function is executed when there is a need to start generating an +\type{mpx} file because (the first time a \type{btex} command was +encountered in the current input file). + +The first arguments is the input file name. This is the name that was given +in the \MP\ language, so it may not be the same as name of the actual +file that is being used, depending on how you your +\type{mp_file_finder} function behaves. The second argument is the +requested output name for mpx commands. + +A zero return value indicates success, everything else indicates +failure to create a proper \type{mpx} file and will result in an \MP\ error. + +\subsection{Enumerations} + +\cenumeration{mp_filetype} + +The \type{mp_file_finder} receives an \type{int} argument that is one of the following types: + +\starttabulate[|l|p|] +\NC mp_filetype_program \NC Metapost language code (r)\NC \NR +\NC mp_filetype_log \NC Log output (w)\NC \NR +\NC mp_filetype_postscript \NC PostScript output (w)\NC \NR +\NC mp_filetype_memfile \NC Mem file (r+w)\NC \NR +\NC mp_filetype_metrics \NC \TeX\ font metric file (r+w)\NC \NR +\NC mp_filetype_fontmap \NC Font map file (r)\NC \NR +\NC mp_filetype_font \NC Font PFB file (r)\NC \NR +\NC mp_filetype_encoding \NC Font encoding file (r)\NC \NR +\NC mp_filetype_text \NC \type{readfrom} and \type{write} files (r+w)\NC \NR +\stoptabulate + +\cenumeration{mp_interaction_mode} + +When \type{noninteractive} is zero, \MPLIB\ normally starts in a mode where it reports every error, +stops and asks the user for input. This initial mode can be overruled by using one of the following: + +\starttabulate[|l|p|] +\NC mp_batch_mode \NC as with \type{batchmode} \NC \NR +\NC mp_nonstop_mode \NC as with \type{nonstopmode} \NC \NR +\NC mp_scroll_mode \NC as with \type{scrollmode} \NC \NR +\NC mp_error_stop_mode \NC as with \type{errorstopmode} \NC \NR +\stoptabulate + +\cenumeration{mp_history_state} + +These are set depending on the current state of the interpreter. + +\starttabulate[|l|p|] +\NC mp_spotless \NC still clean as a whistle \NC \NR +\NC mp_warning_issued \NC a warning was issued or something was \type{show}-ed \NC \NR +\NC mp_error_message_issued \NC an error has been reported \NC \NR +\NC mp_fatal_eror_stop \NC termination was premature due to error(s) \NC \NR +\NC mp_system_error_stop \NC termination was premature due to disaster + (out of system memory) \NC \NR +\stoptabulate + + +\cenumeration{mp_color_model} + +Graphical objects always have a color model attached to them. + +\starttabulate[|l|p|] +\NC mp_no_model \NC as with \type{withoutcolor} \NC \NR +\NC mp_grey_model \NC as with \type{withgreycolor} \NC \NR +\NC mp_rgb_model \NC as with \type{withrgbcolor} \NC \NR +\NC mp_cmyk_model \NC as with \type{withcmykcolor} \NC \NR +\stoptabulate + + +\cenumeration{mp_knot_type} + +Knots can have left and right types depending on their current +status. By the time you see them in the output, they are usually +either \type{mp_explicit} or \type{mp_endpoint}, but here is the full +list: + +\starttabulate[|l|p|] +\NC mp_endpoint \NC \NC \NR +\NC mp_explicit \NC \NC \NR +\NC mp_given \NC \NC \NR +\NC mp_curl \NC \NC \NR +\NC mp_open \NC \NC \NR +\NC mp_end_cycle \NC \NC \NR +\stoptabulate + +\cenumeration{mp_knot_originator} + +Knots can originate from two sources: they can be explicitly given by +the user, or they can be created by the \MPLIB\ program code (for +example as result of the \type{makepath} operator). + +\starttabulate[|l|p|] +\NC mp_program_code \NC \NC \NR +\NC mp_metapost_user \NC \NC \NR +\stoptabulate + + +\cenumeration{mp_graphical_object_code} + +There are eight different graphical object types. + +\starttabulate[|l|p|] +\NC mp_fill_code \NC \type{addto contour} \NC \NR +\NC mp_stroked_code \NC \type{addto doublepath} \NC \NR +\NC mp_text_code \NC \type{addto also} (via \type{infont})\NC \NR +\NC mp_start_clip_code \NC \type{clip} \NC \NR +\NC mp_start_bounds_code \NC \NC \NR +\NC mp_stop_clip_code \NC \type{setbounds} \NC \NR +\NC mp_stop_bounds_code \NC \NC \NR +\NC mp_special_code \NC \type{special} \NC \NR +\stoptabulate + + +\subsection{Functions} + +\cfunction{char *}{mp_metapost_version}{(void)} + +Returns a copy of the \MPLIB\ version string. + +\cfunction{MP_options *}{mp_options}{(void)} + +Returns a properly initialized option structure, or \type{NULL} in case of allocation errors. + +\cfunction{MP }{mp_initialize}{(MP_options *opt)} + +Returns a pointer to a new \MPLIB\ instance, or \type{NULL} if initialisation failed. + +String options are copied, so you can free any of those (and the \type{opt} structure) +immediately after the call to this function. + +\cfunction{int }{mp_status}{(MP mp)} + +Returns the current value of the interpreter error state, as a \type{mp_history_state}. +This function is useful after \type{mp_initialize}. + +\cfunction{int }{mp_run}{(MP mp)} + +Runs the \MPLIB\ instance using the \type{command_line} and other items from the +\type{MP_options}. After the call to \type{mp_run}, the \MPLIB\ instance should be +closed off by calling \type{mp_finish}. + +The return value is the current \type{mp_history_state} + +\cfunction{void *}{mp_userdata}{(MP mp)} + +Simply returns the pointer that was passed along as \type{userdata} in +the \type{MP_options} struct. + +\cfunction{int }{mp_troff_mode}{(MP mp)} + +Returns the value of \type{troff_mode} as copied from the +\type{MP_options} struct. + +\cfunction{mp_run_data *}{mp_rundata}{(MP mp)} + +Returns the information collected during the previous call to \type{mp_execute}. + +\cfunction{int }{mp_execute}{(MP mp, char *s, size_t l)} + +Executes string \type{s} with length \type{l} in the \MPLIB\ +instance. This call can be repeated as often as is needed. The return +value is the current \type{mp_history_state}. To get at the produced +results, call \type {mp_rundata}. + +\cfunction{void }{mp_finish}{(MP mp)} + +This finishes off the use of the \MPLIB\ instance: it closes all files +and frees all the memory allocated by this instance. + +\cfunction{double }{mp_get_char_dimension}{(MP mp,char*fname,int n,int t)} + +This is a helper function that returns one of the dimensions of glyph +\type{n} in font \type{fname} as a double in PostScript (AFM) +units. The requested item \type{t} can be \type{'w'} (width), +\type{'h'} (height), or \type{'d'} (depth). + +\cfunction{int }{mp_memory_usage}{(MP mp)} + +Returns the current memory usage of this instance. + +\cfunction{int }{mp_hash_usage}{(MP mp)} + +Returns the current hash usage of this instance. + +\cfunction{int }{mp_param_usage}{(MP mp)} + +Returns the current simultaneous macro parameter usage of this instance. + +\cfunction{int }{mp_open_usage}{(MP mp)} + +Returns the current \type{input} levels of this instance. + +\section{C API for graphical backend functions} + +These are all defined in \type{mplibps.h} + +Unless otherwise stated, the \type{int} fields that express \MP\ values +should be interpreted as scaled points: the 32bits are divided into an +integer part and a fraction part so that the value $65536$ equals +1~\PS\ point (of which there are exactly 72 in an inch). + + +\subsection{Structures} + +The structures in this section are used by the items in the body of +the \type{edges} field of an \type{mp_rundata} structure. They are +presented here in a bottom-up manner. + +\ctypedef {}{mp_knot}{} + +Each \MPLIB\ path (a sequence of \MP\ points) is represented as a linked list +of structures of the type \type{mp_knot}. + +\starttabulate[|l|l|p|] +\NC struct mp_knot * \NC next \NC the next knot, or NULL\NC \NR +\NC mp_knot_type \NC left_type \NC the \type{mp_knot_type} for the left side \NC \NR +\NC mp_knot_type \NC right_type \NC the \type{mp_knot_type} for the right side \NC \NR +\NC signed int \NC x_coord \NC $x$\NC \NR +\NC signed int \NC y_coord \NC $y$\NC \NR +\NC signed int \NC left_x \NC $x$ of the left (incoming) control point\NC \NR +\NC signed int \NC left_y \NC $y$ of the left (incoming) control point\NC \NR +\NC signed int \NC right_x \NC $x$ of the right (outgoing) control point\NC \NR +\NC signed int \NC right_y \NC $y$ of the right (outgoing) control point\NC \NR +\NC mp_knot_originator \NC originator \NC the \type{mp_knot_originator} \NC \NR +\stoptabulate + +\ctypedef {}{mp_color}{} + +The graphical object that can be colored, have two fields to define +the color: one for the color model and one for the color values. The +structure for the color values is defined as follows: + +\starttabulate[|l|l|p|] +\NC int \NC a_val \NC see below, values are in scaled points\NC \NR +\NC int \NC b_val \NC --\NC \NR +\NC int \NC c_val \NC --\NC \NR +\NC int \NC d_val \NC --\NC \NR +\stoptabulate + +All graphical objects that have \type{mp_color} fields also have +\type{mp_color_model} fields. The color model decides the meaning of +the four data fields: + +\starttabulate[|l|c|c|c|c|] +\NC color model value \NC a_val \NC b_val \NC c_val \NC d_val \NC \FR +\NC mp_no_model \NC -- \NC -- \NC -- \NC -- \NC \NR +\NC mp_grey_model \NC grey \NC -- \NC -- \NC -- \NC \NR +\NC mp_rgb_model \NC red \NC green \NC blue \NC \NC \NR +\NC mp_cmyk_model \NC cyan \NC magenta \NC yellow\NC black \NC \NR +\stoptabulate + +\ctypedef {}{mp_dash_object}{} + +Dash lists are represented like this: + +\starttabulate[|l|l|p|] +\NC int * \NC array \NC an array of dash lengths, terminated by $-1$. + the values are in scaled points\NC \NR +\NC int \NC offset\NC the dash array offset (as in PostScript) \NC \NR +\stoptabulate + +\ctypedef {}{mp_graphic_object}{} + +Now follow the structure definitions of the objects that can appear +inside a figure (this is called an \quote{edge structure} in the +internal WEB documentation). + +There are eight different graphical object types, but there are seven +different C structures. Type \type{mp_graphic_object} represents the +base line of graphical object types. It has only two fields: + +\starttabulate[|l|l|p|] +\NC mp_graphical_object_code \NC type \NC \NC \NR +\NC struct mp_graphic_object * \NC next \NC next object or NULL \NC \NR +\stoptabulate + +Because every graphical object has at least these two types, the body +of a picture is represented as a linked list of +\type{mp_graphic_object} items. Each object in turn can then be +typecast to the proper type depending on its \type{type}. + +The two \quote{missing} objects in the explanations below are the ones +that match \type{mp_stop_clip_code} and \type{mp_stop_bounds_code}: +these have no extra fields besides \type{type} and \type{next}. + +\ctypedef {}{mp_fill_object}{} + +Contains the following fields on top of the ones defined by \type{mp_graphic_object}: + +\starttabulate[|l|l|p|] +\NC char * \NC pre_script \NC this is the result of \type{withprescript} \NC \NR +\NC char * \NC post_script \NC this is the result of \type{withpostscript}\NC \NR +\NC mp_color \NC color \NC the color value of this object\NC \NR +\NC mp_color_model \NC color_model \NC the color model\NC \NR +\NC unsigned char \NC ljoin \NC the line join style; values have the same meaning + as in \PS: 0 for mitered, 1 for round, 2 for beveled.\NC \NR +\NC mp_knot * \NC path_p \NC the (always cyclic) path\NC \NR +\NC mp_knot * \NC htap_p \NC a possible reversed path (see below)\NC \NR +\NC mp_knot * \NC pen_p \NC a possible pen (see below)\NC \NR +\NC int \NC miterlim \NC the miter limit\NC \NR +\stoptabulate + +Even though this object is called an \type{mp_fill_object}, it can be the result of both +\type{fill} and \type{filldraw} in the \MP\ input. This means that there can be a pen +involved as well. The final output should behave as follows: + +\startitemize +\item If there is no \type{pen_p}; simply fill \type{path_p}. +\item If there is a one-knot pen (\type{pen_p->next} = \type{pen_p}) then fill \type{path_p} +and also draw \type{path_p} with the \type{pen_p}. Do not forget to take \type{ljoin} and +\type{miterlim} into account when drawing with the pen. +\item If there is a more complex pen (\type{pen_p->next} != \type{pen_p}) then its path +has already been preprocessed for you. fill \type{path_p} and \type{htap_p}. +\stopitemize + +\ctypedef {}{mp_stroked_object}{} + +Contains the following fields on top of the ones defined by \type{mp_graphic_object}: + +\starttabulate[|l|l|p|] +\NC char * \NC pre_script \NC this is the result of \type{withprescript} \NC \NR +\NC char * \NC post_script \NC this is the result of \type{withpostscript} \NC \NR +\NC mp_color \NC color \NC color value \NC \NR +\NC mp_color_model \NC color_model \NC color model \NC \NR +\NC unsigned char \NC ljoin \NC the line join style \NC \NR +\NC unsigned char \NC lcap \NC the line cap style; values have the same meaning + as in \PS: 0 for butt ends, 1 for round ends, 2 for projecting ends.\NC \NR +\NC mp_knot * \NC path_p \NC the path \NC \NR +\NC mp_knot * \NC pen_p \NC the pen \NC \NR +\NC int \NC miterlim \NC miter limit \NC \NR +\NC mp_dash_object * \NC dash_p \NC a possible dash list\NC \NR +\stoptabulate + +\ctypedef {}{mp_text_object}{} + +Contains the following fields on top of the ones defined by \type{mp_graphic_object}: + +\starttabulate[|l|l|p|] +\NC char * \NC pre_script \NC this is the result of \type{withprescript}\NC \NR +\NC char * \NC post_script\NC this is the result of \type{withpostscript}\NC \NR +\NC mp_color \NC color \NC color value \NC \NR +\NC mp_color_model \NC color_model\NC color model \NC \NR +\NC char * \NC text_p \NC string to be placed \NC \NR +\NC char * \NC font_name \NC the \MP\ font name\NC \NR +\NC unsigned int \NC font_dsize \NC size of the font\NC \NR +\NC int \NC width \NC width of the picture resulting from the string\NC \NR +\NC int \NC height \NC height\NC \NR +\NC int \NC depth \NC depth\NC \NR +\NC int \NC tx \NC transformation component\NC \NR +\NC int \NC ty \NC transformation component\NC \NR +\NC int \NC txx \NC transformation component\NC \NR +\NC int \NC tyx \NC transformation component\NC \NR +\NC int \NC txy \NC transformation component\NC \NR +\NC int \NC tyy \NC transformation component\NC \NR +\stoptabulate + +All fonts are loaded by \MPLIB\ at the design size (but not all fonts have the same design +size). If text is to be scaled, this happens via the transformation components. + +\ctypedef {}{mp_clip_object}{} + +Contains the following field on top of the ones defined by \type{mp_graphic_object}: + +\starttabulate[|l|l|p|] +\NC mp_knot * \NC path_p \NC defines the clipping path that is in effect until + the object with the matching \type{mp_stop_clip_code} is encountered\NC \NR +\stoptabulate + +\ctypedef {}{mp_bounds_object}{} + +Contains the following field on top of the ones defined by \type{mp_graphic_object}: + +\starttabulate[|l|l|p|] +\NC mp_knot * \NC path_p \NC the path that was used for boundary calculation \NC \NR +\stoptabulate + +This object can be ignored when output is generated, it only has effect on the boudingbox +of the following objects and that has been taken into account already. + +\ctypedef {}{mp_special_object}{} + +This represents the output generated by a \MP\ \type{special} command. It +contains the following field on top of the ones defined by \type{mp_graphic_object}: + +\starttabulate[|l|l|p|] +\NC char *\NC pre_script \NC the special string\NC \NR +\stoptabulate + +Each \type{special} command generates one object. All of the relevant +\type{mp_special_object}s for a figure are linked together at the start +of that figure. + +\ctypedef {}{mp_edge_object}{} + +\starttabulate[|l|l|p|] +\NC mp_edge_object * \NC next \NC points to the next figure (or NULL)\NC \NR +\NC mp_graphic_object * \NC body \NC a linked list of objects in this figure \NC \NR +\NC char * \NC filename \NC this would have been the used filename if a \PS\ file + would have been generated\NC \NR +\NC MP \NC parent \NC a pointer to the instance that created + this figure\NC \NR +\NC int \NC minx \NC lower-left $x$ of the bounding box\NC \NR +\NC int \NC miny \NC lower-left $y$ of the bounding box\NC \NR +\NC int \NC maxx \NC upper right $x$ of the bounding box\NC \NR +\NC int \NC maxy \NC upper right $y$ of the bounding box\NC \NR +\NC int \NC width \NC value of \type{charwd}; +this would become the \TFM\ width (but without the potential rounding correction for \TFM\ file format)\NC \NR +\NC int \NC height \NC similar for height (\type{charht})\NC \NR +\NC int \NC depth \NC similar for depth (\type{chardp})\NC \NR +\NC int \NC ital_corr \NC similar for italic correction (\type{charic})\NC \NR +\NC int \NC charcode \NC Value of \type{charcode} (rounded, but not + modulated for \TFM's 256 values yet)\NC \NR +\stoptabulate + +\subsection{Functions} + +\cfunction{int }{mp_ps_ship_out}{(mp_edge_object*hh,int prologues,int procset)} + +If you have an \type{mp_edge_object}, you can call this function. It will +generate the \PS\ output for the figure and save it internally. A subsequent call to +\type{mp_rundata} will find the generated text in the \type{ps_out} field. + +Returns zero for success. + +\cfunction{void }{mp_gr_toss_objects}{(mp_edge_object*hh)} + +This frees a single \type{mp_edge_object} and its \type{mp_graphic_object} contents. + +\cfunction{void }{mp_gr_toss_object}{(mp_graphic_object*p)} + +This frees a single \type{mp_graphic_object} object. + +\cfunction{mp_graphic_object *}{mp_gr_copy_object}{(MP mp,mp_graphic_object*p)} + +This creates a deep copy of a \type{mp_graphic_object} object. + +\section{C API for label generation (a.k.a. makempx)} + +The following are all defined in \type{mpxout.h}. + +\subsection {Structures} + +\ctypedef {}{MPX}{} + +An opaque pointer that is passed on to the file_finder. + +\ctypedef {}{mpx_options}{} + +This structure holds the option fields for \type{mpx} generation. +You have to fill in all fields except \type{mptexpre}, that +one defaults to \type{mptexpre.tex} + + +\starttabulate[|l|l|p|] +\NC mpx_modes \NC mode \NC \NC \NR +\NC char * \NC cmd \NC the command (or sequence of commands) to run\NC \NR +\NC char * \NC mptexpre \NC prepended to the generated \TeX\ file\NC \NR +\NC char * \NC mpname \NC input file name \NC \NR +\NC char * \NC mpxname \NC output file name\NC \NR +\NC char * \NC banner \NC string to be printed to the generated to-be-typeset file\NC \NR +\NC int \NC debug \NC When nonzero, \type{mp_makempx} outputs some debug information and do not delete temp files\NC \NR +\NC mpx_file_finder \NC find_file \NC \NC \NR +\stoptabulate + +\subsection{Function prototype typedefs} + +\ctypedef{char * }{(*mpx_file_finder)}{ (MPX, const char*, const char*, int)} + +The return value is a new string indicating the disk file to be used. +The arguments are the file name, the file mode (either \type{"r"} or \type{"w"}), +and the file type (an \type{mpx_filetype}, see below). If the mode is \type{"w"}, +it is usually best to simply return a copy of the first argument. + +\subsection{Enumerations} + +\cenumeration{mpx_modes} + +\starttabulate[|l|p|] +\NC mpx_tex_mode \NC \NC \NR +\NC mpx_troff_mode \NC \NC \NR +\stoptabulate + +\cenumeration{mpx_filetype} + +\starttabulate[|l|p|] +\NC mpx_tfm_format \NC \TeX\ or Troff ffont metric file \NC \NR +\NC mpx_vf_format \NC \TeX\ virtual font file \NC \NR +\NC mpx_trfontmap_format \NC Troff font map \NC \NR +\NC mpx_trcharadj_format \NC Troff character shift information \NC \NR +\NC mpx_desc_format \NC Troff DESC file \NC \NR +\NC mpx_fontdesc_format \NC Troff FONTDESC file \NC \NR +\NC mpx_specchar_format \NC Troff special character definition\NC \NR +\stoptabulate + +\subsection{Functions} + +\cfunction{int }{mpx_makempx}{(mpx_options *mpxopt)} + +A return value of zero is success, non-zero values indicate errors. + +\page + +\section{Lua API} + +The \MP\ library interface registers itself in the table \type{mplib}. + +\subsection{\luatex{mplib.version}} + +Returns the \MPLIB\ version. + +\starttyping +<string> s = mplib.version() +\stoptyping + +\subsection{\luatex{mplib.new}} + +To create a new metapost instance, call + +\starttyping +<mpinstance> mp = mplib.new({...}) +\stoptyping + +This creates the \type{mp} instance object. The argument hash can have a number of +different fields, as follows: + +\starttabulate[|lT|l|p|p|] +\NC \ssbf name \NC \bf type \NC \bf description \NC \bf default \NC\NR +\NC error_line \NC number \NC error line width \NC 79 \NC\NR +\NC print_line \NC number \NC line length in ps output \NC 100\NC\NR +\NC main_memory \NC number \NC total memory size \NC 5000\NC\NR +\NC hash_size \NC number \NC hash size \NC 16384 \NC\NR +\NC param_size \NC number \NC max. active macro parameters\NC 150\NC\NR +\NC max_in_open \NC number \NC max. input file nestings \NC 10\NC\NR +\NC random_seed \NC number \NC the initial random seed \NC variable\NC\NR +\NC interaction \NC string \NC the interaction mode, one of +\type {batch}, \type {nonstop}, \type {scroll}, \type {errorstop} \NC \type {errorstop}\NC\NR +\NC ini_version \NC boolean \NC the --ini switch \NC true \NC\NR +\NC mem_name \NC string \NC \type {--mem} \NC \type {plain} \NC\NR +\NC job_name \NC string \NC \type {--jobname} \NC \type {mpout} \NC\NR +\NC find_file \NC function \NC a function to find files \NC only local files\NC\NR +\stoptabulate + +The \type{find_file} function should be of this form: + +\starttyping +<string> found = finder (<string> name, <string> mode, <string> type) +\stoptyping + +with: + +\starttabulate[|lT|l|p|] +\NC name \NC the requested file \NC \NR +\NC mode \NC the file mode: \type {r} or \type {w} \NC \NR +\NC type \NC the kind of file, one of: \type {mp}, \type {mem}, \type {tfm}, \type {map}, \type {pfb}, \type {enc} \NC \NR +\stoptabulate + +Return either the full pathname of the found file, or \type{nil} if +the file cannot be found. + +\subsection{\luatex{mp:statistics}} + +You can request statistics with: + +\starttyping +<table> stats = mp:statistics() +\stoptyping + +This function returns the vital statistics for an \MPLIB\ instance. There are four +fields, giving the maximum number of used items in each of the four +statically allocated object classes: + +\starttabulate[|lT|l|p|] +\NC main_memory \NC number \NC memory size \NC\NR +\NC hash_size \NC number \NC hash size\NC\NR +\NC param_size \NC number \NC simultaneous macro parameters\NC\NR +\NC max_in_open \NC number \NC input file nesting levels\NC\NR +\stoptabulate + +\subsection{\luatex{mp:execute}} + +You can ask the \METAPOST\ interpreter to run a chunk of code by calling + +\starttyping +local rettable = mp:execute('metapost language chunk') +\stoptyping + +for various bits of Metapost language input. Be sure to check the +\type{rettable.status} (see below) because when a fatal \METAPOST\ +error occurs the \MPLIB\ instance will become unusable thereafter. + +Generally speaking, it is best to keep your chunks small, but beware +that all chunks have to obey proper syntax, like each of them is a +small file. For instance, you cannot split a single statement over +multiple chunks. + +In contrast with the normal standalone \type{mpost} command, there is +{\em no\/} implied \quote{input} at the start of the first chunk. + +\subsection{\luatex{mp:finish}} + +\starttyping +local rettable = mp:finish() +\stoptyping + +If for some reason you want to stop using an \MPLIB\ instance while +processing is not yet actually done, you can call \type{mp:finish}. +Eventually, used memory will be freed and open files will be closed by +the \LUA\ garbage collector, but an explicit \type{mp:finish} is the +only way to capture the final part of the output streams. + +\subsection{Result table} + +The return value of \type{mp:execute} and \type{mp:finish} is a table +with a few possible keys (only \type {status} is always guaranteed to be present). + +\starttabulate[|l|l|p|] +\NC log \NC string \NC output to the \quote {log} stream \NC \NR +\NC term \NC string \NC output to the \quote {term} stream \NC \NR +\NC error \NC string \NC output to the \quote {error} stream (only used for \quote {out of memory})\NC \NR +\NC status \NC number \NC the return value: 0=good, 1=warning, 2=errors, 3=fatal error \NC \NR +\NC fig \NC table \NC an array of generated figures (if any)\NC \NR +\stoptabulate + +When \type{status} equals~3, you should stop using this \MPLIB\ instance +immediately, it is no longer capable of processing input. + +If it is present, each of the entries in the \type{fig} array is a +userdata representing a figure object, and each of those has a number of +object methods you can call: + +\starttabulate[|l|l|p|] +\NC boundingbox \NC function \NC returns the bounding box, as an array of 4 values\NC \NR +\NC postscript \NC function \NC return a string that is the ps output of the \type{fig} \NC \NR +\NC svg \NC function \NC return a string that is the svg output of the \type{fig} \NC \NR +\NC objects \NC function \NC returns the actual array of graphic objects in this \type{fig} \NC \NR +\NC copy_objects \NC function \NC returns a deep copy of the array of graphic objects in this \type{fig} \NC \NR +\NC filename \NC function \NC the filename this \type{fig}'s \POSTSCRIPT\ output + would have written to in standalone mode\NC \NR +\NC width \NC function \NC the \type{charwd} value \NC \NR +\NC height \NC function \NC the \type{charht} value \NC \NR +\NC depth \NC function \NC the \type{chardp} value \NC \NR +\NC italcorr \NC function \NC the \type{charic} value \NC \NR +\NC charcode \NC function \NC the (rounded) \type{charcode} value \NC \NR +\stoptabulate + +{\bf NOTE:} you can call \type{fig:objects()} only once for any one \type{fig} object! + +When the boundingbox represents a \quote {negated rectangle}, i.e.\ when the first set +of coordinates is larger than the second set, the picture is empty. + +Graphical objects come in various types that each have a different list of +accessible values. The types are: \type{fill}, \type{outline}, \type{text}, +\type{start_clip}, \type{stop_clip}, \type{start_bounds}, \type{stop_bounds}, \type{special}. + +There is helper function (\type{mplib.fields(obj)}) to get the list of +accessible values for a particular object, but you can just as easily +use the tables given below). + +All graphical objects have a field \type{type} that gives the object +type as a string value, that not explicit mentioned in the tables. In +the following, \type{number}s are \POSTSCRIPT\ points represented as +a floating point number, unless stated otherwise. Field values that +are of \type{table} are explained in the next section. + +\subsubsection{fill} + +\starttabulate[|l|l|p|] +\NC path \NC table \NC the list of knots \NC \NR +\NC htap \NC table \NC the list of knots for the reversed trajectory \NC \NR +\NC pen \NC table \NC knots of the pen \NC \NR +\NC color \NC table \NC the object's color \NC \NR +\NC linejoin \NC number \NC line join style (bare number)\NC \NR +\NC miterlimit \NC number \NC miter limit\NC \NR +\NC prescript \NC string \NC the prescript text \NC \NR +\NC postscript \NC string \NC the postscript text \NC \NR +\stoptabulate + +The entries \type{htap} and \type{pen} are optional. + +There is helper function (\type{mplib.pen_info(obj)}) that returns +a table containing a bunch of vital characteristics of the used pen +(all values are floats): + +\starttabulate[|l|l|p|] +\NC width \NC number \NC width of the pen\NC \NR +\NC rx \NC number \NC $x$ scale \NC \NR +\NC sx \NC number \NC $xy$ multiplier \NC \NR +\NC sy \NC number \NC $yx$ multiplier \NC \NR +\NC ry \NC number \NC $y$ scale \NC \NR +\NC tx \NC number \NC $x$ offset \NC \NR +\NC ty \NC number \NC $y$ offset \NC \NR +\stoptabulate + +\subsubsection{outline} + +\starttabulate[|l|l|p|] +\NC path \NC table \NC the list of knots \NC \NR +\NC pen \NC table \NC knots of the pen \NC \NR +\NC color \NC table \NC the object's color \NC \NR +\NC linejoin \NC number \NC line join style (bare number)\NC \NR +\NC miterlimit \NC number \NC miter limit \NC \NR +\NC linecap \NC number \NC line cap style (bare number)\NC \NR +\NC dash \NC table \NC representation of a dash list\NC \NR +\NC prescript \NC string \NC the prescript text \NC \NR +\NC postscript \NC string \NC the postscript text \NC \NR +\stoptabulate + +The entry \type{dash} is optional. + +\subsubsection{text} + +\starttabulate[|l|l|p|] +\NC text \NC string \NC the text \NC \NR +\NC font \NC string \NC font tfm name \NC \NR +\NC dsize \NC number \NC font size\NC \NR +\NC color \NC table \NC the object's color \NC \NR +\NC width \NC number \NC \NC \NR +\NC height \NC number \NC \NC \NR +\NC depth \NC number \NC \NC \NR +\NC transform \NC table \NC a text transformation \NC \NR +\NC prescript \NC string \NC the prescript text \NC \NR +\NC postscript \NC string \NC the postscript text \NC \NR +\stoptabulate + +\subsubsection{special} + +\starttabulate[|l|l|p|] +\NC prescript \NC string \NC special text \NC \NR +\stoptabulate + +\subsubsection{start_bounds, start_clip} + +\starttabulate[|l|l|p|] +\NC path \NC table \NC the list of knots \NC \NR +\stoptabulate + +\subsubsection{stop_bounds, stop_clip} + +Here are no fields available. + +\subsection{Subsidiary table formats} + +\subsubsection{Paths and pens} + +Paths and pens (that are really just a special type of paths as far as +\MPLIB\ is concerned) are represented by an array where each entry +is a table that represents a knot. + +\starttabulate[|lT|l|p|] +\NC left_type \NC string \NC when present: 'endpoint', but ususally absent \NC \NR +\NC right_type \NC string \NC like \type{left_type}\NC \NR +\NC x_coord \NC number \NC $x$ coordinate of this knot\NC \NR +\NC y_coord \NC number \NC $y$ coordinate of this knot\NC \NR +\NC left_x \NC number \NC $x$ coordinate of the precontrol point of this knot\NC \NR +\NC left_y \NC number \NC $y$ coordinate of the precontrol point of this knot\NC \NR +\NC right_x \NC number \NC $x$ coordinate of the postcontrol point of this knot\NC \NR +\NC right_y \NC number \NC $y$ coordinate of the postcontrol point of this knot\NC \NR +\stoptabulate + +There is one special case: pens that are (possibly transformed) +ellipses have an extra string-valued key \type{type} with value +\type{elliptical} besides the array part containing the knot list. + +\subsubsection{Colors} + +A color is an integer array with 0, 1, 3 or 4 values: + +\starttabulate[|l|l|p|] +\NC 0 \NC marking only \NC no values \NC\NR +\NC 1 \NC greyscale \NC one value in the range (0,1), \quote {black} is 0 \NC\NR +\NC 3 \NC RGB \NC three values in the range (0,1), \quote {black} is 0,0,0 \NC\NR +\NC 4 \NC CMYK \NC four values in the range (0,1), \quote {black} is 0,0,0,1 \NC\NR +\stoptabulate + +If the color model of the internal object was \type{unitialized}, then +it was initialized to the values representing \quote {black} in the colorspace +\type{defaultcolormodel} that was in effect at the time of the \type{shipout}. + +\subsubsection{Transforms} + +Each transform is a six-item array. + +\starttabulate[|l|l|p|] +\NC 1 \NC number \NC represents x \NC\NR +\NC 2 \NC number \NC represents y \NC\NR +\NC 3 \NC number \NC represents xx \NC\NR +\NC 4 \NC number \NC represents yx \NC\NR +\NC 5 \NC number \NC represents xy \NC\NR +\NC 6 \NC number \NC represents yy \NC\NR +\stoptabulate + +Note that the translation (index 1 and 2) comes first. This differs +from the ordering in \POSTSCRIPT, where the translation comes last. + +\subsubsection{Dashes} + +Each \type{dash} is two-item hash, using the same model as \POSTSCRIPT\ +for the representation of the dashlist. \type{dashes} is an array of +\quote {on} and \quote {off}, values, and \type{offset} is the phase of the pattern. + +\starttabulate[|l|l|p|] +\NC dashes \NC hash \NC an array of on-off numbers \NC\NR +\NC offset \NC number \NC the starting offset value \NC\NR +\stoptabulate + +\subsection{Character size information} + +These functions find the size of a glyph in a defined font. The +\type{fontname} is the same name as the argument to \type{infont}; +the \type{char} is a glyph id in the range 0 to 255; the returned +\type{w} is in AFM units. + +\subsubsection{\luatex{mp.char_width}} + +\starttyping +<number> w = mp.char_width(<string> fontname, <number> char) +\stoptyping + +\subsubsection{\luatex{mp.char_height}} + +\starttyping +<number> w = mp.char_height(<string> fontname, <number> char) +\stoptyping + +\subsubsection{\luatex{mp.char_depth}} + +\starttyping +<number> w = mp.char_depth(<string> fontname, <number> char) +\stoptyping + + +\stoptext + + + + + + diff --git a/Master/texmf-dist/doc/metapost/base/source-manual/mpman-app-legacy.tex b/Master/texmf-dist/doc/metapost/base/source-manual/mpman-app-legacy.tex new file mode 100644 index 00000000000..02531611d72 --- /dev/null +++ b/Master/texmf-dist/doc/metapost/base/source-manual/mpman-app-legacy.tex @@ -0,0 +1,342 @@ +\section{Legacy information}
+\label{legacy}
+
+\subsection{MetaPost Versus \MF}
+\label{MPvsMF}
+
+Since the \MF\index{metafont?\MF} and MetaPost languages have so much in
+common, expert users of \MF\ will want to skip most of the explanations
+in this document and concentrate on concepts that are unique to
+MetaPost. The comparisons in this appendix are intended to help experts
+that are familiar with {\sl The\ \MF book} as well as other users that
+want to benefit from Knuth's more detailed explanations \cite{kn:c}.
+
+Since \MF\ is intended for making \TeX\ fonts, it has a number of
+primitives for generating the {\tt tfm}\index{tfm file?{\tt tfm}
+file}\index{files!tfm?{\tt tfm}} files that \TeX\ needs for character
+dimensions, spacing information, ligatures\index{ligatures} and
+kerning\index{kerning}. MetaPost can also be used for generating fonts,
+and it also has \MF's primitives for making {\tt tfm} files. These are
+listed in Table~\ref{tfmprim}. Explanations can be found in the \MF\
+documentation \cite{kn:c,kn:mf3}.
+
+\begin{table}[htp]
+$$\begin{tabular}{|l|l|} \hline
+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 systems to protect special characters like
+{\tt\&}.}
+$$ \hbox{\verb|mpost '&mfplain' cmr10|} $$
+The analog of a \MF\ command line like
+$$ \hbox{\verb|mf '\mode=lowres; mag=1.2; input cmr10'|} $$
+is
+$$ \hbox{\verb|mpost '&mfplain \mode=lowres; mag=1.2; input cmr10'|} $$
+The result is a set of PostScript\index{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:red2}.
+
+\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}
+
+
+\begin{table}
+\centering
+\begin{tabular}{|c|}\hline
+MetaPost primitives not found in \MF\\\hline
+\begin{minipage}[b]{.75\linewidth}\ttfamily
+\begin{multicols}{3}
+blackpart\\
+bluepart\\
+bounded\\
+btex\\
+clip\\
+clipped\\
+closefrom\\
+cmykcolor\\
+color\\
+colormodel\\
+cyanpart\\
+dashed\\
+dashpart\\
+defaultcolormodel\\
+etex\\
+filenametemplate\\
+filled\\
+fontmapfile\\
+fontmapline\\
+fontpart\\
+fontsize\\
+for within\\
+glyph of\\
+greenpart\\
+greypart\\
+hour\\
+infont\\
+jobname\\
+linecap\\
+linejoin\\
+llcorner\\
+lrcorner\\
+magentapart\\
+minute\\
+miterlimit\\
+mpprocset\\
+mpxbreak\\
+outputformat\\
+outputtemplate\\
+pathpart\\
+penpart\\
+prologues\\
+readfrom\\
+redpart\\
+restoreclipcolor\\
+rgbcolor\\
+setbounds\\
+stroked\\
+textpart\\
+textual\\
+tracinglostchars\\
+troffmode\\
+truecorners\\
+ulcorner\\
+urcorner\\
+verbatimtex\\
+withcmykcolor\\
+withcolor\\
+withgreyscale\\
+withoutcolor\\
+withpostscript\\
+withprescript\\
+withrgbcolor\\
+write to\\
+yellowpart
+\end{multicols}
+\end{minipage}\\\hline
+
+Variables and Macros defined only in Plain MetaPost\\\hline
+\begin{minipage}[b]{.75\linewidth}\ttfamily
+\begin{multicols}{3}
+ahangle\\
+ahlength\\
+background\\
+bbox\\
+bboxmargin\\
+beginfig\\
+beveled\\
+black\\
+blue\\
+buildcycle\\
+butt\\
+center\\
+colorpart\\
+cutafter\\
+cutbefore\\
+cuttings\\
+dashpattern\\
+defaultfont\\
+defaultpen\\
+defaultscale\\
+dotlabel\\
+dotlabels\\
+drawarrow\\
+drawdblarrow\\
+drawoptions\\
+endfig\\
+EOF\\
+evenly\\
+extra\_beginfig\\
+extra\_endfig\\
+green\\
+image\\
+label\\
+labeloffset\\
+mitered\\
+red\\
+rounded\\
+squared\\
+thelabel\\
+white
+\end{multicols}
+\end{minipage}\\\hline
+\end{tabular}
+\caption{Macros and internal variables defined in MetaPost but not \MF.}
+\label{mponly}
+\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\index{PostScript!point}\index{point!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\index{PostScript}
+commands that are to be placed at the beginning of the next output file.
+
+In this regard, it is worth mentioning that rules in \TeX\ material
+included via {\tt btex..etex} in MetaPost are rounded to the correct
+number of pixels according to PostScript\index{PostScript!conversion rules}
+conversion rules~\cite{ad:red2}. In \MF, rules are not generated
+directly, but simply included in specials and interpreted later by
+other programs, such as {\tt gftodvi}\index{gftodvi?\ttt{gftodvi}},
+so there is no special conversion.
+
+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{mpx file?{\tt mpx}
+ file}\index{files!mpx?{\tt mpx}} files. It should be of no concern to
+users since {\tt mpx} files are generated automatically.
+
+\subsection{File name templates}
+\label{Dfilenametemplate}
+
+The output file naming template mechanism introduced in MetaPost
+version~1.000 originally used a primitive called
+\ttindex{filenametemplate}, as opposed to the internal string variable
+\ttt{outputtemplate}\index{outputtemplate?\texttt{outputtemplate}}
+described in section~\ref{Doutputtemplate}. This primitive took a
+string argument with the same syntax as \ttt{outputtemplate}, except
+that it didn't know about the \verb|%{...}| escape sequence for
+evaluating internal variables, e.g.,:
+
+$$\begin{verbatim}
+filenametemplate "%j-%c.mps";
+\end{verbatim}
+$$
+
+The \verb|filenametemplate| primitive has been deprecated since the
+introduction of \verb|outputtemplate| (version~1.200), but is still
+supported. If you happen to need writing future-proof source files,
+that at the same time are backwards compatible to MetaPost versions
+between 1.000 and~1.200, this output filename template declaration might
+help:
+
+$$\begin{verbatim}
+if scantokens(mpversion) < 1.200:
+ filenametemplate
+else:
+ outputtemplate :=
+fi
+"%j-%c.mps";
+\end{verbatim}
+$$
+
+
+%%% Local Variables:
+%%% mode: latex
+%%% TeX-PDF-mode: t
+%%% TeX-master: "mpman"
+%%% End:
diff --git a/Master/texmf-dist/doc/metapost/base/source-manual/mpman-app-optab.tex b/Master/texmf-dist/doc/metapost/base/source-manual/mpman-app-optab.tex new file mode 100644 index 00000000000..d0da5811299 --- /dev/null +++ b/Master/texmf-dist/doc/metapost/base/source-manual/mpman-app-optab.tex @@ -0,0 +1,155 @@ +%%% Two notes on column specification:
+%%% (i) Column widths are manually chosen as small as possible to allow
+%%% for a wider last X column.
+%%% (ii) In the first column \linepenalty=100 prefers shorter paragraphs
+%%% (less lines), where plain \raggedright were indifferent and
+%%% sometimes caused a dangling line, e.g., for 'directionpoint of'
+%%% or 'directiontime of'.
+\begin{longtable}{|>{\raggedright\linepenalty=100\ttfamily}p{.793in}*{3}{|>{\raggedright}p{.715in}}|>{\raggedleft}p{1.5em}|>{\raggedright\arraybackslash}X|}
+\caption{\strut Operators}\label{optab}\\
+\hline
+Name& \multicolumn3{c|}{Argument/result types}& \makebox[.2in][c]{Page}& Explanation\\\cline{2-4}
+& \multicolumn1{c|}{Left}& \multicolumn1{c|}{Right}& \multicolumn1{c|}{Result}& & \\
+\hline
+\hline
+\endfirsthead
+\caption[]{\strut Operators \emph{(continued)}}\\
+\hline
+Name& \multicolumn3{c|}{Argument/result types}& \makebox[.2in][c]{Page}& Explanation\\\cline{2-4}
+& \multicolumn1{c|}{Left}& \multicolumn1{c|}{Right}& \multicolumn1{c|}{Result}& & \\
+\hline
+\hline
+\endhead
+\&\index{&?\texttt{\&}}& string\par path& string\par path & string\par path& \pageref{Damp}& Concatenation---works for paths $l\hbox{\tt\&}r$ if $r$ starts exactly where the $l$ ends\\\hline
+*\index{*?\texttt{*}}& numeric& (cmyk)color\par numeric\par pair& (cmyk)color\par numeric\par pair& \pageref{Dmldiv}& Multiplication\\\hline
+*\index{*?\texttt{*}}& (cmyk)color\par numeric\par pair& numeric& (cmyk)color\par numeric\par pair& \pageref{Dmldiv}& Multiplication\\\hline
+**\index{**?\texttt{**}}& numeric& numeric& numeric& \pageref{Dpow}& Exponentiation\\\hline
++\index{+?\texttt{+}}& (cmyk)color\par numeric\par pair& (cmyk)color\par numeric\par pair& (cmyk)color\par numeric\par pair& \pageref{Dadd}& Addition\\\hline
+++\index{++?\texttt{++}}& numeric& numeric& numeric& \pageref{Dpyadd}& Pythagorean addition $\sqrt{l^2+r^2}$\\\hline
++-+\index{+-+?\texttt{+-+}}& numeric& numeric& numeric& \pageref{Dpysub}& Pythagorean subtraction $\sqrt{l^2-r^2}$\\\hline
+-\index{-?\texttt{-}}& (cmyk)color\par numeric\par pair& (cmyk)color\par numeric\par pair& (cmyk)color\par numeric\par pair& \pageref{Dadd}& Subtraction\\\hline
+-\index{-?\texttt{-}}& --& (cmyk)color\par numeric\par pair& (cmyk)color\par numeric\par pair& \pageref{Dneg}& Negation\\\hline
+/\index{/?\texttt{/}}& (cmyk)color\par numeric\par pair& numeric& (cmyk)color\par numeric\par pair& \pageref{Dmldiv}& Division\\\hline
+<\index{<?\texttt{<}} =\index{=?\texttt{=}} >\index{>?\texttt{>}}\par <=\index{<=?\texttt{<=}} >=\index{>=?\texttt{>=}}\par <>\index{<>?\texttt{<>}}& string\par numeric\par pair\par (cmyk)color\par transform& string\par numeric\par pair\par (cmyk)color\par transform& boolean& \pageref{Dcmpar}& Comparison operators\\\hline
+\pl abs\index{abs?\texttt{abs}}& --& numeric\par pair& numeric& \pageref{Dabs}& Absolute value\par Euclidean length $\sqrt{(\mbox{\ttfamily xpart\ } r)^2+(\mbox{\ttfamily ypart\ } r)^2}$\\\hline
+and\index{and?\texttt{and}}& boolean& boolean& boolean& \pageref{Dand}& Logical and\\\hline
+angle\index{angle?\texttt{angle}}& --& pair& numeric& \pageref{Dangle}& 2$-$argument arctangent (in degrees)\\\hline
+arclength\index{arclength?\texttt{arclength}}& --& path& numeric& \pageref{Darclng}& Arc length of a path\\\hline
+arctime of\index{arctime of?\texttt{arctime of}}& numeric& path& numeric& \pageref{Darctim}& Time on a path where arc length from the start reaches a given value\\\hline
+ASCII\index{ASCII?\texttt{ASCII}}& --& string& numeric& --& ASCII value of first character in string\\\hline
+\pl bbox\index{bbox?\texttt{bbox}}& --& picture\par path\par pen& path& \pageref{Dbbox}& A rectangular path for the bounding box\\\hline
+blackpart\index{blackpart?\texttt{blackpart}}& --& cmykcolor& numeric& \pageref{Dcmykprt}& Extract the fourth component\\\hline
+bluepart\index{bluepart?\texttt{bluepart}}& --& color& numeric& \pageref{Drgbprt}& Extract the third component\\\hline
+boolean\index{boolean?\texttt{boolean}}& --& any& boolean& \pageref{Dboolop}& Is the expression of type boolean?\\\hline
+\pl bot\index{bot?\texttt{bot}}& --& numeric\par pair& numeric\par pair& \pageref{Dbot}& Bottom of current pen when centered at the given coordinate(s)\\\hline
+bounded\index{bounded?\texttt{bounded}}& --& any& boolean& \pageref{Dbounded}& Is argument a picture with a bounding box?\\\hline
+\pl ceiling\index{ceiling?\texttt{ceiling}}& --& numeric& numeric& \pageref{Dceil}& Least integer greater than or equal to\\\hline
+\pl center\index{center?\texttt{center}}& --& picture\par path\par pen& pair& \pageref{Dcenter}& Center of the bounding box\\\hline
+char\index{char?\texttt{char}}& --& numeric& string& \pageref{Dchar}& Character with a given ASCII code\\\hline
+clipped\index{clipped?\texttt{clipped}}& --& any& boolean& \pageref{Dclipped}& Is argument a clipped picture?\\\hline
+cmykcolor\index{cmykcolor?\texttt{cmykcolor}}& --& any& boolean& \pageref{Dccolrop}& Is the expression of type cmykcolor?\\\hline
+color\index{color?\texttt{color}}& --& any& boolean& \pageref{Dcolrop}& Is the expression of type color?\\\hline
+colormodel\index{colormodel?\texttt{colormodel}}& --& image object& numeric& \pageref{Dcolormodel}& What is the color model of the image object?\\\hline
+\pl colorpart\index{colorpart?\texttt{colorpart}}& --& image object&
+(cmyk)color\par numeric\par boolean& \pageref{Dcolorpart}& What is the
+color of the image object?\\\hline
+cosd\index{cosd?\texttt{cosd}}& --& numeric& numeric& \pageref{Dcosd}& Cosine of angle in degrees\\\hline
+\pl cutafter\index{cutafter?\texttt{cutafter}}& path& path& path& \pageref{Dcuta}& Left argument with part after the intersection dropped\\\hline
+\pl cutbefore\index{cutbefore?\texttt{cutbefore}}& path& path& path& \pageref{Dcutb}& Left argument with part before the intersection dropped\\\hline
+cyanpart\index{cyanpart?\texttt{cyanpart}}& --& cmykcolor& numeric& \pageref{Dcmykprt}& Extract the first component\\\hline
+cycle\index{cycle?\texttt{cycle}}& --& path& boolean& \pageref{Dcycop}& Determines whether a path is cyclic\\\hline
+dashpart\index{dashpart?\texttt{dashpart}}& --& picture& picture& \pageref{Ddashpart}& Dash pattern of a path in a stroked picture\\\hline
+decimal\index{decimal?\texttt{decimal}}& --& numeric& string& \pageref{Ddecop}& The decimal representation\\\hline
+\pl dir\index{dir?\texttt{dir}}& --& numeric& pair& \pageref{Ddirop}& $(\cos\theta,\sin\theta)$ given $\theta$ in degrees\\\hline
+\pl direction of\index{direction of?\texttt{direction of}}& numeric& path& pair& \pageref{Ddirof}& The direction of a path at a given `time'\\\hline
+\pl direction\-point of\index{directionpoint of?\texttt{directionpoint of}}& pair& path& numeric& \pageref{Ddpntof}& Point where a path has a given direction\\\hline
+direction\-time of\index{directiontime of?\texttt{directiontime of}}& pair& path& numeric& \pageref{Ddtimof}& `Time' when a path has a given direction\\\hline
+\pl div\index{div?\texttt{div}}& numeric& numeric& numeric& --& Integer division $\lfloor l/r\rfloor$\\\hline
+\pl dotprod\index{dotprod?\texttt{dotprod}}& pair& pair& numeric& \pageref{Ddprod}& vector dot product\\\hline
+filled\index{filled?\texttt{filled}}& --& any& boolean& \pageref{Dfilled}& Is argument a filled outline?\\\hline
+floor\index{floor?\texttt{floor}}& --& numeric& numeric& \pageref{Dfloor}& Greatest integer less than or equal to\\\hline
+fontpart\index{fontpart?\texttt{fontpart}}& --& picture& string& \pageref{Dfontpart}& Font of a textual picture component\\\hline
+fontsize\index{fontsize?\texttt{fontsize}}& --& string& numeric& \pageref{Dfntsiz}& The point size of a font\\\hline
+glyph of\index{glyph?\texttt{glyph}}& numeric\par string& string& picture&
+\pageref{Dglyph}& Convert a glyph of a font to contours\\\hline
+greenpart\index{greenpart?\texttt{greenpart}}& --& color& numeric& \pageref{Drgbprt}& Extract the second component\\\hline
+greypart\index{greypart?\texttt{greypart}}& --& numeric& numeric& \pageref{Dgreyprt}& Extract the first (only) component\\\hline
+hex\index{hex?\texttt{hex}}& --& string& numeric& --& Interpret as a hexadecimal number\\\hline
+infont\index{infont?\texttt{infont}}& string& string& picture& \pageref{Sinfont}& Typeset string in given font\\\hline
+\pl intersec\-tionpoint\index{intersectionpoint?\texttt{intersectionpoint}}& path& path& pair& \pageref{Disecpt}& An intersection point\\\hline
+intersec\-tiontimes\index{intersectiontimes?\texttt{intersectiontimes}}& path& path& pair& \pageref{Disectt}& Times ($t_l,t_r)$ on paths $l$ and $r$ when the paths intersect\\\hline
+\pl inverse\index{inverse?\texttt{inverse}}& --& transform& transform& \pageref{Dinv}& Invert a transformation\\\hline
+known\index{known?\texttt{known}}& --& any& boolean& \pageref{Dknown}& Does argument have a known value?\\\hline
+length\index{length?\texttt{length}}& --& path\par string\par picture& numeric& \pageref{Dlength}\par \pageref{DlengthString}\par \pageref{DlengthPicture}& Number of components (arcs, characters, strokes, \ldots) in the argument\\\hline
+\pl lft\index{lft?\texttt{lft}}& --& numeric\par pair& numeric\par pair& \pageref{Dlft}& Left side of current pen when its center is at the given coordinate(s)\\\hline
+llcorner\index{llcorner?\texttt{llcorner}}& --& picture\par path\par pen& pair& \pageref{Dcornop}& Lower-left corner of bounding box\\\hline
+lrcorner\index{lrcorner?\texttt{lrcorner}}& --& picture\par path\par pen& pair& \pageref{Dcornop}& Lower-right corner of bounding box\\\hline
+magentapart\index{magentapart?\texttt{magentapart}}& --& cmykcolor& numeric& \pageref{Dcmykprt}& Extract the second component\\\hline
+makepath\index{makepath?\texttt{makepath}}& --& pen& path& \pageref{Dmkpath}& Cyclic path bounding the pen shape\\\hline
+makepen\index{makepen?\texttt{makepen}}& --& path& pen& \pageref{Dmkpen}& A polygonal pen made from the convex hull of the path knots\\\hline
+mexp\index{mexp?\texttt{mexp}}& --& numeric& numeric& --& The function $\exp(x/256)$\\\hline
+mlog\index{mlog?\texttt{mlog}}& --& numeric& numeric& --& The function $256\ln(x)$\\\hline
+\pl mod\index{mod?\texttt{mod}}& --& numeric& numeric& --& The remainder function $l-r\lfloor l/r\rfloor$\\\hline
+normal\-deviate\index{normaldeviate?\texttt{normaldeviate}}& --& --& numeric& --& Choose a random number with mean~0 and standard deviation~1\\\hline
+not\index{not?\texttt{not}}& --& boolean& boolean& \pageref{Dnot}& Logical negation\\\hline
+numeric\index{numeric?\texttt{numeric}}& --& any& boolean& \pageref{Dnumop}& Is the expression of type numeric?\\\hline
+oct\index{oct?\texttt{oct}}& --& string& numeric& --& Interpret string as octal number\\\hline
+odd\index{odd?\texttt{odd}}& --& numeric& boolean& --& Is the closest integer odd or even?\\\hline
+or\index{or?\texttt{or}}& boolean& boolean& boolean& \pageref{Dor}& Logical inclusive or\\\hline
+pair\index{pair?\texttt{pair}}& --& any& boolean& \pageref{Dpairop}& Is the expression of type pair?\\\hline
+path\index{path?\texttt{path}}& --& any& boolean& \pageref{Dpathop}& Is the expression of type path?\\\hline
+pathpart\index{pathpart?\texttt{pathpart}}& --& picture& path& \pageref{Dpathpart}& Path of a stroked picture component\\\hline
+pen\index{pen?\texttt{pen}}& --& any& boolean& \pageref{Dpenop}& Is the expression of type pen?\\\hline
+penoffset of\index{penoffset of?\texttt{penoffset of}}& pair& pen& pair& --& Point on the pen furthest to the right of the given direction\\\hline
+penpart\index{penpart?\texttt{penpart}}& --& picture& pen& \pageref{Dpenpart}& Pen of a stroked picture component\\\hline
+picture\index{picture?\texttt{picture}}& --& any& boolean& \pageref{Dpictop}& Is the expression of type picture?\\\hline
+point of\index{point of?\texttt{point of}}& numeric& path& pair& \pageref{Dpntof}& Point on a path given a time value\\\hline
+postcontrol of\index{postcontrol?\texttt{postcontrol}}& numeric& path& pair& --& First B\'ezier control point on path segment starting at the given time\\\hline
+precontrol of\index{precontrol?\texttt{precontrol}}& numeric& path& pair& --& Last B\'ezier control point on path segment ending at the given time\\\hline
+readfrom\index{readfrom?\texttt{readfrom}}& --& string& string& \pageref{Dreadfrom}& Read a line from file\\\hline
+redpart\index{redpart?\texttt{redpart}}& --& color& numeric& \pageref{Drgbprt}& Extract the first component\\\hline
+reverse\index{reverse?\texttt{reverse}}& --& path& path& \pageref{Drevrse}& `time'-reversed path, beginning swapped with ending\\\hline
+rgbcolor\index{rgbcolor?\texttt{rgbcolor}}& --& any& boolean& \pageref{Drcolrop}& Is the expression of type color?\\\hline
+rotated\index{rotated?\texttt{rotated}}& picture\par path\par pair\par pen\par transform& numeric& picture\par path\par pair\par pen\par transform& \pageref{Dtranop}& Rotate counterclockwise a given number of degrees\\\hline
+\pl round\index{round?\texttt{round}}& --& numeric\par pair& numeric\par pair& \pageref{Dround}& round each component to the nearest integer\\\hline
+\pl rt\index{rt?\texttt{rt}}& --& numeric\par pair& numeric\par pair& \pageref{Drt}& Right side of current pen when centered at given coordinate(s)\\\hline
+scaled\index{scaled?\texttt{scaled}}& picture\par path\par pair\par pen\par transform& numeric& picture\par path\par pair\par pen\par transform& \pageref{Dtranop}& Scale all coordinates by the given amount\\\hline
+scantokens\index{scantokens?\texttt{scantokens}}& --& string& token sequence& \pageref{Dscantokens}& Converts a string to a token or token sequence. Provides string to numeric conversion, etc.\\\hline
+shifted\index{shifted?\texttt{shifted}}& picture\par path\par pair\par pen\par transform& pair& picture\par path\par pair\par pen\par transform& \pageref{Dtranop}& Add the given shift amount to each pair of coordinates\\\hline
+sind\index{sind?\texttt{sind}}& --& numeric& numeric& \pageref{Dsind}& Sine of an angle in degrees\\\hline
+slanted\index{slanted?\texttt{slanted}}& picture\par path\par pair\par pen\par transform& numeric& picture\par path\par pair\par pen\par transform& \pageref{Dtranop}& Apply the slanting transformation that maps $(x,y)$ into $(x+sy,y)$, where~$s$ is the numeric argument\\\hline
+sqrt\index{sqrt?\texttt{sqrt}}& --& numeric& numeric& \pageref{Dsqrt}& Square root\\\hline
+str\index{str?\texttt{str}}& --& suffix& string& \pageref{Dstr}& String representation for a suffix\\\hline
+string\index{string?\texttt{string}}& --& any& boolean& \pageref{Dstrgop}& Is the expression of type string?\\\hline
+stroked\index{stroked?\texttt{stroked}}& --& any& boolean& \pageref{Dstroked}& Is argument a stroked line?\\\hline
+subpath of\index{subpath?\texttt{subpath}}& pair& path& path& \pageref{Dsubpth}& Portion of a path for given range of time values\\\hline
+substring of\index{substring
+of?\texttt{substring of}}& pair& string& string& \pageref{Dsubstr}& Substring bounded by given indices\\\hline
+textpart\index{textpart?\texttt{textpart}}& --& picture& string& \pageref{Dtextpart}& Text of a textual picture component\\\hline
+textual\index{textual?\texttt{textual}}& --& any& boolean& \pageref{Dtextual}& Is argument typeset text?\\\hline
+\pl top\index{top?\texttt{top}}& --& numeric\par pair& numeric\par pair& \pageref{Dtop}& Top of current pen when centered at the given coordinate(s)\\\hline
+transform\index{transform?\texttt{transform}}& --& any& boolean& \pageref{Dtrnfop}& Is the argument of type transform?\\\hline
+transformed\index{transformed?\texttt{transformed}}& picture\par path\par pair\par pen\par transform& transform& picture\par path\par pair\par pen\par transform& \pageref{Dtrfrmd}& Apply the given transform to all coordinates\\\hline
+ulcorner\index{ulcorner?\texttt{ulcorner}}& --& picture\par path\par pen& pair& \pageref{Dcornop}& Upper-left corner of bounding box\\\hline
+uniform\-deviate\index{uniformdeviate?\texttt{uniformdeviate}}& --& numeric& numeric& --& Random number between zero and the value of the argument\\\hline
+\pl unitvector\index{unitvector?\texttt{unitvector}}& --& pair& pair& \pageref{Duvec}& Rescale a vector so its length is~1\\\hline
+unknown\index{unknown?\texttt{unknown}}& --& any& boolean& \pageref{Dunknwn}& Is the value unknown?\\\hline
+urcorner\index{urcorner?\texttt{urcorner}}& --& picture\par path\par pen& pair& \pageref{Dcornop}& Upper-right corner of bounding box\\\hline
+\pl whatever\index{whatever?\texttt{whatever}}& --& --& numeric& \pageref{Dwhatev}& Create a new anonymous unknown\\\hline
+xpart\index{xpart?\texttt{xpart}}& --& pair\par transform& number& \pageref{Dxprt}& $x$ or $t_x$ component\\\hline
+xscaled\index{xscaled?\texttt{xscaled}}& picture\par path\par pair\par pen\par transform& numeric& picture\par path\par pair\par pen\par transform& \pageref{Dtranop}& Scale all $x$ coordinates by the given amount\\\hline
+xxpart\index{xxpart?\texttt{xxpart}}& --& transform& number& \pageref{Dtrprt}& $t_{xx}$ entry in transformation matrix\\\hline
+xypart\index{xypart?\texttt{xypart}}& --& transform& number& \pageref{Dtrprt}& $t_{xy}$ entry in transformation matrix\\\hline
+yellowpart\index{yellowpart?\texttt{yellowpart}}& --& cmykcolor& numeric& \pageref{Dcmykprt}& Extract the third component\\\hline
+ypart\index{ypart?\texttt{ypart}}& --& pair\par transform& number& \pageref{Dyprt}& $y$ or $t_y$ component\\\hline
+yscaled\index{yscaled?\texttt{yscaled}}& picture\par path\par pair\par pen\par transform& numeric& picture\par path\par pair\par pen\par transform& \pageref{Dtranop}& Scale all $y$ coordinates by the given amount\\\hline
+yxpart\index{yxpart?\texttt{yxpart}}& --& transform& number& \pageref{Dtrprt}& $t_{yx}$ entry in transformation matrix\\\hline
+yypart\index{yypart?\texttt{yypart}}& --& transform& number& \pageref{Dtrprt}& $t_{yy}$ entry in transformation matrix\\\hline
+zscaled\index{zscaled?\texttt{zscaled}}& picture\par path\par pair\par pen\par transform& pair& picture\par path\par pair\par pen\par transform& \pageref{Dtranop}& Rotate and scale all coordinates so that $(1,0)$ is mapped into the given pair; i.e., do complex multiplication.\\\hline
+\end{longtable}
+
+%%% Local Variables:
+%%% mode: latex
+%%% TeX-PDF-mode: t
+%%% TeX-master: "mpman"
+%%% End:
diff --git a/Master/texmf-dist/doc/metapost/base/source-manual/mpman-app-refman.tex b/Master/texmf-dist/doc/metapost/base/source-manual/mpman-app-refman.tex new file mode 100644 index 00000000000..4eba05ddc38 --- /dev/null +++ b/Master/texmf-dist/doc/metapost/base/source-manual/mpman-app-refman.tex @@ -0,0 +1,951 @@ +\section{Reference Manual}
+\label{refman}
+
+\begingroup
+\renewcommand\topfraction{1.0}% Allow *lots* of figures and tables.
+\renewcommand\textfraction{0.0}
+\setcounter{topnumber}{10}
+\setcounter{totalnumber}{10}
+
+\subsection{The MetaPost language}
+\label{refman:lang}
+
+Tables \ref{ivartab}--\ref{pseudotab} summarize the built-in features of
+Plain MetaPost. Features from the Plain\index{Plain macros} macro
+package are marked by \pl\ symbols. The distinction between primitives
+and plain macros can be ignored by the casual user.
+
+The tables in this appendix give the name of each feature, the page
+number where it is explained, and a short description. A few features
+are not explained elsewhere and have no page number listed. These
+features exist primarily for compatibility with \MF\index{metafont?\MF}
+and are intended to be self-explanatory. Certain other features from
+\MF\ are omitted entirely because they are of limited interest to the
+MetaPost users and/or would require long explanations. All of these are
+documented in {\sl The \MF book} \cite{kn:c} as explained in
+Appendix~\ref{MPvsMF}.
+
+Tables~\ref{ivartab} and~\ref{isvartab} list internal variables that
+take on numeric and string 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.
+
+Table~\ref{optab} summarizes MetaPost operators and lists
+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 this table 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}, \ref{sycmds1} and~\ref{sycmds2} 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{sycondloop} applies to the result
+of expanding all conditionals and loops. Conditionals and loops do have
+a syntax, but they deal with almost arbitrary sequences of tokens.
+Figure~\ref{sycondloop} specifies conditionals in terms of
+\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 current figure\\\hline
+\tt day& --&
+ the current day of the month\\\hline
+\tt defaultcolormodel& \pageref{Ddefaultcolormodel}&
+ the initial color model (default: 5, rgb)\\\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
+\tt hour& --&
+ the hour of the day this job started\\\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 minute& --&
+ the minute of the hour this job started\\\hline
+\tt miterlimit& \pageref{Dmiterlim}&
+ controls miter length as in PostScript\\\hline
+\tt month& --&
+ the current month (e.g, 3 $\equiv$ March)\\\hline
+\tt mpprocset& --&
+ \vtop{\hbox{set this to~1 if you want to include a PostScript
+dictionary}\hbox{of abbreviations in the output}}\\\hline
+\tt pausing& --&
+ ${}>0$ to display lines on the terminal before they are read\\\hline
+\tt prologues& \pageref{Dprologues}&
+ ${}>0$ to output conforming PostScript using built-in fonts\\\hline
+\tt restoreclipcolor& --&
+ restore the graphics state after clip operations (default: 1)\\\hline
+\tt showstopping& --&
+ ${}>0$ to stop after each {\tt show} command\\\hline
+\tt time& --&
+ 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 troffmode& \pageref{Dtroffmode}&
+ set to~1 if a {\tt -troff} or {\tt -T} option was given\\\hline
+\tt truecorners& \pageref{Dtruecorn}&
+ ${}>0$ to make {\tt llcorner} etc. ignore {\tt setbounds}\\\hline
+\tt warningcheck& \pageref{Dwarncheck}&
+ 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{hour?\texttt{hour}}\index{minute?\texttt{minute}}\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{Internal string variables}
+$$\begin{tabular}{|l|r|l|}
+\hline
+\multicolumn1{|c}{Name}& \multicolumn1{|c}{Page}& \multicolumn1{|c|}{Explanation}\\
+\hline
+\hline
+\tt jobname& --&
+ The name of this job\\\hline
+\tt outputformat& \pageref{Doutputformat}&
+ Output backend to be used (default: ``eps'')\\\hline
+\tt outputtemplate& \pageref{Doutputtemplate}&
+ Output filename template (default: ``\%j.\%c'')\\\hline
+\end{tabular}
+$$
+\label{isvartab}
+\index{jobname?\texttt{jobname}}
+\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
+\pl\tt EOF& string& \pageref{Deof}&
+ Single null character\\\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 mpversion& string& \pageref{Dmpversion}&
+ MetaPost version number\\\hline
+\tt nullpen& pen& \pageref{Dnlpen}&
+ Empty pen\\\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 \verb|(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}
+
+
+\clearpage
+\LTXtable{\textwidth}{mpman-app-optab}
+
+\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
+\tt \verb|closefrom|& \pageref{Dclosefrom}&
+ Close a file opened by {\tt readfrom}\\\hline
+\pl\tt \verb|cutdraw|& \pageref{Dctdraw}&
+ Draw with butt end caps\\\hline
+\tt \verb|dashed|& \pageref{Ddashed}&
+ Apply dash pattern to drawing command\\\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
+\tt \verb|errhelp|& \pageref{Derrhelp}&
+ Declare help message for interactive mode\\\hline
+\tt \verb|errmessage|& \pageref{Derrmessage}&
+ Show error message on the terminal and enter interactive
+ mode\\\hline
+\tt \verb|filenametemplate|& \pageref{Dfilenametemplate}&
+ Set output file name pattern (deprecated, see
+ \verb|outputtemplate|)\\\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|fontmapfile|& \pageref{Dfontmapfile}&
+ read font map entries from file\\\hline
+\tt \verb|fontmapline|& \pageref{Dfontmapline}&
+ declare a font map entry\\\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|message|& \pageref{Dmessage}&
+ Show message string on the terminal\\\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
+\tt \verb|withcmykcolor|& \pageref{Dwithcmykcolor}&
+ Apply CMYK color to drawing command\\\hline
+\tt \verb|withcolor|& \pageref{Dwithcolor}&
+ Apply generic color specification to drawing command\\\hline
+\tt \verb|withgreyscale|& \pageref{Dwithgreyscale}&
+ Apply greyscale color to drawing command\\\hline
+\tt \verb|withoutcolor|& \pageref{Dwithoutcolor}&
+ Don't apply any color specification to drawing command\\\hline
+\tt \verb|withpen|& \pageref{sec.pens}&
+ Apply pen to drawing operation\\\hline
+\tt \verb|withpostscript|& \pageref{Dwithpost}&
+ End raw PostScript code\\\hline
+\tt \verb|withprescript|& \pageref{Dwithpre}&
+ Begin raw PostScript code\\\hline
+\tt \verb|withrgbcolor|& \pageref{Dwithrgbcolor}&
+ Apply RGB color to drawing command\\\hline
+\tt \verb|write to|& \pageref{Dwrite}&
+ Write string to file\\\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
+\pl\tt \verb|buildcycle|& list of paths& path& \pageref{buildcy}&
+ Build a cyclic path\\\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
+\pl\tt \verb|drawdot|& pair& --& \pageref{Ddrawdot}&
+ Draw a dot at the given point\\\hline
+\pl\tt \verb|drawoptions|& drawing options& --& \pageref{Ddropts}&
+ Set options for drawing commands\\\hline
+\pl\tt \verb|image|& string& picture& \pageref{Dimage}&
+ Return picture from text\\\hline
+\pl\tt \verb|incr|& numeric variable& numeric& \pageref{Dincr}&
+ Increment and return new value\\\hline
+\pl\tt \verb|label|& suffix, picture, pair& --& \pageref{Dlabel}&
+ Draw picture near given point\\\hline
+\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
+\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 \verb|--|$\\
+$\tt \qquad \;|\; \descr{direction specifier} \descr{basic path join} \descr{direction specifier}$\\
+$\tt \descr{direction specifier} \rightarrow \descr{empty}$\\
+$\tt \qquad \;|\; \verb|{|curl \descr{numeric expression}\verb|}|$\\
+$\tt \qquad \;|\; \verb|{|\descr{pair expression}\verb|}|$\\
+$\tt \qquad \;|\; \verb|{|\descr{numeric expression}\hbox{\tt ,}\descr{numeric expression}\verb|}|$\\
+$\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 \;|\; nullpen \;|\; nullpicture \;|\; pencircle$\\
+$\tt \qquad \;|\; true \;|\; whatever$\\
+$\tt \descr{unary op} \rightarrow \descr{type}$\\
+$\tt \qquad \;|\; abs \;|\; angle \;|\; arclength \;|\; ASCII \;|\; bbox \;|\; blackpart \;|\; bluepart \;|\; bot \;|\; bounded$\\
+$\tt \qquad \;|\; ceiling \;|\; center \;|\; char \;|\; clipped \;|\; colormodel \;|\; cosd \;|\; cyanpart \;|\; cycle$\\
+$\tt \qquad \;|\; dashpart \;|\; decimal \;|\; dir \;|\; floor \;|\; filled \;|\; fontpart \;|\; fontsize$\\
+$\tt \qquad \;|\; greenpart \;|\; greypart \;|\; hex \;|\; inverse \;|\; known \;|\; length \;|\; lft \;|\; llcorner$\\
+$\tt \qquad \;|\; lrcorner\;|\; magentapart \;|\; makepath \;|\; makepen \;|\; mexp \;|\; mlog \;|\; not \;|\; oct \;|\; odd$\\
+$\tt \qquad \;|\; pathpart \;|\; penpart \;|\; readfrom \;|\; redpart \;|\; reverse \;|\; round \;|\; rt \;|\; sind \;|\; sqrt$\\
+$\tt \qquad \;|\; stroked \;|\; textpart \;|\; textual \;|\; top \;|\; ulcorner$\\
+$\tt \qquad \;|\; uniformdeviate \;|\; unitvector \;|\; unknown \;|\; urcorner \;|\; xpart \;|\; xxpart$\\
+$\tt \qquad \;|\; xypart \;|\; yellowpart \;|\; ypart \;|\; yxpart \;|\; yypart$\\
+$\tt \descr{type} \rightarrow boolean \;|\; cmykcolor \;|\; color \;|\; numeric \;|\; pair$\\
+$\tt \qquad \;|\; path \;|\; pen \;|\; picture \;|\; rgbcolor \;|\; string \;|\; transform$\\
+$\tt \descr{internal type} \rightarrow numeric \;|\; string$\\
+$\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 \;|\; glyph \;|\; penoffset \;|\; point \;|\; postcontrol \;|\; precontrol$\\
+$\tt \qquad \;|\; subpath \;|\; 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 \;|\; defaultcolormodel \;|\; defaultpen \;|\; defaultscale$\\
+$\tt \qquad \;|\; hour \;|\; jobname \;|\; labeloffset \;|\; linecap \;|\; linejoin
+\;|\; minute \;|\; miterlimit \;|\; month$\\
+$\tt \qquad \;|\; outputformat \;|\; outputtemplate \;|\; pausing \;|\; prologues \;|\; showstopping$\\
+$\tt \qquad \;|\; time \;|\; tracingoutput \;|\; 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{cmykcolor expression} \rightarrow \descr{expression}$\\
+$\tt \descr{color expression} \rightarrow \descr{expression}$\\
+$\tt \descr{numeric atom} \rightarrow \descr{atom}$\\
+$\tt \descr{numeric expression} \rightarrow \descr{expression}$\\
+$\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{rgbcolor expression} \rightarrow \descr{expression}$\\
+$\tt \descr{string expression} \rightarrow \descr{expression}$\\
+$\tt \descr{suffix parameter} \rightarrow \descr{parameter}$\\
+$\tt \descr{transform primary} \rightarrow \descr{primary}$
+\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 \;|\; 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 \;|\; write \descr{string expression} to \descr{string expression}$\\
+$\tt \qquad \;|\; \descr{addto command}$\\
+$\tt \qquad \;|\; \descr{drawing command}$\\
+$\tt \qquad \;|\; \descr{font metric command}$\\
+$\tt \qquad \;|\; \descr{newinternal command}$\\
+$\tt \qquad \;|\; \descr{message command}$\\
+$\tt \qquad \;|\; \descr{mode command}$\\
+$\tt \qquad \;|\; \descr{show command}$\\
+$\tt \qquad \;|\; \descr{special 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 \;|\; withrgbcolor \descr{rgbcolor expression} \;|\; withcmykcolor \descr{cmykcolor expression}$\\
+$\tt \qquad \;|\; withgreyscale \descr{numeric expression} \;|\; withoutcolor$\\
+$\tt \qquad \;|\; withprescript \descr{string expression} \;|\; withpostscript \descr{string expression}$\\
+$\tt \qquad \;|\; withpen \descr{pen expression} \;|\; dashed \descr{picture expression}$\\
+$\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{newinternal command} \rightarrow newinternal \descr{internal type} \descr{symbolic token list}$\\
+$\tt \qquad \;|\; newinternal \descr{symbolic token list}$\\
+$\tt $\\
+$\tt \descr{message command} \rightarrow errhelp \descr{string expression}$\\
+$\tt \qquad \;|\; errmessage \descr{string expression}$\\
+$\tt \qquad \;|\; filenametemplate \descr{string expression}$\\
+$\tt \qquad \;|\; message \descr{string expression}$
+\end{ctabbing}
+\caption{Part 1 of the syntax for commands}
+\index{option list?\tdescr{option list}}\index{picture variable?\tdescr{picture variable}}%
+\label{sycmds1}
+
+% is this really true? in practice, in real implementations?
+%\bigskip
+%By the way, the default for \ttindex{randomseed} is, in effect,
+%$\textsl{day} + \textsl{time}*\epsilon$. Unfortunately, \textsl{time}
+%is in minutes.
+\end{figure}
+
+\begin{figure}[htp]
+\begin{ctabbing}
+$\tt \descr{mode command} \rightarrow batchmode \;|\; nonstopmode$\\
+$\tt \qquad \;|\; scrollmode \;|\; errorstopmode$\\
+$\tt $\\
+$\tt \descr{special command} \rightarrow fontmapfile \descr{string expression}$\\
+$\tt \qquad \;|\; fontmapline \descr{string expression}$\\
+$\tt \qquad \;|\; special \descr{string expression}$\\
+$\tt $\\
+$\tt \descr{tracing command} \rightarrow tracingall \;|\; loggingall \;|\; tracingnone$
+\end{ctabbing}
+\caption{Part 2 of the syntax for commands}
+\index{batchmode?\texttt{batchmode}}\index{nonstopmode?\texttt{nonstopmode}}\index{scrollmode?\texttt{scrollmode}}\index{errorstopmode?\texttt{errorstopmode}}%
+\label{sycmds2}
+\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 \;|\; for \descr{symbolic token} \hbox{\tt within} \descr{picture expression}$\\
+$\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}
+
+\endgroup
+
+
+\subsection{Command-line syntax}
+\label{refman:commandline}
+\index{command-line}
+
+\begingroup
+\renewcommand*{\arraystretch}{1.25}% Give command-line switch tables air.
+\newcommand*{\cmdindex}[1]{\index{command-line!\texttt{mpost}!\texttt{#1}}\texttt{#1}}
+
+\subsubsection*{The \texttt{mpost} program}
+\label{refman:mpost}
+
+The command-line syntax of the MetaPost executable is
+$$ {\tt mpost}\ \descr{switches}\ \descr{file}
+$$\label{Dmpost}
+where $\descr{file}$ is a text file containing statements in the
+MetaPost language. Typically, MetaPost input files have file extension
+\texttt{.mp}\index{mp file?{\tt mp} file}\index{files!mp?{\tt mp}},
+e.g., \texttt{foo.mp}. This extension can then be omitted in the
+\texttt{mpost} call. There exist a number of command-line switches to
+control the run-time behavior of the MetaPost executable. Switches can
+prefixed by one or two dashes. Both forms have the same meaning. An
+exemplary call to MetaPost that compiles file \texttt{foo.mp}, but
+immediately exits after encountering the first error without
+user-interaction would look like:
+$$ \hbox{\tt mpost -halt-on-error foo} $$
+
+Here's a summary of the command-line switches understood by
+\texttt{mpost}:
+
+\begin{longtable}{>{\ttfamily}p{.3\linewidth}>{\raggedright\arraybackslash}p{.6\linewidth}}
+ \cmdindex{-debug}
+ & Don't delete intermediate files.\\
+ \cmdindex{-dvitomp}
+ & Act as the \textit{dvitomp} executable (see below).\\
+ \cmdindex{-file-line-error}
+ & Start error messages with \texttt{filename:lineno:} instead of
+ \texttt{!}.\\
+ \cmdindex{-halt-on-error}
+ & Immediately exit after the first error occurred.\\
+ \cmdindex{-help}
+ & Show help on command-line switches.\\
+ \cmdindex{-ini}
+ & Be the INI variant of the program.\\
+ \cmdindex{-interaction}=$\descr{string}$
+ & Set interaction mode to one of \texttt{batchmode, nonstopmode,
+ scrollmode, errorstopmode}.\\
+ \cmdindex{-jobname}=$\descr{jobname}$
+ & Set the name of the job (affects output file names).\\
+ \cmdindex{-kpathsea-debug}=$\descr{number}$
+ & Set debugging flags for path searching.\\
+ \cmdindex{-mem}=$\descr{string}$
+ & Use $\descr{string}$ as memory dump name (same as
+ \texttt{\&$\descr{string}$})\\
+ \cmdindex{-no-file-line-error}
+ & Enable normal MetaPost and \TeX\ style error messages.\\
+ \cmdindex{-no-kpathsea}
+ & Do not use \textit{kpathsea} to find files. All files have to be in
+ the current directory or specified via a full path.\\
+ \cmdindex{-progname}=$\descr{string}$
+ & Pretend to be the $\descr{string}$ executable.\\
+ \cmdindex{-recorder}
+ & Write a list of all opened disk files to
+ \texttt{$\descr{jobname}$.fls}\index{fls file?{\tt fls}
+ file}\index{files!fls?{\tt fls}}. (This functionality is provided
+ by \textit{kpathsea}.)\\
+ \cmdindex{-s}$\descr{key}$=$\descr{value}$ \textrm{or}\newline
+ -s $\descr{key}$=$\descr{value}$
+ & Set internal variable $\descr{key}$ to $\descr{value}$. The
+ assignment is applied just before the input file is read-in. This
+ switch can be applied multiple times on the command-line.\newline
+ $\descr{value}$ can be an integer between -16383 and 16383 or a string
+ in double quotes. For strings, double quotes are stripped, but no
+ other processing takes place.\newline
+ Example: \verb|-soutputformat="svg" -sprologues=3|\newline
+ Use SVG backend converting font shapes to paths.\\
+ \cmdindex{-tex}=$\descr{texprogram}$
+ & Load format $\descr{texprogram}$ for rendering \TeX\ material.\\
+ \cmdindex{-troff}, \cmdindex{-T}
+ & Output \textit{troff} compatible PostScript files.\\
+ \cmdindex{-version}
+ & Print version information and exit.\\
+\end{longtable}
+
+The following command-line switches are silently ignored in
+\textit{mplib}-based MetaPost (v1.100 or later), because they are always
+`on':
+\begin{longtable}{>{\ttfamily}p{.3\linewidth}>{\raggedright\arraybackslash}p{.6\linewidth}}
+ \cmdindex{-8bit}
+ & \\
+ \cmdindex{-parse-first-line}
+ & \\
+\end{longtable}
+
+The following command-line switches are ignored, but trigger a warning:
+\begin{longtable}{>{\ttfamily}p{.3\linewidth}>{\raggedright\arraybackslash}p{.6\linewidth}}
+ \cmdindex{-no-parse-first-line}
+ & \\
+ \cmdindex{-output-directory}=$\descr{string}$
+ & \\
+ \cmdindex{-translate-file}=$\descr{string}$
+ & \\
+\end{longtable}
+
+\renewcommand*{\cmdindex}[1]{\index{command-line!\texttt{dvitomp}!\texttt{#1}}\texttt{#1}}
+
+\subsubsection*{The \texttt{dvitomp} program}
+\label{refman:dvitomp}
+
+The \ttindex{dvitomp}\label{Ddvitomp} program converts DVI\index{dvi
+ file?{\tt dvi} file}\index{files!dvi?{\tt dvi}} files into low-level
+MetaPost code. The command-line syntax of the executable is
+$$ \hbox{\verb|dvitomp|}\ \descr{switches}\ \descr{infile}\ \descr{outfile}
+$$
+where $\descr{infile}$ is the DVI file to convert and $\descr{outfile}$
+contains the equivalent MetaPost code. MetaPost uses the
+\texttt{dvitomp} program when typesetting \verb|btex| \verb|...|
+\verb|etex| labels by \TeX\ for the final conversion back into MetaPost
+code. Files generated that way end with \texttt{.mpx}\index{mpx
+ file?{\tt mpx} file}\index{files!mpx?{\tt mpx}}. The following
+command-line switches are accepted:
+\begin{longtable}{>{\ttfamily}p{.3\linewidth}>{\raggedright\arraybackslash}p{.6\linewidth}}
+ \cmdindex{-help}
+ & Show help on command-line switches.\\
+ \cmdindex{-kpathsea-debug}=$\descr{number}$
+ & Set debugging flags for path searching.\\
+ \cmdindex{-progname}=$\descr{string}$
+ & Pretend to be the $\descr{string}$ executable.\\
+ \cmdindex{-version}
+ & Print version information and exit.\\
+\end{longtable}
+
+The \texttt{dvitomp} program used to be part of a set of external tools,
+called \emph{mpware}\index{mpware tools}\footnote{\texttt{makempx},
+ \texttt{mpto}, \texttt{dvitomp}, and \texttt{dmp}.}, that were used by
+MetaPost for processing \verb|btex| \verb|...| \verb|etex| labels.
+Since MetaPost version~1.100, the label conversion is handled internally
+by the \texttt{mpost} executable. The \emph{mpware} tools are therefore
+obsolete and no longer part of the MetaPost distribution. Nowadays, the
+\texttt{dvitomp} executable is either a copy of the \texttt{mpost}
+executable with the name \texttt{dvitomp} or a wrapper, calling
+\texttt{mpost} as
+$$ \hbox{\verb|mpost -dvitomp|}\ \descr{infile}\
+\descr{outfile}\qquad\hbox{.} $$
+
+\endgroup
+
+%%% Local Variables:
+%%% mode: latex
+%%% TeX-PDF-mode: t
+%%% TeX-master: "mpman"
+%%% End:
diff --git a/Master/texmf-dist/doc/metapost/base/source-manual/mpman-optab.tex b/Master/texmf-dist/doc/metapost/base/source-manual/mpman-optab.tex new file mode 100644 index 00000000000..bd0a2868ea5 --- /dev/null +++ b/Master/texmf-dist/doc/metapost/base/source-manual/mpman-optab.tex @@ -0,0 +1,147 @@ +%%% Two notes on column specification:
+%%% (i) Column widths are manually chosen as small as possible to allow
+%%% for a wider last X column.
+%%% (ii) In the first column \linepenalty=100 prefers shorter paragraphs
+%%% (less lines), where plain \raggedright were indifferent and
+%%% sometimes caused a dangling line, e.g., for 'directionpoint of'
+%%% or 'directiontime of'.
+\begin{longtable}{|>{\raggedright\linepenalty=100\ttfamily}p{.793in}*{3}{|>{\raggedright}p{.715in}}|>{\raggedleft}p{1.5em}|>{\raggedright\arraybackslash}X|}
+\caption{\strut Operators}\label{optab}\\
+\hline
+Name& \multicolumn3{c|}{Argument/result types}& \makebox[.2in][c]{Page}& Explanation\\\cline{2-4}
+& \multicolumn1{c|}{Left}& \multicolumn1{c|}{Right}& \multicolumn1{c|}{Result}& & \\
+\hline
+\hline
+\endfirsthead
+\caption[]{\strut Operators \emph{(continued)}}\\
+\hline
+Name& \multicolumn3{c|}{Argument/result types}& \makebox[.2in][c]{Page}& Explanation\\\cline{2-4}
+& \multicolumn1{c|}{Left}& \multicolumn1{c|}{Right}& \multicolumn1{c|}{Result}& & \\
+\hline
+\hline
+\endhead
+\&\index{&?\texttt{\&}}& string\par path& string\par path & string\par path& \pageref{Damp}& Concatenation---works for paths $l\hbox{\tt\&}r$ if $r$ starts exactly where the $l$ ends\\\hline
+*\index{*?\texttt{*}}& numeric& (cmyk)color\par numeric\par pair& (cmyk)color\par numeric\par pair& \pageref{Dmldiv}& Multiplication\\\hline
+*\index{*?\texttt{*}}& (cmyk)color\par numeric\par pair& numeric& (cmyk)color\par numeric\par pair& \pageref{Dmldiv}& Multiplication\\\hline
+**\index{**?\texttt{**}}& numeric& numeric& numeric& \pageref{Dpow}& Exponentiation\\\hline
++\index{+?\texttt{+}}& (cmyk)color\par numeric\par pair& (cmyk)color\par numeric\par pair& (cmyk)color\par numeric\par pair& \pageref{Dadd}& Addition\\\hline
+++\index{++?\texttt{++}}& numeric& numeric& numeric& \pageref{Dpyadd}& Pythagorean addition $\sqrt{l^2+r^2}$\\\hline
++-+\index{+-+?\texttt{+-+}}& numeric& numeric& numeric& \pageref{Dpysub}& Pythagorean subtraction $\sqrt{l^2-r^2}$\\\hline
+-\index{-?\texttt{-}}& (cmyk)color\par numeric\par pair& (cmyk)color\par numeric\par pair& (cmyk)color\par numeric\par pair& \pageref{Dadd}& Subtraction\\\hline
+-\index{-?\texttt{-}}& --& (cmyk)color\par numeric\par pair& (cmyk)color\par numeric\par pair& \pageref{Dneg}& Negation\\\hline
+/\index{/?\texttt{/}}& (cmyk)color\par numeric\par pair& numeric& (cmyk)color\par numeric\par pair& \pageref{Dmldiv}& Division\\\hline
+<\index{<?\texttt{<}} =\index{=?\texttt{=}} >\index{>?\texttt{>}}\par <=\index{<=?\texttt{<=}} >=\index{>=?\texttt{>=}}\par <>\index{<>?\texttt{<>}}& string\par numeric\par pair\par (cmyk)color\par transform& string\par numeric\par pair\par (cmyk)color\par transform& boolean& \pageref{Dcmpar}& Comparison operators\\\hline
+\pl abs\index{abs?\texttt{abs}}& --& numeric\par pair& numeric& \pageref{Dabs}& Absolute value\par Euclidean length $\sqrt{(\mbox{\ttfamily xpart\ } r)^2+(\mbox{\ttfamily ypart\ } r)^2}$\\\hline
+and\index{and?\texttt{and}}& boolean& boolean& boolean& \pageref{Dand}& Logical and\\\hline
+angle\index{angle?\texttt{angle}}& --& pair& numeric& \pageref{Dangle}& 2$-$argument arctangent (in degrees)\\\hline
+arclength\index{arclength?\texttt{arclength}}& --& path& numeric& \pageref{Darclng}& Arc length of a path\\\hline
+arctime of\index{arctime of?\texttt{arctime of}}& numeric& path& numeric& \pageref{Darctim}& Time on a path where arc length from the start reaches a given value\\\hline
+ASCII\index{ASCII?\texttt{ASCII}}& --& string& numeric& --& ASCII value of first character in string\\\hline
+\pl bbox\index{bbox?\texttt{bbox}}& --& picture\par path\par pen& path& \pageref{Dbbox}& A rectangular path for the bounding box\\\hline
+blackpart\index{blackpart?\texttt{blackpart}}& --& cmykcolor& numeric& \pageref{Dcmykprt}& Extract the fourth component\\\hline
+bluepart\index{bluepart?\texttt{bluepart}}& --& color& numeric& \pageref{Drgbprt}& Extract the third component\\\hline
+boolean\index{boolean?\texttt{boolean}}& --& any& boolean& \pageref{Dboolop}& Is the expression of type boolean?\\\hline
+\pl bot\index{bot?\texttt{bot}}& --& numeric\par pair& numeric\par pair& \pageref{Dbot}& Bottom of current pen when centered at the given coordinate(s)\\\hline
+bounded\index{bounded?\texttt{bounded}}& --& any& boolean& \pageref{Dbounded}& Is argument a picture with a bounding box?\\\hline
+\pl ceiling\index{ceiling?\texttt{ceiling}}& --& numeric& numeric& \pageref{Dceil}& Least integer greater than or equal to\\\hline
+\pl center\index{center?\texttt{center}}& --& picture\par path\par pen& pair& \pageref{Dcenter}& Center of the bounding box\\\hline
+char\index{char?\texttt{char}}& --& numeric& string& \pageref{Dchar}& Character with a given ASCII code\\\hline
+clipped\index{clipped?\texttt{clipped}}& --& any& boolean& \pageref{Dclipped}& Is argument a clipped picture?\\\hline
+cmykcolor\index{cmykcolor?\texttt{cmykcolor}}& --& any& boolean& \pageref{Dccolrop}& Is the expression of type cmykcolor?\\\hline
+color\index{color?\texttt{color}}& --& any& boolean& \pageref{Dcolrop}& Is the expression of type color?\\\hline
+colormodel\index{colormodel?\texttt{colormodel}}& --& image object& numeric& \pageref{Dcolormodel}& What is the color model of the image object?\\\hline
+\pl colorpart\index{colorpart?\texttt{colorpart}}& --& image object&
+(cmyk)color\par numeric\par boolean& \pageref{Dcolorpart}& What is the
+color of the image object?\\\hline
+cosd\index{cosd?\texttt{cosd}}& --& numeric& numeric& \pageref{Dcosd}& Cosine of angle in degrees\\\hline
+\pl cutafter\index{cutafter?\texttt{cutafter}}& path& path& path& \pageref{Dcuta}& Left argument with part after the intersection dropped\\\hline
+\pl cutbefore\index{cutbefore?\texttt{cutbefore}}& path& path& path& \pageref{Dcutb}& Left argument with part before the intersection dropped\\\hline
+cyanpart\index{cyanpart?\texttt{cyanpart}}& --& cmykcolor& numeric& \pageref{Dcmykprt}& Extract the first component\\\hline
+cycle\index{cycle?\texttt{cycle}}& --& path& boolean& \pageref{Dcycop}& Determines whether a path is cyclic\\\hline
+dashpart\index{dashpart?\texttt{dashpart}}& --& picture& picture& \pageref{Ddashpart}& Dash pattern of a path in a stroked picture\\\hline
+decimal\index{decimal?\texttt{decimal}}& --& numeric& string& \pageref{Ddecop}& The decimal representation\\\hline
+\pl dir\index{dir?\texttt{dir}}& --& numeric& pair& \pageref{Ddirop}& $(\cos\theta,\sin\theta)$ given $\theta$ in degrees\\\hline
+\pl direction of\index{direction of?\texttt{direction of}}& numeric& path& pair& \pageref{Ddirof}& The direction of a path at a given `time'\\\hline
+\pl direction\-point of\index{directionpoint of?\texttt{directionpoint of}}& pair& path& numeric& \pageref{Ddpntof}& Point where a path has a given direction\\\hline
+direction\-time of\index{directiontime of?\texttt{directiontime of}}& pair& path& numeric& \pageref{Ddtimof}& `Time' when a path has a given direction\\\hline
+\pl div\index{div?\texttt{div}}& numeric& numeric& numeric& --& Integer division $\lfloor l/r\rfloor$\\\hline
+\pl dotprod\index{dotprod?\texttt{dotprod}}& pair& pair& numeric& \pageref{Ddprod}& vector dot product\\\hline
+filled\index{filled?\texttt{filled}}& --& any& boolean& \pageref{Dfilled}& Is argument a filled outline?\\\hline
+floor\index{floor?\texttt{floor}}& --& numeric& numeric& \pageref{Dfloor}& Greatest integer less than or equal to\\\hline
+fontpart\index{fontpart?\texttt{fontpart}}& --& picture& string& \pageref{Dfontpart}& Font of a textual picture component\\\hline
+fontsize\index{fontsize?\texttt{fontsize}}& --& string& numeric& \pageref{Dfntsiz}& The point size of a font\\\hline
+greenpart\index{greenpart?\texttt{greenpart}}& --& color& numeric& \pageref{Drgbprt}& Extract the second component\\\hline
+greypart\index{greypart?\texttt{greypart}}& --& numeric& numeric& \pageref{Dgreyprt}& Extract the first (only) component\\\hline
+hex\index{hex?\texttt{hex}}& --& string& numeric& --& Interpret as a hexadecimal number\\\hline
+infont\index{infont?\texttt{infont}}& string& string& picture& \pageref{Sinfont}& Typeset string in given font\\\hline
+\pl intersec\-tionpoint\index{intersectionpoint?\texttt{intersectionpoint}}& path& path& pair& \pageref{Disecpt}& An intersection point\\\hline
+intersec\-tiontimes\index{intersectiontimes?\texttt{intersectiontimes}}& path& path& pair& \pageref{Disectt}& Times ($t_l,t_r)$ on paths $l$ and $r$ when the paths intersect\\\hline
+\pl inverse\index{inverse?\texttt{inverse}}& --& transform& transform& \pageref{Dinv}& Invert a transformation\\\hline
+known\index{known?\texttt{known}}& --& any& boolean& \pageref{Dknown}& Does argument have a known value?\\\hline
+length\index{length?\texttt{length}}& --& path\par string\par picture& numeric& \pageref{Dlength}\par \pageref{DlengthString}\par \pageref{DlengthPicture}& Number of components (arcs, characters, strokes, \ldots) in the argument\\\hline
+\pl lft\index{lft?\texttt{lft}}& --& numeric\par pair& numeric\par pair& \pageref{Dlft}& Left side of current pen when its center is at the given coordinate(s)\\\hline
+llcorner\index{llcorner?\texttt{llcorner}}& --& picture\par path\par pen& pair& \pageref{Dcornop}& Lower-left corner of bounding box\\\hline
+lrcorner\index{lrcorner?\texttt{lrcorner}}& --& picture\par path\par pen& pair& \pageref{Dcornop}& Lower-right corner of bounding box\\\hline
+magentapart\index{magentapart?\texttt{magentapart}}& --& cmykcolor& numeric& \pageref{Dcmykprt}& Extract the second component\\\hline
+makepath\index{makepath?\texttt{makepath}}& --& pen& path& \pageref{Dmkpath}& Cyclic path bounding the pen shape\\\hline
+makepen\index{makepen?\texttt{makepen}}& --& path& pen& \pageref{Dmkpen}& A polygonal pen made from the convex hull of the path knots\\\hline
+mexp\index{mexp?\texttt{mexp}}& --& numeric& numeric& --& The function $\exp(x/256)$\\\hline
+mlog\index{mlog?\texttt{mlog}}& --& numeric& numeric& --& The function $256\ln(x)$\\\hline
+\pl mod\index{mod?\texttt{mod}}& --& numeric& numeric& --& The remainder function $l-r\lfloor l/r\rfloor$\\\hline
+normal\-deviate\index{normaldeviate?\texttt{normaldeviate}}& --& --& numeric& --& Choose a random number with mean~0 and standard deviation~1\\\hline
+not\index{not?\texttt{not}}& --& boolean& boolean& \pageref{Dnot}& Logical negation\\\hline
+numeric\index{numeric?\texttt{numeric}}& --& any& boolean& \pageref{Dnumop}& Is the expression of type numeric?\\\hline
+oct\index{oct?\texttt{oct}}& --& string& numeric& --& Interpret string as octal number\\\hline
+odd\index{odd?\texttt{odd}}& --& numeric& boolean& --& Is the closest integer odd or even?\\\hline
+or\index{or?\texttt{or}}& boolean& boolean& boolean& \pageref{Dor}& Logical inclusive or\\\hline
+pair\index{pair?\texttt{pair}}& --& any& boolean& \pageref{Dpairop}& Is the expression of type pair?\\\hline
+path\index{path?\texttt{path}}& --& any& boolean& \pageref{Dpathop}& Is the expression of type path?\\\hline
+pathpart\index{pathpart?\texttt{pathpart}}& --& picture& path& \pageref{Dpathpart}& Path of a stroked picture component\\\hline
+pen\index{pen?\texttt{pen}}& --& any& boolean& \pageref{Dpenop}& Is the expression of type pen?\\\hline
+penoffset of\index{penoffset of?\texttt{penoffset of}}& pair& pen& pair& --& Point on the pen furthest to the right of the given direction\\\hline
+penpart\index{penpart?\texttt{penpart}}& --& picture& pen& \pageref{Dpenpart}& Pen of a stroked picture component\\\hline
+picture\index{picture?\texttt{picture}}& --& any& boolean& \pageref{Dpictop}& Is the expression of type picture?\\\hline
+point of\index{point of?\texttt{point of}}& numeric& path& pair& \pageref{Dpntof}& Point on a path given a time value\\\hline
+postcontrol of\index{postcontrol?\texttt{postcontrol}}& numeric& path& pair& --& First B\'ezier control point on path segment starting at the given time\\\hline
+precontrol of\index{precontrol?\texttt{precontrol}}& numeric& path& pair& --& Last B\'ezier control point on path segment ending at the given time\\\hline
+readfrom\index{readfrom?\texttt{readfrom}}& --& string& string& \pageref{Dreadfrom}& Read a line from file\\\hline
+redpart\index{redpart?\texttt{redpart}}& --& color& numeric& \pageref{Drgbprt}& Extract the first component\\\hline
+reverse\index{reverse?\texttt{reverse}}& --& path& path& \pageref{Drevrse}& `time'-reversed path, beginning swapped with ending\\\hline
+rgbcolor\index{rgbcolor?\texttt{rgbcolor}}& --& any& boolean& \pageref{Drcolrop}& Is the expression of type color?\\\hline
+rotated\index{rotated?\texttt{rotated}}& picture\par path\par pair\par pen\par transform& numeric& picture\par path\par pair\par pen\par transform& \pageref{Dtranop}& Rotate counterclockwise a given number of degrees\\\hline
+\pl round\index{round?\texttt{round}}& --& numeric\par pair& numeric\par pair& \pageref{Dround}& round each component to the nearest integer\\\hline
+\pl rt\index{rt?\texttt{rt}}& --& numeric\par pair& numeric\par pair& \pageref{Drt}& Right side of current pen when centered at given coordinate(s)\\\hline
+scaled\index{scaled?\texttt{scaled}}& picture\par path\par pair\par pen\par transform& numeric& picture\par path\par pair\par pen\par transform& \pageref{Dtranop}& Scale all coordinates by the given amount\\\hline
+scantokens\index{scantokens?\texttt{scantokens}}& --& string& token sequence& \pageref{Dscantokens}& Converts a string to a token or token sequence. Provides string to numeric conversion, etc.\\\hline
+shifted\index{shifted?\texttt{shifted}}& picture\par path\par pair\par pen\par transform& pair& picture\par path\par pair\par pen\par transform& \pageref{Dtranop}& Add the given shift amount to each pair of coordinates\\\hline
+sind\index{sind?\texttt{sind}}& --& numeric& numeric& \pageref{Dsind}& Sine of an angle in degrees\\\hline
+slanted\index{slanted?\texttt{slanted}}& picture\par path\par pair\par pen\par transform& numeric& picture\par path\par pair\par pen\par transform& \pageref{Dtranop}& Apply the slanting transformation that maps $(x,y)$ into $(x+sy,y)$, where~$s$ is the numeric argument\\\hline
+sqrt\index{sqrt?\texttt{sqrt}}& --& numeric& numeric& \pageref{Dsqrt}& Square root\\\hline
+str\index{str?\texttt{str}}& --& suffix& string& \pageref{Dstr}& String representation for a suffix\\\hline
+string\index{string?\texttt{string}}& --& any& boolean& \pageref{Dstrgop}& Is the expression of type string?\\\hline
+stroked\index{stroked?\texttt{stroked}}& --& any& boolean& \pageref{Dstroked}& Is argument a stroked line?\\\hline
+subpath of\index{subpath?\texttt{subpath}}& pair& path& path& \pageref{Dsubpth}& Portion of a path for given range of time values\\\hline
+substring of\index{substring
+of?\texttt{substring of}}& pair& string& string& \pageref{Dsubstr}& Substring bounded by given indices\\\hline
+textpart\index{textpart?\texttt{textpart}}& --& picture& string& \pageref{Dtextpart}& Text of a textual picture component\\\hline
+textual\index{textual?\texttt{textual}}& --& any& boolean& \pageref{Dtextual}& Is argument typeset text?\\\hline
+\pl top\index{top?\texttt{top}}& --& numeric\par pair& numeric\par pair& \pageref{Dtop}& Top of current pen when centered at the given coordinate(s)\\\hline
+transform\index{transform?\texttt{transform}}& --& any& boolean& \pageref{Dtrnfop}& Is the argument of type transform?\\\hline
+transformed\index{transformed?\texttt{transformed}}& picture\par path\par pair\par pen\par transform& transform& picture\par path\par pair\par pen\par transform& \pageref{Dtrfrmd}& Apply the given transform to all coordinates\\\hline
+ulcorner\index{ulcorner?\texttt{ulcorner}}& --& picture\par path\par pen& pair& \pageref{Dcornop}& Upper-left corner of bounding box\\\hline
+uniform\-deviate\index{uniformdeviate?\texttt{uniformdeviate}}& --& numeric& numeric& --& Random number between zero and the value of the argument\\\hline
+\pl unitvector\index{unitvector?\texttt{unitvector}}& --& pair& pair& \pageref{Duvec}& Rescale a vector so its length is~1\\\hline
+unknown\index{unknown?\texttt{unknown}}& --& any& boolean& \pageref{Dunknwn}& Is the value unknown?\\\hline
+urcorner\index{urcorner?\texttt{urcorner}}& --& picture\par path\par pen& pair& \pageref{Dcornop}& Upper-right corner of bounding box\\\hline
+\pl whatever\index{whatever?\texttt{whatever}}& --& --& numeric& \pageref{Dwhatev}& Create a new anonymous unknown\\\hline
+xpart\index{xpart?\texttt{xpart}}& --& pair\par transform& number& \pageref{Dxprt}& $x$ or $t_x$ component\\\hline
+xscaled\index{xscaled?\texttt{xscaled}}& picture\par path\par pair\par pen\par transform& numeric& picture\par path\par pair\par pen\par transform& \pageref{Dtranop}& Scale all $x$ coordinates by the given amount\\\hline
+xxpart\index{xxpart?\texttt{xxpart}}& --& transform& number& \pageref{Dtrprt}& $t_{xx}$ entry in transformation matrix\\\hline
+xypart\index{xypart?\texttt{xypart}}& --& transform& number& \pageref{Dtrprt}& $t_{xy}$ entry in transformation matrix\\\hline
+yellowpart\index{yellowpart?\texttt{yellowpart}}& --& cmykcolor& numeric& \pageref{Dcmykprt}& Extract the third component\\\hline
+ypart\index{ypart?\texttt{ypart}}& --& pair\par transform& number& \pageref{Dyprt}& $y$ or $t_y$ component\\\hline
+yscaled\index{yscaled?\texttt{yscaled}}& picture\par path\par pair\par pen\par transform& numeric& picture\par path\par pair\par pen\par transform& \pageref{Dtranop}& Scale all $y$ coordinates by the given amount\\\hline
+yxpart\index{yxpart?\texttt{yxpart}}& --& transform& number& \pageref{Dtrprt}& $t_{yx}$ entry in transformation matrix\\\hline
+yypart\index{yypart?\texttt{yypart}}& --& transform& number& \pageref{Dtrprt}& $t_{yy}$ entry in transformation matrix\\\hline
+zscaled\index{zscaled?\texttt{zscaled}}& picture\par path\par pair\par pen\par transform& pair& picture\par path\par pair\par pen\par transform& \pageref{Dtranop}& Rotate and scale all coordinates so that $(1,0)$ is mapped into the given pair; i.e., do complex multiplication.\\\hline
+\end{longtable}
diff --git a/Master/texmf-dist/doc/metapost/base/source-manual/mpman.bib b/Master/texmf-dist/doc/metapost/base/source-manual/mpman.bib new file mode 100644 index 00000000000..c476a028e02 --- /dev/null +++ b/Master/texmf-dist/doc/metapost/base/source-manual/mpman.bib @@ -0,0 +1,88 @@ +% BibTeX entries for MetaPost doc, by John Hobby. Public domain. + +@string{dcg = "Discrete and Computational Geometry"} + +@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 +} +@book{ad:red2, + author = "{Adobe Systems Inc.}", + title = "{P}ost{S}cript Language Reference Manual", + publisher = "Addison Wesley", + address = "Reading, Massachusetts", + edition = "second", + year = 1990 +} +@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 +} +@manual{w3c:svg1.1, + organization = "World Wide Web Consortium (W3C)", + title = "Scalable Vector Graphics (SVG)~1.1 Specification", + month = jan, + year = 2003, + note = "\url{http://www.w3.org/TR/SVG11/}" +} +@misc{reckdahl:epslatex, + author = "Keith Reckdahl", + title = "Using Imported Graphics in {\LaTeX} and {pdf\LaTeX}", + month = jan, + year = 2006, + edition = "3.0.1", + note = "\texttt{CTAN://info/epslatex}" +} diff --git a/Master/texmf-dist/doc/metapost/base/source-manual/mpman.ist b/Master/texmf-dist/doc/metapost/base/source-manual/mpman.ist new file mode 100644 index 00000000000..9238679ce08 --- /dev/null +++ b/Master/texmf-dist/doc/metapost/base/source-manual/mpman.ist @@ -0,0 +1,4 @@ +% MakeIndex style file for MetaPost doc, by John Hobby. Public domain. + +% @ is a valid character in some entries +actual '?' % ? instead of @ diff --git a/Master/texmf-dist/doc/metapost/base/source-manual/mpman.mp b/Master/texmf-dist/doc/metapost/base/source-manual/mpman.mp new file mode 100644 index 00000000000..d4e81d0d08c --- /dev/null +++ b/Master/texmf-dist/doc/metapost/base/source-manual/mpman.mp @@ -0,0 +1,858 @@ +% Figures for MetaPost manual, by John Hobby. Public domain. + +if scantokens(mpversion) < 1.200: + filenametemplate +else: + outputtemplate := +fi +"%j-%c.mps"; + +%%% This redefinition of dotlabel draws dots as a closed path +%%% which are rendered more smoothly in Adobe Reader. +vardef dotlabel@#(expr s,z) text t_ = + label@#(s,z) t_; + addto currentpicture + contour (makepath pencircle scaled dotlabeldiam) shifted z t_; +enddef; + + +%%% TeX macro \place is only used in figure 0. +verbatimtex +\input texnames.sty +\def\place#1{\vphantom{FiMP}\smash{#1}} +etex + +%%% The boxes package is only used in figure 0. +input boxes + +beginfig(0); +ba.dy = bb.dy = d.dy = 12bp; +d.dx = 100bp; +boxit.aa(btex \place{Figures in MetaPost} etex); +boxit.ab(btex \place{\TeX\ Document} etex); +boxit.ba(btex \hbox to 75bp {\hfil\place{MetaPost}\hfil} etex); +boxit.bb.(btex \hbox to 75bp {\hfil\place{\TeX\ or \LaTeX}\hfil} etex); +boxit.ca(btex \place{Figures in PostScript} etex); +boxit.cb(btex \place{{\tt dvi} file} etex); +boxit.d(btex \place{\tt dvips} etex); +boxit.e(btex PostScript etex); +boxit.f(btex \vbox{ + \hbox to 50bp {\hfil\hbox{bounding}\hfil} + \hbox to 50bp {\hfil\hbox{box}\hfil} + } etex scaled .8); +ba.n - aa.s = ca.n - ba.s += bb.n - ab.s = cb.n - bb.s += e.n - d.s = down * 25bp; +ypart cb.s - ypart d.n = 25bp; +e.s = origin; +ypart ca.s = ypart cb.s; +xpart aa.n = xpart 0.1[d.nw,d.ne]; +xpart ab.n = xpart 0.9[d.nw,d.ne]; +drawunboxed(aa,ab,ca,cb,e); +drawboxed(ba,bb,d); +drawarrow aa.s -- top ba.n; drawarrow ab.s -- top bb.n; +drawarrow ba.s -- top ca.n; drawarrow bb.s -- top cb.n; +drawarrow ca.s -- top 0.1[d.nw,d.ne]; +drawarrow cb.s -- top 0.9[d.nw,d.ne]; +drawarrow d.s -- top e.n; +path p; +p = ca.e{right} .. {right}bb.w; +f.c = point .5 of p; +drawunboxed(f); +draw p cutafter bpath f dashed evenly; +drawarrow p cutbefore subpath (1,3) of bpath f dashed evenly; +endfig; + + +beginfig(1); +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: + drawdot (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 "ptmr8r" 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; + + +beginfig(55) +picture wheel, car; +path body; + u := 5bp; + % Use a calligraphic pen. + pickup pencircle scaled .1u yscaled .6 rotated 30; + % Define a wheel object. + wheel := image( + draw fullcircle scaled 2u xscaled .8 rotated 30; + draw fullcircle scaled .1u xscaled .8 rotated 30 + withpen currentpen scaled .5; + ); + % Construct path for car body. + body := (3.2u,0){right}..(4.5u,1.5u){up}..(1.5u,2.5u){dir(-170)} + ..(1.5u,4.25u){up}...(0,5u){left}; + body := body .. reverse body reflectedabout (origin, (0,u)); + % Define a car object. + car := image( + draw wheel shifted (2u, 0);% Draw two wheels. + draw wheel shifted (-2u, 0); + draw (-.8u,0){dir(5)}..(.8u,0);% Draw connection betweeen wheels. + draw body;% Draw body. + % Draw speed indicators. + for i=1.5, 2, 2.5: + draw (5u, u*i){right}..{dir(-10)}(6.5u,u*i*.95); + endfor + ) shifted (0, u) slanted -.2 rotated 1;% Introduce asymmetries. + % Draw two cars and a faster one. + draw car shifted (5u,0); + draw car shifted (20u,0); + draw car slanted -.25 shifted (45u,0); + % Draw motorway. + draw (-5u,-u)...(25u,-.5u)...(60u,-u) + withpen currentpen scaled 4 withcolor .7white; +endfig; + + +fontmapfile "=lm-ec.map"; +beginfig(56); + picture q; + path p; + interim ahlength := 12bp; + interim ahangle := 25; + q := glyph "Dcaron" of "ec-lmr10" scaled .2; + for item within q: + p := pathpart item; + drawarrow p withcolor (.6,.9,.6) + withpen pencircle scaled 1.5; + for j=0 upto length p: + pickup pencircle scaled .7; + draw (point j of p -- precontrol j of p) + dashed evenly withcolor blue; + draw (point j of p -- postcontrol j of p) + dashed evenly withcolor blue; + pickup pencircle scaled 3; + draw precontrol j of p withcolor red; + draw postcontrol j of p withcolor red; + pickup pencircle scaled 2; + draw point j of p withcolor black; + endfor + endfor +endfig; + + +%%% Title page rule. +beginfig(60); + pickup pencircle scaled 1.1bp; + linecap := rounded; + draw origin--(4.38in,0); +endfig; + +end diff --git a/Master/texmf-dist/doc/metapost/base/source-manual/mpman.tex b/Master/texmf-dist/doc/metapost/base/source-manual/mpman.tex new file mode 100644 index 00000000000..0f689273db3 --- /dev/null +++ b/Master/texmf-dist/doc/metapost/base/source-manual/mpman.tex @@ -0,0 +1,5289 @@ +% $Id: mpman.tex 1051 2009-05-25 08:31:54Z taco $ +% MetaPost manual, by John Hobby. License at end. +\listfiles +\RequirePackage{ifpdf} +\ifpdf +\ifnum\pdftexversion<140 +\else +\pdfminorversion=5 +\pdfobjcompresslevel=1% Use compressed object streams. +\fi +\RequirePackage{cmap} +\fi +\documentclass{article} % article is NOT the original style +\usepackage[nofancy]{svninfo}% Access VCS information. +\svnInfo $Id: mpman.tex 1051 2009-05-25 08:31:54Z taco $ +\newcommand*{\mpversion}{1.200} + +\usepackage[T1]{fontenc} +\usepackage{lmodern} +\usepackage{textcomp} +\usepackage{mflogo} +\usepackage{makeidx} +\usepackage{fancyvrb} +\usepackage{ctabbing} +\RecustomVerbatimEnvironment + {verbatim}{BVerbatim}{baseline=c} +\usepackage{graphicx} +\usepackage[latin1]{inputenc} +\usepackage[textwidth=6in,textheight=8.65in]{geometry} +\usepackage{tocloft} + \setlength\cftbeforesecskip{1.3ex plus 0.3ex minus 0.3ex} +\usepackage{ltxtable} + + +\def\ttindex#1{{\tt #1}\index{#1?\texttt{#1}}} +\def\ttt{\texttt} % I get tired of typing this out + +\def\ConTeXt{Con\TeX t} + +\newcommand\descr[1]{{\langle\hbox{#1}\rangle}} +\newcommand\invisgap{\nobreak\hskip0pt\relax} +\newcommand\tdescr[1]{$\langle$\invisgap#1\invisgap$\rangle$} + +\newcommand\pl{\dag} + +\newcommand\mathcenter[1]{\vcenter{\hbox{#1}}} + + +\renewcommand{\topfraction}{.85} +\renewcommand{\bottomfraction}{.7} +\renewcommand{\textfraction}{.15} +\renewcommand{\floatpagefraction}{.5} +\renewcommand{\dbltopfraction}{.66} +\renewcommand{\dblfloatpagefraction}{.66} +\setcounter{topnumber}{9} +\setcounter{bottomnumber}{9} +\setcounter{totalnumber}{20} +\setcounter{dbltopnumber}{9} + +\makeindex + +\usepackage{multicol} +\usepackage[rgb,x11names]{xcolor}% Optimize for screen reading. +\usepackage{hyperxmp} +\usepackage{hyperref} +\hypersetup{ + pdftitle={MetaPost: A User's Manual}, + pdfauthor={John D. Hobby and the MetaPost development team}, + pdfkeywords={MetaPost, PostScript, SVG, vector graphics language, + MetaFont, TeX} +} +\hypersetup{ + pdfstartview={XYZ null null null},% Zoom factor is determined by viewer. + colorlinks, + linkcolor=RoyalBlue3, + urlcolor=Chocolate4, + citecolor=SpringGreen3 +} +\usepackage[all]{hypcap} +\ifpdf +\pdfmapfile{=cm2lm.map}% replace CM by LM in figures +\else +\DeclareGraphicsExtensions{.mps} +\DeclareGraphicsRule{mps}{eps}{*}{} +\usepackage{breakurl} +\fi +\begin{document} +\VerbatimFootnotes +%%% Title page layout documentation is missing. +\begin{titlepage} + \vbox to \textheight {% + \vskip0pt + \vfil + \vfil + \vfil + \centerline{\resizebox{3.5in}{!}{\fontseries{b}\selectfont\MP}} + \vskip10bp% actually 21bp (-11bp) + \centerline{\includegraphics{mpman-60.mps}} + \vskip15bp% actually 21bp (-6bp) + \centerline{% + \resizebox{3.5in}{!}{% + \scshape% + \fontsize{28bp}{28bp}\selectfont + \strut\lowercase{A USER\kern-2bp\lower3bp\hbox{'}S MANUAL}% + }% + } + \vskip-11bp + \vfil + \vfil + \centerline{\large John D. Hobby} + \vskip3bp + \centerline{and the MetaPost development team} + \vskip20.8bp% actually 31.8bp (-11bp) + \centerline{\large documented version: \mpversion} + \vskip3bp + \centerline{\svnToday} + \vfil + \vfil + \vfil + } +\end{titlepage} + +\setlength{\columnsep}{2.5em} +\begin{multicols}{2} +\tableofcontents +\end{multicols} + +\section{Introduction} +\label{intro} + +MetaPost is a programming language much like Knuth's \MF\footnote{\MF\ +is a trademark of Addison Wesley Publishing +company.}\index{metafont?\MF}~\cite{kn:c} except that it outputs +vector graphics, either PostScript programs or SVG\index{SVG} graphics, +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. + +This document introduces the MetaPost language, beginning with the +features that are easiest to use and most important for simple +applications. The first few sections describe the language as it +appears to the novice user with key parameters at their default values. +Some features described in these sections are part of a predefined macro +package called Plain. Later sections summarize the complete language +and distinguish between primitives and preloaded macros from the Plain +macro package\index{Plain macros}. Reading the manual and creating +moderately complex graphics with MetaPost does not require knowledge of +\MF\ or access to {\sl The \MF book} \cite{kn:c}. However, to really +master MetaPost, both are beneficial, since the MetaPost language is +based on Knuth's \MF\ to a large extent. Appendix~\ref{MPvsMF} gives a +detailed comparison of MetaPost and \MF. + +MetaPost documentation is completed by ``Drawing Boxes with MetaPost'' +and ``Drawing Graphs with MetaPost''---the manuals of the \texttt{boxes} +and \texttt{graph} packages originally developed by John~D. Hobby. + +The MetaPost home page is \url{http://tug.org/metapost}. It has links +to much additional information, including many articles that have been +written about MetaPost. For general help, try the +\url{metapost@tug.org} mailing list; you can subscribe to this list at +\url{http://tug.org/mailman/listinfo/metapost}. + +The development is currently hosted at +\url{https://foundry.supelec.fr/projects/metapost/}; visit this site +for the current development team members, sources, and much else. + +Please report bugs and request enhancements either on the +\url{metapost@tug.org} list, or through the address given above. +(Please do not send reports directly to Dr.\ Hobby any more.) + + +\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: +$$ \includegraphics{mpman-1.mps} $$ + +\label{Ddrawdot}MetaPost also has a \ttt{drawdot} command to print a +single point, as in \ttt{drawdot(30,0)}. + +What is meant by coordinates like \verb|(30,0)|? MetaPost uses the same +default coordinate system that PostScript\index{PostScript!coordinate +system} does. This +means that \verb|(30,0)| is 30 units to the right of the origin, where a +unit is $1\over72$ of an inch. We shall refer to this default unit as a +{\sl PostScript point\/}\index{PostScript!point}\index{point!PostScript} +to distinguish it from the standard printer's +point\index{point!printer's} which is $1\over72.27$ inches. + +MetaPost uses the same names for units of measure that \TeX\ and \MF\ +do. Thus \verb|bp|\index{bp?\texttt{bp}}\label{Dbp} refers to +PostScript points (``big points'') and +\verb|pt|\index{pt?\texttt{pt}}\label{Dpt} refers to printer's points. +Other units of measure include +\verb|in|\index{in?\texttt{in}}\label{Din} for inches, +\verb|cm|\index{cm?\texttt{cm}}\label{Dcm} for centimeters, and +\verb|mm|\index{mm?\texttt{mm}}\label{Dmm} for millimeters. For +example, +$$ \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 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|drawdot| 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: drawdot (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: drawdot (i*u,j*u); endfor +endfor +endfig; +\end{verbatim} +\quad \mathcenter{\includegraphics{mpman-2.mps}} +$$ +\caption{MetaPost commands and the resulting output} +\label{fig1} +\end{figure} + + +\section{The MetaPost workflow} +\label{workflow} + +Before describing the MetaPost language in detail, let's have a look at +how the MetaPost program is used for developing graphics: creating +MetaPost source files, compiling sources, previewing MetaPost graphics, +and finally including MetaPost graphics into third-party applications. +This section also contains some technical details about MetaPost that +are useful to know. If you're not interested in these basics right now +you can savely skip those parts and only refer to them later. + +\subsection{Processing source files} +\label{processing} + +To create graphics with MetaPost, you prepare a text file containing +code in the MetaPost language and then invoke the compiler, usually by +giving a command of the form\index{mpost?\texttt{mpost}} +$$ {\tt mpost}\, \descr{filename} $$ +on the command-line. The syntax and program name itself are +system-dependent; sometimes it is named \texttt{mp}. MetaPost input +files\index{files!input} normally have names ending +\texttt{.mp}\index{mp file?{\tt mp} file}\index{files!mp?{\tt mp}} but +this part of the name can be omitted when invoking MetaPost. The +command-line options provided by MetaPost are summarized in +appendix~\ref{refman:commandline}. + +\paragraph{Input file} +\label{inputfile} + +A MetaPost input file normally contains a sequence of +\verb|beginfig()|\index{beginfig?\texttt{beginfig}}, +\verb|endfig|\index{endfig?\texttt{endfig}} pairs with an {\tt + end}\index{end?\texttt{end}} statement after the last one. These are +macros that perform various administrative functions and ensure that the +results of all drawing operations get packaged up and translated into +PostScript. The numeric argument to the \verb|beginfig| macro +determines the name of the corresponding output file, whose name, by +default, is of the form $\descr{jobname}{\tt.}\descr{n}$, where +$\descr{jobname}$ is the base name of the graphics source file and +$\descr{n}$ is the current argument to \verb|beginfig|. As an example, +if a file is named {\tt fig.mp}, the output from drawing statements +between \verb|beginfig(1)| and the next \verb|endfig| is written in a +file {\tt fig.1}\index{files!output}. + +Statements can also appear outside \verb|beginfig/endfig|. Such +statements are processed, but drawing operations generate no visible +output. Typically, global configurations are put outside +\verb|beginfig/endfig|, e.g., assignments to internal variables, such as +\verb|outputtemplate| or \verb|prologues|, or a \LaTeX\ preamble +declaration for enhanced text rendering. + +\paragraph{Log file and version number} +\label{logfile} + +Any terminal I/O is summarized in a +transcript\index{files!transcript}\index{transcript file} file called +$\descr{filename}{\tt.log}$\index{log file?{\tt log} + file}\index{files!log?{\tt 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 identifies the +version\index{version number} of MetaPost you are using. The version +number is also written to the generated PostScript or SVG file as a +comment (for PostScript output the \texttt{Creator}\index{Creator + comment in PostScript output} line is used). You can also determine +the current version from within a MetaPost program via the predefined +constant string +\texttt{mpversion}\index{mpversion?\texttt{mpversion}}\label{Dmpversion} +(since version~0.9). For instance the following code + +$$\begin{verbatim} +message "mp = " & mpversion; +\end{verbatim} +$$ +writes +$$\begin{verbatim}[commandchars=\\\{\}] +mp = \mpversion +\end{verbatim} +$$ +to the console and the transcript file. + +\paragraph{Output format} +\label{outputformat} + +MetaPost can generate graphic in two output formats: Encapsulated +PostScript\index{PostScript!structured} (EPSF\index{EPSF}), hence the +name, and, since version~1.200, Scalable Vector Graphics +(SVG\index{SVG}) following version~1.1 of the SVG +specification~\cite{w3c:svg1.1}. By default, MetaPost outputs +PostScript files. The output format can be changed to SVG by assigning +the value \verb|"svg"| to the internal string variable\index{internal + variables}\index{variables!internal} +\ttindex{outputformat}\label{Doutputformat}: + +$$\begin{verbatim} +outputformat := "svg"; +\end{verbatim} +$$ + +Any other value makes MetaPost fall back to PostScript output. Variable +\verb|outputformat| is case-sensitive, so assigning it the string +\verb|"SVG"| enables PostScript output, too. Default value of variable +\verb|outputformat| is \verb|"eps"|. + +\paragraph{Output file names} +\label{outputfilenames} + +As discussed earlier, by default, every +\verb|beginfig/endfig| group in an input file corresponds to an output +file that follows the naming scheme $\descr{jobname}{\tt.}\descr{n}$. +That is, all files have varying numeric file extensions. MetaPost +provides a template mechanism that allows for more flexible output file +names. The template mechanism uses \ttt{printf}-style escape sequences +that are re-evaluated at ship-out time, i.e., before each figure is +written to disk. + +To configure the output file naming scheme a string containing the +corresponding escape sequences has to be assigned to the internal string +variable\index{internal variables}\index{variables!internal} +\ttt{outputtemplate}% +\index{outputtemplate?\texttt{outputtemplate}}\label{Doutputtemplate}. +The escape sequences provided are listed in table~\ref{tab:fntmpl}. If +this code is saved in a file \ttt{fig.mp}, + +$$\begin{verbatim} +outputtemplate := "%j-%3c.mps"; +beginfig(1); + draw origin--(100,100); +endfig; +\end{verbatim} +$$ +it will create the output file \ttt{fig-001.mps} instead of \ttt{fig.1}. +The file extension \texttt{.mps}\index{mps file?{\tt mps} + file}\index{files!mps?{\tt mps}} is conventionally chosen for +MetaPost's PostScript output (see section~\ref{teximport}). For SVG +output one would want to use \texttt{.svg}\index{svg file?{\tt svg} + file}\index{files!svg?{\tt svg}} instead. + +%\suppressfloats[t] +\begin{table} + \def\d{$\langle$0-9$\rangle$} + \centering + \begin{tabular}{|>{\ttfamily}l|>{\ttfamily}l|l|} + \hline + \multicolumn1{|c|}{Escape sequence} & \multicolumn1{c|}{Equivalent} + & \multicolumn1{c|}{Meaning}\\\hline + \%\%\index{\%\%?\texttt{\%\%}} & & percent sign\\ + \%\d\{$\descr{internal + variable}$\}\index{\%\{...\}?\texttt{\%\{\ldots\}}} & & evaluate + internal variable\\ + \%j\index{\%j?\texttt{\%j}} & \%\{jobname\} & current jobname\\ + \%\d c\index{\%c?\texttt{\%c}} & \%\d\{charcode\} & charcode value (\verb|beginfig| + argument)\\ + \%\d y\index{\%y?\texttt{\%y}} & \%\d\{year\} & current year\\ + \%\d m\index{\%m?\texttt{\%m}} & \%\d\{month\} & month (numeric)\\ + \%\d d\index{\%d?\texttt{\%d}} & \%\d\{day\} & day of the month\\ + \%\d H\index{\%H?\texttt{\%H}} & \%\d\{hour\} & hour\\ + \%\d M\index{\%M?\texttt{\%M}} & \%\d\{minute\} & minute\\ + \hline + \end{tabular} + \caption{Allowed escape sequences for \ttt{outputtemplate}} + \label{tab:fntmpl} +\end{table} + +The template mechanism can also be used for naming graphic files +individually, yet keeping all sources in one file. E.\,g., collecting +different diagram sources in a file \ttt{fig.mp} + +$$\begin{verbatim} +outputtemplate := "fig-quality.mps"; +beginfig(1); + ... +endfig; + +outputtemplate := "fig-cost-vs-productivity.mps"; +beginfig(2); + ... +endfig; +\end{verbatim} +$$ +it might be easier to recall the correct diagram names in a \TeX\ +document than with numbered file names. Note, the argument to +\verb|beginfig| is not relevant as long as there's no \ttt{\%c} pattern +in the file name template string. + +To ensure compatibility with older files, the default value of +\ttt{outputtemplate} is \verb|%j.%c|. +If you assign an empty string, it will revert to that default. MetaPost +versions~1.000 to~1.102 used a different template mechanism, see +section~\ref{Dfilenametemplate} for more information. + +What does one do with all the graphic files? PostScript files are +perfectly suitable for inclusion into documents created by +\TeX\index{TeX?\TeX} or \emph{troff}\index{troff}. The SVG format, as +an XML descendant (Extensible Meta Language), is more aiming at +automated data processing/interchanging and is widely used for web +applications. The next sections deal with the import of MetaPost +graphics into third-party applications. + +At this point, it seems advisable to point out, that it is good style to +create MetaPost graphics at nearly target size. While vector graphics +\emph{can} be scaled without quality degradation, the visual character +of a drawing might change unintentionally at large post-processing scale +factors, because certain properties of a drawing do not scale +proportionally, e.g., line width or arrow size. Additionally, while +outline fonts do scale proportionally, this is not always desired, e.g., +when a font is available in optical sizes, like the Computer Modern font +family. + +\subsection{Previewing MetaPost graphics} +\label{previewing} +\index{previewing} +\index{PostScript!previewing} +\index{SVG!previewing} + +The PostScript output of MetaPost can be previewed with any decent +PostScript viewer, e.\,g., GSview\index{GSview}. +The situation becomes only a little bit fussy when PostScript graphics +contain text. By default, MetaPost doesn't produce self-contained EPS +files, e.\,g., font resources and encoding vectors are not stored in +the output. For that reason MetaPost output containing text may be +rendered with wrong fonts, wrong glyphs or with no text at all in a +PostScript viewer. For a long time, the most reliable way for +previewing was to prepare a test document that includes all MetaPost +figures, process that with \TeX\ or \LaTeX\ and \ttindex{dvips} and +display the resulting \ttt{ps} file in a PostScript +viewer.\footnote{There are alternatives, though. \ttindex{mpstoeps} is +a Perl script that automates the process outlined above. +\ttindex{mptopdf} is another tools that converts MetaPost files to +PDF.} + +However, with MetaPost version~1.000 the situation changed. Since that +version MetaPost is able to produce self-contained EPS files, that can +reliably be previewed, may they contain text or not. The +new behaviour can be triggered by setting MetaPost's internal variable +\ttt{prologues}\index{prologues?\texttt{prologues}} to~3. See +section~\ref{Dbtex} for more information on \ttt{prologues}. + +Starting with version~1.200, MetaPost is also capable of producing +SVG output. SVG files can be previewed with certain web browsers, +for example Firefox~3\index{Firefox} or Konqueror~4.2\index{Konqueror}. + +\subsection{Importing MetaPost graphics in \TeX\ documents} +\label{teximport} +\index{TeX?\TeX!importing MetaPost files} +\index{LaTeX?\LaTeX!importing MetaPost files} +\index{pdfLaTeX?pdf\LaTeX!importing MetaPost files} +\index{pdfTeX?pdf\TeX!importing MetaPost files} +\index{ConTeXt?Con\TeX t!importing MetaPost files} + +MetaPost graphics in the PostScript format can be easily integreated +into documents prepared with \TeX\ and friends. MetaPost's PostScript +output is a low-featured dialect of the Postscript language, called +\emph{purified EPS}, that can be converted into the Portable Document +Format (PDF\index{PDF}) language on-the-fly. For that reason, MetaPost +graphics can be handled by both engines, the traditional \TeX\ with an +external output driver and the newer pdf\TeX, that contains a built-in +PDF output driver. + +Figure~\ref{fig0} shows the process of including a MetaPost graphic into +a plain \TeX\ or \LaTeX\ document. In the \TeX\ document a ``magic +macro'' provided by the format or an external package is used for +including a graphic file. During the typesetting stage, the macro only +reads bounding box information off the PostScript file and reserves the +required space on the page via an empty box. The file reference is +passed-on to the output driver and only then, finally, the file is +embedded into the document. The freely available program +\ttindex{dvips} is used as an output driver in this +example.\footnote{The C source for \ttt{dvips} comes with the web2c + \TeX\ distribution. Similar programs are available from other + sources.} The next paragraphs give brief information on some popular +combinations of formats and engines. + +\begin{figure}[htp] +$$ \includegraphics{mpman-0.mps} $$ +\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} + +\paragraph{Plain \TeX\ with \TeX} +For users of \TeX\ with traditional DVI output the +\ttt{epsf}\index{epsf.tex?\texttt{epsf.tex}} package provides the +``magic macro'' +$$ \verb|\epsfbox{|\descr{filename}\verb|}|% +\index{epsfbox?\texttt{\string\epsfbox}} $$ +for embedding graphics, e.g., \verb|\epsfbox{fig.1}|. + +\paragraph{Plain \TeX\ with pdf\TeX} +Users of Plain \TeX\ and pdf\TeX\ should refer to the standalone macros +of the \ttindex{mptopdf} bundle, that can be found at +\url{http://context.aanhet.net/mptopdf.htm}. + +\paragraph{\LaTeX\ format} +For \LaTeX\ documents the well-known \ttindex{graphics} (or +\ttindex{graphicx}) package aids in external graphics inclusion. The +package supports different engines and can handle several graphic +formats. The ``magic macro'' is +$$ \verb|\includegraphics{|\descr{filename}\verb|}|% +\index{includegraphics?\texttt{\string\includegraphics}} $$ + +When the \ttt{dvips} driver is chosen, the \ttt{graphics} package +assumes all files with an unknown file extension to be in the EPS +format. MetaPost files with a numeric default file extension are +therefore handled correctly -- even if only in a fall-back procedure +(see~\cite{reckdahl:epslatex} for more information). + +For the pdf\TeX\ driver, the situation is a bit different. Only files +with file extension \texttt{.mps}\index{mps file?{\tt mps} + file}\index{files!mps?{\tt mps}} are recognized as purified EPS and +can be converted to PDF\index{PDF} on-the-fly. The recommended +procedure for including MetaPost graphics into \LaTeX\ documents +compiled with the pdf\TeX\ engine should be obvious: change MetaPost's +output file naming scheme to write files ending \texttt{.mps} via +\verb|outputtemplate|\index{outputtemplate?\texttt{outputtemplate}} (see +p.~\pageref{Doutputtemplate}). In the \LaTeX\ document include the +graphic files with full name, e.g., +$$\begin{verbatim} +\includegraphics{fig-1.mps} +\end{verbatim} +$$ + +Note, the latter approach works with the \ttt{dvips} driver, too. Even +though, again, this time \ttt{.mps} is an unknown file extension and +triggers EPS file handling in the fall-back procedure. This property of +the \ttt{graphics} package, that comes in handy for MetaPost files, is +the reason many MetaPost source files start with the line +$$\begin{verbatim} +outputtemplate := "%j-%c.mps"; +\end{verbatim} +$$ + +\paragraph{Con\TeX t} +In Con\TeX t\index{ConTeXt?Con\TeX t} support of MetaPost is integrated +in the kernel. Apart from inline graphics (see MetaFun\index{MetaFun} +manual), one can embed graphics explictely with the +\verb+\externalfigure+% +\index{externalfigure?\texttt{\string\externalfigure}} command. +Numbered graphics are recognized automatically, as are graphics with the +\ttt{mps} suffix. Special features like shading, transparency, image +inclusion, color spaces and such are handled automatically. In practice +Con\TeX t users will probably define MetaPost graphics in the document +source which has some advantages, like a more natural interfacing with +document properties, font support, and automatic processing. Support +for MetaPost inclusion is present in the versions MkII as well as MkIV, +but the used methods are slightly different. Future versions of MkIV +will support an even more tight integration. + +\subsection{Importing MetaPost graphics in \emph{troff} documents} +\label{troffimport} +\index{troff!importing MetaPost files} + +It is also possible to include MetaPost output in a GNU \emph{troff} +document. The procedure is similar to Figure~\ref{fig0}: the +\ttt{grops} output processor includes PostScript files when they are +requested via \emph{troff}'s \ttt{\string\X} command. The +\ttt{-mpspic}\index{mpspic?\texttt{-mpspic}} macro package provides a +command \verb|.PSPIC|\index{PSPIC?\texttt{.PSPIC}}, that does just that +when including an encapsulated PostScript file in the source code. For +instance, the \emph{troff} command +$$ \hbox{\verb|.PSPIC fig.1|} $$ +includes \ttt{fig.1}, using the natural height and width of the +image as given in the file's bounding box. + +\subsection{Handling SVG files} +\label{svgimport} +\index{SVG!third-party applications} + +SVG graphics can be easily embedded into HTML\index{HTML} documents with +the following code snippet: + +$$\begin{verbatim} +<p> + <object data="foo.svg" type="image/svg+xml" width="300" height="200"> + </object> +</p> +\end{verbatim} +$$ + +SVG files can also be imported by various interactive graphics editing +programs, for example GIMP\index{GIMP} or Inkscape\index{Inkscape}. See +section~\ref{Dprologues} for information on font handling in SVG +graphics. + + +\section{Curves} +\label{curves} + +MetaPost is perfectly happy to draw curved lines as well as straight ones. +A \verb|draw| statement with the points separated by +\verb|..|\index{..?\texttt{..}} draws a smooth curve through the points. +For example consider the result of +$$ \hbox{\verb|draw z0..z1..z2..z3..z4|} $$ +after defining five points as follows: +$$\begin{verbatim} +z0 = (0,0); z1 = (60,40); +z2 = (40,90); z3 = (10,70); +z4 = (30,50); +\end{verbatim} +$$ +Figure~\ref{fig2} shows the curve with points \verb|z0| through \verb|z4| +labeled. + +\begin{figure}[htp] +$$ \includegraphics{mpman-3.mps} +$$ +\caption[A curve through points 0, 1, 2, 3, and 4] + {The result of {\tt draw z0..z1..z2..z3..z4}} +\label{fig2} +\end{figure} + +There are many other ways to draw a curved path through the same five +points. To make a smooth closed curve, connect \verb|z4| back to the +beginning by appending \verb|..cycle|\index{cycle?\texttt{cycle}} to the +\verb|draw| statement as shown in Figure~\ref{fig3}a. It is also +possible in a single \verb|draw| statement to mix curves and straight +lines as shown in Figure~\ref{fig3}b. Just use \verb|--| where you want +straight lines and \verb|..| where you want curves. Thus +$$ \hbox{\verb|draw z0..z1..z2..z3--z4--cycle|} $$ +produces a curve through points 0,~1, 2, and~3, then a polygonal line from +point~3 to point~4 and back to point~0. The result is essentially the same +as having two draw statements +\begin{eqnarray*} + \hbox{\verb|draw z0..z1..z2..z3|}\\ +\noalign{\hbox{and}} + \hbox{\verb|draw z3--z4--z0|} +\end{eqnarray*} + +\begin{figure}[htp] +$$ {\includegraphics{mpman-104.mps} \atop (a)} + \qquad {\includegraphics{mpman-204.mps} \atop (b)} +$$ +\caption[Closed curves through five points] + {(a)~The result of {\tt draw z0..\linebreak[0]z1..\linebreak[0]% + z2..\linebreak[0]z3..\linebreak[0]z4..\linebreak[0]cycle}; + (b)~the result of {\tt draw z0..\linebreak[0]z1..\linebreak[0]% + z2..\linebreak[0]z3--\linebreak[0]z4--\linebreak[0]cycle}.} +\label{fig3} +\end{figure} + +\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] +$$ \includegraphics{mpman-5.mps} +$$ +\caption[A curve and the control polygon] + {The result of {\tt draw z0..z1..z2..z3..z4} with the + automatically-selected B\'ezier control polygon illustrated by dashed + lines.} +\label{fig4} +\end{figure} + +\subsection{Specifying Direction, Tension, and Curl} +\label{tenscurl} + +MetaPost provides many ways of controlling the behavior of a curved path +without actually specifying the control points. For instance, some +points on the path may be selected as vertical or horizontal extrema. +If \verb|z1| is to be a horizontal extreme and \verb|z2| is to be a +vertical extreme, you can specify that $(X(t),Y(t))$ should go upward at +\verb|z1| and to the left at \verb|z2|: +$$ \hbox{\verb|draw z0..z1{up}..z2{left}..z3..z4;|} $$ +The resulting shown in Figure~\ref{fig5} has the desired vertical and +horizontal directions at \verb|z1| and \verb|z2|, but it does not look +as smooth as the curve in Figure~\ref{fig2}. The reason is the large +discontinuity in curvature\index{curvature} at \verb|z1|. If it were +not for the specified direction at \verb|z1|, the MetaPost interpreter +would have chosen a direction designed to make the curvature above +\verb|z1| almost the same as the curvature below that point. + +\begin{figure}[htp] +$$ \includegraphics{mpman-6.mps} +$$ +\caption[A curve and the control polygon] + {The result of {\tt draw z0..z1\char`\{up\char`\}..z2\char`\{left\char`\}% + ..z3..z4}.} +\label{fig5} +\end{figure} + +How can the choice of directions at given points on a curve determine whether +the curvature will be continuous? The reason is that curves used in MetaPost +come from a family where a path is determined by its endpoints and the +directions there. Figures \ref{fig6} and~\ref{fig7} give a good idea of what +this family of curves is like. + +\begin{figure}[htp] +$$ \mathcenter{\includegraphics{mpman-7.mps}} \quad +\begin{verbatim} +beginfig(7) +for a=0 upto 9: + draw (0,0){dir 45}..{dir -10a}(6cm,0); +endfor +endfig; +\end{verbatim} +$$ +\caption{A curve family and the MetaPost instructions for generating it} +\label{fig6} +\end{figure} + +\begin{figure}[htp] +$$ \mathcenter{\includegraphics{mpman-8.mps}} \quad +\begin{verbatim} +beginfig(8) +for a=0 upto 7: + draw (0,0){dir 45}..{dir 10a}(6cm,0); +endfor +endfig; +\end{verbatim} +$$ +\caption{Another curve family with the corresponding MetaPost instructions} +\label{fig7} +\end{figure} + +Figures \ref{fig6} and~\ref{fig7} illustrate a few new MetaPost +features. The first is the {\tt +dir}\index{dir?\texttt{dir}}\label{Ddirop} operator that takes an angle +in degrees and generates a unit vector in that direction. Thus +\verb|dir 0| is equivalent to {\tt +right}\index{right?\texttt{right}}\label{Dright} and \verb|dir 90| is +equivalent to {\tt up}\index{up?\texttt{up}}\label{Dup}. There are also +predefined direction vectors {\tt +left}\index{left?\texttt{left}}\label{Dleft} and {\tt +down}\index{down?\texttt{down}}\label{Ddown} for {\tt dir 180} and {\tt +dir 270}. + +The direction +vectors given in \verb|{}| can be of any length, and they can come before a +point as well as after one. It is even possible for a path specification +to have directions given before and after a point. For example a path +specification containing +$$ \hbox{\verb|..{dir 60}(10,0){up}..|} $$ +produces a curve with a corner at $(10,0)$. + +Note that some of the curves in Figure~\ref{fig6} have points of +inflection\index{inflections}. This is necessary in order to produce +smooth curves in situations like Figure~\ref{fig3}a, but it is probably +not desirable when dealing with vertical and horizontal extreme points +as in Figure~\ref{fig8}a. If \verb|z1| is supposed to be the topmost +point on the curve, this can be achieved by using +\verb|...|\index{...?\texttt{...}} instead of \verb|..| in the path +specification as shown in Figure~\ref{fig8}b. The meaning of \verb|...| +is ``choose an inflection-free path between these points unless the +endpoint directions make this impossible.'' (It would be possible to +avoid inflections in Figure~\ref{fig6}, but not in Figure~\ref{fig7}). + +\begin{figure}[htp] +$$ {\mathcenter{\includegraphics{mpman-109.mps}} \atop + \hbox{\verb|draw z0{up}..z1{right}..z2{down}|}} + \quad + {\mathcenter{\includegraphics{mpman-209.mps}} \atop + \hbox{\verb|draw z0{up}...z1{right}...z2{down}|}} +$$ +\caption{Two {\tt draw} statements and the resulting curves.} +\label{fig8} +\end{figure} + +Another way to control a misbehaving path is to increase the +``tension''\index{tension} parameter. Using \verb|..| in a path +specification sets the tension parameter to the default value~1. If +this makes some part of a path a little too wild, we can selectively +increase the tension. If Figure~\ref{fig9}a is considered ``too wild,'' +a {\tt draw} statement of the following form increases the tension +between {\tt z1} and {\tt z2}: +$$ \hbox{\verb|draw z0..z1..tension 1.3..z2..z3|} $$ +This produces Figure~\ref{fig9}b. For an asymmetrical effect like +Figure~\ref{fig9}c, the \verb|draw| statement becomes +$$ \hbox{\verb|draw z0..z1..tension 1.5 and 1..z2..z3|} $$ +The tension parameter can be less than one, but it must be at least $3\over4$. + +\begin{figure}[htp] +$$ {\mathcenter{\includegraphics{mpman-110.mps}} \atop (a)} + \quad + {\mathcenter{\includegraphics{mpman-210.mps}} \atop (b)} + \quad + {\mathcenter{\includegraphics{mpman-310.mps}} \atop (c)} +$$ +\caption[Effects of changing the tension parameter] + {Results of {\tt draw z0..z1..tension} $\alpha$ {\tt and} $\beta$ + {\tt ..z2..z3} for various $\alpha$ and $\beta$: + (a)~$\alpha=\beta=1$; (b)~$\alpha=\beta=1.3$; + (c)~$\alpha=1.5$, $\beta=1$.} +\label{fig9} +\end{figure} + +MetaPost paths also have a parameter called +``curl''\index{curl?\texttt{curl}} that affects the ends of a path. In +the absence of any direction specifications, the first and last segments +of a non-cyclic path are approximately circular arcs as in the $c=1$ +case of Figure~\ref{fig10}. To use a different value for the curl +parameter, specify \verb|{curl c}| for some other value of $c$. Thus +$$ \hbox{\verb|draw z0{curl c}..z1..{curl c}z2|} $$ +sets the curl parameter for \verb|z0| and \verb|z2|. Small values of +the curl parameter reduce the curvature\index{curvature} at the +indicated path endpoints, while large values increase the curvature as +shown in Figure~\ref{fig10}. In particular, a curl value of zero makes +the curvature approach zero. + +\begin{figure}[htp] +$$ {\mathcenter{\includegraphics{mpman-111.mps}} \atop c=0} + \qquad + {\mathcenter{\includegraphics{mpman-211.mps}} \atop c=1} + \qquad + {\mathcenter{\includegraphics{mpman-311.mps}} \atop c=2} + \qquad + {\mathcenter{\includegraphics{mpman-411.mps}} \atop c=\infty} +$$ +\caption[Effects of changing the curl parameter] + {Results of {\tt draw z0\char`\{curl c\char`\}..z1..% + \char`\{curl c\char`\}z2} for various values + of the curl parameter~$c$.} +\label{fig10} +\end{figure} + +\subsection{Summary of Path Syntax} + +There are a few other features of MetaPost path syntax, but they are +relatively unimportant. Since \MF\ uses the same path syntax, +interested readers can refer to \cite[chapter 14]{kn:c}. The summary of +path syntax in Figure~\ref{sypath} includes everything discussed so far +including the \verb|--| and \verb|...| constructions which \cite{kn:c} +shows to be macros rather than primitives. A few comments on the +semantics are in order here: If there is a non-empty $\descr{direction +specifier}$ before a $\descr{path knot}$ but not after it, or vice +versa, the specified direction (or curl amount) applies to both the +incoming and outgoing path segments. A similar arrangement applies when +a $\descr{controls}$ specification gives only one $\descr{pair +primary}$. Thus +$$ \hbox{\verb|..controls (30,20)..|} $$ +is equivalent to +$$ \hbox{\verb|...controls (30,20) and (30,20)..|} $$ + +\begin{figure}[htp] +\begin{ctabbing} +$\descr{path expression} \rightarrow + \descr{path subexpression}$\\ +\qquad \= ${}\mid \descr{path subexpression} \descr{direction specifier}$\\ +\> ${}\mid \descr{path subexpression} \descr{path join}$ \verb|cycle|\\ +$\descr{path subexpression} \rightarrow + \descr{path knot}$\\ +\> ${}\mid \descr{path expression} \descr{path join} \descr{path knot}$\\ +$\descr{path join} \rightarrow + \hbox{\verb|--|}$\\ +\> ${}\mid \descr{direction specifier} \descr{basic path join} + \descr{direction specifier}$\\ +$\descr{direction specifier} \rightarrow + \descr{empty}$\\ +\> ${}\mid {}$\verb|{curl| $\descr{numeric expression}$\verb|}|\\ +\> ${}\mid {}$\verb|{|$\descr{pair expression}$\verb|}|\\ +\> ${}\mid {}$\verb|{|$\descr{numeric expression}$\verb|,|% + $\descr{numeric expression}$\verb|}|\\ +$\descr{basic path join} \rightarrow + \hbox{\verb|..|} + \mid \hbox{\verb|...|} + \mid \hbox{\verb|..|}\descr{tension}\hbox{\verb|..|} + \mid \hbox{\verb|..|}\descr{controls}\hbox{\verb|..|}$\\ +$\descr{tension} \rightarrow + \hbox{\verb|tension|}\descr{numeric primary}$\\ +\> ${}\mid \hbox{\verb|tension|}\descr{numeric primary} + \hbox{\verb|and|}\descr{numeric primary}$\\ +$\descr{controls} \rightarrow + \hbox{\verb|controls|}\descr{pair primary}$\\ +\> ${}\mid \hbox{\verb|controls|}\descr{pair primary} + \hbox{\verb|and|}\descr{pair primary}$ +\end{ctabbing} +\caption{The syntax for path construction} +\label{sypath} +\end{figure} + +A pair of coordinates like \verb|(30,20)| or a \verb|z| variable that +represents a coordinate pair is what Figure~\ref{sypath} calls a +$\descr{pair primary}$. A $\descr{path knot}$ is similar except that it +can take on other forms such as a path expression in parentheses. +Primaries and expressions of various types will be discussed in full +generality in Section~\ref{exprs}. + + +\section{Linear Equations} +\label{lin.eq} + +An important feature taken from \MF\ is the ability to solve linear +equations so that programs can be written in a partially declarative fashion. +For example, the MetaPost interpreter can read +$$ \hbox{\verb|a+b=3; 2a=b+3;|} $$ +and deduce that $a=2$ and $b=1$. The same equations can be written +slightly more compactly by stringing them together with multiple equal +signs: +$$ \hbox{\verb|a+b = 2a-b = 3;|} $$ +Whichever way you give the equations, you can then give the +command\index{show?\texttt{show}} +$$ \hbox{\tt show a,b;} $$ +to see the values of {\tt a} and {\tt b}. MetaPost responds by typing +$$\begin{verbatim} +>> 2 +>> 1 +\end{verbatim} +$$ + +Note that {\tt =}\index{=?\texttt{=}} is not an assignment operator; it +simply declares that the left-hand side equals the right-hand side. +Thus {\tt a=a+1} produces an error message complaining about an +``inconsistent equation\index{Inconsistent equation?\texttt{Inconsistent +equation}}.'' The way to increase the value of {\tt a} is to use the +assignment\index{assignment} operator {\tt :=}\index{:=?\texttt{:=}} as +follows: +$$ \hbox{\tt a:=a+1;} $$ +In other words, {\tt :=} is for changing existing values while {\tt =} is for +giving linear equations to solve. + +There is no restriction against mixing equations and assignment +operations as in the following example: +$$ \hbox{\tt a = 2; b = a; a := 3; c = a;} $$ +After the first two equations set {\tt a} and~{\tt b} equal to 2, the +assignment operation changes {\tt a} to~3 without affecting {\tt b}. +The final value of {\tt c} is 3 since it is equated to the new value of +{\tt a}. In general, an assignment operation is interpreted by first +computing the new value, then eliminating the old value from all +existing equations before actually assigning the new value. + +\subsection{Equations and Coordinate Pairs} + +MetaPost can also solve linear equations involving coordinate pairs. We have +already seen many trivial examples of this in the form of equations like +$$ \hbox{\verb|z1=(0,.2in)|} $$ +Each side of the equation must be formed by adding or subtracting +coordinate pairs and multiplying or dividing them by known numeric +quantities. Other ways of naming pair-valued variables will be +discussed later, but the ${\tt z}\descr{number}$\index{z convention?{\tt +z} convention} is convenient because it is an abbreviation for +$$ \hbox{\tt (x}\descr{number} \hbox{\tt, y}\descr{number}\hbox{\tt)} $$ +This makes it possible to give values to \verb|z| variables by giving +equations involving their coordinates. For instance, points {\tt z1}, +{\tt z2}, {\tt z3}, and~{\tt z6} in Figure~\ref{fig12} were initialized +via the following equations: +\begin{eqnarray*} + &&\hbox{\verb|z1=-z2=(.2in,0);|} \\ + &&\hbox{\verb|x3=-x6=.3in;|} \\ + &&\hbox{\verb|x3+y3=x6+y6=1.1in;|} +\end{eqnarray*} +Exactly the same points could be obtained by setting their values directly: +$$ \begin{verbatim} +z1=(.2in,0); z2=(-.2in,0); +z3=(.3in,.8in); z6=(-.3in,1.4in); +\end{verbatim} +$$ + +After reading the equations, the MetaPost interpreter knows the values +of {\tt z1}, {\tt z2}, {\tt z3}, and~{\tt z6}. The next step in the +construction of Figure~\ref{fig12} is to define points {\tt z4} and {\tt +z5} equally spaced along the line from {\tt z3} to {\tt z6}. Since this +operation comes up often, MetaPost has a special syntax for it. This +mediation construction\index{mediation}\index{[]?\texttt{[]}!mediation} +$$ \hbox{\verb|z4=1/3[z3,z6]|} $$ +means that {\tt z4} is $1\over3$ of the way from $z3$ to $z6$; i.e., +$$ {\tt z4}={\tt z3}+{1\over3}({\tt z6}-{\tt z3}). $$ +Similarly +$$ \hbox{\verb|z5=2/3[z3,z6]|} $$ +makes {\tt z5} $2\over3$ of the way from $z3$ to $z6$. + +\begin{figure}[htp] +$$ \begin{verbatim} +beginfig(13); +z1=-z2=(.2in,0); +x3=-x6=.3in; +x3+y3=x6+y6=1.1in; +z4=1/3[z3,z6]; +z5=2/3[z3,z6]; +z20=whatever[z1,z3]=whatever[z2,z4]; +z30=whatever[z1,z4]=whatever[z2,z5]; +z40=whatever[z1,z5]=whatever[z2,z6]; +draw z1--z20--z2--z30--z1--z40--z2; +pickup pencircle scaled 1pt; +draw z1--z2; +draw z3--z6; +endfig; +\end{verbatim} +\quad \mathcenter{\includegraphics{mpman-13.mps}} +$$ +\caption[MetaPost code and figure using linear equations] + {MetaPost commands and the resulting figure. Point labels have been + added to the figure for clarity.} +\label{fig12} +\end{figure} + +Mediation can also be used to say that some point is at an unknown +position along the line between two known points. For instance, we +could a introduce new variable {\tt aa} and write something like +$$ \hbox{\verb|z20=aa[z1,z3];|} $$ +This says that {\tt z20} is some unknown fraction {\tt aa} of the way +along the line between {\tt z1} and {\tt z3}. Another such equation +involving a different line is sufficient to fix the value of {\tt z20}. +To say that {\tt z20} is at the intersection of the {\tt z1}-{\tt z3} +line and the {\tt z2}-{\tt z4} line, introduce another variable {\tt ab} +and set +$$ \hbox{\verb|z20=ab[z2,z4];|} $$ +This allows MetaPost to solve for {\tt x20}, {\tt y20}, {\tt aa}, and {\tt ab}. + +It is a little painful to keep thinking up new names like {\tt aa} and +{\tt ab}. This can be avoided by using a special feature called {\tt +whatever}\index{whatever?\texttt{whatever}}\label{Dwhatev}. This macro +generates a new anonymous variable each time it appears. Thus the +statement +$$ \hbox{\verb|z20=whatever[z1,z3]=whatever[z2,z4]|} $$ +sets {\tt z20} as before, except it uses {\tt whatever} to generate two +{\em different\/} anonymous variables instead of {\tt aa} and {\tt ab}. +This is how Figure~\ref{fig12} sets {\tt z20}, {\tt z30}, and +{\tt z40}. + +\subsection{Dealing with Unknowns} + +A system of equations such as those used in Figure~\ref{fig12} can be given in +any order as long as all the equations are linear and all the variables can +be determined before they are needed. This means that the equations +\begin{eqnarray*} + && \hbox{\verb|z1=-z2=(.2in,0);|}\\ + && \hbox{\verb|x3=-x6=.3in;|}\\ + && \hbox{\verb|x3+y3=x6+y6=1.1in;|}\\ + && \hbox{\verb|z4=1/3[z3,z6];|}\\ + && \hbox{\verb|z5=2/3[z3,z6];|} +\end{eqnarray*} +suffice to determine {\tt z1} through {\tt z6}, no matter what order the +equations are given in. On the other hand +$$ \hbox{\verb|z20=whatever[z1,z3]|} $$ +is legal only when a known value has previously been specified for the difference +${\tt z3}-{\tt z1}$, because the equation is equivalent +to\index{mediation} +$$ \hbox{\verb|z20 = z1 + whatever*(z3-z1)|} $$ +and the linearity requirement disallows multiplying unknown components +of ${\tt z3}-{\tt z1}$ by the anonymous unknown result of {\tt +whatever}. The general rule is that you cannot multiply two unknown +quantities or divide by an unknown quantity, nor can an unknown quantity +be used in a {\tt draw} statement. Since only linear equations are +allowed, the MetaPost interpreter can easily solve the equations and +keep track of what values are known. + +The most natural way to ensure that MetaPost can handle an expression like +$$ \hbox{\verb|whatever[z1,z3]|} $$ +is to ensure that {\tt z1} and {\tt z3} are both known. However this is not +actually required since MetaPost may be able to deduce a known value for +${\tt z3}-{\tt z1}$ before either of {\tt z1} and {\tt z3} are known. +For instance, MetaPost will accept the equations +$$ \hbox{\verb|z3=z1+(.1in,.6in); z20=whatever[z1,z3];|} $$ +but it will not be able to determine any of the components of {\tt z1}, +{\tt z3}, or {\tt z20}. + +These equations do give partial information about {\tt z1}, {\tt z3}, +and {\tt z20}. A good way to see this is to give another equation such as +$$ \hbox{\verb|x20-x1=(y20-y1)/6;|} $$ +This produces the error message ``{\tt ! Redundant +equation}\index{Redundant equation?\texttt{Redundant equation}}.'' +MetaPost assumes that you are trying to tell it something new, so it +will usually warn you when you give a redundant equation. If the new +equation had been +$$ \hbox{\verb|(x20-x1)-(y20-y1)/6=1in;|} $$ +the error message would have been\index{Inconsistent +equation?\texttt{Inconsistent equation}} +$$ \hbox{\verb|! Inconsistent equation (off by 71.99979).|} $$ +This error message illustrates +roundoff\index{roundoff error} error in MetaPost's linear equation solving +mechanism. Roundoff error +is normally not a serious problem, but it is likely to cause trouble if you are +trying to do something like find the intersection of two lines that are almost +parallel. + + +\section{Expressions} +\label{exprs} + +It is now time for a more systematic view of the MetaPost language. We +have seen that there are numeric quantities and coordinate pairs, and +that these can be combined to specify paths for {\tt draw} statements. +We have also seen how variables can be used in linear equations, but we +have not discussed all the operations and data types that can be used in +equations. + +It is possible to experiment with expressions involving any of the data types +mentioned below by using the statement\index{show?\texttt{show}}\label{Dshow} +$$ {\tt show}\, \descr{expression} $$ +to ask MetaPost to print a symbolic representation of the value of each +expression. For known numeric values, each is printed on a new line +preceded by ``\verb|>> |''. Other types of result are printed similarly, +except that complicated values are sometimes not printed on standard +output. This produces a reference to the transcript +file\index{files!transcript} that looks like this: +$$ \hbox{\verb|>> picture (see the transcript file)|} $$ +If you want to the full results of {\tt show} statements to be printed +on your terminal, assign a positive value to the internal\index{internal +variables} variable\index{variables!internal} {\tt +tracingonline}\index{tracingonline?\texttt{tracingonline}}\label{Dtonline}. + +\subsection{Data Types} + +MetaPost actually has ten basic data types\index{types}: numeric, +pair, path, transform, (rgb)color, cmykcolor, string, boolean, picture, and +pen. Let us consider these one at a time beginning with the numeric +type. + +Numeric\index{numeric type} quantities in MetaPost are represented in fixed +point arithmetic\index{arithmetic} as +integer multiples of $1\over65536$. 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?\texttt{warningcheck}}\label{Dwarncheck} +to zero suppresses the warning messages about large numeric quantities. + +The pair\index{pair type} type is represented as a pair of numeric +quantities. We have seen that pairs are used to give coordinates in +{\tt draw} statements. Pairs can be added, subtracted, used in +mediation expressions, or multiplied or divided by numerics. + +Paths\index{path type} have already been discussed in the context of {\tt draw} +statements, but +that discussion did not mention that paths are first-class objects that can be +stored and manipulated. A path represents a straight or curved line that is +defined parametrically. + +Another data type represents an arbitrary affine +transformation\index{transform type}. A {\em transform\/} can be any +combination of rotating, scaling, slanting, and shifting. If ${\tt +p}=(p_x,p_y)$ is a pair and {\tt T} is a +transform,\index{transformed?\texttt{transformed}} +$$ \hbox{\tt p transformed T} $$ +is a pair of the form +$$ (t_x+t_{xx}p_x+t_{xy}p_y, t_y+t_{yx}p_x+t_{yy}p_y), $$ +where the six numeric quantities $(t_x,t_y,t_{xx},t_{xy},t_{yx},t_{yy})$ +determine {\tt T}. Transforms can also be applied to paths, pictures, pens, +and transforms. + +The color\index{color type} type is like the pair type, except +that it has three components instead of two and each component is +normally between 0 and 1. Like pairs, colors can be added, +subtracted, used in mediation expressions, or multiplied or divided +by numerics. Colors can be specified in terms of the predefined +constants \ttindex{black}\label{Dblack}, \ttindex{white}\label{Dwhite}, +\ttindex{red}\label{Dred}, \ttindex{green}\label{Dgreen}, +\ttindex{blue}\label{Dblue}, or the red, green, and +blue components can be given explicitly. Black is {\tt (0,0,0)} and +white is {\tt (1,1,1)}. A level of gray such as {\tt (.4,.4,.4)} can also be +specified as {\tt 0.4white}. Although color typed variables may be +any ordered triplet, when adding an object to a picture, MetaPost will +convert its color by clipping each component between 0 and 1. For +example, MetaPost will output the color (1,2,3) as (1,1,1). +MetaPost solves linear equations involving +colors the same way it does for pairs. The type `rgbcolor' is an alias of +type `color'. + +The cmykcolor\index{cmykcolor type} type is similar +to the color type except that it has four components instead of +three. This type is used to specify colors by their cyan, magenta, +yellow, and black components explicitly. Because CMYK colors deal with +pigments instead of light rays, the color white would be expressed as +{\tt (0,0,0,0)} and black as {\tt (0,0,0,1)}. In theory, the colors +{\tt ($c$,$m$,$y$,1)} and {\tt (1,1,1,$k$)} should result in black for +any values of $c$, $m$, $y$ and~$k$, too. But in practice, this is +avoided since it is a waste of colored ink and can lead to +unsatisfactory results. + +A string\index{string type} represents a sequence of characters. +String constants\index{string constants} are given +in double quotes \hbox{\verb|"like this"|}. String constants cannot contain +double quotes or newlines, but there is a way to construct a string containing +any sequence of eight-bit characters. + +\label{Dscantokens} +Conversion from strings to other types, notably numeric, can be accomplished by +the {\tt scantokens}\index{scantokens?\texttt{scantokens}} primitive: +\begin{center}\texttt{n := scantokens(}\textit{str}\texttt{);}\end{center} +More generally, \texttt{scantokens} parses a string into a token +sequence, as if MetaPost had read it as input. + +The boolean\index{boolean type} type has the constants {\tt +true}\index{true?\texttt{true}}\label{Dtrue} and {\tt +false}\index{false}\label{Dfalse} and the operators {\tt +and}\index{and?\texttt{and}}\label{Dand}, {\tt +or}\index{or?\texttt{or}}\label{Dor}, {\tt +not}\index{not?\texttt{not}}\label{Dnot}. The relations \verb|=| and +\verb|<>|\index{<>?\texttt{<>}}\label{Dcmpar} test objects of any type +for equality and inequality\index{inequality}. +Comparison\index{comparison} relations \verb|<|\index{<?\texttt{<}}, +\verb|<=|\index{<=?\texttt{<=}}, \verb|>|\index{>?\texttt{>}}, and +\verb|>=|\index{>=?\texttt{>=}} are defined lexicographically for +strings and in the obvious way for numerics. Ordering relations are +also defined for booleans, pairs, colors, and transforms, but the +comparison rules are not worth discussing here. + +The picture\index{picture type} data type is just what the name implies. +Anything that can be drawn in MetaPost can be stored in a picture +variable. In fact, the {\tt draw}\index{draw?\texttt{draw}} statement +actually stores its results in a special picture variable called {\tt +currentpicture}\index{currentpicture?\texttt{currentpicture}}. Pictures +can be added to other pictures and operated on by transforms. + +Finally, there is a data type called a pen\index{pen type}. The main +function of pens in MetaPost is to determine line thickness, but they +can also be used to achieve calligraphic effects. The +statement\index{pickup?\texttt{pickup}}\label{Dpickup} +$$ {\tt pickup\ }\descr{pen expression} $$ +causes the given pen to be used in subsequent {\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 ten basic +types, but most of the operations fit into a fairly simple syntax with +four levels of precedence as shown in Figure~\ref{syexpr}. There are +primaries\index{primary?\tdescr{primary}}, +secondaries\index{secondary?\tdescr{secondary}}, +tertiaries\index{tertiary?\tdescr{tertiary}}, and +expressions\index{expression?\tdescr{expression}} of each of the basic +types, so the syntax rules could be specialized to deal with items such +as \tdescr{numeric primary}, \tdescr{boolean tertiary}, etc. This +allows the result type for an operation to depend on the choice of +operator and the types of its operands. For example, the {\tt <} +relation is a \tdescr{tertiary binary} that can be applied to a +\tdescr{numeric expression} and a \tdescr{numeric tertiary} to give a +\tdescr{boolean expression}. The same operator can accept other operand +types such as \tdescr{string expression} and \tdescr{string tertiary}, +but an error message results if the operand types do not match. + +\begin{figure}[htp] +\begin{ctabbing} +$\tt \descr{primary} \rightarrow \descr{variable}$\\ +$\tt \qquad \;|\; \hbox{\tt (}\descr{expression}\hbox{\tt )}$\\ +$\tt \qquad \;|\; \descr{nullary op}$\\ +$\tt \qquad \;|\; \descr{of operator} \descr{expression} + of \descr{primary}$\\ +$\tt \qquad \;|\; \descr{unary op} \descr{primary}$\\ +$\tt \descr{secondary} \rightarrow \descr{primary}$\\ +$\tt \qquad \;|\; \descr{secondary} \descr{primary binop} \descr{primary}$\\ +$\tt \descr{tertiary} \rightarrow \descr{secondary}$\\ +$\tt \qquad \;|\; \descr{tertiary} \descr{secondary binop} + \descr{secondary}$\\ +$\tt \descr{expression} \rightarrow \descr{tertiary}$\\ +$\tt \qquad \;|\; \descr{expression} \descr{tertiary binop} + \descr{tertiary}$ +\end{ctabbing} +\caption{The overall syntax rules for expressions} +\index{unary op?\tdescr{unary op}} \index{nullary op?\tdescr{nullary op}} +\index{primary binop?\tdescr{primary binop}} +\index{secondary binop?\tdescr{secondary binop}} +\index{tertiary binop?\tdescr{tertiary binop}} +\label{syexpr} +\end{figure} + +The multiplication and division operators {\tt *}\label{Dmldiv} and~{\tt +/} are examples of what Figure~\ref{syexpr} calls a \tdescr{primary +binop}. Each can accept two numeric operands or one numeric operand and +one operand of type pair or color. The exponentiation operator +\verb|**|\index{**?\texttt{**}}\index{exponentiation}\label{Dpow} is a +\tdescr{primary binop} that requires two numeric operands. Placing this +at the same level of precedence as multiplication and division has the +unfortunate consequence that \verb|3*a**2| means $(3a)^2$, not +$3(a^2)$\index{parsing irregularities}. Since unary +negation\label{Dneg} applies at the primary level, it also turns out +that \verb|-a**2| means $(-a)^2$. Fortunately, subtraction has lower +precedence so that \verb|a-b**2| does mean $a-(b^2)$ instead of +$(a-b)^2$. + +Another \tdescr{primary binop} is the {\tt +dotprod}\index{dotprod?\texttt{dotprod}}\label{Ddprod} operator that +computes the vector dot product of two pairs. For example, {\tt z1 +dotprod z2} is equivalent to {\tt x1*x2 + y1*y2}. + +The additive operators {\tt +} and {\tt -}\label{Dadd} are +\tdescr{secondary binops} that operate on numerics, pairs, or colors and +produce results of the same type. Other operators that fall in this +category are ``Pythagorean addition'' +\verb|++|\index{++?\texttt{++}}\label{Dpyadd} and ``Pythagorean +subtraction'' \verb|+-+|\index{+-+?\texttt{+-+}}\label{Dpysub}: +\verb|a++b| means $\sqrt{a^2+b^2}$ and \verb|a+-+b| means +$\sqrt{a^2-b^2}$. There are too many other operators to list here, but +some of the most important are the boolean operators {\tt +and}\index{and?\texttt{and}} and {\tt or}\index{or?\texttt{or}}. The +{\tt and} operator is a \tdescr{primary binop} and the {\tt or} operator +is a \tdescr{secondary binop}. + +The basic operations on strings are concatenation\index{concatenation}, +substring construction and calculating the length of a string. +The \tdescr{tertiary binop} \verb|&|\index{&?\texttt{\&}}\label{Damp} +implements concatenation; e.g., +$$ \hbox{\verb|"abc" & "de"|} $$ +produces the string \verb|"abcde"|. The {\tt +length}\index{length?\texttt{length}}\label{DlengthString} operator +returns the number of characters in a string if the argument is a +\tdescr{string primary}; e.g., +$$ \hbox{\verb|length "abcde"|} $$ +returns \verb|5|. Another application of the {\tt length} operator is +discussed on p.\ \pageref{Dlength}. For substring construction, the +\tdescr{of operator} {\tt substring}\index{substring +of?\texttt{substring of}}\label{Dsubstr} is used like this: +$$ {\tt substring}\, \descr{pair expression} \,{\tt of}\, \descr{string primary} $$ +The \tdescr{pair expression} determines what part of the string to +select. For this purpose, the string is indexed\index{indexing} so that +integer positions fall {\em between\/} characters. Pretend the string +is written on a piece of graph paper so that the first character +occupies $x$~coordinates between zero and one and the next character +covers the range $1\le x\le2$, etc. Thus the string \verb|"abcde"| +should be thought of like this +$$ \includegraphics{mpman-14.mps} $$ +and {\tt substring (2,4) of "abcde"} is {\tt "cd"}. This takes a little +getting used to but it tends to avoid annoying ``off by one'' errors. + +Some operators take no arguments at all. An example of what +Figure~\ref{syexpr} calls a \tdescr{nullary op} is {\tt +nullpicture}\index{nullpicture?\texttt{nullpicture}}\label{Dnlpic} which +returns a completely blank picture. + +The basic syntax in Figure~\ref{syexpr} only covers aspects of the +expression syntax that are relatively type-independent. For instance, +the complicated path syntax given in Figure~\ref{sypath} gives +alternative rules for constructing a \tdescr{path expression}. An +additional rule\index{path knot?\tdescr{path knot}} +$$ \descr{path knot} \rightarrow \descr{pair tertiary} \;|\; \descr{path tertiary} +$$ +explains the meaning of \tdescr{path knot} in Figure~\ref{sypath}. This means +that the path expression +$$ \hbox{\verb|z1+(1,1){right}..z2|} $$ +does not need parentheses around {\tt z1+(1,1)}. + +\subsection{Fractions, Mediation, and Unary Operators} + +Mediation\index{mediation} expressions do not appear in the basic expression +syntax of Figure~\ref{syexpr}. Mediation expressions are parsed at the +\tdescr{primary} level, so the general rule for constructing them is +$$ \descr{primary} \rightarrow + \descr{numeric atom} \hbox{\tt [} \descr{expression} + \hbox{\tt ,} \descr{expression} \hbox{\tt ]} +$$ +where each \tdescr{expression} can be of type numeric, pair, or color. +The \tdescr{numeric atom}\index{numeric atom?\tdescr{numeric atom}} in a +mediation expression is an extra simple type of \tdescr{numeric primary} +as shown in Figure~\ref{synprim}. The meaning of all this is that the +initial parameter in a mediation expression needs to be parenthesized +when it is not just a variable, a positive number, or a positive +fraction. For example,\index{parsing irregularities} +$$ \hbox{\tt -1[a,b]} \quad {\rm and}\quad \hbox{\tt (-1)[a,b]} $$ +are very different: the former is $-b$ since it is equivalent to +{\tt -(1[a,b])}; the latter is $a-(b-a)$ or $2a-b$. + +\begin{figure}[htp] +\begin{ctabbing} +$\tt \descr{numeric primary} \rightarrow \descr{numeric atom}$\\ +$\tt \qquad \;|\; \descr{numeric atom}\hbox{\tt [} + \descr{numeric expression}\hbox{\tt ,}\descr{numeric expression}\hbox{\tt ]}$\\ +$\tt \qquad \;|\; \descr{of operator} \descr{expression} of \descr{primary}$\\ +$\tt \qquad \;|\; \descr{unary op} \descr{primary}$\\ +$\tt \descr{numeric atom} \rightarrow \descr{numeric variable}$\\ +$\tt \qquad \;|\; \descr{number or fraction}$\\ +$\tt \qquad \;|\; \hbox{\tt (}\descr{numeric expression}\hbox{\tt )}$\\ +$\tt \qquad \;|\; \descr{numeric nullary op}$\\ +$\tt \descr{number or fraction} \rightarrow \descr{number} + \hbox{\tt /}\descr{number}$\\ +$\tt \qquad \;|\; \descr{number not followed by + `$\hbox{\tt /}\descr{number}$'}$ +\end{ctabbing} +\caption{Syntax rules for numeric primaries} +\label{synprim} +\end{figure} + +A noteworthy feature of the syntax rules in Figure~\ref{synprim} is that +the {\tt /}\index{fractions} operator binds most tightly when its +operands are numbers. Thus {\tt 2/3} is a \tdescr{numeric +atom}\index{numeric atom?\tdescr{numeric atom}}\index{parsing +irregularities} while {\tt (1+1)/3} is only a \tdescr{numeric +secondary}. Applying a \tdescr{unary op} such as {\tt +sqrt}\index{sqrt?\texttt{sqrt}}\label{Dsqrt} makes the difference clear: +$$ \hbox{\tt sqrt 2/3} $$ +means $\sqrt{2\over3}$ while +$$ \hbox{\tt sqrt(1+1)/3} $$ +means $\sqrt 2/3$. Operators such as {\tt sqrt} can be written in +standard functional notation, but it is often unnecessary to +parenthesize the argument. This applies to any function that is parsed +as a \tdescr{unary op}. For instance {\tt +abs(x)}\index{abs?\texttt{abs}}\label{Dabs} and {\tt abs x} both compute +the absolute value of {\tt x}. The same holds for the {\tt +round}\index{round?\texttt{round}}\label{Dround}, {\tt +floor}\index{floor?\texttt{floor}}\label{Dfloor}, {\tt +ceiling}\index{ceiling?\texttt{ceiling}}\label{Dceil}, {\tt +sind}\index{sind?\texttt{sind}}\label{Dsind}, and {\tt +cosd}\index{cosd?\texttt{cosd}}\label{Dcosd} functions. The last two of +these compute trigonometric functions of angles in degrees. + +Not all unary operators take numeric arguments and return numeric +results. For instance, the {\tt abs}\index{abs?\texttt{abs}} operator +can be applied to a pair to compute the Euclidean length of a vector. +Applying the {\tt +unitvector}\index{unitvector?\texttt{unitvector}}\label{Duvec} operator +to a pair produces the same pair rescaled so that its Euclidean length +is~1. The {\tt decimal}\index{decimal?\texttt{decimal}}\label{Ddecop} +operator takes a number and returns the string representation. The {\tt +angle}\index{angle?\texttt{angle}}\label{Dangle} operator takes a pair +and computes the two-argument arctangent; i.e., {\tt angle} is the +inverse of the {\tt dir} operator that was discussed in +Section~\ref{tenscurl}. There is also an operator {\tt +cycle}\index{cycle?\texttt{cycle}}\label{Dcycop} that takes a +\tdescr{path primary} and returns a boolean result indicating whether +the path is a closed curve. + +There is a whole class of other operators that classify expressions and +return boolean results. A type name such as {\tt +pair}\index{pair?\texttt{pair}} can operate on any type of +\tdescr{primary} and return a boolean result indicating whether the +argument is a {\tt pair}\label{Dpairop}. Similarly, each of the +following can be used as a unary operator: +{\tt numeric}\index{numeric?\texttt{numeric}}\label{Dnumop}, +{\tt boolean}\index{boolean?\texttt{boolean}}\label{Dboolop}, +{\tt cmykcolor}\index{cmykcolor?\texttt{cmykcolor}}\label{Dccolrop}, +{\tt color}\index{color?\texttt{color}}\label{Dcolrop}, +{\tt string}\index{string?\texttt{string}}\label{Dstrgop}, +{\tt transform}\index{transform?\texttt{transform}}\label{Dtrnfop}, +{\tt path}\index{path?\texttt{path}}\label{Dpathop}, +{\tt pen}\index{pen?\texttt{pen}}\label{Dpenop}, +{\tt picture}\index{picture?\texttt{picture}}\label{Dpictop}, and +{\tt rgbcolor}\index{rgbcolor?\texttt{rgbcolor}}\label{Drcolrop}. +Besides just +testing the type of a \tdescr{primary}, you can use the {\tt +known}\index{known?\texttt{known}}\label{Dknown} and {\tt +unknown}\index{unknown?\texttt{unknown}}\label{Dunknwn} operators to +test if it has a completely known value. + +Even a number can behave like an operator in some contexts. This refers +to the trick that allows {\tt 3x}\index{multiplication, implicit} and +{\tt 3cm} as alternatives to {\tt 3*x} and {\tt 3*cm}. The rule is that +a \tdescr{number or fraction} that is not followed by {\tt +}, {\tt -}, +or another \tdescr{number or fraction} can serve as a \tdescr{primary +binop}. Thus {\tt 2/3x}\index{parsing irregularities} is two thirds of +{\tt x} but {\tt (2)/3x} is $2\over3x$ and {\tt 3 3} is illegal. + +There are also operators for extracting numeric subfields from pairs, +colors, cmykcolors, and even transforms. If {\tt p} is a \tdescr{pair +primary}, {\tt xpart p}\index{xpart?\texttt{xpart}}\label{Dxprt} and +{\tt ypart p}\index{ypart?\texttt{ypart}}\label{Dyprt} extract its components so that +$$ \hbox{\tt (xpart p, ypart p)} $$ is equivalent to~{\tt p} even if +{\tt p} is an unknown pair that is being used in a linear equation. +Similarly, a color {\tt c} is equivalent +to\index{redpart?\texttt{redpart}}% +\index{greenpart?\texttt{greenpart}}% +\index{bluepart?\texttt{bluepart}}\label{Drgbprt} +$$ \hbox{\tt (redpart c, greenpart c, bluepart c)}. $$ +For a cmykcolor {\tt c}, the components are% +\index{cyanpart?\texttt{cyanpart}}% +\index{magentapart?\texttt{magentapart}}% +\index{yellowpart?\texttt{yellowpart}}% +\index{blackpart?\texttt{blackpart}}\label{Dcmykprt} +$$ \hbox{\tt (cyanpart c, magentapart c, yellowpart c, blackpart c)} $$ +and for a greyscale color {\tt c}, there is only one component% +\index{greypart?\texttt{greypart}}\label{Dgreyprt}% +$$ \hbox{\tt greypart c}. $$ +All color component operators are discussed in more detail in +section~\ref{piccomp}. Part specifiers for transforms are discussed +in section~\ref{transsec}. + + +\section{Variables} +\label{vars} + +MetaPost allows compound variable names such as {z.a}, {\tt x2r}, {\tt y2r}, +and {\tt z2r}, where {\tt z2r} means {\tt (x2r,y2r)} and {\tt z.a} means +{\tt (x.a,y.a)}. In fact there is a broad class of suffixes such that +{\tt z}\tdescr{suffix}\index{suffix?\tdescr{suffix}} means +$$ (x\descr{suffix},\, y\descr{suffix}). $$ +Since a \tdescr{suffix} is composed of tokens, it is best to begin with a few +comments about tokens. + +\subsection{Tokens} + +A MetaPost input file is treated as a sequence of numbers, string +constants, and symbolic tokens\index{tokens}\index{tokens!symbolic}. A +number consists of a sequence of digits possibly containing a decimal +point. Technically, the minus sign in front of a negative number is a +separate token. Since MetaPost uses fixed point +arithmetic\index{arithmetic}, it does not understand exponential +notation such as {\tt 6.02E23}. MetaPost would interpret this as the +number 6.02, followed by the symbolic token {\tt E}, followed by the +number~23. + +Anything between a pair of double quotes {\tt "} is a +string constant\index{string constants}. It is +illegal for a string constant to start on one line and end on a later line. +Nor can a string constant contain double quotes {\tt "} or anything other than +printable ASCII characters. + +Everything in a line of input other than numbers and string constants is broken +into symbolic tokens\index{tokens!symbolic}. A symbolic token is a sequence of +one or more similar characters, where characters are ``similar'' if they occur +on the same row of Table~\ref{classes}. + +\begin{table} +$$\begin{tabular}{c} +\verb|ABCDEFGHIJKLMNOPQRSTUVWXYZ_abcdefghijklmnopqrstuvwxyz|\\ +{\tt :<=>|}\\ +\verb|#&@$|\\ +\verb|/*\|\\ +{\tt +-}\\ +{\tt !?}\\ +{\tt '`}\\ +\verb|^~|\\ +\verb|{}|\\ +{\tt [}\\ +{\tt ]}\\ +\end{tabular} +$$ +\caption{Character classes for tokenization} +\label{classes} +\end{table} + +Thus \verb|A_alpha| and {\tt +-+} are symbolic tokens but {\tt !=} is +interpreted as two tokens and {\tt x34} is a symbolic token followed by +a number. Since the brackets {\tt [} and {\tt ]} are listed on lines by +themselves, the only symbolic tokens involving them are {\tt [}, {\tt +[[}, {\tt [[[}, etc.\ and {\tt ]}, {\tt ]]}, etc. + +Some characters are not listed in Table~\ref{classes} because they need +special treatment. The four characters {\tt ,;()} are ``loners'': each +comma, semicolon, or parenthesis is a separate token +even when they occur consecutively. Thus {\tt (())} is four tokens, not +one or two. The percent sign is very special because it introduces +comments\index{comments}. The percent sign and everything after it up +to the end of the line are ignored. + +Another special character is the period. Two or more periods +together form a symbolic token, but a single period is ignored, and a period +preceded or followed by digits is part of a number Thus {\tt ..} +and {\tt ...} are symbolic tokens while {\tt a.b} is just two tokens {\tt a} +and {\tt b}. It conventional to use periods to separate tokens in this fashion +when naming a variable that is more than one token long. + +\subsection{Variable Declarations} +\label{vardecl} + +A variable name is a symbolic token or a sequence of symbolic tokens. +Most symbolic tokens are legitimate variable names, but anything with a +predefined meaning like {\tt draw}, {\tt +}, or {\tt ..} is disallowed; +i.e., variable names cannot be macros or MetaPost primitives. This +minor restriction allows an amazingly broad class of variable names: +{\tt alpha}, \verb|==>|, \verb|@&#$&|, and \verb|~~| are all legitimate +variable names. Such symbolic tokens without special meanings are +called {\em tags}\index{tags}. + +A variable name can be a sequence of tags like {\tt f.bot} or {\tt +f.top}. The idea is to provide some of the functionality of Pascal +records or C structures. It is also possible to simulate arrays by +using variable names that contain numbers as well as symbolic tokens. +For example, the variable name {\tt x2r} consists of the tag {\tt x}, +the number 2, and the tag~{\tt r}. There can also be variables named +{\tt x3r} and even {\tt x3.14r}. These variables can be treated as an +array\index{arrays} via constructions like {\tt x[i]r}, where {\tt i} +has an appropriate numeric value. The overall syntax for variable names +is shown in Figure~\ref{syvar}. + +\begin{figure}[htp] +\begin{ctabbing} +$\tt \descr{variable} \rightarrow \descr{tag}\descr{suffix}$\\ +$\tt \descr{suffix} \rightarrow \descr{empty} \;|\; + \descr{suffix}\descr{subscript} \;|\; \descr{suffix}\descr{tag}$\\ +$\tt \descr{subscript} \rightarrow \descr{number} \;|\; + \hbox{\tt [}\descr{numeric expression}\hbox{\tt ]}$ +\end{ctabbing} +\caption{The syntax for variable names.} +\index{suffix?\tdescr{suffix}}\index{subscript?\tdescr{subscript}} +\label{syvar} +\end{figure} + +Variables like {\tt x2} and {\tt y2} take on numeric values by default, so we +can use the fact that {\tt z}\tdescr{suffix} is an abbreviation for\index{z convention?{\tt z} convention}\label{Dzconv} +$$ (x\descr{suffix},\, y\descr{suffix}) $$ +to generate pair-valued variables when needed. It turns out that the +{\tt beginfig}\index{beginfig?\texttt{beginfig}} macro wipes out +pre-existing values variables that begin with the tags {\tt x} or {\tt +y} so that {\tt beginfig} \ldots\ {\tt endfig} blocks do not interfere +with each other when this naming scheme is used. In other words, +variables that start with {\tt x}, {\tt y}, {\tt z} are +local\index{variables!local}\index{locality} to the figure they are used +in. General mechanisms for making variables local will be discussed in +Section~\ref{grsec}. + +Type declarations\index{declarations}\index{type declarations} +make it possible to use almost any naming scheme while still +wiping out any previous value that might cause interference. For example, the +declaration +$$ \hbox{\tt pair pp, a.b;} $$ +makes {\tt pp} and {\tt a.b} unknown pairs. Such a declaration is not +strictly local since {\tt pp} and {\tt a.b} are not automatically +restored to their previous values at the end of the current figure. Of +course, they are restored to unknown pairs if the declaration is +repeated. + +Declarations work the same way for any of the other nine types: numeric, +path, transform, color, cmykcolor, string, boolean, picture, and pen. The +only restriction is that you cannot give explicit numeric subscripts in +a variable declaration. Do not give the illegal declaration +$$ \hbox{\tt numeric q1, q2, q3;} $$ +use the generic subscript\index{subscript!generic} symbol +{\tt []}\index{arrays}\index{[]?\texttt{[]}!array} +instead, to declare the whole array: +$$ \hbox{\tt numeric q[];} $$ +You can also declare ``multidimensional'' arrays\index{arrays!multidimensional}. +After the declaration +$$ \hbox{\tt path p[]q[], pq[][];} $$ +{\tt p2q3} and {\tt pq1.4 5} are both paths. + +Internal\index{internal variables}\index{variables!internal} variables +like {\tt tracingonline} cannot be declared in the normal fashion. All +the internal variables discussed in this manual are predefined and do +not have to be declared at all, but there is a way to declare that a +variable should behave like a newly-created internal variable. The +declaration is {\tt + newinternal}\index{newinternal?\texttt{newinternal}}\label{Dnewint} +followed by an optional type specifier \texttt{numeric}\index{internal + variables!\texttt{numeric}}\index{variables!internal!\texttt{numeric}} +or \texttt{string}\index{internal + variables!\texttt{string}}\index{variables!internal!\texttt{string}} +and a list of symbolic tokens. For example, +$$\begin{verbatim} +newinternal numeric n, m; +newinternal string s, t; +newinternal num; +\end{verbatim} +$$ +are valid declarations that declare three internal numeric variables +\texttt{n}, \texttt{m}, and~\texttt{num} and two internal string +variables \texttt{s} and~\texttt{t}. + +Internal variables always have known values, and these values can only +be changed by using the assignment\index{assignment} operator +{\tt:=}\index{:=?\texttt{:=}}. Internal numeric variables are initially +zero and internal string variables are initially the empty +string~\verb|""|, except that the Plain\index{Plain macros} macro +package gives some of the variables different initial values. (The +Plain macros are normally preloaded automatically as explained in +Section~\ref{intro}.) + +Internal string variables have been introduced in MetaPost +version~1.200. For backwards compatibility, if the type specifier is +missing, internal variables default to a \texttt{numeric}\index{internal + variables!\texttt{numeric}}\index{variables!internal!\texttt{numeric}} +type, as in the last example. The declarations \texttt{newinternal + numeric;} and \texttt{newinternal string;} are invalid and throw an +error. + + +\section{Integrating Text and Graphics} +\label{text} + +MetaPost has a number of features for including labels and other +text\index{text and graphics} in the figures it generates. The simplest +way to do this is to use the {\tt +label}\index{label?\texttt{label}}\label{Dlabel} statement\index{label +suffix?\tdescr{label suffix}} +$$ {\tt label}\descr{label suffix} \hbox{\tt (} + \descr{string or picture expression} \hbox{\tt,}\, \descr{pair expression} + \hbox{\tt );} +$$ +The \tdescr{string or picture expression} gives the label and the +\tdescr{pair expression} says where to put it. The \tdescr{label +suffix} can be \tdescr{empty} in which case the label is just centered +on the given coordinates. If you are labeling some feature of a diagram +you probably want to offset the label slightly to avoid overlapping. +This is illustrated in Figure~\ref{fig16} where the {\tt "a"} label is +placed above the midpoint of the line it refers to and the {\tt "b"} +label is to the left of the midpoint of its line. This is achieved by +using {\tt label.top}\index{top?\texttt{top}} for the {\tt "a"} label +and {\tt label.lft}\index{lft?\texttt{lft}} for the {\tt "b"} label as +shown in the figure. The \tdescr{label suffix} specifies the position +of the label relative to the specified coordinates. The complete set of +possibilities is\index{rt?\texttt{rt}}\index{bot?\texttt{bot}}% +\index{ulft?\texttt{ulft}}\index{urt?\texttt{urt}}\index{llft?\texttt{llft}}\index{lrt?\texttt{lrt}} +$$ \tt \descr{label suffix} \rightarrow + \descr{empty} \;|\; lft \;|\; rt \;|\; top \;|\; bot \;|\; + ulft \;|\;urt \;|\; llft \;|\; lrt +$$ +where {\tt lft} and {\tt rt} mean left and right and {\tt llft}, {\tt +ulft}, etc.\ mean lower left, upper left, etc. The actual amount by +which the label is offset in whatever direction is determined by the +internal variable\index{internal variables}\index{variables!internal} +{\tt +labeloffset}\index{labeloffset?\texttt{labeloffset}}\label{Dlaboff}. + +\begin{figure}[htp] +$$ +\begin{verbatim} +beginfig(17); +a=.7in; b=.5in; +z0=(0,0); +z1=-z3=(a,0); +z2=-z4=(0,b); +draw z1..z2..z3..z4..cycle; +draw z1--z0--z2; +label.top("a", .5[z0,z1]); +label.lft("b", .5[z0,z2]); +dotlabel.bot("(0,0)", z0); +endfig; +\end{verbatim} +\qquad \mathcenter{\includegraphics{mpman-17.mps}} +$$ +\caption{MetaPost code and the resulting output} +\label{fig16} +\end{figure} + +Figure~\ref{fig16} also illustrates the +{\tt dotlabel}\index{dotlabel?\texttt{dotlabel}}\label{Ddotlab} +statement. This is effectively +like a {\tt label} statement followed by a statement drawing a dot at +the indicated coordinates. For example +$$ \hbox{\tt dotlabel.bot("(0,0)", z0)} $$ +places a dot at {\tt z0} and then puts the label ``(0,0)'' just below the dot. + +Another alternative is the macro +{\tt thelabel}\index{thelabel?\texttt{thelabel}}\label{Dthelab}. This has +the same syntax as the {\tt label} and {\tt dotlabel} statements except that it +returns the label as a \tdescr{picture primary} instead of actually drawing it. +Thus +$$ \hbox{\tt label.bot("(0,0)", z0)} $$ +is equivalent to +$$ \hbox{\tt draw thelabel.bot("(0,0)", z0)} $$ + +For simple applications of labeled figures, you can normally get by with +just {\tt label} and {\tt dotlabel}. In fact, you may be able to use a +short form of the {\tt dotlabel} statement that saves a lot of typing +when you have many points {\tt z0}, {\tt z1}, {\tt z.a}, {\tt z.b}, +etc.\ and you want to use the {\tt z} suffixes as labels. The +statement\index{dotlabels?\texttt{dotlabels}}\label{Ddotlbs} +$$ \hbox{\tt dotlabels.rt(0, 1, a);} $$ +is equivalent to +$$ \hbox{\tt dotlabel.rt("0",z0); dotlabel.rt("1",z1); dotlabel.rt("a",z.a);} $$ +Thus the argument to {\tt dotlabels} is a list of suffixes for which {\tt z} +variables are known, and the \tdescr{label suffix} given with {\tt dotlabels} +is used to position all the labels. + +There is also a {\tt +labels}\index{labels?\texttt{labels}}\label{Dlabels} statement that is +analogous to {\tt dotlabels} but its use is discouraged because it +presents compatibility problems with \MF\index{metafont?\MF}. Some +versions of the preloaded Plain\index{Plain macros} macro package define +{\tt labels} to be synonymous with {\tt dotlabels}. + +For labeling statements such as {\tt label} and {\tt dotlabel} that use +a string expression for the label text, the string gets typeset in a +default font as determined by the string variable {\tt +defaultfont}\index{defaultfont?\texttt{defaultfont}}\label{Ddffont}. +The initial value of {\tt defaultfont} is likely to be {\tt "cmr10"}, +but it can be changed to a different font name by giving an assignment +such as +$$ \hbox{\tt defaultfont:="ptmr8r"} $$ +\ttt{ptmr8r} is a typical way to refer to the Times-Roman font in \TeX. +The discussion of font names on p.\ \pageref{fontname} explains further. + +There is also a numeric quantity called +{\tt defaultscale}\index{defaultscale?\texttt{defaultscale}}\label{Ddfscale} +that determines the type size. +When {\tt default\-scale} is 1, you get the ``normal size'' which is +usually 10 point, but this can also be changed. For instance +$$ \hbox{\tt defaultscale := 1.2} $$ +makes labels come out twenty percent larger. If you do not know the +normal size and you want to be sure the text comes out at some specific +size, say 12 points, you can use the {\tt +fontsize}\index{fontsize?\texttt{fontsize}}\label{Dfntsiz} operator to +determine the normal size: e.g., +$$ \hbox{\tt defaultscale := 12pt/fontsize defaultfont;} $$ + +\label{fontname} +When you change {\tt defaultfont}, the new font name should be something +that \TeX\ would understand since MetaPost gets height and width +information by reading a {\tt tfm}\index{tfm file?{\tt tfm} +file}\index{files!tfm?{\tt tfm}} file. (This is explained in {\sl The +\TeX book\/} \cite{kn:a}.) It should be possible to use built-in +PostScript\index{PostScript!fonts} fonts, but the names for +them are system-dependent. Some typical ones are {\tt ptmr8r} for +Times-Roman\index{Times-Roman}, \ttt{pplr8r} for Palatino\index{Palatino}, +and \ttt{phvr} for Helvetica\index{Helvetica}. The Fontname document, +available at \url{http://tug.org/fontname}, has much more information +about font names and \TeX. A \TeX\index{TeX?\TeX!fonts} font such +as {\tt cmr10} is a little dangerous because it does not have a space +character or certain ASCII symbols. + +MetaPost does not use the ligatures\index{ligatures} and +kerning\index{kerning} information that comes with a \TeX\ font. +Further, MetaPost itself does not interpret virtual fonts. + + +\subsection{Typesetting Your Labels} + +\label{Dbtex} +\index{labels, typesetting} + +\TeX\index{TeX?\TeX} may be used to format complex labels. +If you say\index{btex?\texttt{btex}}\index{etex?\texttt{etex}} +$$ {\tt btex}\, \descr{typesetting commands}\, {\tt etex} $$ +in a MetaPost input file, the \tdescr{typesetting commands} get processed by +\TeX\ and translated into a picture expression +(actually a \tdescr{picture primary}) that can be used in a {\tt label} +or {\tt dotlabel} statement. Any spaces after {\tt btex} or before {\tt etex} +are ignored. For instance, the statement +$$ \hbox{\verb|label.lrt(btex $\sqrt x$ etex, (3,sqrt 3)*u)|} $$ +in Figure~\ref{fig17} places the label $\sqrt x$ at the lower right of the +point {\tt (3,sqrt 3)*u}. + +\begin{figure}[htp] +$$ +\begin{verbatim} +beginfig(18); +numeric u; +u = 1cm; +draw (0,2u)--(0,0)--(4u,0); +pickup pencircle scaled 1pt; +draw (0,0){up} + for i=1 upto 8: ..(i/2,sqrt(i/2))*u endfor; +label.lrt(btex $\sqrt x$ etex, (3,sqrt 3)*u); +label.bot(btex $x$ etex, (2u,0)); +label.lft(btex $y$ etex, (0,u)); +endfig; +\end{verbatim} +\qquad \mathcenter{\includegraphics{mpman-18.mps}} +$$ +\caption{Arbitrary \TeX\ as labels} +\label{fig17} +\end{figure} + +Figure~\ref{fig18} illustrates some of the more complicated things that can +be done with labels. Since the result of {\tt btex} \ldots {\tt etex} is +a picture, it can be operated on like a picture. In particular, it is possible +to apply transformations to pictures. We have not discussed the syntax for +this yet, but a \tdescr{picture secondary} +can be\index{rotated text}\index{rotated?\texttt{rotated}} +$$ \descr{picture secondary}\, {\tt rotated}\, \descr{numeric primary} $$ +This is used in Figure~\ref{fig18} to rotate the label ``$y$ axis'' so that +it runs vertically. + +\begin{figure}[htp] +$$ +\begin{verbatim} +beginfig(19); +numeric ux, uy; +120ux=1.2in; 4uy=2.4in; +draw (0,4uy)--(0,0)--(120ux,0); +pickup pencircle scaled 1pt; +draw (0,uy){right} + for ix=1 upto 8: + ..(15ix*ux, uy*2/(1+cosd 15ix)) + endfor; +label.bot(btex $x$ axis etex, (60ux,0)); +label.lft(btex $y$ axis etex rotated 90, + (0,2uy)); +label.lft( + btex $\displaystyle y={2\over1+\cos x}$ etex, + (120ux, 4uy)); +endfig; +\end{verbatim} +\qquad \mathcenter{\includegraphics{mpman-19.mps}} +$$ +\caption{\TeX\ labels with display math, and rotated by MetaPost} +\label{fig18} +\end{figure} + +Another complication in Figure~\ref{fig18} is the use of the displayed equation +$$y={2\over 1+\cos x}$$ +as a label. It would be more natural to code this as +$$ \hbox{\verb|$$y={2\over 1+\cos x}$$|} $$ +but this would not work because +\TeX\ typesets the labels in ``horizontal mode.'' + +For a way to typeset \emph{variable} text as labels, see the +\texttt{TEX} utility routine described on p.\ \pageref{dTEX}. + +Here is how \TeX\ material gets translated into a form MetaPost +understands: MetaPost stores all {\tt btex}\index{btex?\texttt{btex}} +\ldots\ {\tt etex}\index{etex?\texttt{etex}} blocks in a temporary +file and then runs \TeX\ on that file. If the environment variable +\ttindex{MPTEXPRE} is set to the name of an existing file, its content +will be prepended to the output file for processing by \TeX. You can +use this to include \LaTeX\ preambles, for instance. The \ttt{TEX} +macro described on p.\ \pageref{dTEX} provides another way to handle +this. + +Once the \TeX\ run is finished, MetaPost translates the resulting +DVI\index{dvi file?{\tt dvi} file}\index{files!dvi?{\tt dvi}} file into +low level MetaPost commands that are then read instead of the {\tt btex} +\ldots\ {\tt etex} blocks. If the main file is {\tt fig.mp}, the +translated \TeX\ material is placed in a file named {\tt + fig.mpx}\index{mpx file?{\tt mpx} file}\index{files!mpx?{\tt mpx}}. + +The conversion normally runs silently without any user intervention but +it could fail, for instance if one of the {\tt btex} \ldots {\tt etex} +blocks contains an erroneous \TeX\index{TeX?\TeX!errors} command. In +that case, the \TeX\ input is saved in the file {\tt + mpxerr.tex}\index{mpxerr.tex?\texttt{mpxerr.tex}} and the \TeX\ error +messages appear in {\tt + mpxerr.log}\index{mpxerr.log?\texttt{mpxerr.log}}\index{log file?{\tt + log} file}\index{files!log?{\tt log}}. + +The DVI to MetaPost conversion route {\it does\/} understand virtual +fonts, so you can use your normal \TeX\ font switching commands inside +the label. + + +\label{Dmakempx} +In MetaPost versions before 1.100, the \TeX\ label preprocessing was +handled by an external program that was called upon automatically by +MetaPost. On Web2C-based systems, the preprocessor was normally named +\ttindex{makempx}, which called the utility \ttindex{mpto} for the +creation of the \TeX\ input file and the utility \ttindex{dvitomp} for +the conversion to low level MetaPost. In the current MetaPost version, +the work of this program is now done internally. However, if the +environment variable \ttindex{MPXCOMMAND} is set, the whole label +conversion mechanism will be delegated to the command given in that +variable. + + +\label{Dverbatimtex} +\TeX\ macro definitions or any other auxiliary \TeX\ commands can be +enclosed in a {\tt verbatimtex}\index{verbatimtex?\texttt{verbatimtex}} +\ldots\ {\tt etex}\index{etex?\texttt{etex}} block. The difference +between {\tt btex} and {\tt verbatimtex} is that the former generates a +picture expression while the latter only adds material for \TeX\ to +process. For instance, if you want \TeX\ to typeset labels using macros +defined in {\tt mymac.tex}, your MetaPost input file would look +something like this: +\begin{eqnarray*} +&& \verb|verbatimtex \input mymac etex|\\ +&& \verb|beginfig(1);|\\ +&& \qquad \dots\\ +&& \verb|label(btex|\, \descr{\TeX\ material using \hbox{\tt mymac.tex}}\, + \verb|etex, | \descr{some coordinates} \hbox{\tt );}\\ +&& \qquad \dots +\end{eqnarray*} + +\label{Dtroffmode} +On Unix\footnote{Unix is a registered trademark of Unix Systems +Laboratories.}\index{Unix} and other Web2C-based systems, the +option {\tt -troff} to MetaPost tells the preprocessor that {\tt btex} +$\ldots$ {\tt etex} and {\tt verbatimtex} $\ldots$ {\tt etex} blocks +are in troff\index{troff} instead of \TeX. When using this option, +MetaPost sets the internal variable +\ttindex{troffmode} to~1\index{prologues?\texttt{prologues}}. + +\label{Dprologues} +Setting \ttt{prologues} can be useful with \TeX, too, not just troff. +Here is some explanation: + +\begin{itemize} +\item In PostScript output mode, when \ttt{prologues} is 0, which is the default, the MetaPost +output files do not have embedded fonts. Fonts in the resulting +output will probably render as Courier\index{Courier} or +Times-Roman\index{Times-Roman}. + +In SVG mode, the text will probably render in a generic sans serif font. +There may very well be problems with the encoding of non-ASCII characters: +the font model of SVG is totally different from the model used by MetaPost. + +\item In PostScript output mode, when \ttt{prologues} is 1, the MetaPost output claims to be +``structured PostScript''\index{PostScript!structured} (EPSF\index{EPSF}), +but it is not completely conformant. This variant is kept for backward +compatibility with old (troff) documents, but its use is deprecated. +MetaPost sets \ttt{prologues} to~1 when the {\tt -troff} option is given +on the command line. + +A \ttt{prologues:=1} setting is currently ignored in SVG output +mode. The value is reserved for future use (possibly for mapping to +\ttt{font-family}, \ttt{font-weight}, etc. properties). + +\item In PostScript output mode, when \ttt{prologues} is 2, the +MetaPost output is EPSF and assumes +that the text comes from PostScript\index{PostScript!fonts} fonts +provided by the ``environment'', such as the document viewer or +embedded application using the output. MetaPost will attempt to +set up the font encodings correctly, based on \ttt{fontmapfile} and +\ttt{fontmapline} commands. + +A \ttt{prologues:=2} setting is currently ignored in SVG output mode. +The value is reserved for future use (possibly for external +\ttt{font-face} definitions). + +\item In PostScript output mode, when \ttt{prologues} is 3, the MetaPost output will be EPSF but +will contain the PostScript font(s) (or a subset) used based on the +\ttt{fontmapfile} and \ttt{fontmapline} commands. This value is useful +for generating stand-alone PostScript graphics. + +In SVG mode, the font glyphs are converted to path definitions that +are included at the top of the output file. This method is currently +the only reliable way to export text objects to SVG. + +\end{itemize} + + +It is worth noting that the default value \ttt{prologues:=0} is sufficient +for graphics included in \TeX-based documents. Also, the \ttt{prologues} variable is irrelevant +when processing MetaPost files through the \ttindex{mptopdf} utility +(part of the \ConTeXt\ distribution), because PDF files are, by nature, +stand-alone. Moreover, the value of \ttt{prologues} has no effect on +\MF\ fonts in your MetaPost files, i.\,e., MetaPost never embeds such +fonts. Only output drivers, e.\,g., \ttt{dvips} or pdf\LaTeX\ will +handle those. + +The details on how to include PostScript figures in a paper +done in \TeX\ or troff are system-dependent. They can generally be found +in manual pages and other on-line documentation, but have a look at +section~\ref{teximport} of this manual for some brief instructions that +in many cases should work. The manual for the +widely-used Dvips processor is in a file \ttt{dvips.texi}, included in +most distributions, and is available online at +\url{http://tug.org/texinfohtml/dvips.html}, among many other places and +formats. + +\subsection{Font map files} +\label{fontmap} + +If \ttt{prologues} is set to~2, any used fonts in the output file are +automatically re-encoded, and the encoding vector file specified in +the fontmap entry will be embedded in the output file. If +\ttt{prologues} is set to~3, MetaPost will also attempt to include +(a subset of) the used PostScript\index{PostScript!fonts} fonts. For +this to work, it needs to acquire font map information. + +The code is based on the font library used by pdf\TeX. Following in the +footsteps of pdf\TeX, there are two new associated primitives: +\ttindex{fontmapfile}\label{Dfontmapfile} and +\ttindex{fontmapline}\label{Dfontmapline}. Here is a simple example, +specifying the map file for Latin Modern fonts in YandY (\LaTeX\ LY1) +encoding: +\begin{center}\begin{tabular}{l} +\verb|prologues:=2;|\\ +\verb|fontmapfile "texnansi-lm.map";|\\ +\verb|beginfig(1);|\\ +\verb| draw "Helló, világ" infont "texnansi-lmr10";|\\ +\verb|endfig;| +\end{tabular}\end{center} + +Using \ttt{fontmapline}, you can specify font mapping information +inside the figure: +\begin{center}\begin{tabular}{l} +\verb|prologues:=2;|\\ +\verb|fontmapline "pplbo8r URWPalladioL-Bold "&ditto&|\\ +\verb| ".167 SlantFont"&ditto&" <8r.enc <uplb8a.pfb";|\\ +\verb|beginfig(1);|\\ +\verb| draw "Hello, world" infont "pplbo8r";|\\ +\verb|endfig;| +\end{tabular}\end{center} +This will attempt to reencode the PostScript font +URWPalladioL-Bold\index{URWPalladioL-Bold}\index{Palatino} +whose tfm file is pplbo8r.tfm. The encoding is found in the file +8r.enc, and will be included into the output file. + +If the same example was run with \ttt{prologues:=3}, MetaPost would +include a subset of the font that resides in uplb8a.pfb into the +output. In this case, the subset of the font is reorganized so that it +has the correct encoding internally, 8r.enc will not be embedded also. + +The argument to both commands has an optional flag character at the very +beginning. This optional flag has the same meaning as in pdf\TeX: +$$\begin{tabular}{|c|l|} \hline +\multicolumn1{|c|}{Option}& \multicolumn1{c|}{Meaning}\\ \hline + + & extend the font list, but ignore duplicates \\ + = & extend the font list, replacing duplicates \\ + $-$ & remove all matching fonts from the font list \\ +\hline +\end{tabular} +$$ +Without any option, the current list will be completely replaced. + +If \ttt{prologues} is set to two or three, yet there are no +\ttt{fontmapfile} statements, MetaPost will attempt to locate a +default map file, with a preference to read {\tt mpost.map}. If that +fails, it will also attempt either {\tt troff.map} or {\tt +pdftex.map}, depending on whether or not troff mode is enabled. If +\ttt{prologues} is set to~1, MetaPost attempts to read a file called +{\tt psfonts.map}, regardless of any {\tt fontmapfile} +statement. Again, this is for backward compatibility only. + + +\subsection{The \texttt{infont} operator} +\label{Sinfont} + +Regardless of whether you use \TeX\ or troff, all the real work of +adding text to pictures is done by a MetaPost primitive operator called +{\tt infont}\index{infont?\texttt{infont}}. It is a \tdescr{primary +binop}\index{primary binop?\tdescr{primary binop}} that takes a +\tdescr{string secondary} as its left argument and a \tdescr{string +primary} as its right argument. The left argument is text, and the +right argument is a font name. The result of the operation is a +\tdescr{picture secondary} 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 "ptmr8r"} $$ +is a picture containing character {\tt n+64} of the font \ttt{ptmr8r}, +which is a typical \TeX\ way to refer to Times-Roman. See p.\ +\pageref{fontname} for further discussion. + +Bare MetaPost does not do any kind of input reencoding, so when +you use {\tt infont} string for labels (instead of {\tt btex} \ldots\ +{\tt etex}), the string has to be specified in the font encoding. + + +\subsection{Measuring Text} +\label{meas} + +MetaPost makes readily available the physical dimensions\index{size} of +pictures generated by the {\tt infont} operator. There are unary +operators {\tt +llcorner}\index{llcorner?\texttt{llcorner}}\label{Dcornop}, {\tt +lrcorner}\index{lrcorner?\texttt{lrcorner}}, {\tt +urcorner}\index{urcorner?\texttt{urcorner}}, {\tt +ulcorner}\index{ulcorner?\texttt{ulcorner}}, and {\tt +center}\index{center?\texttt{center}}\label{Dcenter} that take a \tdescr{picture +primary} and return the corners of its ``bounding box'' as illustrated +in Figure~\ref{bbox}. The {\tt center} operator also accepts +\tdescr{path primary} and \tdescr{pen primary} operands. In MetaPost +Version 0.30 and higher, {\tt llcorner}, {\tt lrcorner}, etc. accept +all three argument types as well. + +The argument type restrictions on the corner operators are not very +important because their main purpose is to allow {\tt label} and {\tt +dotlabel} statements to center their text properly. The predefined +macro\index{bbox?\texttt{bbox}}\label{Dbbox} +$$ {\tt bbox}\, \descr{picture primary} $$ +finds a rectangular path that represents the bounding box of a given picture. +If {\tt p} is a picture, {\tt bbox p} is equivalent to +$$\begin{verbatim} +(llcorner p--lrcorner p--urcorner p--ulcorner p--cycle) +\end{verbatim} +$$ +except that it allows for a small amount of extra space around {\tt p} +as specified by the internal variable\index{internal +variables}\index{variables!internal} {\tt +bboxmargin}\index{bboxmargin?\texttt{bboxmargin}}\label{Dbbmargin}. + +\begin{figure}[htp] +$$ \includegraphics{mpman-20.mps} $$ +\caption{A bounding box and its corner points.} +\label{bbox} +\end{figure} + +Note that MetaPost computes the bounding box of a {\tt +btex}\index{btex?\texttt{btex}} \ldots\ {\tt +etex}\index{etex?\texttt{etex}} picture just the way +\TeX\index{TeX?\TeX} does. This is quite natural, but it has certain +implications in view of the fact that \TeX\ has features like +{\tt\string\strut}\index{strut?{\tt\string\strut}} and +{\tt\string\rlap}\index{rlap?{\tt\string\rlap}} that allow \TeX\ users +to lie about the dimensions of a box. + +When \TeX\ commands that lie about the dimensions of a box are +translated in to low-level MetaPost code, a {\tt +setbounds}\index{setbounds?\texttt{setbounds}}\label{Dsetbnd} statement +does the lying:\index{picture variable?\tdescr{picture variable}} +$$ {\tt setbounds}\, \descr{picture variable}\, {\tt to}\, \descr{path expression} +$$ +makes the \tdescr{picture variable} behave as if its bounding box were +the same as the given path. The path has to be a cycle, i.e., it must +be a closed path. To get the true bounding box of such a +picture, assign a positive value to the internal variable\index{internal +variables}\index{variables!internal} {\tt +truecorners}\index{truecorners?\texttt{truecorners}}\label{Dtruecorn}:\footnote{The +{\tt setbounds} and {\tt truecorners} features are only found in +MetaPost version 0.30 and higher.} i.e., +$$ \hbox{\verb|show urcorner btex $\bullet$\rlap{ A} etex|} $$ +produces ``\verb|>> (4.9813,6.8078)|'' while +$$ \hbox{\verb|truecorners:=1; show urcorner btex $\bullet$\rlap{ A} etex|} $$ +produces ``\verb|>> (15.7742,6.8078)|.'' + + +\section{Advanced Graphics} +\label{adv.gr} + +All the examples in the previous sections have been simple line drawings +with labels added. This section describes shading and tools for +generating not-so-simple line drawings. Shading is done with the {\tt +fill}\index{fill?\texttt{fill}}\label{Dfill} statement. In its simplest +form, the {\tt fill} statement requires a \tdescr{path expression} that +gives the boundary of the region to be filled. In the syntax +$$ {\tt fill}\, \descr{path expression} $$ +the argument should be a cyclic path, i.e., a path that describes a +closed curve via the \verb|..cycle| or \verb|--cycle| notation. For +example, the {\tt fill} statement in Figure~\ref{fig20} builds a closed +path by extending the roughly semicircular path~{\tt p}. This path has +a counter-clockwise orientation, but that does not matter because the +{\tt fill} statement uses PostScript's\index{PostScript} non-zero +winding\index{winding number} number rule\index{non-zero fill + rule}\index{fill rule!non-zero}\index{PostScript!fill + rule}~\cite{ad:red2}. + +\begin{figure}[htp] +$$ \begin{verbatim} +beginfig(21); +path p; +p = (-1cm,0)..(0,-1cm)..(1cm,0); +fill p{up}..(0,0){-1,-2}..{up}cycle; +draw p..(0,1cm)..cycle; +endfig; +\end{verbatim} +\qquad \mathcenter{\includegraphics{mpman-21.mps}} +$$ +\caption{MetaPost code and the corresponding output.} +\label{fig20} +\end{figure} + +The general {\tt fill} statement\index{withcolor?\texttt{withcolor}}\label{Dwithcolor} +$$ {\tt fill}\, \descr{path expression}\, + {\tt withcolor}\, \descr{color expression} +$$ +specifies a shade of gray or (if you have a color printer) some +rainbow color. The $\descr{color expression}$ can have five possible +values, mapping to four possible color models: + +$$ +\begin{tabular}{ll} +Actual input & Remapped meaning\\\hline +{\tt withcolor} $\descr{rgbcolor} c$ & withrgbcolor\index{withrgbcolor?\texttt{withrgbcolor}}\label{Dwithrgbcolor} $c$\\ +{\tt withcolor} $\descr{cmykcolor} c$ & withcmykcolor\index{withcmykcolor?\texttt{withcmykcolor}}\label{Dwithcmykcolor} $c$\\ +{\tt withcolor} $\descr{numeric} c$ & withgreyscale\index{withgreyscale?\texttt{withgreyscale}}\label{Dwithgreyscale} $c$\\ +{\tt withcolor} $\descr{false}$ & withoutcolor\index{withoutcolor?\texttt{withoutcolor}}\label{Dwithoutcolor} \\ +{\tt withcolor} $\descr{true}$ & $\descr{current default color model}$\\ +\end{tabular} +$$ + +For the specific color models, there are also: +$$ {\tt fill}\, \descr{path expression}\, + {\tt withrgbcolor}\, \descr{rgbcolor expression} +$$ +$$ {\tt fill}\, \descr{path expression}\, + {\tt withcmykcolor}\, \descr{cmykcolor expression} +$$ +$$ {\tt fill}\, \descr{path expression}\, + {\tt withgreyscale}\, \descr{numeric} +$$ +$$ {\tt fill}\, \descr{path expression}\, + {\tt withoutcolor} +$$ + +An image object cannot have more then one color model, the last +\ttt{withcolor}, \ttt{withrgbcolor}, \ttt{withcmykcolor}, +\ttt{withgreyscale} or \ttt{withoutcolor} specification sets the color +model for any particular object. + +The model \ttt{withoutcolor} needs a bit more explanation: selecting +this model means that MetaPost will not write a color selection +statement to the PostScript output file for this object. + +The `current default' color model can be set up using the internal +variable \ttindex{defaultcolormodel}\label{Ddefaultcolormodel}. +Table~\ref{dfltcmod} lists the valid values. +\begin{table} +\centering +\begin{tabular}{|c|l|} +\hline +Value & Color model\\\hline +1 & no model\\ +3 & greyscale\\ +5 & rgb (default)\\ +7 & cmyk\\ +\hline +\end{tabular} +\caption{Supported color models.} +\label{dfltcmod} +\end{table} + + +Figure~\ref{fig21} illustrates several applications of the fill command +to fill areas with shades of gray. The paths involved are intersecting +circles {\tt a} and {\tt b} and a path {\tt ab} that bounds the region +inside both circles. Circles {\tt a} and {\tt b} are derived from a +predefined path {\tt +fullcircle}\index{fullcircle?\texttt{fullcircle}}\label{Dfcirc} that +approximates a circle of unit diameter centered on the origin. There is +also a predefined path {\tt +halfcircle}\index{halfcircle?\texttt{halfcircle}}\label{Dhcirc} that is +the part of {\tt fullcircle} above the $x$ axis. Path~{\tt ab} is then +initialized using a predefined macro {\tt buildcycle} that will be +discussed shortly. + +\begin{figure}[htp] +$$ \begin{verbatim} +beginfig(22); +path a, b, aa, ab; +a = fullcircle scaled 2cm; +b = a shifted (0,1cm); +aa = halfcircle scaled 2cm; +ab = buildcycle(aa, b); +picture pa, pb; +pa = thelabel(btex $A$ etex, (0,-.5cm)); +pb = thelabel(btex $B$ etex, (0,1.5cm)); +fill a withcolor .7white; +fill b withcolor .7white; +fill ab withcolor .4white; +unfill bbox pa; +draw pa; +unfill bbox pb; +draw pb; +label.lft(btex $U$ etex, (-1cm,.5cm)); +draw bbox currentpicture; +endfig; +\end{verbatim} +\qquad \mathcenter{\includegraphics{mpman-22.mps}} +$$ +\caption{MetaPost code and the corresponding output.} +\index{fullcircle?\texttt{fullcircle}}\index{halfcircle?\texttt{halfcircle}}\index{buildcycle?\texttt{buildcycle}} +\label{fig21} +\end{figure} + +Filling circle {\tt a} with the light gray color {\tt .7white} and then +doing the same with circle {\tt b} doubly fills the region where the +disks overlap. The rule is that each {\tt fill} statement assigns the +given color to all points in the region covered, wiping out whatever was +there previously including lines and text as well as filled regions. +Thus it is important to give {\tt fill} commands in the right order. In +the above example, the overlap region gets the same color twice, leaving +it light gray after the first two {\tt fill} statements. The third fill +statement assigns the darker color {\tt .4white} to the overlap region. + +At this point the circles and the overlap region have their final colors +but there are no cutouts for the labels. The cutouts are achieved by +the {\tt unfill}\index{unfill?\texttt{unfill}}\label{Dunfill} statements +that effectively erase\index{erasing} the regions bounded by {\tt bbox +pa}\index{bbox?\texttt{bbox}} and {\tt bbox pb}. More precisely, {\tt +unfill} is shorthand for filling {\tt withcolor background}, where {\tt +background} is normally equal to {\tt white} as is appropriate for +printing on white paper. If necessary, you can assign a new color value +to {\tt +background}\index{background?\texttt{background}}\label{Dbground}. + +The labels need to be stored in pictures {\tt pa} and {\tt pb} to allow +for measuring their bounding box before actually drawing them. The +macro {\tt thelabel}\index{thelabel?\texttt{thelabel}} creates such +pictures and shifts them into position so that they are ready to draw. +Using the resulting pictures in {\tt draw} statements of the +form\index{draw?\texttt{draw}} +$$ {\tt draw}\, \descr{picture expression} $$ +adds them to {\tt currentpicture}\index{currentpicture?\texttt{currentpicture}} +so that they overwrite a portion of what has +already been drawn. In Figure~\ref{fig21} just the white rectangles produced by +{\tt unfill} get overwritten. + +\subsection{Building Cycles} +\label{buildcy} + +The {\tt buildcycle}\index{buildcycle?\texttt{buildcycle}} command +constructs paths for use with the {\tt fill} or {\tt unfill} macros. +When given two or more paths such as {\tt aa} and {\tt b}, the {\tt +buildcycle} macro tries to piece them together so as to form a cyclic +path. In this case path {\tt aa} is a semicircle that starts just to +the right of the intersection with path {\tt b}, then passes through +{\tt b} and ends just outside the circle on the left as shown in +Figure~\ref{fig22}a. + +Figure~\ref{fig22}b shows how {\tt buildcycle} forms a closed cycle from +the pieces of paths {\tt aa} and {\tt b}. The {\tt buildcycle} macro +detects the two intersections\index{intersections} labeled 1 and 2 in +Figure~\ref{fig22}b. Then it constructs the cyclic path shown in bold +in the figure by going forward along path {\tt aa} from intersection~1 +to intersection~2 and then forward around the counter-clockwise path +{\tt b} back to intersection~1. It turns out that {\tt buildcycle(a,b)} +would have produced the same result, but the reasoning behind this is a +little confusing. + + +\begin{figure}[htp] +$$ {\includegraphics{mpman-123.mps} \atop (a)} + \qquad {\includegraphics{mpman-223.mps} \atop (b)} +$$ +\caption[A demonstration of cycle building] + {(a)~The semicircular path~{\tt aa} + with a dashed line marking path {\tt b}; (b)~paths~{\tt aa} and {\tt b} + with the portions selected by {\tt buildcycle} shown by heavy lines.} +\label{fig22} +\end{figure} + +It is a easier to use the {\tt buildcycle} macro in situations like +Figure~\ref{fig23} where there are more than two path arguments and each +pair of consecutive paths has a unique intersection. For instance, the +line~{\tt q0.5} and the curve~{\tt p2} intersect only at point~$P$; and +the curve {\tt p2} and the line~{\tt q1.5} intersect only at point~$Q$. +In fact, each of the points $P$, $Q$, $R$, $S$ is a unique intersection, +and the result of\index{buildcycle?\texttt{buildcycle}} +$$ \hbox{\tt buildcycle(q0.5, p2, q1.5, p4)} $$ +takes {\tt q0.5} from $S$ to~$P$, then {\tt p2} from $P$ to~$Q$, then +{\tt q1.5} from $Q$ to~$R$, and finally {\tt p4} from $R$ back to~$S$. +An examination of the MetaPost code for Figure~\ref{fig23} reveals that +you have to go backwards along {\tt p2} in order to get from $P$ to~$Q$. +This works perfectly well as long as the +intersection\index{intersection} points are uniquely defined but it can +cause unexpected results when pairs of paths intersect more than once. + +\begin{figure}[htp] +$$ \begin{verbatim} +beginfig(24); +h=2in; w=2.7in; +path p[], q[], pp; +for i=2 upto 4: ii:=i**2; + p[i] = (w/ii,h){1,-ii}...(w/i,h/i)...(w,h/ii){ii,-1}; +endfor +q0.5 = (0,0)--(w,0.5h); +q1.5 = (0,0)--(w/1.5,h); +pp = buildcycle(q0.5, p2, q1.5, p4); +fill pp withcolor .7white; +z0=center pp; +picture lab; lab=thelabel(btex $f>0$ etex, z0); +unfill bbox lab; draw lab; +draw q0.5; draw p2; draw q1.5; draw p4; +dotlabel.top(btex $P$ etex, p2 intersectionpoint q0.5); +dotlabel.rt(btex $Q$ etex, p2 intersectionpoint q1.5); +dotlabel.lft(btex $R$ etex, p4 intersectionpoint q1.5); +dotlabel.bot(btex $S$ etex, p4 intersectionpoint q0.5); +endfig; +\end{verbatim} +\atop \mathcenter{\includegraphics{mpman-24.mps}} +$$ +\caption{MetaPost code and the corresponding output.} +\label{fig23} +\end{figure} + +The general rule for the {\tt buildcycle} macro is that +$$ \hbox{\tt buildcycle(}p_1\hbox{\tt,}\, p_2\hbox{\tt,}\, + p_3\hbox{\tt,}\, \ldots \hbox{\tt,} p_k \hbox{\tt )} +$$ +chooses the intersection between each $p_i$ and $p_{i+1}$ to be as late +as possible on $p_i$ and as early as possible on $p_{i+1}$. There is no +simple rule for resolving conflicts between these two goals, so you +should avoid cases where one intersection point occurs later on $p_i$ +and another intersection\index{intersection} point occurs earlier on +$p_{i+1}$. + +The preference for intersections as late as possible on $p_i$ and as +early as possible on $p_{i+1}$ leads to ambiguity resolution in favor of +forward-going subpaths. For cyclic paths such as path~{\tt b} in +Figure~\ref{fig22} ``early'' and ``late'' are relative to a start/finish +point which is where you get back to when you say ``{\tt ..cycle}''. +For the path~{\tt b}, this turns out to be the rightmost point on the +circle. + +A more direct way to deal with path intersections is via the +\tdescr{secondary binop}\index{secondary binop?\tdescr{secondary binop}} +{\tt +intersection\-point}\index{intersectionpoint?\texttt{intersectionpoint}}\label{Disecpt} +that finds the points $P$, $Q$, $R$, and~$S$ in Figure~\ref{fig23}. +This macro finds a point where two given paths intersect. If there is +more than one intersection point, it just chooses one; if there is no +intersection, the macro generates an error message. + +\subsection{Dealing with Paths Parametrically} + +The {\tt +intersectionpoint}\index{intersectionpoint?\texttt{intersectionpoint}} +macro is based on a primitive operation called {\tt +intersectiontimes}\index{intersectiontimes?\texttt{intersectiontimes}}\label{Disectt}. +This \tdescr{secondary binop} is one of several operations that deal +with paths parametrically. It locates an intersection between two paths +by giving the ``time'' parameter on each path. This refers to the +parameterization scheme from Section~\ref{curves} that described paths +as piecewise cubic curves $\bigl(X(t),Y(t)\bigr)$ where $t$ ranges from +zero to the number of curve segments. In other words, when a path is +specified as passing through a sequence of points, where $t=0$ at the +first point, then $t=1$ at the next, and $t=2$ at the next, etc. The +result of +$$ \hbox{\tt a intersectiontimes b} $$ +is $(-1,-1)$ if there is no intersection; otherwise you get +a pair $(t_a,t_b)$, where $t_a$ is a time on path {\tt a} when it intersects +path~{\tt b}, and $t_b$ is the corresponding time on path~{\tt b}. + +For example, suppose path~{\tt a} is denoted by the thin line in +Figure~\ref{fig24} and path~{\tt b} is denoted by the thicker line. If +the labels indicate time values on the paths, the pair of time values +computed by +$$ \hbox{\tt a intersectiontimes b} $$ +must be one of +$$ (0.25,1.77),\ (0.75,1.40), {\rm or}\ (2.58,0.24), $$ +depending on which of the three intersection points is chosen by the +MetaPost interpreter. The exact rules for choosing among multiple +intersection points are a little complicated, but it turns out that you +get the time values $(0.25,1.77)$ in this example. Smaller time values +are preferred over larger ones so that $(t_a,t_b)$ is preferred to +$(t'_a,t'_b)$ whenever $t_a<t'_a$ and $t_b<t'_b$. When no single +alternative minimizes both the $t_a$ and $t_b$ components the $t_a$ +component tends to get priority, but the rules get more complicated when +there are no integers between $t_a$ and $t'_a$\index{intersection}. +(For more details, see {\sl The \MF book} \cite[Chapter 14]{kn:c}). + +\begin{figure}[htp] +$$ \includegraphics{mpman-25.mps} $$ +\caption{Two intersecting paths with time values marked on each path.} +\label{fig24} +\end{figure} + +The {\tt intersectiontimes} operator is more flexible than {\tt +intersectionpoint} because there are a number of things that can be done +with time values on a path. One of the most important is just to ask +``where is path {\tt p} at time {\tt t}?'' The construction\index{point +of?\texttt{point of}}\label{Dpntof} +$$ {\tt point}\, \descr{numeric expression}\, {\tt of}\, \descr{path primary} $$ +answers this question. If the \tdescr{numeric expression} is less than +zero or greater than the time value assigned to the last point on the +path, the {\tt point of} construction normally yields an endpoint of the +path. Hence, it is common to use the predefined constant {\tt +infinity}\index{infinity?\texttt{infinity}}\label{Dinf} (equal to +4095.99998) as the \tdescr{numeric expression} in a {\tt point of} +construction when dealing with the end of a path. + +Such ``infinite'' time values do not work for a cyclic path, since time +values outside of the normal range can be handled by modular arithmetic +in that case; i.e., a cyclic path~{\tt p} through points $z_0$, $z_1$, +$z_2$, \ldots, $z_{n-1}$ has the normal parameter range $0\le t<n$, but +$$ \hbox{\tt point t of p} $$ +can be computed for any~$t$ by first reducing $t$ modulo~$n$. If the +modulus~$n$ is not readily +available,\index{length?\texttt{length}}\label{Dlength} +$$ {\tt length}\, \descr{path primary} $$ +gives the integer value of the upper limit of the normal time parameter +range for the specified path. + +MetaPost uses the same correspondence between time values and points on +a path to evaluate the {\tt +subpath}\index{subpath?\texttt{subpath}}\label{Dsubpth} operator. The +syntax for this operator is +$$ {\tt subpath}\, \descr{pair expression}\, {\tt of}\, \descr{path primary} $$ +If the value of the \tdescr{pair expression} is $(t_1,t_2)$ and the +\tdescr{path primary} is $p$, the result is a path that follows $p$ from +{\tt point $t_1$ of $p$} to {\tt point $t_2$ of $p$}. If $t_2<t_1$, the +subpath runs backwards along~$p$. + +An important operation based on the {\tt subpath} operator is the +\tdescr{tertiary binop}\index{tertiary binop?\tdescr{tertiary binop}} +{\tt cutbefore}\index{cutbefore?\texttt{cutbefore}}\label{Dcutb}. For +intersecting paths $p_1$ and $p_2$, +$$ p_1\ {\tt cutbefore}\ p_2 $$ +is equivalent to +$$ \hbox{\tt subpath (xpart($p_1$ intersectiontimes $p_2$), length $p_1$) of $p_1$} +$$ +except that it also sets the path variable {\tt +cuttings}\index{cuttings?\texttt{cuttings}}\label{Dcuttings} to the +portion of $p_1$ that gets cut off. In other words, {\tt cutbefore} +returns its first argument with the part before the intersection cut +off. With multiple intersections, it tries to cut off as little as +possible. If the paths do not intersect, {\tt cutbefore} returns its +first argument. + +There is also an analogous \tdescr{tertiary binop}\index{tertiary +binop?\tdescr{tertiary binop}} called {\tt +cutafter}\index{cutafter?\texttt{cutafter}}\label{Dcuta} that works by +applying {\tt cutbefore} with time reversed along its first argument. +Thus +$$ p_1\ {\tt cutafter}\ p_2 $$ +tries to cut off the part of $p_1$ after its last intersection with $p_2$. + +Another operator\index{direction of?\texttt{direction of}}\label{Ddirof} +$$ {\tt direction}\, \descr{numeric expression}\, {\tt of}\, \descr{path primary} +$$ +finds a vector in the direction of the \tdescr{path primary}. This is +defined for any time value analogously to the {\tt point of} +construction. The resulting direction vector has the correct +orientation and a somewhat arbitrary magnitude. Combining {\tt point +of} and {\tt direction of} constructions yields the equation for a +tangent line as illustrated in Figure~\ref{fig25}. + +\begin{figure}[htp] +$$ \begin{verbatim} +beginfig(26); +numeric scf, #, t[]; +3.2scf = 2.4in; +path fun; +# = .1; % Keep the function single-valued +fun = ((0,-1#)..(1,.5#){right}..(1.9,.2#){right}..{curl .1}(3.2,2#)) + yscaled(1/#) scaled scf; +x1 = 2.5scf; +for i=1 upto 2: + (t[i],whatever) = + fun intersectiontimes ((x[i],-infinity)--(x[i],infinity)); + z[i] = point t[i] of fun; + z[i]-(x[i+1],0) = whatever*direction t[i] of fun; + draw (x[i],0)--z[i]--(x[i+1],0); + fill fullcircle scaled 3bp shifted z[i]; +endfor +label.bot(btex $x_1$ etex, (x1,0)); +label.bot(btex $x_2$ etex, (x2,0)); +label.bot(btex $x_3$ etex, (x3,0)); +draw (0,0)--(3.2scf,0); +pickup pencircle scaled 1pt; +draw fun; +endfig; +\end{verbatim} +\atop \includegraphics{mpman-26.mps} +$$ +\caption{MetaPost code and the resulting figure} +\label{fig25} +\end{figure} + +If you know a slope and you want to find a point on a curve where the +tangent line has that slope, the {\tt directiontime}\index{directiontime +of?\texttt{directiontime of}}\label{Ddtimof} operator inverts the {\tt +direction of} operation. Given a direction vector and a path, +$$ {\tt directiontime}\, \descr{pair expression}\, {\tt of}\, + \descr{path primary} +$$ +returns a numeric value that gives the first time~$t$ when the path has +the indicated direction. (If there is no such time, the result is +$-1$). For example, if {\tt a} is the path drawn as a thin curve in +Figure~\ref{fig24}, {\tt directiontime (1,1) of a} returns 0.2084. + +There is also an predefined macro \index{directionpoint +of?\texttt{directionpoint of}}\label{Ddpntof} +$$ {\tt directionpoint}\, \descr{pair expression}\, {\tt of}\, + \descr{path primary} +$$ +that finds the first point on a path where a given direction is achieved. The +{\tt directionpoint} macro produces an error message if the direction does not +occur on the path. + +Operators {\tt +arclength}\index{arclength?\texttt{arclength}}\label{Darclng} and {\tt +arctime of}\index{arctime of?\texttt{arctime of}}\label{Darctim} relate +the ``time'' on a path to the more familiar concept of arc +length.\index{arc length}\footnote{The {\tt arclength} and {\tt arctime} +operators are only found in MetaPost version 0.50 and higher.} The +expression +$$ \hbox{{\tt arclength} \tdescr{path primary}} $$ +gives the arc length of a path. If {\tt p} is a path and {\tt a} is a number +between 0 and {\tt arclength p}, +$$ \hbox{\tt arctime a of p} $$ +gives the time~{\tt t} such that +$$ \hbox{\tt arclength subpath (0,t) of p} = {\tt a}. $$ + +\subsection{Affine Transformations} +\label{transsec} +\index{transform type} + +Note how path {\tt fun} in Figure~\ref{fig25} is first constructed as +$$ \hbox{\verb|(0,-.1)..(1,.05){right}..(1.9,.02){right}..{curl .1}(3.2,.2)|} $$ +and then the {\tt yscaled}\index{yscaled?\texttt{yscaled}} and {\tt +scaled}\index{scaled?\texttt{scaled}} operators are used to adjust the +shape and size of the path. As the name suggests, an expression +involving ``{\tt yscaled 10}'' multiplies $y$ coordinates by ten so that +every point $(x,y)$ on the original path corresponds to a point +$(x,10y)$ on the transformed path. + +Including {\tt scaled} and {\tt yscaled}, there are seven transformation +operators that take a numeric or pair +argument:\index{shifted?\texttt{shifted}}% +\index{rotated?\texttt{rotated}}\index{slanted?\texttt{slanted}}\index{scaled?\texttt{scaled}}\index{xscaled?\texttt{xscaled}}% +\index{yscaled?\texttt{yscaled}}\index{zscaled?\texttt{zscaled}}\label{Dtranop} +\begin{eqnarray*} + (x,y){\tt\ shifted\ }(a,b) &=& (x+a,\, y+b); \\ + (x,y){\tt\ rotated\ }\theta &=& (x\cos\theta-y\sin\theta,\, + x\sin\theta+y\cos\theta); \\ + (x,y){\tt\ slanted\ }a &=& (x+ay,\, y); \\ + (x,y){\tt\ scaled\ }a &=& (ax,\, ay); \\ + (x,y){\tt\ xscaled\ }a &=& (ax,\, y); \\ + (x,y){\tt\ yscaled\ }a &=& (x,\, ay); \\ + (x,y){\tt\ zscaled\ }(a,b) &=& (ax-by,\, bx+ay). +\end{eqnarray*} +Most of these operations are self-explanatory except for {\tt zscaled} +which can be thought of as multiplication of complex numbers. The +effect of {\tt zscaled} $(a,b)$ is to rotate and scale so as to map +$(1,0)$ into $(a,b)$. The effect of {\tt rotated}~$\theta$ is rotate +$\theta$ degrees counter-clockwise. + +Any combination of shifting, rotating, slanting, etc.\ is an affine +transformation, the net effect of which is to transform any pair $(x,y)$ +into +$$ (t_x+t_{xx}x+t_{xy}y,\, t_y+t_{yx}x+t_{yy}y), $$ +for some sextuple $(t_x,t_y,t_{xx},t_{xy},t_{yx},t_{yy})$. This +information can be stored in a variable of type transform so that {\tt +transformed T}\index{transformed?\texttt{transformed}}\label{Dtrfrmd} +might be equivalent to +$$ \hbox{\tt xscaled -1 rotated 90 shifted (1,1)} $$ +if {\tt T} is an appropriate transform variable. The +transform~{\tt T} could then be initialized with an +expression of type transform as follows: +$$ \begin{verbatim} +transform T; +T = identity xscaled -1 rotated 90 shifted (1,1); +\end{verbatim} +$$ +As this example indicates, transform expressions can be built up by +applying transformation operators to other transforms. The predefined +transformation {\tt +identity}\index{identity?\texttt{identity}}\label{Dident} is a useful +starting point for this process. This can be illustrated by +paraphrasing the above equation for {\tt T} into English: ``{\tt T} +should be the transform obtained by doing whatever {\tt identity} +does. Then scaling $x$~coordinates by $-1$, rotating $90^\circ$, and +shifting by $(1,1)$.'' This works because {\tt identity} is the +identity transformation which does nothing; i.e., {\tt transformed +identity} is a no-op. + +The syntax for transform expressions and transformation operators is given in +Figure~\ref{sytrans}. It includes two more options for +\tdescr{transformer}:\index{reflectedabout?\texttt{reflectedabout}} +$$ \hbox{\tt reflectedabout(}p, q\hbox{\tt )} $$ +reflects about the line defined by points $p$ and $q$; +and\index{rotatedaround?\texttt{rotatedaround}} +$$ \hbox{\tt rotatedaround(}p,\theta\hbox{\tt )} $$ +rotates $\theta$ degrees counter-clockwise around point $p$. For example, +the equation for initializing transform~{\tt T} could have been +$$ \hbox{\tt T = identity reflectedabout((2,0), (0,2))}. $$ + +\begin{figure}[htp] +\begin{ctabbing} +$\tt \descr{pair secondary} \rightarrow + \descr{pair secondary} \descr{transformer}$\\ +$\tt \descr{path secondary} \rightarrow + \descr{path secondary} \descr{transformer}$\\ +$\tt \descr{picture secondary} \rightarrow + \descr{picture secondary} \descr{transformer}$\\ +$\tt \descr{pen secondary} \rightarrow + \descr{pen secondary} \descr{transformer}$\\ +$\tt \descr{transform secondary} \rightarrow + \descr{transform secondary} \descr{transformer}$\\[6pt] +$\tt \descr{transformer} \rightarrow rotated \descr{numeric primary}$\\ +$\tt \qquad \;|\; scaled \descr{numeric primary}$\\ +$\tt \qquad \;|\; shifted \descr{pair primary}$\\ +$\tt \qquad \;|\; slanted \descr{numeric primary}$\\ +$\tt \qquad \;|\; transformed \descr{transform primary}$\\ +$\tt \qquad \;|\; xscaled \descr{numeric primary}$\\ +$\tt \qquad \;|\; yscaled \descr{numeric primary}$\\ +$\tt \qquad \;|\; zscaled \descr{pair primary}$\\ +$\tt \qquad \;|\; reflectedabout\hbox{\tt (}\descr{pair expression} + \hbox{\tt ,}\descr{pair expression}\hbox{\tt )}$\\ +$\tt \qquad \;|\; rotatedaround\hbox{\tt (}\descr{pair expression} + \hbox{\tt ,}\descr{numeric expression}\hbox{\tt )}$ +\end{ctabbing} +\caption{The syntax for transforms and related operators} +\label{sytrans} +\end{figure} + +There is also a unary operator {\tt +inverse}\index{inverse?\texttt{inverse}}\label{Dinv} that takes a +transform and finds another transform that undoes the effect of the +first transform. Thus if +$$ p = q{\tt\ transformed\ }T $$ +then +$$ q = p{\tt\ transformed\ inverse\ }T. $$ + +It is not legal to take the {\tt inverse} of an +unknown transform\index{transformation!unknown} but we +have already seen that you can say +$$ \hbox{\tt T = } \descr{transform expression} $$ +when {\tt T} has not been given a value yet. It is also possible to +apply an unknown transform to a known pair or transform and use the +result in a linear equation. Three such equations are sufficient to +determine a transform. Thus the equations +$$ \begin{verbatim} +(0,1) transformed T' = (3,4); +(1,1) transformed T' = (7,1); +(1,0) transformed T' = (4,-3); +\end{verbatim} +$$ +allow MetaPost to determine that the transform {\tt T'} is a combination of +rotation and scaling with +$$\openup\jot + \tabskip=0pt plus 1fil + \halign to\displaywidth{\tabskip=0pt + \hfil$\displaystyle{#}$& $\displaystyle{{}#}$\hfil \qquad& + \hfil$\displaystyle{#}$& $\displaystyle{{}#}$\hfil + \tabskip=0pt plus 1fil\cr +\noalign{\vskip-\jot} + t_{xx}&=4,& t_{yx}&=-3,\cr + t_{yx}&=3,& t_{yy}&=4,\cr + t_x&=0,& t_y&=0.\cr} +$$ + +Equations involving an unknown transform are treated as linear equations +in the six parameters that define the transform. These six parameters +can also be referred to directly +as\index{xpart?\texttt{xpart}}\index{ypart?\texttt{ypart}}\index{xxpart?\texttt{xxpart}}% +\index{xypart?\texttt{xypart}}\index{yxpart?\texttt{yxpart}}\index{yypart?\texttt{yypart}}\label{Dtrprt} +$$ {\tt xpart\ T},\ {\tt ypart\ T},\ {\tt xxpart\ T},\ {\tt xypart\ T},\ + {\tt yxpart\ T},\ {\tt yypart\ T}, +$$ +where {\tt T} is a transform. For instance, Figure~\ref{fig27} uses the +equations +$$ \hbox{\tt xxpart T=yypart T; yxpart T=-xypart T} $$ +to specify that {\tt T} is shape preserving; i.e., it is a combination of +rotating, shifting, and uniform scaling. + +\begin{figure}[htp] +$$\begin{verbatim} +beginfig(28); +path p[]; +p1 = fullcircle scaled .6in; +z1=(.75in,0)=-z3; +z2=directionpoint left of p1=-z4; +p2 = z1..z2..{curl1}z3..z4..{curl 1}cycle; +fill p2 withcolor .4[white,black]; +unfill p1; +draw p1; +transform T; +z1 transformed T = z2; +z3 transformed T = z4; +xxpart T=yypart T; yxpart T=-xypart T; +picture pic; +pic = currentpicture; +for i=1 upto 2: + pic:=pic transformed T; + draw pic; +endfor +dotlabels.top(1,2,3); dotlabels.bot(4); +endfig; +\end{verbatim} +\quad \mathcenter{\includegraphics{mpman-28.mps}} +$$ +\caption{MetaPost code and the resulting ``fractal'' figure} +\label{fig27} +\end{figure} + + +\subsection{Dashed Lines} + +The MetaPost language provides many ways of changing the appearance of a +line besides just changing its width. One way is to use dashed lines as +was done in Figures \ref{fig4} and~\ref{fig22}. The syntax for this +is\index{dashed?\texttt{dashed}}\label{Ddashed} +$$ {\tt draw}\, \descr{path expression}\, {\tt dashed}\, \descr{dash pattern} $$ +where a \tdescr{dash pattern}\index{dash pattern?\tdescr{dash pattern}} +is really a special type of \tdescr{picture expression}. There is a +predefined \tdescr{dash pattern} called {\tt +evenly}\index{evenly?\texttt{evenly}}\label{Devenly} that makes dashes 3 +PostScript points long separated by gaps of the same size. Another +predefined dash pattern {\tt +withdots}\index{withdots?\texttt{withdots}}\label{Dwdots} produces +dotted lines with dots 5 PostScript points apart.\footnote{{\tt +withdots} is only found in MetaPost version 0.50 and higher.} For dots +further apart or longer dashes further apart, the \tdescr{dash pattern} +can be scaled\index{scaled?\texttt{scaled}} as shown in +Figure~\ref{fig28}. + +\begin{figure}[htp] +$$ \includegraphics{mpman-29.mps} $$ +\caption[Dashed lines and the corresponding dash patters] + {Dashed lines each labeled with the \tdescr{dash pattern} used to create + it.} +\label{fig28} +\end{figure} + +Another way to change a dash pattern is to alter its phase by shifting +it horizontally. Shifting to the right makes the dashes move forward +along the path and shifting to the left moves them backward. +Figure~\ref{fig29} illustrates this effect. The dash pattern can be +thought of as an infinitely repeating pattern strung out along a +horizontal line where the portion of the line to the right of the +$y$~axis is laid out along the path to be dashed\index{dash +pattern?\tdescr{dash pattern}}. + +\begin{figure}[htp] +$$ \includegraphics{mpman-30.mps} $$ +\caption[Dashed lines and the corresponding dash patters] + {Dashed lines and the MetaPost statements for drawing them where {\tt e4} + refers to the dash pattern {\tt evenly scaled 4}.} +\label{fig29} +\end{figure} + +When you shift a dash pattern so that the $y$~axis crosses the middle of +a dash, the first dash gets truncated. Thus the line with dash pattern +{\tt e4} starts with a dash of length 12bp followed by a 12bp gap and +another 12bp dash, etc., while {\tt e4 shifted (-6bp,0)} produces a 6bp +dash, a 12 bp gap, then a 12bp dash, etc. This dash pattern could be +specified more directly via the {\tt dashpattern}\index{dash +pattern?\texttt{dash pattern}}\label{Ddshpat} function: +$$ \hbox{\tt dashpattern(on 6bp off 12bp on 6bp)} $$ +This means ``draw the first 6bp of the line, then skip the next 12bp, then draw +another 6bp and repeat.'' If the line to be dashed is more than 30bp long, the +last 6bp of the first copy of the dash pattern will merge with the first 6bp of +the next copy to form a dash 12bp long. The general syntax for the +{\tt dashpattern} function is shown in Figure~\ref{sydash}. + +\begin{figure}[htp] +\begin{ctabbing} +$\tt \descr{dash pattern} \rightarrow dashpattern + \hbox{\tt (}\descr{on/off list}\hbox{\tt )}$\\ +$\tt \descr{on/off list} \rightarrow + \descr{on/off list}\descr{on/off clause} \;|\; \descr{on/off clause}$\\ +$\tt \descr{on/off clause} \rightarrow on \descr{numeric tertiary} + \;|\; off \descr{numeric tertiary}$ +\end{ctabbing} +\caption{The syntax for the {\tt dashpattern} function} +\label{sydash} +\end{figure} + +Since a dash pattern is really just a special kind of picture, the {\tt +dashpattern} function returns a picture. It is not really necessary to +know the structure of such a picture, so the casual reader will probably +want to skip on to Section~\ref{oopt}. For those who want to know, a +little experimentation shows that if {\tt d} is +$$ \hbox{\tt dashpattern(on 6bp off 12bp on 6bp)}, $$ +then {\tt llcorner d} is $(0,24)$ and {\tt urcorner d} is $(24,24)$. +Drawing {\tt d} directly without using it as a dash pattern produces two +thin horizontal line segments like this: +$$ \includegraphics{mpman-31.mps} $$ +The lines in this example are specified as having width zero, but this +does not matter because the line width is ignored when a picture is used +as a dash pattern. + +The general rule for interpreting a picture {\tt d} as a dash pattern is +that the line segments in {\tt d} are projected onto the $x$-axis and +the resulting pattern is replicated to infinity in both directions by +placing copies of the pattern end-to-end. The actual dash lengths are +obtained by starting at $x=0$ and scanning in the positive $x$ +direction. + +To make the idea of ``replicating to infinity'' more precise, let $P({\tt d})$ +be the projection of {\tt d} onto the $x$~axis, and let +${\rm shift}(P({\tt d}),x)$ be the result of shifting {\tt d} by~$x$. +The pattern resulting from infinite replication is +$$ \bigcup_{{\rm integers}\ n} {\rm shift}(P(d),\, n\cdot\ell(d)), $$ +where $\ell(d)$ measures the length of $P(d)$. The most restrictive possible +definition of this length is $d_{\rm max}-d_{\rm min}$, +where $[d_{\rm min},d_{\rm max}]$ +is the range of $x$~coordinates in $P(d)$. In fact, MetaPost uses +$$ \max(\left|y_0({\tt d})\right|,\, d_{\rm max}-d_{\rm min}), $$ +where $y_0({\tt d})$ is the $y$ coordinate of the contents of {\tt d}. +The contents of {\tt d} should lie on a horizontal line, but if they do +not, the MetaPost interpreter just picks a $y$~coordinate that occurs in +{\tt d}\index{dash pattern?\tdescr{dash pattern}}. + +A picture used as a dashed pattern must contain no text or filled +regions, but it can contain lines that are themselves dashed. This can +give small dashes inside of larger dashes as shown in +Figure~\ref{fig32}.\index{dash pattern?\tdescr{dash pattern}!recursive} + +\begin{figure}[htp] +$$\begin{verbatim} +beginfig(32); +draw dashpattern(on 15bp off 15bp) dashed evenly; +picture p; +p=currentpicture; +currentpicture:=nullpicture; +draw fullcircle scaled 1cm xscaled 3 dashed p; +endfig; +\end{verbatim} +\quad \mathcenter{\includegraphics{mpman-32.mps}} +$$ +\caption{MetaPost code for dashed patterns and the corresponding output} +\label{fig32} +\end{figure} + +\label{dashed-pens} +Also, dashed patterns are intended to be used either with {\tt +pencircle} or no pen at all; {\tt pensquare} and other complex pens +should be avoided. This is because the output uses the PostScript +primitive {\tt setdash}, which does not interact well with the filled +paths created by polygonal pens. See Section~\ref{sec.pens}, p.\ +\pageref{sec.pens}. + +%\newpage + +\subsection{Local specials} + +If you want to attach a special bit of PostScript code, you can use +$$ +{\tt withprescript} \descr{string expression}% +\index{withprescript?\texttt{withprescript}}\label{Dwithpre} +$$ +and +$$ +{\tt withpostscript} \descr{string expression}% +\index{withpostscript?\texttt{withpostscript}}\label{Dwithpost} +$$ +The strings will be written to the output file before and after the +current object, each beginning on their own line. You can specify +multiple {\tt withprescript} or {\tt withpostscript} options if you +like. + +When you specify more than one {\tt withprescript} or more than one {\tt + withpostscript} option, be wary of the fact that the scripts use a +form of nesting: the {\tt withprescript} items are written to the +PostScript file in last in, first out order; whereas the {\tt + withpostscript} items are written in first in, first out order. + +\subsection{Other Options} +\label{oopt} + +You might have noticed that the dashed lines produced by {\tt dashed +evenly}\index{evenly?\texttt{evenly}} appear to have more black than +white. This is an effect of the {\tt +linecap}\index{linecap?\texttt{linecap}}\label{Dlinecap} parameter that +controls the appearance of the ends of lines as well as the ends of +dashes. There are also a number of other ways to affect the appearance +of things drawn with MetaPost. + +The {\tt linecap} parameter has three different settings just as in +PostScript. Plain MetaPost gives this internal variable\index{internal +variables}\index{variables!internal} the default value {\tt +rounded}\index{rounded?\texttt{rounded}} which causes line segments to +be drawn with rounded ends like the segment from {\tt z0} to {\tt z3} in +Figure~\ref{fig33}. Setting ${\tt linecap}\mathrel{\hbox{\tt:=}}{\tt +butt}$\index{butt?\texttt{butt}}\label{Dbutt} cuts the ends off flush so +that dashes produced by {\tt dashed +evenly}\index{evenly?\texttt{evenly}} have length 3bp, not 3bp plus the +line width. You can also get squared-off ends that extend past the +specified endpoints by setting ${\tt linecap}\mathrel{\hbox{\tt:=}}{\tt +squared}$\index{squared?\texttt{squared}}\label{Dsqred} as was done in +the line from {\tt z2} to {\tt z5} in Figure~\ref{fig33}. + +\begin{figure}[htp] +$$\begin{verbatim} +beginfig(33); +for i=0 upto 2: + z[i]=(0,40i); z[i+3]-z[i]=(100,30); +endfor +pickup pencircle scaled 18; +draw z0..z3 withcolor .8white; +linecap:=butt; +draw z1..z4 withcolor .8white; +linecap:=squared; +draw z2..z5 withcolor .8white; +dotlabels.top(0,1,2,3,4,5); +endfig; linecap:=rounded; +\end{verbatim} +\qquad +\mathcenter{\includegraphics{mpman-33.mps}} +$$ +\caption{MetaPost code and the corresponding output} +\label{fig33} +\end{figure} + +Another parameter borrowed from PostScript affects the way a {\tt draw} +statement treats sharp corners\index{corners} in the path to be drawn. +The {\tt linejoin}\index{linejoin?\texttt{linejoin}}\label{Dlinejoin} +parameter can be {\tt +rounded}\index{rounded?\texttt{rounded}}\label{Drnded}, {\tt +beveled}\index{beveled?\texttt{beveled}}\label{Dbvled}, or {\tt +mitered}\index{mitered?\texttt{mitered}}\label{Dmitred} as shown in +Figure~\ref{fig34}. The default value for plain MetaPost is {\tt +rounded} which gives the effect of drawing with a circular brush. + +\begin{figure}[htp] +$$\begin{verbatim} +beginfig(34); +for i=0 upto 2: + z[i]=(0,50i); z[i+3]-z[i]=(60,40); + z[i+6]-z[i]=(120,0); +endfor +pickup pencircle scaled 24; +draw z0--z3--z6 withcolor .8white; +linejoin:=mitered; +draw z1..z4--z7 withcolor .8white; +linejoin:=beveled; +draw z2..z5--z8 withcolor .8white; +dotlabels.bot(0,1,2,3,4,5,6,7,8); +endfig; linejoin:=rounded; +\end{verbatim} +\qquad +\mathcenter{\includegraphics{mpman-34.mps}} +$$ +\caption{MetaPost code and the corresponding output} +\label{fig34} +\end{figure} + +When {\tt linejoin} is {\tt mitered}, sharp corners generate long +pointed features as shown in Figure~\ref{fig35}. Since this might be +undesirable, there is an internal variable\index{internal +variables}\index{variables!internal} called {\tt +miterlimit}\index{miterlimit?\texttt{miterlimit}}\label{Dmiterlim} that +controls how extreme the situation can get before the mitered join is +replaced by a beveled join. For Plain MetaPost, {\tt miterlimit} has a +default value of 10.0 and line joins revert to beveled when the ratio of +miter length to line width reaches this value. + +\begin{figure}[htp] +$$ \includegraphics{mpman-35.mps} $$ +\caption{The miter length and line width whose ratio is limited by + {\tt miterlimit}.} +\label{fig35} +\end{figure} + +The {\tt linecap}, {\tt linejoin}, and {\tt miterlimit} parameters are +especially important because they also affect things that get drawn +behind the scenes. For instance, Plain MetaPost has statements for +drawing arrows\index{arrows}, and the arrowheads are slightly rounded +when {\tt linejoin} is {\tt rounded}. The effect depends on the line +width and is quite subtle at the default line width of 0.5bp as shown in +Figure~\ref{fig36}. + +\begin{figure}[htp] +$$\includegraphics{mpman-36.mps}$$ +\caption{Three ways of drawing arrows.} +\label{fig36} +\end{figure} + +Drawing arrows like the ones in Figure~\ref{fig36} is simply a matter of +saying\index{drawarrow?\texttt{drawarrow}}\label{Ddrwarr} +$$ {\tt drawarrow}\, \descr{path expression} $$ +instead of {\tt draw} \tdescr{path expression}. This draws the given +path with an arrowhead at the last point on the path. If you want the +arrowhead at the beginning of the path, just use the unary operator {\tt +reverse}\index{reverse?\texttt{reverse}}\label{Drevrse} to take the +original path and make a new one with its time sense reversed; i.e., for +a path~{\tt p} with {\tt length p}${}=n$, +$$ {\tt point\ } t {\tt\ of\ reverse\ p} + \quad {\rm and} \quad + {\tt point\ } n-t {\tt\ of\ p} +$$ are synonymous. + +As shown in Figure~\ref{fig36}, a statement +beginning\index{drawdblarrow?\texttt{drawdblarrow}}% +\index{arrows!double-headed}\label{Ddrwdar} +$$ {\tt drawdblarrow}\, \descr{path expression} $$ +draws a double-headed arrow. The size of the arrowhead is guaranteed to +be larger than the line width, but it might need adjusting if the line +width is very great. This is done by assigning a new value to the +internal variable\index{internal variables}\index{variables!internal} +{\tt ahlength}\index{ahlength?\texttt{ahlength}}\label{Dahlength} that +determines arrowhead length as shown in Figure~\ref{fig37}. Increasing +{\tt ahlength} from the default value of 4 PostScript points to 1.5 +centimeters produces the large arrowhead in Figure~\ref{fig37}. There +is also an {\tt ahangle}\index{ahangle?\texttt{ahangle}}\label{Dahangle} +parameter that controls the angle at the tip of the arrowhead. The +default value of this angle is 45 degrees as shown in the figure. + +\begin{figure}[htp] +$$ \includegraphics{mpman-37.mps} $$ +\caption[A large arrowhead with key parameters labeled.] + {A large arrowhead with key parameters labeled and paths used to + draw it marked with white lines.} +\label{fig37} +\end{figure} + +The arrowhead is created by filling the triangular region that is +outlined in white in Figure~\ref{fig37} and then drawing around it with +the currently picked up pen. This combination of filling and drawing +can be combined into a single {\tt filldraw} +statement\index{filldraw?\texttt{filldraw}}\label{Dfildrw}: +$$ {\tt filldraw}\, \descr{path expression}\, + \descr{optional {\tt dashed} and {\tt withcolor} and {\tt withpen} clauses}; +$$ +The \tdescr{path expression} should be a closed cycle like the +triangular path in Figure~\ref{fig37}. This path should not be confused +with the path argument to {\tt drawarrow} which is indicated by a white +line in the figure. + +White lines like the ones in the figure can be created by an {\tt +undraw}\index{undraw?\texttt{undraw}}\label{Dundraw} statement. This is +an erasing\index{erasing} version of {\tt draw} that draws {\tt +withcolor background}\index{background?\texttt{background}} just as the +{\tt unfill} statement does. There is also an {\tt +unfilldraw}\index{unfilldraw?\texttt{unfilldraw}}\label{Dunfdrw} +statement just in case someone finds a use for it. + +The {\tt filldraw}, {\tt undraw} and {\tt unfilldraw} statements and all +the arrow drawing statements are like the {\tt fill} and {\tt draw} +statements in that they take {\tt dashed}\index{dashed?\texttt{dashed}}, +{\tt withpen}\index{withpen?\texttt{withpen}}, and {\tt +withcolor}\index{withcolor?\texttt{withcolor}} options. When you have a +lot of drawing statements it is nice to be able to apply an option such +as {\tt withcolor 0.8white} to all of them without having to type this +repeatedly as was done in Figures \ref{fig33} and~\ref{fig34}. The +statement for this purpose +is\index{drawoptions?\texttt{drawoptions}}\label{Ddropts} +$$ \hbox{\tt drawoptions(} \descr{text} \hbox{\tt )} $$ +where the \tdescr{text} argument gives a sequence of {\tt dashed}, {\tt +withcolor}, and {\tt withpen} options to be applied automatically to all +drawing statements. If you specify +$$ \hbox{\tt drawoptions(withcolor .5[black,white])} $$ +and then want to draw a black line, you can override the {\tt drawoptions} +by specifying +$$ {\tt draw}\, \descr{path expression}\, {\tt withcolor\ black} $$ +To turn off {\tt drawoptions} all together, just give an empty list: +$$ \hbox{\tt drawoptions()} $$ +(This is done automatically by the {\tt +beginfig}\index{beginfig?\texttt{beginfig}} macro). + +Since irrelevant options are ignored, there is no harm in giving a statement +like +$$ \hbox{\tt drawoptions(dashed evenly)} $$ +followed by a sequence of {\tt draw} and {\tt fill} commands. It does +not make sense to use a dash pattern when filling so the {\tt dashed +evenly} gets ignored for {\tt fill} statements. It turns out that +$$ \hbox{\tt drawoptions(withpen } \descr{pen expression} \hbox{\tt )} $$ +does affect {\tt fill} statements as well as {\tt draw} statements. +In fact there is a special pen variable called +{\tt currentpen}\index{currentpen?\texttt{currentpen}} such that +{\tt fill} \ldots\ {\tt withpen currentpen} is equivalent to a {\tt filldraw} +statement. + +Precisely what does it mean to say that drawing options affect those +statements where they make sense? The {\tt dashed} \tdescr{dash +pattern} option only affects +$$ {\tt draw}\, \descr{path expression} $$ +statements, and text appearing in the \tdescr{picture expression} argument to +$$ {\tt draw}\, \descr{picture expression} $$ +statement is only affected by the {\tt withcolor} \tdescr{color +expression} option. For all other combinations of drawing statements +and options, there is some effect. An option applied to a {\tt draw} +\tdescr{picture expression} statement will in general affect some parts +of the picture but not others. For instance, a {\tt dashed} or {\tt +withpen} option will affect all the lines in the picture but none of the +labels. + + +\subsection{Pens} +\label{sec.pens} + +Previous sections have given numerous examples of {\tt pickup} +\tdescr{pen expression} and {\tt withpen} \tdescr{pen expression}, but +there have not been any examples of pen expressions other than +$$ {\tt pencircle\ scaled}\, \descr{numeric primary} $$ +which produces lines of a specified width. For calligraphic effects +such in Figure~\ref{fig38}, you can apply any of the transformation +operators discussed in Section~\ref{transsec}. The starting point for +such transformations is {\tt +pencircle}\index{pencircle?\texttt{pencircle}}\label{Dpncirc}, a circle +one PostScript point in diameter. Thus affine transformations produce a +circular or elliptical\index{pens!elliptical} pen shape. The width of +lines drawn with the pen depends on how nearly perpendicular the line is +to the long axis of the ellipse. + +\begin{figure}[htp] +$$\begin{verbatim} +beginfig(38); +pickup pencircle scaled .2in yscaled .08 rotated 30; +x0=x3=x4; +z1-z0 = .45in*dir 30; +z2-z3 = whatever*(z1-z0); +z6-z5 = whatever*(z1-z0); +z1-z6 = 1.2*(z3-z0); +rt x3 = lft x2; +x5 = .55[x4,x6]; +y4 = y6; +lft x3 = bot y5 = 0; +top y2 = .9in; +draw z0--z1--z2--z3--z4--z5--z6 withcolor .7white; +dotlabels.top(0,1,2,3,4,5,6); +endfig; +\end{verbatim} +\quad \mathcenter{\includegraphics{mpman-38.mps}} +$$ +\caption{MetaPost code and the resulting ``calligraphic'' figure.} +\label{fig38}\index{lft?\texttt{lft}}\index{bot?\texttt{bot}}\index{top?\texttt{top}} +\end{figure} + +Figure~\ref{fig38} demonstrates operators {\tt +lft}\index{lft?\texttt{lft}}\label{Dlft}, {\tt +rt}\index{rt?\texttt{rt}}\label{Drt}, {\tt +top}\index{top?\texttt{top}}\label{Dtop}, and {\tt +bot}\index{bot?\texttt{bot}}\label{Dbot} that answer the question, ``If +the current pen is placed at the position given by the argument, where +will its left, right, top, or bottom edge be?'' In this case the +current pen is the ellipse given in the {\tt pickup} statement and its +bounding box is 0.1734 inches wide and 0.1010 inches high, so {\tt rt +x3} is ${\tt x3}+{\tt 0.0867in}$ and {\tt bot y5} is ${\tt y5}-{\tt +0.0505in}$. The {\tt lft}, {\tt rt}, {\tt top}, and {\tt bot} operators +also accept arguments of type pair in which case they compute the $x$ +and~$y$ coordinates of the leftmost, rightmost, topmost, or bottommost +point on the pen shape. For example, +$$ {\tt rt}(x,y) = (x,y)+({\tt 0.0867in}, {\tt 0.0496in}) $$ +for the pen in Figure~\ref{fig38}. Note that {\tt +beginfig}\index{beginfig?\texttt{beginfig}} resets the current pen to a +default value of +$$ \hbox{\tt pencircle scaled 0.5bp} $$ +at the beginning of each figure. This value can be reselected at any +time by giving the command {\tt pickup +defaultpen}\index{defaultpen?\texttt{defaultpen}}\label{Ddefaultpen}. + +This would be the end of the story on pens, except that for +compatibility with \MF\index{metafont?\MF}, MetaPost also allows pen +shapes to be polygonal\index{pens!polygonal}. There is a predefined pen +called {\tt pensquare}\index{pensquare?\texttt{pensquare}}\label{Dpnsqr} +that can be transformed to yield pens shaped like parallelograms. + +In fact, there is even an operator called {\tt +makepen}\index{makepen?\texttt{makepen}}\label{Dmkpen} that takes a +convex-polygon-shaped path and makes a pen that shape and size. If the +path is not exactly convex or polygonal, the {\tt makepen} operator will +straighten the edges and/or drop some of the vertices. In particular, +{\tt pensquare} is equivalent to +$$ \hbox{\verb|makepen((-.5,-.5)--(.5,-.5)--(.5,.5)--(-.5,.5)--cycle)|} $$ + +{\tt pensquare} and {\tt makepen} should not be used with dash +patterns. See the end of Section~\ref{dashed-pens}, p.\ +\pageref{dashed-pens}. + +The inverse of {\tt makepen} is the {\tt +makepath}\index{makepath?\texttt{makepath}}\label{Dmkpath} operator that +takes a \tdescr{pen primary} and returns the corresponding path. Thus +{\tt makepath pencircle} produces a circular path identical to {\tt +fullcircle}\index{fullcircle?\texttt{fullcircle}}. This also works for +a polygonal pen so that +$$ {\tt makepath\ makepen}\, \descr{path expression} $$ +will take any cyclic path and turn it into a convex polygon\index{convex polygons}. + + +\subsection{Clipping and Low-Level Drawing Commands} + +Drawing statements such as {\tt draw}, {\tt fill}, {\tt filldraw}, and +{\tt unfill} are part of the Plain macro\index{Plain macros} package and +are defined in terms of more primitive statements. The main difference +between the drawing statements discussed in previous sections and the +more primitive versions is that the primitive drawing statements all +require you to specify a picture variable to hold the results. For {\tt +fill}, {\tt draw}, and related statements, the results always go to a +picture variable called {\tt +currentpicture}\index{currentpicture?\texttt{currentpicture}}\label{Dcurpic}. +The syntax for the primitive drawing statements that allow you to +specify a picture variable is shown in Figure~\ref{sydraw}. + +\begin{figure}[htp] +\begin{ctabbing} +$\tt \descr{addto command} \rightarrow$\\ +$\tt \qquad addto \descr{picture variable} also + \descr{picture expression} \descr{option list}$\\ +$\tt \qquad \;|\; addto \descr{picture variable} + contour \descr{path expression} \descr{option list}$\\ +$\tt \qquad \;|\; addto \descr{picture variable} + doublepath \descr{path expression} \descr{option list}$\\ +$\tt \descr{option list} \rightarrow \descr{empty} \;|\; + \descr{drawing option} \descr{option list}$\\ +$\tt \descr{drawing option} \rightarrow withcolor \descr{color expression}$\\ +$\tt \qquad \;|\; withrgbcolor \descr{rgbcolor expression} \;|\; + withcmykcolor \descr{cmykcolor expression}$\\ +$\tt \qquad \;|\; withgreyscale \descr{numeric expression} \;|\; + withoutcolor$\\ +$\tt \qquad \;|\; withprescript \descr{string expression} \;|\; + withpostscript \descr{string expression}$\\ +$\tt \qquad \;|\; withpen \descr{pen expression} \;|\; + dashed \descr{picture expression}$ +\end{ctabbing} +\caption{The syntax for primitive drawing statements} +\label{sydraw} +\index{option list?\tdescr{option list}}\index{addto also?\texttt{addto also}}\index{addto contour?\texttt{addto contour}}% +\index{addto doublepath?\texttt{addto doublepath}}\index{withcolor?\texttt{withcolor}}\index{withpen?\texttt{withpen}}% +\index{dashed?\texttt{dashed}}\index{drawing option?\tdescr{drawing option}} +\end{figure} + +The syntax for primitive drawing commands is compatible with +\MF\index{metafont?\MF}. Table~\ref{draweqv} shows how the primitive +drawing statements relate to the familiar {\tt draw} and {\tt fill} +statements. Each of the statements in the first column of the table +could be ended with an \tdescr{option list} of its own, which is +equivalent to appending the \tdescr{option list} to the corresponding +entry in the second column of the table. For example, +$$ {\tt draw}\ p\ {\tt withpen\ pencircle} $$ +is equivalent to +$$ {\tt addto\ currentpicture\ doublepath}\ p\ + {\tt withpen\ currentpen\ withpen\ pencircle} +$$ +where {\tt +currentpen}\index{currentpen?\texttt{currentpen}}\label{Dcurpen} is a +special pen variable that always holds the last pen picked up. The +second {\tt withpen} option silently overrides the {\tt withpen +currentpen} from the expansion of {\tt draw}. + +\begin{table}[htp] +$$\begin{tabular}{|l|l|} \hline +\multicolumn1{|c|}{statement}& \multicolumn1{c|}{equivalent primitives}\\ \hline +{\tt draw} {\it pic}& {\tt addto currentpicture also} {\it pic}\\ +{\tt draw} $p$& {\tt addto currentpicture doublepath} $p$ + {\tt withpen} $q$\\ +{\tt fill} $c$& {\tt addto currentpicture contour} $c$\\ +{\tt filldraw} $c$& {\tt addto currentpicture contour} $c$ {\tt withpen} $q$\\ +{\tt undraw} {\it pic}& {\tt addto currentpicture also} {\it pic} + {\tt withcolor} $b$\\ +{\tt undraw} $p$& {\tt addto currentpicture doublepath} $p$ + {\tt withpen} $q$ + {\tt withcolor} $b$\\ +{\tt unfill} $c$& {\tt addto currentpicture contour} $c$ + {\tt withcolor} $b$\\ +{\tt unfilldraw} $c$& {\tt addto currentpicture contour} $c$ {\tt withpen} $q$ + {\tt withcolor} $b$\\ \hline +\end{tabular} +$$ +\caption[Drawing statements and equivalent primitive commands] {Common + drawing statements and equivalent primitive versions, where $q$ + stands for {\tt currentpen}, $b$ stands for {\tt background}, + $p$ stands for any path, $c$ stands for a cyclic path, and {\it + pic} stands for a \tdescr{picture expression}. Note that + nonempty {\tt drawoptions} would complicate the entries in the + second column.} +\label{draweqv} +\index{drawoptions?\texttt{drawoptions}} +\end{table} + + +There are two more primitive drawing commands that do not accept any +drawing options. One is the {\tt setbounds} command that was discussed +in Section~\ref{meas}; the other is the {\tt clip} +command\index{clip?\texttt{clip}}\label{Dclip}: +$$ {\tt clip}\, \descr{picture variable}\, {\tt to}\, \descr{path expression} $$ +Given a cyclic path, this statement trims the contents of the +\tdescr{picture variable} to eliminate everything outside of the cyclic path. +There is no ``high level'' version of this statement, so you have to use +$$ {\tt clip\ currentpicture\ to}\, \descr{path expression} $$ +if you want to clip {\tt +currentpicture}\index{currentpicture?\texttt{currentpicture}}. +Figure~\ref{fig40} illustrates clipping. + +\begin{figure}[htp] +$$\begin{verbatim} +beginfig(40); +path p[]; +p1 = (0,0){curl 0}..(5pt,-3pt)..{curl 0}(10pt,0); +p2 = p1..(p1 yscaled-1 shifted(10pt,0)); +p0 = p2; +for i=1 upto 3: p0:=p0.. p2 shifted (i*20pt,0); + endfor +for j=0 upto 8: draw p0 shifted (0,j*10pt); + endfor +p3 = fullcircle shifted (.5,.5) scaled 72pt; +clip currentpicture to p3; +draw p3; +endfig; +\end{verbatim} +\qquad +\mathcenter{\includegraphics{mpman-40.mps}} +$$ +\caption{MetaPost code and the resulting ``clipped'' figure.} +\label{fig40} +\end{figure} + +All the primitive drawing operations would be useless without one last +operation called {\tt shipout}. The +statement\index{shipout?\texttt{shipout}}\label{Dship} +$$ {\tt shipout}\, \descr{picture expression} $$ +writes out a picture as a PostScript\index{PostScript} file whose +file name is determined by +{\tt outputtemplate}\index{outputtemplate?\texttt{outputtemplate}} +(see section~\ref{outputfilenames}). By default, the file name ends +{\tt.}{\it nnn}, where {\tt nnn} is the decimal representation +of the value of the internal variable\index{internal +variables}\index{variables!internal} {\tt +charcode}\index{charcode?\texttt{charcode}}\label{Dcharcode}. (The name +``{\tt charcode}'' is for compatibility with \MF\index{metafont?\MF}.) +Normally, {\tt beginfig}\index{beginfig?\texttt{beginfig}} sets {\tt +charcode}, and {\tt endfig}\index{endfig?\texttt{endfig}} invokes {\tt +shipout}. + +\subsection{Directing Output to a Picture Variable} +Sometimes, it might be desirable to save the output of a drawing +operation and re-use them later. This can easily be done with +MetaPost primitives like \ttt{addto}. On the other hand, since the +higher-level drawing commands defined in the Plain macro package +always write to the +\ttt{currentpicture}\index{currentpicture?\texttt{currentpicture}}, +saving their output required to temporarily save \ttt{currentpicture}, +reset it to \ttt{nullpicture}\index{nullpicture?\texttt{nullpicture}}, +execute the drawing operations, save the \ttt{currentpicture} to a +new \ttt{picture} variable and finally restore \ttt{currentpicture} to +the saved state. In MetaPost version~0.60 a new macro +$$ \hbox{\tt image( $\descr{drawing commands}$ )} $$% +\index{image?\texttt{image}}\label{Dimage}% +was introduced that eases this task. It takes as input a sequence of arbitrary +drawing operations and returns a \ttt{picture} variable containing the +corresponding output, without affecting {\tt currentpicture}. + +As an example, in the code of figure~\ref{fig55} an object \ttt{wheel} has +been defined that saves the output of two \ttt{draw} operations as follows: +\begin{figure}[b] +$$ \includegraphics{mpman-55.mps} $$ +\caption{Copying objects with the \ttt{image} operator.} +\label{fig55} +\end{figure} +$$\begin{verbatim} +picture wheel; +wheel := image( + draw fullcircle scaled 2u xscaled .8 rotated 30; + draw fullcircle scaled .15u xscaled .8 rotated 30; +); +\end{verbatim} +$$ +This \ttt{wheel} object is re-used in the definition of another object \ttt{car}. +Figure~\ref{fig55} shows three \ttt{car} objects drawn with two different slant +values. + + +\subsection{Inspecting the Components of a Picture} +\label{piccomp} + +\mbox{}% Start paragraph here. +\index{setbounds?\texttt{setbounds}|(}% +\index{for within?\texttt{for within}|(}% +% +MetaPost pictures are composed of stroked lines, filled outlines, pieces +of typeset text, clipping paths\index{clip?\texttt{clip}}, and +{\tt setbounds}\index{setbounds?\texttt{setbounds}} paths. (A {\tt setbounds} +path gives an artificial bounding box as is needed for \TeX\ output.) +A picture can have many components of each type. They can be accessed via +an iteration of the form +$$ {\tt for}\ \descr{symbolic token}\ {\tt within}\ + \descr{picture expression}\hbox{\tt:}\ \descr{loop text}\ {\tt endfor} +$$\index{for within?\texttt{for within}}\label{Dforwithin}% +The \tdescr{loop text} can be anything that is balanced with respect to +{\tt for} and {\tt endfor}. The \tdescr{symbolic token} is a loop variable that +scans the components of the picture in the order in which they were drawn. The +component for a clipping or {\tt setbounds} path includes everything the path +applies to. Thus if a single clipping or {\tt setbounds} path applies to +everything in the \tdescr{picture expression}, the whole picture could be +thought of as one big component. In order to make the contents of such a picture +accessible, the {\tt for}\ldots{\tt within} iteration ignores the enclosing +clipping or {\tt setbounds} path in this case. The number of components +that a {\tt for}\ldots {\tt within} iteration would find is returned by +$$ {\tt length}\ \descr{picture primary}\index{length?\texttt{length}}\label{DlengthPicture}$$ + +\index{for within?\texttt{for within}|)} + +\mbox{}% Start paragraph here. +\index{stroked?\texttt{stroked}|(}% +\index{filled?\texttt{filled}|(}% +\index{textual?\texttt{textual}|(}% +\index{clipped?\texttt{clipped}|(}% +\index{bounded?\texttt{bounded}|(}% +% +Once the {\tt for}\ldots{\tt within} iteration has found a picture component, +there are numerous operators for identifying it and extracting relevant +information. The operator +$$ {\tt stroked}\ \descr{primary expression} $$\index{stroked?\texttt{stroked}}\label{Dstroked}% +tests whether the expression is a known picture whose first component is a +stroked line. Similarly, the {\tt filled}\index{filled?\texttt{filled}}\label{Dfilled} +and {\tt textual}\index{textual?\texttt{textual}}\label{Dtextual} operators +return {\tt true} if the first component is a filled outline or a piece of +typeset text. The {\tt clipped}\index{clipped?\texttt{clipped}}\label{Dclipped} +and {\tt bounded}\index{bounded?\texttt{bounded}}\label{Dbounded} operators +test whether the argument is a known picture that starts with a clipping +path or a {\tt setbounds} path. This is true if the first component is +clipped or bounded or if the entire picture is enclosed in a clipping or +{\tt setbounds} path. + +\mbox{}% Start paragraph here. +\index{pathpart?\texttt{pathpart}|(}% +\index{penpart?\texttt{penpart}|(}% +\index{dashpart?\texttt{dashpart}|(}% +% +There are also numerous part extraction operators that test the first component +of a picture. If {\tt p} is a picture and {\tt stroked p} is true, +{\tt pathpart p}\index{pathpart?\texttt{pathpart}}\label{Dpathpart} is the +path describing the line that got stroked, +{\tt penpart p}\index{penpart?\texttt{penpart}}\label{Dpenpart} is the pen +that was used, {\tt dashpart p}\index{dashpart?\texttt{dashpart}}\label{Ddashpart} +is the dash pattern. If the line is not dashed, {\tt dashpart p} +returns an empty picture. + +The same part extraction operators work when {\tt filled p} is true, except +that {\tt dashpart p} is not meaningful in that case. + +For text components, {\tt textual p} is true, +{\tt textpart p}\index{textpart?\texttt{textpart}}\label{Dtextpart} +gives the text that got typeset, +{\tt fontpart p}\index{fontpart?\texttt{fontpart}}\label{Dfontpart} +gives the font that was used, and {\tt xpart~p}\index{xpart?\texttt{xpart}}\index{ypart?\texttt{ypart}}\index{xxpart?\texttt{xxpart}}% +\index{xypart?\texttt{xypart}}\index{yxpart?\texttt{yxpart}}\index{yypart?\texttt{yypart}}, +{\tt ypart~p}, {\tt xxpart~p}, {\tt xypart~p}, {\tt yxpart~p}, {\tt yypart~p} +tell how the text has been shifted, rotated, and scaled. + +\mbox{}% Start paragraph here. +\index{colorpart?\texttt{colorpart}|(}% +\index{colormodel?\texttt{colormodel}|(}% +\index{redpart?\texttt{redpart}|(}% +\index{greenpart?\texttt{greenpart}|(}% +\index{bluepart?\texttt{bluepart}|(}% +\index{cyanpart?\texttt{cyanpart}|(}% +\index{magentapart?\texttt{magentapart}|(}% +\index{yellowpart?\texttt{yellowpart}|(}% +\index{blackpart?\texttt{blackpart}|(}% +\index{greypart?\texttt{greypart}|(}% +% +Finally, for \ttt{stroked}, \ttt{filled} and \ttt{textual} components +the color can be examined by saying +$$ {\tt colorpart}\ +\descr{item}\index{colorpart?\texttt{colorpart}}\label{Dcolorpart} +$$ +This returns the color of a component in its respective color model. +The color model of a component can be identified by the +\ttt{colormodel}\index{colormodel?\texttt{colormodel}}\label{Dcolormodel} +operator (cf. Table~\ref{dfltcmod} on p.~\pageref{dfltcmod}). + +For more fine grained color operations there are operators to extract +single color components of an item. Depending on the color model the +color of a picture component \ttt{p} is +$$ \hbox{\tt (cyanpart p, magentapart p, yellowpart p, blackpart p)} $$% +\index{cyanpart?\texttt{cyanpart}}\index{magentapart?\texttt{magentapart}}\index{yellowpart?\texttt{yellowpart}}\index{blackpart?\texttt{blackpart}} +or +$$ \hbox{\tt (redpart p, greenpart p, bluepart p)} $$% +\index{redpart?\texttt{redpart}}\index{greenpart?\texttt{greenpart}}\index{bluepart?\texttt{bluepart}} +or +$$ \hbox{\tt greypart p} $$% +\index{greypart?\texttt{greypart}} +or +$$ \hbox{\tt false}. $$ + +Note, color part operators {\tt redpart}, {\tt cyanpart} etc. have to +match the color model of the picture component in question. Applying a +non-matching color part operator to a picture component triggers an +error and returns a \ttindex{black} color part in the requested color +model. That is, for the code +$$\begin{verbatim} +picture pic; +pic := image(fill unitsquare scaled 1cm withcolor (0.3, 0.6, 0.9);); +for item within pic: + show greypart item; + show cyanpart item; + show blackpart item; + show redpart item; +endfor +\end{verbatim} +$$ +the output is (omitting the error messages) +$$\begin{verbatim} +>> 0 +>> 0 +>> 1 +>> 0.3 +\end{verbatim} +$$ +since in grey scale color model black is {\tt 0} and in CMYK color model +black is {\tt (0,0,0,1)}. For the matching RGB color model the true +color component is returned. + +When {\tt clipped p} or {\tt bounded p} is true, {\tt pathpart p} gives the +clipping or {\tt setbounds} path and the other part extraction operators are +not meaningful. Such non-meaningful part extractions do not generate +errors. Instead, they return null values or black color (components): +the trivial path {\tt (0,0)} for {\tt pathpart}, +{\tt nullpen}\index{nullpen?\texttt{nullpen}}\label{Dnlpen} for {\tt penpart}, +an empty picture for {\tt dashpart}, +the null string for {\tt textpart} or {\tt fontpart}, +zero for {\tt colormodel}, +{\tt greypart}, +{\tt redpart}, {\tt greenpart}, {\tt bluepart}, +{\tt cyanpart}, {\tt magentapart}, {\tt yellowpart}, +one for {\tt blackpart}, and +black in the current default color model for {\tt colorpart}. + +To summarize the discussion of mismatching part operators: +\begin{enumerate} +\item Asking for non-meaningful parts of an item---such as the {\tt + redpart} of a clipping path, the {\tt textpart} of a stroked item, + or the {\tt pathpart} of a textual item---is silently accepted and + returns a null value or a black color (component). +\item Explicitly asking for a color part of a colored item in the wrong + color model returns a black color component. This operation triggers + an error. +\end{enumerate} + +\index{setbounds?\texttt{setbounds}|)} +\index{stroked?\texttt{stroked}|)} +\index{filled?\texttt{filled}|)} +\index{textual?\texttt{textual}|)} +\index{clipped?\texttt{clipped}|)} +\index{bounded?\texttt{bounded}|)} +\index{pathpart?\texttt{pathpart}|)} +\index{penpart?\texttt{penpart}|)} +\index{dashpart?\texttt{dashpart}|)} +\index{colormodel?\texttt{colormodel}|)} +\index{colorpart?\texttt{colorpart}|)} +\index{redpart?\texttt{redpart}|)} +\index{greenpart?\texttt{greenpart}|)} +\index{bluepart?\texttt{bluepart}|)} +\index{cyanpart?\texttt{cyanpart}|)} +\index{magentapart?\texttt{magentapart}|)} +\index{yellowpart?\texttt{yellowpart}|)} +\index{blackpart?\texttt{blackpart}|)} +\index{greypart?\texttt{greypart}|)} + + +\subsection{Decomposing the glyphs of a font} +\label{glyphs} + +MetaPost provides a primitive to convert a glyph of a font in the Adobe +Type~1 Font\index{PostScript!fonts}\index{font!PostScript}\index{Adobe + Type~1 Font}\index{font!Adobe Type~1} format into its constituent +filled paths---the strokes---and store them in a picture variable. A +glyph\index{font!glyph} is the visual representation of a character in a +font. A character\index{character}\index{font!character} is a certain +slot\index{slot} (index) in a font with an associated meaning, e.g., the +capital letter~``M'' or the exclamation mark. The meaning of a slot is +defined by the font encoding\index{encoding}\index{font!encoding}. In +general, the same character is represented by different glyphs in +different fonts. Figure~\ref{glyphsample} shows some glyphs for the +character at slot~103 in the T1 encoding, i.e., the lower-case +letter~``g''. All glyphs are at the same nominal size. Note, how +glyphs may extend beyond their bounding box. +\begin{figure}[htp] + \centering + \setlength{\fboxsep}{0pt} + \setlength{\fboxrule}{.125pt} + \fontsize{56pt}{56pt}\selectfont + \newcommand*{\showglyph}[4]{% a glyph with its bounding box + \fbox{\usefont{#1}{#2}{#3}{#4}g}% + } + \makebox[0pt][c]{% base line + \rule{.7\textwidth}{.125pt}% + }% + \makebox[0pt][c]{% glyphs + \showglyph{T1}{lmr}{m}{n}\hspace{.3em} + \showglyph{T1}{qag}{m}{n}\hspace{.3em} + \showglyph{T1}{qpl}{m}{it}\hspace{.3em} + \showglyph{T1}{qzc}{m}{it}% + } + \caption{Different glyphs representing the same character.} + \label{glyphsample} +\end{figure} + +The glyphs of an Adobe Type~1 font +\index{PostScript!fonts}\index{font!PostScript}\index{Adobe Type~1 + Font}\index{font!Adobe Type~1} are composed of two types of contours: +Clockwise oriented contours add to the shape of a glyph and are filled +with black ink. Counter-clockwise oriented contours +erase\index{erasing} parts of other contours, i.e., make them +transparent again. To save the contours of a glyph in a picture, the +\verb|glyph|\index{glyph?\texttt{glyph}}\label{Dglyph} operator can be +used. There are two ways to identify a glyph in a font: +\begin{eqnarray*} + & \verb|glyph|\, \descr{numeric expression}\, \verb|of|\, + \descr{string expression}\\ + \noalign{\hbox{and}} + & \verb|glyph|\, \descr{string expression}\, \verb|of|\, + \descr{string expression}\rlap{\quad\mbox{.}} +\end{eqnarray*} + +If the first argument is a numeric expression, it has to be a slot +number between 0 and~255. Fractional slot numbers are rounded to the +nearest integer value. Slot numbers outside the allowed range trigger +an error. If the first argument is string, it has to be a CharString +name\index{CharString name} in the PostScript font's source file. A +CharString name is a unique text label for a glyph in a PostScript font +(a font encoding actually maps CharStrings to slots). This second +syntax can be used to address glyphs without having to think about font +encodings. The second argument to the \verb|glyph| operator is a string +containing a font name (section~\ref{text} has more on font names). + +The \verb|glyph| operator looks-up the font name in the font map to +determine the encoding and to find the font's PostScript source file. +It returns a picture consisting of the glyph's contour lines, explicitly +filled black and white in the greyscale color model according to the +rules laid out above. Additionally, the contours are sorted, such that +all black contours are drawn before white contours. The filling and +sorting is necessary for the picture to resembles the corresponding +glyph visually\footnote{Plain contours already carry enough information + to completely reconstruct a glyph, the orientation of a contour can be + computed from its cardinal and control points. MetaPost has a + \texttt{turningnumber}\index{turningnumber?\texttt{turningnumber}}\label{Dturningnumber} + primitive to do that.}, since Adobe Type~1 +fonts\index{PostScript!fonts}\index{font!PostScript}\index{Adobe Type~1 + Font}\index{font!Adobe Type~1} use a generalized variant of the +non-zero winding number fill rule\index{non-zero fill rule}\index{fill + rule!non-zero}\index{PostScript!fill rule}, that MetaPost doesn't +implement (MetaPost cannot handle non-contiguous paths). As a side +effect, the interiors of the erasing\index{erasing} contours are an +opaque white in the returned picture, while they were transparent in the +original glyph. One can think of erasing contours to be unfilled (see +p.~\pageref{Dunfill}). For instance, the following code saves the +contours of the lower case letter~``g'', bound to slot~103 in the OT1 +encoding\index{OT1 encoding}\index{encoding!OT1}, in the Computer Modern +Roman\index{Computer Modern Roman} font in a picture variable: + +$$\begin{verbatim} +fontmapline "cmr10 CMR10 <cmr10.pfb"; +picture g; +g := glyph 103 of "cmr10"; +\end{verbatim} +$$ + +The \verb|glyph| operator returns an empty picture, if the +\texttt{.tfm}\index{tfm file?{\tt tfm} file}\index{files!tfm?{\tt tfm}} +or \texttt{.pfb}\index{pfb file?{\tt pfb} file}\index{files!pfb?{\tt + pfb}} file cannot be found, if the encoding given in the font map +cannot be found or the slot number is not covered by the encoding or if +the CharString name cannot be found. Note, while MetaPost delegates the +actual font handling to a rendering application for \verb|infont| and +\verb|btex| \ldots\ \verb|etex| blocks, the \verb|glyph| operator +directly operates on font ressources. For that reason, a font map entry +is mandatory for the font in question, given either by +\verb|fontmapline| or \verb|fontmapfile| (see +section~\ref{Dfontmapline}). + +In Figure~\ref{fig56}, the contours of the upper case letter~``\v{D}'' +in the Latin Modern Roman\index{Latin Modern Roman} font are saved in a +picture variable. The glyph is identified by its CharString name +``Dcaron''\index{Dcaron}. The code then iterates over all contours and +draws them together with their cardinal (black) and control points +(red). As it turns out, many of the control points coincide with +cardinal points in this glyph. + +\begin{figure}[htb] +$$\begin{verbatim} +fontmapfile "=lm-ec.map"; +beginfig(56); + picture q; + path p; + interim ahlength := 12bp; + interim ahangle := 25; + q := glyph "Dcaron" of "ec-lmr10" scaled .2; + for item within q: + p := pathpart item; + drawarrow p withcolor (.6,.9,.6) + withpen pencircle scaled 1.5; + for j=0 upto length p: + pickup pencircle scaled .7; + draw (point j of p -- precontrol j of p) + dashed evenly withcolor blue; + draw (point j of p -- postcontrol j of p) + dashed evenly withcolor blue; + pickup pencircle scaled 3; + draw precontrol j of p withcolor red; + draw postcontrol j of p withcolor red; + pickup pencircle scaled 2; + draw point j of p withcolor black; + endfor + endfor +endfig; +\end{verbatim} +\qquad +\mathcenter{\includegraphics{mpman-56.mps}} +$$ +\caption{Iterating over the contours of a glyph} +\label{fig56} +\end{figure} + +The contours in a picture returned by the \verb|glyph| operator are no +raw copies of the contours found in the font sources, but the +\verb|glyph| operator applies a number of transformations to them. +First, the direction of all contours is reversed, so that contours +filled black become counter-clockwise oriented (mathematically positive) +and contours filled white become clockwise oriented (mathematically +negative). Second, in an Adobe Type~1 +font\index{PostScript!fonts}\index{font!PostScript}\index{Adobe Type~1 + Font}\index{font!Adobe Type~1}, contours are in general closed by +repeating the starting point before applying the \verb|closepath| +operator\index{PostScript!\texttt{closepath} operator}. The MetaPost +representation of such a path would be: +$$ +z_0\verb|..|\mbox{\itshape controls}\verb|..|z_1\verb|..| \cdots +\verb|..|z_n\verb|..|\mbox{\itshape controls}\verb|..|z_0\verb|--cycle| +$$ +A more natural MetaPost representation of this path would be: +$$ +z_0\verb|..|\mbox{\itshape controls}\verb|..|z_1\verb|..| \cdots +\verb|..|z_n\verb|..|\mbox{\itshape controls}\verb|..cycle| +$$ +The \verb|glyph| operator transforms all paths into the latter +representation, i.e., the last point is removed, whenever it matches the +starting point. Finally, the picture returned by the \verb|glyph| +operator is scaled such that one font design unit\index{font!design + unit} equals one PostScript +point\index{point!PostScript}\index{PostScript!point} (bp). A usual +font design unit is a thousandth part of the font design +size\index{font!design size}. The returned picture will therefore +typically have a height of around 1000\,bp. + +Converting a text into plain curves is part of a process oftentimes +called ``flattening\index{flattening} a document.'' When flattening +text, all hinting information in fonts are lost. Hinting information +aid a rendering application in aligning certain parts of a glyph on a +low-resolution output device. A flattened text may therefore look +distorted on screen. In SVG output, all text is automatically +flattened, when the internal variable +\verb|prologues|\index{prologues?\texttt{prologues}} is set to~3 (see +section~\ref{Dprologues}). + + +\section{Macros} +\label{macros} + +As alluded to earlier, MetaPost has a set of automatically included +macros called the Plain macro package\index{Plain macros}, and some of +the commands discussed in previous sections are defined as macros +instead of being built into MetaPost. The purpose of this section is to +explain how to write such macros. + +Macros with no arguments are very simple. +A macro definition\index{replacement text?\tdescr{replacement text}}% +\index{def?\texttt{def}}\index{enddef?\texttt{enddef}} +$$ {\tt def}\, \descr{symbolic token}\, \hbox{\tt =}\, + \descr{replacement text}\, {\tt enddef} +$$ +makes the \tdescr{symbolic token} an abbreviation for the +\tdescr{replacement text}, where the \tdescr{replacement text} can be +virtually any sequence of tokens. For example, the Plain macro package +could almost define the {\tt fill} statement like +this\index{fill?\texttt{fill}}: +$$ \hbox{\tt def fill = addto currentpicture contour enddef} $$ + +Macros with arguments are similar, except they have formal parameters +that tell how to use the arguments in the \tdescr{replacement text}. +For example, the {\tt +rotatedaround}\index{rotatedaround?\texttt{rotatedaround}} macro is +defined like this: +$$\begin{verbatim} +def rotatedaround(expr z, d) = + shifted -z rotated d shifted z enddef; +\end{verbatim} +$$ +The {\tt expr}\index{expr?\texttt{expr}} in this definition means that +formal parameters {\tt z} and {\tt d} can be arbitrary expressions. +(They should be pair expressions but the MetaPost interpreter does not +immediately check for that.) + +Since MetaPost is an interpreted language, macros with arguments are a +lot like subroutines\index{subroutines}. MetaPost macros are often used +like subroutines, so the language includes programming concepts to +support this. These concepts include local variables, loops, and +conditional statements. + +\subsection{Grouping} +\label{grsec} + +Grouping in MetaPost is essential for functions\index{functions} and +local\index{variables!local}\index{locality} variables. The basic idea +is that a group is a sequence of statements possibly followed by an +expression with the provision that certain symbolic +tokens\index{tokens!symbolic} can have their old meanings restored at +the end of the group. If the group ends with an expression, the group +behaves like a function call that returns that expression. Otherwise, +the group is just a compound statement\index{compound statement}. The +syntax for a group +is\index{begingroup?\texttt{begingroup}}\index{endgroup?\texttt{endgroup}} +$$ {\tt begingroup}\, \descr{statement list}\, {\tt endgroup} $$ +or +$$ {\tt begingroup}\, \descr{statement list}\, \descr{expression}\, {\tt endgroup} +$$ +where a \tdescr{statement list} is a sequence of statements each +followed by a semicolon. A group with an \tdescr{expression} after the +\tdescr{statement list} behaves like a \tdescr{primary} in +Figure~\ref{syexpr} or like a \tdescr{numeric atom} in +Figure~\ref{synprim}. + +Since the \tdescr{replacement text} for the {\tt +beginfig}\index{beginfig?\texttt{beginfig}} macro starts with {\tt +begingroup} and the \tdescr{replacement text} for {\tt +endfig}\index{endfig?\texttt{endfig}} ends with {\tt endgroup}, each +figure in a MetaPost input file behaves like a group. This is what +allows figures can have local variables. We have already seen in +Section~\ref{vardecl} that variable names beginning with {\tt x} or {\tt +y} are local in the sense that they have unknown values at the beginning +of each figure and these values are forgotten at the end of each figure. +The following example illustrates how locality works: +\begin{eqnarray*} +&& \hbox{\tt x23 = 3.1;}\\ +&& \hbox{\tt beginfig(17);}\\ +&& \qquad \vdots\\ +&& \hbox{\tt y3a=1; x23=2;}\\ +&& \qquad \vdots\\ +&& \hbox{\tt endfig;}\\ +&& \hbox{\tt show x23, y3a;} +\end{eqnarray*} +The result of the {\tt show}\index{show?\texttt{show}} command is +$$\begin{verbatim} +>> 3.1 +>> y3a +\end{verbatim} +$$ +indicating that {\tt x23} has returned to its former value of {\tt 3.1} and +{\tt y3a} is completely unknown as it was at {\tt beginfig(17)}. + +The locality of {\tt x} and {\tt y} variables is achieved by the +statement\index{save?\texttt{save}}\label{Dsave} +$$ \hbox{\tt save x,y} $$ +in the \tdescr{replacement text} for {\tt +beginfig}\index{beginfig?\texttt{beginfig}}. In general, variables are +made local by the statement +$$ {\tt save}\, \descr{symbolic token list} $$ +where \tdescr{symbolic token list} is a comma-separated list of +tokens:\index{tokens!symbolic} +\begin{ctabbing} +$\tt \descr{symbolic token list} \rightarrow \descr{symbolic token}$\\ + $\tt \qquad \;|\; \descr{symbolic token}\hbox{\tt ,} + \descr{symbolic token list}$ +\end{ctabbing} +All variables whose names begin with one of the specified symbolic +tokens become unknown numerics and their present values are saved for +restoration at the end of the current group. If the {\tt save} +statement is used outside of a group, the original values are simply +discarded. + +The main purpose of the {\tt save} statement is to allow macros to use +variables without interfering with existing variables or variables in +other calls to the same macro. For example, the predefined macro {\tt +whatever}\index{whatever?\texttt{whatever}} has the \tdescr{replacement text} +$$ \hbox{\tt begingroup save ?; ? endgroup} $$ +This returns an unknown numeric quantity, but it is no longer called +question mark since that name was local to the group. Asking the name +via {\tt show\index{show?\texttt{show}} whatever} +yields\index{CAPSULE?\texttt{CAPSULE}} +$$ \hbox{\verb|>> %CAPSULE|}{\it nnnn} $$ +where {\it nnnn} is an identification number that is chosen when {\tt save} +makes the name question mark disappear. + +In spite of the versatility of {\tt save}, it cannot be used to make +local changes to any of MetaPost's internal variables\index{internal +variables}\index{variables!internal}. A statement such +as\index{linecap?\texttt{linecap}} +$$ \hbox{\tt save linecap} $$ +would cause MetaPost to temporarily forget the special meaning of this +variable and just make it an unknown numeric. If you want to draw one +dashed line with {\tt linecap:=butt} and then go back to the previous +value, you can use the {\tt +interim}\index{interim?\texttt{interim}}\label{Dinterm} statement as +follows: +\begin{eqnarray*} +&& \hbox{\tt begingroup interim linecap:=butt;}\\ +&& {\tt draw}\, \descr{path expression}\, \hbox{\tt dashed evenly; endgroup} +\end{eqnarray*} +This saves the value of the +internal variable\index{internal variables}\index{variables!internal} +{\tt linecap} and temporarily +gives it a new value without forgetting that {\tt linecap} is an internal +variable. The general syntax is +$$ {\tt interim}\, \descr{internal variable} \mathrel{\hbox{\tt:=}} + \descr{numeric expression} \;|\; \descr{string expression} +$$ + + +\subsection{Parameterized Macros} + +The basic idea behind parameterized macros is to achieve greater flexibility by +allowing auxiliary information to be passed to a macro. We have already seen +that macro definitions can have formal parameters that represent expressions +to be given when the macro is called. For instance a definition such as +$$ \hbox{\tt def rotatedaround(expr z, d) = } \descr{replacement text}\, + {\tt enddef} +$$ +allows the MetaPost interpreter to understand macro calls of the form +$$\tt rotatedaround\hbox{\tt (} + \descr{expression}\hbox{\tt ,} \descr{expression}\hbox{\tt )} +$$ + +The keyword {\tt expr}\index{expr?\texttt{expr}}\index{parameter!expr} +in the macro definition means that the parameters can be expressions of +any type. When the definition specifies {\tt (expr z, d)}, the formal +parameters {\tt z} and {\tt d} behave like variables of the appropriate +types. Within the \tdescr{replacement text}, they can be used in +expressions just like variables, but they cannot be redeclared or +assigned to. There is no restriction against unknown or partially known +arguments. Thus the definition\index{midpoint?\texttt{midpoint}} +$$ \hbox{\tt def midpoint(expr a, b) = (.5[a,b]) enddef} $$ +works perfectly well when {\tt a} and {\tt b} are unknown. An +equation such as +$$ \hbox{\tt midpoint(z1,z2) = (1,1)} $$ +could be used to help determine {\tt z1} and {\tt z2}. + +Notice that the above definition for {\tt midpoint} works for numerics, +pairs, or colors as long as both parameters have the same type. If for +some reason we want a {\tt +middlepoint}\index{middlepoint?\texttt{middlepoint}} macro that works +for a single path or picture, it would be necessary to do an {\tt +if}\index{if?\texttt{if}} test on the argument type. This uses the fact +there is a unary operator\index{path?\texttt{path}} +$$ {\tt path}\, \descr{primary} $$ +that returns a boolean result indicating whether its argument is a path. +Since the basic {\tt if} test has the +syntax\index{else?\texttt{else}}\index{fi?\texttt{fi}} +$$ {\tt if}\, \descr{boolean expression}\hbox{\tt:}\, \descr{balanced tokens}\, + \hbox{\tt else:}\, \descr{balanced tokens}\, {\tt fi} +$$ +where the \tdescr{balanced tokens}\index{balanced +tokens?\tdescr{balanced tokens}} can be anything that is balanced with +respect to {\tt if} and {\tt fi}, the complete {\tt +middlepoint}\index{middlepoint?\texttt{middlepoint}} macro with type test +looks like this: +$$\begin{verbatim} +def middlepoint(expr a) = if path a: (point .5*length a of a) + else: .5(llcorner a + urcorner a) fi enddef; +\end{verbatim} +$$ +The complete syntax for {\tt if} tests is shown in Figure~\ref{syif}. +It allows multiple {\tt if} tests like +$$ \hbox{\tt if $e_1$: \ldots\ else: if $e_2$: \ldots\ else: \ldots\ fi fi} $$ +to be shortened to\index{elseif?\texttt{elseif}} +$$ \hbox{\tt if $e_1$: \ldots\ elseif $e_2$: \ldots\ else: \ldots\ fi} $$ +where $e_1$ and $e_2$ represent boolean expressions. + +Note that {\tt if} tests are not statements and the \tdescr{balanced +tokens} in the syntax rules can be any sequence of balanced tokens even +if they do not form a complete expression or statement. Thus we could +have saved two tokens at the expense of clarity by defining {\tt +middlepoint} like this: +$$\begin{verbatim} +def middlepoint(expr a) = if path a: (point .5*length a of + else: .5(llcorner a + urcorner fi a) enddef; +\end{verbatim} +$$ + +\begin{figure}[htp] +\begin{ctabbing} +$\tt \descr{if test} \rightarrow if \descr{boolean expression} \hbox{\tt :} + \descr{balanced tokens} \descr{alternatives} fi$\\ +$\tt \descr{alternatives} \rightarrow \descr{empty}$\\ +$\tt \qquad \;|\; else\hbox{\tt :} \descr{balanced tokens}$\\ +$\tt \qquad \;|\; elseif \descr{boolean expression} \hbox{\tt :} + \descr{balanced tokens} \descr{alternatives}$ +\end{ctabbing} +\caption{The syntax for {\tt if} tests.} +\label{syif} +\end{figure} + +The real purpose of macros and {\tt if} tests is to automate repetitive +tasks and allow important subtasks to be solved separately. For +example, Figure~\ref{fig42} uses macros \verb|draw_marked|, +\verb|mark_angle|, and \verb|mark_rt_angle| to mark lines and angles +that appear in the figure. + +\begin{figure}[htp] +$$\begin{verbatim} +beginfig(42); +pair a,b,c,d; +b=(0,0); c=(1.5in,0); a=(0,.6in); +d-c = (a-b) rotated 25; +dotlabel.lft("a",a); +dotlabel.lft("b",b); +dotlabel.bot("c",c); +dotlabel.llft("d",d); +z0=.5[a,d]; +z1=.5[b,c]; +(z.p-z0) dotprod (d-a) = 0; +(z.p-z1) dotprod (c-b) = 0; +draw a--d; +draw b--c; +draw z0--z.p--z1; +draw_marked(a--b, 1); +draw_marked(c--d, 1); +draw_marked(a--z.p, 2); +draw_marked(d--z.p, 2); +draw_marked(b--z.p, 3); +draw_marked(c--z.p, 3); +mark_angle(z.p, b, a, 1); +mark_angle(z.p, c, d, 1); +mark_angle(z.p, c, b, 2); +mark_angle(c, b, z.p, 2); +mark_rt_angle(z.p, z0, a); +mark_rt_angle(z.p, z1, b); +endfig; +\end{verbatim} +\quad \mathcenter{\includegraphics{mpman-42.mps}} +$$ +\caption{MetaPost code and the corresponding figure} +\label{fig42} +\end{figure} + +The task of the +\verb|draw_marked|\index{draw_marked?\texttt{draw\_marked}} macro is to +draw a path with a given number of cross marks near its midpoint. A +convenient starting place is the subproblem of drawing a single cross +mark perpendicular to a path {\tt p} at some time {\tt t}. The +\verb|draw_mark|\index{draw_mark?\texttt{draw\_mark}} macro in +Figure~\ref{drawmarked} does this by first finding a vector {\tt dm} +perpendicular to~{\tt p} at~{\tt t}. To simplify positioning the cross +mark, the \verb|draw_marked| macro is defined to take an arc +length\index{arc length} {\tt a} along {\tt p} and use the {\tt +arctime}\index{arctime} operator to compute~{\tt t} + +With the subproblem of drawing a single mark out of the way, the +\verb|draw_marked| macro only needs to draw the path and call +\verb|draw_mark| with the appropriate arc length values. The +\verb|draw_marked| macro in Figure~\ref{drawmarked} uses {\tt n} +equally-spaced {\tt a} values centered on {\tt +.5*arclength~p}\index{arclength?\texttt{arclength}}. + +\begin{figure}[htp] +$$\begin{verbatim} +marksize=4pt; + +def draw_mark(expr p, a) = + begingroup + save t, dm; pair dm; + t = arctime a of p; + dm = marksize*unitvector direction t of p + rotated 90; + draw (-.5dm.. .5dm) shifted point t of p; + endgroup +enddef; + +def draw_marked(expr p, n) = + begingroup + save amid; + amid = .5*arclength p; + for i=-(n-1)/2 upto (n-1)/2: + draw_mark(p, amid+.6marksize*i); + endfor + draw p; + endgroup +enddef; +\end{verbatim} +$$ +\caption{Macros for drawing a path {\tt p} with {\tt n} cross marks.} +\label{drawmarked} +\end{figure} + +Since \verb|draw_marked| works for curved lines, it can be used to draw +the arcs that the +\verb|mark_angle|\index{mark_angle?\texttt{mark\_angle}} macro +generates. Given points {\tt a}, {\tt b}, and {\tt c} that define a +counter-clockwise angle at {\tt b}, the \verb|mark_angle| needs to +generate a small arc from segment {\tt ba} to segment {\tt bc}. The +macro definition in Figure~\ref{markangle} does this by creating an arc +{\tt p} of radius one and then computing a scale factor {\tt s} that +makes it big enough to see clearly. + +The \verb|mark_rt_angle|\index{mark_rt_angle?\texttt{mark\_rt\_angle}} +macro is much simpler. It takes a generic right-angle corner and uses +the {\tt zscaled}\index{zscaled?\texttt{zscaled}} operator to rotate it +and scale it as necessary. + +\begin{figure}[htp] +$$\begin{verbatim} +angle_radius=8pt; + +def mark_angle(expr a, b, c, n) = + begingroup + save s, p; path p; + p = unitvector(a-b){(a-b)rotated 90}..unitvector(c-b); + s = .9marksize/length(point 1 of p - point 0 of p); + if s<angle_radius: s:=angle_radius; fi + draw_marked(p scaled s shifted b, n); + endgroup +enddef; + +def mark_rt_angle(expr a, b, c) = + draw ((1,0)--(1,1)--(0,1)) + zscaled (angle_radius*unitvector(a-b)) shifted b +enddef; +\end{verbatim} +$$ +\caption{Macros for marking angles.} +\label{markangle} +\end{figure} + + +\subsection{Suffix and Text Parameters} + +Macro parameters need not always be expressions as in the previous +examples. Replacing the keyword {\tt expr} with {\tt +suffix}\index{suffix?\texttt{suffix}} or {\tt +text}\index{text?\texttt{text}} in a macro definition declares the +parameters to be variable names or arbitrary sequences of tokens. For +example, there is a predefined macro called {\tt +hide}\index{hide?\texttt{hide}} that takes a text +parameter\index{parameter!text} and interprets it as a sequence of +statements while ultimately producing an empty \tdescr{replacement +text}. In other words, {\tt hide} executes its argument and then gets +the next token as if nothing happened. Thus +$$ \hbox{\tt show hide(numeric a,b; a+b=3; a-b=1) a;} $$ +prints ``\verb|>> 2|.'' + +If the {\tt hide} macro were not predefined, it could be defined like this: +$$\begin{verbatim} +def ignore(expr a) = enddef; +def hide(text t) = ignore(begingroup t; 0 endgroup) enddef; +\end{verbatim} +$$ +The statements represented by the text parameter {\tt t} would be +evaluated as part of the group that forms the argument to {\tt ignore}. +Since {\tt ignore} has an empty \tdescr{replacement text}, expansion of +the {\tt hide} macro ultimately produces nothing. + +Another example of a predefined macro with a text parameter is {\tt +dashpattern}\index{dashpattern?\texttt{dashpattern}}. The definition of +{\tt dashpattern} starts +$$\begin{verbatim} +def dashpattern(text t) = + begingroup save on, off; +\end{verbatim} +$$ +then it defines {\tt on} and {\tt off} to be macros that create the desired +picture when the text parameter~{\tt t} appears in the replacement text. + +Text parameters are very general, but their generality sometimes gets in +the way. If you just want to pass a variable name to a macro, it is +better to declare it as a suffix parameter\index{parameter!suffix}. For +example,\index{incr?\texttt{incr}} +$$ \hbox{\verb|def incr(suffix $) = begingroup $:=$+1; $ endgroup enddef;|} $$ +defines a macro that will take any numeric variable, add one to it, and return +the new value. Since variable names can be more than one token long, +$$ \hbox{\tt incr(a3b)} $$ +is perfectly acceptable if {\tt a3b} is a numeric variable. Suffix +parameters are slightly more general than variable names because the +definition in Figure~\ref{syvar} allows a +\tdescr{suffix}\index{suffix?\tdescr{suffix}} to start with a +\tdescr{subscript}\index{subscript?\tdescr{subscript}}. + +Figure~\ref{fig45} shows how suffix and expr parameters can be used +together. The {\tt getmid}\index{getmid?\texttt{getmid}} macro takes a +path variable and creates arrays of points and directions whose names +are obtained by appending {\tt mid}, {\tt off}, and {\tt dir} to the +path variable. The {\tt joinup}\index{joinup?\texttt{joinup}} macro +takes arrays of points and directions and creates a path of length {\tt +n} that passes through each {\tt pt[i]} with direction {\tt d[i]} or +$-\hbox{\tt d[i]}$. + +\begin{figure}[htp] +$$\begin{verbatim} +def getmid(suffix p) = + pair p.mid[], p.off[], p.dir[]; + for i=0 upto 36: + p.dir[i] = dir(5*i); + p.mid[i]+p.off[i] = directionpoint p.dir[i] of p; + p.mid[i]-p.off[i] = directionpoint -p.dir[i] of p; + endfor +enddef; + +def joinup(suffix pt, d)(expr n) = + begingroup + save res, g; path res; + res = pt[0]{d[0]}; + for i=1 upto n: + g:= if (pt[i]-pt[i-1]) dotprod d[i] <0: - fi 1; + res := res{g*d[i-1]}...{g*d[i]}pt[i]; + endfor + res + endgroup +enddef; + +beginfig(45) +path p, q; +p = ((5,2)...(3,4)...(1,3)...(-2,-3)...(0,-5)...(3,-4) + ...(5,-3)...cycle) scaled .3cm shifted (0,5cm); +getmid(p); +draw p; +draw joinup(p.mid, p.dir, 36)..cycle; +q = joinup(p.off, p.dir, 36); +draw q..(q rotated 180)..cycle; +drawoptions(dashed evenly); +for i=0 upto 3: + draw p.mid[9i]-p.off[9i]..p.mid[9i]+p.off[9i]; + draw -p.off[9i]..p.off[9i]; +endfor +endfig; +\end{verbatim} +\quad \mathcenter{\includegraphics{mpman-45.mps}} +$$ +\caption{MetaPost code and the corresponding figure} +\label{fig45} +\end{figure} + +A definition that starts +$$ \hbox{\tt def joinup(suffix pt, d)(expr n) =} $$ +might suggest that calls to the {\tt joinup} macro should have two sets of +parentheses as in +$$ \hbox{\tt joinup(p.mid, p.dir)(36)} $$ +instead of +$$ \hbox{\tt joinup(p.mid, p.dir, 36)} $$ +In fact, both forms are acceptable. Parameters in a macro call can be +separated by commas or by {\tt )(} pairs. The only restriction is that +a text parameter\index{parameter!text} must be followed by a right +parenthesis. For instance, a macro {\tt foo} with one text parameter +and one expr parameter can be called +$$ \hbox{\tt foo(a,b)(c)} $$ +in which case the text parameter is ``{\tt a,b}'' and the expr parameter is +{\tt c}, but +$$ \hbox{\tt foo(a,b,c)} $$ +sets the text parameter to ``{\tt a,b,c}'' and leaves the MetaPost interpreter +still looking for the expr parameter. + + +\subsection{Vardef Macros} + +A macro definition can begin with {\tt +vardef}\index{vardef?\texttt{vardef}} instead of {\tt def}. Macros +defined in this way are called vardef macros. They are particularly +well-suited to applications where macros are being used like functions +or subroutines. The main idea is that a vardef macro is like a variable +of type ``macro.'' + +Instead of {\tt def} \tdescr{symbolic token}, a vardef macro begins +$$ {\tt vardef}\, \descr{generic variable} $$ +where a \tdescr{generic variable}\index{generic variable?\tdescr{generic +variable}} is a variable name with numeric subscripts replaced by the +generic subscript\index{subscript!generic} symbol {\tt +[]}\index{[]?\texttt{[]}!vardef macro?\texttt{vardef} macro}. In other +words, the name following {\tt +vardef} obeys exactly the same syntax as the name given in a variable +declaration. It is a sequence of tags and generic subscript symbols +starting with a tag, where a tag\index{tags} is a symbolic token that is +not a macro or a primitive operator as explained in +Section~\ref{vardecl}. + +The simplest case is when the name of a vardef macro consists of a +single tag. Under such circumstances, {\tt def} and {\tt vardef} +provide roughly the same functionality. The most obvious difference is +that {\tt begingroup}\index{begingroup?\texttt{begingroup}} and {\tt +endgroup}\index{endgroup?\texttt{endgroup}} are automatically inserted +at the beginning and end of the \tdescr{replacement text} of every +vardef macro. This makes the \tdescr{replacement text} a group so that +a vardef macro behaves like a subroutine or a function call. + +Another property of vardef macros is that they allow multi-token macro +names and macro names involving generic subscripts. When a vardef macro +name has generic subscripts, numeric values have to be given when the +macro is called. After a macro definition +$$ \hbox{\tt vardef a[]b(expr p) =}\, \descr{replacement text}\, + \hbox{\tt enddef;} +$$ +{\tt a2b((1,2))} and {\tt a3b((1,2)..(3,4))} are macro calls. But how +can the \tdescr{replacement text} tell the difference between {\tt a2b} +and {\tt a3b}? Two implicit suffix parameters\index{parameter!suffix} +are automatically provided for this purpose. Every vardef macro has +suffix parameters \verb|#@|\index{#@?\texttt{\#@}} and +\verb|@|\index{@?\texttt{@}}, where \verb|@| is the last token in the +name from the macro call and \verb|#@| is everything preceding the last +token. Thus \verb|#@| is {\tt a2} when the name is given as {\tt a2b} +and {\tt a3} when the name is given as {\tt a3b}. + +Suppose, for example, that the {\tt a[]b} macro is to take its argument +and shift it by an amount that depends on the macro name. The macro +could be defined like this: +$$ \hbox{\verb|vardef a[]b(expr p) = p shifted (#@,b) enddef;|} $$ +Then {\tt a2b((1,2))} means {\tt (1,2) shifted (a2,b)} +and {\tt a3b((1,2)..(3,4))} means +$$ \hbox{\tt ((1,2)..(3,4)) shifted (a3,b)}. $$ + +If the macro had been {\tt a.b[]}, \verb|#@| would always be {\tt a.b} +and the \verb|@| parameter would give the numeric subscript. Then {\tt +a@} would refer to an element of the array {\tt a[]}. Note that +\verb|@| is a suffix parameter, not an expr parameter, so an expression +like {\tt @+1} would be illegal. The only way to get at the numeric +values of subscripts in a suffix parameter\index{parameter!suffix} is by +extracting them from the string returned by the {\tt +str}\index{str?\texttt{str}}\label{Dstr} operator. This operator takes +a suffix and returns a string representation of a suffix. Thus {\tt str +@} would be \verb|"3"| in {\tt a.b3} and \verb|"3.14"| in {\tt a.b3.14} +or {\tt a.b[3.14]}. Since the syntax for a +\tdescr{suffix}\index{suffix?\tdescr{suffix}} in Figure~\ref{syvar} +requires negative subscripts to be in brackets, {\tt str @} returns {\tt +"[-3]"} in {\tt a.b[-3]}. + +The {\tt str} operator is generally for emergency use only. It is +better to use suffix parameters only as variable names or suffixes. The +best example of a vardef macro involving suffixes is the {\tt z} macro +that defines the {\tt z} convention\index{z convention?{\tt z} +convention}. The definition involves a special token +\verb|@#|\index{@#?\texttt{@\#}} that refers to the suffix following the +macro name: +$$ \hbox{\verb|vardef z@#=(x@#,y@#) enddef;|} $$ +This means that any variable name whose first token is {\tt z} is +equivalent to a pair of variables whose names are obtained by replacing +{\tt z} with {\tt x} and~{\tt y}. For instance, {\tt z.a1} calls the +{\tt z} macro with the suffix parameter \verb|@#| set to {\tt a1}. + +In general, +$$ {\tt vardef}\, \descr{generic variable} \hbox{\verb|@#|} $$ +is an alternative to {\tt vardef} \tdescr{generic variable} that causes the +MetaPost interpreter +to look for a suffix following the name given in the macro call and makes this +available as the \verb|@#| suffix parameter. + +To summarize the special features of vardef macros, they allow a broad +class of macro names as well as macro names followed by a special suffix +parameter. Furthermore, {\tt begingroup} and {\tt endgroup} are +automatically added to the \tdescr{replacement text} of a vardef macro. +Thus using {\tt vardef} instead of {\tt def} to define the {\tt +joinup}\index{joinup?\texttt{joinup}} macro in Figure~\ref{fig45} would +have avoided the need to include {\tt begingroup} and {\tt endgroup} +explicitly in the macro definition. + +In fact, most of the macro definitions given in previous examples could +equally well use {\tt vardef} instead of {\tt def}. It usually does not +matter very much which you use, but a good general rule is to use {\tt +vardef} if you intend the macro to be used like a function or a +subroutine. The following comparison should help in deciding when to +use {\tt vardef}. + +\begin{itemize} +\item Vardef macros are automatically surrounded by {\tt begingroup} +and {\tt endgroup}. +\item The name of a vardef macro can be more than one token long and it can +contain subscripts. +\item A vardef macro can have access to the suffix that follows the macro name +when the macro is called. +\item When a symbolic token is used in the name of a vardef macro it remains +a tag\index{tags} and can still be used in other variable names. Thus +{\tt p5dir} is a legal variable name even though {\tt dir} is a vardef +macro, but an ordinary macro such as {\tt ...}\index{...?\texttt{...}} +cannot be used in a variable name. (This is fortunate since {\tt +z5...z6} is supposed to be a path expression, not an elaborate variable +name). +\end{itemize} + + +\subsection{Defining Unary and Binary Macros} + +It has been mentioned several times that some of the operators and +commands discussed so far are actually predefined macros. These include +unary operators such as {\tt round}\index{round?\texttt{round}} and {\tt +unitvector}\index{unitvector?\texttt{unitvector}}, statements such as +{\tt fill}\index{fill?\texttt{fill}} and {\tt +draw}\index{draw?\texttt{draw}}, and binary operators such as {\tt +dotprod}\index{dotprod?\texttt{dotprod}} and {\tt +intersectionpoint}\index{intersectionpoint?\texttt{intersectionpoint}}. +The main difference between these macros and the ones we already know +how to define is their argument syntax. + +The {\tt round} and {\tt unitvector} macros are examples of what +Figure~\ref{syexpr} calls \tdescr{unary op}. That is, they are followed +by a primary expression. To specify a macro argument of this type, the +macro definition should look like this: +$$ \hbox{\tt vardef round primary u =}\, \descr{replacement text}\, + \hbox{\tt enddef;} +$$ +The {\tt u} parameter is an expr parameter\index{parameter!expr} and it can be +used exactly like the expr parameter defined using the ordinary +$$ \hbox{\tt (expr u)} $$ +syntax. + +As the {\tt round} example suggests, a macro can be defined to take a +\tdescr{secondary}\index{secondary?\tdescr{secondary}}, +\tdescr{tertiary}\index{tertiary?\tdescr{tertiary}}, or an +\tdescr{expression}\index{expression?\tdescr{expression}} parameter. +For example, the predefined definition of the {\tt fill} macro is +roughly\index{fill?\texttt{fill}} +$$ \hbox{\tt def fill expr c = addto currentpicture contour c enddef;} $$ + +It is even possible to define a macro to play the role of \tdescr{of +operator}\index{of operator?\tdescr{of operator}} in +Figure~\ref{syexpr}. For example, the {\tt direction +of}\index{direction of?\texttt{direction of}} macro has a definition of +this form: +$$ \hbox{\tt vardef direction expr t of p =}\, \descr{replacement text}\, + \hbox{\tt enddef;} +$$ + +Macros can also be defined to behave like binary operators. For instance, the +definition of the {\tt dotprod} macro has the +form\index{dotprod?\texttt{dotprod}}\index{primarydef?\texttt{primarydef}} +$$ \hbox{\tt primarydef w dotprod z =}\, \descr{replacement text}\, + \hbox{\tt enddef;} +$$ +This makes {\tt dotprod} a \tdescr{primary binop}\index{primary +binop?\tdescr{primary binop}}. Similarly, {\tt +secondarydef}\index{secondarydef?\texttt{secondarydef}} and {\tt +tertiarydef}\index{tertiarydef?\texttt{tertiarydef}} introduce +\tdescr{secondary binop}\index{secondary binop?\tdescr{secondary binop}} +and \tdescr{tertiary binop}\index{tertiary binop?\tdescr{tertiary +binop}} definitions. These all define ordinary macros, not vardef +macros; e.g., there is no ``{\tt primaryvardef}.'' + +Thus macro definitions can be introduced by {\tt def}, {\tt vardef}, +{\tt primarydef}, {\tt secondarydef}, or {\tt tertiarydef}. A +\tdescr{replacement text}\index{replacement text?\tdescr{replacement +text}} is any list of tokens that is balanced with respect to {\tt +def}-{\tt enddef} pairs where all five macro definition tokens are +treated like {\tt def} for the purpose of {\tt def}-{\tt enddef} +matching. + +The rest of the syntax for macro definitions is summarized in +Figure~\ref{symacro}. The syntax contains a few surprises. The macro +parameters can have a \tdescr{delimited part} and an \tdescr{undelimited +part}. Normally, one of these is \tdescr{empty}, but it is possible to +have both parts nonempty: +$$ \hbox{\tt def foo(text a) expr b =}\, \descr{replacement text}\, + \hbox{\tt enddef;} +$$ +This defines a macro {\tt foo} to take a text parameter in parentheses followed +by an expression. + +\begin{figure}[htp] +\begin{ctabbing} +$\tt \descr{macro definition} \rightarrow + \descr{macro heading} \hbox{\tt =} \descr{replacement text}\, enddef$\\ +$\tt \descr{macro heading} \rightarrow def\, \descr{symbolic token} + \descr{delimited part} \descr{undelimited part}$\\ +$\tt \qquad \;|\; vardef\, \descr{generic variable} \descr{delimited part} + \descr{undelimited part}$\\ +$\tt \qquad \;|\; vardef\, \descr{generic variable} \hbox{\tt @\#} + \descr{delimited part} \descr{undelimited part}$\\ +$\tt \qquad \;|\; \descr{binary def} \descr{parameter} + \descr{symbolic token} \descr{parameter}$\\ +$\tt \descr{delimited part} \rightarrow \descr{empty}$\\ +$\tt \qquad \;|\; \descr{delimited part} + \hbox{\tt (}\descr{parameter type} \descr{parameter tokens}\hbox{\tt )}$\\ +$\tt \descr{parameter type} \rightarrow expr \;|\; suffix \;|\; text$\\ +$\tt \descr{parameter tokens} \rightarrow \descr{parameter} \;|\; + \descr{parameter tokens}\hbox{\tt ,} \descr{parameter}$\\ +$\tt \descr{parameter} \rightarrow \descr{symbolic token}$\\ +$\tt \descr{undelimited part} \rightarrow \descr{empty}$\\ +$\tt \qquad \;|\; \descr{parameter type} \descr{parameter}$\\ +$\tt \qquad \;|\; \descr{precedence level} \descr{parameter}$\\ +$\tt \qquad \;|\; expr\, \descr{parameter}\, of\, \descr{parameter}$\\ +$\tt \descr{precedence level} \rightarrow primary \;|\; secondary \;|\; + tertiary$\\ +$\tt \descr{binary def} \rightarrow primarydef \;|\; secondarydef \;|\; + tertiatydef$ +\end{ctabbing} +\caption{The syntax for macro definitions} +\label{symacro} +\end{figure} + +The syntax also allows the \tdescr{undelimited part} to specify an +argument type of {\tt suffix}\index{suffix?\texttt{suffix}} or {\tt +text}\index{text?\texttt{text}}. An example of a macro with an +undelimited suffix parameter\index{parameter!suffix} is the predefined +macro {\tt incr}\index{incr?\texttt{incr}}\label{Dincr} that is actually +defined like this: +$$ \hbox{\verb|vardef incr suffix $ = $:=$+1; $ enddef;|} $$ +This makes {\tt incr} a function that takes a variable, increments it, +and returns the new value. Undelimited suffix parameters may be +parenthesized, so {\tt incr a} and {\tt incr(a)} are both legal if {\tt +a} is a numeric variable. There is also a similar predefined macro {\tt +decr}\index{decr?\texttt{decr}} that subtracts~1. + +Undelimited text parameters\index{parameter!text} run to the end of a +statement. More precisely, an undelimited text parameter is the list of +tokens following the macro call up to the first ``{\tt +;}\index{semicolon}'' or ``{\tt +endgroup}\index{endgroup?\texttt{endgroup}}'' or ``{\tt +end}\index{end?\texttt{end}}'' except that an argument containing ``{\tt +begingroup}'' will always include the matching ``{\tt endgroup}.'' An +example of an undelimited text parameter comes from the predefined macro +{\tt cutdraw}\index{cutdraw?\texttt{cutdraw}}\label{Dctdraw} whose +definition is +roughly\index{linecap?\texttt{linecap}}\index{butt?\texttt{butt}}\index{interim?\texttt{interim}} +$$\begin{verbatim} +def cutdraw text t = + begingroup interim linecap:=butt; draw t; endgroup enddef; +\end{verbatim} +$$ +This makes {\tt cutdraw} synonymous with {\tt draw} except for the {\tt +linecap} value. (This macro is provided mainly for compatibility with +\MF\index{metafont?\MF}.) + + +\section{Loops} + +Numerous examples in previous sections have used simple {\tt for} loops of the +form\index{loops}\index{for?\texttt{for}}\index{endfor?\texttt{endfor}} +$$ {\tt for}\, \descr{symbolic token}\, \hbox{\tt =}\, + \descr{expression}\, {\tt upto}\, \descr{expression}:\ + \descr{loop text}\, {\tt endfor} +$$ +It is equally simple to construct a loop that counts downward: just +replace {\tt upto} by {\tt +downto}\index{downto?\texttt{downto}}\label{Ddwnto} make the second +\tdescr{expression} smaller than the first. This section covers more +complicated types of progressions, loops where the loop counter behaves +like a suffix parameter, and ways of exiting from a loop. + +The first generalization is suggested by the fact that {\tt +upto}\index{upto?\texttt{upto}} is a predefined macro +for\index{step?\texttt{step}}\index{until?\texttt{until}} +$$ \hbox{\tt step 1 until} $$ +and {\tt downto}\index{downto?\texttt{downto}} is a macro for {\tt step +-1 until}. A loop begining +$$ \hbox{\tt for i=a step b until c} $$ +scans a sequence of {\tt i} values {\tt a}, ${\tt a}+{\tt b}$, ${\tt +a}+2{\tt b}$, \ldots, stopping before {\tt i} passes {\tt c}; i.e., the +loop scans {\tt i} values where ${\tt i}\le {\tt c}$ if ${\tt b}>0$ and +${\tt i}\ge {\tt c}$ if ${\tt b}<0$. For ${\tt b}=0$ the loop never +terminates, even if ${\tt a}={\tt c}$. + +It is best to use this feature only when the step size is an integer or +some number that can be represented exactly in fixed point +arithmetic\index{arithmetic} as a multiple of $1\over65536$. Otherwise, +error will accumulate and the loop index might not reach the expected +termination value. For instance, +$$ \hbox{\tt for i=0 step .1 until 1: show i; endfor} $$ +shows ten {\tt i} values the last of which is 0.90005. + +The standard way of avoid the problems associated with non-integer step +sizes is to iterate over integer values and then multiply by a scale +factor when using the loop index as was done in Figures \ref{fig1} +and~\ref{fig40}. + +Alternatively, the values to iterate over can be given explicitly. Any +sequence of zero or more expressions separated by commas can be used in +place of {\tt a step b upto c}. In fact, the expressions need not all +be the same type and they need not have known values. Thus +$$ \hbox{\tt for t=3.14, 2.78, (a,2a), "hello": show t; endfor} $$ +shows the four values listed. + +Note that the loop body in the above example is a statement followed by a +semicolon. It is common for the body of a loop to be one or more statements, +but this need not be the case. A loop is like a macro definition followed by +calls to the macro. The loop body can be virtually any sequence of tokens as +long as they make sense together. Thus, the (ridiculous) statement +$$ \hbox{\verb|draw for p=(3,1),(6,2),(7,5),(4,6),(1,3): p-- endfor cycle;|} $$ +is equivalent to +$$ \hbox{\verb|draw (3,1)--(6,2)--(7,5)--(4,6)--(1,3)--cycle;|} $$ +(See Figure~\ref{fig17} for a more realistic example of this.) + +If a loop is like a macro definition, the loop index is like an expr +parameter\index{parameter!expr}. It can represent any value, but it is +not a variable and it cannot be changed by an assignment +statement\index{assignment}. In order to do that, you need a {\tt +forsuffixes}\index{forsuffixes?\texttt{forsuffixes}} loop. A {\tt +forsuffixes} loop is a lot like a {\tt for} loop, except the loop index +behaves like a suffix parameter\index{parameter!suffix}. The syntax is +$$ {\tt forsuffixes}\, \descr{symbolic token}\, \hbox{\tt =}\, + \descr{suffix list}:\ \descr{loop text}\, {\tt endfor} +$$ +where a \tdescr{suffix list} is a comma-separated list of suffixes. If +some of the suffixes are \tdescr{empty}, the \tdescr{loop text} gets +executed with the loop index parameter set to the empty suffix. + +A good example of a {\tt forsuffixes} loop is the definition of the {\tt +dotlabels}\index{dotlabels?\texttt{dotlabels}} +macro\index{str?\texttt{str}}: +$$\begin{verbatim} +vardef dotlabels@#(text t) = + forsuffixes $=t: dotlabel@#(str$,z$); endfor enddef; +\end{verbatim} +$$ +This should make it clear why the parameter to {\tt dotlabels} has to be a +comma-separated list of suffixes. Most macros that accept variable-length +comma-separated lists +use them in {\tt for} or {\tt forsuffixes} loops in this fashion as values to +iterate over. + +When there are no values to iterate over, you can use a +{\tt forever}\index{forever?\texttt{forever}} loop: +$$ {\tt forever}\hbox{\tt :}\, \descr{loop text}\, {\tt endfor} $$ +To terminate such a loop when a boolean condition becomes true, use an exit +clause\index{exitif?\texttt{exitif}}: +$$ {\tt exitif}\, \descr{boolean expression} \hbox{\tt ;} $$ +When the MetaPost interpreter encounters an exit clause, it evaluates +the \tdescr{boolean expression} and exits the current loop if the +expression is true. If it is more convenient to exit the loop when an +expression becomes false, use the predefined macro {\tt +exitunless}\index{exitunless?\texttt{exitunless}}. + +Thus MetaPost's version of a {\bf while} loop is +$$ \hbox{\tt forever: exitunless}\, \descr{boolean expression} \hbox{\tt ;}\, + \descr{loop text}\, {\tt endfor} +$$ +The exit clause could equally well come just before {\tt endfor} or anywhere +in the \tdescr{loop text}. In fact any {\tt for}, {\tt forever}, or +{\tt forsuffixes} loop can contain any number of exit clauses. + +The summary of loop syntax shown in Figure~\ref{syloop} does not mention +exit clauses explicitly because a \tdescr{loop text} can be virtually +any sequence of tokens. The only restriction is that a \tdescr{loop +text} must be balanced with respect to {\tt for} and {\tt endfor}. Of +course this balancing process treats {\tt forsuffixes} and {\tt forever} +just like {\tt for}. + +\begin{figure}[htp] +\begin{ctabbing} +$\tt \descr{loop} \rightarrow \descr{loop header}\hbox{\tt :}\, + \descr{loop text} endfor$\\ +$\tt \descr{loop header} \rightarrow for\, \descr{symbolic token}\, + \hbox{\tt =}\, \descr{progression}$\\ +$\tt \qquad \;|\; for\, \descr{symbolic token}\, \hbox{\tt =}\, + \descr{for list}$\\ +$\tt \qquad \;|\; forsuffixes\, \descr{symbolic token}\, \hbox{\tt =}\, + \descr{suffix list}$\\ +$\tt \qquad \;|\; forever$\\ +$\tt \descr{progression} \rightarrow \descr{numeric expression}\, upto\, + \descr{numeric expression}$\\ +$\tt \qquad \;|\; \descr{numeric expression}\, downto\, + \descr{numeric expression}$\\ +$\tt \qquad \;|\; \descr{numeric expression}\, step\, + \descr{numeric expression}\, until\, \descr{numeric expression} $\\ +$\tt \descr{for list} \rightarrow \descr{expression} + \;|\; \descr{for list}\hbox{\tt ,}\, \descr{expression}$\\ +$\tt \descr{suffix list} \rightarrow \descr{suffix} + \;|\; \descr{suffix list}\hbox{\tt ,}\, \descr{suffix}$ +\end{ctabbing} +\caption{The syntax for loops} +\label{syloop} +\end{figure} + + +\section{Reading and Writing Files} +File access was one of the new language features introduced in version~0.60 +of the MetaPost language. A new operator +$$ {\tt readfrom}\ \descr{file name} $$\index{readfrom?\texttt{readfrom}}\label{Dreadfrom}% +returns a string giving the next line of input from the named +file\index{files!reading}. The \tdescr{file name} can be any primary +expression of type string. If the file has ended or cannot be read, the +result is a string consisting of a single null character. The preloaded +{\tt plain} macro package introduces the name +{\tt EOF}\index{EOF?\texttt{EOF}}\label{Deof} for this string. After +{\tt readfrom} has returned {\tt EOF}, additional reads from the same file +cause the file to be reread from the start. + +All files opened by \ttt{readfrom} that have not completely been read +yet are closed\index{files!closing} automatically when the program +terminates, but there exists a command +$${\tt closefrom}\ \descr{file name}$$% +\index{closefrom?\texttt{closefrom}}\label{Dclosefrom}% +to close files opened by {\tt readfrom} explicitly. It is wise to +manually close files you do not need to read completely (i.e. until {\tt + EOF} is returned) because otherwise such files will continue to use +internal resources and perhaps cause a \ttt{capacity exceeded!} error. + +The opposite of {\tt readfrom} is the command +$$ {\tt write}\ \descr{string expression}\ {\tt to}\ \descr{file name} $$% +\index{write to?\texttt{write to}}\label{Dwrite}% +This writes\index{files!writing} a line of text to the specified output file, +opening the file first if necessary. All such files are +closed\index{files!closing} automatically when the program terminates. They +can also be closed explicitly by using {\tt EOF}\index{EOF?\texttt{EOF}} +as the \tdescr{string expression}. The only way to tell if a {\tt write} +command has succeeded is to close the file and use {\tt readfrom} to look +at it. + + +\section{Utility Routines} + +\index{utility routines} +\index{mplib?\texttt{mplib}} +\index{metapost/base?\texttt{metapost/base}} + +This section describes some of the utility routines included in the +\texttt{mplib} directory of the development source hierarchy. Future +versions of this documentation may include more; meanwhile, please read +the source files, most have explanatory comments at the top. They are +also included in the MetaPost and larger \TeX\ distributions, typically +in a \texttt{texmf/metapost/base} directory. + + +\subsection{\texttt{TEX.mp}} + +\label{dTEX} +\index{TEX.mp?\texttt{TEX.mp}} +\index{labels, with variable text} +\index{string expressions, as labels} + +\texttt{TEX.mp} provides a way to typeset the text of a MetaPost string +expression. Suppose, for example, you need labels of the form $n_0$, +$n_1$, \ldots, $n_{10}$ across the $x$ axis. You can do this (relatively) +conveniently with \texttt{TEX.mp}, as follows: +$$\begin{verbatim} +input TEX; +beginfig(100) + last := 10; + for i := 0 upto last: + label(TEX("$n_{" & decimal(i) & "}$"), (5mm*i,0)); + endfor + ... +endfig; +\end{verbatim} +$$ +In contrast, the basic \texttt{btex} command (see p.\ \pageref{Dbtex}) +typesets verbatim text. That is, \texttt{btex~s~etex} typesets the +literal character `s'; \texttt{TEX(s)} typesets the value of the +MetaPost text variable~$s$. + +\index{LaTeX?\LaTeX!typesetting labels with} In version 0.9, +\texttt{TEX.mp} acquired two additional routines to facilitate using +\LaTeX\ to typeset labels: \texttt{TEXPRE} and \texttt{TEXPOST}. Their +values are remembered, and included before and after (respectively) each +call to \texttt{TEX}. Otherwise, each \texttt{TEX} call is effectively +typeset independently. \texttt{TEX} calls also do not interfere with +uses of {\tt verbatimtex}\index{verbatimtex?\texttt{verbatimtex}} (p.\ +\pageref{Dverbatimtex}). + +Here's the same example as above, using the \LaTeX\ commands \verb|\(| +and \verb|\)|: + +$$\begin{verbatim} +input TEX; +TEXPRE("%&latex" & char(10) & "\documentclass{article}\begin{document}"); +TEXPOST("\end{document}"); +beginfig(100) + last := 10; + for i := 0 upto last: + label(TEX("\( n_{" & decimal(i) & "} \)"), (5mm*i,0)); + endfor + ... +endfig; +\end{verbatim} +$$ +Explanation: +\begin{itemize} + +\item +The \texttt{\%\&latex} causes \LaTeX\ to be invoked instead of \TeX. +(See below, also.) Web2C- and MiKTeX-based \TeX\ implementations, at +least, understand this \texttt{\%\&} specification; see, e.g., the Web2C +documentation for details, \url{http://tug.org/web2c}. (Information on +how to do the same with other systems would be most welcome.) + +\item +The \texttt{char(10)} puts a newline (ASCII character code 10, decimal) +in the output. + +\item +The \verb|\documentclass...| is the usual way to start a \LaTeX\ +document. + +\item +The \verb|TEXPOST("\end{document}")| is not strictly necessary, due to +the behavior of \texttt{mpto}, but it is safer to include it. + +\end{itemize} + +Unfortunately, \TeX\ \verb|\special| instructions vanish in this +process. So it is not possible to use packages such as \texttt{xcolor} +and \texttt{hyperref}. + +In case you're curious, these routines are implemented very simply: they +write \texttt{btex} commands to a temporary file and then use +\texttt{scantokens} (p.\ \pageref{Dscantokens}) to process it. The +\texttt{makempx} mechanism (p.\ \pageref{Dmakempx}) does all the work of +running \TeX. + +The \verb|%&| magic on the first line is not the only way to specify +invoking a different program than (plain) \TeX. It has the advantage of +maximum flexibility: different \texttt{TEX} constructs can use different +\TeX\ processors. But at least two other methods are possible: + +\begin{itemize} +\item Set the environment variable \texttt{TEX} to \texttt{latex}---or +whatever processor you want to invoke. (To handle \ConTeXt\ fragments, +\ttt{texexec} could be used.) This might be convenient when writing a +script, or working on a project that always requires \texttt{latex}. + +\item Invoke MetaPost with the command-line option \ttt{-tex=latex} (or +whatever processor, of course). This might be useful from a Makefile, +or just a one-off run. +\end{itemize} + +\subsection{\texttt{mproof.tex}} + +\index{mproof.tex?\texttt{mproof.tex}} + +\texttt{mproof.tex} is a (plain) \TeX\ routine, not MetaPost at all. It +writes a proof sheet for MetaPost output. Call it like this: + +$$\hbox{\tt tex mproof {\sl MetaPost-output-filename}}$$ +Then process the resulting \texttt{.dvi}\index{dvi file?{\tt dvi} + file}\index{files!dvi?{\tt dvi}} file as usual. + +\section{Debugging} + +MetaPost inherits from \MF\index{metafont?\MF} numerous facilities for +interactive debugging, most of which can only be mentioned briefly here. +Further information on error messages, debugging, and generating tracing +information can be found in {\sl The\ \MF book} \cite{kn:c}. + +Suppose your input file says +$$ \hbox{\verb|draw z1--z2;|} $$ +on line 17 without first giving known values to {\tt z1} and {\tt z2}. +Figure~\ref{errmsg} shows what the MetaPost interpreter prints on your +terminal when it finds the error. The actual error message is the line +beginning with ``{\tt !}''; the next six lines give the context that +shows exactly what input was being read when the error was found; and +the ``{\tt ?}'' on last line is a prompt for your response. Since the +error message talks about an undefined $x$~coordinate, this value is +printed on the first line after the ``\verb|>>|''. In this case the +$x$~coordinate of {\tt z1} is just the unknown variable {\tt x1}, so the +interpreter prints the variable name {\tt x1} just as it would if it +were told to\index{show?\texttt{show}} ``{\tt show x1}'' at this point. + +\begin{figure}[htp] +$$\begin{verbatim} +>> x1 +! Undefined x coordinate has been replaced by 0. +<to be read again> + { +--->{ + curl1}..{curl1} +l.17 draw z1-- + z2; +? +\end{verbatim} +$$ +\caption{An example of an error message.} +\label{errmsg} +\end{figure} + +The context listing may seem a little confusing at first, but it really just +gives a few lines of text showing how much of each line has been read so far. +Each line of input is printed on two lines like this: +\begin{eqnarray*} + \descr{descriptor}\ \hbox{Text read so far} \\ + && \hbox{Text yet to be read} +\end{eqnarray*} +The \tdescr{descriptor} identifies the input source. It is either a +line number like ``{\tt l.17}'' for line 17 of the current file; or it +can be a macro name followed by ``{\tt ->}''; or it is a descriptive +phrase in angle brackets. Thus, the meaning of the context listing in +Figure~\ref{errmsg} is that the interpreter has just read line 17 of the +input file up to ``\verb|--|,'' the expansion of the \verb|--| macro has +just started, and the initial ``\verb|{|'' has been reinserted to allow +for user input before scanning this token. + +Among the possible responses to a {\tt ?} prompt are the following: +\begin{description} +\item[x] terminates the run so that you can fix your input file and start over. +\item[h] prints a help message followed by another {\tt ?} prompt. +\item[\tdescr{return}] causes the interpreter to proceed as best it can. +\item[?] prints a listing of the options available, followed by another + {\tt ?} prompt. +\end{description} + +This interactive mode is not only entered when MetaPost finds an error +in the code. It can be explicitly entered by the \ttindex{errmessage} +command. The \ttindex{message}\label{Dmessage} command writes a string +argument to a new line on the terminal. The +\ttindex{errmessage}\label{Derrmessage} command is similar, but the +string argument is preceded by \verb|"! "| and followed by~\verb|"."|. +Additionally, some lines of context are appended as in MetaPost's normal +error messages. If the user now types ``h'', the most recent +\ttindex{errhelp}\label{Derrhelp} string will be shown (unless it was +empty). + +\begin{figure}[htp] +\begin{ctabbing} +$\tt \descr{message command} \rightarrow errhelp \descr{string expression}$\\ +$\tt \qquad \;|\; errmessage \descr{string expression}$\\ +$\tt \qquad \;|\; message \descr{string expression}$ +\end{ctabbing} +\caption{The syntax for message commands} +\label{symsg} +\end{figure} + +Error messages and responses to {\tt show} commands are also written +into the transcript\index{files!transcript} file whose name is obtained +from the name of the main input file by changing ``{\tt .mp}''\index{mp + file?{\tt mp} file}\index{files!mp?{\tt mp}} to ``{\tt + .log}''\index{log file?{\tt log} file}\index{files!log?{\tt + log}}. When the internal variable\index{internal + variables}\index{variables!internal} {\tt + tracingonline}\index{tracingonline?\texttt{tracingonline}} is at its +default value of zero, some {\tt show} commands print their results in +full detail only in the transcript file. + +Only one type of {\tt show}\index{show?\texttt{show}} command has been +discussed so far: {\tt show} followed by a comma-separated list of +expressions prints symbolic representations of the expressions. + +The {\tt showtoken}\index{showtoken?\texttt{showtoken}}\label{Dshtok} +command can be used to show the +parameters and replacement text of a macro. It takes a comma-separated list of +tokens and identifies each one. If the token is a primitive as in +``\verb|showtoken +|'' it is just identified as being itself: +$$ \hbox{\verb|> +=+|} $$ +Applying {\tt showtoken} to a variable or a {\tt vardef} macro yields +$$ \hbox{\tt > } \descr{token}\hbox{\tt =variable} $$ + +To get more information about a variable, use +{\tt showvariable}\index{showvariable?\texttt{showvariable}}\label{Dshvar} +instead of {\tt showtoken}. The +argument to {\tt showvariable} is a comma-separated list of symbolic tokens +and the result is a description of all the variables whose names begin with +one of the listed tokens. This even works for {\tt vardef} macros. For +example, {\tt showvariable z} yields +$$ \hbox{\verb|z@#=macro:->begingroup(x(SUFFIX2),y(SUFFIX2))endgroup|} $$ + +There is also a {\tt +showdependencies}\index{showdependencies?\texttt{showdependencies}}\label{Dshdep} +command that takes no arguments and prints a list of all {\em dependent} +variables and how the linear equations given so far make them depend on +other variables. Thus after +$$ \hbox{\tt z2-z1=(5,10); z1+z2=(a,b);} $$ +{\tt showdependencies} prints what is shown in Figure~\ref{shdep}. This could +be useful in answering a question like ``What does it mean +`{\tt !\ Undefined x coordinate}?' I thought the equations given so far would +determine {\tt x1}.'' + +\begin{figure}[htp] +$$\begin{verbatim} +x2=0.5a+2.5 +y2=0.5b+5 +x1=0.5a-2.5 +y1=0.5b-5 +\end{verbatim} +$$ +\caption{The result of {\tt z2-z1=(5,10); z1+z2=(a,b); showdependencies;}} +\label{shdep} +\end{figure} + +When all else fails, the predefined macro {\tt +tracingall}\index{tracingall?\texttt{tracingall}}\label{Dtall} causes +the interpreter to print a detailed listing of everything it is doing. +Since the tracing information is often quite voluminous, it may be +better to use the {\tt +loggingall}\index{loggingall?\texttt{loggingall}}\label{Dlogall} macro +that produces the same information but only writes it in the +transcript\index{files!transcript} file. There is also a {\tt +tracingnone}\index{tracingnone?\texttt{tracingnone}}\label{Dtnone} macro +that turns off all the tracing output. + +Tracing output is controlled by the set of internal +variables\index{internal variables}\index{variables!internal} summarized +below. When any one of these variables is given a positive value, the +corresponding form of tracing is turned on. Here is the set of tracing +variables and what happens when each of them is positive: +\begin{description} +\item[{\tt tracingcapsules}]\index{tracingcapsules?\texttt{tracingcapsules}}\label{Dtcapsules}% +shows the values of temporary quantities (capsules) when they become known. +% +\item[{\tt tracingchoices}]\index{tracingchoices?\texttt{tracingchoices}}\label{Dtchoices}% +shows the B\'ezier control\index{control points} points of each new path +when they are chosen. % +\item[{\tt tracingcommands}]\index{tracingcommands?\texttt{tracingcommands}}\label{Dtcommands}% +shows the commands before they are performed. A setting ${}>1$ also shows +{\tt if}\index{if?\texttt{if}} tests and loops before they are expanded; +a setting ${}>2$ shows algebraic operations before they are performed. +% +\item[{\tt tracingequations}]\index{tracingequations?\texttt{tracingequations}}\label{Dtequations}% +shows each variable when it becomes known. +% +\item[{\tt tracinglostchars}]\index{tracinglostchars?\texttt{tracinglostchars}}\label{Dtlostchars}% +warns about characters omitted from a picture because they are not in the font +being used to typeset labels. +% +\item[{\tt tracingmacros}]\index{tracingmacros?\texttt{tracingmacros}}\label{Dtmacros}% +shows macros before they are expanded. +% +\item[{\tt tracingoutput}]\index{tracingoutput?\texttt{tracingoutput}}\label{Dtoutput}% +shows pictures as they are being shipped out as PostScript files. +% +\item[{\tt tracingrestores}]\index{tracingrestores?\texttt{tracingrestores}}\label{Dtrestores}% +shows symbols and internal variables as they are being restored at the end +of a group. +% +\item[{\tt tracingspecs}]\index{tracingspecs?\texttt{tracingspecs}}\label{Dtspecs}% +shows the outlines generated when drawing with a +polygonal pen\index{pens!polygonal}. +% +\item[{\tt tracingstats}]\index{tracingstats?\texttt{tracingstats}}\label{Dtstats} +shows in the transcript file at the end of the job how many of the +MetaPost interpreter's limited resources were used. +\end{description} + + +\section*{Acknowledgement} + +I would like to thank Don Knuth for making this work possible by +developing \MF\ and placing it in the public domain. I am also indebted +to him for helpful suggestions, particularly with regard to the +treatment of included \TeX\ material. + + +\appendix +\include{mpman-app-refman} +\include{mpman-app-legacy} + + +\bibliographystyle{plain} +\bibliography{mpman} + + +\printindex + + +\end{document} + +% Copyright 1990 - 1995 by AT&T Bell Laboratories. +% Updated 2006 by Taco Hoekwater, Karl Berry, and others. + +% Permission to use, copy, modify, and distribute this software +% and its documentation for any purpose and without fee is hereby +% granted, provided that the above copyright notice appear in all +% copies and that both that the copyright notice and this +% permission notice and warranty disclaimer appear in supporting +% documentation, and that the names of AT&T Bell Laboratories or +% any of its entities not be used in advertising or publicity +% pertaining to distribution of the software without specific, +% written prior permission. + +% AT&T disclaims all warranties with regard to this software, +% including all implied warranties of merchantability and fitness. +% In no event shall AT&T be liable for any special, indirect or +% consequential damages or any damages whatsoever resulting from +% loss of use, data or profits, whether in an action of contract, +% negligence or other tortious action, arising out of or in +% connection with the use or performance of this software. + +% In addition, John Hobby, the original author of MetaPost and this +% manual, makes the following requests: +% - I request that it remain clear that I am the author of +% "A User's Manual for MetaPost" and "Drawing Graphs with MetaPost". +% - I request to be consulted before significant changes are made. + +%%% Local Variables: +%%% mode: latex +%%% TeX-PDF-mode: t +%%% TeX-master: t +%%% End: diff --git a/Master/texmf-dist/doc/metapost/base/source-manual/timepop.d b/Master/texmf-dist/doc/metapost/base/source-manual/timepop.d new file mode 100644 index 00000000000..c8b2bae7a04 --- /dev/null +++ b/Master/texmf-dist/doc/metapost/base/source-manual/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 |