From e0c6872cf40896c7be36b11dcc744620f10adf1d Mon Sep 17 00:00:00 2001 From: Norbert Preining Date: Mon, 2 Sep 2019 13:46:59 +0900 Subject: Initial commit --- systems/doc/metapost/source-manual/Makefile | 89 + systems/doc/metapost/source-manual/README | 21 + systems/doc/metapost/source-manual/TODO | 124 + systems/doc/metapost/source-manual/agepop91.d | 85 + systems/doc/metapost/source-manual/agepopm.d | 85 + systems/doc/metapost/source-manual/charts.mp | 120 + systems/doc/metapost/source-manual/cm2lm.map | 8 + systems/doc/metapost/source-manual/countries.d | 60 + systems/doc/metapost/source-manual/ctabbing.sty | 18 + systems/doc/metapost/source-manual/demo.ms | 105 + systems/doc/metapost/source-manual/energy.d | 75 + systems/doc/metapost/source-manual/figs.1 | 227 + systems/doc/metapost/source-manual/figs.mp | 24 + systems/doc/metapost/source-manual/grdemo-doc.ms | 184 + systems/doc/metapost/source-manual/grdemo-doc.ps | 1025 ++++ systems/doc/metapost/source-manual/grdemo.eps | 779 +++ systems/doc/metapost/source-manual/grdemo.mp | 37 + systems/doc/metapost/source-manual/grdemo.ms | 124 + systems/doc/metapost/source-manual/lead.d | 24 + systems/doc/metapost/source-manual/matmul.d | 21 + systems/doc/metapost/source-manual/mpboxes.bib | 19 + systems/doc/metapost/source-manual/mpboxes.mp | 146 + systems/doc/metapost/source-manual/mpboxes.tex | 572 ++ systems/doc/metapost/source-manual/mpgraph.bib | 98 + systems/doc/metapost/source-manual/mpgraph.mp | 141 + systems/doc/metapost/source-manual/mpgraph.tex | 1044 ++++ systems/doc/metapost/source-manual/mplibapi.tex | 1572 +++++ .../metapost/source-manual/mpman-app-legacy.tex | 347 ++ .../source-manual/mpman-app-numbersystems.tex | 98 + .../doc/metapost/source-manual/mpman-app-optab.tex | 156 + .../metapost/source-manual/mpman-app-refman.tex | 1068 ++++ systems/doc/metapost/source-manual/mpman-charts.mp | 210 + systems/doc/metapost/source-manual/mpman.bib | 135 + systems/doc/metapost/source-manual/mpman.ist | 4 + systems/doc/metapost/source-manual/mpman.mp | 851 +++ systems/doc/metapost/source-manual/mpman.tex | 6008 ++++++++++++++++++++ systems/doc/metapost/source-manual/timepop.d | 21 + 37 files changed, 15725 insertions(+) create mode 100644 systems/doc/metapost/source-manual/Makefile create mode 100644 systems/doc/metapost/source-manual/README create mode 100644 systems/doc/metapost/source-manual/TODO create mode 100644 systems/doc/metapost/source-manual/agepop91.d create mode 100644 systems/doc/metapost/source-manual/agepopm.d create mode 100644 systems/doc/metapost/source-manual/charts.mp create mode 100644 systems/doc/metapost/source-manual/cm2lm.map create mode 100644 systems/doc/metapost/source-manual/countries.d create mode 100644 systems/doc/metapost/source-manual/ctabbing.sty create mode 100644 systems/doc/metapost/source-manual/demo.ms create mode 100644 systems/doc/metapost/source-manual/energy.d create mode 100644 systems/doc/metapost/source-manual/figs.1 create mode 100644 systems/doc/metapost/source-manual/figs.mp create mode 100644 systems/doc/metapost/source-manual/grdemo-doc.ms create mode 100644 systems/doc/metapost/source-manual/grdemo-doc.ps create mode 100644 systems/doc/metapost/source-manual/grdemo.eps create mode 100644 systems/doc/metapost/source-manual/grdemo.mp create mode 100644 systems/doc/metapost/source-manual/grdemo.ms create mode 100644 systems/doc/metapost/source-manual/lead.d create mode 100644 systems/doc/metapost/source-manual/matmul.d create mode 100644 systems/doc/metapost/source-manual/mpboxes.bib create mode 100644 systems/doc/metapost/source-manual/mpboxes.mp create mode 100644 systems/doc/metapost/source-manual/mpboxes.tex create mode 100644 systems/doc/metapost/source-manual/mpgraph.bib create mode 100644 systems/doc/metapost/source-manual/mpgraph.mp create mode 100644 systems/doc/metapost/source-manual/mpgraph.tex create mode 100644 systems/doc/metapost/source-manual/mplibapi.tex create mode 100644 systems/doc/metapost/source-manual/mpman-app-legacy.tex create mode 100644 systems/doc/metapost/source-manual/mpman-app-numbersystems.tex create mode 100644 systems/doc/metapost/source-manual/mpman-app-optab.tex create mode 100644 systems/doc/metapost/source-manual/mpman-app-refman.tex create mode 100644 systems/doc/metapost/source-manual/mpman-charts.mp create mode 100644 systems/doc/metapost/source-manual/mpman.bib create mode 100644 systems/doc/metapost/source-manual/mpman.ist create mode 100644 systems/doc/metapost/source-manual/mpman.mp create mode 100644 systems/doc/metapost/source-manual/mpman.tex create mode 100644 systems/doc/metapost/source-manual/timepop.d (limited to 'systems/doc/metapost/source-manual') diff --git a/systems/doc/metapost/source-manual/Makefile b/systems/doc/metapost/source-manual/Makefile new file mode 100644 index 0000000000..e3e170652b --- /dev/null +++ b/systems/doc/metapost/source-manual/Makefile @@ -0,0 +1,89 @@ +# Makefile for MetaPost documentation. Public domain. +# Rules for the groff/troff docs are in TeX Live, +# texmf-dist/doc/metapost/base/Makefile. + +RM = -rm -f +latex = latex +pdflatex = pdflatex +contextpdf = texexec +contextdvi = texexec --dvi +dvips = dvips +bibtex = bibtex +mpost = mpost -tex=tex +mkindex = makeindex -c -s mpman.ist + +all: pdf +pdf: mpman.pdf mpgraph.pdf mpboxes.pdf mplibapi.pdf +ps: mpman.ps mpgraph.ps mpboxes.ps mplibapi.ps + +mplibapi.pdf: mplibapi.tex + mv -f mpgraph.mp mpgraph.saved + $(contextpdf) mplibapi + mv -f mpgraph.saved mpgraph.mp + +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-app-numbersystems.tex mpman.bib mpman.ist mpman.mp charts.mp mpman-charts.mp + $(mpost) mpman + $(mpost) mpman-charts + $(pdflatex) mpman + $(bibtex) mpman + $(pdflatex) mpman + $(pdflatex) mpman + $(mkindex) mpman + $(pdflatex) mpman + +mplibapi.ps: mplibapi.tex + mv -f mpgraph.mp mpgraph.saved + $(contextdvi) mplibapi + mv -f mpgraph.saved mpgraph.mp + $(dvips) mplibapi + +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 charts.mp mpman-charts.mp + $(mpost) mpman + $(mpost) mpman-charts + $(latex) mpman + $(bibtex) mpman + $(latex) mpman + $(latex) mpman + $(mkindex) mpman + $(latex) mpman + $(dvips) mpman + +clean: + $(RM) *.aux *.bbl *.blg *.dvi *.idx *.ilg *.ind *.log *.mps *.mpx *.out *.toc mpxerr.* + $(RM) *.tui *.tuo *.tmp *-mpgraph.mp + +distclean: clean + $(RM) mp?*.pdf mp?*.ps diff --git a/systems/doc/metapost/source-manual/README b/systems/doc/metapost/source-manual/README new file mode 100644 index 0000000000..2f7a8f66ad --- /dev/null +++ b/systems/doc/metapost/source-manual/README @@ -0,0 +1,21 @@ +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, +later updated Troy Henderson and Stephan Hennig, and currently +maintained by the MetaPost developers. 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. + +See the Makefile for the sequence of commands to create the DVI/PS/PDF output. diff --git a/systems/doc/metapost/source-manual/TODO b/systems/doc/metapost/source-manual/TODO new file mode 100644 index 0000000000..db21b676ab --- /dev/null +++ b/systems/doc/metapost/source-manual/TODO @@ -0,0 +1,124 @@ +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 *** +***************************** +* Describe boundingpath + +* Describe prescriptpart/postscriptpart. + +* Describe penrazor, penspeck. + +* Describe drawdot withpen counter-intuitivity. Describe recent change + in drawdot definition. + + + +***************************** +*** Short term issues *** +***************************** + +Integrating Text and Graphics: +* Fix bad description of prologues in table ivartab. +* Move discussion of prologues to sec. workflow2. +* Discuss difference between + label(btex ... etex, ...) + draw btex ... etex + +Advanced Graphics: +* Describe turningnumber (mention differences in sec. 'MetaPost + Versus METAFONT'). +* Make fig56 black and white. + +Notes on the MetaPost Workflow: +* Describe variables jobname, charcode. + +Reference Manual: +* Describe environment variables and configuration files. + +Legacy Information: +* Cite original Hobby papers. + +Debugging: +* turningnumber and tracingchoices > 2 + + + +***************************** +*** Mid Term Issues *** +***************************** + +Introduction: +* Revise introduction. + +Integrating Text and Graphics: +* Completely revise this section and consolidate information + scattered around mpman. +* More information and examples on alternatives for calling TeX + or LaTeX from within MetaPost. +* Revise (and add more) flow charts for MetaPost workflow. +* Describe whitespace handling of verbatimtex/btex/etex. +* Why is verbatimtex\end{document}etex "safer", cf. sec. 13.1? +* Discuss difference between "draw withpen" and + "label(, ...) withpen" (when label bug is fixed). + +Advanced Graphics: +* Add a sub-section discussing colours. +* Colour cars and change code example in section piccomp. + +Reference Manual: +* Describe missing variables, constants, and operators. +* Add description of interaction mode. + +Legacy Information: +* Describe mpware (currently scattered around in mpman). + + + + +***************************** +*** Long Term Issues *** +***************************** + +Title page: +* Add decent title graphics. + +Reference Manual: +* Review presentation of primitives and plain macros in appendix A. +* Build reference manual automatically from mp.web (as a separate manual?). + +General: +* Make mpman self-contained (no need to look-up sth. in 'The MetaFontbook'). +* 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/systems/doc/metapost/source-manual/agepop91.d b/systems/doc/metapost/source-manual/agepop91.d new file mode 100644 index 0000000000..2dcd5dc0da --- /dev/null +++ b/systems/doc/metapost/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/systems/doc/metapost/source-manual/agepopm.d b/systems/doc/metapost/source-manual/agepopm.d new file mode 100644 index 0000000000..7451d4601b --- /dev/null +++ b/systems/doc/metapost/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/systems/doc/metapost/source-manual/charts.mp b/systems/doc/metapost/source-manual/charts.mp new file mode 100644 index 0000000000..f7ba689a50 --- /dev/null +++ b/systems/doc/metapost/source-manual/charts.mp @@ -0,0 +1,120 @@ +% Support package for drawing charts. + +def _drawNode = drawboxed enddef; + +%%% These paramaters determine the size of nodes and the grid distance. +newinternal applwidth; applwidth := 30bp; +newinternal applheight; applheight := 14bp; +newinternal extwidth; extwidth := 30bp; +newinternal extheight; extheight := 14bp; +newinternal rowscale; rowscale := 100bp; +newinternal colscale; colscale := 100bp; + +%%% This macro builds and draws a rectangular node at a given location +%%% with text indicating an application. +%% @param i Node suffix. +%% @param row Row. +%% @param col Column. +%% @param text The text to render in the box node. +def appl(suffix i)(expr coor)(text t) = + boxit.i(t); + i.c = coor; + i.e = i.c + .5applwidth*right; + i.n = i.c + .5applheight*up; + _drawNode(i); +enddef; + + +%%% This macro builds and draws an oval node at a given location with +%%% text indicating a file name extension. +%% @param i Node suffix. +%% @param row Row. +%% @param col Column. +%% @param text The text to render in the oval node. +def ext(suffix i)(expr coor)(text t) = + circleit.i(t); + i.c = coor; + i.e = i.c + .5extwidth*right; + i.n = i.c + .5extheight*up; + _drawNode(i); +enddef; + + +%%% This macro builds and draws a rectangular node at a given location +%%% with text indicating an application. +%% @param i Node suffix. +%% @param row Row. +%% @param col Column. +%% @param text The text to render in the box node. +def appl_rc(suffix i)(expr coor)(text t) = + boxit.i(t); + i.c = (colscale * ypart coor, -rowscale * xpart coor); + i.e = i.c + .5applwidth*right; + i.n = i.c + .5applheight*up; + _drawNode(i); +enddef; + + +%%% This macro builds and draws an oval node at a given location with +%%% text indicating a file name extension. +%% @param i Node suffix. +%% @param row Row. +%% @param col Column. +%% @param text The text to render in the oval node. +def ext_rc(suffix i)(expr coor)(text t) = + circleit.i(t); + i.c = (colscale * ypart coor, -rowscale * xpart coor); + i.e = i.c + .5extwidth*right; + i.n = i.c + .5extheight*up; + _drawNode(i); +enddef; + + +%%% This macro draws a straight arrow between two nodes. Arrow length +%%% is corrected for the pen width, so that the arrow doesn't sink into +%%% the frame of the target node. If pen width is changed, the code +%%% "0.5bp" has to be replaced by half of the new pen width. +%% @param a Source node. +%% @param b Target node. +def line(suffix a,b) = + begingroup + save p;path p; + p := a.c--b.c cutbefore bpath(a) cutafter bpath(b); + drawarrow subpath (0, arctime (arclength p - 0.5bp) of p) of p; + endgroup +enddef; + + +%%% This macro draws a curved arrow between two nodes with determined +%%% leaving and entering angles. Arrow length is corrected for the pen +%%% width so that the arrow doesn't sink into the frame of the target +%%% node. If pen width is changed, the code "0.5bp" has to be replaced +%%% by half of the new pen width. +%% @param a Source node. +%% @param b Target node. +%% @param anga Leaving angle at (center of) node a. +%% @param angb Entering angle at (center of) node b. +def curve(suffix a,b)(expr anga,angb) = + begingroup + save p;path p; + p := a.c{dir anga}..{dir angb}b.c cutbefore bpath(a) cutafter bpath(b); + drawarrow subpath (0, arctime (arclength p - 0.5bp) of p) of p; + endgroup +enddef; + + +%%% This macro draws a curved arrow between two nodes with determined +%%% leaving and entering angles offset. Arrow length is corrected for +%%% the pen width so that the arrow doesn't sink into the frame of the +%%% target node. If pen width is changed, the code "0.5bp" has to be +%%% replaced by half of the new pen width. +%% @param a Source node. +%% @param b Target node. +%% @param angr Offset to entering and leaving angles at nodes a and b. +def curve_rel(suffix a,b)(expr angr) = + begingroup + save alpha; + alpha = angle(b.c-a.c); + curve(a, b, alpha+angr, alpha-angr); + endgroup +enddef; diff --git a/systems/doc/metapost/source-manual/cm2lm.map b/systems/doc/metapost/source-manual/cm2lm.map new file mode 100644 index 0000000000..619facd6d0 --- /dev/null +++ b/systems/doc/metapost/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/systems/doc/metapost/source-manual/countries.d b/systems/doc/metapost/source-manual/countries.d new file mode 100644 index 0000000000..2b372f882c --- /dev/null +++ b/systems/doc/metapost/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/systems/doc/metapost/source-manual/ctabbing.sty b/systems/doc/metapost/source-manual/ctabbing.sty new file mode 100644 index 0000000000..b61ec6ed78 --- /dev/null +++ b/systems/doc/metapost/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/systems/doc/metapost/source-manual/demo.ms b/systems/doc/metapost/source-manual/demo.ms new file mode 100644 index 0000000000..736c8641fb --- /dev/null +++ b/systems/doc/metapost/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/systems/doc/metapost/source-manual/energy.d b/systems/doc/metapost/source-manual/energy.d new file mode 100644 index 0000000000..0a8fa42d58 --- /dev/null +++ b/systems/doc/metapost/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/systems/doc/metapost/source-manual/figs.1 b/systems/doc/metapost/source-manual/figs.1 new file mode 100644 index 0000000000..b47233e3ad --- /dev/null +++ b/systems/doc/metapost/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/systems/doc/metapost/source-manual/figs.mp b/systems/doc/metapost/source-manual/figs.mp new file mode 100644 index 0000000000..c8e87ba562 --- /dev/null +++ b/systems/doc/metapost/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/systems/doc/metapost/source-manual/grdemo-doc.ms b/systems/doc/metapost/source-manual/grdemo-doc.ms new file mode 100644 index 0000000000..19c0ed030d --- /dev/null +++ b/systems/doc/metapost/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/systems/doc/metapost/source-manual/grdemo-doc.ps b/systems/doc/metapost/source-manual/grdemo-doc.ps new file mode 100644 index 0000000000..f60e465bf1 --- /dev/null +++ b/systems/doc/metapost/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/systems/doc/metapost/source-manual/grdemo.eps b/systems/doc/metapost/source-manual/grdemo.eps new file mode 100644 index 0000000000..ae476c1973 --- /dev/null +++ b/systems/doc/metapost/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/systems/doc/metapost/source-manual/grdemo.mp b/systems/doc/metapost/source-manual/grdemo.mp new file mode 100644 index 0000000000..14fb760925 --- /dev/null +++ b/systems/doc/metapost/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/systems/doc/metapost/source-manual/grdemo.ms b/systems/doc/metapost/source-manual/grdemo.ms new file mode 100644 index 0000000000..fbcbfaceff --- /dev/null +++ b/systems/doc/metapost/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/systems/doc/metapost/source-manual/lead.d b/systems/doc/metapost/source-manual/lead.d new file mode 100644 index 0000000000..2d09412438 --- /dev/null +++ b/systems/doc/metapost/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/systems/doc/metapost/source-manual/matmul.d b/systems/doc/metapost/source-manual/matmul.d new file mode 100644 index 0000000000..6a0afe941c --- /dev/null +++ b/systems/doc/metapost/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/systems/doc/metapost/source-manual/mpboxes.bib b/systems/doc/metapost/source-manual/mpboxes.bib new file mode 100644 index 0000000000..6b4042b1a8 --- /dev/null +++ b/systems/doc/metapost/source-manual/mpboxes.bib @@ -0,0 +1,19 @@ +% 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/systems/doc/metapost/source-manual/mpboxes.mp b/systems/doc/metapost/source-manual/mpboxes.mp new file mode 100644 index 0000000000..10ec530dbe --- /dev/null +++ b/systems/doc/metapost/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/systems/doc/metapost/source-manual/mpboxes.tex b/systems/doc/metapost/source-manual/mpboxes.tex new file mode 100644 index 0000000000..a167df8e26 --- /dev/null +++ b/systems/doc/metapost/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/systems/doc/metapost/source-manual/mpgraph.bib b/systems/doc/metapost/source-manual/mpgraph.bib new file mode 100644 index 0000000000..27ef07de1f --- /dev/null +++ b/systems/doc/metapost/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/systems/doc/metapost/source-manual/mpgraph.mp b/systems/doc/metapost/source-manual/mpgraph.mp new file mode 100644 index 0000000000..2c94edfe54 --- /dev/null +++ b/systems/doc/metapost/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/systems/doc/metapost/source-manual/mpgraph.tex b/systems/doc/metapost/source-manual/mpgraph.tex new file mode 100644 index 0000000000..759c6e8506 --- /dev/null +++ b/systems/doc/metapost/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 + +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/systems/doc/metapost/source-manual/mplibapi.tex b/systems/doc/metapost/source-manual/mplibapi.tex new file mode 100644 index 0000000000..b4638fcda0 --- /dev/null +++ b/systems/doc/metapost/source-manual/mplibapi.tex @@ -0,0 +1,1572 @@ + +\def\MPLIB{MPlib} +\def\MP{MetaPost} +\def\POSTSCRIPT{PostScript} +\def\PS{PostScript} +\def\SVG{SVG} +\def\PNG{PNG} +\def\MNG{MNG} +\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 + +\defineselector[title][max=2,n=2] + +\def\ctypedef#1#2#3{\subsubsection[#2]{\select{title}{\type{#2}}{\type{#1#2#3}}}\bookmark{#2}} +\def\cenumeration#1{\subsubsection{\type{#1}}\bookmark{#1}} +\def\cfunction#1#2#3{\subsubsection[#2]{\select{title}{\type{#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, version 2.00}} +\blank[3*line] +\centerline{Taco Hoekwater, September 2012 -- Luigi Scarso, February 2018} +\StopTitlePage + +\section{Table of contents} + +\setupselector[title][n=1] + +\placecontent[criterium=all,level=subsection] + +\setupselector[title][n=2] + +\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 "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. See below for how to +preload a macro package. + +\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 preloads the \quote{plain} macro 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 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 +\NC int \NC math_mode \NC 0 \NC set this to \type{mp_math_double_mode} to use doubles + instead of scaled (\type{mp_math_scaled_mode}) values\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 configuration 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 redirected +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_stream \NC ship_out \NC holds the exported EPS, SVG or PNG string \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 at least \type{mplibps.h} to be able to actually +make use of 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 null characters (\type{\0}) +in \type{data} except when \type{ship_out} is used for PNG output. + +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\ inside 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 argument is the input file name. This is the name that was given +in the \MP\ language, so it may not be the same as the name of the actual +file that is being used, depending on how 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 or SVG output (w)\NC \NR +\NC mp_filetype_bitmap \NC PNG output (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_math_mode} + +\starttabulate[|l|p|] +\NC mp_math_scaled_mode \NC uses scaled point data for numerical values \NC \NR +\NC mp_math_double_mode \NC uses IEEE double floating point data for numerical values \NC \NR +\NC mp_math_binary_mode \NC not used yet. \NC \NR +\NC mp_math_decimal_mode \NC not used yet. \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_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{boolean }{mp_finished}{(MP mp)} + +Returns the current value of \type{mp->finished}. +This function is useful to check if \type{mp_execute} will execute the string, because +if \type{mp->finished} is \type{true} it will return after resetting the streams. + + + +\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 path and knot manipulation} + +\subsection{Enumerations} + +\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 + + +\subsection{Structures} + +\ctypedef {}{mp_number}{} + +Numerical values are represented by opaque structure pointers named \type{mp_number}. + +\ctypedef {}{mp_knot}{} + +Each \MPLIB\ path (a sequence of \MP\ points) is represented as a linked list +of structure pointers of the type \type{mp_knot}. + +\starttabulate[|l|l|p|] +\NC mp_knot \NC next \NC the next knot, or NULL\NC \NR +\NC mp_knot_type \NC data.types.left_type \NC the \type{mp_knot_type} for the left side \NC \NR +\NC mp_knot_type \NC data.types.right_type \NC the \type{mp_knot_type} for the right side \NC \NR +\NC mp_number \NC x_coord \NC $x$\NC \NR +\NC mp_number \NC y_coord \NC $y$\NC \NR +\NC mp_number \NC left_x \NC $x$ of the left (incoming) control point\NC \NR +\NC mp_number \NC left_y \NC $y$ of the left (incoming) control point\NC \NR +\NC mp_number \NC right_x \NC $x$ of the right (outgoing) control point\NC \NR +\NC mp_number \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 + +Paths are always represented as a circular list. The difference between cyclic and +non-cyclic paths is indicated by their \type{mp_knot_type}. + +While the fields of the knot structure are in fact accessible, it is better to use +the access functions below as the internal structure tends to change. + +\subsection{Functions for accessing knot data} + +\cfunction{mp_number}{mp_knot_x_coord}{(MP mp,mp_knot p)} +Access the $x$ coordinate of the knot. +\cfunction{mp_number}{mp_knot_y_coord}{(MP mp,mp_knot p)} +Access the $y$ coordinate of the knot. +\cfunction{mp_number}{mp_knot_left_x}{(MP mp,mp_knot p)} +Access the $x$ coordinate of the left control point of the knot. +\cfunction{mp_number}{mp_knot_left_y}{(MP mp,mp_knot p)} +Access the $y$ coordinate of the left control point of the knot. +\cfunction{mp_number}{mp_knot_right_x}{(MP mp,mp_knot p)} +Access the $x$ coordinate of the right control point of the knot. +\cfunction{mp_number}{mp_knot_right_y}{(MP mp,mp_knot p)} +Access the $y$ coordinate of the right control point of the knot. +\cfunction{int}{mp_knot_left_type}{(MP mp,mp_knot p)} +Access the type of the knot on the left side. +\cfunction{int}{mp_knot_right_type}{(MP mp,mp_knot p)} +Access the type of the knot on the right side. +\cfunction{mp_knot}{mp_knot_next}{(MP mp,mp_knot p)} +Access the pointer to the next knot. +\cfunction{mp_number}{mp_knot_left_curl}{(MP mp,mp_knot p)} +Access the left curl of the knot (applies to unresolved knots, see below). +\cfunction{mp_number}{mp_knot_left_given}{(MP mp,mp_knot p)} +Access the left given value of the knot (applies to unresolved knots, see below). +\cfunction{mp_number}{mp_knot_left_tension}{(MP mp,mp_knot p)} +Access the left tension of the knot (applies to unresolved knots, see below). +\cfunction{mp_number}{mp_knot_right_curl}{(MP mp,mp_knot p)} +Access the right curl value of the knot (applies to unresolved knots, see below). +\cfunction{mp_number}{mp_knot_right_given}{(MP mp,mp_knot p)} +Access the right given value of the knot (applies to unresolved knots, see below). +\cfunction{mp_number}{mp_knot_right_tension}{(MP mp,mp_knot p)} +Access the right tension value of the knot (applies to unresolved knots, see below). + +\cfunction{double}{mp_number_as_double}{(MP mp,mp_number n)} + +Converts an \type{mp_number} to \type{double}. + +\subsection{Functions for creating and modifying knot data} + +\cfunction{mp_knot}{mp_create_knot}{(MP mp)} + +Allocates and returns a new knot. Returns \type{NULL} on (malloc) failure. + +\cfunction{int}{mp_set_knot}{(MP mp,mp_knot p,double x,double y)} + +Fills in the coordinate of knot \type{p}. \type{x1} and \type{y1} values should be +within the proper range for the current numerical mode. +Return 1 on success, 0 on failure. + +\cfunction{int}{mp_close_path}{(MP mp,mp_knot p,mp_knot q)} + +Connects \type{p} and \type{q} using an \quote{endpoint join}, where \type{p} is the last knot +of the path, and \type{q} is the first knot. The right tension of \type{p} and the +left tension of \type{q} are (re)set to the default of 1.0. + +Because all knot list data structures are always circular, this is needed to end the path +properly even if the path is not intended cyclic (or use \type{mp_close_path_cycle()}, +if it is indeed a cycle). +Return 1 on success, 0 on failure. + +\cfunction{int}{mp_close_path_cycle}{(MP mp,mp_knot p,mp_knot q)} + +Connects \type{p} and \type{q} using an \quote{open join}, where \type{p} is the last knot +of the path, and \type{q} is the first knot. The right tension of \type{p} and the +left tension of \type{q} are (re)set to the default of 1.0. + +This is needed to mimic metapost's \type{cycle}. +return 1 on success, 0 on failure. + +\cfunction{mp_knot}{mp_append_knot}{(MP mp,mp_knot p,double x,double y)} + +Appends a knot to previous knot \type{q}, and returns the new knot. +This is a convenience method combining \type{mp_create_knot()}, \type{mp_set_knot()}, and +(if \type{q} is not NULL) \type{mp_close_path_cycle()}. +Returns NULL on failure. + +\cfunction{int}{mp_set_knot_left_curl}{(MP mp,mp_knot q,double value)} + +Sets the left curl value for a knot. +\type{fabs(value)} should be less than 4096.0 +return 1 on success, 0 on failure. + +\cfunction{int}{mp_set_knot_right_curl}{(MP mp,mp_knot q,double value)} + +Sets the right curl value for a knot. +\type{fabs(value)} should be less than 4096.0 +return 1 on success, 0 on failure. + +\cfunction{int}{mp_set_knot_curl}{(MP mp,mp_knot q,double value)} + +Sets the curl value for a knot. +\type{fabs(value)} should be less than 4096.0 +return 1 on success, 0 on failure. + +\cfunction{int}{mp_set_knotpair_curls}{(MP mp,mp_knot p,mp_knot q,double t1,double t2)} + +A convenience method that calls \type{mp_set_knot_curl(mp,p,t1)} and \type{mp_set_knot_curl(mp,q,t2)} +return 1 if both succeed, 0 otherwise. + +\cfunction{int}{mp_set_knot_direction}{(MP mp,mp_knot q,double x,double y)} + +Sets the direction \type{{x,y}} value for a knot. +\type{fabs(x)} and \type{fabs(y)} should be less than 4096.0 +return 1 on success, 0 on failure. + +\cfunction{int}{mp_set_knotpair_directions}{(MP mp,mp_knot p,mp_knot q,double x1,double y1,double x2,double y2)} + +A convenience method that calls +\type{mp_set_knot_direction(mp,p,x1,y1)} and \type{mp_set_knot_direction(mp,p,x2,y2)} +return 1 if both succeed, 0 otherwise. + +\cfunction{int}{mp_set_knotpair_tensions}{(MP mp,mp_knot p,mp_knot q,double t1,double t2)} + +Sets the tension specifiers for a pair of connected knots. +\type{fabs(t1)} and \type{fabs(t2)} should be more than 0.75 and less than 4096.0 +return 1 on success, 0 on failure. + +\cfunction{int}{mp_set_knot_left_tension}{(MP mp, mp_knot p, double t1)} + +Set the left tension of a knot. \type{fabs(t1)} should be more than 0.75 and less than 4096.0 +return 1 on success, 0 on failure. + +\cfunction{int}{mp_set_knot_right_tension}{(MP mp, mp_knot p, double t1)} + +Set the right tension of a knot. \type{fabs(t1)} should be more than 0.75 and less than 4096.0 +return 1 on success, 0 on failure. + +\cfunction{int}{mp_set_knot_left_control}{(MP mp, mp_knot p, double x1, double y1)} +\cfunction{int}{mp_set_knot_right_control}{(MP mp, mp_knot p, double x1, double y1)} + +Sets explicit left or right control for a knot. \type{x1} and \type{y1} values should be +within the proper range for the current numerical mode. +return 1 on success, 0 on failure. + +\cfunction{int}{mp_set_knotpair_controls}{(MP mp,mp_knot p,mp_knot q,double x1,double y1,double x2,double y2)} + +Sets explicit controls for a knot pair. All four \type{x} and \type{y} values should be +within the proper range for the current numerical mode. +return 1 on success, 0 on failure. + +\cfunction{int}{mp_solve_path}{(MP mp,mp_knot first)} + +Finds explicit controls for the knot list at \type{first}, which +is changed in-situ. Returns 0 if there was any kind of error, in which +case \type{first} is unmodified. There can be quite a set of potential errors, +mostly harmless processing errors. +However, be aware that it is also possible that there are internal mplib +memory allocation errors. A distinction between those can not be made +at the moment. +Return 1 on success, 0 on failure. + +\cfunction{void}{mp_free_path}{(MP mp,mp_knot p)} + +Frees the memory of a path. + +\subsection{Example usage} + +Since the above function list is quite dry and not that easy to grasp, +here are two examples of how to use it. First a simple example +(\type{mp_dump_path()} code is given below). + + +\starttyping +#include +#include +#include +#include "mplib.h" + +int main (int argc, char ** argv) { + MP mp ; + mp_knot p, first, q; + MP_options * opt = mp_options () ; + opt -> command_line = NULL; + opt -> noninteractive = 1 ; + mp = mp_initialize ( opt ) ; + if ( ! mp ) exit ( EXIT_FAILURE ) ; + + /* Equivalent Metapost code: + + path p; + p := (0,0)..(10,10)..(10,-5)..cycle; + + */ + first = p = mp_append_knot(mp,NULL,0,0); + if ( ! p ) exit ( EXIT_FAILURE ) ; + q = mp_append_knot(mp,p,10,10); + if ( ! q ) exit ( EXIT_FAILURE ) ; + p = mp_append_knot(mp,q,10,-5); + if ( ! p ) exit ( EXIT_FAILURE ) ; + mp_close_path_cycle(mp, p, first); + /* mp_dump_path(mp, first); */ + if (mp_solve_path(mp, first)) { + /* mp_dump_path(mp, first); */ + } + mp_free_path(mp, first); + mp_finish ( mp ) ; + free(opt); + return 0; +} +\stoptyping + +For some more challenging path input, here is a more elaborate +example of the path processing code: + +\starttyping + /* Equivalent Metapost code: + + path p; + p := (0,0).. + (2,20)-- + (10, 5)..controls (2,2) and (9,4.5).. + (3,10)..tension 3 and atleast 4 .. + (1,14){2,0} .. {0,1}(5,-4); + */ + first = p = mp_append_knot(mp,NULL,0,0); + q = mp_append_knot(mp,p,2,20); + p = mp_append_knot(mp,q,10,5); + if (!mp_set_knotpair_curls(mp, q,p, 1.0, 1.0)) + exit ( EXIT_FAILURE ) ; + q = mp_append_knot(mp,p,3,10); + if (!mp_set_knotpair_controls(mp, p,q, 2.0, 2.0, 9.0, 4.5)) + exit ( EXIT_FAILURE ) ; + p = mp_append_knot(mp,q,1,14); + if (!mp_set_knotpair_tensions(mp,q,p, 3.0, -4.0)) + exit ( EXIT_FAILURE ) ; + q = mp_append_knot(mp,p,5,-4); + if (!mp_set_knotpair_directions(mp, p,q, 2.0, 0.0, 0.0, 1.0)) + exit ( EXIT_FAILURE ) ; + + mp_close_path(mp, q, first); + + /* mp_dump_path(mp, first); */ + if (mp_solve_path(mp, first)) { + /* mp_dump_path(mp, first); */ + } + mp_free_path(mp, first); +\stoptyping + +And here is the source code for the \type{mp_dump_path} function, +which produces path output that is similar to Metapost's +\type{tracingchoices} report. + +\starttyping +#include +#include +#include +#include +#include "mplib.h" + +#define ROUNDED_ZERO(v) (fabs((v))<0.00001 ? 0 : (v)) +#define PI 3.1415926535897932384626433832795028841971 +#define RADIANS(a) (mp_number_as_double(mp,(a)) / 16.0) * PI/180.0 + +void mp_dump_path (MP mp, mp_knot h) { + mp_knot p, q; + if (h == NULL) return; + p = h; + do { + q=mp_knot_next(mp,p); + if ( (p==NULL)||(q==NULL) ) { + printf("\n???"); + return; /* this won't happen */ + } + printf ("(%g,%g)", mp_number_as_double(mp,mp_knot_x_coord(mp,p)), + mp_number_as_double(mp,mp_knot_y_coord(mp,p))); + switch (mp_knot_right_type(mp,p)) { + case mp_endpoint: + if ( mp_knot_left_type(mp,p)==mp_open ) printf("{open?}"); + if ( (mp_knot_left_type(mp,q)!=mp_endpoint)||(q!=h) ) + q=NULL; /* force an error */ + goto DONE; + break; + case mp_explicit: + printf ("..controls (%g,%g)", + mp_number_as_double(mp,mp_knot_right_x(mp,p)), + mp_number_as_double(mp,mp_knot_right_y(mp,p))); + printf(" and "); + if ( mp_knot_left_type(mp,q)!=mp_explicit ) { + printf("??"); + } else { + printf ("(%g,%g)",mp_number_as_double(mp,mp_knot_left_x(mp,q)), + mp_number_as_double(mp,mp_knot_left_y(mp,q))); + } + goto DONE; + break; + case mp_open: + if ( (mp_knot_left_type(mp,p)!=mp_explicit) + && + (mp_knot_left_type(mp,p)!=mp_open) ) { + printf("{open?}"); + } + break; + case mp_curl: + case mp_given: + if ( mp_knot_left_type(mp,p)==mp_open ) + printf("??"); + if ( mp_knot_right_type(mp,p)==mp_curl ) { + printf("{curl %g}", mp_number_as_double(mp,mp_knot_right_curl(mp,p))); + } else { + double rad = RADIANS(mp_knot_right_curl(mp,p)); + double n_cos = ROUNDED_ZERO(cos(rad)*4096); + double n_sin = ROUNDED_ZERO(sin(rad)*4096); + printf("{%g,%g}", n_cos, n_sin); + } + break; + } + if ( mp_knot_left_type(mp,q)<=mp_explicit ) { + printf("..control?"); /* can't happen */ + } else if ((mp_number_as_double(mp,mp_knot_right_tension(mp,p))!=(1.0))|| + (mp_number_as_double(mp,mp_knot_left_tension(mp,q)) !=(1.0))) { + printf("..tension "); + if ( mp_number_as_double(mp,mp_knot_right_tension(mp,p))<0.0 ) + printf("atleast "); + printf("%g", fabs(mp_number_as_double(mp,mp_knot_right_tension(mp,p)))); + if (mp_number_as_double(mp,mp_knot_right_tension(mp,p)) != + mp_number_as_double(mp,mp_knot_left_tension(mp,q))) { + printf(" and "); + if (mp_number_as_double(mp,mp_knot_left_tension(mp,q))< 0.0) + printf("atleast "); + printf("%g", fabs(mp_number_as_double(mp,mp_knot_left_tension(mp,q)))); + } + } + DONE: + p=q; + if ( p!=h || mp_knot_left_type(mp,h)!=mp_endpoint) { + printf ("\n .."); + if ( mp_knot_left_type(mp,p) == mp_given ) { + double rad = RADIANS(mp_knot_left_curl(mp,p)); + double n_cos = ROUNDED_ZERO(cos(rad)*4096); + double n_sin = ROUNDED_ZERO(sin(rad)*4096); + printf("{%g,%g}", n_cos, n_sin); + } else if ( mp_knot_left_type(mp,p) ==mp_curl ){ + printf("{curl %g}", mp_number_as_double(mp,mp_knot_left_curl(mp,p))); + } + } + } while (p!=h); + if ( mp_knot_left_type(mp,h)!=mp_endpoint ) + printf("cycle"); + printf (";\n"); +} +\stoptyping + +The above function is much complicated because of all the knot type +cases that can only happen {\it before} \type{mp_solve_path()} is +called. A version that only prints processed paths and is less +scared of using direct field access would be much shorter: + +\starttyping +void mp_dump_solved_path (MP mp, mp_knot h) { + mp_knot p, q; + if (h == NULL) return; + p = h; + do { + q=mp_knot_next(mp,p); + printf ("(%g,%g)..controls (%g,%g) and (%g,%g)", + mp_number_as_double(mp,p->x_coord), + mp_number_as_double(mp,p->y_coord), + mp_number_as_double(mp,p->right_x), + mp_number_as_double(mp,p->right_y), + mp_number_as_double(mp,q->left_x), + mp_number_as_double(mp,q->left_y)); + p=q; + if ( p!=h || h->data.types.left_type!=mp_endpoint) { + printf ("\n .."); + } + } while (p!=h); + if ( h->data.types.left_type!=mp_endpoint ) + printf("cycle"); + printf (";\n"); +} +\stoptyping + +\page +\section{C API for graphical backend functions} +\bookmark{C API for graphical backend functions} + +These are all defined in \type{mplibps.h} + +\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_gr_knot}{} + +These are like \type{mp_knot}, except that all \type{mp_number} values +have been simplified to \type{double}. + +\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 double \NC a_val \NC see below\NC \NR +\NC double \NC b_val \NC --\NC \NR +\NC double \NC c_val \NC --\NC \NR +\NC double \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 double * \NC array \NC an array of dash lengths, terminated by $-1$.\NC \NR +\NC double \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 fields, 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_gr_knot \NC path_p \NC the (always cyclic) path\NC \NR +\NC mp_gr_knot \NC htap_p \NC a possible reversed path (see below)\NC \NR +\NC mp_gr_knot \NC pen_p \NC a possible pen (see below)\NC \NR +\NC double \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: \type{path_p} and \type{htap_p} already incorporate +its shape. +\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_gr_knot \NC path_p \NC the path \NC \NR +\NC mp_gr_knot \NC pen_p \NC the pen \NC \NR +\NC double \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 double \NC font_dsize \NC size of the font\NC \NR +\NC double \NC width \NC width of the picture resulting from the string\NC \NR +\NC double \NC height \NC height\NC \NR +\NC double \NC depth \NC depth\NC \NR +\NC double \NC tx \NC transformation component\NC \NR +\NC double \NC ty \NC transformation component\NC \NR +\NC double \NC txx \NC transformation component\NC \NR +\NC double \NC tyx \NC transformation component\NC \NR +\NC double \NC txy \NC transformation component\NC \NR +\NC double \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_gr_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_gr_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 double \NC minx \NC lower-left $x$ of the bounding box\NC \NR +\NC double \NC miny \NC lower-left $y$ of the bounding box\NC \NR +\NC double \NC maxx \NC upper right $x$ of the bounding box\NC \NR +\NC double \NC maxy \NC upper right $y$ of the bounding box\NC \NR +\NC double \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 double \NC height \NC similar for height (\type{charht})\NC \NR +\NC double \NC depth \NC similar for depth (\type{chardp})\NC \NR +\NC double \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{ship_out} field. + +Returns zero for success. + +\cfunction{int }{mp_svg_ship_out}{(mp_edge_object*hh,int prologues)} + +If you have an \type{mp_edge_object}, you can call this function. It will +generate the \SVG\ output for the figure and save it internally. A subsequent call to +\type{mp_rundata} will find the generated text in the \type{ship_out} field. + +Returns zero for success. + + +\cfunction{int }{mp_png_ship_out}{(mp_edge_object*hh, char *options)} + +If you have an \type{mp_edge_object}, you can call this function. It will +generate the \PNG\ bitmap for the figure and save it internally. A subsequent call to +\type{mp_rundata} will find the generated data in the \type{ship_out} field. + +Note: the \type{options} structure follows the same syntax as in the Metapost language, +and can be NULL. + +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 + s = mplib.version() +\stoptyping + +\subsection{\luatex{mplib.new}} + +To create a new metapost instance, call + +\starttyping + mp = mplib.new({...}) +\stoptyping + +This creates the \type{mp} instance object. The \type{mp} instance object +always starts out in so|-|called \quote{inimp} mode, there is no +support for preload files. + +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 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 job_name \NC string \NC \type {--jobname} \NC \type {mpout} \NC\NR +\NC math_mode \NC string \NC the number system mode, one of \type{scaled} or + \type{double} \NC \type {scaled} \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 + found = finder ( name, mode, 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 {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 + stats = mp:statistics() +\stoptyping + +This function returns the allocation statistics for an \MPLIB\ +instance. There are four fields, giving the maximum number of used +items in each of four object classes: + +\starttabulate[|lT|l|p|] +\NC memory \NC number \NC allocated memory (in bytes)\NC\NR +\NC hash \NC number \NC hash size (in entries)\NC\NR +\NC params \NC number \NC simultaneous macro parameters\NC\NR +\NC 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 png \NC function \NC return a string that is the png 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 + w = mp.char_width( fontname, char) +\stoptyping + +\subsubsection{\luatex{mp.char_height}} + +\starttyping + w = mp.char_height( fontname, char) +\stoptyping + +\subsubsection{\luatex{mp.char_depth}} + +\starttyping + w = mp.char_depth( fontname, char) +\stoptyping + +\subsection{Solving path control points} + +\starttyping + success = mp.solve_path(
knots, cyclic) +\stoptyping + +This modifies the \type{knots} table (which should contain an +array of points in a path, with the substructure explained below) +by filling in the control points. The boolean \type{cyclic} is +used to determine whether the path should be the equivalent of +\type{--cycle}. If the return value is \type{false}, there +is an extra return argument containing the error string. + +On entry, the individual knot tables can contain the values +mentioned above (but typically the \type{left_{x,y}} and +\type{right_{x,y}} will be missing). \type{{x,y}_coord} are +both required. Also, some extra values are allowed: +\starttabulate[|lT|l|p|] +\NC left_tension \NC number \NC A tension specifier \NC \NR +\NC right_tension \NC number \NC like \type{left_tension}\NC \NR +\NC left_curl \NC number \NC A curl specifier\NC \NR +\NC right_curl \NC number \NC like \type{left_curl}\NC \NR +\NC direction_x \NC number \NC $x$ displacement of a direction specifier\NC \NR +\NC direction_y \NC number \NC $y$ displacement of a direction specifier\NC \NR +\stoptabulate + +Note the following: +\startitemize +\item A knot has either a direction specifier, or a curl specifier, or a tension specification, + or explicit control points, with the note that tensions, curls and control points are split + in a left and a right side (directions apply to both sides equally). +\item The absolute value of a tension specifier should be more than 0.75 and less than 4096.0, + with negative values indicating \quote{\type{atleast}}. +\item The absolute value of a direction or curl should be less than 4096.0. +\item If a tension, curl, or direction is specified, then existing control points will be + replaced by the newly computed value. +\item Calling \type{solve_path} does not alter the used mplib instance. +\stopitemize + +\stoptext + + + + + + diff --git a/systems/doc/metapost/source-manual/mpman-app-legacy.tex b/systems/doc/metapost/source-manual/mpman-app-legacy.tex new file mode 100644 index 0000000000..597ce8a5b1 --- /dev/null +++ b/systems/doc/metapost/source-manual/mpman-app-legacy.tex @@ -0,0 +1,347 @@ +\svnInfo $Id: mpman-app-legacy.tex 2023 2014-05-21 08:47:19Z stephanhennig $ +\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\\ +numberprecision\\ +numbersystem\\ +outputfilename\\ +outputformat\\ +outputformatoptions\\ +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 smoothing turningcheck +chardx granularity tracingedges xoffset +chardy proofing tracingpens yoffset +\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/systems/doc/metapost/source-manual/mpman-app-numbersystems.tex b/systems/doc/metapost/source-manual/mpman-app-numbersystems.tex new file mode 100644 index 0000000000..23d3dce7cf --- /dev/null +++ b/systems/doc/metapost/source-manual/mpman-app-numbersystems.tex @@ -0,0 +1,98 @@ +\svnInfo $Id: mpman-app-numbersystems.tex 2023 2014-05-21 08:47:19Z stephanhennig $ +\section{High-precision arithmetic with MetaPost} +\label{hparith} + +In addition to the fixed-point arithmetics inherited from \MF, MetaPost +can also do higher-precision arithmetics. In total, MetaPost can handle +numeric quantities in four internal representation formats or number +systems. Number systems differ in rounding errors\index{rounding error} +introduced by and the speed of arithmetic operations. Simply storing a +numeric value in a variable may already introduce a rounding error, so +that can already be considered an arithmetic operation. + +The internal representation format used for numeric quantities can be +determined by a command-line switch +\texttt{-numbersystem}\index{command-line!mpost?\texttt{mpost}!-numbersystem?\texttt{-numbersystem}} +when invoking the MetaPost executable. Argument is a string and can be +one of \texttt{scaled}, \texttt{double}, \texttt{binary}, or +\texttt{decimal}. The argument is stored in an internal string variable +\texttt{numbersystem}\index{numbersystem?\texttt{numbersystem}}\label{Dnumbersystem}. +Assigning a value to this variable at run-time triggers an error. + +The \texttt{scaled}\index{scaled?\texttt{scaled}} number system refers +to 32~bit fixed-point arithmetics described in Section~\ref{datatypes}. +This is the default number system. Precision is ca. 10~decimal digits, +5 digits before and after the comma. All arithmetic operations are done +in software. + +The \texttt{double}\index{double?\texttt{double}} number system does +IEEE standard floating-point arithmetics with 64~bits (or double) +precision. In the internal representation, double floating-point +numbers use $52+1$~bits for the mantissa, which determines precision, +11~bits for the exponent, which determines the valid range of numbers, +and one bit for the sign. The smallest absolute value that can be +represented is ca. $2.2\cdot10^{-308}$, the largest value is +ca. $1.8\cdot10^{308}$. The 53~bit mantissa makes for a precision of +ca. 15 decimal digits. The smallest possible difference between two +distinct numbers in double floating-point number representation is +$2^{-53} \approx 1.1\cdot10^{-16}$. The largest integer value that can +be represented exactly is $2^{53}-1 \approx 9,0\cdot10^{15}$. Variable +\texttt{warningcheck}\index{warningcheck?\texttt{warningcheck}} is set +to $2^{52}$ in \texttt{double} mode. Arithmetic operations make use of +a hardware floating-point unit (FPU), if available. + +While the IEEE double precision floating-point format provides plenty +room for storing numeric values, still, precision and range are finite +and fix. For users that need higher precision or range, MetaPost +provides support for (almost) arbitrary precision floating-point +arithmetics. The \texttt{binary}\index{binary?\texttt{binary}} number +system is similar to the \texttt{double} number system, except that the +number of bits used for the mantissa is not fixed, but variable. +Precision is determined by an internal variable +\texttt{numberprecision}\index{numberprecision?\texttt{numberprecision}}\label{Dnumberprecision} +in decimal digits. Valid numbers are in the range 1 to 1000. Higher +values make for better precision at the expense of performance of +arithmetic operations. Default precision is 34~decimal digits +(ca. 113~bits in the mantissa). Exponent in the internal representation +is an integer in the range $[-9,999,999; +9,999,999]$. All arithmetic +operations are done in software using the MPFR library~\cite{lib:mpfr} +and are usually orders of magnitude slower than in \texttt{double} mode. + +Number system \texttt{decimal}\index{decimal?\texttt{decimal}} provides +arbitrary precision floating-point arithmetics similar to the +\texttt{binary} number system. Except that it uses a base of~10 for the +internal representation instead of a base of~2. The point is that with +base~2 floating-point numbers some decimal numbers cannot be represented +exactly, among them such strange numbers like $0.1$. In a base~2 +floating-point number format, this value has an infinit repeating +representation, which cannot be stored in a mantissa of finite precision +without introducing a rounding error. While such initial errors may be +small, they use to accummulate when doing calculations. Sometimes +increasing precision by switching from \texttt{double} to +\texttt{binary} mode is sufficient to get satisfying results again. On +the other hand, there's a demand for doing calculations exactly like +humans do with pencil and paper, e.g., for certain financial +calculations. The only way to ensure exact result is switching base of +the internal representation to~10. Again, precision can be determined +by assigning a value to variable +\texttt{numberprecision}\index{numberprecision?\texttt{numberprecision}}. +Valid numbers are in the range 1 to 1000. Default precision is +34~decimal digits. Exponent in the internal representation is an +integer in the range $[-9,999,999; +9,999,999]$. All arithmetic +operations are done in software using the decNumber +library~\cite{lib:decnumber} and are usually slower than in +\texttt{binary} mode. + +In all number systems except the traditional fixed-point +(\texttt{scaled}) number system, numbers can be given in scientific +notation, i.e., input like \texttt{1.23e4} is interpreted as the value +$12,300$ instead of the product of the numeric value $1.23$ and (array) +variable \verb|e[4]|. + + + +%%% Local Variables: +%%% mode: latex +%%% TeX-PDF-mode: t +%%% TeX-master: "mpman" +%%% End: diff --git a/systems/doc/metapost/source-manual/mpman-app-optab.tex b/systems/doc/metapost/source-manual/mpman-app-optab.tex new file mode 100644 index 0000000000..dd779479d4 --- /dev/null +++ b/systems/doc/metapost/source-manual/mpman-app-optab.tex @@ -0,0 +1,156 @@ +\svnInfo $Id: mpman-app-optab.tex 1438 2010-10-26 20:08:17Z stephanhennig $ +%%% 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{\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 of?\texttt{postcontrol of}}& numeric& path& pair& \pageref{Dprepostctrl}& First B\'ezier control point on path segment starting at the given time\\\hline +precontrol of\index{precontrol of?\texttt{precontrol of}}& numeric& path& pair& \pageref{Dprepostctrl}& 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/systems/doc/metapost/source-manual/mpman-app-refman.tex b/systems/doc/metapost/source-manual/mpman-app-refman.tex new file mode 100644 index 0000000000..7d301c3ce0 --- /dev/null +++ b/systems/doc/metapost/source-manual/mpman-app-refman.tex @@ -0,0 +1,1068 @@ +\svnInfo $Id: mpman-app-refman.tex 2022 2014-05-20 21:50:47Z stephanhennig $ +\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& \pageref{Dday}& + 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 +\pl\tt dotlabeldiam& \pageref{Ddotlabdiam}& + Diameter of the dot drawn by \verb|dotlabel| (default 3{\tt bp})\\\hline +\tt hour& \pageref{Dhour}& + The hour of the day this job started\\\hline +\tt hppp& \pageref{Dhppp}& + The number of horizontal points per pixel for bitmap output\\\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& \pageref{Dminute}& + The minute of the hour this job started\\\hline +\tt miterlimit& \pageref{Dmiterlim}& + Controls miter length as in PostScript\\\hline +\tt month& \pageref{Dmonth}& + The current month (e.g, 3 $\equiv$ March)\\\hline +\tt mpprocset& \pageref{Dmpprocset}& + Create a PostScript dictionary of command abbreviations\\\hline +\tt numberprecision&\pageref{Dnumberprecision}& + Arithmetic precision in \texttt{binary} and \texttt{decimal} mode\\\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& \pageref{Dtime}& + 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 vppp& \pageref{Dvppp}& + The number of vertical points per pixel for bitmap output\\\hline +\tt warningcheck& \pageref{Dwarncheck}& + Controls error message when variable value is large\\\hline +\tt year& \pageref{Dyear}& + The current year (e.g., 1992)\\\hline +\end{tabular} +$$ +\label{ivartab}% +\index{pausing?\texttt{pausing}}\index{showstopping?\texttt{showstopping}}% +\index{tracingtitles?\texttt{tracingtitles}} +\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 numbersystem& \pageref{Dnumbersystem}& + Arithmetic mode as given on the command-line\\\hline +\tt outputfilename& \pageref{Doutputfilename}& + Name of the output file last written\\\hline +\tt outputformat& \pageref{Doutputformat}& + Output backend to be used (default: ``eps'')\\\hline +\tt outputformatoptions& \pageref{Doutputformatoptions}& + Configure PNG output backend (default: ``'')\\\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& \pageref{Dcc}& + 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& \pageref{Ddd}& + 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& \pageref{Depsilon}& + 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& \pageref{Dorigin}& + The pair $(0,0)$\\\hline +\pl\tt pc& numeric& \pageref{Dpc}& + 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& \pageref{Dqcirc}& + 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& \pageref{Dunitsqr}& + 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{ditto?\texttt{ditto}}% +\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 \;|\; hppp \;|\; jobname \;|\; labeloffset \;|\; linecap \;|\; linejoin +\;|\; minute \;|\; miterlimit \;|\; month$\\ +$\tt \qquad \;|\; numberprecision \;|\; numbersystem$\\ +$\tt \qquad \;|\; outputfilename \;|\; outputformat \;|\; outputformatoptions \;|\; outputtemplate$\\ +$\tt \qquad \;|\; 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 \;|\; vppp \;|\; 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} + +\begingroup +\renewcommand*{\arraystretch}{1.25}% Give command-line switch tables air. + +\subsubsection{The MetaPost Program} +\label{refman:mpost} + +\newcommand*{\opt}[1]{\ensuremath{\big[}#1\ensuremath{\big]}} +\newcommand*{\cmdsw}{\tdescr{switches}} +\newcommand*{\cmdmem}{\tdescr{preloadfile}} +\newcommand*{\cmdin}{\tdescr{infile}} +\newcommand*{\cmdcode}{\tdescr{commands}} +\newcommand*{\cmdindex}[1]{\index{command-line!mpost?\texttt{mpost}!#1?\texttt{#1}}\texttt{#1}} + +The MetaPost program processes commands in the MetaPost language, either +read from a file or typed-in interactively, and compiles them into +PostScript or SVG graphics. The run-time behavior of the executable can +be controlled by command-line parameters, environment variables, and +configuration files. The MetaPost executable is named +mpost\label{Dmpost}\index{mpost} (or occasionally just mp). The +command-line syntax of the executable is +$$ +\begin{verbatim}[commandchars=\\\{\}] +mpost \opt{\cmdsw} \opt{\&\cmdmem} \opt{\cmdin} \opt{\cmdcode} +\end{verbatim} +\index{mpost?\texttt{mpost}}\index{command-line!mpost?\texttt{mpost}} +$$ +Any of the parameters is optional. If no argument is given to the +\verb|mpost| command, MetaPost enters interactive mode\index{interactive + mode}, indicated by a \verb|**| prompt\index{**?\texttt{**}!prompt}, +waiting for a file name to be typed-in by keyboard. The file is then +read-in and processed as if it were given as parameter \cmdin\ on the +command-line. + +\begin{description} +\item[\cmdin] A MetaPost input file is a text file containing statements + in the MetaPost language. Typically, input files have file extension + \texttt{mp}\index{mp file?{\tt mp} file}\index{files!mp?{\tt mp}}, + e.g., \texttt{fig.mp}. Here is how MetaPost searches for input files. + If \cmdin\ doesn't end with \texttt{.mp}\index{mp file?{\tt mp} + file}\index{files!mp?{\tt mp}}, MetaPost first looks for a file + \texttt{\cmdin.mp}. Only if that file doesn't exist, it looks for + file \cmdin\ literally. That way, the \texttt{mp}\index{mp file?{\tt + mp} file}\index{files!mp?{\tt mp}} file extension can be omitted + when calling MetaPost. If \cmdin\ already ends with + \texttt{.mp}\index{mp file?{\tt mp} file}\index{files!mp?{\tt mp}}, no + special file name handling takes place and MetaPost looks for that + file only. + + As an example, if there are two files \texttt{fig} and \texttt{fig.mp} + in the current directory and MetaPost is invoked with + \verb|'mpost fig'|, the file that gets processed is \texttt{fig.mp}. + To process file \texttt{fig} in this situation, MetaPost can be called + as \verb|'mpost fig.'|. Note, the trailing dot is only needed as long + as there exists a file \texttt{fig.mp} alongside file \texttt{fig}. + + If MetaPost cannot find any input file by the rules specified above, + it complaints with an error message and interactively asks for a new + input file name. + +\item[\cmdcode] All text on the command-line after \cmdin\ is + interpreted as MetaPost code and is processed after \cmdin\ is read. + If \cmdin\ already contains an \verb|end| statement, \cmdcode\ gets + effectively ignored. If MetaPost doesn't encounter an \verb|end| + statement neither in \cmdin\ nor in \cmdcode, it enters interactive + mode after processing all input. + +\item[\texttt{\&\cmdmem}] The MetaPost program code in the \cmdmem\ + MetaPost source file (and any other files that it inputs) is executed + before all other processing starts. The \cmdmem\ file should end with + an \texttt{end}\index{end?\texttt{end}} or + \texttt{dump}\index{dump?\texttt{dump}} command. + + If neither \texttt{\&\cmdmem} nor \cmdindex{-mem} is specified on the + command line, MetaPost will default to loading the macro file + \texttt{mpost.mp}\index{mpost.mp?\texttt{mpost.mp}}, or to whatever + the actual name of the MetaPost executable is. The \cmdindex{-ini} + switch can be used to suppress this behavior. + +\item[\cmdsw] MetaPost provides a number of command-line switches that + control the run-time behavior. Switches can be prefixed by one or two + dashes. Both forms have the same meaning. An exemplary call to + MetaPost that compiles a file \texttt{fig.mp}, using \LaTeX\ to + typeset \verb|btex|\slash\verb|etex| labels, would look like: +$$ +\begin{verbatim} +mpost -tex=latex fig +\end{verbatim} +\index{mpost?\texttt{mpost}} +$$ + +Here's a summary of the command-line switches provided by mpost: + +\setlength{\LTleft}{\leftmargin} +\begin{longtable}{>{\ttfamily}p{.35\linewidth}>{\raggedright\arraybackslash}p{.6\linewidth}} + \cmdindex{-debug} + & Don't delete intermediate files.\\ + \cmdindex{-dvitomp} + & Act as the \texttt{dvitomp} executable (see below).\\ + \cmdindex{-file-line-error} + & Start error messages with \verb|`filename:lineno:'| instead of + \verb|`!'|.\\ + \cmdindex{-halt-on-error} + & Immediately exit after the first error occurred.\\ + \cmdindex{-help} + & Show help on command-line switches.\\ + \cmdindex{-ini} + & Do not load any preload file.\\ + \cmdindex{-interaction}=\tdescr{string} + & Set interaction mode to one of \texttt{batchmode}, + \texttt{nonstopmode}, \texttt{scrollmode}, \texttt{errorstopmode}.\\ + \cmdindex{-jobname}=\tdescr{jobname} + & Set the name of the job (affects output file names).\\ + \cmdindex{-kpathsea-debug}=\tdescr{number} + & Set debugging flags for path searching.\\ + \cmdindex{-mem}=\tdescr{string} + & Use \tdescr{string} for the name of the file that contains macros to be preloaded + (same as \texttt{\&\cmdmem})\\ + \cmdindex{-no-file-line-error} + & Enable normal MetaPost and \TeX\ style error messages.\\ + \cmdindex{-no-kpathsea} + & Do not use the kpathsea program to find files. All files have to be + in the current directory or specified via a full path.\\ + \cmdindex{-numbersystem}=\tdescr{string} + & Set arithmetic mode to one of \texttt{scaled}, \texttt{double}, + \texttt{binary}, \texttt{decimal}\\ + \cmdindex{-progname}=\tdescr{string} + & Pretend to be the \tdescr{string} executable.\\ + \cmdindex{-recorder} + & Write a list of all opened disk files to + \texttt{\tdescr{jobname}.fls}\index{fls file?{\tt fls} + file}\index{files!fls?{\tt fls}}. (This functionality is provided + by kpathsea.)\\ + \cmdindex{-s} \tdescr{key}=\tdescr{value} + & Set internal variable \tdescr{key} to \tdescr{value}. This switch + can be given multiple times on the command-line. The assignments are + applied just before the input file is read-in. \tdescr{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. To avoid double quotes being already stripped by the shell, + the whole assignment can be enclosed in another pair of single quotes. + Example: \verb|-s 'outputformat="svg"' -s prologues=3|\newline + Use SVG backend converting font shapes to paths.\\ + \cmdindex{-tex}=\tdescr{texprogram} + & Load format \tdescr{texprogram} for rendering \TeX\ material.\\ + \cmdindex{-troff}, \cmdindex{-T} + & Output troff compatible PostScript files.\\ + \cmdindex{-version} + & Print version information and exit.\\ +\end{longtable} + +The following command-line switches are silently ignored in +\emph{mplib}-based MetaPost (v1.100 or later), because they are always +`on': + +\begin{longtable}{>{\ttfamily}p{.35\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{.35\linewidth}>{\raggedright\arraybackslash}p{.6\linewidth}} + \cmdindex{-no-parse-first-line} + & \\ + \cmdindex{-output-directory}=\tdescr{string} + & \\ + \cmdindex{-translate-file}=\tdescr{string} + & \\ +\end{longtable} + +\end{description} + +\subsubsection{The dvitomp Program} +\label{refman:dvitomp} + +\renewcommand*{\cmdindex}[1]{\index{command-line!dvitomp?\texttt{dvitomp}!#1?\texttt{#1}}\texttt{#1}} +\renewcommand*{\cmdin}{\tdescr{infile}} +\newcommand*{\cmdout}{\tdescr{outfile}} + +The dvitomp\label{Ddvitomp}\index{dvitomp} program converts +DVI\index{dvi file?{\tt dvi} file}\index{files!dvi?{\tt dvi}} files into +low-level MetaPost code. MetaPost uses the dvitomp program when +typesetting \verb|btex|\slash\verb|etex| labels by \TeX\ for the final +conversion back into MetaPost code. The command-line syntax of the +executable is +$$ +\begin{verbatim}[commandchars=\\\{\}] +dvitomp \opt{\cmdsw} \cmdin \opt{\cmdout} +\end{verbatim} +\index{dvitomp?\texttt{dvitomp}}\index{command-line!dvitomp?\texttt{dvitomp}} +$$ +Parameters \cmdsw\ and \cmdout\ are optional. + +\begin{description} +\item[\cmdin] This is the name of the DVI file to convert. If the name + doesn't end with \texttt{.dvi}\index{dvi file?{\tt dvi} + file}\index{files!dvi?{\tt dvi}}, that extension is appended. Note, + dvitomp never opens files not ending \texttt{.dvi}. This file is in + general automatically generated by \TeX\ or troff, driven by MetaPost. + +\item[\cmdout] This is the name of the output file containing the + MetaPost code equivalent to \cmdin. If \cmdout\ is not given, + \cmdout\ is \cmdin\ with the extension \texttt{.dvi} replaced by + \texttt{.mpx}\index{mpx file?{\tt mpx} file}\index{files!mpx?{\tt + mpx}}. If \cmdout\ is given and doesn't end with + \texttt{.mpx}\index{mpx file?{\tt mpx} file}\index{files!mpx?{\tt + mpx}}, that extension is appended. + +\item[\cmdsw] Command-line switches can be prefixed by one or two + dashes. Both forms have the same meaning. The following command-line + switches are provided by dvitomp: + +\setlength{\LTleft}{\leftmargin} +\begin{longtable}{>{\ttfamily}p{.35\linewidth}>{\raggedright\arraybackslash}p{.6\linewidth}} + \cmdindex{-help} + & Show help on command-line switches.\\ + \cmdindex{-kpathsea-debug}=\tdescr{number} + & Set debugging flags for path searching.\\ + \cmdindex{-progname}=\tdescr{string} + & Pretend to be the \tdescr{string} executable.\\ + \cmdindex{-version} + & Print version information and exit.\\ +\end{longtable} + +\end{description} + +The dvitomp program used to be part of a set of external tools, called +\emph{mpware}\index{mpware tools}\footnote{makempx, mpto, dvitomp, and + dmp.}, which were used by MetaPost for processing +\verb|btex|\slash\verb|etex| labels. Since MetaPost version~1.100, the +label conversion is handled internally by the mpost\index{mpost} +program. The \emph{mpware} tools are therefore obsolete and no longer +part of the MetaPost distribution. Nowadays, dvitomp is either a copy +of the mpost executable with the name dvitomp or a wrapper, calling +mpost\index{mpost} as +$$ +\begin{verbatim}[commandchars=\\\{\}] +mpost -dvitomp \cmdin \cmdout +\end{verbatim} +\index{mpost?\texttt{mpost}} +$$ + +\endgroup + +%%% Local Variables: +%%% mode: latex +%%% TeX-PDF-mode: t +%%% TeX-master: "mpman" +%%% End: diff --git a/systems/doc/metapost/source-manual/mpman-charts.mp b/systems/doc/metapost/source-manual/mpman-charts.mp new file mode 100644 index 0000000000..6dc550965a --- /dev/null +++ b/systems/doc/metapost/source-manual/mpman-charts.mp @@ -0,0 +1,210 @@ +verbatimtex + \def\appl#1{\applfontx#1\strut} + \def\ext#1{\extfontx#1\strut} + \font\applfontx=ec-lmri10 + \font\extfontx=ec-lmtt10 + \font\extfontvii=ec-lmtt8 at 7pt +etex + +% Use the boxes package for drawing charts. +input boxes +input charts +%prologues:=3; + +if scantokens(mpversion) < 1.200: + filenametemplate +else: + outputtemplate := +fi +"%j-%c.mps"; + + +beginfig(1); + interim applwidth := 72bp; + interim applheight := 28bp; + interim extwidth := 48bp; + interim extheight := 28bp; + interim rowscale := 56bp; + interim colscale := 100bp; + interim ahangle := 30; + +% Build and draw boxes. + ext_rc(fig.mp, (0,0), btex \ext{fig.mp} etex); + appl_rc(mpost, (1,0), btex \appl{MetaPost} etex); + ext_rc(fig.1, (2,0), btex \ext{fig.1} etex); + ext_rc(doc.tex, (0,2), btex \ext{doc.tex} etex); + appl_rc(tex, (1,2), btex \appl{\TeX} etex); + ext_rc(doc.dvi, (2,2), btex \ext{doc.dvi} etex); + appl_rc(dvips, (3,1), btex \appl{dvips} etex); + ext_rc(doc.ps, (4,1), btex \ext{doc.ps} etex); + +% Draw connections. + line(fig.mp, mpost); + line(mpost, fig.1); + line(doc.tex, tex); + line(tex, doc.dvi); + curve(fig.1, dvips, -90, 0); + curve(doc.dvi, dvips, -90, 180); + line(dvips, doc.ps); + +% Draw bounding box link. + boxit.bb(btex + \vbox{ + \hbox to 50bp {\hfil\strut bounding\hfil} + \hbox to 50bp {\hfil\strut box\hfil} + } + etex scaled .8); + path p; + p := fig.1.e{right}..{right}tex.w; + bb.c = point 0.5 of p; + drawunboxed(bb); + draw p cutafter bpath bb dashed evenly; + drawarrow p cutbefore subpath (1,3) of bpath bb dashed evenly; +endfig; + + +verbatimtex + \font\applfontx=ec-lmbxi10 +etex + +beginfig(2); +% Pre-define workflow segment parameters. + wfsegments := 6;% counter + wfsegangle = 360/wfsegments;% angle + wfstart := 90;% angle + wfdiam := 200bp;% dimension + wfthick := 48bp;% dimension + wfgap := 8;% angle + wfinset := 8;% angle + +% Pre-define colors of some graphic elements. + color wf_col, appl_col, ext_col; + wf_col = .9white; + appl_col = (.1, .1, .7); + ext_col = 0white; + +% The size of the user icon. + usersize := 20bp; + +% Construct a workflow segment. +% +% * The anchor point of a workflow segment is at its center. +% +% * Array wfang[] stores the angle on a circle corresponding +% to a vertex of a workflow segment. The mapping of indices +% to vertices is: +% +% 2---------0 +% / / +% 3 1 +% \ \ +% 2---------0 +% +% * For array wfscale[] the mapping is: +% +% 3---------0 +% / / +% < < +% \ \ +% 2---------1 +% + numeric wfang[], wfscale[]; + path wfseg; + wfang0 = .5(-wfsegangle + wfgap - wfinset); + wfang1 = .5(-wfsegangle + wfgap + wfinset); + wfang2 = .5( wfsegangle - wfgap - wfinset); + wfang3 = .5( wfsegangle - wfgap + wfinset); + wfscale[0] = 1 + wfthick/wfdiam; + wfscale[1] = 1 - wfthick/wfdiam; + wfscale[2] = 1 - 1.0*wfthick/wfdiam; + wfscale[3] = 1 + 1.0*wfthick/wfdiam; + wfseg := 0.5dir(wfang0)*wfscale0 {dir(wfang0-180)} + ..{dir(wfang1+135)} 0.5dir(wfang1) {dir(wfang1-135)} + ..{dir(wfang0+180)} 0.5dir(wfang0)*wfscale1 {dir(wfang0+90)} + ..{dir(wfang2+90)} 0.5dir(wfang2)*wfscale2 {dir(wfang2)} + ..{dir(wfang3+45)} 0.5dir(wfang3) {dir(wfang3-45)} + ..{dir(wfang2)} 0.5dir(wfang2)*wfscale3 {dir(wfang2-90)} + ..{dir(wfang0-90)} cycle; + +% Store user icon in picture variable. + picture unituserLeft, unituserRight; + unituserRight := image( +% This clip-art has been taken from the Open Clip-Art Library at +% . The original SVG file by +% 'yyycatch' is licensed as Public Domain and can be found at +% . It has been +% converted to MetaPost by exporting the SVG file to EPS in Inkscape +% and then coordinates, colours and pens have been manually translated +% to the corresponding MetaPost commands. + path p[]; + p1 = + (39.387, 60.034) .. controls (17.117, 59.401) and (-0.352, 22.932) + .. (7.887, 10.565) .. controls (16.125, -1.802) and (64.465, -1.802) + .. (72.34, 10.565) .. controls (80.215, 22.932) and (62.383, 60.686) + .. cycle; + p2 = + (22.809, 52.588) + -- (59.93, 52.588) .. controls (59.93, 52.588) and (60.523, 15.705) + .. (47.293, 15.705) .. controls (34.852, 15.705) and (22.809, 52.588) + .. cycle; + p3 = + (69.125, 67.963) .. controls (69.125, 50.881) and (56.723, 37.037) + .. (41.422, 37.037) .. controls (26.125, 37.037) and (13.723, 50.881) + .. (13.723, 67.963) .. controls (13.723, 85.045) and (26.125, 98.893) + .. (41.422, 98.893) .. controls (56.633, 98.893) and (69, 85.198) + .. cycle; + p4 = + (31.047, 76.764) .. controls (31.047, 76.764) and (43.93, 63.147) + .. (57.152, 64.209) .. controls (70.398, 65.276) and (79.316, 71.444) + .. (79.316, 71.444) .. controls (79.316, 71.444) and (72.488, 108.674) + .. (41.977, 109.291) .. controls (18.086, 109.791) and (6.324, 86.862) + .. (2.84, 71.444) .. controls (-0.691, 55.83) and (4.152, 55.889) + .. (9.313, 57.221) .. controls (14.477, 58.549) and (31.047, 76.764) + .. cycle; + p5 = + (84.211, 30.416) .. controls (87.586, 25.877) and (85.977, 18.955) + .. (80.617, 14.967) .. controls (75.258, 10.979) and (68.164, 11.428) + .. (64.785, 15.971) + -- (64.734, 16.037) .. controls (62.766, 18.741) and (62.41, 30.342) + .. (65.918, 32.764) .. controls (69.781, 35.428) and (80.832, 34.955) + .. cycle; + interim linecap := butt; + interim linejoin := mitered; + fill p1 withcolor (1, 0.501961, 0.501961); + draw p1 withcolor 0.219608 withpen pencircle scaled 2.577288; + fill p2 withcolor 1; + draw p2 withcolor 0.219608 withpen pencircle scaled 2.782928; + fill p3 withcolor (1, 0.8, 0.666667); + draw p3 withcolor 0.219608 withpen pencircle scaled 3.31912; + fill p4 withcolor (0.827451, 0.552941, 0.372549); + draw p4 withcolor 0.219608 withpen pencircle scaled 3.262816; + fill p5 withcolor (1, 0.8, 0.666667); + draw p5 withcolor 0.219608 withpen pencircle scaled 2.4; + ); +% Normalize user icon. + unituserRight := unituserRight shifted (-llcorner unituserRight -.5urcorner unituserRight); + unituserRight := unituserRight scaled (.5/ypart urcorner unituserRight); + unituserLeft := unituserRight reflectedabout ((0,0), (0,1)); + +% Helper function: transform location on workflow circle in +% degrees into cartesian coordinates. + def degtoxy(expr deg) = + (point deg/45 of fullcircle scaled wfdiam) + enddef; + +% Draw workflow segments. + for i=0 upto wfsegments-1: + fill wfseg scaled wfdiam rotated (wfstart+i*wfsegangle) withcolor wf_col; + endfor + +% Fill-in workflow segment descriptions. + label(unituserLeft scaled usersize, degtoxy(wfstart+wfsegangle*0)); + label(btex \appl{Editor} etex, degtoxy(wfstart+wfsegangle*1)) withcolor appl_col; + label(btex \ext{fig.mp} etex, degtoxy(wfstart+wfsegangle*2)) withcolor ext_col; + label(btex \appl{MetaPost} etex, degtoxy(wfstart+wfsegangle*3)) withcolor appl_col; + label(btex \ext{fig.1} etex, degtoxy(wfstart+wfsegangle*4+wfsegangle/7)) withcolor ext_col; + label(btex \ext{fig.log} etex, degtoxy(wfstart+wfsegangle*4-wfsegangle/7)) withcolor .7[ext_col, wf_col]; + label(btex \appl{Previewer} etex, degtoxy(wfstart+wfsegangle*5)) withcolor appl_col; +endfig; + +end diff --git a/systems/doc/metapost/source-manual/mpman.bib b/systems/doc/metapost/source-manual/mpman.bib new file mode 100644 index 0000000000..7f089f8ba7 --- /dev/null +++ b/systems/doc/metapost/source-manual/mpman.bib @@ -0,0 +1,135 @@ +% 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/}" +} +@manual{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}" +} +@manual{hagen:metafun, + author = "Hans Hagen", + title = "Metafun", + month = jan, + year = 2002, + note = "\url{http://www.pragma-ade.com/general/manuals/metafun-s.pdf}" +} +@manual{luatex:manual, + organization = "Lua\TeX\ development team", + title = "Lua\TeX: Reference Manual", + note = "\url{http://www.luatex.org/svn/trunk/manual/luatexref-t.pdf}" +} +@manual{hagen:luamplib, + author = "Hans Hagen and Taco Hoekwater and Elie Roux", + title = "The luamplib package", + note = "\texttt{CTAN://macros/luatex/generic/luamplib/luamplib.pdf}" +} +@misc{lib:cairo, + key = "Cairo", + title = "Cairo graphics library", + note = "\texttt{http://cairographics.org/}" +} +% taken from http://www.mpfr.org/faq.html#cite +@Article{lib:mpfr, + author = "Laurent Fousse and Guillaume Hanrot and Vincent Lef\`evre and Patrick + P\'elissier and Paul Zimmermann", + title = "{MPFR}: A Multiple-Precision Binary Floating-Point Library with Correct Rounding", + journal = "{ACM} Transactions on Mathematical Software", + volume = "33", + number = "2", + month = jun, + year = "2007", + pages = "13:1--13:15", + URL = "http://doi.acm.org/10.1145/1236463.1236468", + abstract = "This paper presents a multiple-precision binary floating-point library, + written in the ISO C language, and based on the GNU MP library. Its + particularity is to extend to arbitrary-precision ideas from the IEEE 754 + standard, by providing \emph{correct rounding} and \emph{exceptions}. + We demonstrate how these strong semantics are achieved --- with no + significant slowdown with respect to other arbitrary-precision tools + --- and discuss a few applications where such a library can be useful.", +} +@misc{lib:decnumber, + key = "decnumber", + title = "dec{N}umber {ANSI} {C} implementation of General Decimal Arithmetic", + note = "\texttt{http://speleotrove.com/decimal/decnumber.html}" +} diff --git a/systems/doc/metapost/source-manual/mpman.ist b/systems/doc/metapost/source-manual/mpman.ist new file mode 100644 index 0000000000..9238679ce0 --- /dev/null +++ b/systems/doc/metapost/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/systems/doc/metapost/source-manual/mpman.mp b/systems/doc/metapost/source-manual/mpman.mp new file mode 100644 index 0000000000..342389e6aa --- /dev/null +++ b/systems/doc/metapost/source-manual/mpman.mp @@ -0,0 +1,851 @@ +% 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; + + +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(261); +path p[] ; +pen mypen ; +pen mypenC; +numeric L ; +numeric S ; +L:=10; +Sa:=1; +Sb:=2; +Rot=32; +p[-1] := ( (Sa*cosd(0),Sb*sind(0)) for i=1 upto L-1: -- (Sa*cosd(i/L*360), Sb*sind(i/L*360)) endfor -- cycle ) rotated Rot; +mypen := makepen(p[-1]) ; +mypenC:= (pencircle xscaled 2Sa yscaled 2Sb) rotated Rot; +p0 := (0,0){down} .. {up} (100,0) ; +p1 := envelope mypen of p0 ; +draw p1 withcolor black withpen pencircle scaled 0.2pt ; +draw p0 withcolor 0.8white withpen mypenC; +for t=1 upto length(p1): + draw (point t of p1) withpen pencircle scaled 0.8pt; +endfor; +%currentpicture := currentpicture scaled 30 ; +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 ${}\mid \descr{path subexpression} \descr{path join}$ \verb|cycle|\\ +$\descr{path subexpression} \rightarrow + \descr{path knot}$\\ +\> ${}\mid \descr{path expression} \descr{path join} \descr{path knot}$\\ +$\descr{path join} \rightarrow + \hbox{\verb|--|}$\\ +\> ${}\mid \descr{direction specifier} \descr{basic path join} + \descr{direction specifier}$\\ +$\descr{direction specifier} \rightarrow + \descr{empty}$\\ +\> ${}\mid {}$\verb|{curl| $\descr{numeric expression}$\verb|}|\\ +\> ${}\mid {}$\verb|{|$\descr{pair expression}$\verb|}|\\ +\> ${}\mid {}$\verb|{|$\descr{numeric expression}$\verb|,|% + $\descr{numeric expression}$\verb|}|\\ +$\descr{basic path join} \rightarrow + \hbox{\verb|..|} + \mid \hbox{\verb|...|} + \mid \hbox{\verb|..|}\descr{tension}\hbox{\verb|..|} + \mid \hbox{\verb|..|}\descr{controls}\hbox{\verb|..|}$\\ +$\descr{tension} \rightarrow + \hbox{\verb|tension|}\descr{numeric primary}$\\ +\> ${}\mid \hbox{\verb|tension|}\descr{numeric primary} + \hbox{\verb|and|}\descr{numeric primary}$\\ +$\descr{controls} \rightarrow + \hbox{\verb|controls|}\descr{pair primary}$\\ +\> ${}\mid \hbox{\verb|controls|}\descr{pair primary} + \hbox{\verb|and|}\descr{pair primary}$ +\end{ctabbing} +\caption{The syntax for path construction} +\label{sypath} +\end{figure} + +A pair of coordinates like \verb|(30,20)| or a \verb|z| variable that +represents a coordinate pair is what Figure~\ref{sypath} calls a +$\descr{pair primary}$. A $\descr{path knot}$ is similar except that it +can take on other forms such as a path expression in parentheses. +Primaries and expressions of various types will be discussed in full +generality in Section~\ref{exprs}. + + +\section{Linear Equations} +\label{lin.eq} + +An important feature taken from \MF\ is the ability to solve linear +equations so that programs can be written in a partially declarative fashion. +For example, the MetaPost interpreter can read +$$ \hbox{\verb|a+b=3; 2a=b+3;|} $$ +and deduce that $a=2$ and $b=1$. The same equations can be written +slightly more compactly by stringing them together with multiple equal +signs: +$$ \hbox{\verb|a+b = 2a-b = 3;|} $$ +Whichever way you give the equations, you can then give the +command\index{show?\texttt{show}} +$$ \hbox{\tt show a,b;} $$ +to see the values of {\tt a} and {\tt b}. MetaPost responds by typing +$$\begin{verbatim} +>> 2 +>> 1 +\end{verbatim} +$$ + +Note that {\tt =}\index{=?\texttt{=}} is not an assignment operator; it +simply declares that the left-hand side equals the right-hand side. +Thus {\tt a=a+1} produces an error message complaining about an +``inconsistent equation\index{Inconsistent equation?\texttt{Inconsistent +equation}}.'' The way to increase the value of {\tt a} is to use the +assignment\index{assignment} operator {\tt :=}\index{:=?\texttt{:=}} as +follows: +$$ \hbox{\tt a:=a+1;} $$ +In other words, {\tt :=} is for changing existing values while {\tt =} is for +giving linear equations to solve. + +There is no restriction against mixing equations and assignment +operations as in the following example: +$$ \hbox{\tt a = 2; b = a; a := 3; c = a;} $$ +After the first two equations set {\tt a} and~{\tt b} equal to 2, the +assignment operation changes {\tt a} to~3 without affecting {\tt b}. +The final value of {\tt c} is 3 since it is equated to the new value of +{\tt a}. In general, an assignment operation is interpreted by first +computing the new value, then eliminating the old value from all +existing equations before actually assigning the new value. + +\subsection{Equations and Coordinate Pairs} + +MetaPost can also solve linear equations involving coordinate pairs. We have +already seen many trivial examples of this in the form of equations like +$$ \hbox{\verb|z1=(0,.2in)|} $$ +Each side of the equation must be formed by adding or subtracting +coordinate pairs and multiplying or dividing them by known numeric +quantities. Other ways of naming pair-valued variables will be +discussed later, but the ${\tt z}\descr{number}$\index{z convention?{\tt +z} convention} is convenient because it is an abbreviation for +$$ \hbox{\tt (x}\descr{number} \hbox{\tt, y}\descr{number}\hbox{\tt)} $$ +This makes it possible to give values to \verb|z| variables by giving +equations involving their coordinates. For instance, points {\tt z1}, +{\tt z2}, {\tt z3}, and~{\tt z6} in Figure~\ref{fig12} were initialized +via the following equations: +\begin{eqnarray*} + &&\hbox{\verb|z1=-z2=(.2in,0);|} \\ + &&\hbox{\verb|x3=-x6=.3in;|} \\ + &&\hbox{\verb|x3+y3=x6+y6=1.1in;|} +\end{eqnarray*} +Exactly the same points could be obtained by setting their values directly: +$$ \begin{verbatim} +z1=(.2in,0); z2=(-.2in,0); +z3=(.3in,.8in); z6=(-.3in,1.4in); +\end{verbatim} +$$ + +After reading the equations, the MetaPost interpreter knows the values +of {\tt z1}, {\tt z2}, {\tt z3}, and~{\tt z6}. The next step in the +construction of Figure~\ref{fig12} is to define points {\tt z4} and {\tt +z5} equally spaced along the line from {\tt z3} to {\tt z6}. Since this +operation comes up often, MetaPost has a special syntax for it. This +mediation construction\index{mediation}\index{[]?\texttt{[]}!mediation} +$$ \hbox{\verb|z4=1/3[z3,z6]|} $$ +means that {\tt z4} is $1\over3$ of the way from $z3$ to $z6$; i.e., +$$ {\tt z4}={\tt z3}+{1\over3}({\tt z6}-{\tt z3}). $$ +Similarly +$$ \hbox{\verb|z5=2/3[z3,z6]|} $$ +makes {\tt z5} $2\over3$ of the way from $z3$ to $z6$. + +\begin{figure}[htp] +$$ \begin{verbatim} +beginfig(13); +z1=-z2=(.2in,0); +x3=-x6=.3in; +x3+y3=x6+y6=1.1in; +z4=1/3[z3,z6]; +z5=2/3[z3,z6]; +z20=whatever[z1,z3]=whatever[z2,z4]; +z30=whatever[z1,z4]=whatever[z2,z5]; +z40=whatever[z1,z5]=whatever[z2,z6]; +draw z1--z20--z2--z30--z1--z40--z2; +pickup pencircle scaled 1pt; +draw z1--z2; +draw z3--z6; +endfig; +\end{verbatim} +\quad \mathcenter{\includegraphics{mpman-13.mps}} +$$ +\caption[MetaPost code and figure using linear equations] + {MetaPost commands and the resulting figure. Point labels have been + added to the figure for clarity.} +\label{fig12} +\end{figure} + +Mediation can also be used to say that some point is at an unknown +position along the line between two known points. For instance, we +could a introduce new variable {\tt aa} and write something like +$$ \hbox{\verb|z20=aa[z1,z3];|} $$ +This says that {\tt z20} is some unknown fraction {\tt aa} of the way +along the line between {\tt z1} and {\tt z3}. Another such equation +involving a different line is sufficient to fix the value of {\tt z20}. +To say that {\tt z20} is at the intersection of the {\tt z1}-{\tt z3} +line and the {\tt z2}-{\tt z4} line, introduce another variable {\tt ab} +and set +$$ \hbox{\verb|z20=ab[z2,z4];|} $$ +This allows MetaPost to solve for {\tt x20}, {\tt y20}, {\tt aa}, and {\tt ab}. + +It is a little painful to keep thinking up new names like {\tt aa} and +{\tt ab}. This can be avoided by using a special feature called {\tt +whatever}\index{whatever?\texttt{whatever}}\label{Dwhatev}. This macro +generates a new anonymous variable each time it appears. Thus the +statement +$$ \hbox{\verb|z20=whatever[z1,z3]=whatever[z2,z4]|} $$ +sets {\tt z20} as before, except it uses {\tt whatever} to generate two +{\em different\/} anonymous variables instead of {\tt aa} and {\tt ab}. +This is how Figure~\ref{fig12} sets {\tt z20}, {\tt z30}, and +{\tt z40}. + +\subsection{Dealing with Unknowns} + +A system of equations such as those used in Figure~\ref{fig12} can be given in +any order as long as all the equations are linear and all the variables can +be determined before they are needed. This means that the equations +\begin{eqnarray*} + && \hbox{\verb|z1=-z2=(.2in,0);|}\\ + && \hbox{\verb|x3=-x6=.3in;|}\\ + && \hbox{\verb|x3+y3=x6+y6=1.1in;|}\\ + && \hbox{\verb|z4=1/3[z3,z6];|}\\ + && \hbox{\verb|z5=2/3[z3,z6];|} +\end{eqnarray*} +suffice to determine {\tt z1} through {\tt z6}, no matter what order the +equations are given in. On the other hand +$$ \hbox{\verb|z20=whatever[z1,z3]|} $$ +is legal only when a known value has previously been specified for the difference +${\tt z3}-{\tt z1}$, because the equation is equivalent +to\index{mediation} +$$ \hbox{\verb|z20 = z1 + whatever*(z3-z1)|} $$ +and the linearity requirement disallows multiplying unknown components +of ${\tt z3}-{\tt z1}$ by the anonymous unknown result of {\tt +whatever}. The general rule is that you cannot multiply two unknown +quantities or divide by an unknown quantity, nor can an unknown quantity +be used in a {\tt draw} statement. Since only linear equations are +allowed, the MetaPost interpreter can easily solve the equations and +keep track of what values are known. + +The most natural way to ensure that MetaPost can handle an expression like +$$ \hbox{\verb|whatever[z1,z3]|} $$ +is to ensure that {\tt z1} and {\tt z3} are both known. However this is not +actually required since MetaPost may be able to deduce a known value for +${\tt z3}-{\tt z1}$ before either of {\tt z1} and {\tt z3} are known. +For instance, MetaPost will accept the equations +$$ \hbox{\verb|z3=z1+(.1in,.6in); z20=whatever[z1,z3];|} $$ +but it will not be able to determine any of the components of {\tt z1}, +{\tt z3}, or {\tt z20}. + +These equations do give partial information about {\tt z1}, {\tt z3}, +and {\tt z20}. A good way to see this is to give another equation such as +$$ \hbox{\verb|x20-x1=(y20-y1)/6;|} $$ +This produces the error message ``{\tt ! Redundant +equation}\index{Redundant equation?\texttt{Redundant equation}}.'' +MetaPost assumes that you are trying to tell it something new, so it +will usually warn you when you give a redundant equation. If the new +equation had been +$$ \hbox{\verb|(x20-x1)-(y20-y1)/6=1in;|} $$ +the error message would have been\index{Inconsistent +equation?\texttt{Inconsistent equation}} +$$ \hbox{\verb|! Inconsistent equation (off by 71.99979).|} $$ +This error message illustrates +roundoff\index{roundoff error} error in MetaPost's linear equation solving +mechanism. Roundoff error +is normally not a serious problem, but it is likely to cause trouble if you are +trying to do something like find the intersection of two lines that are almost +parallel. + + +\section{Expressions} +\label{exprs} + +It is now time for a more systematic view of the MetaPost language. We +have seen that there are numeric quantities and coordinate pairs, and +that these can be combined to specify paths for {\tt draw} statements. +We have also seen how variables can be used in linear equations, but we +have not discussed all the operations and data types that can be used in +equations. + +It is possible to experiment with expressions involving any of the data types +mentioned below by using the statement\index{show?\texttt{show}}\label{Dshow} +$$ {\tt show}\, \descr{expression} $$ +to ask MetaPost to print a symbolic representation of the value of each +expression. For known numeric values, each is printed on a new line +preceded by ``\verb|>> |''. Other types of result are printed similarly, +except that complicated values are sometimes not printed on standard +output. This produces a reference to the transcript +file\index{files!transcript} that looks like this: +$$ \hbox{\verb|>> picture (see the transcript file)|} $$ +If you want to the full results of {\tt show} statements to be printed +on your terminal, assign a positive value to the internal\index{internal +variables} variable\index{variables!internal} {\tt +tracingonline}\index{tracingonline?\texttt{tracingonline}}\label{Dtonline}. + +\subsection{Data Types} +\label{datatypes} + +MetaPost actually has ten basic data types\index{types}: numeric, pair, +path, transform, (rgb)color, cmykcolor, string, boolean, picture, and +pen. Let us consider these one at a time beginning with the numeric +type. + +Numeric\index{numeric type} quantities in MetaPost are represented in +fixed point arithmetic\index{arithmetic} as integer multiples of +$1\over65536$, the smallest positive value, which is also available as +the predefined constant +\texttt{epsilon}\index{epsilon?\texttt{epsilon}}\label{Depsilon}.\footnote{MetaPost + can also do arithmetic with higher and (almost) arbitrary precision. + See Appendix~\ref{hparith} for more information.} Numeric quantities +must normally have absolute values less than 4096 but intermediate +results can be eight times larger. This should not be a problem for +distances or coordinate values since 4096 PostScript points is more than +1.4~meters. If you need to work with numbers of magnitude 4096 or more, +setting the internal variable +\texttt{warningcheck}\index{warningcheck?\texttt{warningcheck}}\label{Dwarncheck} +to zero suppresses the warning messages about large numeric quantities. + +The pair\index{pair type} type is represented as a pair of numeric +quantities. We have seen that pairs are used to give coordinates in +{\tt draw} statements. Pairs can be added, subtracted, used in +mediation expressions, or multiplied or divided by numerics. + +Paths\index{path type} have already been discussed in the context of {\tt draw} +statements, but +that discussion did not mention that paths are first-class objects that can be +stored and manipulated. A path represents a straight or curved line that is +defined parametrically. + +Another data type represents an arbitrary affine +transformation\index{transform type}. A {\em transform\/} can be any +combination of rotating, scaling, slanting, and shifting. If ${\tt +p}=(p_x,p_y)$ is a pair and {\tt T} is a +transform,\index{transformed?\texttt{transformed}} +$$ \hbox{\tt p transformed T} $$ +is a pair of the form +$$ (t_x+t_{xx}p_x+t_{xy}p_y, t_y+t_{yx}p_x+t_{yy}p_y), $$ +where the six numeric quantities $(t_x,t_y,t_{xx},t_{xy},t_{yx},t_{yy})$ +determine {\tt T}. Transforms can also be applied to paths, pictures, pens, +and transforms. + +The color\index{color type} type is like the pair type, except +that it has three components instead of two and each component is +normally between 0 and 1. Like pairs, colors can be added, +subtracted, used in mediation expressions, or multiplied or divided +by numerics. Colors can be specified in terms of the predefined +constants \ttindex{black}\label{Dblack}, \ttindex{white}\label{Dwhite}, +\ttindex{red}\label{Dred}, \ttindex{green}\label{Dgreen}, +\ttindex{blue}\label{Dblue}, or the red, green, and +blue components can be given explicitly. Black is {\tt (0,0,0)} and +white is {\tt (1,1,1)}. A level of gray such as {\tt (.4,.4,.4)} can also be +specified as {\tt 0.4white}. Although color typed variables may be +any ordered triplet, when adding an object to a picture, MetaPost will +convert its color by clipping each component between 0 and 1. For +example, MetaPost will output the color (1,2,3) as (1,1,1). +MetaPost solves linear equations involving +colors the same way it does for pairs. The type `rgbcolor' is an alias of +type `color'. + +The cmykcolor\index{cmykcolor type} type is similar +to the color type except that it has four components instead of +three. This type is used to specify colors by their cyan, magenta, +yellow, and black components explicitly. Because CMYK colors deal with +pigments instead of light rays, the color white would be expressed as +{\tt (0,0,0,0)} and black as {\tt (0,0,0,1)}. In theory, the colors +{\tt ($c$,$m$,$y$,1)} and {\tt (1,1,1,$k$)} should result in black for +any values of $c$, $m$, $y$ and~$k$, too. But in practice, this is +avoided since it is a waste of colored ink and can lead to +unsatisfactory results. + +A string\index{string type} represents a sequence of characters. +String constants\index{string constants} are given +in double quotes \hbox{\verb|"like this"|}. String constants cannot contain +double quotes or newlines, but there is a way to construct a string containing +any sequence of eight-bit characters. + +\label{Dscantokens} +Conversion from strings to other types, notably numeric, can be accomplished by +the {\tt scantokens}\index{scantokens?\texttt{scantokens}} primitive: +\begin{center}\texttt{n := scantokens(}\textit{str}\texttt{);}\end{center} +More generally, \texttt{scantokens} parses a string into a token +sequence, as if MetaPost had read it as input. + +The boolean\index{boolean type} type has the constants {\tt +true}\index{true?\texttt{true}}\label{Dtrue} and {\tt +false}\index{false}\label{Dfalse} and the operators {\tt +and}\index{and?\texttt{and}}\label{Dand}, {\tt +or}\index{or?\texttt{or}}\label{Dor}, {\tt +not}\index{not?\texttt{not}}\label{Dnot}. The relations \verb|=| and +\verb|<>|\index{<>?\texttt{<>}}\label{Dcmpar} test objects of any type +for equality and inequality\index{inequality}. +Comparison\index{comparison} relations \verb|<|\index{|\index{>?\texttt{>}}, and +\verb|>=|\index{>=?\texttt{>=}} are defined lexicographically for +strings and in the obvious way for numerics. Ordering relations are +also defined for booleans, pairs, colors, and transforms, but the +comparison rules are not worth discussing here. + +The picture\index{picture type} data type is just what the name implies. +Anything that can be drawn in MetaPost can be stored in a picture +variable. In fact, the {\tt draw}\index{draw?\texttt{draw}} statement +actually stores its results in a special picture variable called {\tt +currentpicture}\index{currentpicture?\texttt{currentpicture}}. Pictures +can be added to other pictures and operated on by transforms. + +Finally, there is a data type called a pen\index{pen type}. The main +function of pens in MetaPost is to determine line thickness, but they +can also be used to achieve calligraphic effects. The +statement\index{pickup?\texttt{pickup}}\label{Dpickup} +$$ {\tt pickup\ }\descr{pen expression} $$ +causes the given pen to be used in subsequent +\verb|draw|\index{draw?\texttt{draw}} or +\verb|drawdot|\index{drawdot?\texttt{drawdot}} statements. Normally, +the pen expression is of the form +$$ {\tt pencircle\ scaled\ }\descr{numeric primary}. $$ +This defines a circular pen that produces lines of constant thickness. +If calligraphic effects are desired, the pen expression can be adjusted to give +an elliptical pen or a polygonal pen. + +\subsection{Operators} + +There are many different ways to make expressions of the ten basic +types, but most of the operations fit into a fairly simple syntax with +four levels of precedence as shown in Figure~\ref{syexpr}. There are +primaries\index{primary?\tdescr{primary}}, +secondaries\index{secondary?\tdescr{secondary}}, +tertiaries\index{tertiary?\tdescr{tertiary}}, and +expressions\index{expression?\tdescr{expression}} of each of the basic +types, so the syntax rules could be specialized to deal with items such +as \tdescr{numeric primary}, \tdescr{boolean tertiary}, etc. This +allows the result type for an operation to depend on the choice of +operator and the types of its operands. For example, the {\tt <} +relation is a \tdescr{tertiary binary} that can be applied to a +\tdescr{numeric expression} and a \tdescr{numeric tertiary} to give a +\tdescr{boolean expression}. The same operator can accept other operand +types such as \tdescr{string expression} and \tdescr{string tertiary}, +but an error message results if the operand types do not match. + +\begin{figure}[htp] +\begin{ctabbing} +$\tt \descr{primary} \rightarrow \descr{variable}$\\ +$\tt \qquad \;|\; \hbox{\tt (}\descr{expression}\hbox{\tt )}$\\ +$\tt \qquad \;|\; \descr{nullary op}$\\ +$\tt \qquad \;|\; \descr{of operator} \descr{expression} + of \descr{primary}$\\ +$\tt \qquad \;|\; \descr{unary op} \descr{primary}$\\ +$\tt \descr{secondary} \rightarrow \descr{primary}$\\ +$\tt \qquad \;|\; \descr{secondary} \descr{primary binop} \descr{primary}$\\ +$\tt \descr{tertiary} \rightarrow \descr{secondary}$\\ +$\tt \qquad \;|\; \descr{tertiary} \descr{secondary binop} + \descr{secondary}$\\ +$\tt \descr{expression} \rightarrow \descr{tertiary}$\\ +$\tt \qquad \;|\; \descr{expression} \descr{tertiary binop} + \descr{tertiary}$ +\end{ctabbing} +\caption{The overall syntax rules for expressions} +\index{unary op?\tdescr{unary op}} \index{nullary op?\tdescr{nullary op}} +\index{primary binop?\tdescr{primary binop}} +\index{secondary binop?\tdescr{secondary binop}} +\index{tertiary binop?\tdescr{tertiary binop}} +\label{syexpr} +\end{figure} + +The multiplication and division operators {\tt *}\label{Dmldiv} and~{\tt +/} are examples of what Figure~\ref{syexpr} calls a \tdescr{primary +binop}. Each can accept two numeric operands or one numeric operand and +one operand of type pair or color. The exponentiation operator +\verb|**|\index{**?\texttt{**}}\index{exponentiation}\label{Dpow} is a +\tdescr{primary binop} that requires two numeric operands. Placing this +at the same level of precedence as multiplication and division has the +unfortunate consequence that \verb|3*a**2| means $(3a)^2$, not +$3(a^2)$\index{parsing irregularities}. Since unary +negation\label{Dneg} applies at the primary level, it also turns out +that \verb|-a**2| means $(-a)^2$. Fortunately, subtraction has lower +precedence so that \verb|a-b**2| does mean $a-(b^2)$ instead of +$(a-b)^2$. + +Another \tdescr{primary binop} is the {\tt +dotprod}\index{dotprod?\texttt{dotprod}}\label{Ddprod} operator that +computes the vector dot product of two pairs. For example, {\tt z1 +dotprod z2} is equivalent to {\tt x1*x2 + y1*y2}. + +The additive operators {\tt +} and {\tt -}\label{Dadd} are +\tdescr{secondary binops} that operate on numerics, pairs, or colors and +produce results of the same type. Other operators that fall in this +category are ``Pythagorean addition'' +\verb|++|\index{++?\texttt{++}}\label{Dpyadd} and ``Pythagorean +subtraction'' \verb|+-+|\index{+-+?\texttt{+-+}}\label{Dpysub}: +\verb|a++b| means $\sqrt{a^2+b^2}$ and \verb|a+-+b| means +$\sqrt{a^2-b^2}$. There are too many other operators to list here, but +some of the most important are the boolean operators {\tt +and}\index{and?\texttt{and}} and {\tt or}\index{or?\texttt{or}}. The +{\tt and} operator is a \tdescr{primary binop} and the {\tt or} operator +is a \tdescr{secondary binop}. + +The basic operations on strings are concatenation\index{concatenation}, +substring construction and calculating the length of a string. +The \tdescr{tertiary binop} \verb|&|\index{&?\texttt{\&}}\label{Damp} +implements concatenation; e.g., +$$ \hbox{\verb|"abc" & "de"|} $$ +produces the string \verb|"abcde"|. The {\tt +length}\index{length?\texttt{length}}\label{DlengthString} operator +returns the number of characters in a string if the argument is a +\tdescr{string primary}; e.g., +$$ \hbox{\verb|length "abcde"|} $$ +returns \verb|5|. Another application of the {\tt length} operator is +discussed on p.\ \pageref{Dlength}. For substring construction, the +\tdescr{of operator} {\tt substring}\index{substring +of?\texttt{substring of}}\label{Dsubstr} is used like this: +$$ {\tt substring}\, \descr{pair expression} \,{\tt of}\, \descr{string primary} $$ +The \tdescr{pair expression} determines what part of the string to +select. For this purpose, the string is indexed\index{indexing} so that +integer positions fall {\em between\/} characters. Pretend the string +is written on a piece of graph paper so that the first character +occupies $x$~coordinates between zero and one and the next character +covers the range $1\le x\le2$, etc. Thus the string \verb|"abcde"| +should be thought of like this +$$ \includegraphics{mpman-14.mps} $$ +and {\tt substring (2,4) of "abcde"} is {\tt "cd"}. This takes a little +getting used to but it tends to avoid annoying ``off by one'' errors. + +Some operators take no arguments at all. An example of what +Figure~\ref{syexpr} calls a \tdescr{nullary op} is {\tt +nullpicture}\index{nullpicture?\texttt{nullpicture}}\label{Dnlpic} which +returns a completely blank picture. + +The basic syntax in Figure~\ref{syexpr} only covers aspects of the +expression syntax that are relatively type-independent. For instance, +the complicated path syntax given in Figure~\ref{sypath} gives +alternative rules for constructing a \tdescr{path expression}. An +additional rule\index{path knot?\tdescr{path knot}} +$$ \descr{path knot} \rightarrow \descr{pair tertiary} \;|\; \descr{path tertiary} +$$ +explains the meaning of \tdescr{path knot} in Figure~\ref{sypath}. This means +that the path expression +$$ \hbox{\verb|z1+(1,1){right}..z2|} $$ +does not need parentheses around {\tt z1+(1,1)}. + +\subsection{Fractions, Mediation, and Unary Operators} + +Mediation\index{mediation} expressions do not appear in the basic expression +syntax of Figure~\ref{syexpr}. Mediation expressions are parsed at the +\tdescr{primary} level, so the general rule for constructing them is +$$ \descr{primary} \rightarrow + \descr{numeric atom} \hbox{\tt [} \descr{expression} + \hbox{\tt ,} \descr{expression} \hbox{\tt ]} +$$ +where each \tdescr{expression} can be of type numeric, pair, or color. +The \tdescr{numeric atom}\index{numeric atom?\tdescr{numeric atom}} in a +mediation expression is an extra simple type of \tdescr{numeric primary} +as shown in Figure~\ref{synprim}. The meaning of all this is that the +initial parameter in a mediation expression needs to be parenthesized +when it is not just a variable, a positive number, or a positive +fraction. For example,\index{parsing irregularities} +$$ \hbox{\tt -1[a,b]} \quad {\rm and}\quad \hbox{\tt (-1)[a,b]} $$ +are very different: the former is $-b$ since it is equivalent to +{\tt -(1[a,b])}; the latter is $a-(b-a)$ or $2a-b$. + +\begin{figure}[htp] +\begin{ctabbing} +$\tt \descr{numeric primary} \rightarrow \descr{numeric atom}$\\ +$\tt \qquad \;|\; \descr{numeric atom}\hbox{\tt [} + \descr{numeric expression}\hbox{\tt ,}\descr{numeric expression}\hbox{\tt ]}$\\ +$\tt \qquad \;|\; \descr{of operator} \descr{expression} of \descr{primary}$\\ +$\tt \qquad \;|\; \descr{unary op} \descr{primary}$\\ +$\tt \descr{numeric atom} \rightarrow \descr{numeric variable}$\\ +$\tt \qquad \;|\; \descr{number or fraction}$\\ +$\tt \qquad \;|\; \hbox{\tt (}\descr{numeric expression}\hbox{\tt )}$\\ +$\tt \qquad \;|\; \descr{numeric nullary op}$\\ +$\tt \descr{number or fraction} \rightarrow \descr{number} + \hbox{\tt /}\descr{number}$\\ +$\tt \qquad \;|\; \descr{number not followed by + `$\hbox{\tt /}\descr{number}$'}$ +\end{ctabbing} +\caption{Syntax rules for numeric primaries} +\label{synprim} +\end{figure} + +A noteworthy feature of the syntax rules in Figure~\ref{synprim} is that +the {\tt /}\index{fractions} operator binds most tightly when its +operands are numbers. Thus {\tt 2/3} is a \tdescr{numeric +atom}\index{numeric atom?\tdescr{numeric atom}}\index{parsing +irregularities} while {\tt (1+1)/3} is only a \tdescr{numeric +secondary}. Applying a \tdescr{unary op} such as {\tt +sqrt}\index{sqrt?\texttt{sqrt}}\label{Dsqrt} makes the difference clear: +$$ \hbox{\tt sqrt 2/3} $$ +means $\sqrt{2\over3}$ while +$$ \hbox{\tt sqrt(1+1)/3} $$ +means $\sqrt 2/3$. Operators such as {\tt sqrt} can be written in +standard functional notation, but it is often unnecessary to +parenthesize the argument. This applies to any function that is parsed +as a \tdescr{unary op}. For instance {\tt +abs(x)}\index{abs?\texttt{abs}}\label{Dabs} and {\tt abs x} both compute +the absolute value of {\tt x}. The same holds for the {\tt +round}\index{round?\texttt{round}}\label{Dround}, {\tt +floor}\index{floor?\texttt{floor}}\label{Dfloor}, {\tt +ceiling}\index{ceiling?\texttt{ceiling}}\label{Dceil}, {\tt +sind}\index{sind?\texttt{sind}}\label{Dsind}, and {\tt +cosd}\index{cosd?\texttt{cosd}}\label{Dcosd} functions. The last two of +these compute trigonometric functions of angles in degrees. + +Not all unary operators take numeric arguments and return numeric +results. For instance, the {\tt abs}\index{abs?\texttt{abs}} operator +can be applied to a pair to compute the Euclidean length of a vector. +Applying the {\tt +unitvector}\index{unitvector?\texttt{unitvector}}\label{Duvec} operator +to a pair produces the same pair rescaled so that its Euclidean length +is~1. The {\tt decimal}\index{decimal?\texttt{decimal}}\label{Ddecop} +operator takes a number and returns the string representation. The {\tt +angle}\index{angle?\texttt{angle}}\label{Dangle} operator takes a pair +and computes the two-argument arctangent; i.e., {\tt angle} is the +inverse of the {\tt dir} operator that was discussed in +Section~\ref{tenscurl}. There is also an operator {\tt +cycle}\index{cycle?\texttt{cycle}}\label{Dcycop} that takes a +\tdescr{path primary} and returns a boolean result indicating whether +the path is a closed curve. + +There is a whole class of other operators that classify expressions and +return boolean results. A type name such as {\tt +pair}\index{pair?\texttt{pair}} can operate on any type of +\tdescr{primary} and return a boolean result indicating whether the +argument is a {\tt pair}\label{Dpairop}. Similarly, each of the +following can be used as a unary operator: +{\tt numeric}\index{numeric?\texttt{numeric}}\label{Dnumop}, +{\tt boolean}\index{boolean?\texttt{boolean}}\label{Dboolop}, +{\tt cmykcolor}\index{cmykcolor?\texttt{cmykcolor}}\label{Dccolrop}, +{\tt color}\index{color?\texttt{color}}\label{Dcolrop}, +{\tt string}\index{string?\texttt{string}}\label{Dstrgop}, +{\tt transform}\index{transform?\texttt{transform}}\label{Dtrnfop}, +{\tt path}\index{path?\texttt{path}}\label{Dpathop}, +{\tt pen}\index{pen?\texttt{pen}}\label{Dpenop}, +{\tt picture}\index{picture?\texttt{picture}}\label{Dpictop}, and +{\tt rgbcolor}\index{rgbcolor?\texttt{rgbcolor}}\label{Drcolrop}. +Besides just +testing the type of a \tdescr{primary}, you can use the {\tt +known}\index{known?\texttt{known}}\label{Dknown} and {\tt +unknown}\index{unknown?\texttt{unknown}}\label{Dunknwn} operators to +test if it has a completely known value. + +Even a number can behave like an operator in some contexts. This refers +to the trick that allows {\tt 3x}\index{multiplication, implicit} and +{\tt 3cm} as alternatives to {\tt 3*x} and {\tt 3*cm}. The rule is that +a \tdescr{number or fraction} that is not followed by {\tt +}, {\tt -}, +or another \tdescr{number or fraction} can serve as a \tdescr{primary +binop}. Thus {\tt 2/3x}\index{parsing irregularities} is two thirds of +{\tt x} but {\tt (2)/3x} is $2\over3x$ and {\tt 3 3} is illegal. + +There are also operators for extracting numeric subfields from pairs, +colors, cmykcolors, and even transforms. If {\tt p} is a \tdescr{pair +primary}, {\tt xpart p}\index{xpart?\texttt{xpart}}\label{Dxprt} and +{\tt ypart p}\index{ypart?\texttt{ypart}}\label{Dyprt} extract its components so that +$$ \hbox{\tt (xpart p, ypart p)} $$ is equivalent to~{\tt p} even if +{\tt p} is an unknown pair that is being used in a linear equation. +Similarly, a color {\tt c} is equivalent +to\index{redpart?\texttt{redpart}}% +\index{greenpart?\texttt{greenpart}}% +\index{bluepart?\texttt{bluepart}}\label{Drgbprt} +$$ \hbox{\tt (redpart c, greenpart c, bluepart c)}. $$ +For a cmykcolor {\tt c}, the components are% +\index{cyanpart?\texttt{cyanpart}}% +\index{magentapart?\texttt{magentapart}}% +\index{yellowpart?\texttt{yellowpart}}% +\index{blackpart?\texttt{blackpart}}\label{Dcmykprt} +$$ \hbox{\tt (cyanpart c, magentapart c, yellowpart c, blackpart c)} $$ +and for a greyscale color {\tt c}, there is only one component% +\index{greypart?\texttt{greypart}}\label{Dgreyprt}% +$$ \hbox{\tt greypart c}. $$ +All color component operators are discussed in more detail in +section~\ref{piccomp}. Part specifiers for transforms are discussed +in section~\ref{transsec}. + + +\section{Variables} +\label{vars} + +MetaPost allows compound variable names such as {z.a}, {\tt x2r}, {\tt y2r}, +and {\tt z2r}, where {\tt z2r} means {\tt (x2r,y2r)} and {\tt z.a} means +{\tt (x.a,y.a)}. In fact there is a broad class of suffixes such that +{\tt z}\tdescr{suffix}\index{suffix?\tdescr{suffix}} means +$$ (x\descr{suffix},\, y\descr{suffix}). $$ +Since a \tdescr{suffix} is composed of tokens, it is best to begin with a few +comments about tokens. + +\subsection{Tokens} + +A MetaPost input file is treated as a sequence of numbers, string +constants, and symbolic tokens\index{tokens}\index{tokens!symbolic}. A +number consists of a sequence of digits possibly containing a decimal +point. Technically, the minus sign in front of a negative number is a +separate token. Since MetaPost uses fixed point +arithmetic\index{arithmetic}, it does not understand exponential +notation such as {\tt 6.02E23}. MetaPost would interpret this as the +number 6.02, followed by the symbolic token {\tt E}, followed by the +number~23. + +Anything between a pair of double quotes {\tt "} is a +string constant\index{string constants}. It is +illegal for a string constant to start on one line and end on a later line. +Nor can a string constant contain double quotes {\tt "} or anything other than +printable ASCII characters. + +Everything in a line of input other than numbers and string constants is broken +into symbolic tokens\index{tokens!symbolic}. A symbolic token is a sequence of +one or more similar characters, where characters are ``similar'' if they occur +on the same row of Table~\ref{classes}. + +\begin{table} +$$\begin{tabular}{c} +\verb|ABCDEFGHIJKLMNOPQRSTUVWXYZ_abcdefghijklmnopqrstuvwxyz|\\ +{\tt :<=>|}\\ +\verb|#&@$|\\ +\verb|/*\|\\ +{\tt +-}\\ +{\tt !?}\\ +{\tt '`}\\ +\verb|^~|\\ +\verb|{}|\\ +{\tt [}\\ +{\tt ]}\\ +\end{tabular} +$$ +\caption{Character classes for tokenization} +\label{classes} +\end{table} + +Thus \verb|A_alpha| and {\tt +-+} are symbolic tokens but {\tt !=} is +interpreted as two tokens and {\tt x34} is a symbolic token followed by +a number. Since the brackets {\tt [} and {\tt ]} are listed on lines by +themselves, the only symbolic tokens involving them are {\tt [}, {\tt +[[}, {\tt [[[}, etc.\ and {\tt ]}, {\tt ]]}, etc. + +Some characters are not listed in Table~\ref{classes} because they need +special treatment. The four characters {\tt ,;()} are ``loners'': each +comma, semicolon, or parenthesis is a separate token even when they +occur consecutively. Thus {\tt (())} is four tokens, not one or two. +The percent sign is very special because it introduces +comments\index{\%?\texttt{\%}!comment}\index{comments}. The percent +sign and everything after it up to the end of the line are ignored. + +Another special character is the period. Two or more periods +together form a symbolic token, but a single period is ignored, and a period +preceded or followed by digits is part of a number Thus {\tt ..} +and {\tt ...} are symbolic tokens while {\tt a.b} is just two tokens {\tt a} +and {\tt b}. It conventional to use periods to separate tokens in this fashion +when naming a variable that is more than one token long. + +\subsection{Variable Declarations} +\label{vardecl} + +A variable name is a symbolic token or a sequence of symbolic tokens. +Most symbolic tokens are legitimate variable names, but anything with a +predefined meaning like {\tt draw}, {\tt +}, or {\tt ..} is disallowed; +i.e., variable names cannot be macros or MetaPost primitives. This +minor restriction allows an amazingly broad class of variable names: +{\tt alpha}, \verb|==>|, \verb|@&#$&|, and \verb|~~| are all legitimate +variable names. Such symbolic tokens without special meanings are +called {\em tags}\index{tags}. + +A variable name can be a sequence of tags like {\tt f.bot} or {\tt +f.top}. The idea is to provide some of the functionality of Pascal +records or C structures. It is also possible to simulate arrays by +using variable names that contain numbers as well as symbolic tokens. +For example, the variable name {\tt x2r} consists of the tag {\tt x}, +the number 2, and the tag~{\tt r}. There can also be variables named +{\tt x3r} and even {\tt x3.14r}. These variables can be treated as an +array\index{arrays} via constructions like {\tt x[i]r}, where {\tt i} +has an appropriate numeric value. The overall syntax for variable names +is shown in Figure~\ref{syvar}. + +\begin{figure}[htp] +\begin{ctabbing} +$\tt \descr{variable} \rightarrow \descr{tag}\descr{suffix}$\\ +$\tt \descr{suffix} \rightarrow \descr{empty} \;|\; + \descr{suffix}\descr{subscript} \;|\; \descr{suffix}\descr{tag}$\\ +$\tt \descr{subscript} \rightarrow \descr{number} \;|\; + \hbox{\tt [}\descr{numeric expression}\hbox{\tt ]}$ +\end{ctabbing} +\caption{The syntax for variable names.} +\index{suffix?\tdescr{suffix}}\index{subscript?\tdescr{subscript}} +\label{syvar} +\end{figure} + +Variables like {\tt x2} and {\tt y2} take on numeric values by default, so we +can use the fact that {\tt z}\tdescr{suffix} is an abbreviation for\index{z convention?{\tt z} convention}\label{Dzconv} +$$ (x\descr{suffix},\, y\descr{suffix}) $$ +to generate pair-valued variables when needed. It turns out that the +{\tt beginfig}\index{beginfig?\texttt{beginfig}} macro wipes out +pre-existing values variables that begin with the tags {\tt x} or {\tt +y} so that {\tt beginfig} \ldots\ {\tt endfig} blocks do not interfere +with each other when this naming scheme is used. In other words, +variables that start with {\tt x}, {\tt y}, {\tt z} are +local\index{variables!local}\index{locality} to the figure they are used +in. General mechanisms for making variables local will be discussed in +Section~\ref{grsec}. + +Type declarations\index{declarations}\index{type declarations} +make it possible to use almost any naming scheme while still +wiping out any previous value that might cause interference. For example, the +declaration +$$ \hbox{\tt pair pp, a.b;} $$ +makes {\tt pp} and {\tt a.b} unknown pairs. Such a declaration is not +strictly local since {\tt pp} and {\tt a.b} are not automatically +restored to their previous values at the end of the current figure. Of +course, they are restored to unknown pairs if the declaration is +repeated. + +Declarations work the same way for any of the other nine types: numeric, +path, transform, color, cmykcolor, string, boolean, picture, and pen. The +only restriction is that you cannot give explicit numeric subscripts in +a variable declaration. Do not give the illegal declaration +$$ \hbox{\tt numeric q1, q2, q3;} $$ +use the generic subscript\index{subscript!generic} symbol +{\tt []}\index{arrays}\index{[]?\texttt{[]}!array} +instead, to declare the whole array: +$$ \hbox{\tt numeric q[];} $$ +You can also declare ``multidimensional'' arrays\index{arrays!multidimensional}. +After the declaration +$$ \hbox{\tt path p[]q[], pq[][];} $$ +{\tt p2q3} and {\tt pq1.4 5} are both paths. + +Internal\index{internal variables}\index{variables!internal} variables +like {\tt tracingonline} cannot be declared in the normal fashion. All +the internal variables discussed in this manual are predefined and do +not have to be declared at all, but there is a way to declare that a +variable should behave like a newly-created internal variable. The +declaration is {\tt + newinternal}\index{newinternal?\texttt{newinternal}}\label{Dnewint} +followed by an optional type specifier \texttt{numeric}\index{internal + variables!\texttt{numeric}}\index{variables!internal!\texttt{numeric}} +or \texttt{string}\index{internal + variables!\texttt{string}}\index{variables!internal!\texttt{string}} +and a list of symbolic tokens. For example, +$$\begin{verbatim} +newinternal numeric n, m; +newinternal string s, t; +newinternal num; +\end{verbatim} +$$ +are valid declarations that declare three internal numeric variables +\texttt{n}, \texttt{m}, and~\texttt{num} and two internal string +variables \texttt{s} and~\texttt{t}. + +Internal variables always have known values, and these values can only +be changed by using the assignment\index{assignment} operator +{\tt:=}\index{:=?\texttt{:=}}. Internal numeric variables are initially +zero and internal string variables are initially the empty +string~\verb|""|, except that the Plain\index{Plain macros} macro +package gives some of the variables different initial values. (The +Plain macros are normally preloaded automatically as explained in +Section~\ref{intro}.) + +Internal string variables have been introduced in MetaPost +version~1.200. For backwards compatibility, if the type specifier is +missing, internal variables default to a \texttt{numeric}\index{internal + variables!\texttt{numeric}}\index{variables!internal!\texttt{numeric}} +type, as in the last example. The declarations \texttt{newinternal + numeric;} and \texttt{newinternal string;} are invalid and throw an +error. + + +\section{Integrating Text and Graphics} +\label{text} + +MetaPost has a number of features for including labels and other +text\index{text and graphics} in the figures it generates. The simplest +way to do this is to use the {\tt +label}\index{label?\texttt{label}}\label{Dlabel} statement\index{label +suffix?\tdescr{label suffix}} +$$ {\tt label}\descr{label suffix} \hbox{\tt (} + \descr{string or picture expression} \hbox{\tt,}\, \descr{pair expression} + \hbox{\tt );} +$$ +The \tdescr{string or picture expression} gives the label and the +\tdescr{pair expression} says where to put it. The \tdescr{label +suffix} can be \tdescr{empty} in which case the label is just centered +on the given coordinates. If you are labeling some feature of a diagram +you probably want to offset the label slightly to avoid overlapping. +This is illustrated in Figure~\ref{fig16} where the {\tt "a"} label is +placed above the midpoint of the line it refers to and the {\tt "b"} +label is to the left of the midpoint of its line. This is achieved by +using {\tt label.top}\index{top?\texttt{top}} for the {\tt "a"} label +and {\tt label.lft}\index{lft?\texttt{lft}} for the {\tt "b"} label as +shown in the figure. The \tdescr{label suffix} specifies the position +of the label relative to the specified coordinates. The complete set of +possibilities is\index{rt?\texttt{rt}}\index{bot?\texttt{bot}}% +\index{ulft?\texttt{ulft}}\index{urt?\texttt{urt}}\index{llft?\texttt{llft}}\index{lrt?\texttt{lrt}} +$$ \tt \descr{label suffix} \rightarrow + \descr{empty} \;|\; lft \;|\; rt \;|\; top \;|\; bot \;|\; + ulft \;|\;urt \;|\; llft \;|\; lrt +$$ +where {\tt lft} and {\tt rt} mean left and right and {\tt llft}, {\tt +ulft}, etc.\ mean lower left, upper left, etc. The actual amount by +which the label is offset in whatever direction is determined by the +internal variable\index{internal variables}\index{variables!internal} +{\tt +labeloffset}\index{labeloffset?\texttt{labeloffset}}\label{Dlaboff}. + +\begin{figure}[htp] +$$ +\begin{verbatim} +beginfig(17); +a=.7in; b=.5in; +z0=(0,0); +z1=-z3=(a,0); +z2=-z4=(0,b); +draw z1..z2..z3..z4..cycle; +draw z1--z0--z2; +label.top("a", .5[z0,z1]); +label.lft("b", .5[z0,z2]); +dotlabel.bot("(0,0)", z0); +endfig; +\end{verbatim} +\qquad \mathcenter{\includegraphics{mpman-17.mps}} +$$ +\caption{MetaPost code and the resulting output} +\label{fig16} +\end{figure} + +Figure~\ref{fig16} also illustrates the +{\tt dotlabel}\index{dotlabel?\texttt{dotlabel}}\label{Ddotlab} +statement. This is effectively +like a {\tt label} statement followed by a statement drawing a dot at +the indicated coordinates. For example +$$ \hbox{\tt dotlabel.bot("(0,0)", z0)} $$ +places a dot at {\tt z0} and then puts the label ``(0,0)'' just below +the dot. The diameter of the dot drawn by the {\tt dotlabel} statement +is determined by the value of the internal variable {\tt + dotlabeldiam}\index{dotlabeldiam?\texttt{dotlabeldiam}}\label{Ddotlabdiam}. +Default value is 3bp. + +Another alternative is the macro +{\tt thelabel}\index{thelabel?\texttt{thelabel}}\label{Dthelab}. This has +the same syntax as the {\tt label} and {\tt dotlabel} statements except that it +returns the label as a \tdescr{picture primary} instead of actually drawing it. +Thus +$$ \hbox{\tt label.bot("(0,0)", z0)} $$ +is equivalent to +$$ \hbox{\tt draw thelabel.bot("(0,0)", z0)} $$ + +For simple applications of labeled figures, you can normally get by with +just {\tt label} and {\tt dotlabel}. In fact, you may be able to use a +short form of the {\tt dotlabel} statement that saves a lot of typing +when you have many points {\tt z0}, {\tt z1}, {\tt z.a}, {\tt z.b}, +etc.\ and you want to use the {\tt z} suffixes as labels. The +statement\index{dotlabels?\texttt{dotlabels}}\label{Ddotlbs} +$$ \hbox{\tt dotlabels.rt(0, 1, a);} $$ +is equivalent to +$$ \hbox{\tt dotlabel.rt("0",z0); dotlabel.rt("1",z1); dotlabel.rt("a",z.a);} $$ +Thus the argument to {\tt dotlabels} is a list of suffixes for which {\tt z} +variables are known, and the \tdescr{label suffix} given with {\tt dotlabels} +is used to position all the labels. + +There is also a {\tt +labels}\index{labels?\texttt{labels}}\label{Dlabels} statement that is +analogous to {\tt dotlabels} but its use is discouraged because it +presents compatibility problems with \MF\index{metafont?\MF}. Some +versions of the preloaded Plain\index{Plain macros} macro package define +{\tt labels} to be synonymous with {\tt dotlabels}. + +For labeling statements such as {\tt label} and {\tt dotlabel} that use +a string expression for the label text, the string gets typeset in a +default font as determined by the string variable {\tt +defaultfont}\index{defaultfont?\texttt{defaultfont}}\label{Ddffont}. +The initial value of {\tt defaultfont} is likely to be {\tt "cmr10"}, +but it can be changed to a different font name by giving an assignment +such as +$$ \hbox{\tt defaultfont:="ptmr8r"} $$ +\ttt{ptmr8r} is a typical way to refer to the Times-Roman font in \TeX. +The discussion of font names on p.\ \pageref{fontname} explains further. + +There is also a numeric quantity called +{\tt defaultscale}\index{defaultscale?\texttt{defaultscale}}\label{Ddfscale} +that determines the type size. +When {\tt default\-scale} is 1, you get the ``normal size'' which is +usually 10 point, but this can also be changed. For instance +$$ \hbox{\tt defaultscale := 1.2} $$ +makes labels come out twenty percent larger. If you do not know the +normal size and you want to be sure the text comes out at some specific +size, say 12 points, you can use the {\tt +fontsize}\index{fontsize?\texttt{fontsize}}\label{Dfntsiz} operator to +determine the normal size: e.g., +$$ \hbox{\tt defaultscale := 12pt/fontsize defaultfont;} $$ + +\label{fontname} +When you change {\tt defaultfont}, the new font name should be something +that \TeX\ would understand since MetaPost gets height and width +information by reading a {\tt tfm}\index{tfm file?{\tt tfm} +file}\index{files!tfm?{\tt tfm}} file. (This is explained in {\sl The +\TeX book\/} \cite{kn:a}.) It should be possible to use built-in +PostScript\index{PostScript!fonts} fonts, but the names for +them are system-dependent. Some typical ones are {\tt ptmr8r} for +Times-Roman\index{Times-Roman}, \ttt{pplr8r} for Palatino\index{Palatino}, +and \ttt{phvr} for Helvetica\index{Helvetica}. The Fontname document, +available at \url{http://tug.org/fontname}, has much more information +about font names and \TeX. A \TeX\index{TeX?\TeX!fonts} font such +as {\tt cmr10} is a little dangerous because it does not have a space +character or certain ASCII symbols. + +MetaPost does not use the ligatures\index{ligatures} and +kerning\index{kerning} information that comes with a \TeX\ font. +Further, MetaPost itself does not interpret virtual fonts. + + +\subsection{Typesetting Your Labels} + +\label{Dbtex} +\index{labels, typesetting} + +\TeX\index{TeX?\TeX} may be used to format complex labels. +If you say\index{btex?\texttt{btex}}\index{etex?\texttt{etex}} +$$ {\tt btex}\, \descr{typesetting commands}\, {\tt etex} $$ +in a MetaPost input file, the \tdescr{typesetting commands} get processed by +\TeX\ and translated into a picture expression +(actually a \tdescr{picture primary}) that can be used in a {\tt label} +or {\tt dotlabel} statement. Any spaces after {\tt btex} or before {\tt etex} +are ignored. For instance, the statement +$$ \hbox{\verb|label.lrt(btex $\sqrt x$ etex, (3,sqrt 3)*u)|} $$ +in Figure~\ref{fig17} places the label $\sqrt x$ at the lower right of the +point {\tt (3,sqrt 3)*u}. + +\begin{figure}[htp] +$$ +\begin{verbatim} +beginfig(18); +numeric u; +u = 1cm; +draw (0,2u)--(0,0)--(4u,0); +pickup pencircle scaled 1pt; +draw (0,0){up} + for i=1 upto 8: ..(i/2,sqrt(i/2))*u endfor; +label.lrt(btex $\sqrt x$ etex, (3,sqrt 3)*u); +label.bot(btex $x$ etex, (2u,0)); +label.lft(btex $y$ etex, (0,u)); +endfig; +\end{verbatim} +\qquad \mathcenter{\includegraphics{mpman-18.mps}} +$$ +\caption{Arbitrary \TeX\ as labels} +\label{fig17} +\end{figure} + +Figure~\ref{fig18} illustrates some of the more complicated things that can +be done with labels. Since the result of {\tt btex} \ldots {\tt etex} is +a picture, it can be operated on like a picture. In particular, it is possible +to apply transformations to pictures. We have not discussed the syntax for +this yet, but a \tdescr{picture secondary} +can be\index{rotated text}\index{rotated?\texttt{rotated}} +$$ \descr{picture secondary}\, {\tt rotated}\, \descr{numeric primary} $$ +This is used in Figure~\ref{fig18} to rotate the label ``$y$ axis'' so that +it runs vertically. + +\begin{figure}[htp] +$$ +\begin{verbatim} +beginfig(19); +numeric ux, uy; +120ux=1.2in; 4uy=2.4in; +draw (0,4uy)--(0,0)--(120ux,0); +pickup pencircle scaled 1pt; +draw (0,uy){right} + for ix=1 upto 8: + ..(15ix*ux, uy*2/(1+cosd 15ix)) + endfor; +label.bot(btex $x$ axis etex, (60ux,0)); +label.lft(btex $y$ axis etex rotated 90, + (0,2uy)); +label.lft( + btex $\displaystyle y={2\over1+\cos x}$ etex, + (120ux, 4uy)); +endfig; +\end{verbatim} +\qquad \mathcenter{\includegraphics{mpman-19.mps}} +$$ +\caption{\TeX\ labels with display math, and rotated by MetaPost} +\label{fig18} +\end{figure} + +Another complication in Figure~\ref{fig18} is the use of the displayed equation +$$y={2\over 1+\cos x}$$ +as a label. It would be more natural to code this as +$$ \hbox{\verb|$$y={2\over 1+\cos x}$$|} $$ +but this would not work because +\TeX\ typesets the labels in ``horizontal mode.'' + +For a way to typeset \emph{variable} text as labels, see the +\texttt{TEX} utility routine described on p.\ \pageref{dTEX}. + +Here is how \TeX\ material gets translated into a form MetaPost +understands: MetaPost stores all {\tt btex}\index{btex?\texttt{btex}} +\ldots\ {\tt etex}\index{etex?\texttt{etex}} blocks in a temporary +file and then runs \TeX\ on that file. If the environment variable +\ttindex{MPTEXPRE} is set to the name of an existing file, its content +will be prepended to the output file for processing by \TeX. You can +use this to include \LaTeX\ preambles, for instance. The \ttt{TEX} +macro described on p.\ \pageref{dTEX} provides another way to handle +this. + +Once the \TeX\ run is finished, MetaPost translates the resulting +DVI\index{dvi file?{\tt dvi} file}\index{files!dvi?{\tt dvi}} file into +low level MetaPost commands that are then read instead of the {\tt btex} +\ldots\ {\tt etex} blocks. If the main file is {\tt fig.mp}, the +translated \TeX\ material is placed in a file named {\tt + fig.mpx}\index{mpx file?{\tt mpx} file}\index{files!mpx?{\tt mpx}}. + +The conversion normally runs silently without any user intervention but +it could fail, for instance if one of the {\tt btex} \ldots {\tt etex} +blocks contains an erroneous \TeX\index{TeX?\TeX!errors} command. In +that case, the \TeX\ input is saved in the file {\tt + mpxerr.tex}\index{mpxerr.tex?\texttt{mpxerr.tex}} and the \TeX\ error +messages appear in {\tt + mpxerr.log}\index{mpxerr.log?\texttt{mpxerr.log}}\index{log file?{\tt + log} file}\index{files!log?{\tt log}}. + +The DVI to MetaPost conversion route {\it does\/} understand virtual +fonts, so you can use your normal \TeX\ font switching commands inside +the label. + + +\label{Dmakempx} +In MetaPost versions before 1.100, the \TeX\ label preprocessing was +handled by an external program that was called upon automatically by +MetaPost. On Web2C-based systems, the preprocessor was normally named +\ttindex{makempx}, which called the utility \ttindex{mpto} for the +creation of the \TeX\ input file and the utility \texttt{dvitomp}\index{dvitomp?\texttt{dvitomp}} for +the conversion to low level MetaPost. In the current MetaPost version, +the work of this program is now done internally. However, if the +environment variable \ttindex{MPXCOMMAND} is set, the whole label +conversion mechanism will be delegated to the command given in that +variable. + + +\label{Dverbatimtex} +\TeX\ macro definitions or any other auxiliary \TeX\ commands can be +enclosed in a {\tt verbatimtex}\index{verbatimtex?\texttt{verbatimtex}} +\ldots\ {\tt etex}\index{etex?\texttt{etex}} block. The difference +between {\tt btex} and {\tt verbatimtex} is that the former generates a +picture expression while the latter only adds material for \TeX\ to +process. For instance, if you want \TeX\ to typeset labels using macros +defined in {\tt mymac.tex}, your MetaPost input file would look +something like this: +\begin{eqnarray*} +&& \verb|verbatimtex \input mymac etex|\\ +&& \verb|beginfig(1);|\\ +&& \qquad \dots\\ +&& \verb|label(btex|\, \descr{\TeX\ material using \hbox{\tt mymac.tex}}\, + \verb|etex, | \descr{some coordinates} \hbox{\tt );}\\ +&& \qquad \dots +\end{eqnarray*} + +\label{Dtroffmode} +On Unix\footnote{Unix is a registered trademark of Unix Systems +Laboratories.}\index{Unix} and other Web2C-based systems, the +option {\tt -troff} to MetaPost tells the preprocessor that {\tt btex} +$\ldots$ {\tt etex} and {\tt verbatimtex} $\ldots$ {\tt etex} blocks +are in troff\index{troff} instead of \TeX. When using this option, +MetaPost sets the internal variable +\ttindex{troffmode} to~1\index{prologues?\texttt{prologues}}. + +\label{Dprologues} +Setting \ttt{prologues} can be useful with \TeX, too, not just troff. +Here is some explanation: + +\begin{itemize} +\item In PostScript output mode, when \ttt{prologues} is 0, which is the default, the MetaPost +output files do not have embedded fonts. Fonts in the resulting +output will probably render as Courier\index{Courier} or +Times-Roman\index{Times-Roman}. + +In SVG mode, the text will probably render in a generic sans serif font. +There may very well be problems with the encoding of non-ASCII characters: +the font model of SVG is totally different from the model used by MetaPost. + +\item In PostScript output mode, when \ttt{prologues} is 1, the MetaPost output claims to be +``structured PostScript''\index{PostScript!structured} (EPSF\index{EPSF}), +but it is not completely conformant. This variant is kept for backward +compatibility with old (troff) documents, but its use is deprecated. +MetaPost sets \ttt{prologues} to~1 when the {\tt -troff} option is given +on the command line. + +A \ttt{prologues:=1} setting is currently ignored in SVG output +mode. The value is reserved for future use (possibly for mapping to +\ttt{font-family}, \ttt{font-weight}, etc. properties). + +\item In PostScript output mode, when \ttt{prologues} is 2, the +MetaPost output is EPSF and assumes +that the text comes from PostScript\index{PostScript!fonts} fonts +provided by the ``environment'', such as the document viewer or +embedded application using the output. MetaPost will attempt to +set up the font encodings correctly, based on \ttt{fontmapfile} and +\ttt{fontmapline} commands. + +A \ttt{prologues:=2} setting is currently ignored in SVG output mode. +The value is reserved for future use (possibly for external +\ttt{font-face} definitions). + +\item In PostScript output mode, when \ttt{prologues} is 3, the MetaPost output will be EPSF but +will contain the PostScript font(s) (or a subset) used based on the +\ttt{fontmapfile} and \ttt{fontmapline} commands. This value is useful +for generating stand-alone PostScript graphics. + +In SVG mode, the font glyphs are converted to path definitions that +are included at the top of the output file. + +\end{itemize} + +The correct setting for variable \texttt{prologues} depends on how +MetaPost graphics are post-processed. Here are recommendations for some +popular use-cases: + +\begin{description} + +\item[\normalfont\itshape Previewing:] Section~\ref{preview} discusses + previewing PostScript output. + +\item[\normalfont\itshape \TeX\ and dvips:] When including PostScript + figures into a \TeX\ document that is processed by \TeX\ and a DVI + output processer, e.g., dvips\index{dvips}, variable + \texttt{prologues} should \emph{not} be set to the value~1, unless the + used fonts are known to be resident in the PostScript interpreter. + Make sure that variable \texttt{prologues} is set to either~0 (font + inclusion handled by dvips, but without re-encoding support), 2 (font + inclusion by dvips, with font re-encoding if necessary), or~3 (font + inclusion and re-encoding by MetaPost). Value~3 is safest, but may + result in slightly larger output. + +\item[\normalfont\itshape pdf\TeX:] When generating PDF files with + pdf\TeX\ (and the mptopdf\index{mptopdf} bundle), variable + \texttt{prologues} is not relevant. + +\item[\normalfont\itshape PostScript in external applications:] Some + text\index{text processor} processors or graphics applications can + directly import EPSF files, while for others MetaPost's PostScript + output has to be converted to a different vector or even a bitmap + format first. In any case, as soon as PostScript graphics generated + by MetaPost are leaving the \TeX\ ecosystem, variable + \texttt{prologues} should be set to~3, so that all needed fonts are + embedded (as a subset). + +\item[\normalfont\itshape SVG output:] Converting font glyphs to paths + by setting variable \texttt{prologues} to~3 is currently the only + reliable way to export text objects to SVG. + +\item[\normalfont\itshape PNG output:] Variable \texttt{prologues} has + no effect in PNG output mode. + +\end{description} + +It is worth noting that the value of \ttt{prologues} has no effect on +\MF\ fonts in your MetaPost files, i.\,e., MetaPost never embeds such +fonts. Only output drivers, e.\,g., \ttt{dvips} or pdf\LaTeX\ will +handle those. + +The details on how to include PostScript figures in a paper +done in \TeX\ or troff are system-dependent. They can generally be found +in manual pages and other on-line documentation, but have a look at +section~\ref{mpimport} of this manual for some brief instructions that +in many cases should work. The manual for the +widely-used Dvips processor is in a file \ttt{dvips.texi}, included in +most distributions, and is available online at +\url{http://tug.org/texinfohtml/dvips.html}, among many other places and +formats. + +\subsection{Font Map Files} +\label{fontmap} + +If \ttt{prologues} is set to~2, any used fonts in the output file are +automatically re-encoded, and the encoding vector file specified in +the fontmap entry will be embedded in the output file. If +\ttt{prologues} is set to~3, MetaPost will also attempt to include +(a subset of) the used PostScript\index{PostScript!fonts} fonts. For +this to work, it needs to acquire font map information. + +The code is based on the font library used by pdf\TeX. Following in the +footsteps of pdf\TeX, there are two new associated primitives: +\ttindex{fontmapfile}\label{Dfontmapfile} and +\ttindex{fontmapline}\label{Dfontmapline}. Here is a simple example, +specifying the map file for Latin Modern fonts in YandY (\LaTeX\ LY1) +encoding: +\begin{center}\begin{tabular}{l} +\verb|prologues:=2;|\\ +\verb|fontmapfile "texnansi-lm.map";|\\ +\verb|beginfig(1);|\\ +\verb| draw "Helló, világ" infont "texnansi-lmr10";|\\ +\verb|endfig;| +\end{tabular}\end{center} + +Using \ttt{fontmapline}, you can specify font mapping information +inside the figure: +\begin{center}\begin{tabular}{l} +\verb|prologues:=2;|\\ +\verb|fontmapline "pplbo8r URWPalladioL-Bold "&ditto&|\\ +\verb| ".167 SlantFont"&ditto&" <8r.enc > (4.9813,6.8078)|'' while +$$ \hbox{\verb|truecorners:=1; show urcorner btex $\bullet$\rlap{ A} etex|} $$ +produces ``\verb|>> (15.7742,6.8078)|.'' + + +\section{Advanced Graphics} +\label{adv.gr} + +All the examples in the previous sections have been simple line drawings +with labels added. This section describes shading and tools for +generating not-so-simple line drawings. Shading is done with the {\tt +fill}\index{fill?\texttt{fill}}\label{Dfill} statement. In its simplest +form, the {\tt fill} statement requires a \tdescr{path expression} that +gives the boundary of the region to be filled. In the syntax +$$ {\tt fill}\, \descr{path expression} $$ +the argument should be a cyclic path, i.e., a path that describes a +closed curve via the \verb|..cycle| or \verb|--cycle| notation. For +example, the {\tt fill} statement in Figure~\ref{fig20} builds a closed +path by extending the roughly semicircular path~{\tt p}. This path has +a counter-clockwise orientation, but that does not matter because the +{\tt fill} statement uses PostScript's\index{PostScript} non-zero +winding\index{winding number} number rule\index{non-zero fill + rule}\index{fill rule!non-zero}\index{PostScript!fill + rule}~\cite{ad:red2}. + +\begin{figure}[htp] +$$ \begin{verbatim} +beginfig(21); +path p; +p = (-1cm,0)..(0,-1cm)..(1cm,0); +fill p{up}..(0,0){-1,-2}..{up}cycle; +draw p..(0,1cm)..cycle; +endfig; +\end{verbatim} +\qquad \mathcenter{\includegraphics{mpman-21.mps}} +$$ +\caption{MetaPost code and the corresponding output.} +\label{fig20} +\end{figure} + +The general {\tt fill} statement\index{withcolor?\texttt{withcolor}}\label{Dwithcolor} +$$ {\tt fill}\, \descr{path expression}\, + {\tt withcolor}\, \descr{color expression} +$$ +specifies a shade of gray or (if you have a color printer) some +rainbow color. The $\descr{color expression}$ can have five possible +values, mapping to four possible color models: + +$$ +\begin{tabular}{ll} +Actual input & Remapped meaning\\\hline +{\tt withcolor} $\descr{rgbcolor} c$ & withrgbcolor\index{withrgbcolor?\texttt{withrgbcolor}}\label{Dwithrgbcolor} $c$\\ +{\tt withcolor} $\descr{cmykcolor} c$ & withcmykcolor\index{withcmykcolor?\texttt{withcmykcolor}}\label{Dwithcmykcolor} $c$\\ +{\tt withcolor} $\descr{numeric} c$ & withgreyscale\index{withgreyscale?\texttt{withgreyscale}}\label{Dwithgreyscale} $c$\\ +{\tt withcolor} $\descr{false}$ & withoutcolor\index{withoutcolor?\texttt{withoutcolor}}\label{Dwithoutcolor} \\ +{\tt withcolor} $\descr{true}$ & $\descr{current default color model}$\\ +\end{tabular} +$$ + +For the specific color models, there are also: +$$ {\tt fill}\, \descr{path expression}\, + {\tt withrgbcolor}\, \descr{rgbcolor expression} +$$ +$$ {\tt fill}\, \descr{path expression}\, + {\tt withcmykcolor}\, \descr{cmykcolor expression} +$$ +$$ {\tt fill}\, \descr{path expression}\, + {\tt withgreyscale}\, \descr{numeric} +$$ +$$ {\tt fill}\, \descr{path expression}\, + {\tt withoutcolor} +$$ + +An image object cannot have more then one color model, the last +\ttt{withcolor}, \ttt{withrgbcolor}, \ttt{withcmykcolor}, +\ttt{withgreyscale} or \ttt{withoutcolor} specification sets the color +model for any particular object. + +The model \ttt{withoutcolor} needs a bit more explanation: selecting +this model means that MetaPost will not write a color selection +statement to the PostScript output file for this object. + +The `current default' color model can be set up using the internal +variable \ttindex{defaultcolormodel}\label{Ddefaultcolormodel}. +Table~\ref{dfltcmod} lists the valid values. +\begin{table} +\centering +\begin{tabular}{|c|l|} +\hline +Value & Color model\\\hline +1 & no model\\ +3 & greyscale\\ +5 & rgb (default)\\ +7 & cmyk\\ +\hline +\end{tabular} +\caption{Supported color models.} +\label{dfltcmod} +\end{table} + + +Figure~\ref{fig21} illustrates several applications of the fill command +to fill areas with shades of gray. The paths involved are intersecting +circles {\tt a} and {\tt b} and a path {\tt ab} that bounds the region +inside both circles. Circles {\tt a} and {\tt b} are derived from {\tt + fullcircle}. Path~{\tt ab} is then initialized using a predefined +macro {\tt buildcycle} that will be discussed shortly. + +\begin{figure}[htp] +$$ \begin{verbatim} +beginfig(22); +path a, b, aa, ab; +a = fullcircle scaled 2cm; +b = a shifted (0,1cm); +aa = halfcircle scaled 2cm; +ab = buildcycle(aa, b); +picture pa, pb; +pa = thelabel(btex $A$ etex, (0,-.5cm)); +pb = thelabel(btex $B$ etex, (0,1.5cm)); +fill a withcolor .7white; +fill b withcolor .7white; +fill ab withcolor .4white; +unfill bbox pa; +draw pa; +unfill bbox pb; +draw pb; +label.lft(btex $U$ etex, (-1cm,.5cm)); +draw bbox currentpicture; +endfig; +\end{verbatim} +\qquad \mathcenter{\includegraphics{mpman-22.mps}} +$$ +\caption{MetaPost code and the corresponding output.} +\index{fullcircle?\texttt{fullcircle}}\index{halfcircle?\texttt{halfcircle}}\index{buildcycle?\texttt{buildcycle}} +\label{fig21} +\end{figure} + +Filling circle {\tt a} with the light gray color {\tt .7white} and then +doing the same with circle {\tt b} doubly fills the region where the +disks overlap. The rule is that each {\tt fill} statement assigns the +given color to all points in the region covered, wiping out whatever was +there previously including lines and text as well as filled regions. +Thus it is important to give {\tt fill} commands in the right order. In +the above example, the overlap region gets the same color twice, leaving +it light gray after the first two {\tt fill} statements. The third fill +statement assigns the darker color {\tt .4white} to the overlap region. + +At this point the circles and the overlap region have their final colors +but there are no cutouts for the labels. The cutouts are achieved by +the {\tt unfill}\index{unfill?\texttt{unfill}}\label{Dunfill} statements +that effectively erase\index{erasing} the regions bounded by {\tt bbox +pa}\index{bbox?\texttt{bbox}} and {\tt bbox pb}. More precisely, {\tt +unfill} is shorthand for filling {\tt withcolor background}, where {\tt +background} is normally equal to {\tt white} as is appropriate for +printing on white paper. If necessary, you can assign a new color value +to {\tt +background}\index{background?\texttt{background}}\label{Dbground}. + +The labels need to be stored in pictures {\tt pa} and {\tt pb} to allow +for measuring their bounding box before actually drawing them. The +macro {\tt thelabel}\index{thelabel?\texttt{thelabel}} creates such +pictures and shifts them into position so that they are ready to draw. +Using the resulting pictures in {\tt draw} statements of the +form\index{draw?\texttt{draw}} +$$ {\tt draw}\, \descr{picture expression} $$ +adds them to {\tt currentpicture}\index{currentpicture?\texttt{currentpicture}} +so that they overwrite a portion of what has +already been drawn. In Figure~\ref{fig21} just the white rectangles produced by +{\tt unfill} get overwritten. + +\subsection{Building Cycles} +\label{buildcy} + +The {\tt buildcycle}\index{buildcycle?\texttt{buildcycle}} command +constructs paths for use with the {\tt fill} or {\tt unfill} macros. +When given two or more paths such as {\tt aa} and {\tt b}, the {\tt +buildcycle} macro tries to piece them together so as to form a cyclic +path. In this case path {\tt aa} is a semicircle that starts just to +the right of the intersection with path {\tt b}, then passes through +{\tt b} and ends just outside the circle on the left as shown in +Figure~\ref{fig22}a. + +Figure~\ref{fig22}b shows how {\tt buildcycle} forms a closed cycle from +the pieces of paths {\tt aa} and {\tt b}. The {\tt buildcycle} macro +detects the two intersections\index{intersections} labeled 1 and 2 in +Figure~\ref{fig22}b. Then it constructs the cyclic path shown in bold +in the figure by going forward along path {\tt aa} from intersection~1 +to intersection~2 and then forward around the counter-clockwise path +{\tt b} back to intersection~1. It turns out that {\tt buildcycle(a,b)} +would have produced the same result, but the reasoning behind this is a +little confusing. + + +\begin{figure}[htp] +$$ {\includegraphics{mpman-123.mps} \atop (a)} + \qquad {\includegraphics{mpman-223.mps} \atop (b)} +$$ +\caption[A demonstration of cycle building] + {(a)~The semicircular path~{\tt aa} + with a dashed line marking path {\tt b}; (b)~paths~{\tt aa} and {\tt b} + with the portions selected by {\tt buildcycle} shown by heavy lines.} +\label{fig22} +\end{figure} + +It is a easier to use the {\tt buildcycle} macro in situations like +Figure~\ref{fig23} where there are more than two path arguments and each +pair of consecutive paths has a unique intersection. For instance, the +line~{\tt q0.5} and the curve~{\tt p2} intersect only at point~$P$; and +the curve {\tt p2} and the line~{\tt q1.5} intersect only at point~$Q$. +In fact, each of the points $P$, $Q$, $R$, $S$ is a unique intersection, +and the result of\index{buildcycle?\texttt{buildcycle}} +$$ \hbox{\tt buildcycle(q0.5, p2, q1.5, p4)} $$ +takes {\tt q0.5} from $S$ to~$P$, then {\tt p2} from $P$ to~$Q$, then +{\tt q1.5} from $Q$ to~$R$, and finally {\tt p4} from $R$ back to~$S$. +An examination of the MetaPost code for Figure~\ref{fig23} reveals that +you have to go backwards along {\tt p2} in order to get from $P$ to~$Q$. +This works perfectly well as long as the +intersection\index{intersection} points are uniquely defined but it can +cause unexpected results when pairs of paths intersect more than once. + +\begin{figure}[htp] +$$ \begin{verbatim} +beginfig(24); +h=2in; w=2.7in; +path p[], q[], pp; +for i=2 upto 4: ii:=i**2; + p[i] = (w/ii,h){1,-ii}...(w/i,h/i)...(w,h/ii){ii,-1}; +endfor +q0.5 = (0,0)--(w,0.5h); +q1.5 = (0,0)--(w/1.5,h); +pp = buildcycle(q0.5, p2, q1.5, p4); +fill pp withcolor .7white; +z0=center pp; +picture lab; lab=thelabel(btex $f>0$ etex, z0); +unfill bbox lab; draw lab; +draw q0.5; draw p2; draw q1.5; draw p4; +dotlabel.top(btex $P$ etex, p2 intersectionpoint q0.5); +dotlabel.rt(btex $Q$ etex, p2 intersectionpoint q1.5); +dotlabel.lft(btex $R$ etex, p4 intersectionpoint q1.5); +dotlabel.bot(btex $S$ etex, p4 intersectionpoint q0.5); +endfig; +\end{verbatim} +\atop \mathcenter{\includegraphics{mpman-24.mps}} +$$ +\caption{MetaPost code and the corresponding output.} +\label{fig23} +\end{figure} + +The general rule for the {\tt buildcycle} macro is that +$$ \hbox{\tt buildcycle(}p_1\hbox{\tt,}\, p_2\hbox{\tt,}\, + p_3\hbox{\tt,}\, \ldots \hbox{\tt,} p_k \hbox{\tt )} +$$ +chooses the intersection between each $p_i$ and $p_{i+1}$ to be as late +as possible on $p_i$ and as early as possible on $p_{i+1}$. There is no +simple rule for resolving conflicts between these two goals, so you +should avoid cases where one intersection point occurs later on $p_i$ +and another intersection\index{intersection} point occurs earlier on +$p_{i+1}$. + +The preference for intersections as late as possible on $p_i$ and as +early as possible on $p_{i+1}$ leads to ambiguity resolution in favor of +forward-going subpaths. For cyclic paths such as path~{\tt b} in +Figure~\ref{fig22} ``early'' and ``late'' are relative to a start/finish +point which is where you get back to when you say ``{\tt ..cycle}''. +For the path~{\tt b}, this turns out to be the rightmost point on the +circle. + +A more direct way to deal with path intersections is via the +\tdescr{secondary binop}\index{secondary binop?\tdescr{secondary binop}} +{\tt +intersection\-point}\index{intersectionpoint?\texttt{intersectionpoint}}\label{Disecpt} +that finds the points $P$, $Q$, $R$, and~$S$ in Figure~\ref{fig23}. +This macro finds a point where two given paths intersect. If there is +more than one intersection point, it just chooses one; if there is no +intersection, the macro generates an error message. + +\subsection{Dealing with Paths Parametrically} + +The {\tt +intersectionpoint}\index{intersectionpoint?\texttt{intersectionpoint}} +macro is based on a primitive operation called {\tt +intersectiontimes}\index{intersectiontimes?\texttt{intersectiontimes}}\label{Disectt}. +This \tdescr{secondary binop} is one of several operations that deal +with paths parametrically. It locates an intersection between two paths +by giving the ``time'' parameter on each path. This refers to the +parameterization scheme from Section~\ref{curves} that described paths +as piecewise cubic curves $\bigl(X(t),Y(t)\bigr)$ where $t$ ranges from +zero to the number of curve segments. In other words, when a path is +specified as passing through a sequence of points, where $t=0$ at the +first point, then $t=1$ at the next, and $t=2$ at the next, etc. The +result of +$$ \hbox{\tt a intersectiontimes b} $$ +is $(-1,-1)$ if there is no intersection; otherwise you get +a pair $(t_a,t_b)$, where $t_a$ is a time on path {\tt a} when it intersects +path~{\tt b}, and $t_b$ is the corresponding time on path~{\tt b}. + +For example, suppose path~{\tt a} is denoted by the thin line in +Figure~\ref{fig24} and path~{\tt b} is denoted by the thicker line. If +the labels indicate time values on the paths, the pair of time values +computed by +$$ \hbox{\tt a intersectiontimes b} $$ +must be one of +$$ (0.25,1.77),\ (0.75,1.40), {\rm or}\ (2.58,0.24), $$ +depending on which of the three intersection points is chosen by the +MetaPost interpreter. The exact rules for choosing among multiple +intersection points are a little complicated, but it turns out that you +get the time values $(0.25,1.77)$ in this example. Smaller time values +are preferred over larger ones so that $(t_a,t_b)$ is preferred to +$(t'_a,t'_b)$ whenever $t_a> 0 +>> 0 +>> 1 +>> 0.3 +\end{verbatim} +$$ +since in grey scale color model black is {\tt 0} and in CMYK color model +black is {\tt (0,0,0,1)}. For the matching RGB color model the true +color component is returned. + +When {\tt clipped p} or {\tt bounded p} is true, {\tt pathpart p} gives the +clipping or {\tt setbounds} path and the other part extraction operators are +not meaningful. Such non-meaningful part extractions do not generate +errors. Instead, they return null values or black color (components): +the trivial path {\tt (0,0)} for {\tt pathpart}, +{\tt nullpen}\index{nullpen?\texttt{nullpen}}\label{Dnlpen} for {\tt penpart}, +an empty picture for {\tt dashpart}, +the null string for {\tt textpart} or {\tt fontpart}, +zero for {\tt colormodel}, +{\tt greypart}, +{\tt redpart}, {\tt greenpart}, {\tt bluepart}, +{\tt cyanpart}, {\tt magentapart}, {\tt yellowpart}, +one for {\tt blackpart}, and +black in the current default color model for {\tt colorpart}. + +To summarize the discussion of mismatching part operators: +\begin{enumerate} +\item Asking for non-meaningful parts of an item---such as the {\tt + redpart} of a clipping path, the {\tt textpart} of a stroked item, + or the {\tt pathpart} of a textual item---is silently accepted and + returns a null value or a black color (component). +\item Explicitly asking for a color part of a colored item in the wrong + color model returns a black color component. This operation triggers + an error. +\end{enumerate} + +\index{setbounds?\texttt{setbounds}|)} +\index{stroked?\texttt{stroked}|)} +\index{filled?\texttt{filled}|)} +\index{textual?\texttt{textual}|)} +\index{clipped?\texttt{clipped}|)} +\index{bounded?\texttt{bounded}|)} +\index{pathpart?\texttt{pathpart}|)} +\index{penpart?\texttt{penpart}|)} +\index{dashpart?\texttt{dashpart}|)} +\index{colormodel?\texttt{colormodel}|)} +\index{colorpart?\texttt{colorpart}|)} +\index{redpart?\texttt{redpart}|)} +\index{greenpart?\texttt{greenpart}|)} +\index{bluepart?\texttt{bluepart}|)} +\index{cyanpart?\texttt{cyanpart}|)} +\index{magentapart?\texttt{magentapart}|)} +\index{yellowpart?\texttt{yellowpart}|)} +\index{blackpart?\texttt{blackpart}|)} +\index{greypart?\texttt{greypart}|)} + + +\subsection{Decomposing the Glyphs of a Font} +\label{glyphs} + +MetaPost provides a primitive to convert a +glyph\index{glyph}\index{font!glyph} of a font in the Adobe Type~1 +Font\index{PostScript!fonts}\index{font!PostScript}\index{Adobe Type~1 + Font}\index{font!Adobe Type~1} format into its constituent filled +paths---the strokes---and store them in a picture variable. A glyph is +the visual representation of a character in a font. A +character\index{character}\index{font!character} is a certain +slot\index{slot}\index{font!slot} (index) in a font with an associated +meaning, e.g., the capital letter~``M'' or the exclamation mark. The +meaning of a slot is defined by the font +encoding\index{encoding}\index{font!encoding}. In general, the same +character is represented by different glyphs in different fonts. +Figure~\ref{glyphsample} shows some glyphs for the character at slot~103 +in the T1 encoding, i.e., the lower-case letter~``g''. All glyphs are +at the same nominal size. Note, how glyphs may extend beyond their +bounding box. +\begin{figure}[htp] + \centering + \setlength{\fboxsep}{0pt} + \setlength{\fboxrule}{.125pt} + \fontsize{56pt}{56pt}\selectfont + \newcommand*{\showglyph}[4]{% a glyph with its bounding box + \fbox{\usefont{#1}{#2}{#3}{#4}g}% + } + \makebox[0pt][c]{% base line + \rule{.7\textwidth}{.125pt}% + }% + \makebox[0pt][c]{% glyphs + \showglyph{T1}{lmr}{m}{n}\hspace{.3em} + \showglyph{T1}{qag}{m}{n}\hspace{.3em} + \showglyph{T1}{qpl}{m}{it}\hspace{.3em} + \showglyph{T1}{qzc}{m}{it}% + } + \caption{Different glyphs representing the same character.} + \label{glyphsample} +\end{figure} + +The glyphs of an Adobe Type~1 +font\index{PostScript!fonts}\index{font!PostScript}\index{Adobe Type~1 + Font}\index{font!Adobe Type~1} are composed of two types of contours: +Clockwise oriented contours add to the shape of a glyph and are filled +with black ink. Counter-clockwise oriented contours +erase\index{erasing} parts of other contours, i.e., make them +transparent again. To save the contours of a glyph in a picture, the +\verb|glyph|\index{glyph?\texttt{glyph}}\label{Dglyph} operator can be +used. There are two ways to identify a glyph in a font: +\begin{eqnarray*} + & \verb|glyph|\, \descr{numeric expression}\, \verb|of|\, + \descr{string expression}\\ + \noalign{\hbox{and}} + & \verb|glyph|\, \descr{string expression}\, \verb|of|\, + \descr{string expression}\rlap{\quad\mbox{.}} +\end{eqnarray*} + +If the first argument is a numeric expression, it has to be a slot +number between 0 and~255. Fractional slot numbers are rounded to the +nearest integer value. Slot numbers outside the allowed range trigger +an error. If the first argument is string, it has to be a CharString +name\index{CharString name} in the PostScript font's source file. A +CharString name is a unique text label for a glyph in a PostScript font +(a font encoding actually maps CharStrings to slots). This second +syntax can be used to address glyphs without having to think about font +encodings. The second argument to the \verb|glyph| operator is a string +containing a font name (section~\ref{text} has more on font names). + +The \verb|glyph| operator looks-up the font name in the font map to +determine the encoding and to find the font's PostScript source file. +It returns a picture consisting of the glyph's contour lines, explicitly +filled black and white in the greyscale color model according to the +rules laid out above. Additionally, the contours are sorted, such that +all black contours are drawn before white contours. The filling and +sorting is necessary for the picture to resembles the corresponding +glyph visually\footnote{Plain contours already carry enough information + to completely reconstruct a glyph, the orientation of a contour can be + computed from its cardinal and control points. MetaPost has a + \texttt{turningnumber}\index{turningnumber?\texttt{turningnumber}}\label{Dturningnumber} + primitive to do that.}, since Adobe Type~1 +fonts\index{PostScript!fonts}\index{font!PostScript}\index{Adobe Type~1 + Font}\index{font!Adobe Type~1} use a generalized variant of the +non-zero winding number fill rule\index{non-zero fill rule}\index{fill + rule!non-zero}\index{PostScript!fill rule}, which MetaPost doesn't +implement (MetaPost cannot handle non-contiguous paths). As a side +effect, the interiors of the erasing\index{erasing} contours are an +opaque white in the returned picture, while they were transparent in the +original glyph. One can think of erasing contours to be unfilled (see +p.~\pageref{Dunfill}). For instance, the following code saves the +contours of the lower case letter~``g'', bound to slot~103 in the OT1 +encoding\index{OT1 encoding}\index{encoding!OT1}, in the +Computer\index{Computer Modern Roman} Modern Roman font in a picture +variable: + +$$ +\begin{verbatim} +fontmapline "cmr10 CMR10 > 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> 2|.'' + +If the {\tt hide} macro were not predefined, it could be defined like this: +$$\begin{verbatim} +def ignore(expr a) = enddef; +def hide(text t) = ignore(begingroup t; 0 endgroup) enddef; +\end{verbatim} +$$ +The statements represented by the text parameter {\tt t} would be +evaluated as part of the group that forms the argument to {\tt ignore}. +Since {\tt ignore} has an empty \tdescr{replacement text}, expansion of +the {\tt hide} macro ultimately produces nothing. + +Another example of a predefined macro with a text parameter is {\tt +dashpattern}\index{dashpattern?\texttt{dashpattern}}. The definition of +{\tt dashpattern} starts +$$\begin{verbatim} +def dashpattern(text t) = + begingroup save on, off; +\end{verbatim} +$$ +then it defines {\tt on} and {\tt off} to be macros that create the desired +picture when the text parameter~{\tt t} appears in the replacement text. + +Text parameters are very general, but their generality sometimes gets in +the way. If you just want to pass a variable name to a macro, it is +better to declare it as a suffix parameter\index{parameter!suffix}. For +example,\index{incr?\texttt{incr}} +$$ \hbox{\verb|def incr(suffix $) = begingroup $:=$+1; $ endgroup enddef;|} $$ +defines a macro that will take any numeric variable, add one to it, and return +the new value. Since variable names can be more than one token long, +$$ \hbox{\tt incr(a3b)} $$ +is perfectly acceptable if {\tt a3b} is a numeric variable. Suffix +parameters are slightly more general than variable names because the +definition in Figure~\ref{syvar} allows a +\tdescr{suffix}\index{suffix?\tdescr{suffix}} to start with a +\tdescr{subscript}\index{subscript?\tdescr{subscript}}. + +Figure~\ref{fig45} shows how suffix and expr parameters can be used +together. The {\tt getmid}\index{getmid?\texttt{getmid}} macro takes a +path variable and creates arrays of points and directions whose names +are obtained by appending {\tt mid}, {\tt off}, and {\tt dir} to the +path variable. The {\tt joinup}\index{joinup?\texttt{joinup}} macro +takes arrays of points and directions and creates a path of length {\tt +n} that passes through each {\tt pt[i]} with direction {\tt d[i]} or +$-\hbox{\tt d[i]}$. + +\begin{figure}[htp] +$$\begin{verbatim} +def getmid(suffix p) = + pair p.mid[], p.off[], p.dir[]; + for i=0 upto 36: + p.dir[i] = dir(5*i); + p.mid[i]+p.off[i] = directionpoint p.dir[i] of p; + p.mid[i]-p.off[i] = directionpoint -p.dir[i] of p; + endfor +enddef; + +def joinup(suffix pt, d)(expr n) = + begingroup + save res, g; path res; + res = pt[0]{d[0]}; + for i=1 upto n: + g:= if (pt[i]-pt[i-1]) dotprod d[i] <0: - fi 1; + res := res{g*d[i-1]}...{g*d[i]}pt[i]; + endfor + res + endgroup +enddef; + +beginfig(45) +path p, q; +p = ((5,2)...(3,4)...(1,3)...(-2,-3)...(0,-5)...(3,-4) + ...(5,-3)...cycle) scaled .3cm shifted (0,5cm); +getmid(p); +draw p; +draw joinup(p.mid, p.dir, 36)..cycle; +q = joinup(p.off, p.dir, 36); +draw q..(q rotated 180)..cycle; +drawoptions(dashed evenly); +for i=0 upto 3: + draw p.mid[9i]-p.off[9i]..p.mid[9i]+p.off[9i]; + draw -p.off[9i]..p.off[9i]; +endfor +endfig; +\end{verbatim} +\quad \mathcenter{\includegraphics{mpman-45.mps}} +$$ +\caption{MetaPost code and the corresponding figure} +\label{fig45} +\end{figure} + +A definition that starts +$$ \hbox{\tt def joinup(suffix pt, d)(expr n) =} $$ +might suggest that calls to the {\tt joinup} macro should have two sets of +parentheses as in +$$ \hbox{\tt joinup(p.mid, p.dir)(36)} $$ +instead of +$$ \hbox{\tt joinup(p.mid, p.dir, 36)} $$ +In fact, both forms are acceptable. Parameters in a macro call can be +separated by commas or by {\tt )(} pairs. The only restriction is that +a text parameter\index{parameter!text} must be followed by a right +parenthesis. For instance, a macro {\tt foo} with one text parameter +and one expr parameter can be called +$$ \hbox{\tt foo(a,b)(c)} $$ +in which case the text parameter is ``{\tt a,b}'' and the expr parameter is +{\tt c}, but +$$ \hbox{\tt foo(a,b,c)} $$ +sets the text parameter to ``{\tt a,b,c}'' and leaves the MetaPost interpreter +still looking for the expr parameter. + + +\subsection{Vardef Macros} + +A macro definition can begin with {\tt +vardef}\index{vardef?\texttt{vardef}} instead of {\tt def}. Macros +defined in this way are called vardef macros. They are particularly +well-suited to applications where macros are being used like functions +or subroutines. The main idea is that a vardef macro is like a variable +of type ``macro.'' + +Instead of {\tt def} \tdescr{symbolic token}, a vardef macro begins +$$ {\tt vardef}\, \descr{generic variable} $$ +where a \tdescr{generic variable}\index{generic variable?\tdescr{generic +variable}} is a variable name with numeric subscripts replaced by the +generic subscript\index{subscript!generic} symbol {\tt +[]}\index{[]?\texttt{[]}!vardef macro?\texttt{vardef} macro}. In other +words, the name following {\tt +vardef} obeys exactly the same syntax as the name given in a variable +declaration. It is a sequence of tags and generic subscript symbols +starting with a tag, where a tag\index{tags} is a symbolic token that is +not a macro or a primitive operator as explained in +Section~\ref{vardecl}. + +The simplest case is when the name of a vardef macro consists of a +single tag. Under such circumstances, {\tt def} and {\tt vardef} +provide roughly the same functionality. The most obvious difference is +that {\tt begingroup}\index{begingroup?\texttt{begingroup}} and {\tt +endgroup}\index{endgroup?\texttt{endgroup}} are automatically inserted +at the beginning and end of the \tdescr{replacement text} of every +vardef macro. This makes the \tdescr{replacement text} a group so that +a vardef macro behaves like a subroutine or a function call. + +Another property of vardef macros is that they allow multi-token macro +names and macro names involving generic subscripts. When a vardef macro +name has generic subscripts, numeric values have to be given when the +macro is called. After a macro definition +$$ \hbox{\tt vardef a[]b(expr p) =}\, \descr{replacement text}\, + \hbox{\tt enddef;} +$$ +{\tt a2b((1,2))} and {\tt a3b((1,2)..(3,4))} are macro calls. But how +can the \tdescr{replacement text} tell the difference between {\tt a2b} +and {\tt a3b}? Two implicit suffix parameters\index{parameter!suffix} +are automatically provided for this purpose. Every vardef macro has +suffix parameters \verb|#@|\index{#@?\texttt{\#@}} and +\verb|@|\index{@?\texttt{@}}, where \verb|@| is the last token in the +name from the macro call and \verb|#@| is everything preceding the last +token. Thus \verb|#@| is {\tt a2} when the name is given as {\tt a2b} +and {\tt a3} when the name is given as {\tt a3b}. + +Suppose, for example, that the {\tt a[]b} macro is to take its argument +and shift it by an amount that depends on the macro name. The macro +could be defined like this: +$$ \hbox{\verb|vardef a[]b(expr p) = p shifted (#@,b) enddef;|} $$ +Then {\tt a2b((1,2))} means {\tt (1,2) shifted (a2,b)} +and {\tt a3b((1,2)..(3,4))} means +$$ \hbox{\tt ((1,2)..(3,4)) shifted (a3,b)}. $$ + +If the macro had been {\tt a.b[]}, \verb|#@| would always be {\tt a.b} +and the \verb|@| parameter would give the numeric subscript. Then {\tt +a@} would refer to an element of the array {\tt a[]}. Note that +\verb|@| is a suffix parameter, not an expr parameter, so an expression +like {\tt @+1} would be illegal. The only way to get at the numeric +values of subscripts in a suffix parameter\index{parameter!suffix} is by +extracting them from the string returned by the {\tt +str}\index{str?\texttt{str}}\label{Dstr} operator. This operator takes +a suffix and returns a string representation of a suffix. Thus {\tt str +@} would be \verb|"3"| in {\tt a.b3} and \verb|"3.14"| in {\tt a.b3.14} +or {\tt a.b[3.14]}. Since the syntax for a +\tdescr{suffix}\index{suffix?\tdescr{suffix}} in Figure~\ref{syvar} +requires negative subscripts to be in brackets, {\tt str @} returns {\tt +"[-3]"} in {\tt a.b[-3]}. + +The {\tt str} operator is generally for emergency use only. It is +better to use suffix parameters only as variable names or suffixes. The +best example of a vardef macro involving suffixes is the {\tt z} macro +that defines the {\tt z} convention\index{z convention?{\tt z} +convention}. The definition involves a special token +\verb|@#|\index{@#?\texttt{@\#}} that refers to the suffix following the +macro name: +$$ \hbox{\verb|vardef z@#=(x@#,y@#) enddef;|} $$ +This means that any variable name whose first token is {\tt z} is +equivalent to a pair of variables whose names are obtained by replacing +{\tt z} with {\tt x} and~{\tt y}. For instance, {\tt z.a1} calls the +{\tt z} macro with the suffix parameter \verb|@#| set to {\tt a1}. + +In general, +$$ {\tt vardef}\, \descr{generic variable} \hbox{\verb|@#|} $$ +is an alternative to {\tt vardef} \tdescr{generic variable} that causes the +MetaPost interpreter +to look for a suffix following the name given in the macro call and makes this +available as the \verb|@#| suffix parameter. + +To summarize the special features of vardef macros, they allow a broad +class of macro names as well as macro names followed by a special suffix +parameter. Furthermore, {\tt begingroup} and {\tt endgroup} are +automatically added to the \tdescr{replacement text} of a vardef macro. +Thus using {\tt vardef} instead of {\tt def} to define the {\tt +joinup}\index{joinup?\texttt{joinup}} macro in Figure~\ref{fig45} would +have avoided the need to include {\tt begingroup} and {\tt endgroup} +explicitly in the macro definition. + +In fact, most of the macro definitions given in previous examples could +equally well use {\tt vardef} instead of {\tt def}. It usually does not +matter very much which you use, but a good general rule is to use {\tt +vardef} if you intend the macro to be used like a function or a +subroutine. The following comparison should help in deciding when to +use {\tt vardef}. + +\begin{itemize} +\item Vardef macros are automatically surrounded by {\tt begingroup} +and {\tt endgroup}. +\item The name of a vardef macro can be more than one token long and it can +contain subscripts. +\item A vardef macro can have access to the suffix that follows the macro name +when the macro is called. +\item When a symbolic token is used in the name of a vardef macro it remains +a tag\index{tags} and can still be used in other variable names. Thus +{\tt p5dir} is a legal variable name even though {\tt dir} is a vardef +macro, but an ordinary macro such as {\tt ...}\index{...?\texttt{...}} +cannot be used in a variable name. (This is fortunate since {\tt +z5...z6} is supposed to be a path expression, not an elaborate variable +name). +\end{itemize} + + +\subsection{Defining Unary and Binary Macros} + +It has been mentioned several times that some of the operators and +commands discussed so far are actually predefined macros. These include +unary operators such as {\tt round}\index{round?\texttt{round}} and {\tt +unitvector}\index{unitvector?\texttt{unitvector}}, statements such as +{\tt fill}\index{fill?\texttt{fill}} and {\tt +draw}\index{draw?\texttt{draw}}, and binary operators such as {\tt +dotprod}\index{dotprod?\texttt{dotprod}} and {\tt +intersectionpoint}\index{intersectionpoint?\texttt{intersectionpoint}}. +The main difference between these macros and the ones we already know +how to define is their argument syntax. + +The {\tt round} and {\tt unitvector} macros are examples of what +Figure~\ref{syexpr} calls \tdescr{unary op}. That is, they are followed +by a primary expression. To specify a macro argument of this type, the +macro definition should look like this: +$$ \hbox{\tt vardef round primary u =}\, \descr{replacement text}\, + \hbox{\tt enddef;} +$$ +The {\tt u} parameter is an expr parameter\index{parameter!expr} and it can be +used exactly like the expr parameter defined using the ordinary +$$ \hbox{\tt (expr u)} $$ +syntax. + +As the {\tt round} example suggests, a macro can be defined to take a +\tdescr{secondary}\index{secondary?\tdescr{secondary}}, +\tdescr{tertiary}\index{tertiary?\tdescr{tertiary}}, or an +\tdescr{expression}\index{expression?\tdescr{expression}} parameter. +For example, the predefined definition of the {\tt fill} macro is +roughly\index{fill?\texttt{fill}} +$$ \hbox{\tt def fill expr c = addto currentpicture contour c enddef;} $$ + +It is even possible to define a macro to play the role of \tdescr{of +operator}\index{of operator?\tdescr{of operator}} in +Figure~\ref{syexpr}. For example, the {\tt direction +of}\index{direction of?\texttt{direction of}} macro has a definition of +this form: +$$ \hbox{\tt vardef direction expr t of p =}\, \descr{replacement text}\, + \hbox{\tt enddef;} +$$ + +Macros can also be defined to behave like binary operators. For instance, the +definition of the {\tt dotprod} macro has the +form\index{dotprod?\texttt{dotprod}}\index{primarydef?\texttt{primarydef}} +$$ \hbox{\tt primarydef w dotprod z =}\, \descr{replacement text}\, + \hbox{\tt enddef;} +$$ +This makes {\tt dotprod} a \tdescr{primary binop}\index{primary +binop?\tdescr{primary binop}}. Similarly, {\tt +secondarydef}\index{secondarydef?\texttt{secondarydef}} and {\tt +tertiarydef}\index{tertiarydef?\texttt{tertiarydef}} introduce +\tdescr{secondary binop}\index{secondary binop?\tdescr{secondary binop}} +and \tdescr{tertiary binop}\index{tertiary binop?\tdescr{tertiary +binop}} definitions. These all define ordinary macros, not vardef +macros; e.g., there is no ``{\tt primaryvardef}.'' + +Thus macro definitions can be introduced by {\tt def}, {\tt vardef}, +{\tt primarydef}, {\tt secondarydef}, or {\tt tertiarydef}. A +\tdescr{replacement text}\index{replacement text?\tdescr{replacement +text}} is any list of tokens that is balanced with respect to {\tt +def}-{\tt enddef} pairs where all five macro definition tokens are +treated like {\tt def} for the purpose of {\tt def}-{\tt enddef} +matching. + +The rest of the syntax for macro definitions is summarized in +Figure~\ref{symacro}. The syntax contains a few surprises. The macro +parameters can have a \tdescr{delimited part} and an \tdescr{undelimited +part}. Normally, one of these is \tdescr{empty}, but it is possible to +have both parts nonempty: +$$ \hbox{\tt def foo(text a) expr b =}\, \descr{replacement text}\, + \hbox{\tt enddef;} +$$ +This defines a macro {\tt foo} to take a text parameter in parentheses followed +by an expression. + +\begin{figure}[htp] +\begin{ctabbing} +$\tt \descr{macro definition} \rightarrow + \descr{macro heading} \hbox{\tt =} \descr{replacement text}\, enddef$\\ +$\tt \descr{macro heading} \rightarrow def\, \descr{symbolic token} + \descr{delimited part} \descr{undelimited part}$\\ +$\tt \qquad \;|\; vardef\, \descr{generic variable} \descr{delimited part} + \descr{undelimited part}$\\ +$\tt \qquad \;|\; vardef\, \descr{generic variable} \hbox{\tt @\#} + \descr{delimited part} \descr{undelimited part}$\\ +$\tt \qquad \;|\; \descr{binary def} \descr{parameter} + \descr{symbolic token} \descr{parameter}$\\ +$\tt \descr{delimited part} \rightarrow \descr{empty}$\\ +$\tt \qquad \;|\; \descr{delimited part} + \hbox{\tt (}\descr{parameter type} \descr{parameter tokens}\hbox{\tt )}$\\ +$\tt \descr{parameter type} \rightarrow expr \;|\; suffix \;|\; text$\\ +$\tt \descr{parameter tokens} \rightarrow \descr{parameter} \;|\; + \descr{parameter tokens}\hbox{\tt ,} \descr{parameter}$\\ +$\tt \descr{parameter} \rightarrow \descr{symbolic token}$\\ +$\tt \descr{undelimited part} \rightarrow \descr{empty}$\\ +$\tt \qquad \;|\; \descr{parameter type} \descr{parameter}$\\ +$\tt \qquad \;|\; \descr{precedence level} \descr{parameter}$\\ +$\tt \qquad \;|\; expr\, \descr{parameter}\, of\, \descr{parameter}$\\ +$\tt \descr{precedence level} \rightarrow primary \;|\; secondary \;|\; + tertiary$\\ +$\tt \descr{binary def} \rightarrow primarydef \;|\; secondarydef \;|\; + tertiatydef$ +\end{ctabbing} +\caption{The syntax for macro definitions} +\label{symacro} +\end{figure} + +The syntax also allows the \tdescr{undelimited part} to specify an +argument type of {\tt suffix}\index{suffix?\texttt{suffix}} or {\tt +text}\index{text?\texttt{text}}. An example of a macro with an +undelimited suffix parameter\index{parameter!suffix} is the predefined +macro {\tt incr}\index{incr?\texttt{incr}}\label{Dincr} that is actually +defined like this: +$$ \hbox{\verb|vardef incr suffix $ = $:=$+1; $ enddef;|} $$ +This makes {\tt incr} a function that takes a variable, increments it, +and returns the new value. Undelimited suffix parameters may be +parenthesized, so {\tt incr a} and {\tt incr(a)} are both legal if {\tt +a} is a numeric variable. There is also a similar predefined macro {\tt +decr}\index{decr?\texttt{decr}} that subtracts~1. + +Undelimited text parameters\index{parameter!text} run to the end of a +statement. More precisely, an undelimited text parameter is the list of +tokens following the macro call up to the first ``{\tt +;}\index{semicolon}'' or ``{\tt +endgroup}\index{endgroup?\texttt{endgroup}}'' or ``{\tt +end}\index{end?\texttt{end}}'' except that an argument containing ``{\tt +begingroup}'' will always include the matching ``{\tt endgroup}.'' An +example of an undelimited text parameter comes from the predefined macro +{\tt cutdraw}\index{cutdraw?\texttt{cutdraw}}\label{Dctdraw} whose +definition is +roughly\index{linecap?\texttt{linecap}}\index{butt?\texttt{butt}}\index{interim?\texttt{interim}} +$$\begin{verbatim} +def cutdraw text t = + begingroup interim linecap:=butt; draw t; endgroup enddef; +\end{verbatim} +$$ +This makes {\tt cutdraw} synonymous with {\tt draw} except for the {\tt +linecap} value. (This macro is provided mainly for compatibility with +\MF\index{metafont?\MF}.) + + +\section{Loops} + +Numerous examples in previous sections have used simple {\tt for} loops of the +form\index{loops}\index{for?\texttt{for}}\index{endfor?\texttt{endfor}} +$$ {\tt for}\, \descr{symbolic token}\, \hbox{\tt =}\, + \descr{expression}\, {\tt upto}\, \descr{expression}:\ + \descr{loop text}\, {\tt endfor} +$$ +It is equally simple to construct a loop that counts downward: just +replace {\tt upto} by {\tt +downto}\index{downto?\texttt{downto}}\label{Ddwnto} make the second +\tdescr{expression} smaller than the first. This section covers more +complicated types of progressions, loops where the loop counter behaves +like a suffix parameter, and ways of exiting from a loop. + +The first generalization is suggested by the fact that {\tt +upto}\index{upto?\texttt{upto}} is a predefined macro +for\index{step?\texttt{step}}\index{until?\texttt{until}} +$$ \hbox{\tt step 1 until} $$ +and {\tt downto}\index{downto?\texttt{downto}} is a macro for {\tt step +-1 until}. A loop begining +$$ \hbox{\tt for i=a step b until c} $$ +scans a sequence of {\tt i} values {\tt a}, ${\tt a}+{\tt b}$, ${\tt +a}+2{\tt b}$, \ldots, stopping before {\tt i} passes {\tt c}; i.e., the +loop scans {\tt i} values where ${\tt i}\le {\tt c}$ if ${\tt b}>0$ and +${\tt i}\ge {\tt c}$ if ${\tt b}<0$. For ${\tt b}=0$ the loop never +terminates, even if ${\tt a}={\tt c}$. + +It is best to use this feature only when the step size is an integer or +some number that can be represented exactly in fixed point +arithmetic\index{arithmetic} as a multiple of $1\over65536$. Otherwise, +error will accumulate and the loop index might not reach the expected +termination value. For instance, +$$ \hbox{\tt for i=0 step .1 until 1: show i; endfor} $$ +shows ten {\tt i} values the last of which is 0.90005. + +The standard way of avoid the problems associated with non-integer step +sizes is to iterate over integer values and then multiply by a scale +factor when using the loop index as was done in Figures \ref{fig1} +and~\ref{fig40}. + +Alternatively, the values to iterate over can be given explicitly. Any +sequence of zero or more expressions separated by commas can be used in +place of {\tt a step b upto c}. In fact, the expressions need not all +be the same type and they need not have known values. Thus +$$ \hbox{\tt for t=3.14, 2.78, (a,2a), "hello": show t; endfor} $$ +shows the four values listed. + +Note that the loop body in the above example is a statement followed by a +semicolon. It is common for the body of a loop to be one or more statements, +but this need not be the case. A loop is like a macro definition followed by +calls to the macro. The loop body can be virtually any sequence of tokens as +long as they make sense together. Thus, the (ridiculous) statement +$$ \hbox{\verb|draw for p=(3,1),(6,2),(7,5),(4,6),(1,3): p-- endfor cycle;|} $$ +is equivalent to +$$ \hbox{\verb|draw (3,1)--(6,2)--(7,5)--(4,6)--(1,3)--cycle;|} $$ +(See Figure~\ref{fig17} for a more realistic example of this.) + +If a loop is like a macro definition, the loop index is like an expr +parameter\index{parameter!expr}. It can represent any value, but it is +not a variable and it cannot be changed by an assignment +statement\index{assignment}. In order to do that, you need a {\tt +forsuffixes}\index{forsuffixes?\texttt{forsuffixes}} loop. A {\tt +forsuffixes} loop is a lot like a {\tt for} loop, except the loop index +behaves like a suffix parameter\index{parameter!suffix}. The syntax is +$$ {\tt forsuffixes}\, \descr{symbolic token}\, \hbox{\tt =}\, + \descr{suffix list}:\ \descr{loop text}\, {\tt endfor} +$$ +where a \tdescr{suffix list} is a comma-separated list of suffixes. If +some of the suffixes are \tdescr{empty}, the \tdescr{loop text} gets +executed with the loop index parameter set to the empty suffix. + +A good example of a {\tt forsuffixes} loop is the definition of the {\tt +dotlabels}\index{dotlabels?\texttt{dotlabels}} +macro\index{str?\texttt{str}}: +$$\begin{verbatim} +vardef dotlabels@#(text t) = + forsuffixes $=t: dotlabel@#(str$,z$); endfor enddef; +\end{verbatim} +$$ +This should make it clear why the parameter to {\tt dotlabels} has to be a +comma-separated list of suffixes. Most macros that accept variable-length +comma-separated lists +use them in {\tt for} or {\tt forsuffixes} loops in this fashion as values to +iterate over. + +When there are no values to iterate over, you can use a +{\tt forever}\index{forever?\texttt{forever}} loop: +$$ {\tt forever}\hbox{\tt :}\, \descr{loop text}\, {\tt endfor} $$ +To terminate such a loop when a boolean condition becomes true, use an exit +clause\index{exitif?\texttt{exitif}}: +$$ {\tt exitif}\, \descr{boolean expression} \hbox{\tt ;} $$ +When the MetaPost interpreter encounters an exit clause, it evaluates +the \tdescr{boolean expression} and exits the current loop if the +expression is true. If it is more convenient to exit the loop when an +expression becomes false, use the predefined macro {\tt +exitunless}\index{exitunless?\texttt{exitunless}}. + +Thus MetaPost's version of a {\bf while} loop is +$$ \hbox{\tt forever: exitunless}\, \descr{boolean expression} \hbox{\tt ;}\, + \descr{loop text}\, {\tt endfor} +$$ +The exit clause could equally well come just before {\tt endfor} or anywhere +in the \tdescr{loop text}. In fact any {\tt for}, {\tt forever}, or +{\tt forsuffixes} loop can contain any number of exit clauses. + +The summary of loop syntax shown in Figure~\ref{syloop} does not mention +exit clauses explicitly because a \tdescr{loop text} can be virtually +any sequence of tokens. The only restriction is that a \tdescr{loop +text} must be balanced with respect to {\tt for} and {\tt endfor}. Of +course this balancing process treats {\tt forsuffixes} and {\tt forever} +just like {\tt for}. + +\begin{figure}[htp] +\begin{ctabbing} +$\tt \descr{loop} \rightarrow \descr{loop header}\hbox{\tt :}\, + \descr{loop text} endfor$\\ +$\tt \descr{loop header} \rightarrow for\, \descr{symbolic token}\, + \hbox{\tt =}\, \descr{progression}$\\ +$\tt \qquad \;|\; for\, \descr{symbolic token}\, \hbox{\tt =}\, + \descr{for list}$\\ +$\tt \qquad \;|\; forsuffixes\, \descr{symbolic token}\, \hbox{\tt =}\, + \descr{suffix list}$\\ +$\tt \qquad \;|\; forever$\\ +$\tt \descr{progression} \rightarrow \descr{numeric expression}\, upto\, + \descr{numeric expression}$\\ +$\tt \qquad \;|\; \descr{numeric expression}\, downto\, + \descr{numeric expression}$\\ +$\tt \qquad \;|\; \descr{numeric expression}\, step\, + \descr{numeric expression}\, until\, \descr{numeric expression} $\\ +$\tt \descr{for list} \rightarrow \descr{expression} + \;|\; \descr{for list}\hbox{\tt ,}\, \descr{expression}$\\ +$\tt \descr{suffix list} \rightarrow \descr{suffix} + \;|\; \descr{suffix list}\hbox{\tt ,}\, \descr{suffix}$ +\end{ctabbing} +\caption{The syntax for loops} +\label{syloop} +\end{figure} + + +\section{Reading and Writing Files} +File access was one of the new language features introduced in version~0.60 +of the MetaPost language. A new operator +$$ {\tt readfrom}\ \descr{file name} $$\index{readfrom?\texttt{readfrom}}\label{Dreadfrom}% +returns a string giving the next line of input from the named +file\index{files!reading}. The \tdescr{file name} can be any primary +expression of type string. If the file has ended or cannot be read, the +result is a string consisting of a single null character. The preloaded +{\tt plain} macro package introduces the name +{\tt EOF}\index{EOF?\texttt{EOF}}\label{Deof} for this string. After +{\tt readfrom} has returned {\tt EOF}, additional reads from the same file +cause the file to be reread from the start. + +All files opened by \ttt{readfrom} that have not completely been read +yet are closed\index{files!closing} automatically when the program +terminates, but there exists a command +$${\tt closefrom}\ \descr{file name}$$% +\index{closefrom?\texttt{closefrom}}\label{Dclosefrom}% +to close files opened by {\tt readfrom} explicitly. It is wise to +manually close files you do not need to read completely (i.e. until {\tt + EOF} is returned) because otherwise such files will continue to use +internal resources and perhaps cause a \ttt{capacity exceeded!} error. + +The opposite of {\tt readfrom} is the command +$$ {\tt write}\ \descr{string expression}\ {\tt to}\ \descr{file name} $$% +\index{write to?\texttt{write to}}\label{Dwrite}% +This writes\index{files!writing} a line of text to the specified output file, +opening the file first if necessary. All such files are +closed\index{files!closing} automatically when the program terminates. They +can also be closed explicitly by using {\tt EOF}\index{EOF?\texttt{EOF}} +as the \tdescr{string expression}. The only way to tell if a {\tt write} +command has succeeded is to close the file and use {\tt readfrom} to look +at it. + + +\section{Utility Routines} + +\index{utility routines} +\index{mplib?\texttt{mplib}} +\index{metapost/base?\texttt{metapost/base}} + +This section describes some of the utility routines included in the +\texttt{mplib} directory of the development source hierarchy. Future +versions of this documentation may include more; meanwhile, please read +the source files, most have explanatory comments at the top. They are +also included in the MetaPost and larger \TeX\ distributions, typically +in a \texttt{texmf/metapost/base} directory. + + +\subsection{\texttt{TEX.mp}} + +\label{dTEX} +\index{TEX.mp?\texttt{TEX.mp}} +\index{labels, with variable text} +\index{string expressions, as labels} + +\texttt{TEX.mp} provides a way to typeset the text of a MetaPost string +expression. Suppose, for example, you need labels of the form $n_0$, +$n_1$, \ldots, $n_{10}$ across the $x$ axis. You can do this (relatively) +conveniently with \texttt{TEX.mp}, as follows: +$$\begin{verbatim} +input TEX; +beginfig(100) + last := 10; + for i := 0 upto last: + label(TEX("$n_{" & decimal(i) & "}$"), (5mm*i,0)); + endfor + ... +endfig; +\end{verbatim} +$$ +In contrast, the basic \texttt{btex} command (see p.\ \pageref{Dbtex}) +typesets verbatim text. That is, \texttt{btex~s~etex} typesets the +literal character `s'; \texttt{TEX(s)} typesets the value of the +MetaPost text variable~$s$. + +\index{LaTeX?\LaTeX!typesetting labels with} In version 0.9, +\texttt{TEX.mp} acquired two additional routines to facilitate using +\LaTeX\ to typeset labels: \texttt{TEXPRE} and \texttt{TEXPOST}. Their +values are remembered, and included before and after (respectively) each +call to \texttt{TEX}. Otherwise, each \texttt{TEX} call is effectively +typeset independently. \texttt{TEX} calls also do not interfere with +uses of {\tt verbatimtex}\index{verbatimtex?\texttt{verbatimtex}} (p.\ +\pageref{Dverbatimtex}). + +Here's the same example as above, using the \LaTeX\ commands \verb|\(| +and \verb|\)|: + +$$\begin{verbatim} +input TEX; +TEXPRE("%&latex" & char(10) & "\documentclass{article}\begin{document}"); +TEXPOST("\end{document}"); +beginfig(100) + last := 10; + for i := 0 upto last: + label(TEX("\( n_{" & decimal(i) & "} \)"), (5mm*i,0)); + endfor + ... +endfig; +\end{verbatim} +$$ +Explanation: +\begin{itemize} + +\item +The \texttt{\%\&latex}\index{\%?\texttt{\%}!magic comment!\%\&?\texttt{\%\&}} causes \LaTeX\ to be invoked instead of \TeX. +(See below, also.) Web2C- and MiKTeX-based \TeX\ implementations, at +least, understand this \texttt{\%\&} specification; see, e.g., the Web2C +documentation for details, \url{http://tug.org/web2c}. (Information on +how to do the same with other systems would be most welcome.) + +\item +The \texttt{char(10)} puts a newline (ASCII character code 10, decimal) +in the output. + +\item +The \verb|\documentclass...| is the usual way to start a \LaTeX\ +document. + +\item +The \verb|TEXPOST("\end{document}")| is not strictly necessary, due to +the behavior of \texttt{mpto}, but it is safer to include it. + +\end{itemize} + +Unfortunately, \TeX\ \verb|\special| instructions vanish in this +process. So it is not possible to use packages such as \texttt{xcolor} +and \texttt{hyperref}. + +In case you're curious, these routines are implemented very simply: they +write \texttt{btex} commands to a temporary file and then use +\texttt{scantokens} (p.\ \pageref{Dscantokens}) to process it. The +\texttt{makempx} mechanism (p.\ \pageref{Dmakempx}) does all the work of +running \TeX. + +The \verb|%&| magic on the first line is not the only way to specify +invoking a different program than (plain) \TeX. It has the advantage of +maximum flexibility: different \texttt{TEX} constructs can use different +\TeX\ processors. But at least two other methods are possible: + +\begin{itemize} +\item Set the environment variable \texttt{TEX} to \texttt{latex}---or +whatever processor you want to invoke. (To handle \ConTeXt\ fragments, +\ttt{texexec} could be used.) This might be convenient when writing a +script, or working on a project that always requires \texttt{latex}. + +\item Invoke MetaPost with the command-line option \ttt{-tex=latex} (or +whatever processor, of course). This might be useful from a Makefile, +or just a one-off run. +\end{itemize} + + +\section{Another Look at the MetaPost Workflow} +\label{workflow2} + +\index{workflow} + +In Section~\ref{workflow} we already had a brief look at how MetaPost +compiles input files and generates output files. This section contains +some more information and discusses internal variables that can be used +to control MetaPost's run-time behavior, previewing PostScript output, +debugging MetaPost code, and importing MetaPost graphics into +third-party applications. + +\subsection{Customizing Run-Time Behavior} + +\index{runtime behavior!customize} + +MetaPost knows and obeys a number of internal\index{internal + variables}\index{variables!internal} variables that have no direct +impact on drawing commands, but can be used to customize the way the +MetaPost compiler processes input files. The following paragraphs +describe those variables (in no particular order). + +\paragraph{Date and Time} + +MetaPost provides a number of internal numeric variables that store the +date and time a job was started, i.e., the MetaPost executable was +called on the command-line. Variables +\texttt{year}\index{year?\texttt{year}}\label{Dyear}, +\texttt{month}\index{month?\texttt{month}}\label{Dmonth}, +\texttt{day}\index{day?\texttt{day}}\label{Dday}, +\texttt{hour}\index{hour?\texttt{hour}}\label{Dhour}, and +\texttt{minute}\index{minute?\texttt{minute}}\label{Dminute} should be +self-explanatory. Variable +\texttt{time}\index{time?\texttt{time}}\label{Dtime} returns the number +of minutes past midnight, since the job was started, i.e., +$\texttt{time} = 60*\texttt{hour} + \texttt{minute}$. + +\paragraph{Output File Names} + +As discussed in Section~\ref{workflow}, by default, every +\verb|beginfig| \ldots\ \verb|endfig| group in an input file corresponds +to an output file that follows the naming scheme +\texttt{\tdescr{jobname}.\tdescr{n}}. That is, all files have varying +numeric file extensions. MetaPost provides a template mechanism that +allows for more flexible output file names. The template mechanism uses +\texttt{printf}-style escape sequences that are re-evaluated at ship-out +time, i.e., before each figure is written to disk. + +To configure the output file naming scheme a string containing the +corresponding escape sequences has to be assigned to the internal string +variable +\verb|outputtemplate|\index{outputtemplate?\texttt{outputtemplate}}\label{Doutputtemplate}. +The escape sequences provided are listed in +table~\ref{tab:outputtemplate}. As an example, if this code is saved in +a file \texttt{fig.mp}, +$$ +\begin{verbatim} +outputtemplate := "%j-%c.mps"; +beginfig(1); + drawdot origin; +endfig; +end +\end{verbatim} +$$ +it will create the output file \texttt{fig-1.mps} instead of +\texttt{fig.1}. The file extension \texttt{mps}\index{mps file?{\tt + mps} file}\index{files!mps?{\tt mps}} is conventionally chosen for +MetaPost's PostScript output (see Section~\ref{mpimport}). For SVG and +PNG output one would want to use file extensions \texttt{svg}\index{svg + file?{\tt svg} file}\index{files!svg?{\tt svg}} and +\texttt{png}\index{png file?{\tt png} file}\index{files!png?{\tt png}} +instead. + +\begin{table} + \centering + \begin{tabular}{|>{\ttfamily}l|l|>{\ttfamily}l|} + \hline + \multicolumn1{|c|}{Escape sequence} & \multicolumn1{c|}{Meaning} & \multicolumn1{c|}{Alternative}\\\hline + \%\%\index{\%?\texttt{\%}!outputtemplate escape sequence?\texttt{outputtemplate} escape sequence!\%\%?\texttt{\%\%}} & percent sign &\\ + \%\{\tdescr{internal variable}\}\index{\%?\texttt{\%}!outputtemplate + escape sequence?\texttt{outputtemplate} escape sequence!\%\{...\}?\texttt{\%\{\tdescr{internal variable}\}}} & evaluate internal variable &\\ + \%j\index{\%?\texttt{\%}!outputtemplate escape sequence?\texttt{outputtemplate} escape sequence!\%j?\texttt{\%j}} & current jobname & \%\{jobname\}\\ + \%c\index{\%?\texttt{\%}!outputtemplate escape sequence?\texttt{outputtemplate} escape sequence!\%c?\texttt{\%c}} & charcode value (\texttt{beginfig} argument) & \%\{charcode\}\\ + \%y\index{\%?\texttt{\%}!outputtemplate escape sequence?\texttt{outputtemplate} escape sequence!\%y?\texttt{\%y}} & current year & \%\{year\}\\ + \%m\index{\%?\texttt{\%}!outputtemplate escape sequence?\texttt{outputtemplate} escape sequence!\%m?\texttt{\%m}} & month (numeric) & \%\{month\}\\ + \%d\index{\%?\texttt{\%}!outputtemplate escape sequence?\texttt{outputtemplate} escape sequence!\%d?\texttt{\%d}} & day of the month & \%\{day\}\\ + \%H\index{\%?\texttt{\%}!outputtemplate escape sequence?\texttt{outputtemplate} escape sequence!\%H?\texttt{\%H}} & hour & \%\{hour\}\\ + \%M\index{\%?\texttt{\%}!outputtemplate escape sequence?\texttt{outputtemplate} escape sequence!\%M?\texttt{\%M}} & minute & \%\{minute\}\\ + \hline + \end{tabular} + \caption{Allowed escape sequences for \ttt{outputtemplate}} + \label{tab:outputtemplate} +\end{table} + +In single-letter escape sequences referring to internal numerics, the +corresponding value is rounded to the nearest integer before it is +converted to a string expression. In such escape sequences, a number +from the range 0 to~99 can optionally be placed directly after \verb|%| +that determines the minimum number of digits in the resulting string +expression, like \verb|%2m|. If the decimal representation of the +internal variable requires more digits, actual string length will exceed +the requested length. If less digits are required, the string is padded +to the requested length with zeros from left. + +In single-letter escape sequences referring to internal string +variables, like \verb|%j|, and in the \verb|%{...}| escape sequence, +neither rounding nor zero-padding take place. + +For backwards compatibility, the +\verb|%c|\index{\%?\texttt{\%}!outputtemplate escape + sequence?\texttt{outputtemplate} escape sequence!\%c?\texttt{\%c}} +escape sequence is handled special. If the result of rounding the +charcode value is negative, \verb|%c| evaluates to the string \verb|ps|. +This transformation can be bypassed by using \verb|%{charcode}| instead +of \verb|%c|. But note, that this bypasses rounding and zero-padding as +well. + +The template mechanism can also be used for naming graphic files +individually, yet keeping all sources in one file. Collecting, e.g., +different diagram sources in a single file \texttt{fig.mp}, it might be +easier to recall the correct diagram names in a \TeX\ document than with +numbered file names. Note, the argument to \verb|beginfig| is not +relevant as long as there's no \verb|%c| pattern in the file name +template string. +$$ +\begin{verbatim} +outputtemplate := "fig-quality.mps"; +beginfig(1); + ... +endfig; + +outputtemplate := "fig-cost-vs-productivity.mps"; +beginfig(2); + ... +endfig; +\end{verbatim} +$$ + +To ensure compatibility with older files, the default value of +\verb|outputtemplate| is \verb|%j.%c|. If you assign an empty string, +it will revert to that default. MetaPost versions~1.000 to~1.102 used a +different template mechanism, see Section~\ref{Dfilenametemplate} for +more information. + +During \texttt{shipout}\index{shipout?\texttt{shipout}}, the name of the +output file to be written is stored in an internal string variable +\texttt{outputfilename}\index{outputfilename?\texttt{outputfilename}}\label{Doutputfilename}. +It remains available until the next \texttt{shipout} command. The +variable is initially empty. + +\paragraph{Output Format} + +MetaPost can generate graphics in three output formats: + +\begin{itemize} +\item Encapsulated PostScript\index{PostScript!structured} + (EPSF\index{EPSF}), +\item Scalable Vector Graphics (SVG\index{SVG}) following version~1.1 of + the SVG specification~\cite{w3c:svg1.1} (since MetaPost version + 1.200), +\item Portable Network Graphics (PNG), a losslessly compressing bitmap + format (since MetaPost version 1.800). +\end{itemize} +By default, MetaPost outputs PostScript files---hence the name MetaPost. +The output format can be changed by assigning values \verb|"svg"| or +\verb|"png"| to the internal string variable\index{internal + variables}\index{variables!internal} +\verb|outputformat|\index{outputformat?\texttt{outputformat}}\label{Doutputformat}: +$$ +\begin{verbatim} +outputformat := "svg"; +\end{verbatim} +$$ +Other values make MetaPost fall back to PostScript output. Variable +\verb|outputformat| is case-sensitive, so assigning it the string +\verb|"SVG"| enables PostScript output, too. Default value of variable +\verb|outputformat| is \verb|"eps"|. + +\paragraph{Bitmap output} To create bitmap output in the PNG format, +MetaPost utilizes the Cairo\index{Cairo} \cite{lib:cairo} graphics +library.\footnote{The Cairo library version is printed when MetaPost is + run with the \texttt{-version} command-line switch.} Bitmap +conversion can be controlled from within MetaPost using three internal +variables: \texttt{outputformatoptions}, \texttt{hppp}, and +\texttt{vppp}. + +\begin{table} + \centering + \begin{tabular}{|>{\ttfamily}l|>{\ttfamily}l|l|} + \hline + \multicolumn1{|c|}{Key} & \multicolumn1{c|}{Values} & \multicolumn1{c|}{Meaning}\\\hline + format & + rgba\index{rgba?\texttt{rgba}|see{\texttt{outputformatoptions}, + \texttt{format}}} & RGB color space\index{PNG!color space!RGBA} + with alpha channel\index{PNG!alpha channel}\\ + & rgb\index{rgb?\texttt{rgb}|see{\texttt{outputformatoptions}, + \texttt{format}}} & RGB color space\index{PNG!color space!RGB}\\ + & graya\index{graya?\texttt{graya}|see{\texttt{outputformatoptions}, + \texttt{format}}} & gray scale color space\index{PNG!color + space!gray scale with alpha} with alpha channel\index{PNG!alpha + channel}\\ + & gray\index{gray?\texttt{gray}|see{\texttt{outputformatoptions}, + \texttt{format}}} & gray scale color space\index{PNG!color + space!gray scale}\\ + \hline + antialias & + none\index{none?\texttt{none}|see{\texttt{outputformatoptions}, + \texttt{antialias}}} & no anti aliasing\index{PNG!anti + aliasing}\\ + & fast\index{fast?\texttt{fast}|see{\texttt{outputformatoptions}, + \texttt{antialias}}} & fastest anti aliasing algorithm\\ + & good\index{good?\texttt{good}|see{\texttt{outputformatoptions}, + \texttt{antialias}}} & better quality, but slower\\ + & best\index{best?\texttt{best}|see{\texttt{outputformatoptions}, + \texttt{antialias}}} & best quality, slowest\\ + \hline + \end{tabular} + \caption{Valid keys and values in variable \texttt{outputformatoptions}.} + \label{tab:outputformatoptions} +\end{table} + +Variable +\texttt{outputformatoptions}\index{outputformatoptions?\texttt{outputformatoptions}}\label{Doutputformatoptions} +is a string containing a list of \tdescr{key}\verb|=|\tdescr{value} +pairs separated by spaces (no other spaces are allowed). Key +\texttt{format}\index{format?\texttt{format}|see{outputformatoptions, + \texttt{format}}}\index{outputformatoptions?\texttt{outputformatoptions}!format?\texttt{format}} +determines color space of the written PNG file. Key +\texttt{antialias}\index{antialias?\texttt{antialias}|see{outputformatoptions, + \texttt{antialias}}}\index{outputformatoptions?\texttt{outputformatoptions}!antialias?\texttt{antialias}} +determines what level of anti aliasing\index{anti aliasing|see{PNG, anti + aliasing}}\index{PNG!anti aliasing} is applied during vector graphic +to bitmap conversion. The set of accepted values and their meanings can +be found in table~\ref{tab:outputformatoptions}. An assignment that +would match the compiled-in default setup would look like + +$$ +\begin{verbatim} +outputformatoptions := "format=rgba antialias=fast"; +\end{verbatim} +$$ +Keys not given in an assignment to \texttt{outputformatoptions} are +reset to their default value. By default, this variable is empty. + +PNG files have a transparent background\index{background in PNG output} +if output color space provides an alpha channel\index{alpha + channel|see{PNG, alpha channel}}\index{PNG!alpha channel} +(\texttt{format}\index{outputformatoptions?\texttt{outputformatoptions}!format?\texttt{format}} +is \texttt{rgba} or \texttt{graya}). Otherwise background becomes +white. Color channels have a bit-depth of~8 in output. Colors not +supported by the output format, e.g., CMYK colors, are transformed to a +color with a similar visual impression. Here's how colors are +transformed during bitmap conversion. Let's recall that color +components in a MetaPost picture are in the range $[0;1]$ (see the +discussion of color types in Section~\ref{datatypes}). Whatever input +and output color spaces are used, all colors found in a picture are +initially converted to RGB color space. A gray scale color with +intensity $i$ is converted to an RGB color with all components set +to~$i$. RGB colors are left unchanged. A CMYK color with components +$(c,m,y,k)$ is converted to an RGB color with components $(r,g,b)$ using +equations +\begin{eqnarray} + r &=& 1 - k - c\\ + g &=& 1 - k - m\\ + b &=& 1 - k - y +\end{eqnarray} +with results clipped to the range $[0;1]$. If requested by the output +format (\texttt{gray} or \texttt{graya}), such a color is further +converted to a gray color with intensity +\begin{eqnarray} +j = 0.2126 \cdot r + 0.7152 \cdot g + 0.0722 \cdot b +\end{eqnarray} + +Note, colors are exact in PNG output if input and output color spaces +are compatible, i.e., both are RGB or gray scale or output in RGB color +space contains only gray scale colors. Users that care about color +conversion can apply the necessary transformations explicitly in a +\texttt{for within~\tdescr{\mbox{picture}}}\index{for within?\texttt{for + within}} loop inside +\texttt{extra\_endfig}\index{extra_endfig?\texttt{extra\_endfig}} (see +Section~\ref{Dforwithin} and Appendix~\ref{Dxefig}). MetaPost has no +built-in color management support. The built-in conversions are +provided just as a convenience. + +Resolution of PNG output is always 72~dpi\index{dpi}\index{units!dpi} +(dots per inch). Two internal variables +\texttt{hppp}\index{hppp?\texttt{hppp}}\label{Dhppp} and +\texttt{vppp}\index{vppp?\texttt{vppp}}\label{Dvppp} are used by the PNG +backend to decide on the scale of the generated bitmap. These two +variables have already been present in \MF\ and have been revived when +MetaPost acquired the bitmap backend in version 1.800. But there's a +catch: In \MF, variables \texttt{hppp} and \texttt{vppp} refer to +horizontal and vertical scale in \emph{pixels per + point}\index{units!pixels per point} and values larger than~1 result +in output of larger dimensions. In MetaPost, the meaning of both +variables is the other way around. They refer to horizontal and +vertical scale in \emph{points per pixel}\index{units!points per pixel} +and values larger than~1 result in output of smaller dimensions. +Default value for both variables is $1.0$, i.e., one MetaPost point per +pixel. + +\paragraph{PostScript Dictionary} + +For PostScript output, MetaPost can define a dictionary of abbreviations +of the PostScript commands, e.g., \verb|l| instead of \verb|lineto|, to +reduce the size of output files. Setting the internal variable +\texttt{mpprocset}\index{mpprocset?\texttt{mpprocset}}\label{Dmpprocset} +to~1 makes MetaPost create an extended preamble setting-up the +dictionary. Default value of variable \texttt{mpprocset} is~0, that is, +no dictionary is used. For SVG and PNG output, variable +\texttt{mpprocset} is not relevant. + +\paragraph{Version Number} + +The version number of the MetaPost compiler can be determined from +within a MetaPost program via the predefined constant string +\texttt{mpversion}\index{mpversion?\texttt{mpversion}}\label{Dmpversion} +(since version~0.9). For instance the following code +$$ +\begin{verbatim} +message "mp = " & mpversion; +\end{verbatim} +$$ +writes +$$ +\begin{verbatim}[commandchars=\\\{\}] +mp = \mpversion +\end{verbatim} +$$ +to the console and the transcript file. Variable \texttt{mpversion} can +be used to execute code depending on the MetaPost version like this: +$$ +\begin{verbatim}[commandchars=\\\{\}] +if unknown mpversion: string mpversion; mpversion := "0.000"; fi +if scantokens(mpversion) < 1.200: + errmessage "MetaPost v1.200 or later required (found v" & mpversion & ")"; +else: + \tdescr{code} +fi +\end{verbatim} +$$ +The first line is optional and only added to handle ancient MetaPost +versions gracefully that don't even know about variable +\textrm{mpversion} (prior to v0.9). The second test does the actual +work. + +The version number is also written to output files and the transcript +file. For PostScript output, the version number can be found in the +\texttt{Creator}\index{Creator comment in PostScript + output?\texttt{Creator} comment in PostScript output|see{PostScript, + \texttt{Creator} comment}}\index{PostScript!Creator + comment?\texttt{Creator} comment} comment. SVG files contain a simple +comment line near the beginning of the file. For PNG output, the +version number can be found in a text chunk with keyword +\texttt{Software}\index{Software keyword in PNG text + chunk?\texttt{Software} keyword in PNG text chunk|see{PNG, text + chunk}}\index{text chunk|see{PNG, text chunk}}\index{PNG!text + chunk}. The transcript\index{files!transcript} file starts with a +banner line that identifies the version\index{version number} of the +MetaPost compiler. + +\subsection{Previewing PostScript Output} +\label{preview} +\index{preview!PostScript} + +Previewing MetaPost's PostScript output is not difficult, but there are +some catches that one should know about. This section deals with the +following questions: How can graphics be clipped to their true bounding +box in the PostScript viewer application? Why are my text labels +rendered with an ugly font (or not at all) and how to avoid that? How +can several graphics be combined into a multi-page document that can be +previewed within one instance of the viewer application? + +\subsubsection{Bounding Box} +\index{bounding box} +\index{PostScript!bounding box} + +With default settings, MetaPost writes very much stripped-down +PostScript code, containing only the bare graphics code, but no other +ressources, like fonts etc. The PostScript code is somewhat deficient, +because it fails to correctly identify as Encapsulated PostScript +(EPSF\index{EPSF}) in the header. Note, Encapsulated PostScript files +don't have an associated page size, but provide bounding box +information, because they are meant for inclusion into other documents. +Instead MetaPost output wrongly pretends to be full PostScript +(PS\index{PS}), which it is not. + +This is just fine for including MetaPost graphics in, say, \TeX\ +documents (see Section~\ref{mpimport}), but some PostScript viewers have +difficulties rendering those PostScript files correctly. As an example, +because of the wrong ``PS'' header, GSview\index{GSview}---not knowing +better---ignores bounding box information and then clips all contents to +a (configurable) page size. Graphic elements laying outside those fixed +page boundaries are therefore not visible, e.g., when they have negative +coordinates. + +To avoid such situations, the first rule when previewing MetaPost's +PostScript output is to put the line +$$ +\begin{verbatim} +prologues := 2; +\end{verbatim} +\index{prologues?\texttt{prologues}} +$$ +before the first \verb|beginfig| in MetaPost input files (see the +discussion about \texttt{prologues} in Section~\ref{Dprologues}). That +way, MetaPost's PostScript output correctly identifies as Encapsulated +PostScript and viewer applications should always obey the file's +bounding box for on-screen rendering. + +A workaround for MetaPost's deficient default PostScript code that can +sometimes be seen is to move the lower left corner of a figure to the +origin as a last operation by saying +$$ +\begin{verbatim}[commandchars=\\\{\}] +\color{gray}currentpicture := currentpicture shifted -llcorner currentpicture; +\end{verbatim} +\index{currentpicture?\texttt{currentpicture}} +\index{llcorner?\texttt{llcorner}} +$$ +before \verb|endfig|. But this doesn't prevent from clipping on the +right and upper page boundaries. Additionally, the line is required for +all figures, cluttering source code, and it alters all coordinates in +PostScript output, which might complicate debugging. Applying such a +manual transformation is therefore not recommended (which is why the +line is grayed out). Instead, users are advised to adjust +\texttt{prologues} once in the preamble of the input file and enable +clipping to the bounding box in the PostScript viewer. For +GSview\index{GSview}, that can be done by activating \texttt{Options} +$\rightarrow$ \texttt{EPS Clip} and optionally \texttt{Options} +$\rightarrow$ \texttt{Show Bounding Box} for verification. + +\subsubsection{Text Labels} + +Another popular previewing issue concerns graphics that contain text +labels. An observation MetaPost users can often make is that text +labels in graphics are rendered with wrong fonts, wrong glyphs, and +sometimes even not at all. The reason is that with default settings, +again, MetaPost's PostScript output is deficient, in that it uses a +simple, non-standard way to declare what fonts are used in a graphic. +Setting variable \texttt{prologues} to~2, as shown in the previous +section, makes MetaPost generate more complex PostScript code to declare +all needed PostScript\index{PostScript!fonts} fonts and embed the +necessary encoding information. If the PostScript viewer can provide +the requested fonts, this might be sufficient to get text labels +rendered correctly. If you still observe wrong or missing glyphs you +should put the line +$$ +\begin{verbatim} +prologues := 3; +\end{verbatim} +\index{prologues?\texttt{prologues}} +$$ +into the preamble of the input file. That way, MetaPost embeds the used +PostScript\index{PostScript!fonts} fonts into the output file so that +they are always available (see the discussion about \texttt{prologues} +in Section~\ref{Dprologues}). Note, this might enlarge the size of +output files considerably. Additionally, fonts might be embedded +multiple times when several graphics using the same fonts are included +into a document. For that reason, it is recommended to reset variable +\texttt{prologues} to~0 before finally including MetaPost graphics into +external documents. + +\subsubsection{Proof Sheets} +\index{proof sheets} + +If you have lots of figures in a source file and need to preview many of +them at the same time, opening every graphic in a new instance of the +viewer application and switching between them back and forth can get +cumbersom. An alternative is to collect all graphics generated from a +MetaPost input file in a proof sheet, a multi-page document, that can be +previewed and navigated in a single instance of the viewer application. +The MetaPost distribution contains two (plain) \TeX\ scripts, +\texttt{mproof.tex} and \texttt{mpsproof.tex}, that help with the latter +approach. + +\paragraph{\texttt{mproof.tex}} +\index{mproof.tex?\texttt{mproof.tex}} + +To write a proof sheet for MetaPost output, call \texttt{mproof.tex} as +$$ +\begin{verbatim}[commandchars=\\\{\}] +tex mproof \tdescr{MetaPost output files} +\end{verbatim} +$$ +Then process the resulting \texttt{.dvi}\index{dvi file?{\tt dvi} + file}\index{files!dvi?{\tt dvi}} file as usual. That way, there's no +need to care about different settings of variable +\texttt{prologues}\index{prologues?\texttt{prologues}}, since in proof +sheets MetaPost graphics are already embedded. + +Note, the parameters after \texttt{mproof} are an explicit list of +MetaPost output files, possibly generated from different input files. +On shells that support POSIX\index{shell patterns}\index{POSIX!shell + patterns} shell patterns, these can be used to avoid typing a long +list of files. As an example, for a file \texttt{fig.mp} containing +three figures with charcodes 1, 2, and~3, the proof sheet can be +generated by calling +$$ +\begin{verbatim} +tex mproof fig.? +\end{verbatim} +$$ +The pattern \texttt{fig.?} is automatically expanded to \texttt{fig.1 + fig.2 fig.3} by the shell (but not necessarily in numerically +increasing order) before \TeX\ is run. If there were an output file +\texttt{fig.10}, using patterns \texttt{fig.??} or \texttt{fig.*} to +cover two-digit indices would fail, since those covered the source file +\texttt{fig.mp} as well. To avoid that, output file names have to be +made more significant, e.g., by setting variable \texttt{outputtemplate} +to \verb|%j-%c.mps| (see Section~\ref{Doutputtemplate}). The proof sheet +can then be generated with +$$ +\begin{verbatim} +tex mproof *.mps +\end{verbatim} +$$ + +\paragraph{\texttt{mpsproof.tex}} +\index{mpsproof.tex?\texttt{mpsproof.tex}} + +An alternative to \texttt{mproof.tex} is the script +\texttt{mpsproof.tex}, which is similar, but more powerful. While the +former script only runs with \TeX\ and requires a DVI output driver to +generate PostScript files, \texttt{mpsproof.tex} can as well be run +through pdf\TeX\ to directly generate PDF files. Additionally, it +provides some command-line options. + +With the +\verb|\noheaders|\index{mpsproof.tex?\texttt{mpsproof.tex}!noheaders?\texttt{\textbackslash + noheaders}} option, file names, date stamps, and page numbers are +omitted from the proof sheet. Use it like +$$ +\begin{verbatim}[commandchars=\|\{\}] +tex mpsproof \noheaders |tdescr{MetaPost output files} +\end{verbatim} +$$ + +The +\verb|\bbox|\index{mpsproof.tex?\texttt{mpsproof.tex}!bbox?\texttt{\textbackslash + bbox}} option can be used to generate an output file that has +exactly the same page size as a figure's bounding box (\verb|\bbox| is +actually an alias for the longer +\verb|\encapsulate|\index{mpsproof.tex?\texttt{mpsproof.tex}!encapsulate?\texttt{\textbackslash + encapsulate}}). With this option only one figure can be processed +at a time, e.g., +$$ +\begin{verbatim} +pdftex mpsproof \bbox fig.1 +\end{verbatim} +$$ + +\paragraph{Alternatives} Other alternatives for previewing MetaPost +figures, which are not part of the MetaPost distribution, are the +mptopdf\index{mptopdf} bundle or the Perl script \ttindex{mpstoeps.pl}. +There is also an online compiler and viewer for MetaPost code at +\url{http://tlhiv.org/mppreview/}. + +\subsection{Debugging} +\label{debug} + +\index{debug} + +MetaPost inherits from \MF\index{metafont?\MF} numerous facilities for +interactive debugging, most of which can only be mentioned briefly here. +Further information on error messages, debugging, and generating tracing +information can be found in {\sl The\ \MF book} \cite{kn:c}. + +Suppose your input file says +$$ \hbox{\verb|draw z1--z2;|} $$ +on line 17 without first giving known values to {\tt z1} and {\tt z2}. +Figure~\ref{errmsg} shows what the MetaPost interpreter prints on your +terminal when it finds the error. The actual error message is the line +beginning with ``{\tt !}''; the next six lines give the context that +shows exactly what input was being read when the error was found; and +the ``{\tt ?}'' on last line is a prompt for your response. Since the +error message talks about an undefined $x$~coordinate, this value is +printed on the first line after the ``\verb|>>|''. In this case the +$x$~coordinate of {\tt z1} is just the unknown variable {\tt x1}, so the +interpreter prints the variable name {\tt x1} just as it would if it +were told to\index{show?\texttt{show}} ``{\tt show x1}'' at this point. + +\begin{figure}[htp] +$$\begin{verbatim} +>> x1 +! Undefined x coordinate has been replaced by 0. + + { +--->{ + curl1}..{curl1} +l.17 draw z1-- + z2; +? +\end{verbatim} +$$ +\caption{An example of an error message.} +\label{errmsg} +\end{figure} + +The context listing may seem a little confusing at first, but it really just +gives a few lines of text showing how much of each line has been read so far. +Each line of input is printed on two lines like this: +\begin{eqnarray*} + \descr{descriptor}\ \hbox{Text read so far} \\ + && \hbox{Text yet to be read} +\end{eqnarray*} +The \tdescr{descriptor} identifies the input source. It is either a +line number like ``{\tt l.17}'' for line 17 of the current file; or it +can be a macro name followed by ``{\tt ->}''; or it is a descriptive +phrase in angle brackets. Thus, the meaning of the context listing in +Figure~\ref{errmsg} is that the interpreter has just read line 17 of the +input file up to ``\verb|--|,'' the expansion of the \verb|--| macro has +just started, and the initial ``\verb|{|'' has been reinserted to allow +for user input before scanning this token. + +Among the possible responses to a {\tt ?} prompt are the following: +\begin{description} +\item[x] terminates the run so that you can fix your input file and start over. +\item[h] prints a help message followed by another {\tt ?} prompt. +\item[\tdescr{return}] causes the interpreter to proceed as best it can. +\item[?] prints a listing of the options available, followed by another + {\tt ?} prompt. +\end{description} + +This interactive mode is not only entered when MetaPost finds an error +in the code. It can be explicitly entered by the \ttindex{errmessage} +command. The \ttindex{message}\label{Dmessage} command writes a string +argument to a new line on the terminal. The +\ttindex{errmessage}\label{Derrmessage} command is similar, but the +string argument is preceded by \verb|"! "| and followed by~\verb|"."|. +Additionally, some lines of context are appended as in MetaPost's normal +error messages. If the user now types ``h'', the most recent +\ttindex{errhelp}\label{Derrhelp} string will be shown (unless it was +empty). + +\begin{figure}[htp] +\begin{ctabbing} +$\tt \descr{message command} \rightarrow errhelp \descr{string expression}$\\ +$\tt \qquad \;|\; errmessage \descr{string expression}$\\ +$\tt \qquad \;|\; message \descr{string expression}$ +\end{ctabbing} +\caption{The syntax for message commands} +\label{symsg} +\end{figure} + +Error messages and responses to {\tt show} commands are also written +into the transcript\index{files!transcript} file whose name is obtained +from the name of the main input file by changing ``{\tt .mp}''\index{mp + file?{\tt mp} file}\index{files!mp?{\tt mp}} to ``{\tt + .log}''\index{log file?{\tt log} file}\index{files!log?{\tt + log}}. When the internal variable\index{internal + variables}\index{variables!internal} {\tt + tracingonline}\index{tracingonline?\texttt{tracingonline}} is at its +default value of zero, some {\tt show} commands print their results in +full detail only in the transcript file. + +Only one type of {\tt show}\index{show?\texttt{show}} command has been +discussed so far: {\tt show} followed by a comma-separated list of +expressions prints symbolic representations of the expressions. + +The {\tt showtoken}\index{showtoken?\texttt{showtoken}}\label{Dshtok} +command can be used to show the +parameters and replacement text of a macro. It takes a comma-separated list of +tokens and identifies each one. If the token is a primitive as in +``\verb|showtoken +|'' it is just identified as being itself: +$$ \hbox{\verb|> +=+|} $$ +Applying {\tt showtoken} to a variable or a {\tt vardef} macro yields +$$ \hbox{\tt > } \descr{token}\hbox{\tt =variable} $$ + +To get more information about a variable, use +{\tt showvariable}\index{showvariable?\texttt{showvariable}}\label{Dshvar} +instead of {\tt showtoken}. The +argument to {\tt showvariable} is a comma-separated list of symbolic tokens +and the result is a description of all the variables whose names begin with +one of the listed tokens. This even works for {\tt vardef} macros. For +example, {\tt showvariable z} yields +$$ \hbox{\verb|z@#=macro:->begingroup(x(SUFFIX2),y(SUFFIX2))endgroup|} $$ + +There is also a {\tt +showdependencies}\index{showdependencies?\texttt{showdependencies}}\label{Dshdep} +command that takes no arguments and prints a list of all {\em dependent} +variables and how the linear equations given so far make them depend on +other variables. Thus after +$$ \hbox{\tt z2-z1=(5,10); z1+z2=(a,b);} $$ +{\tt showdependencies} prints what is shown in Figure~\ref{shdep}. This could +be useful in answering a question like ``What does it mean +`{\tt !\ Undefined x coordinate}?' I thought the equations given so far would +determine {\tt x1}.'' + +\begin{figure}[htp] +$$\begin{verbatim} +x2=0.5a+2.5 +y2=0.5b+5 +x1=0.5a-2.5 +y1=0.5b-5 +\end{verbatim} +$$ +\caption{The result of {\tt z2-z1=(5,10); z1+z2=(a,b); showdependencies;}} +\label{shdep} +\end{figure} + +When all else fails, the predefined macro {\tt +tracingall}\index{tracingall?\texttt{tracingall}}\label{Dtall} causes +the interpreter to print a detailed listing of everything it is doing. +Since the tracing information is often quite voluminous, it may be +better to use the {\tt +loggingall}\index{loggingall?\texttt{loggingall}}\label{Dlogall} macro +that produces the same information but only writes it in the +transcript\index{files!transcript} file. There is also a {\tt +tracingnone}\index{tracingnone?\texttt{tracingnone}}\label{Dtnone} macro +that turns off all the tracing output. + +Tracing output is controlled by the set of internal +variables\index{internal variables}\index{variables!internal} summarized +below. When any one of these variables is given a positive value, the +corresponding form of tracing is turned on. Here is the set of tracing +variables and what happens when each of them is positive: +\begin{description} +\item[{\tt tracingcapsules}]\index{tracingcapsules?\texttt{tracingcapsules}}\label{Dtcapsules}% +shows the values of temporary quantities (capsules) when they become known. +% +\item[{\tt tracingchoices}]\index{tracingchoices?\texttt{tracingchoices}}\label{Dtchoices}% +shows the B\'ezier control\index{control points} points of each new path +when they are chosen. % +\item[{\tt tracingcommands}]\index{tracingcommands?\texttt{tracingcommands}}\label{Dtcommands}% +shows the commands before they are performed. A setting ${}>1$ also shows +{\tt if}\index{if?\texttt{if}} tests and loops before they are expanded; +a setting ${}>2$ shows algebraic operations before they are performed. +% +\item[{\tt tracingequations}]\index{tracingequations?\texttt{tracingequations}}\label{Dtequations}% +shows each variable when it becomes known. +% +\item[{\tt tracinglostchars}]\index{tracinglostchars?\texttt{tracinglostchars}}\label{Dtlostchars}% +warns about characters omitted from a picture because they are not in the font +being used to typeset labels. +% +\item[{\tt tracingmacros}]\index{tracingmacros?\texttt{tracingmacros}}\label{Dtmacros}% +shows macros before they are expanded. +% +\item[{\tt tracingoutput}]\index{tracingoutput?\texttt{tracingoutput}}\label{Dtoutput}% +shows pictures as they are being shipped out as PostScript files. +% +\item[{\tt tracingrestores}]\index{tracingrestores?\texttt{tracingrestores}}\label{Dtrestores}% +shows symbols and internal variables as they are being restored at the end +of a group. +% +\item[{\tt tracingspecs}]\index{tracingspecs?\texttt{tracingspecs}}\label{Dtspecs}% +shows the outlines generated when drawing with a +polygonal pen\index{pens!polygonal}. +% +\item[{\tt tracingstats}]\index{tracingstats?\texttt{tracingstats}}\label{Dtstats} +shows in the transcript file at the end of the job how many of the +MetaPost interpreter's limited resources were used. +\end{description} + +\subsection{Importing MetaPost Graphics into External Applications} +\label{mpimport} + +MetaPost is very well suited for creating graphics that are to be +included into third-party applications, such as text documents, +presentations or web pages, because MetaPost outputs graphics in vector +formats, which can be scaled without quality degradation. However, +practice shows, that vector graphics, too, are best created with a rough +target size already in mind. Scaling a vector graphic calls for +non-proportional scaling of certain technical parameters, such as line +width, arrow size or fonts. Otherwise, with growing scale factors +scalable graphics tend to change their visual character. Additionally, +during import into a main document, they'll likely fail to match, e.g., +stroke width of the document. To circumvent this, it is advisable to +apply only small post-processing scale factors to vector graphics. The +following sections briefly discuss how to import MetaPost graphics into +documents with selected applications. + +\subsubsection{\TeX\ and Friends} +\label{teximport} +\index{TeX?\TeX!and friends} + +MetaPost graphics in the PostScript\index{PostScript} format can be +easily integrated into documents prepared with \TeX\ and friends. +MetaPost's PostScript output is a low-featured dialect of the Postscript +language, called \emph{purified EPS}\index{EPS!purified}, which can be +converted into the Portable Document Format (PDF\index{PDF}) language +on-the-fly. For that reason, external MetaPost graphics can be used on +both routes: a) using the traditional \TeX\ engine together with an +external PostScript output driver and b) using newer \TeX\ engines, like +pdf\TeX\ or its successor Lua\TeX, which contain a built-in PDF output +driver. Lua\TeX\ can additionally process embedded MetaPost code +natively, falling back to the built-in \emph{mplib} library. + +Figure~\ref{fig:teximport} shows the process of including an external +MetaPost graphic into a \TeX\ document using the PostScript route. In +the \TeX\ source a ``magic macro'' provided by the format or an external +package is used for including a graphic file. During the typesetting +stage, the macro only reads bounding box information off the PostScript +file and reserves the required space on the page via an empty box. The +file reference is passed-on to the output driver and only then, finally, +the file is embedded into the document. The freely available program +\ttindex{dvips} is used as an output driver in this +example.\footnote{The C source for \ttt{dvips} comes with the web2c + \TeX\ distribution. Similar programs are available from other + sources.} The next paragraphs give more detailed information on some +popular combinations of \TeX\ formats and engines. + +\begin{figure} +$$ \includegraphics{mpman-charts-1.mps} $$ +\caption{A diagram of the processing for a \TeX\ document embedding + MetaPost figures} +\label{fig:teximport} +\end{figure} + +\paragraph{Plain \TeX\ Format} +\label{plaintexformat} +\index{TeX?\TeX!format, plain!importing MetaPost files} + +For users of the Plain \TeX\ format and the traditional \TeX\ +engine\index{TeX?\TeX!engine} with Device Independend output +(DVI\index{dvi file?{\tt dvi} file}) the +\ttt{epsf}\index{epsf.tex?\texttt{epsf.tex}} package provides the +``magic macro'' +$$ \verb|\epsfbox{|\descr{filename}\verb|}|% +\index{epsfbox?\texttt{\string\epsfbox}} $$ +for embedding graphics, e.g., \verb|\epsfbox{fig.1}|. + +Users of the pdf\TeX\ engine\index{pdfTeX?pdf\TeX!engine} should refer +to the standalone macros of the mptopdf\index{mptopdf} bundle, which can +be found at \url{http://context.aanhet.net/mptopdf.htm}. + +With the Lua\TeX\ engine\index{LuaTeX?Lua\TeX!engine}, embedding +external graphics works the same as with pdf\TeX. Additionally, +Lua\TeX\ users can inline MetaPost code directly into Plain \TeX\ +documents. Lua\TeX\ is able to process such MetaPost code snippets, +falling back to the built-in \emph{mplib}\index{mplib?\emph{mplib}} +library. Note, \emph{mplib} doesn't support +\verb|verbatimtex|\slash\verb|btex| \ldots\ \verb|etex| constructs, +currently. Here is an example of a MetaPost graphic inlined into a +Plain \TeX\ document. For more information, please refer to the +Lua\TeX~\cite[chap.~4.8]{luatex:manual} and +\ttindex{luamplib}~\cite{hagen:luamplib} documentation. + +$$\begin{verbatim} +\input luamplib.sty +\mplibcode +beginfig(1); + ... +endfig; +\endmplibcode +\bye +\end{verbatim} +$$ + +\paragraph{\LaTeX\ Format} +\label{latexformat} +\index{LaTeX?\LaTeX!format!importing MetaPost files} +\index{TeX?\TeX!engine} +\index{pdfTeX?pdf\TeX!engine} + +For users of the \LaTeX\ format and the traditional \TeX\ engine with +Device Independent output (DVI\index{dvi file?{\tt dvi} file}) the +well-known \ttindex{graphics} (or \ttindex{graphicx}) package aids in +external graphics inclusion. The package supports different engines, +guessing the correct output driver automatically, and can handle several +graphic formats. The ``magic macro'' is +$$ \verb|\includegraphics{|\descr{filename}\verb|}|% +\index{includegraphics?\texttt{\string\includegraphics}} $$ + +In DVI output driver mode the \ttt{graphics} package assumes all files +with an unknown file extension, such as \texttt{.1} etc., to be in the +EPS\index{EPS} format. It therefore handles MetaPost files with a +numeric default file extension correctly (see~\cite{reckdahl:epslatex} +for more information). + +When using the pdf\TeX\ engine with a built-in PDF output driver, the +situation is a bit different. Only files with file extension +\texttt{.mps}\index{mps file?{\tt mps} file}\index{files!mps?{\tt mps}} +are recognized as purified EPS\index{EPS!purified} and can be converted +to PDF\index{PDF} on-the-fly. The recommended procedure for embedding +MetaPost graphics into \LaTeX\ documents compiled with pdf\TeX\ is +therefore to change MetaPost's output file name extension via +\verb|outputtemplate|\index{outputtemplate?\texttt{outputtemplate}} (see +p.~\pageref{Doutputtemplate}). In the \LaTeX\ document include the +graphic files with full name, e.g., +$$\begin{verbatim} +\includegraphics{fig-1.mps} +\end{verbatim} +$$ + +Note, the latter approach works with the \ttindex{dvips} driver, too. +Even though, again, this time \ttt{.mps} is an unknown file extension, +triggering EPS file handling in a fall-back procedure. This property of +the \ttt{graphics} package, which comes in handy for MetaPost files, is +the reason many MetaPost source files start with the line +$$\begin{verbatim} +outputtemplate := "%j-%c.mps"; +\end{verbatim} +$$ + +With the Lua\TeX\ engine\index{LuaTeX?Lua\TeX!engine}, embedding +external graphics works the same as with pdf\TeX. Additionally, +Lua\TeX\ users can inline MetaPost code directly into La\TeX\ documents. +Lua\TeX\ is able to process such MetaPost code snippets, falling back to +the built-in \emph{mplib}\index{mplib?\emph{mplib}} library. Note, +\emph{mplib} doesn't support \verb|verbatimtex|\slash\verb|btex| \ldots\ +\verb|etex| constructs, currently. Here is an example of a MetaPost +graphic inlined into a \LaTeX\ document. For more information, please +refer to the Lua\TeX~\cite[chap.~4.8]{luatex:manual} and +\ttindex{luamplib}~\cite{hagen:luamplib} documentation. +$$\begin{verbatim} +\documentclass{article} +\usepackage{luamplib} +\begin{document} +\begin{mplibcode} +beginfig(1); + ... +endfig; +\end{mplibcode} +\end{document} +\end{verbatim} +$$ + +\paragraph{Con\TeX t Format} +\label{contextformat} +\index{ConTeXt?Con\TeX t!format!importing MetaPost files} + +In Con\TeX t\index{ConTeXt?Con\TeX t} graphics support is integrated in +the kernel, covering advanced features like shading, transparency, color +spaces or image inclusion. The ``magic macro'' for embedding external +graphics is +$$ \verb|\externalfigure[|\descr{filename}\verb|]|% +\index{externalfigure?\texttt{\string\externalfigure}} $$ +% +The macro can handle numbered files as well as files with the \ttt{mps} +suffix. + +Alternatively, Con\TeX t users can inline MetaPost code in the document +source, which allows for more natural interfacing with document +properties, font support, and automatic processing~\cite{hagen:metafun}. +Here is an example of a MetaPost graphic inlined into a Con\TeX t +document. +$$\begin{verbatim}[commandchars=|\[\]] +\starttext +\startuseMPgraphic{|tdescr[name]} + ... +\stopuseMPgraphic +\useMPgraphic{|tdescr[name]} +\stoptext +\end{verbatim} +$$ + +Con\TeX t MkIV, being based on the Lua\TeX\ engine, provides a much +tighter integration of MetaPost than older versions, since it can +fall-back to the built-in \emph{mplib}\index{mplib?\emph{mplib}} +library. + +\subsubsection{Troff} +\label{troffimport} +\index{troff!importing MetaPost files} + +It is also possible to include MetaPost output in a GNU +troff\index{troff} document. The procedure is similar to +Figure~\ref{fig:teximport}: the \ttindex{grops} output processor +includes PostScript files when they are requested via troff's +\ttt{\string\X}\index{X?\texttt{\string\X}} command. The +\ttt{-mpspic}\index{mpspic?\texttt{-mpspic}} macro package provides a +command \verb|.PSPIC|\index{PSPIC?\texttt{.PSPIC}}, which does just that +when including an encapsulated PostScript file in the source code. For +instance, the troff command +$$ \hbox{\verb|.PSPIC fig.1|} $$ +includes \ttt{fig.1}, using the natural height and width of the +image as given in the file's bounding box. + +\subsubsection{Web Applications} +\label{webimport} + +An SVG\index{svg file?{\tt svg} file}\index{files!svg?{\tt svg}} file +\texttt{fig.svg} can be easily embedded into +HTML\index{HTML}\index{files!HTML} documents with the following code +snippet: +$$\begin{verbatim} +

+ + +

+\end{verbatim} +\index{object tag?\texttt{object} tag|see{HTML, tags, \texttt{object}}} +\index{HTML!tags!object?\texttt{object}} +$$ +The code is similar for PNG\index{png file?{\tt png} + file}\index{files!png?{\tt png}} files: +$$\begin{verbatim} +

+ A picture. +

+\end{verbatim} +\index{img tag?\texttt{img} tag|see{HTML, tags, \texttt{img}}} +\index{HTML!tags!img?\texttt{img}} +$$ +The \texttt{width} and \texttt{height} attributes used above allow for +scaling a graphic to an arbitrary size. More information about HTML +tags and attributes can be found in an HTML reference. + +SVG and PNG files can also be imported by various interactive graphics +editing programs, for example GIMP\index{GIMP} or +Inkscape\index{Inkscape}. See Section~\ref{Dprologues} for information +on font handling in SVG graphics. + + +\section*{Acknowledgement} + +I would like to thank Don Knuth for making this work possible by +developing \MF\ and placing it in the public domain. I am also indebted +to him for helpful suggestions, particularly with regard to the +treatment of included \TeX\ material. + + +\appendix +\include{mpman-app-numbersystems} +\include{mpman-app-refman} +\include{mpman-app-legacy} + + +\bibliographystyle{plain} +\bibliography{mpman} + + +\printindex + + +\end{document} + +% Copyright 1990 - 1995 by AT&T Bell Laboratories. +% Updated 2006 by Taco Hoekwater, Karl Berry, and others. + +% Permission to use, copy, modify, and distribute this software +% and its documentation for any purpose and without fee is hereby +% granted, provided that the above copyright notice appear in all +% copies and that both that the copyright notice and this +% permission notice and warranty disclaimer appear in supporting +% documentation, and that the names of AT&T Bell Laboratories or +% any of its entities not be used in advertising or publicity +% pertaining to distribution of the software without specific, +% written prior permission. + +% AT&T disclaims all warranties with regard to this software, +% including all implied warranties of merchantability and fitness. +% In no event shall AT&T be liable for any special, indirect or +% consequential damages or any damages whatsoever resulting from +% loss of use, data or profits, whether in an action of contract, +% negligence or other tortious action, arising out of or in +% connection with the use or performance of this software. + +% In addition, John Hobby, the original author of MetaPost and this +% manual, makes the following requests: +% - I request that it remain clear that I am the author of +% "A User's Manual for MetaPost" and "Drawing Graphs with MetaPost". +% - I request to be consulted before significant changes are made. + +%%% Local Variables: +%%% mode: latex +%%% TeX-PDF-mode: t +%%% TeX-master: t +%%% End: diff --git a/systems/doc/metapost/source-manual/timepop.d b/systems/doc/metapost/source-manual/timepop.d new file mode 100644 index 0000000000..c8b2bae7a0 --- /dev/null +++ b/systems/doc/metapost/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 -- cgit v1.2.3